tur/httpd

(httpd-register-tls-impl [wrap-fd :int handshake :int read-fn :int write-fn :int shutdown :int free-fn :int] :nil)

install TLS function pointers into the H5 hook table.

Called once by user code after importing tur/tls (the spice provides a one-liner helper that captures these pointers and forwards them here). Without this call, httpd-new-tls fails cleanly because the function pointer table is all zeros.

Since: Phase H5

(httpd-set-max-body! [n :int] :int)

cap the request body size the server will read.

A request whose Content-Length exceeds the cap is answered 413 and the connection closed before any of the body is read or allocated. The default is 8 MiB. This is the server-wide ceiling; mw-body-size applies a lower per-route limit on top of it.

(httpd-set-max-body! (* 64 1048576))   ; accept uploads up to 64 MiB

Since: security-audit-plan WP4 (M-4)

(httpd-set-bind-any! [on :bool] :bool)

listen on every interface instead of loopback.

Servers bind 127.0.0.1 by default, so a program that starts httpd is not reachable from the network until it says so. Call this (or set the environment variable TUR_HTTPD_BIND_ANY=1) before httpd-new / httpd-new-pool / httpd-new-async to bind 0.0.0.0. TUR_BIND_LOOPBACK, which the test harnesses export, still forces loopback.

(httpd-set-bind-any! true)
(httpd-new 8080 handler)   ; reachable on every interface

Since: security-audit-plan WP4 (M-4)

(httpd-set-bind-addr! [addr :cstr] :bool)

listen on one address, IPv4 or IPv6.

httpd-set-bind-any! chooses between loopback and every interface; this names the interface -- a numeric address like "192.168.1.5", "::1" or "::" (every IPv6 interface). It applies to the servers created after it (httpd-new, httpd-new-pool, httpd-new-async, ...) and wins over httpd-set-bind-any!. "" clears it, back to that default. An address that does not parse is refused and the setting is left as it was. TUR_BIND_LOOPBACK, which the test harnesses export, still forces loopback -- of the address's own family (127.0.0.1 or ::1).

(httpd-set-bind-addr! "::1")
(httpd-new 8080 handler)   ; IPv6 loopback only

Since: 2026-10-03 (security-audit-plan WP4 residual)

(httpd-bind-addr :int)

internal: the IPv4 address (host order) to listen on.

(httpd-listen-socket [port :int] :int)

internal: a bound, listening, non-blocking socket for port on the configured address (httpd-set-bind-addr!, else loopback or every interface per httpd-bind-addr), or -1. Shared by the constructors.

(httpd-status-text [status :int] :cstr)

internal: the reason phrase for a status code.

(httpd-error-response [status :int buf :ptr<void> cap :int] :int)

internal: a complete close-the-connection response.

Writes "HTTP/1.1 <status> <text>" with an empty body and Connection: close into buf (at most cap bytes) and returns its length.

(httpd-parse-head [c :ptr<void> buf :ptr<void> total :int out :ptr<void>] :int)

internal: parse a request head that is already in memory.

buf holds total bytes (NUL-terminated) that include the whole header block. Fills the connection's method / path / version / req_headers and client_keep_alive, stores the validated Content-Length through out (an int64_t*), and returns the header block's length in bytes. A request the server must refuse returns the negated status to answer it with:

-400  malformed, negative or conflicting Content-Length, or both
      Content-Length and Transfer-Encoding (the request-smuggling shape),
      or a method / version too long for its field
