chttp is a minimal HTTP router for node:http, async-first, zero dependencies, authored in the scriptc compilable subset so the same source compiles to a single native ELF. Workspace: packages/router (runtime) and packages/unplugin (build-time route-lowering plugin).
pnpm test- all workspace testspnpm --filter @chttp/router build- build runtime packagepnpm smoke:pack- pack router and val, compile the tarballs to an ELF with scriptc, curl it (runpnpm -r buildfirst)pnpm lint- oxlint (type-aware)pnpm fmt- oxfmtpnpm --filter @chttp/unplugin test- plugin testspnpm docs:build- build docs sitebash scripts/scriptc-gate.sh- 100% static coverage on all five scriptc gates (chttp-html, chttp-stream, chttp-val, static/gate, chttp-fetch). Every API change inpackages/routeris gated on this staying at 100%.
All packages/* publish at one shared version via pnpm native versioning (versioning.fixed in pnpm-workspace.yaml; pnpm change check guards drift in CI).
pnpm changeper logical change, commit the intent file with the change.- At release:
pnpm version -r(bumps the fixed group, consumes intents, writes CHANGELOGs), commit, tagv<version>. - Tag push triggers
.github/workflows/release.yml: verifies every package.json matches the tag, publishes all nine.
Full procedure in RELEASING.md, release notes in CHANGELOG.md (root entry generated by node scripts/changelog-root.mjs).
Publish and pack with pnpm only (pnpm publish, pnpm pack), never npm publish or npm pack. Internal ranges are workspace:^ and only pnpm rewrites them to real semver ranges in the tarball; npm would ship the workspace: protocol and break installs.
These are hard bans. The full rationale lives in ARCHITECTURE.md section 0.
- Handlers/middleware may return a Promise; dispatch settles a non-settled chain result by
awaiting it insidesettleChain(the package's only async function; fire-and-forget). Sync-complete results —undefined,null, or thecobject — keep a zero-microtask path viaisSettled. NEVER detect promises by reading.thenas a value (typeof r.thensilently lowers toundefined),instanceof Promise(SC1090), or a union mixing Promise/non-Promise arms (SC2009). | nullunions only. Neverundefined(SC3004).- No
Object.create(null)/Object.freeze. Plain({})records only. Classes only for the router's entity types (Ctx,ReqView, sinks,HttpError). - Indexed
forloops (andfor...ofover arrays). Neverfor...in. - No
new Function/eval, no non-programinstanceof, no object/method-shorthand. - Concrete types on all route/middleware tables; no
any[]/unknown[](SC1090).
contracts/route-contract.md is the frozen seam contract between runtime and generated dispatch. Do not diverge from it.
- Generic method calls dispatch only through
ClientCorereceivers — generic signatures on theClient<App>interface are signature-only to scriptc (SC1090). ELF consumers bindconst c: ClientCore = createClient(u); gate apps do the same. Record<ParamKey<P>, string>may appear only in the interface's.d.tssurface — any program code that names or converts it (assignment,as, field copy) fails SC2003/SC2009. That's why class method params takeClientInputCore, andParamKeychecking is Node-side only.- Reading a missing record key throws at runtime under scriptc ("record has no key" — typed slots can't represent undefined). Probe optional headers/fields with
Object.prototype.hasOwnProperty.call(rec, k)before indexing, matching ReqView. - Overload signatures don't monomorphize (only the implementation signature does) — don't use them for subset code.
node:tlsconnect(port, host, {servername, rejectUnauthorized})lowers as of 0.3.3 (verified in the gate);new URLlowers.
- Conventional commits, atomic commits (one logical change each).
- Any handler or dispatch change ships with tests.
- Any performance claim requires re-running the relevant bench cell first.
bench/RESULTS-v2.mdis the baseline. - Plugin work is fixture-first:
fixtures/vite-appmust build before an emit change lands. Seepackages/unplugin/AGENTS.md.
app.fetch(req: Request) → Promise<Response> is the canonical entry. app.handler() is a thin Node adapter around it. Both compile to a native ELF — the bench/apps/chttp-fetch.ts gate must stay at 100% static coverage.
No-bluff rule. Any sentence in user-facing docs (README, docs/, comments, or release notes) claiming chttp is "Web Standards compatible", "drops into the Hono ecosystem", or "runs on Cloudflare Workers" must be backed by a passing test. The gate for the Hono claim specifically is examples/integrations/hono-middleware/test/logger.test.ts — it imports logger from hono/logger unmodified, fires a real Request through app.fetch, and asserts the inbound log line. If that test is removed or skipped without a replacement, the matching sentence in the README must be removed in the same PR. PR review enforces this; no exceptions.
The full surface is documented in ARCHITECTURE.md under "Response sink and the two surfaces". The new ResponseSink class (packages/router/src/sink.ts) is the single seam that lets the same Ctx produce either a ServerResponse write or a Web Response finalization. Both subclasses stay inside the scriptc subset.