moon_router

A request body as a JSON object.

Anything that is not an object — a bare number, an array, a truncated document — is one answer, because a client that sent any of them made the same mistake. An empty body is an empty object, which is what a POST with no fields means.

• body: Raw request body text; an empty body reads as an empty object.

use moon_router.binding
use std.json.Json

struct Update { title: string, tags: [string] }

fn main() {
  let body = binding.json_body(
    "{\"title\":\"moon\",\"zoom\":2,\"active\":true,\"ids\":[1,2]}",
  ).unwrap()
  println(binding.require_non_empty(binding.string_field(body, "title").unwrap(), "title"))
  println(binding.number_field(body, "zoom", 1.0))
  println(binding.bool_field(body, "active", false))
  println(binding.int_array_field(body, "ids"))
  println(binding.require_range(2.0, 1.0, 10.0, "zoom"))
  println(binding.strict_int("42"))
  println(binding.require_strict_int("42", "invalid id", "id"))
  println(binding.typed_body<Update>("{\"title\":\"moon\",\"tags\":[]}"))
}

The one answer a malformed body gets, named so a route that reads a body some other way can give the same one.

A request body as a T, decoded by its codec.

The fourteen extractors below are for a body whose shape is genuinely dynamic. A body with a known shape should declare a struct and come through here instead of calling six of them in a row, each re-stating a field's name, its type, and what counts as a bad value for it.

A decode failure is the same VALIDATION_ERROR envelope the hand-written path produces, so a client cannot tell which route read its body which way. The codec's message names the JSON path it failed at (decode: expected string at $.tags[3].name, found int), and that is what rides the field channel — strictly more than "Invalid JSON" says, and in the same place.

• body: Raw request body text, decoded by T's codec.

A string field, or "" when absent. A present field of the wrong type is a bad request rather than a missing one — the client meant to send it.

• body: The decoded request body object.
• key: Field name to read.

A number field as a float. JSON has one number type; the distinction between 3 and 3.0 is a spelling, not a meaning.

• body: The decoded request body object.
• key: Field name to read.
• fallback: Value used when the field is absent.

A number field that may genuinely be absent, which is different from being zero: an unsent zoomLevel leaves the stored one alone.

• body: The decoded request body object.
• key: Field name to read.

Reads an optional Boolean field from a JSON object.

• body: The decoded request body object.
• key: Field name to read.
• fallback: Value used when the field is absent.

Reads an optional integer field from a JSON object.

• body: The decoded request body object.
• key: Field name to read.
• fallback: Value used when the field is absent.

A field that must be an array of integers — a list of ids. Absent and null are none, which a caller distinguishes from an empty array meaning "clear the list".

• body: The decoded request body object.
• key: Field name to read.

Reads a required string-array field from a JSON object.

• body: The decoded request body object.
• key: Field name to read.

Refuses a value outside its range, naming the field so a UI can point at the input that is wrong rather than at the form.

• value: Value to check.
• low: Lowest value accepted.
• high: Highest value accepted.
• field: Field name carried in the validation error.

A bound as the message spells it. to_string already prints an integral float without a decimal point, which is what interpolating a JavaScript number does.

• value: Bound to render into a message.

Rejects an empty field value with a validation error.

• value: Field value to check.
• field: Field name carried in the validation error.

An optional sign and digits, and nothing else — no whitespace, no decimal point, no empty value. none when the text is not exactly an integer.

Stricter than a permissive parse on purpose, and the strictness is not any one language's: strconv.Atoi, Rust's str::parse and JavaScript's Number() all refuse the same texts. " 12" and "12abc" are not twelve, and reading them as twelve is how a typo in a URL silently operates on the wrong row.

• value: Text that must be exactly an optional sign followed by digits.

strict_int where a bad value is a 400 naming the field, rather than a silent absence — the shape a path segment wants, since /tags/{id} with a malformed id names no row at all.

• value: Text that must be exactly an optional sign followed by digits.
• message: Message carried in the validation error.
• field: Field name carried in the validation error.

