HTTP APIs

Authentication#

Three helpers. Each answers "who is this?" and leaves the policy to you. There are no closures, so keys live in your state and a short before hook passes them in:

gc struct App { jwt: zokor.JwtAuth, keys: zokor.ApiKeys }
struct Claims { sub: str, role: str, exp: int }

fn require_user(c: zokor.Ctx[App]) -> opt[http.Response] {
    let r: result[Claims, http.Response] = zokor.bearer_claims(c, c.state.jwt);
    guard let claims = r else let deny = err_of(r) { return some(deny); }
    c.set_local("user_id", claims.sub);
    return none;
}

JWTs, HS256 through dolphlabs/jwt:

• Configuration. jwt_auth_from(cfg) reads JWT_SECRETS

  (comma-separated, newest first, 32+ bytes each), JWT_AUDIENCE, JWT_ISSUER and JWT_LEEWAY (seconds of clock skew, default 30).

• Checks. bearer_claims checks the signature, algorithm and duplicate

  claims, then exp (required), nbf, and aud and iss when configured. Only then does it decode the payload into your own claims type.

• Failures. Every failure gets the same 401 with

  WWW-Authenticate: Bearer error="invalid_token". token_problem(token, auth, now) gives the reason for your logs.

• Signing and rotation. sign_token(claims, auth) signs with the

  newest secret. A token signed with an older listed secret still verifies, so rotation logs nobody out.

Basic auth:

• basic_credentials(c) returns the user and password, keeping a colon

  inside the password.

• basic_matches(creds, user, pass) compares SHA-256 digests in constant

  time, so neither content nor length leaks through timing.

• basic_denied(c, realm) asks the browser to log in.

API keys:

• API_KEYS=billing:key1,search:key2, 24+ bytes each, is read by

  api_keys_from(cfg).

• api_key_client(c, keys) reads X-Api-Key and returns the client's

  name, so a request can be traced to who sent it.

• Only SHA-256 digests are kept in memory. Every key is compared, in

  constant time.

Operator injection (MongoDB)#

MongoDB reads a key starting with $ as an operator. A login handler that passes the body to a query, with a body like {"user":"ada","password":{"$ne":""}}, matches any password. The guard works like express-mongo-sanitize and is opt-in:

r.mongo_sanitize(zokor.SanitizeMode.REJECT);   // or zokor.sanitize_from(cfg): MONGO_SANITIZE

• What it checks. Every key of a JSON body, at any depth and inside

  arrays, and every query-parameter name, decoded first so %24where is $where. A key starting with $ or containing a . is refused.

• REJECT answers 400 bad_request naming the key, for example

  body key 'password.$ne'. No before hook and no handler runs.

• STRIP removes the offending keys and carries on.
• What it leaves alone. Values are never touched, so "$5 off" is

  fine. A body that isn't JSON, or isn't valid JSON, is left for the handler to refuse.

• Cost. With the guard on, a JSON body is parsed once more.

SQL has no equivalent on purpose. A blacklist rejects O'Brien and still misses real attacks. The defence is parameterised queries, which the Postgres helpers use exclusively.

Cookies#

let theme = c.cookie("theme");                    // "" when not sent

let ck = zokor.new_cookie("theme", "dark");        // HttpOnly, Secure, SameSite=Lax, Path=/
ck.max_age = 86400 * 30;
return zokor.set_cookie(resp, ck) ?? resp;         // err names what is wrong

• Safe defaults. A new cookie is HttpOnly, Secure, SameSite=Lax

  and Path=/, with no Domain, so it's host-only.

• Checked before it's sent. set_cookie refuses:
  • a value with a space, quote, comma, ;, backslash or control byte,

    which could add attributes of its own

  • a bad name
  • a path or domain carrying ;
  • SameSite=None without Secure, which browsers drop
  • a __Host- or __Secure- cookie that breaks its prefix's rules
  • more than 4,096 bytes
• Reading. c.cookie(name) and c.cookies() skip malformed pairs the

  way browsers do, and the first of two same-named cookies wins.

• Deleting. clear_cookie(resp, name, path, domain) removes a cookie

  (Max-Age=0, and an Expires in 1970 for clients that read only that).

