chttp is a minimal HTTP router for node:http, async-first. The package has zero runtime dependencies and is authored in the scriptc-compilable subset of TypeScript, so scriptc build can statically lower the whole package into a native binary. Routes are registered on an App, matched against a trie at request time, and handled by a chain of middleware plus one handler that writes the response through Ctx helpers. Handlers and middleware may return promises: dispatch awaits a non-sett...
A request enters through the node:http listener created by app.serve() or app.handler(). The listener calls app._dispatch, which first offers the request to the registered generated dispatch module (the build-time seam), then splits req.url into path and query string, matches the path against the route trie, picks the entry for the method, and runs the precomposed chain for that entry. Ctx helpers (text, json, html, redirect) set status, headers, and content length, then...
flowchart TD
A[node:http server receives request] --> B["app._dispatch(req, res)"]
B --> C{"_gen(req, res) returns true?"}
C -- "yes, generated module handled it" --> Z[response already written]
C -- no --> D[split url into path and query string]
D --> E["matchPath over route trie"]
E -- "no node" --> F[run notFound chain]
E -- "node found" --> G{"findEntry for method"}
G -- "no entry, node has routes" --> H["allow405: Allow header, optional onError"]
G -- entry found --> I["pick precomposed _chains[idx]"]
F --> J[new ReqView + new Ctx]
I --> J
J --> K{"body declared and write method?"}
K -- yes --> L["buffer data/end events, then run chain"]
K -- no --> M["run chain"]
L --> N["chain writes via Ctx helpers"]
M --> N
N --> O[response complete]
M -- "throws or rejects" --> P["onError if set, else send500"]
L -- "throws or rejects" --> P
M -- "settled, no response" --> P
L -- "settled, no response" --> P
P --> O
H --> O
F --> O
| Module | Role |
|---|---|
packages/router/src/index.ts |
The whole core: App, Ctx, ReqView, compose, matchPath, addRoute, error path, exported createRouter() factory |
packages/router/src/gen.ts |
The GenDispatch base class and DispatchFn type, the interface between runtime dispatch and build-generated route modules |
packages/unplugin/src |
Build-time plugin: extracts the literal route table from *.chttp.ts modules and emits a routes.gen.ts that satisfies contracts/route-contract.md |
Inside packages/router/src/index.ts:
ReqView(line 37) is a read view overIncomingMessage: method, path, query, headers, body. Param and query tables materialize lazily; dispatch skips param work entirely for handlers that never read them.Ctx(line 213) wrapsReqViewplusServerResponseand exposes the response-writing helpers.sentrecords whether a body-carrying helper already flushed, which the error path consults.- The route table is a trie of plain records (
RouteNode, line 325). Node kinds: 0 static, 1:param, 2*wildcard. Handlers never live in the records;hfstores indices intoApp._fnsand parallel class-side arrays (_mws,_chains,_pn,_pi,_sp,_bodyF) hold per-entry metadata. matchPath(line 431) does zero-allocation matching over the raw path withcharCodeAtsegment bounds. A static-only fast descent runs first; on a miss it hands off to a depth-first search over an explicit frame stack (no recursion). Children are visited wildcard, param, then static, so static segments win.findEntry(line 503) resolves the method against the matched node's method table, with*(all) and HEAD-falls-back-to-GET support.App._dispatch(line 964) is the request entry described above.runOnError(line 1039) andsend500(line 639) hold the error path.
Verb methods (get, post, put, delete, patch, head, options, all, on) all funnel into App._add, which registers the handler via _regFn and inserts the path into the trie via addRoute. app.use(fn) pushes a middleware onto the app-level list; a route registers a snapshot of the current list, so middleware added after a route does not affect it. app.route(prefix, subApp) flattens a sub-app's trie into the parent under a prefix, merging the parent's current middleware...
Each registered entry is composed exactly once, at registration time: compose(mw, handler) folds the middleware snapshot and handler into one Handler stored in _chains[i]. Dispatch calls that function directly. There is no runtime chain walker and no per-request closure allocation. The semantics are linear koan-style: next() resumes the tail, and a middleware that calls next() twice re-runs the tail twice.
Route paths support static segments, :name params, and a trailing * wildcard splat. Param names and segment positions are extracted once at registration (pathMeta) and bound to the ReqView at dispatch. Values are decoded and materialized only on the first param() or splat read.
Match results are not memoized in a cache object. The memoization is structural. The per-entry chain, middleware snapshot, param metadata, and body flag are all computed once during _regFn. Each request pays only for the trie walk, one method lookup, and one prebuilt array access.
Bodies are opt-in per route: app.post('/x', h, { body: true }). Only then, and only for write methods (POST, PUT, PATCH, DELETE), does dispatch attach data/end listeners, buffer chunks via string concatenation, set the body on ReqView, and run the chain from the end callback. Without the flag, c.req.body() returns ''.
multipart/form-data follows the same declaration seam: app.post('/x', h, { multipart: { ... } }). chttp sits on raw node:http — there is no runtime formData() to delegate to, so src/multipart.ts owns the bytes: a byte-level parser (MultipartParser, explicit state machine, _pend carry so boundaries split across chunks still match) feeds a MultipartStorage strategy per file part — memoryStorage() buffers into UploadedFile.bytes, diskStorage(dir) streams writeSync calls into a temp file and reports path + size. Declarative limits (maxFileBytes, maxFiles, maxFieldBytes) are enforced during the parse; a breach answers 413 mid-upload, destroys the socket on finish, and unlinks the partial temp file — nothing is buffered twice and nothing is re-serialized. Results land on the ReqView before the chain runs, so c.req.file()/field()/files()/fields() stay synchronous. body and multipart on the same route throw at registration (multipart owns the stream). Generated dispatch declines these routes — the runtime is the only parser owner (contracts/route-contract.md, Declared-multipart rule).
Every chain invocation goes through runChain: one try/catch for the synchronous path, plus await settlement inside settleChain when the chain result is not already settled (undefined/null/c are; everything else, in practice promises, is not). Throws and rejections reach runOnError through the same code. A settled chain that never wrote a response gets the built-in 500 fallback.
On an error, runOnError applies this order:
- If headers were already sent, the socket is destroyed (nothing sane to write); otherwise the user
onError(err, c)runs, if registered. - If the handler answered (checked via
Ctx.sent), dispatch stops there. - If it did not answer, the built-in
send500writes a plain-text 500. - Anything thrown inside
onErrorfalls back tosend500too, so a request always gets exactly one terminal outcome and the error handler cannot loop.
A path match whose method misses goes through allow405 instead: a 405 with an Allow header built from the node's registered methods (* expands to every standard verb, GET implies HEAD). If an onError is registered it first gets a synthetic Ctx wrapping the real request so it can answer custom 405s.
Ctx writes through a ResponseSink rather than directly to a ServerResponse. The sink has two concrete subclasses:
NodeResponseSink(packages/router/src/sink.ts) wraps a realnode:httpServerResponse.setStatus,setHeader,appendHeader,bodymap one-to-one to the underlying socket. This is the path theapp.handler()adapter uses.FetchResponseSinkcaptures into a{status, headers: Headers, chunks: Uint8Array[]}record.app.fetch()finalizes the sink by constructing anew Response(stream, init)from the captured chunks, so the same chain code produces a spec-compliant WebResponsethat the Workerd / Deno Deploy / Bun / Vercel Edge / Service Worker / Lambda @edge runtime can serialize and ship.
The two sinks share a ResponseSink base class with setStatus, setHeader, appendHeader, body, redirect, isSent, and finalize. Ctx holds the sink; c.text, c.json, c.html, c.bytes, c.header, c.redirect, c.status all dispatch through it. Handlers and middleware never see ServerResponse or Response directly except via c.req.raw (the inbound Request) and the optional c.res getter (the outbound platform object: ServerResponse on the Node path, a Response-shaped view on the fetch path).
app.handler() is a ~60 LOC Node adapter that synthesizes a Request from the inbound IncomingMessage (path, method, query, headers, buffered body) and a NodeResponseSink over the ServerResponse, then awaits app._runSink(req, sink). app.fetch(req, env?, ctx?) is the canonical entry — the same createRouter() symbol works on Node, every Workers / Edge runtime, and as a Service Worker.
@chttp/stream writes through the same sink. On the Node path chunks flush straight to the socket; on the fetch path they collect into a ReadableStream that the runtime pulls lazily. Streaming parity is covered by the standard pnpm test suite plus the chttp-fetch scriptc gate (bench/apps/chttp-fetch.ts, 100% static coverage).
Generated dispatch (@chttp/unplugin) still emits a NodeResponseSink-shaped class — the build-time seam is Node-shaped and unchanged. The fetch path synthesizes a Request plus a NodeResponseSink and intercepts finalize() to produce the Response. A follow-up issue proposes a parallel Web-Standards-shaped emitter (GenFetch); it's not required for the surface contract.
chttp's source is written inside the scriptc-compilable subset so scriptc build lowers it to a native binary. The constraints that force the code into its current shape:
- The only async function in the package is
settleChain, the fire-and-forget settler called when a chain result is not already settled. Promises cannot be detected directly in the subset: reading.thenas a value refuses (SC1090; in expression position it silently lowers toundefined),instanceof Promiseis refused, and a union mixingPromiseand non-Promise arms refuses (SC2009).awaitis the one narrowing left: it passthroughs non-thenables and joins real promises, so the disc... | nullunions only, never| undefined.- No
Object.create(null)orObject.freeze; plain record literals with full shapes. - Indexed
forloops only;.pop()as a statement, never an expression. - No
?./??, no object or method shorthand in literals, no spread, noeval/new Function. - No function values inside records: handlers and middleware snapshots live in parallel arrays on the
Appclass, and trie nodes store numeric indices. Function-typed record fields degrade instantiation tounknownand fence every call site. - No recursion for matching:
matchPathandmountRoutesuse explicit frame stacks, because recursive calls monomorphize anunknowninstantiation. String(x)/Number(x)coercion at function entry for parameters that arriveunknown.- Bodies are read with
req.on('data' | 'end')plus string concatenation.Buffer.concat(Buffer[])does lower.
The GenDispatch seam (packages/router/src/gen.ts) is a base class whose default dispatch returns false. The unplugin emits a class CompiledRoutes extends GenDispatch from the extracted route table and the app registers it with app.withDispatch(...). _dispatch offers every request to that module first, so generated code can dispatch literal routes directly (seeding pre-materialized param pairs via ReqView._seedPm) and bypass the general trie entirely. The unplugin is delibera...
Reference documents:
contracts/route-contract.mdis the frozen contract for generated dispatch modules: emitted class shape, param seeding, body flag handling, and error behavior.docs/unplugin.mddocuments the build-time plugin: extraction rules, the module model, and the emitted code shape.