A 200 response with a JSON body. (ok is a moon keyword, hence success.)

• json_body: Already-serialized JSON text.

use moon_router.envelope
use std.http.Response
use std.json.Json

struct Project { name: string, year: int }

fn main() {
  println(envelope.success("{\"ok\":true}").status)
  println(envelope.ok_status(201, "{\"created\":true}").status)
  println(envelope.ok_json(Json.Obj({"name": Json.Str("moon")})).body)
  println(envelope.ok_typed(Project { name: "moon", year: 2026 }).body)
  println(envelope.no_content().status)
  println(envelope.from_result(ok("{}")).status)
}

A JSON response with an explicit status.

• status: HTTP status for the response.
• json_body: Already-serialized JSON text.

Installs the application's error body rendering. Set once, at boot.

A service replacing one written in another language has a shape it must match byte for byte, and it is usually not this one: Go's AppError is flat, and a Go service encodes it with HTML escaping and a trailing LF. A closure rather than a fixed set of shapes, because the encoder is the application's too.

• render: Called as render(status, code, message, field) to produce the error body.

Restores this package's nested envelope.

This package's shape: {"error":{"message":…,"code":…,"field":…,"status_code":…}}.

• status: HTTP status for the response.
• code: Machine-readable error code.
• message: Human-readable message.
• field: Field the error is about; omitted when empty.

The flat shape a Go AppError emits: {"error":…,"code":…,"field":…}, with the status carried by the response line alone.

• status: HTTP status for the response.
• code: Machine-readable error code.
• message: Human-readable message.
• field: Field the error is about; omitted when empty.

The AppError envelope: field is omitted when empty.

• status: HTTP status for the response.
• code: Machine-readable error code.
• message: Human-readable message.
• field: Field the error is about; omitted when empty.

use moon_router.envelope
use std.http.Response

fn main() {
  let carried = envelope.field_message("title is required", "title")
  let (message, field) = envelope.split_field(carried)
  println(message + ":" + field)
  println(envelope.status_for("NOT_FOUND"))
  println(envelope.code_for("SqlError"))
  println(envelope.app_error(400, "VALIDATION_ERROR", message, field).body)
  let failed: Result<string, Error> = err.NOT_FOUND("missing")
  println(envelope.from_result(failed).status)
}

The separator a carried field name hides behind. U+0001, which no message a person writes contains.

A message that carries field with it, for err.VALIDATION_ERROR(..).

• message: Human-readable message.
• field: Field name carried alongside it.

Splits a carried message back into (message, field).

• message: A message built by field_message.

The HTTP status for an error name.

The names are the conventional ones a service raises, and everything unrecognised is 500 — a failure nobody classified is an internal one, which is the safe direction: it is better to under-report a client error than to tell a client its request was at fault when the server was.

• name: The failure's error name.

The wire code for an error name: a classified name passes through, anything else reports as INTERNAL_ERROR.

This is the leak guard. An unclassified failure's name is an internal detail — SqlError, WriteFailed, whatever the module happened to call it — and a client that could read it would be reading the server's internals. OPERATION_FAILED is the exception because it is deliberately raised as a 500 a client is meant to see named.

• name: The failure's error name.

A failure as an envelope response: status and code derived from its name, and a carried field name taken back out of its message.

• failure: The failure to render.

Either half of a handler's Result, rendered.

The shape almost every handler ends in, and the reason from_error exists: a handler computes a Result<string, Error> and this decides whether that is a 200 with a body or a status derived from the failure's name.

• outcome: A handler result whose success half is already-serialized JSON text.

Installs the application's success-body encoding. Set once, at boot.

• render: Called with the response tree to produce the body bytes.

Restores std.json.to_string.

value as response bytes, through the installed encoder.

• value: The tree to render.

A JSON response carrying an encoded Json value.

• status: HTTP status for the response.
• value: The tree to render into the body.

json at 200. (ok is a moon keyword, hence the longer name.)

• value: The tree to render into the body.