• Lifetime. max_age (seconds; -1, the default, is a session

  cookie) is what every browser uses. Set expires too, an instant from timez, for HTTP clients that only read Expires; when both are sent Max-Age wins:

  Copy

  ck.max_age = 3600;
  ck.expires = some(timez.now().add(timez.HOUR));   // Expires=<HTTP date>

Signed cookies carry an HMAC-SHA256 over their name and value, so a client can read them but not change them, or move one to another name:

let keys = zokor.cookie_keys_from(cfg);            // COOKIE_KEYS=newest,older
let ck = zokor.signed_cookie("uid", "42", keys) ?? zokor.new_cookie("uid", "");
let uid = zokor.signed_value(c, "uid", keys) ?? "";  // none when forged

The first key signs and every listed key verifies. To rotate, put the new key first and keep the old one until the cookies it signed have expired; nobody is logged out. Keys must be at least 32 bytes. Signatures are compared in constant time. Signed is not encrypted: never put a secret in a cookie.

Conditional requests#

A client that already holds the current version gets 304 Not Modified and no body; a write made against a version that is no longer current gets 412 instead of overwriting someone else's change (RFC 9110 §13):

fn get_doc(c: zokor.Ctx[App]) -> http.Response {
    let doc = load(c);                                 // has .version, .updated_at
    let tag = zokor.etag_of(to_bytes(to_str(doc.version)));
    if let stop = zokor.preconditions(c, tag, some(doc.updated_at)) {
        return stop;                                   // 304, or 412 on a write
    }
    let resp = zokor.ok_json(json.encode(doc));
    return zokor.with_validators(resp, tag, some(doc.updated_at));
}

• One call for reads and writes. preconditions evaluates If-Match,

  If-Unmodified-Since, If-None-Match and If-Modified-Since in the order RFC 9110 §13.2.2 sets. A PUT that sends back the ETag it read in If-Match updates only if nobody changed the resource since: optimistic concurrency, no lock. Pass "" as the tag for a resource that does not exist yet, and If-None-Match: * means "create, never replace".

• Comparisons as the RFC has them. If-Match compares strongly, so a

  W/ tag never matches; If-None-Match compares weakly. Tag lists, *, and all three HTTP date forms are read; a date that is not a valid HTTP date is ignored, and a malformed tag never matches.

• r.etags(), opt in: every 200 answer to a GET or HEAD gets an

  ETag hashed from its body, and a matching If-None-Match gets a 304 that keeps the other headers (Cache-Control, Vary, …). A response with its own ETag is left alone. It hashes every such body, measured in process (bench/conditional): about 1.5 µs a request at 128 bytes, 2.7 µs at 1 KB and 20 µs at 16 KB. With nothing turned on, the request path costs what it did. For a large body, a version you already have (preconditions) is far cheaper than hashing the bytes.

Security headers#

On by default, on every response: dynamic, static, errors, and the 500 after a panic.

content-security-policy: default-src 'none'; frame-ancestors 'none'
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
referrer-policy: no-referrer

• CSP. An API answers JSON, so its CSP allows nothing: a response

  opened in a browser runs no script and can't be framed.

• HSTS. Browsers ignore HSTS on plain HTTP, so it's harmless behind a

  proxy that ends TLS, and right when the proxy doesn't.

• COOP and CORP are opt-in: same-origin CORP breaks legitimate

  cross-origin embeds.

• Handlers win. A handler that sets one of these headers with

  with_header keeps its own value.

r.security_headers(zokor.security_from(cfg)) applies the settings, and zokor.no_security_headers() turns them off. Bad values are refused with the fix: an unknown frame option or referrer policy, preload without a year and subdomains, or a CSP containing a line break. Static routes are pre-rendered with the headers, so they cost nothing per request there. On a dynamic response, the five lines add about 10 allocations.

CORS#

Off by default. One call turns it on:

r.cors(zokor.cors_from(cfg));   // CORS_ORIGINS=https://app.example.com,https://*.example.org

or r.cors(zokor.cors_policy(["https://app.example.com"])) from code.