-413  Content-Length above the body cap (httpd-server-set-max-body! for
      this server, else httpd-set-max-body!'s)
-414  a request target too long for the path field
-501  Transfer-Encoding (chunked bodies are not implemented, and reading
      the chunks as the next request would desync the connection)

Pure over its input: no socket, which is what the fuzz target relies on.

(httpd-resp-head [c :ptr<void> is11 :int out :ptr<void>] :ptr<void>)

internal: build the response status line + header block.

Returns a malloc'd buffer (caller frees) holding everything up to and including the blank line, and stores its length through out (an int64_t*); NULL on allocation failure. A user-set Content-Length is dropped (the server owns the byte count), and so is any header whose name or value would break the framing -- a CR or LF in either (response splitting when a handler echoes request data into a header), or a name with a colon or blank in it.

(httpd-resp-finalize [c :ptr<void>] :nil)

internal: last word on the status before the head is built.

A 101 Switching Protocols is only honest on a connection that is really being handed off. One set without httpd-conn-upgrade! (a handler bug) is answered 500, and one whose upgrade the server refused (the async server, which cannot hand off a connection yet) is answered 501 -- in both cases with an explanatory body and the connection closed, so the client never believes it upgraded.

A 1xx, 204 or 304 response has no body (RFC 9110), so one a handler set anyway -- a middleware that ran after the status was decided, say -- is dropped here rather than written as bytes the client would read as the start of the next response.

(httpd-conn-release [c :ptr<void>] :nil)

internal: free everything a request attached to conn.

The body, the response body, both header lists, the cached JSON body, the multipart parts, the attribute list, the owned accessor strings and an upgrade callback that never ran. Leaves conn reusable (every freed field is reset).

(httpd-handle [fd :int handler :int tls :int max-body :int read-ms :int] :nil)

internal: serve one or more HTTP requests on fd, then close fd. Loops while the client keeps the connection alive.

HTTP/1.1 keep-alive semantics:

- HTTP/1.1: connection kept alive unless Connection: close.
- HTTP/1.0: connection closed unless Connection: keep-alive.
- Each request head must arrive whole within the read timeout
  (`read-ms`, else httpd-set-read-timeout!'s, 5 s by default); that
  also bounds how long an idle keep-alive connection is held.  A head
  that is still incomplete at the deadline is answered 408, one larger
  than 256 KiB is answered 431, and an idle connection is just closed.
- Bytes a client pipelined behind one request are kept for the next.

When tls is non-zero it is an opaque TLS connection handle obtained from the spice's tls-wrap-fd + tls-handshake; reads and writes are routed through the registered TLS ops instead of recv/send.

A handler that called httpd-conn-upgrade! gets its response written and then the connection handed to its callback; one that called httpd-conn-detach! has taken the connection already. Either way this function neither closes the fd nor releases the TLS state afterwards.

max-body is the server's own body cap (-1: httpd-set-max-body!'s).

Since: Phase H1 (TLS path: Phase H5; upgrade, deadline: tourist-on-stdlib-httpd H1)

(httpd-worker [arg :ptr<void>] :ptr<void>)

internal: worker thread function.

Pops fds from the shared queue and processes them sequentially via httpd-handle. Exits when the queue is closed and drained.

Since: Phase H3

(httpd-accept-cb [env :ptr<void> id :int events :int user :int] :nil)

internal reactor READ callback for the listen fd.

Drains the listen queue, pushing each accepted fd onto the shared worker queue and signalling one waiting worker. env[1] is the HttpdBlock pointer (synthetic fat closure built in httpd-new).

Since: Phase H2

(httpd-new-pool [port :int workers :int ^fat handler :(fn [ptr<void>] nil)])

create an httpd instance with a configurable worker count.

At most 512 accepted connections wait for a free worker; past that a connection is answered 503 and closed. httpd-new-pool-with-limit sets another cap.

Since: Phase H3

(httpd-new-pool-with-limit [port :int workers :int ^fat handler :(fn [ptr<void>] nil) max-pending :int])

httpd-new-pool with a pending-connection cap.

Each worker serves one connection at a time; accepted connections wait in a queue for a free worker, each holding a descriptor. When max-pending connections are already waiting, a new one is answered 503 Service Unavailable and closed instead of queued.

(let [h (httpd-new-pool-with-limit 0 4 handler 64)]
  (httpd-run h)
  (httpd-free h))

Since: 2026-10-03 (security-audit-plan WP4 residual)

(httpd-new [port :int ^fat handler :(fn [ptr<void>] nil)])

create a new httpd instance with the default worker pool size (4).

(let [h (httpd-new 0 (fn [conn :ptr<void>] :nil
                       (httpd-resp-status! conn 200)
                       (httpd-resp-body! conn "OK")))]
  (httpd-run h)
  (httpd-free h))

Since: Phase H1

(httpd-new-tls [port :int workers :int ^fat handler :(fn [ptr<void>] nil) ctx :int])

create an httpd instance with TLS termination.

The accept loop is identical to the plaintext path; each accepted fd is wrapped with tls-wrap-fd + driven through tls-handshake on the worker that pops it. Reads and writes inside httpd-handle then go through the registered TLS ops instead of recv/send.

Prerequisites:

* The tur/tls spice must be linked (otherwise the function-pointer
  table is all zeros and this constructor returns NULL).
* The user must call (tls-httpd-init) once -- exported by the
  spice's tls/httpd module -- before calling httpd-new-tls.

(tls-httpd-init)
(let [ctx (tls-ctx-new)]
  (tls-ctx-load-cert-pem ctx "cert.pem")
  (tls-ctx-load-key-pem  ctx "key.pem")
  (let [h (httpd-new-tls 8443 4 my-handler ctx)]
    (httpd-run h)
    (httpd-free h)
    (tls-ctx-free ctx)))

Since: Phase H5

(httpd-port [h :ptr<void>] :int)

return the port the server is listening on.

Useful when httpd-new was called with port 0 (kernel-assigned).

Since: Phase H1

(httpd-run [h :ptr<void>])

run the listener reactor until httpd-stop is called.

Since: Phase H1

(httpd-stop [h :ptr<void>])

signal the listener to stop accepting new connections.

Thread-safe. Stops the listener reactor and closes the shared queue so workers exit when drained.

Since: Phase H1

(httpd-free [h :ptr<void>] :nil)

free all resources after httpd-run returns.

Joins the worker threads, removes the reactor source, frees the reactor and synthetic accept closure, closes the listen socket, drains and frees the shared queue, and frees the HttpdBlock.

Since: Phase H1

(httpd-set-read-timeout! [ms :int] :int)

set how long the server waits on a client.

A request head must arrive whole within this time (else 408), each read of a request body may wait this long, an idle keep-alive connection is closed after it, and on a TLS server it bounds the handshake. The default is 5000 ms. This is the process-wide value; a pool server can carry its own with httpd-server-set-read-timeout!. The async server uses it for every park on a client read or write.

(httpd-set-read-timeout! 30000)   ; slow clients get 30 s

Since: tourist-on-stdlib-httpd H1

(httpd-server-set-read-timeout! [h :ptr<void> ms :int] :nil)

give one pool server its own read timeout.

Overrides httpd-set-read-timeout! for the server h (from httpd-new, httpd-new-pool, httpd-new-pool-with-limit or httpd-new-tls), so two servers in one process can differ. Call it before httpd-run.

(httpd-server-set-read-timeout! h 500)

Since: tourist-on-stdlib-httpd H1

(httpd-server-set-max-body! [h :ptr<void> n :int] :nil)

give one pool server its own body cap.

Overrides httpd-set-max-body! for the server h: a request whose Content-Length exceeds it is answered 413 before any of the body is read. Call it before httpd-run.

(httpd-server-set-max-body! h 1048576)   ; 1 MiB for this server

Since: tourist-on-stdlib-httpd H1

(httpd-linger-drain [fd :int] :nil)

internal: half-close fd and read what the peer is still sending, briefly, so the close that follows does not reset the connection over unread data (a reset can discard the error response the client has not read yet). Bounded to 256 KiB and 500 ms.

(httpd-conn-fd [conn :ptr<void>] :int)

the client socket behind a request.

(httpd-conn-fd c)   ; => 7

Since: tourist-on-stdlib-httpd H1

(httpd-conn-tls [conn :ptr<void>] :ptr<void>)

the TLS state behind a request, or NULL on plaintext.

The handle the registered TLS implementation's wrap op returned for this connection (with tls/httpd from the tls spice: a tls_conn_t*).

(httpd-conn-tls c)   ; => NULL on a plaintext connection

Since: tourist-on-stdlib-httpd H1

(httpd-conn-read [conn :ptr<void> buf :ptr<void> len :int] :int)

read up to len raw bytes from the connection.

Goes through the registered TLS ops on a TLS connection, recv(2) otherwise. Meant for a connection that has been handed off; during an ordinary request the server has already read the request.

(httpd-conn-read c buf 4096)

Since: tourist-on-stdlib-httpd H1

(httpd-conn-write [conn :ptr<void> buf :ptr<void> len :int] :int)

write all len bytes to the connection.

Loops over short writes (a TLS record carries at most 16 KiB). Goes through the registered TLS ops on a TLS connection, send(2) otherwise.

(httpd-conn-write c frame frame-len)

Since: tourist-on-stdlib-httpd H1

(httpd-conn-clear-timeout [fd :int] :nil)

internal: drop the server's SO_RCVTIMEO from a socket it is handing to someone else.

(httpd-set-rcvtimeo [fd :int ms :int] :nil)

internal: set a socket's receive timeout to ms milliseconds (0 = none). POSIX takes a struct timeval; winsock takes a DWORD of milliseconds, and reads a timeval's first word as one (5 s became 5 ms).

(httpd-upgrade-refuse [c :ptr<void>] :nil)

internal: the async server cannot hand a connection off yet. Marks the conn (httpd-resp-finalize answers a 101 with 501) and says why on stderr, once per process.

(httpd-conn-upgrade! [conn :ptr<void> ^fat on-upgrade :(fn [ptr<void>] nil)] :bool)

hand the connection to on-upgrade after this response.

Call from a handler, after setting the response that accepts the upgrade (for a WebSocket: status 101 plus Upgrade, Connection and Sec-WebSocket-Accept headers). When the handler returns the server writes that response -- without a Content-Length or a body -- and then, on the same worker thread, calls on-upgrade with the conn. The request accessors still work inside the callback. From then on the callback owns the socket and its TLS state: the server neither reads another request from it nor closes it. Release them with httpd-conn-close! (or, for a transport kept past the callback, with the TLS spice's own shutdown/free and close(2)).

The callback blocks its worker for as long as it runs. If the response cannot be written the callback is not called and the connection is closed as usual. Only pool servers can hand a connection off; on the async server this returns false (see the section notes).

(httpd-resp-status! c 101)
(httpd-resp-header! c "Upgrade" "websocket")
(httpd-resp-header! c "Sec-WebSocket-Accept" accept)
(httpd-conn-upgrade! c (fn [c2 : ptr<void>] : nil
                         (run-session c2)
                         (httpd-conn-close! c2)))

Since: tourist-on-stdlib-httpd H1

(httpd-conn-detach! [conn :ptr<void>] :bool)

take the connection over, effective now.

For a handler that writes its own response straight to the transport (httpd-conn-fd / httpd-conn-tls, or httpd-conn-write) and keeps using the connection. When the handler returns the server writes nothing, reads nothing more and closes nothing: the fd and its TLS state belong to the caller, who must release them (httpd-conn-close!). The socket loses the server's read timeout at once.

(when (httpd-conn-detach! c)
  (httpd-conn-write c reply reply-len)
  (httpd-conn-close! c))

Since: tourist-on-stdlib-httpd H1

(httpd-conn-upgraded? [conn :ptr<void>] :bool)

has this connection been (or will it be) handed off?

True after httpd-conn-upgrade! or httpd-conn-detach! succeeded.

(when (httpd-conn-upgraded? c) (println "hijacked"))

Since: tourist-on-stdlib-httpd H1

(httpd-conn-close! [conn :ptr<void>] :bool)

release a connection that has been handed off.

Sends the TLS close_notify and frees the TLS state (when there is one) and closes the socket. Only acts on a conn the caller owns -- inside an httpd-conn-upgrade! callback, or after httpd-conn-detach! -- because during an ordinary request the server owns the descriptor and closing it under the server is a double close. Idempotent.

(httpd-conn-close! c)

Since: tourist-on-stdlib-httpd H1

(httpd-req-method [conn :ptr<void>] :cstr)

return the HTTP method from the parsed request.

Since: Phase H1

(httpd-req-path [conn :ptr<void>] :cstr)

return the request-target path from the parsed request.

Since: Phase H1

(httpd-req-version [conn :ptr<void>] :cstr)

return the HTTP version from the parsed request line.

Since: Phase H4

(httpd-req-body [conn :ptr<void>] :cstr)

return the request body (NUL-terminated copy).

Returns the body bytes read after the headers, sized by the Content-Length request header. Returns an empty string when there was no Content-Length or it was zero.

Since: Phase H4

(httpd-req-body-len [conn :ptr<void>] :int)

return the request body length in bytes.

Since: Phase H4

(httpd-resp-status-get [conn :ptr<void>] :int)

return the currently-set response status code.

Returns 0 if no status has been set yet (the default applied during response writing is 200 OK).

Since: Phase H6

(httpd-resp-status! [conn :ptr<void> status :int] :nil)

set the HTTP response status code.

Since: Phase H1

(httpd-resp-close! [conn :ptr<void>] :nil)

close the connection after this response.

The response goes out with Connection: close and the server closes the connection instead of waiting for another keep-alive request. A Connection header a handler sets itself does not do this (the server owns that header); this does.

(httpd-resp-close! c)

Since: tourist-on-stdlib-httpd H2

(httpd-resp-body! [conn :ptr<void> body :cstr] :nil)

set the HTTP response body (copies the string).

Since: Phase H1

(httpd-resp-body-bytes! [conn :ptr<void> bytes :ptr<void> len :int] :nil)

binary-safe response body setter.

Like httpd-resp-body! but takes a (ptr, byte-count) pair instead of a NUL-terminated cstr, so the body may contain embedded NUL bytes (e.g. gzip output, raw binary payloads). Copies len bytes from bytes into a fresh response-body allocation; the writer emits exactly len bytes regardless of any embedded NULs.

(httpd-resp-body-bytes! c gzip-data gzip-len)

Since: Phase H8 (M6)

(httpd-req-header [conn :ptr<void> name :cstr] :cstr)

look up a request header by name (case-insensitive).

Returns the empty string if the header is absent.

(let [ua (httpd-req-header c "User-Agent")] ...)

Since: Phase H8 (M0)

(httpd-req-header? [conn :ptr<void> name :cstr] :int)

presence test for a request header.

(when (= 1 (httpd-req-header? c "Authorization")) ...)

Since: Phase H8 (M0)

(httpd-resp-header! [conn :ptr<void> name :cstr value :cstr] :nil)

set (or replace) a response header.

If name is already present on the response, its value is replaced. Otherwise a new entry is appended. Use httpd-resp-header-add! for truly repeatable headers like Set-Cookie or Vary.

(httpd-resp-header! c "Content-Type" "application/json")

Since: Phase H8 (M0)

(httpd-resp-header-add! [conn :ptr<void> name :cstr value :cstr] :nil)

append a response header without de-duplication.

Use for headers that legitimately repeat -- Set-Cookie, Vary, WWW-Authenticate -- where each entry is independent. For single- valued headers, prefer httpd-resp-header!.

(httpd-resp-header-add! c "Set-Cookie" "session=abc; Path=/")
(httpd-resp-header-add! c "Set-Cookie" "csrf=xyz; Path=/")

Since: Phase H8 (M0)

(httpd-resp-vary! [conn :ptr<void> token :cstr] :nil)

add a token to the response's Vary header, once.

Vary lists the request headers a response depends on, and several middleware add to it (CORS adds Origin, compression Accept-Encoding). This merges: the token is appended to an existing Vary value unless it is already listed (case-insensitive), and a Vary: * is left alone.

(httpd-resp-vary! c "Accept-Encoding")
(httpd-resp-vary! c "Origin")          ; Vary: Accept-Encoding, Origin

Since: tourist-on-stdlib-httpd H4

(httpd-req-cookie [conn :ptr<void> name :cstr] :cstr)

read a single cookie value from the Cookie: header.

Parses the request's Cookie: header (using httpd-req-header) into name=value pairs separated by ; and returns the value for name. Case-sensitive on the cookie name (per RFC 6265).

(let [sid (httpd-req-cookie c "session")]
  (if (= (cstr-len sid) 0) ...))

Since: Phase H8 (M2)

(httpd-req-header-raw [conn :ptr<void> name :cstr] :cstr)

internal: a request header's value, or NULL when the request has no such header (case-insensitive name). Borrowed.

(httpd-cookie-parse-raw [header :cstr name :cstr] :cstr)

internal: one cookie's value out of a Cookie header value.

The walk every cookie accessor shares (httpd-req-cookie, httpd-string's httpd-req-cookie-raw, tourist's req-cookie): name=value pairs separated by ; and optional blanks, names compared case-sensitively (RFC 6265).

Returns a fresh malloc'd copy of the value (a present-empty cookie is a fresh ""), which the caller frees, or NULL when header is NULL or the cookie is absent.

(defstruct CookieOpts [])

fully-specified Set-Cookie attributes.

Field conventions:

path       -- "" omits the Path attribute
domain     -- "" omits the Domain attribute
max-age    -- -1 omits the Max-Age attribute; 0 expires immediately
secure     -- 0 / 1: include the "Secure" flag
http-only  -- 0 / 1: include the "HttpOnly" flag
same-site  -- "" omits; "Lax" / "Strict" / "None" otherwise

Since: Phase H8 (M2)

(cookie [name :cstr value :cstr] :CookieOpts)

construct a CookieOpts with sensible defaults.

Defaults: Path=/, no Domain, no Max-Age (session cookie), not Secure (callers on TLS should opt in via cookie-full), HttpOnly, SameSite=Lax.

(httpd-set-cookie! c (cookie "session" "abc123"))

Since: Phase H8 (M2)

(cookie-full [name :cstr value :cstr path :cstr domain :cstr max-age :int secure :int http-only :int same-site :cstr] :CookieOpts)

construct a CookieOpts with every attribute explicit.

Use this when the defaults from cookie are wrong, e.g. cross-site flows that need SameSite=None + Secure, or long-lived cookies that need a Max-Age. See CookieOpts for the per-field semantics.

(httpd-set-cookie! c (cookie-full "tracking" "t1" "/api" "example.com"
                                  3600 1 0 "None"))

Since: Phase H8 (M2)

(httpd-set-cookie! [conn :ptr<void> opts :CookieOpts] :nil)

emit a Set-Cookie response header from a CookieOpts.

Serialises the opts into a single Set-Cookie value and appends it via httpd-resp-header-add!. Calling this multiple times produces multiple Set-Cookie lines, as RFC 6265 requires.

(httpd-set-cookie! c (cookie "session" "abc123"))

docs/archive/history/defstruct-inline-c-byvalue-callsite-plan.md.

Since: Phase H8 (M2); requires the DS1 fix in

(httpd-cookie-format [opts :CookieOpts] :cstr)

internal: the Set-Cookie header value for a CookieOpts.

name=value then Path, Domain, Max-Age, Secure, HttpOnly and SameSite as CookieOpts says. Shared by httpd-set-cookie! and tourist's set-cookie!.

Returns a fresh malloc'd string the caller frees, or NULL when the name is empty or memory ran out.

Since: tourist-on-stdlib-httpd H5

(httpd-req-form [conn :ptr<void> field :cstr] :cstr)

look up a single URL-encoded form field by name.

Walks the request body (which must already have been received -- the worker reads Content-Length bytes) looking for name=value separated by &. The value is percent-decoded and + is converted to per the application/x-www-form-urlencoded convention.

(let [user (httpd-req-form c "username")
      pw   (httpd-req-form c "password")] ...)

Since: Phase H8 (M3)

(httpd-form-parse-raw [body :ptr<void> len :int field :cstr] :cstr)

internal: one field of a URL-encoded body.

The walk every form accessor shares (httpd-req-form, httpd-string's httpd-req-form-raw, tourist's form-param): name=value pairs separated by &, the value percent-decoded with + as a space. Names are compared as written (case-sensitive, not decoded).

Returns a fresh malloc'd decoded value (a present-empty field is a fresh ""), which the caller frees, or NULL when the body is empty or the field is absent.

(httpd-req-json [conn :ptr<void>] :int)

lazily parse the request body as JSON.

First call invokes json/decode on the request body and caches the resulting node tree on the connection (req_json_cache). Subsequent calls return the cached pointer. The iteration cleanup in httpd-handle calls json/free so handlers never free explicitly.

Returns 0 (nil tree) when the body is absent or json/decode fails on the input; use mw-json-body if you want a 400 short-circuit on malformed JSON.

(let [doc (httpd-req-json c)
      nm  (json/get-string (json/get! doc "name"))]
  (httpd-resp-body! c nm))

Since: Phase H8 (M3)

(mw-json-body [^fat next :(fn [ptr<void>] nil)] :ptr<void>)

pre-parse the JSON body, 400 on failure.

Wraps a base handler so that, before next runs, the request body is parsed via httpd-req-json. On parse failure (json/decode returned 0 AND the body is non-empty) the middleware sets status 400 with a small text body and does NOT call next. On success the cached tree is available to the inner handler via httpd-req-json, which returns the same pointer.

Tip: only wrap routes that genuinely require a JSON body; an empty body or a route that does not expect JSON should not 400. Check (= "application/json" (httpd-req-header c "Content-Type")) at the route layer if you want stricter gating.

(let [composed (compose-middleware base mw-json-body)]
  (httpd-new 0 composed))

Since: Phase H8 (M3)

(httpd-mw-json-body-precheck [conn :ptr<void>] :int)

internal: returns 1 when the body is non-empty but json/decode failed, 0 otherwise. Used by mw-json-body to drive the 400 short-circuit; lives as a fixed-arity helper so the if-form inside mw-json-body can stay in Turmeric.

(defstruct CorsOpts [])

mw-cors configuration.

Field conventions:

allow-origin      -- "*" for any origin (no credentials), or one origin,
                     or a comma-separated list of origins, each matched
                     exactly and echoed back with `Vary: Origin`
allow-methods     -- comma-separated list emitted on preflight
allow-headers     -- comma-separated list emitted on preflight
expose-headers    -- comma-separated list emitted on normal responses
                     (or "" to omit)
allow-credentials -- emit Allow-Credentials: true (not with "*")
max-age           -- preflight cache lifetime in seconds, or -1 to omit

Since: Phase H8 (M4); origin list and bool credentials since

(default-cors-opts :CorsOpts)

permissive defaults suitable for development.

allow-origin = "*", standard set of methods, Content-Type allowed, no expose-headers, no credentials, no max-age. Tighten for prod.

Since: Phase H8 (M4)

(cors-blank? [s :cstr] :bool)

internal: is this string NULL, empty or all blanks?

(cors-wildcard? [allow-origin :cstr] :bool)

internal: is this allow-origin the "*" wildcard?

(cors-opts [allow-origin :cstr allow-methods :cstr allow-headers :cstr expose-headers :cstr allow-credentials :bool max-age :int] :(Result CorsOpts cstr))

build a CorsOpts, refusing an invalid combination.

The checked counterpart of (make-struct CorsOpts ...): credentials with the "*" origin is an error (the CORS spec forbids it and browsers reject the response), as is an empty allow-origin.

(cors-opts "https://app.example.com, https://admin.example.com"
           "GET, POST" "Content-Type" "" true 600)
(cors-opts "*" "GET" "" "" true -1)   ; => err

Since: tourist-on-stdlib-httpd H4

(defopaque CorsConfig :int)

internal: one mw-cors instance's own copy of its settings.

A heap block HttpdCorsCfg (see httpd-cors-config-new) that lives until process exit.

(httpd-cors-config-new [allow-origin :cstr allow-methods :cstr allow-headers :cstr expose-headers :cstr allow-credentials :bool max-age :int] :CorsConfig)

internal: copy CORS settings into a heap block.

Credentials with the "*" origin are dropped (fail closed) with a line on stderr. The block is registered for release at process exit.

(httpd-mw-cors-is-preflight [conn :ptr<void>] :int)

internal: 1 iff this is a CORS preflight.

(httpd-mw-cors-allow-origin [conn :ptr<void> cfg :CorsConfig] :bool)

internal: set Access-Control-Allow-Origin (and Allow-Credentials) for this request per the config; returns true when the origin was allowed. A listed-origin config always adds Vary: Origin, allowed or not, since the answer depends on it.

(httpd-mw-cors-preflight [conn :ptr<void> cfg :CorsConfig] :nil)

internal: answer a preflight (204).

(httpd-mw-cors-decorate [conn :ptr<void> cfg :CorsConfig] :nil)

internal: decorate a normal-flow response.

(mw-cors-with [allow-origin :cstr allow-methods :cstr allow-headers :cstr expose-headers :cstr allow-credentials :bool max-age :int ^fat next :(fn [ptr<void>] nil)] :ptr<void>)

CORS middleware factory (positional args).

(mw-cors-with ao am ah eh ac ma) is a one-arg function suitable for compose-middleware: given a downstream handler next, returns a wrapped handler that either short-circuits a preflight or decorates the normal response. mw-cors-opts is the CorsOpts-valued form.

See CorsOpts / default-cors-opts for field semantics.

(compose-middleware base
  (mw-cors-with "https://app.example.com, https://admin.example.com"
                "GET, POST, OPTIONS"
                "Content-Type, Authorization"
                "" true 60))

Since: Phase H8 (M4); origin list and bool credentials since

(mw-cors [^fat next :(fn [ptr<void>] nil)] :ptr<void>)

CORS middleware with permissive defaults.

(mw-cors next) applies the default-cors-opts settings: allow-origin *, standard methods, Content-Type allowed, no credentials. Use mw-cors-opts for customised settings.

(compose-middleware base mw-cors)

Since: Phase H8 (M4)

(mw-cors-opts [opts :CorsOpts ^fat next :(fn [ptr<void>] nil)] :ptr<void>)

CORS middleware factory configured by a CorsOpts struct.

(mw-cors-opts opts next) returns a wrapped handler; the curried form (mw-cors-opts opts) is a one-arg middleware value suitable for compose-middleware:

(compose-middleware base (mw-cors-opts my-opts))

Build opts with cors-opts to have an invalid combination refused up front; options that slip through (made with make-struct) are served fail-closed as described in the section notes.

(let [opts     (ok-val (cors-opts "https://app.example.com" "GET, POST"
                                  "Content-Type" "" true 600))
      composed (compose-middleware base (mw-cors-opts opts))]
  (httpd-new 0 composed))

Since: Phase H8 (M4)

(cstr-eq-const-time [a :cstr b :cstr] :int)

length-then-constant-time XOR cstring compare.

Returns 1 when both strings have the same length AND all bytes match, 0 otherwise. The byte comparison runs over the full length even on the first mismatch, hiding the position of the difference from a timing observer. The length check is variable-time (different lengths => clearly different secrets), which is the standard trade-off for cstring credential checks.

Since: Phase H8 (M5)

(httpd-mw-basic-auth-check [conn :ptr<void> verifier :int] :int)

internal: decode + dispatch the verifier.

(httpd-basic-auth-decode-raw [hdr :cstr] :cstr)

internal: the user:pass an Authorization header carries.

Accepts Basic <base64> (scheme case-insensitive). Shared by mw-basic-auth and tourist's basic-auth. Returns a fresh malloc'd user:pass string the caller frees, or NULL when the header is NULL, not Basic, not valid base64, has no ':' in it, or decodes to a NUL byte (which would let "secret\0junk" be checked as "secret").

Since: tourist-on-stdlib-httpd H5

(httpd-mw-basic-auth-challenge [conn :ptr<void> realm :cstr] :nil)

internal: emit 401 + WWW-Authenticate.

(mw-basic-auth [realm :cstr ^fat verifier :(fn [cstr cstr] int) ^fat next :(fn [ptr<void>] nil)] :ptr<void>)

HTTP Basic Auth middleware factory.

realm is the value placed in the WWW-Authenticate: Basic realm="..." challenge. verifier is a closure of type (fn [user :cstr pass :cstr] :int) returning 1 to authorise and 0 to reject. Use cstr-eq-const-time in the verifier body for the password check. The verifier parameter is ^fat, so a bare non-capturing verifier is auto-shimmed into a fat closure -- it need not capture a free variable to be dispatched safely.

ALWAYS run Basic Auth behind TLS (see httpd-new-tls); the encoding is reversible and traverses the wire in clear text otherwise.

;; Compare BOTH fields every time and combine the results: returning
;; early on a wrong username tells a caller which usernames exist.
(let [verify (fn [u :cstr p :cstr] :int   ; captures nothing -- fine
               (let [u-ok (cstr-eq-const-time u "admin")
                     p-ok (cstr-eq-const-time p "s3cret")]
                 (* u-ok p-ok)))
      composed (compose-middleware base (mw-basic-auth "app" verify))]
  (httpd-new 0 composed))

Since: Phase H8 (M5)

(httpd-req-multipart-parse [conn :ptr<void>] :int)

internal: parse the body on first access. Returns 1 on success (parts list populated), 0 on absent / malformed / non-multipart content.

(httpd-req-file [conn :ptr<void> field :cstr] :ptr<void>)

look up a multipart part by form field name.

Triggers a lazy parse of the request body on first call; subsequent calls reuse the cached part list (freed in the iteration cleanup).

Returns an opaque part handle (:ptr<void>) usable with the httpd-part-* accessors, or 0 (NULL) when the field is absent / the body is not multipart / parsing failed.

(let [p (httpd-req-file c "upload")]
  (when (not= 0 p)
    (println (httpd-part-filename p))
    (println (int->cstr (httpd-part-data-len p)))))

Since: Phase H8 (M7)

(httpd-part-name [part :ptr<void>] :cstr)

form field name of a part (or "" if missing).

(httpd-part-filename [part :ptr<void>] :cstr)

file name attribute (or "" for non-file parts).

(httpd-part-content-type [part :ptr<void>] :cstr)

per-part Content-Type (or "" if absent).

(httpd-part-data [part :ptr<void>] :ptr<void>)

raw byte buffer (binary-safe, may contain NUL).

(httpd-part-data-len [part :ptr<void>] :int)

byte count of the part's content.

(httpd-async-fiber-body [self :ptr<void> user-data :int] :nil)

internal: per-request fiber entry point.

Runs the non-blocking version of httpd-handle on the accepted fd: sets O_NONBLOCK, reads up to end-of-headers (parking on EWOULDBLOCK), reads body, dispatches the handler, writes the response (parking on EWOULDBLOCK), and loops on keep-alive. Mirrors httpd-handle. NOTE: the trailing user/user-data slot is typed : int DELIBERATELY (an exception to the no-lazy-:int rule): this defn is hand-packed into a fat box's slot 0 (see the clos[0] = ... below / reactor.c park boxes), and the reactor invokes slot 0 through the fat-entry CARRIER convention (typedefs in src/async/reactor.c) -- every value parameter is int64_t. A ptr<void> spelling emits a void * C parameter, which -fsanitize=function flags (and CFI/CET-BTI/WASM reject) at every dispatch.

(httpd-async-accept-cb [env :ptr<void> id :int events :int user :int] :nil)

internal: reactor READ callback on the listen fd.

Drains accept() and spawns a fiber per accepted connection. Honors the A4 in-flight cap: when ha->in_flight >= ha->max_in_flight, sends a quick HTTP/1.0 503 and closes instead of spawning. NOTE: the trailing user/user-data slot is typed : int DELIBERATELY (an exception to the no-lazy-:int rule): this defn is hand-packed into a fat box's slot 0 (see the clos[0] = ... below / reactor.c park boxes), and the reactor invokes slot 0 through the fat-entry CARRIER convention (typedefs in src/async/reactor.c) -- every value parameter is int64_t. A ptr<void> spelling emits a void * C parameter, which -fsanitize=function flags (and CFI/CET-BTI/WASM reject) at every dispatch.

(httpd-new-async-with-limit [port :int ^fat handler :(fn [ptr<void>] nil) max-in-flight :int])

create an async (fiber-per-request) httpd handle.

Binds the listener to a single-thread reactor + LocalFiberGroup. Each accepted connection runs as a fiber that uses non-blocking I/O and parks on the reactor when it would block; handlers may also park explicitly via the httpd-await-* primitives.

(let [h (httpd-new-async 0 handler)]
  (httpd-run-async h)         ;; blocks until httpd-stop-async fires
  (httpd-async-free h))

Since: Phase H8 (A0+A1)

(httpd-new-async [port :int ^fat handler :(fn [ptr<void>] nil)])

create an async server capped at 512 in-flight requests.

Shortcut for (httpd-new-async-with-limit port handler 512): past 512 live request fibers a new connection is answered 503 and closed. 512 sits under the common 1024 open-file soft limit, so a flood is refused before it exhausts the process's descriptors. Use the -with-limit variant to choose another cap (0 = unlimited).

Since: Phase H8 (A0+A1)

(httpd-run-async [h :ptr<void>])

drive the async server until stopped.

Blocks the calling thread, running the fiber-per-request loop. Returns when httpd-stop-async fires (or the reactor exits for any other reason).

Since: Phase H8 (A0+A1)

(httpd-stop-async [h :ptr<void>])

request a graceful shutdown of the async server.

Sets the stop flag, removes the listener source from the reactor, and wakes the reactor so httpd-run-async returns. In-flight fibers finish naturally when their reads/writes complete.

Since: Phase H8 (A0+A1)

(httpd-async-free [h :ptr<void>] :nil)

tear down an async server handle.

Free the fiber group, reactor, and synthetic closures. Call only after httpd-run-async has returned.

Since: Phase H8 (A0+A1)

(httpd-async-port [h :ptr<void>] :int)

read the bound TCP port on an async server.

Useful when port=0 was passed to httpd-new-async (kernel-assigned).

Since: Phase H8 (A0+A1)

(httpd-await-readable [conn :ptr<void>] :nil)

suspend the current fiber until conn fd is readable.

Wraps local-park-fd for the READ event with no timeout. Must be called from inside a request fiber spawned by httpd-new-async; in the blocking thread-pool path it is a no-op (the fiber group is NULL).

Since: Phase H8 (A0)

(httpd-await-writable [conn :ptr<void>] :nil)

suspend until conn fd is writable.

(httpd-await-timer [conn :ptr<void> ms :int] :nil)

suspend the current fiber for ms milliseconds.

Built on local-park-fd with timeout-only: the reactor still polls the conn fd (no events of interest); when the timeout elapses the fiber resumes. Suitable for per-request deadlines, exponential back-off, etc.

Since: Phase H8 (A0)

(router-new :ptr<void>)

create an empty router.

Since: Phase H6

(router-add [r :ptr<void> method :cstr pattern :cstr ^fat handler :(fn [ptr<void>] nil)] :nil)

register a route with the given method, pattern, and handler.

The handler closure is called when an incoming request's method matches and its path matches the pattern. Path segments starting with ':' capture the corresponding request segment; the value can be read inside the handler via httpd-param.

Since: Phase H6

(router-free [r :ptr<void>] :nil)

free a router and all registered routes.

Since: Phase H6

(router-dispatch [r :ptr<void> conn :ptr<void>] :nil)

match the current request against the router's table.

On match: attaches captured path params to conn, calls the route's handler with conn, then frees the params. On no match: sets a 404 response with body "Not Found".

Since: Phase H6

(httpd-param [conn :ptr<void> name :cstr] :cstr)

read a captured route parameter set by router-dispatch.

;; pattern "/users/:id" matched against "/users/42"
(httpd-param conn "id")  ; => "42"

Since: Phase H6

(httpd-call [handler :int conn :ptr<void>] :nil)

invoke a Turmeric handler closure on a connection.

handler is an already-erased fat-closure handle (:int) -- typically a captured next threaded through a middleware, or a value produced by compose-middleware. Handlers entering the server from user code arrive through a ^fat parameter (httpd-new, the mw-* factories, mw-basic-auth) that auto-shims a bare non-capturing fn, so by the time it reaches httpd-call it already carries a valid { thunk, env } layout.

Since: Phase H7

(defroute [router method pattern handler])

macro sugar for (router-add router method pattern handler).

(defroute r "GET" "/" (fn [c :ptr<void>] :nil ...))

Since: Phase H6

(httpd-mw-mono-ms :int)

monotonic clock helper (milliseconds). Internal.

(httpd-mw-log-line [c :ptr<void> elapsed-ms :int] :cstr)

internal: the log line for a completed request.

METHOD PATH -> STATUS BYTES MSms, then ip=ADDR when mw-trust-proxy resolved a client address and rid=ID when mw-request-id assigned an id. No trailing newline. The string belongs to the request.

(httpd-mw-log-emit [c :ptr<void> elapsed-ms :int] :nil)

emit one log line for a completed request. Internal.

(mw-log [^fat next :(fn [ptr<void>] nil)] :ptr<void>)

request logging middleware (stdout).

Wraps a base handler so every request prints one line to stdout after the handler returns. The line carries the request method, path, the response status (defaulting to 200 if unset), the response body length in bytes, and the elapsed wall time in milliseconds -- then ip=ADDR when an mw-trust-proxy outside it resolved the client address, and rid=ID when an mw-request-id outside it assigned a request id. mw-log-to sends the same line somewhere else.

(let [base     (fn [c :ptr<void>] :nil
                 (httpd-resp-status! c 200)
                 (httpd-resp-body!   c "hi"))
      composed (mw-log base)]
  (httpd-new 0 composed))

Since: Phase H8 (M1)

(httpd-mw-log-sink-call [sink :int line :cstr] :nil)

internal: hand a line to a mw-log-to sink closure.

(mw-log-to [^fat sink :(fn [cstr] nil) ^fat next :(fn [ptr<void>] nil)] :ptr<void>)

request logging middleware with your own sink.

mw-log's line (see mw-log), handed to sink instead of printed: write it to a file, a structured logger, a ring buffer for a test. The string is borrowed and lives until the request is finished -- copy it to keep it. The sink runs on the worker that served the request, so several can run at once.

(mw-log-to (fn [line : cstr] : nil (eprintln line)) base)

Since: tourist-on-stdlib-httpd H4

(compose-middleware [base & mws])

wrap a base handler with multiple middlewares.

(let [composed (compose-middleware base mw-log)]
  (httpd-new 0 composed))

;; Multiple middlewares (mw-log is outermost):
(let [composed (compose-middleware base mw-log mw-cors mw-auth)]
  (httpd-new 0 composed))

Since: Phase H8 (M8 core)

(defopaque Handler :int :affine)

an owned, composed request-handler onion (the result of compose-middleware-of / a folded middleware chain).

:affine (use-at-most-once, move-only) is the key: a bound Handler the owner neither MOVES (hands to a server via httpd-handler-carrier) nor BORROWS (invokes via (:: h :int) / httpd-call) is AUTO-DROPPED at scope exit through its Drop instance -- TUR_CLOSURE_DROP walks the captured next boxes down to the base handler, reclaiming the whole onion. This retires the explicit httpd-mw-drop for the runtime-built-chain case: bind the fold result as a Handler and the compiler drops it for you. The carrier is the same int64 fat-closure handle every httpd handler rides, so a Handler bridges to :int / (fn [int] int) by ascription.

Since: automatic R3a (closure-drop-glue)

(httpd-handler-drop [h :Handler] :void)

internal: reclaim a composed Handler onion.

Routes to TUR_CLOSURE_DROP, which recovers the env's drop-glue header and walks the owning captures (the wrapped downstream handlers) before freeing -- the whole onion down to the base, released exactly once. Consumes its affine argument. This is the Drop instance's method; it is not normally called by hand (the scope-exit auto-drop calls it).

Since: automatic R3a (closure-drop-glue)

(definstance Drop [Handler])

reclaim the onion when a bound Handler dies unmoved/unborrowed.

(httpd-handler-carrier [h :Handler] :(fn [ptr<void>] nil))

CONSUME a Handler, yielding its raw int64 carrier for a server constructor (^fat handler : (fn [ptr<void>] nil)) or any :int handler sink that TAKES OWNERSHIP.

Because the parameter is the affine Handler itself, passing a bound Handler here MOVES it -- which suppresses the scope-exit auto-drop, so the server (whose httpd-free / httpd-async-free already TUR_CLOSURE_DROPs its handler) becomes the SOLE owner with no double-free. Use this at a server handoff; use (:: h :int) (a non-consuming read) only for a BORROW where the owner keeps the Handler and lets it auto-drop.

(let [composed (compose-middleware-of base mw1 mw2)]
  (httpd-new-pool 0 1 (httpd-handler-carrier composed)))

Since: automatic R3a (closure-drop-glue)

(defopaque ClosureChain :int :affine)

an owned runtime-built middleware chain: a cons list whose heads are fresh, uniquely-owned factory closures and whose spine cells the builder owns. httpd-mw-fold only BORROWS it (applies each head once); once the fold has produced its onion the whole chain -- heads and cells -- is dead.

:affine (same discipline as Handler): a bound ClosureChain the builder neither MOVES nor BORROWS ((:: chain :int)) is AUTO-DROPPED at scope exit via its Drop instance, which walks the spine dropping each head (TUR_CLOSURE_DROP) and freeing each cell. This is the automatic-R3a replacement for the explicit httpd-mw-free-chain.

SOUNDNESS: sound iff each head is a DISTINCT, uniquely-owned closure (a fresh (make-mw) per cell) -- the same contract httpd-mw-free-chain documents. Do NOT cons the same closure value into the list twice (double-drop), and do NOT wrap a chain whose heads are the borrowed & mws of compose-middleware-of (those heads belong to the variadic caller; use httpd-mw-free-spine, which frees ONLY the cells).

Since: automatic R3a (closure-drop-glue)

(httpd-chain-drop [c :ClosureChain] :void)

internal: reclaim a ClosureChain (drop each head factory via TUR_CLOSURE_DROP + free each spine cell). Consumes its affine argument; it is the Drop instance's method, normally invoked by the scope-exit auto-drop.

Since: automatic R3a (closure-drop-glue)

(definstance Drop [ClosureChain])

reclaim a runtime-built chain when its builder binding dies unmoved/unborrowed.

(httpd-mw-apply [mw :int cur :int] :int)

internal: apply one fat-closure middleware to a handler.

The middleware is a fat closure of shape (fn [next :int] :ptr<void> ...); this performs a single fat-closure dispatch -- the same ascription idiom as httpd-call -- and returns the wrapped handler. It holds no cons-layout knowledge; the list walk lives in httpd-mw-fold. The caller guards against a null mw.

The dispatch ascription MUST name the middleware's REAL type, (fn [int] ptr<void>) -- the emitted call goes through a typed-thunk typedef derived from this ascription, and the lambda's definition is emitted from its own declared type. The old (fn [int] int) spelling made the two disagree on the return type: works on every SysV/AAPCS ABI (same return slot), but it is UB that -fsanitize=function reports and that CFI / CET-BTI / WASM call_indirect turn into a hard failure. The wrapped handler then crosses back to the :int carrier via a value ascription, which is a representation read, not a function-type cast. See docs/archive/emitter-thunk-type-return-mismatch.md.

(httpd-mw-fold [base :int mws :int] :int)

internal: right-fold a cons-list of fat-closure middlewares over a base handler. Each cell holds a fat closure value of shape (fn [next :int] :ptr<void> ...). Applied right-to-left so the list head becomes the outermost wrapper. Null cells are skipped. Unbounded -- the walk recurses over the cons-list abstraction (list-head/list-tail), so there is no fixed element cap.

(httpd-mw-free-spine [mws :int] :nil)

internal: free the cons-cell spine of a variadic middleware rest-list, leaving the head VALUES untouched. compose-middleware-of owns the fresh & mws list; httpd-mw-fold only walks it (applying each head once), so once the fold has built the wrapper chain the spine cells are dead and can be reclaimed. The head factories are borrowed (the caller frees them at its own scope exit), so this frees ONLY the cells, never the heads.

(httpd-mw-drop [handler :int] :nil)

SUPERSEDED: reclaim a raw-:int composed handler onion.

Retired in favor of the Handler auto-drop (automatic R3a): bind the fold result as a Handler ((:: (httpd-mw-fold base chain) :Handler), or use compose-middleware-of, which returns Handler) and the compiler drops the onion for you at scope exit -- no explicit call, and no risk of forgetting it. Kept only for a legacy raw-:int onion that was never bound as a Handler; new code should not use it.

Releases the outermost wrapper AND walks the captured downstream next boxes via the env's drop-glue header, so the whole onion (down to the base handler) is freed.

(let [composed (:: (httpd-mw-fold base chain) :Handler)]
  (httpd-call (:: composed :int) conn))   ; composed auto-drops at scope exit

Since: R3a; superseded by Handler auto-drop (automatic R3a).

(httpd-mw-free-chain [mws :int] :nil)

SUPERSEDED: free a runtime-built middleware cons list (the INPUT to httpd-mw-fold): drop each head factory closure AND free each spine cell.

Retired in favor of the ClosureChain auto-drop (automatic R3a half 2): bind the runtime chain as a ClosureChain ((:: (build-chain n (tnil)) :ClosureChain)) and the compiler walks the spine, dropping each head and freeing each cell, at scope exit -- no explicit call. This function's body is exactly the Drop [ClosureChain] method; kept only for a legacy raw-:int chain that was never bound as a ClosureChain.

Unlike httpd-mw-free-spine (which leaves the heads, because the variadic compose-middleware-of caller owns and frees them), a hand-built runtime chain (e.g. from a build-chain loop) is owned entirely by its builder: the fold only BORROWS each factory (applies it once, discards it), so once the fold has produced the composed onion the whole list -- factories and cells -- is dead and the builder reclaims it. Sound iff each head is a distinct, uniquely-owned closure (a fresh (make-mw) per cell); do NOT cons the same closure value into the list twice (that would double-drop it).

(let [chain    (:: (build-chain 70 (tnil)) :ClosureChain)
      composed (:: (httpd-mw-fold base (:: chain :int)) :Handler)]
  (httpd-call (:: composed :int) conn))  ; composed + chain auto-drop at scope exit

Since: R3a; superseded by ClosureChain auto-drop (automatic R3a half 2).

(compose-middleware-of [A])

runtime variadic form of compose-middleware.

This is a defn, not a macro. Use when the chain is built at runtime (e.g. dependent on config, feature flags, or a runtime-chosen subset). Apply order matches compose-middleware: leftmost = outermost.

Each rest argument must be a *fat closure value* of shape (fn [next :int] :ptr<void> ...) -- i.e. a closure that captures at least one variable. A bare top-level defn name is NOT a fat closure; passing one will compile (thanks to the docs/archive/history/variadic-rest-closure-cast-plan.md fix) but the fat- closure dispatch dereferences code bytes as the fn pointer and BUS-faults. Bridge a bare defn through a let-captured fn literal:

(let [_ 0
      mw-log-val (fn [n :int] :ptr<void> (mw-log n))
      _ 0]
  (compose-middleware-of base mw-log-val ...))

For statically-known chains the macro form compose-middleware remains the better choice -- it accepts bare defns and catches non-callable mistakes at elaboration.

docs/archive/history/variadic-rest-closure-cast-plan.md.
Returns `Handler` since automatic R3a (closure-drop-glue).

Since: Phase H8 (M8 core); requires the V1 cast fix in

(httpd-mw-content-length [conn :ptr<void>] :int)

internal: read Content-Length as int64, or -1.

Returns -1 when the header is absent or unparseable. A non-negative return value is the announced body size in bytes.

(mw-body-size [max-bytes :int ^fat next :(fn [ptr<void>] nil)] :ptr<void>)

reject requests with Content-Length > max-bytes with 413.

When the request advertises a Content-Length greater than max-bytes this middleware responds with status 413 ("Payload Too Large") and a short plain-text body, and does NOT invoke next. Requests without a Content-Length header, or with a value at or below the cap, are passed through unchanged.

The cap is on the announced size. It runs after the server has read the body, so it limits what a handler accepts, not what the server buffers -- httpd-set-max-body! is the ceiling that stops the read itself.

(let [composed (mw-body-size 1048576 base)]  ; 1 MiB cap
  (httpd-new 0 composed))

Since: Phase H8 (MW1)

(httpd-set-attr! [conn :ptr<void> key :cstr val :cstr] :nil)

attach a key/value pair to the current request.

Overwrites any previously-set value for the same key (case-sensitive). The key and value are copied into per-request storage; the original cstrings can be reused or freed by the caller. The attribute lives until the handler returns, then is freed alongside the request / response header lists.

(httpd-set-attr! c "user" "alice")

Since: Phase H8 (MW2)

(httpd-req-attr [conn :ptr<void> key :cstr] :cstr)

retrieve a previously set request attribute.

Returns the empty string ("") if the key has not been set. The returned pointer is into per-request storage and is only valid until the handler returns.

(let [u (httpd-req-attr c "user")] ...)

Since: Phase H8 (MW2)

(httpd-req-remote-ip [conn :ptr<void>] :cstr)

return the client's IP address as a cstr.

Uses getpeername(2) on the connection fd. IPv4 addresses are returned in dotted-quad form ("203.0.113.4"); IPv6 in colon-hex form. Returns the empty string ("") on lookup failure. The returned pointer is into per-request storage and is valid only for the duration of the handler call.

(let [ip (httpd-req-remote-ip c)] ...)

Since: Phase H8 (MW2)

(defstruct RateLimitOpts [requests :int window-s :int])

mw-rate-limit configuration.

Field conventions:

requests -- max requests per window (>= 1)
window-s -- window length in seconds (>= 1)

Since: Phase H8 (MW2)

(httpd-mw-ratelimit-new [requests :int window-s :int] :int)

internal: allocate a fresh RL state struct.

(httpd-mw-ratelimit-check [state :int ip :cstr] :int)

internal: bump the counter for ip; return 0 if the request is allowed, or N>0 = the seconds until the window ends when the request must be rejected.

(httpd-mw-ratelimit-emit-429 [conn :ptr<void> retry-s :int] :nil)

internal: write the 429 response.

(mw-rate-limit [opts :RateLimitOpts ^fat next :(fn [ptr<void>] nil)] :ptr<void>)

sliding-window IP-based rate limiter middleware.

Each mw-rate-limit instance allocates its own counter table. When the same client IP exceeds requests requests within window-s seconds the middleware responds with 429 Too Many Requests plus a Retry-After: <seconds> header without invoking next.

Multiple mw-rate-limit instances get independent counters; share by reusing the same wrapped closure across compositions.

The client is keyed by httpd-req-ip: the peer address, or -- behind an mw-trust-proxy that runs outside this middleware -- the client address it read from X-Forwarded-For. Without that, every client behind one proxy shares the proxy's bucket.

(let [composed (mw-rate-limit (make-struct RateLimitOpts 60 60) base)]
  (httpd-new 0 composed))

Since: Phase H8 (MW2)

(httpd-mw-static-mime [path :cstr] :cstr)

internal: map an extension to a Content-Type.

(httpd-mw-static-try [conn :ptr<void> root :cstr] :int)

internal: attempt to serve path from root relative to the request req-path. Returns 1 on success (response written), 0 if the file is not found / forbidden.

(httpd-static-listing! [conn :ptr<void> dir :cstr path :cstr plen :int] :bool)

internal: answer with an HTML listing of dir (an already-resolved directory), titled with the first plen bytes of path. Dotfiles are left out; directories come first, then files, each group byte-wise. Returns false (nothing written) when dir cannot be read.

(httpd-static-serve-with-flags! [conn :ptr<void> root :cstr rel :cstr index-file :cstr listing :bool] :bool)

internal: httpd-static-serve-with! with the StaticOpts fields passed one by one (index-file "" = none).

(httpd-static-serve! [conn :ptr<void> root :cstr rel :cstr] :bool)

answer a request with a file under a root directory.

mw-static's file serving, for callers that pick the path themselves (a framework mapping /assets/* onto a directory, say). rel is joined onto root (its query string ignored); the file must resolve, symlinks and all, to a regular file inside root, and no segment of rel may start with '.' (.well-known excepted) or contain a backslash. A hit sets status 200, the body (binary-safe), Content-Type from the extension and a strong ETag of "<size hex>-<mtime hex>"; an If-None-Match naming that tag (or *) gets 304 with the ETag and no body.

(when (not (httpd-static-serve! c "./public" "/index.html"))
  (httpd-resp-status! c 404))

Since: tourist-on-stdlib-httpd H5

(defstruct StaticOpts [index :cstr listing :bool])

what the static path does with a request for a directory.

Fields:

index   -- a file to serve for a directory path, e.g. "index.html";
           "" serves none
listing -- render an HTML listing when there is no index

(mw-static-with (StaticOpts "index.html" true) "./public" base)

Since: project-less-tools-plan PT0

(httpd-static-serve-with! [conn :ptr<void> opts :StaticOpts root :cstr rel :cstr] :bool)

httpd-static-serve!, with an index and a listing.

The same file path, containment and dotfile rules as httpd-static-serve!. A request that resolves to a directory, which httpd-static-serve! treats as a miss, is answered according to opts:

1. without a trailing '/' -- 301 to the same path with one, so relative
   links in the page resolve inside the directory;
2. with `(.index opts)` naming a regular file in it -- that file, ETag
   and all;
3. with `(.listing opts)` -- an HTML listing (text/html, no ETag):
   directories first, names escaped and percent-encoded, size and
   modification time, dotfiles left out;
4. otherwise a miss.

With (StaticOpts "" false) it is exactly httpd-static-serve!.

(when (not (httpd-static-serve-with! c (StaticOpts "index.html" true) "./site" (httpd-req-path c)))
  (httpd-resp-status! c 404))

Since: project-less-tools-plan PT0

(httpd-mw-static-fallback [conn :ptr<void> root :cstr] :nil)

internal: when the response status is 404, try to serve a file from root; otherwise no-op. Always returns nil.

(httpd-mw-static-fallback-with [conn :ptr<void> root :cstr index-file :cstr listing :bool] :nil)

internal: mw-static-with's fallback; the StaticOpts fields passed one by one.

(mw-static [root-dir :cstr ^fat next :(fn [ptr<void>] nil)] :ptr<void>)

serve files from a root directory when next returns 404.

Composes after a router: next is consulted first; only when next sets the response status to 404 (the default-handler signal that no route matched) does mw-static attempt to serve a file. The request path is joined onto root-dir and .. segments are rejected as a path-traversal guard. The Content-Type is inferred from the file extension; an ETag of "<size>-<mtime>" is emitted and honoured (If-None-Match matching returns 304 without resending the body).

(let [composed (mw-static "./public" router-handler)]
  (httpd-new 0 composed))

Since: Phase H8 (MW2)

(mw-static-with [opts :StaticOpts root-dir :cstr ^fat next :(fn [ptr<void>] nil)] :ptr<void>)

mw-static, with an index file and a directory listing.

mw-static treats a request for a directory as a miss. This one answers it the way opts says (httpd-static-serve-with! has the rules): a 301 to add the trailing '/', the index file when there is one, else a listing when (.listing opts) is set. Both are opt-in so a framework composing mw-static after its router does not grow a listing by surprise.

(httpd-new 8000 (mw-static-with (StaticOpts "index.html" true) "." not-found))

Since: project-less-tools-plan PT0

(httpd-mw-recover-500 [conn :ptr<void>] :nil)

internal: write a 500 response unless the handler already set a status before panicking. Always returns nil.

(mw-recover [^fat next :(fn [ptr<void>] nil)] :ptr<void>)

catch a downstream panic and respond 500.

Wraps a base handler so that a panic (or any unwind) raised inside next is caught at the middleware boundary. Without it a panicking handler unwinds out of the worker and takes the process (or at best the connection) with it; with it the request gets a 500 and the server keeps serving.

Put it OUTERMOST in the middleware chain -- it can only recover panics raised by handlers it wraps, and an outer middleware's post-processing still runs on the 500 response.

(let [base     (fn [c :ptr<void>] :nil (panic "boom"))
      composed (compose-middleware base mw-recover)]
  (httpd-new 0 composed))
; => client sees "500 Internal Server Error"; the server stays up

Since: Phase H8 (MW3)

(httpd-resp-has-header? [conn :ptr<void> name :cstr] :bool)

has the response a header of this name yet?

Case-insensitive. Middleware that supplies a default (a security header, an ETag) checks this first so a value the route set wins.

(when (not (httpd-resp-has-header? c "Cache-Control"))
  (httpd-resp-header! c "Cache-Control" "no-store"))

Since: tourist-on-stdlib-httpd H4

(defstruct SecureHeadersOpts [])

mw-secure-headers configuration.

Field conventions ("" or -1 leaves a header out):

content-type-options       -- send X-Content-Type-Options: nosniff
frame-options              -- X-Frame-Options ("DENY", "SAMEORIGIN")
referrer-policy            -- Referrer-Policy
cross-origin-opener-policy -- Cross-Origin-Opener-Policy
hsts-max-age               -- Strict-Transport-Security max-age in
                              seconds, or -1 (default) for none
hsts-include-subdomains    -- add includeSubDomains to the HSTS header
content-security-policy    -- Content-Security-Policy, "" (default) for none

HSTS and CSP are opt-in: HSTS switched on by accident locks a domain to https for its max-age, and a wrong CSP default breaks pages silently.

Since: tourist-on-stdlib-httpd H4

(default-secure-headers-opts :SecureHeadersOpts)

the safe defaults.

nosniff, X-Frame-Options: DENY, Referrer-Policy: no-referrer, Cross-Origin-Opener-Policy: same-origin; no HSTS, no CSP.

(mw-secure-headers-opts (default-secure-headers-opts) base)

Since: tourist-on-stdlib-httpd H4

(defopaque SecureHeadersConfig :int)

internal: one mw-secure-headers instance's own copy of its headers (a heap block that lives until process exit).

(httpd-secure-headers-config-new [content-type-options :bool frame-options :cstr referrer-policy :cstr cross-origin-opener-policy :cstr hsts-max-age :int hsts-include-subdomains :bool content-security-policy :cstr] :SecureHeadersConfig)

internal: build the header list once.

(httpd-mw-secure-headers-apply [conn :ptr<void> cfg :SecureHeadersConfig] :nil)

internal: add each configured header the response does not carry already.

(mw-secure-headers-opts [opts :SecureHeadersOpts ^fat next :(fn [ptr<void>] nil)] :ptr<void>)

security headers on every response (helmet).

After next returns, adds each header the options configure unless the response already has one of that name -- a route that sets its own X-Frame-Options keeps it. See SecureHeadersOpts for the headers and why HSTS and CSP are off unless asked for.

(let [opts (make-struct SecureHeadersOpts true "SAMEORIGIN" "no-referrer"
                        "same-origin" 31536000 true "default-src 'self'")]
  (compose-middleware base (mw-secure-headers-opts opts)))

Since: tourist-on-stdlib-httpd H4

(mw-secure-headers [^fat next :(fn [ptr<void>] nil)] :ptr<void>)

mw-secure-headers-opts with the safe defaults.

(compose-middleware base mw-secure-headers)

Since: tourist-on-stdlib-httpd H4

(httpd-mw-request-id-assign! [conn :ptr<void>] :nil)

internal: pick the request's ID and echo it.

An incoming X-Request-Id is kept only if it is 1-128 characters of [A-Za-z0-9._-] -- anything else (a CRLF, a 1 KiB value, a quote) is replaced, so a client cannot inject into logs or headers through it. Otherwise 128 random bits, as 32 hex digits.

(httpd-req-id [conn :ptr<void>] :(Option cstr))

the request's ID, when mw-request-id assigned one.

(let [id (httpd-req-id c)]
  (when (some? id) (println (unwrap id))))

Since: tourist-on-stdlib-httpd H4

(mw-request-id [^fat next :(fn [ptr<void>] nil)] :ptr<void>)

give every request an ID and echo it in X-Request-Id.

Keeps a well-formed incoming X-Request-Id (1-128 of [A-Za-z0-9._-]), else generates 128 random bits as hex. The ID is readable downstream with httpd-req-id, mw-log puts it on each line, and the response carries it (a route may still replace the header).

(compose-middleware base mw-log mw-request-id)   ; mw-log sees the ID

Since: tourist-on-stdlib-httpd H4

(defstruct TrustProxyOpts [trusted :cstr])

which peers may tell the server who the client is.

trusted is a comma-separated list of addresses and CIDR ranges, IPv4 or IPv6 ("10.0.0.0/8, 192.0.2.7, fd00::/8"), and the keywords loopback, linklocal and uniquelocal (the private ranges). The default trusts nobody, so X-Forwarded-For and X-Forwarded-Proto are ignored.

Since: tourist-on-stdlib-httpd H4

(default-trust-proxy-opts :TrustProxyOpts)

trust no proxy.

(mw-trust-proxy (default-trust-proxy-opts) base)   ; peer address only

Since: tourist-on-stdlib-httpd H4

(httpd-ip-parse [s :cstr len :int out :ptr<void>] :bool)

internal: parse a numeric IPv4 or IPv6 address (the first len bytes of s, optionally in [brackets]) into 16 bytes, IPv4 as ::ffff:a.b.c.d. False when it is not an address.

(httpd-trust-parse [trusted :cstr out :ptr<void> cap :int] :int)

internal: parse a trusted list into cap records {16-byte address, prefix bits} at out; returns the count, or -1 when an entry is neither an address, a CIDR nor a keyword.

(trust-proxy-opts [trusted :cstr] :(Result TrustProxyOpts cstr))

build a TrustProxyOpts, refusing an entry that does not parse.

(trust-proxy-opts "loopback, 10.0.0.0/8")
(trust-proxy-opts "10.0.0.0/33")          ; => err

Since: tourist-on-stdlib-httpd H4

(defopaque TrustProxyConfig :int)

internal: one mw-trust-proxy instance's parsed ranges.

(httpd-trust-proxy-config-new [trusted :cstr] :TrustProxyConfig)

internal: parse the trusted list once. An unparsable list trusts nobody (and says so on stderr).

(httpd-mw-trust-proxy-resolve! [conn :ptr<void> cfg :TrustProxyConfig] :nil)

internal: work out the client address and protocol and record them on the request.

An untrusted peer is the client, and its forwarding headers are ignored. A trusted peer's X-Forwarded-For is walked right to left: each hop that is itself trusted is skipped, and the first that is not is the client (a hop that does not parse ends the walk at the last good one). X-Forwarded-Proto is believed only from a trusted peer, and only as http or https.

(mw-trust-proxy [opts :TrustProxyOpts ^fat next :(fn [ptr<void>] nil)] :ptr<void>)

resolve the client address and protocol behind proxies.

Put it outermost: middleware inside it (mw-rate-limit, mw-log) and the handler then see the real client through httpd-req-ip / httpd-req-proto. With the default options (or without this middleware) those return the peer address and the connection's own protocol.

(compose-middleware base
  (mw-trust-proxy (ok-val (trust-proxy-opts "loopback")))
  (mw-rate-limit (make-struct RateLimitOpts 100 60)))

Since: tourist-on-stdlib-httpd H4

(httpd-req-ip [conn :ptr<void>] :cstr)

the client's IP address.

What mw-trust-proxy resolved, when it ran; otherwise the peer address (httpd-req-remote-ip). The string lives as long as the request.

(httpd-req-ip c)   ; => "203.0.113.9" behind a trusted proxy

Since: tourist-on-stdlib-httpd H4

(httpd-req-proto [conn :ptr<void>] :cstr)

"https" or "http": how the client reached the server.

A trusted proxy's X-Forwarded-Proto when mw-trust-proxy ran, else whether this connection is TLS.

(when (cstr-eq? (httpd-req-proto c) "http") (redirect-to-https c))

Since: tourist-on-stdlib-httpd H4

(httpd-mw-etag-apply [conn :ptr<void>] :nil)

internal: tag a 200 GET/HEAD response and answer a matching If-None-Match with 304.

(mw-etag [^fat next :(fn [ptr<void>] nil)] :ptr<void>)

ETags and 304s for dynamic responses.

After next returns a 200 to a GET or HEAD, sets a weak ETag computed from the body (unless the route set an ETag itself, which is then the one compared), and answers a matching If-None-Match with 304 and no body -- the client reuses its copy. The body is still built every time; this saves the transfer, not the work. mw-static does the same for files from their size and mtime.

(compose-middleware api-handler mw-etag)

Since: tourist-on-stdlib-httpd H4

(httpd-mw-timeout-run [conn :ptr<void> next :int ms :int] :nil)

internal: run next on a helper thread against a private copy of the request, and wait up to ms for it.

In time, the copy's response (status, headers, body, the attributes and strings it made) moves onto the real conn. Late, the real conn is answered 503 and the copy is left to the helper thread, which frees it when the handler finally returns. The copy has no socket (fd -1), so a late handler cannot write to a connection that has moved on, and cannot upgrade it.

(httpd-mw-timeout-thread [arg :ptr<void>] :ptr<void>)

internal: the helper thread's body.

(httpd-mw-timeout-free [arg :ptr<void>] :nil)

internal: release a job and its copy of the request.

(mw-timeout [ms :int ^fat next :(fn [ptr<void>] nil)] :ptr<void>)

answer 503 when a handler overruns ms milliseconds.

Runs next on a helper thread against a private copy of the request and waits up to ms. In time, its response is used as usual. Late, the client gets 503 Service Unavailable at the deadline -- but the handler KEEPS RUNNING to completion on its thread: threads cannot be cancelled, so a deadline answers the client early, it does not stop the work. The late handler's response is discarded; it cannot reach the client (its copy has no socket) or upgrade the connection. Let late handlers finish before httpd-free, which releases the closures they run.

On the async server it runs next inline with no deadline.

(compose-middleware slow-report-handler (mw-timeout 2000))

Since: tourist-on-stdlib-httpd H4