204 with no body: an action that succeeded and has nothing to report.

Either half of a handler's Result<Json, Error>, rendered.

• outcome: A handler result whose success half is a Json tree.

A typed JSON response with an explicit status: T encoded by its codec.

Total, because to_value<T> is — a T this cannot encode is a compile error at the call site naming the part of the type that is the problem, not a Result every handler has to thread.

The bytes are written straight out of the value when nothing has installed a body renderer, which is the ordinary case. Going through to_value<T> would materialize the whole document as a Json tree so that to_string could read it once and throw it away — measured at 50 ms of tree against 14 ms of direct encode for a 1.5 MB listing (overhaul plan E2). A service that has installed a renderer still gets the tree, because a renderer's argument is a Json by signature.

• status: HTTP status for the response.
• value: The value to encode by T's codec.

typed at 200.

• value: The value to encode by T's codec.

Either half of a handler's Result<T, Error>, rendered.

• outcome: A handler result whose success half is a T.

The media type an extension names, application/octet-stream when it names nothing this table knows.

Deliberately short. It covers what a service actually streams — video, images, the text a browser renders — and a service with a format of its own passes the content type to serve directly rather than growing this.

• path: Path whose extension names the media type.

use moon_router.files
use moon_router.router
use std.http_server.Request

fn main() {
  println(files.content_type_for("poster.webp"))
  println(files.content_type_for("video.mp4"))
  println(files.is_read_method("HEAD"))
  let request = router.detached_request(
    "GET",
    "/video",
    "Range: bytes=100-199",
    "",
  )
  println(files.header(request, "range"))
  println(files.range_start(request, 1000))
}

Whether method asks to read: GET or HEAD.

A file route answers both, and only both — a HEAD is a GET whose body the client does not want, which is why serve_file handles it rather than the route.

• method: HTTP method, uppercase.

Request header name, or none when it was not sent.

std.http_server.get_header answers "" for both absent and empty, and a range parser has to tell those apart: an empty Range is a malformed request, an absent one is an ordinary read.

• req: Request to read from.
• name: Header name, matched case-insensitively.

The first byte a Range header asks for, or 0 when there is no usable one.

For a log line or a metric — what part of the file a client jumped to. serve_file does the real range handling, including the 416 this cannot express.

• req: Request that may carry a Range header.
• size: Size of the resource in bytes.

Serves path on the socket and answers router.responded().

A missing file goes through the application's own not-found rendering rather than the plain-text 404 serve_file writes for an unopenable path: a service whose 404 is an envelope should answer file routes the same way, and a client cannot tell which route it asked for from the shape of the answer it gets.

• ctx: Request context, used for the connection and the not-found rendering.
• path: File to serve from disk.
• content_type: Value of the Content-Type header.

serve with the content type read off the extension.

• ctx: Request context, used for the connection and the not-found rendering.
• path: File to serve from disk; its extension picks the content type.

Structured request logging via std.log: one info record per request with method, path, status, and wall duration.

CORS configuration; permissive() gives the common defaults.

* origin, the common verb set, Content-Type, Authorization headers.

expose_headers, allow_credentials and preflight_unmatched are all off.

use moon_router.envelope
use moon_router.middleware
use moon_router.router
use std.http.Response
use std.http_server.Request

fn main() {
  let app = router.new()
  let policy = middleware.permissive()
  app.use_mw(middleware.logging())
  app.use_mw(middleware.cors(policy))
  app.get("/health", |_ctx| envelope.success("{\"ok\":true}"))
  let response = app.dispatch(router.detached_request("GET", "/health", "", ""))
  println(middleware.with_cors(response, policy).headers)
}

response with this policy's CORS headers appended.

The middleware does this itself; it is public for the answers that never reach a middleware — a router's fallbacks run outside the onion by construction, and those are exactly the four responses (a 404, a wrong verb, a crash, a timeout) a browser most needs to be allowed to read.

• response: The response the headers are appended to.
• options: The policy whose headers are written.