The router applies it, so it isn't one more before:

• Preflights. A preflight to a path that exists gets a 204 with the

  allowed methods and headers before routing. Neither an auth hook nor a route's own OPTIONS handler can turn it away, and browsers send preflights without credentials.

• Every response. Any answer to an allowed origin carries its headers:

  the 404, the 422, a before's 401 and the 500 after a panic. Without that, the page sees a CORS error instead of the real one.

• Vary: Origin. It's sent whenever the answer depends on the origin,

  so a shared cache never hands one origin's answer to another.

• Other origins. An origin that isn't allowed gets no CORS headers, and

  the browser withholds the response from the page.

A policy is checked before use, and every problem names the fix:

• an origin with a path or trailing slash, which an Origin header never has
• a missing scheme
• upper case
• a wildcard anywhere but a leading *.
• * together with credentials, which browsers refuse

https://*.example.com matches api.example.com and a.b.example.com, but never example.com or evilexample.com. CORS protects users' browsers, not your server: it is no substitute for authentication.

Health and readiness#

r.health();                      // GET /healthz and GET /readyz
r.ready_check("db", db_ready);   // what /readyz waits on

fn db_ready(s: App) -> result[int, str] {
    let q = s.db.query("select 1");
    guard let _rows = q else let e = err_of(q) {
        return err(to_str(e));
    }
    return ok(0);
}

/healthz is liveness: 200 {"status":"ok"} whenever the process is serving, and it never touches a dependency, so a database outage cannot make the orchestrator restart every replica. /readyz runs every check at once and answers 200 {"status":"ok","checks":{"db":"ok"}}, or 503 with "failing" or "timeout" against each check that did not pass. It also answers 503 shutting_down once SIGTERM arrives, so a load balancer stops sending traffic before the drain.

• Bounded. A probe waits at most 0.9s (r.ready_timeout(ns)), inside

  Kubernetes' default 1s probe timeout.

• Isolated. A check runs in its own task, so a panic fails that check,

  not the probe. A check still running from an earlier probe is joined, not started again, so a hung database costs one task, not one per probe.

• No leaks. The body names checks, never errors: a driver's message

  carries hosts and user names. The reason goes to the server's log as a WARN [Health] line, once each time a check starts failing, changes reason or recovers.

• Out of the way. The router answers these paths only when no route

  claims them, so your own /healthz wins. No before runs on them, since an auth hook would fail the probes. r.health_at(live, ready) mounts them elsewhere.

Static files#

let mr = zokor.files_at("/assets", "./public");     // err if not a directory
guard let assets = mr else let e = err_of(mr) { println(e); exit(1); }
assets.max_age = 31536000;                          // hashed names: a year
assets.immutable = true;
r.files(assets);

A GET or HEAD under the prefix that no route claims is a file from the directory:

• Traversal-safe. An encoded separator (%2f, %5c), a .., . or

  dot-file segment (.env, .git), a backslash or a NUL is a 404, and the file's real path, every symlink resolved, must be inside the directory's real path or it is a 404 too: a link cannot lead out.

• Index files. A directory answers index.html (mount.index).
• Validators. ETag from size and modification time, Last-Modified,

  and 304/412 through preconditions.

• Ranges. One Range: bytes= range is a 206 with Content-Range

  (If-Range honoured); one past the end a 416; several ranges get the whole file, as RFC 9110 allows.

• Headers. Content-Type by extension (unknown types are

  application/octet-stream, which nosniff keeps from being rendered), Cache-Control from max_age (no-cache by default: revalidate every time, cheap with the validators) and Accept-Ranges.

Files are read into memory, up to max_size (64 MB), and the read blocks a worker: serve an app's own assets this way, and put a CDN in front of large or busy ones.

Content negotiation and redirects#

Compile the representations a handler can serve at startup:

let made = zokor.new_negotiator(["application/json", "text/html"], zokor.accept_limits());
guard let formats = made else let e = err_of(made) { println(e); exit(1); }
// Keep formats in the router's state. In the handler:
let picked = zokor.negotiate(c, c.state.formats);
guard let media = picked else let bad = err_of(picked) { return bad; }
// Render the selected representation, then return it with media as Content-Type.