CORS middleware: answers OPTIONS preflights with 204 plus the Access-Control-* headers (the router routes a method-miss through the node's middleware chain, which is what makes this fire), and appends Access-Control-Allow-Origin to ordinary responses.

• options: The policy the middleware enforces.

One request, as a logging sink sees it. path is router.path_of — the query dropped, and a trailing slash with it — so two spellings of the same resource are one line in a log and one label in a metric.

How logging_async decides what to record and where to send it.

Log everything, through std.log.

A structured record per request, the level chosen by the status: a 4xx or 5xx is a warning, everything else is information.

• record: The finished request to write.

The async twin of logging(): one record per request, with the quiet-path rule and the caller's sink.

This is the one an ordinary service actually reaches. Every route that talks to a database is registered with *_async, and use_mw_async feeds a chain of its own, so logging() never fires for any of them.

• options: Which paths stay quiet, and where records go.

use moon_router.middleware
use moon_router.router
use std.http.Response

fn main() {
  let app = router.new()
  let logging = middleware.log_all()
  app.use_mw_async(middleware.logging_async(logging))
  app.use_mw_async(middleware.cors_async(middleware.permissive()))
}

The async twin of cors(): a preflight answered with 204 and the rules, and the response headers on everything else.

With preflight_unmatched set this also installs a router.use_preflight responder, because a preflight to a path no route claims never reaches a middleware chain at all — there is no matched node whose onion could run. That is a side effect on the process rather than on a value, and it is deliberate: the alternative is every service repeating the four-line OPTIONS short-circuit ahead of dispatch_async, which is exactly the code this replaces.

• options: The policy the middleware enforces.

How much of a small part is read before it is refused.

Generous for what these fields actually carry — a filename, a tag id list, a preview config object — and far below anything that would matter, which is the point: a field with no ceiling is a way to exhaust memory over a form that looks ordinary.

How much is pulled from the socket at a time.

How much of a whole small upload — a thumbnail, a sprite sheet, an I-frame manifest — is read before it is refused.

One part read fully into memory.

Reads one part into memory, refusing anything over the field ceiling.

• part: The part currently under the multipart reader.
• limit: Byte ceiling; a larger part is refused rather than buffered.

Drains a part without keeping it. Used for the parts a route does not want: the body still has to be consumed to reach the next boundary.

• part: The part to drain so the reader can reach the next boundary.

Streams one part through sink, returning how many bytes passed through.

The sink is called with each chunk as it arrives, so a video part is written to storage as it is uploaded rather than assembled in memory first.

• part: The part to stream.
• sink: Called with each chunk as it arrives; its counts are summed.

Every part of a request, read into memory under the field ceiling.

For the three upload routes whose parts are all small — a thumbnail, a sprite sheet, an I-frame manifest and its segment. The video upload does not use this; it streams.

A repeated name keeps the last part, which is what reading them into a map does in the original.

• request: Streaming request whose body is multipart/form-data.
• limit: Byte ceiling applied to each part.

use moon_router.multipart
use std.http_server.Request

fn fields(request: Request) -> Result<string, Error> {
  let parts = multipart.buffered_parts(request, multipart.MAX_FIELD_BYTES)?
  let title = if parts.has("title") { parts["title"].text() } else { "" }
  ok(title)
}

fn main() {
  println(multipart.extension_of("C:\\uploads\\Poster.WEBP"))
  println(multipart.CHUNK_BYTES)
  println(multipart.MAX_UPLOAD_BYTES)
}

The extension of an uploaded filename, lowercased, including the dot.

Read from the last dot in the last path segment: an upload from a Windows client may carry a whole path, and a directory with a dot in its name must not be mistaken for a file type.

• filename: Uploaded filename, possibly carrying a whole Windows path.

Per-request context handed to handlers: the raw request plus decoded route params. The raw req passes through untouched so plan-55 streaming handlers (respond_stream, serve_file) keep working.

The path a request target names: the query string dropped, and a trailing slash with it, because /api/videos/ names the resource /api/videos does.

Matching does not need it — the trie splits on segments, so both spellings already reach the same route — but everything that reads a target back does: a log line, a metric label, a dispatcher looking at the raw target off the socket. Exported because those readers are otherwise each one find("?") away from getting it subtly wrong.

• target: Raw request target, query string and all.

key=value pairs from a request target's query string, percent-decoded with + read as a space — which is what a query string spells it as and what url_decode deliberately does not do, since a + in a path segment is a plus.

• target: Raw request target, query string and all.

url_decode with + read as a space.

• text: Query-string text to percent-decode, reading + as a space.

How a router answers a request no handler produced a response for.

Supplied by an application whose wire shape is not this package's — a port whose 404 is Go's text/plain body, say, or one that deliberately answers 404 for a wrong verb because the router it replaced did not distinguish. Absent means the envelope, which is what every existing caller gets.

The Ctx handed to each is the request as it arrived, with whatever params were bound before the answer was decided (none, for a 404).

A routing group: value handle over shared storage plus this group's prefix, middleware chain, and timeout class.

Creates an empty router.

use moon_router.envelope
use moon_router.router
use std.http.Response
use std.http_server.Request

fn main() {
  let app = router.new()
  let api = app.group("/api")
  api.get("/projects/{id}", |ctx| {
    envelope.success("{\"id\":\"" + ctx.param("id") + "\"}")
  })
  api.post("/projects", |_ctx| envelope.ok_status(201, "{}"))

  let request = router.detached_request(
    "GET",
    "/api/projects/moon?limit=20&draft=true",
    "",
    "",
  )
  let response = app.dispatch(request)
  println(response.status)
  println(app.find("GET", "/api/projects/moon").params)
  println(app.surface())
  println(router.path_of(request.path))
  println(router.query_pairs(request.path))
}

Percent-decodes a path segment; + is left alone (path, not query, semantics). Invalid escapes pass through literally.

• text: Path segment to percent-decode; + is left as a plus.

A guard, not a limit any real request approaches: JSON routes take small documents, and anything genuinely large should be arriving as multipart and being streamed.

The request body as a string, read off the socket if it is still there.

accept_stream deliberately leaves the body unread, so an upload route can pull a multi-gigabyte file in windows rather than materialise it. Every other route reads req.body — so on an accept_stream server, something has to do that read, and without it every POST and PUT looks to every handler like it carried nothing. The failure is quiet and confusing: an API answers "name is required" to a request that supplied a name.

Two cases are left alone, and both are the point. A body already present is returned untouched (an accept server buffered it). A multipart/ body is not read at all, because those bytes belong to the route that streams them.

• req: The request whose body to read; a multipart/ body is deliberately left alone.

Whether req arrived over a socket this process still holds.

_handle is the accepted descriptor, so a real request always has one; a request built by detached_request carries -1 and nothing may be read off it. Anything reaching for the connection — draining a body, streaming a response, serving a file — has to ask first.

• req: The request to test for a live descriptor.

A Request that never came off a socket.

Routing is the half of a service that is worth testing hardest and the half that needs a live connection least: which route a path picks, what the params decode to, what the middleware puts on the way out, and what answers a request nothing matched are all decided before a byte moves. Opening a listener to ask those questions makes the suite slow, flaky and unable to run two cases at once, so this builds the request instead.

target is the raw request target, query string included, exactly as a client would have sent it. headers is the \n-joined block, and body is the body the handler will see — a detached request has no socket to drain one from, so what is passed here is all there is. A route that streams (serve_file, respond_stream) still needs a real connection; dispatch and dispatch_async do not.

• method: HTTP method, uppercase.
• target: Raw request target, query string included.
• headers: Header block joined with newlines.
• body: Body the handler will see; there is no socket to drain one from.

The sentinel a streaming handler returns after responding through the raw request (respond_stream/serve_file): accept-loop servers must skip respond for it.

Whether response is the already-responded sentinel.

• response: The value a handler returned.

Answers every OPTIONS request from responder, ahead of route matching.

The gap it closes: a preflight to a path no route claims matches nothing, so there is no captured middleware chain to run and no CORS middleware can fire — the browser reads a 404 and refuses the real request that would have followed. A path claimed only under another verb has the same problem with a 405. Neither is a routing question; both are answered by the CORS rules alone, which is why the answer belongs ahead of resolve.

Process-wide rather than per-Router, like envelope.use_error_body: a preflight policy is a property of the service that is listening, and the alternative is threading it through every group handle. middleware.cors_async installs it from CorsOptions.preflight_unmatched; a service with a different rule can install its own.

• responder: Answers every OPTIONS request, ahead of route matching.

Restores matched-chain preflight handling.

This service's not-found rendering for ctx, or the package envelope when no application installed one.

files.serve is the caller that matters: a file route that answers 404 should answer it in the shape every other route does, and the plain-text body std.http_server.serve_file writes for an unopenable path is nobody's wire contract.

• ctx: The request context the 404 is rendered for.

Forgets the recorded fallbacks; the package envelope answers again.

Result of Router.find: status is 200 (route matched — pattern and params describe it), 405 (allow lists the methods), or 404.

Async dispatch for accept-loop servers: the sync semantics plus recovery (a failed handler becomes a 500 envelope, logged at error level with the detail — the client never sees internal error text) and per-group timeouts (a 503 envelope once the route's timeout class expires; the handler task keeps running to completion, mirroring chi where the work is not preempted).

• r: The router to match against.
• req: The request to answer.

How long a shutdown waits for in-flight work before giving up on it.

The signals a service stops on. Ctrl-C and the one an orchestrator sends.

One connection at a time, each served on its own task.

Never returns on its own: the caller cancels it. That is not a shortcut — there is no other way to leave an accept that no client will complete.

• listener: Listener handle to accept on.
• serve_one: Called with each accepted request, on a task of its own.

Blocks until the process is asked to stop, and answers which signal did it.

Serve until a stop signal arrives, then shut down in the one order that works.

Accept in a spawned task; wait; cancel the acceptor before closing the listener, since a parked accept cannot notice a closed socket it is already inside; close the listener so nothing new is taken; then run the caller's drain against drain_ms. Answers true if the drain finished inside its deadline, false if the deadline won — a caller that wants to exit non-zero on a hung shutdown has the answer rather than having to time it itself. A second stop signal also returns false. Waiting for that signal keeps the default hybrid clock paced during the drain, including when its work is blocked in native I/O. An explicitly pinned virtual clock stays virtual.

idle_timeout_ms is how long a finished keep-alive connection may sit in the pool before the server closes it; 0 keeps std.http_server's 60 s default, the same way drain_ms of 0 keeps DEFAULT_DRAIN_MS. A service behind a proxy that holds connections open longer than this will reconnect more often than it needs to, and one that never times them out accumulates descriptors for clients that walked away.

• listener: Listener handle to accept on.
• serve_one: Called with each accepted request, on a task of its own.
• drain: Run after the listener closes, to finish in-flight work.
• drain_ms: How long the drain may take; 0 keeps DEFAULT_DRAIN_MS.
• idle_timeout_ms: How long an idle keep-alive connection may sit in the pool; 0 keeps std.http_server's 60 s default.

use moon_router.router
use moon_router.serve
use moon_router.router.Router
use std.http.Response
use std.http_server.Request

async fn serve_one(app: Router, request: Request) -> int {
  let response = await router.dispatch_async(app, request)
  if !router.is_responded(response) {
    std.http_server.respond(request, response)
  }
  0
}

async fn drain() -> int { 0 }

async fn main() {
  let app = router.new()
  app.get("/health", |_ctx| std.http_server.text(200, "ok"))
  let listener = std.http_server.listen("127.0.0.1", 8080)
  println(await serve.serve_with_shutdown(
    listener,
    |request| serve_one(app, request),
    drain,
    serve.DEFAULT_DRAIN_MS,
    60_000,
  ))
}