negotiate combines repeated Accept lines, preserving quoted parameters. It honors q weights, wildcards and parameter specificity: a specific q=0 excludes that representation even when a wildcard permits others. Equal preferences use specificity, client range order, then startup offer order. An absent header selects the first offer; an empty header or no acceptable offer produces the registered not_acceptable 406. Malformed or over-limit headers produce bad_request 400 with an Accept field. All these responses carry Vary: Accept, alongside compression and CORS fields. Negotiator.choose provides selection without a request context.

accept_limits() defaults to 8 KB of combined header values, 64 list members, 32 parameters per range (including q), 32 offers and 1 KB per offer. Set these before constructing the negotiator. Configure once and treat its compiled vectors as immutable.

let response = zokor.redirect_to("/orders/123"); // checked 303, POST/redirect/GET
let rules = zokor.redirect_rules();             // relative references, 8 KB limit
rules.allow_external = true;
let moved = zokor.redirect_checked(307, "https://app.example.com/orders", rules);

Checked helpers return a result; they validate 301/302/303/307/308 and preserve the destination with an empty body. Relative paths, queries and fragments are accepted. External HTTP(S) URLs require explicit opt-in; network-path references (//host), credentials, raw whitespace, controls, backslashes and malformed percent escapes are refused. Other bytes must be percent-encoded. Errors name the field without echoing the destination. For variable external destinations, the application chooses its permitted hosts. The existing redirect(status, location) remains the raw constructor for destinations the application already controls.

Compression#

r.compress(zokor.compression());       // min_size 1 KB, level 1, text-like types

A response is gzipped when the client's Accept-Encoding allows it (q values honoured: gzip;q=0 refuses it), it is a 2xx other than 204/206 to a method other than HEAD, its body is at least min_size, its type is text, JSON, JavaScript, XML, SVG or form data (or ends in +json/+xml), and it has no Content-Encoding of its own. Every response that could have been gzipped carries Vary: Accept-Encoding; a strong ETag becomes weak. Level 1 is the default: on API JSON it keeps nearly all of level 5's saving (14 KB: 36 µs to 10% of the size, against 74 µs) for half the CPU. Static routes are sent as rendered.

BREACH. Over TLS, compressing a response that holds a secret next to input an attacker controls lets them recover the secret from sizes. Keep pages that mix the two (a CSRF token and reflected search terms) on a router without compression.

Idempotency keys#

A client that retries a POST after a timeout must not charge twice. With Idempotency-Key (the IETF draft), it gets the first answer instead:

let store = zokor.idempotency_redis(redis_pool);   // or idempotency_in_memory()
store.scope_local = "user_id";                       // set by your auth `before`
r.idempotency(store);

• Runs once. A POST or PATCH with the header runs; its answer is kept

  for 24 hours (store.ttl). The same request again gets that answer, with Idempotent-Replayed: true, and the handler does not run.

• Refuses misuse. The key again while the first is still running:

  409. The key with a different method, path or body: 422. A key that is not 1–255 printable characters: 400. store.required = true makes the header mandatory on POST and PATCH.

• Scoped. Keys are per method, route and caller (scope_local names

  the local your authentication sets), so one user cannot replay another's answer.

• Only final answers. A 5xx, 408 or 429 is not kept: the next retry

  runs again. Neither is a body over store.max_body (1 MB). A handler that panics leaves its key "running" for store.lock_ttl (30 s).

• Shared. The Redis store claims a key with SET NX PX, so instances

  behind a balancer agree; if Redis cannot be reached the request is refused with 503 rather than risk running twice. The in-memory store is for a single instance.

Pagination#

Offset pages (?limit=20&offset=40) and keyset pages (?limit=20&cursor=…) answer in the same envelope, so a client reads every list the same way:

fn list_orders(c: zokor.Ctx[App]) -> http.Response {
    let pr = zokor.page_of(c, 20, 100);            // default 20, at most 100
    guard let p = pr else let bad = err_of(pr) { return bad; }   // 422, named
    let after = zokor.cursor_parts(p);             // [] on the first page
    // WHERE (created, id) < ($1, $2) ORDER BY created DESC, id DESC LIMIT p.fetch()
    let rows = load_orders(c, after, p.fetch());
    return zokor.cursor_page(c, p, rows, order_key);
}

fn order_key(o: Order) -> [str] { return [o.created, to_str(o.id)]; }

{"data":[...],"page":{"limit":20,"cursor":"WyIyMDI2...","next":"WyIyMDI2...","total":null}}

• One row past the page. p.fetch() is limit + 1: an extra row

  means there is a next page, without a COUNT(*). offset_page takes an optional total when the handler has one.

• Links. A Link header (RFC 8288) carries rel="next" (and

  rel="prev" for offset pages), keeping the request's other query parameters.

• Checked. limit must be 1 to the maximum; offset 0 to 1,000,000

  (deeper: use a cursor); not both offset and cursor; a cursor this API did not issue is refused. Each problem is a named field in a 422.

• Keyset is the one to use on big tables: the next page is an index

  range, and rows inserted between requests are neither skipped nor repeated. A cursor is opaque base64url of the last row's sort key; a client can forge one, but only to read another position of a list it may read anyway, so authorise the list, and never put a secret in a key.

JSON#

slang already does the part Go does badly: you decode into a struct, a missing field is an error rather than a silent zero, and the message names the field. No tags, no interface{}, no omitempty guessing. zokor adds the four things that are still missing.

A DTO, decoded and reported. The wire is camelCase, your struct is snake_case, and there are no struct tags — so rewrite the keys:

gc struct CreateOrg { name: str, plan: str, seats: i32, website: opt[str] }

let r: result[CreateOrg, str] = json.decode(zokor.snake_keys(c.body_str()));
guard let dto = r else let e = err_of(r) {
    return zokor.decode_failed(c.state.errors, e, c.request_id);
}

decode_failed turns slang's own message into the standard envelope with the field named, so a client gets the same shape for a bad type as for a bad value:

{"error":{"code":"validation_failed","status":422,
          "fields":[{"field":"seats","reason":"expected a number, got a string"}]}}
{"error":{"code":"validation_failed","status":422,
          "fields":[{"field":"plan","reason":"is required"}]}}

Values, checked all at once. Decoding says a field is a string; it does not say it is an email between 3 and 40 characters. A checker collects every problem, because a client fixing one field per request is a client making five requests:

let v = zokor.checker();
let name  = v.req_str(body, "name", 1, 80);
let email = v.req_email(body, "email");
let role  = v.req_one_of(body, "role", ["admin", "member"]);
let age    = v.opt_int(body, "age", 0, 150, 0);
if v.failed() {
    return zokor.respond_fields(c.state.errors, "validation_failed",
                                v.fields, c.request_id);
}

req_str, req_int, req_bool, req_email, req_url, req_uuid, req_one_of, req_strs, req_obj, opt_str, opt_int, plus note for a rule of your own and under("address", inner) to report a nested check as address.city.

A shape nobody declared — a webhook, a passthrough, somebody else's field. A missing key gives Null rather than an error, so a chain never has to be guarded at every step:

guard let body = c.json_body() else { ... }

body.get("type").str_or("unknown")
body.path("data.customer.address.city").str_or("nowhere")
body.path("data.items.0.sku").str_or("none")
body.path("data.items").size()
body.has_key("note")          // present, even if null: PATCH semantics

Building a response, instead of concatenating strings and getting the quoting wrong:

zokor.jobj()
    .set_str("id", id)
    .set_int("seats", n)
    .set_opt_str("website", dto.website)     // absent when none
    .set("tags", zokor.jarr().add_str("a").add_str("b"))
    .render()

Numbers keep the text they arrived as, so a 64-bit id survives a round trip; \uXXXX escapes and surrogate pairs decode; and the parser refuses what JSON refuses — a leading zero, a lone surrogate, an unescaped control character, nesting past 64 deep.

Uploads#

multipart/form-data is a format where being lax is a vulnerability: the client picks the delimiter, names the parts and supplies the filenames. A handler says what it accepts; anything else comes back as a registered failure and never reaches it.

fn upload_avatar(c: zokor.Ctx[App]) -> http.Response {
    let rules = zokor.with_max_file_bytes(
        zokor.uploads_allowing(["image/png", "image/jpeg"]), 1048576);

    let r = c.upload(rules);          // POST/PUT/PATCH only
    guard let form = r else let e = err_of(r) {
        return zokor.respond_with(c.state.errors, e.code, e.detail, c.request_id);
    }
    guard let avatar = zokor.file(form, "avatar") else {
        return zokor.respond(c.state.errors, "validation_failed", c.request_id);
    }

    zokor.value(form, "title");        // the non-file fields
    zokor.files_for(form, "docs");     // <input multiple>
    avatar.filename;                   // safe to use as one path segment
    avatar.raw_filename;               // what the client actually sent
    return zokor.ok_json("{\"bytes\":" + to_str(len(avatar.data)) + "}");
}

Filenames are made safe: everything before the last / or \ is dropped, control characters go, a leading dot goes, and a name that is empty after that becomes upload. ../../etc/passwd arrives as passwd. The name the client sent is kept as raw_filename for logs.

Limits are the caller's, checked while the body is walked: parts, files, bytes per file, bytes per field, total bytes, header size, filename length. Over a size limit is a 413; a body that is not well-formed multipart is a 400; a type or extension that is not allowed is a 415.

Refused rather than guessed at: a Content-Type that is not multipart or has no boundary, a boundary that is empty or over 70 characters, a body that stops before its closing delimiter, a part with no Content-Disposition or no name, unterminated or oversized part headers, and a Content-Transfer-Encoding the web does not use. A file sent with no Content-Type is refused unless you turn require_content_type off.

A body arrives whole, so this does not stream: set max_total_bytes for what a service can afford to hold.

Rate limits and bearer tokens#

Both are values in your state, shared by every request and safe to use from concurrent handlers (each holds a mutex).

gc struct App {
    errors: zokor.Registry,
    limiter: zokor.RateLimiter,
    tokens: zokor.TokenStore,
}

// 100 requests per client per minute; tokens last a day. Durations
// are int nanoseconds, written out: `60 * 1000000000` overflows in
// slang today (a product of two literals is computed in 32 bits).
let app = App {
    errors: zokor.new_registry(),
    limiter: zokor.new_rate_limiter(100, 60000000000),
    tokens: zokor.new_token_store(86400000000000)
};

fn limit(c: zokor.Ctx[App]) -> opt[http.Response] {
    return zokor.rate_limit(c, c.state.limiter, c.header("x-api-key"));
}

fn auth(c: zokor.Ctx[App]) -> opt[http.Response] {
    guard let user = zokor.bearer_subject(c, c.state.tokens) else {
        return some(zokor.respond(c.state.errors, "unauthorized", c.request_id));
    }
    c.set_local("user", user);
    return none;
}

• Refusals. rate_limit answers a refused request with the

  registered rate_limited code (429, through your renderer if you set one) and Retry-After in whole seconds. Refused requests don't count against the window.

• Headers on every answer. Allowed or refused, a response carries

  RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the next request frees up), so well-behaved clients can pace themselves.

• Keys. The key is yours to choose: an API key, a user, an address.

  An empty key shares one "anonymous" budget. rate_limit_client(c, l) keys on the client's address, resolved through TRUSTED_PROXIES, so a client can't escape its limit or spend someone else's by sending a header.

• Concurrency. The limiter is split into 16 shards, each with its own

  lock, so tasks checking different clients don't wait on each other. With 8 tasks: 2.0 µs a check, against 17.3 µs with a single lock.

• Testing. take_at(key, now) and check_at(key, now) take the

  clock as a parameter, so tests need no sleeps.

A before hook that lets a request through can still add headers to its answer with c.add_header(name, value): the limiter uses it, and so can a hook that refreshes a cookie.

TokenStore.issue(subject) returns a 64-hex-character token from crypto.rand; lookup(token) gives the subject back (expired tokens are dropped), revoke(token) logs one session out and revoke_subject(subject) all of them. Tokens live in memory: they do not survive a restart and are not shared between instances.