# chttp Documentation - Full Context

> Generated by docmd

---

## [Coding agents](https://chttpjs.pages.dev/architecture/)

# Coding agents

Read this before writing or changing chttp code. The core is authored in the scriptc compilable subset, so some normal TypeScript is banned.

## Give an agent the docs

These docs are published for agents too: [llms.txt](https://chttpjs.pages.dev/llms.txt) is the page index, [llms-full.txt](https://chttpjs.pages.dev/llms-full.txt) is every page in one file. Point your agent at either.

## Subset rules for `packages/router/src`

- `| null` unions only. Never `undefined`.
- No `Object.create(null)`, `Object.freeze`. Plain `({})` records only.
- Classes only for the router's entity types (`CtxCore`/`Ctx`, `ReqViewCore`/`ReqView`, the response sinks, `HttpError`).
- Indexed `for` loops or `for...of` over arrays. Never `for...in`.
- No `new Function`, `eval`, non-program `instanceof`, object or method shorthand.
- Concrete types on route and middleware tables. No `any[]` or `unknown[]`.
- Never detect promises with `typeof r.then` or `instanceof Promise`. Dispatch settles non-settled results by `await` inside `settleChain`.

```ts
// ok
for (let i = 0; i < routes.length; i++) {}
const rec: { [k: string]: string } = {};

// banned
for (const k in rec) {}
const fns = { run: function (): void {} };
```

## Shape of the code

- One core file, `packages/router/src/index.ts`: router, context, dispatch, the Node-shaped `app.handler()` adapter, and the Web Standards-shaped `app.fetch()`.
- A second core file, `packages/router/src/sink.ts`: the `ResponseSink` abstraction plus `NodeResponseSink` (writes to `ServerResponse`) and `FetchResponseSink` (captures into a Web `Response`). `Ctx` holds a `ResponseSink`; both surfaces route through the same chain.
- Route data is plain records. Handlers live in `App._fns`, nodes carry indices.
- Matching uses an explicit frame stack, no recursion.
- Response helpers call the sink at statement level. `app.fetch()` finalizes the sink to a `Response` in the chained promise; `app.handler()` finalizes by writing to `res.end()`.

## Where to read more

- [ARCHITECTURE.md](https://github.com/sigilco/chttp/blob/main/ARCHITECTURE.md): request flow, compose model, error path, scriptc compilation.
- [AGENTS.md](https://github.com/sigilco/chttp/blob/main/AGENTS.md): commands, release flow, full ban list.
- Repo skills: [`chttp-app-dev`](https://github.com/sigilco/chttp/blob/main/.agents/skills/chttp-app-dev/SKILL.md) for writing subset-compatible apps, [`chttp-integration`](https://github.com/sigilco/chttp/blob/main/.agents/skills/chttp-integration/SKILL.md) for wiring chttp and the plugin into an existing project.
- Build-time lowering: [Route lowering plugin](unplugin.md).


---

## ['@chttp/auth](https://chttpjs.pages.dev/auth/)

# @chttp/auth

Auth primitives for chttp apps — sessions, cookies, scrypt passwords, CSRF, JWT, OAuth2+PKCE and TOTP — as plain async functions over `node:crypto`, authored in the scriptc-compilable subset. The same source builds to a JS package with `tsc` and lowers into a native ELF with `scriptc build`. Zero runtime dependencies.

```ts
import {
  MemorySessionStore,
  buildSessionCookie,
  createSession,
  generateSessionToken,
  readCookie,
  validateSessionToken,
} from "@chttp/auth";
```

## What it does

- **Sessions (Lucia pattern)** — a 384-bit `id.secret` bearer token, `hashToken` SHA-256 store key (the only thing persisted), `createSession`, `validateSessionToken` with sliding expiry, `invalidateSession`/`invalidateAllUserSessions`. The `SessionStore` contract is sync-or-async — stores may return values or Promises; auth `await`s either way (one microtask on sync stores). `MemorySessionStore` is dev/test only, **not for production**.
- **Cookies** — `serializeCookie`/`readCookie` plus `buildSessionCookie` (HttpOnly, Lax, Secure, Max-Age bound to TTL), `buildExpiredSessionCookie` for logout, `buildCsrfCookie` (not HttpOnly by design — double-submit needs a JS read).
- **Passwords** — `hashPassword`/`verifyPassword` in the self-describing `scrypt:N:r:p:salt:hash` format with OWASP defaults; parameter upgrades don't invalidate old hashes, and verify dummy-hashes on malformed rows to flatten timing.
- **CSRF** — `generateCsrfToken`, `verifyCsrfToken` (constant-time compare), `verifyRequestOrigin` (Origin allowlist) — the two halves of the pattern.
- **JWT** — `signJwt`/`verifyJwt`/`verifyJwtWith`, JWS compact, HS256. Verify is null-on-invalid for every failure and `none` is hard-rejected; `verifyJwtWith` parses claims through any [Standard Schema](https://standardschema.dev) validator (`@chttp/val`, valibot, zod).
- **OAuth2 + PKCE** — `generateState`, `generateCodeVerifier`, `codeChallenge`, `createAuthorizationURL`, `exchangeCodeForTokens` (form POST + basic auth; JSON and form-urlencoded responses both parse), `fetchUserInfo`/`fetchUserInfoWith`. `googleProvider`, `githubProvider`, `discordProvider` presets; a new provider is a 15-LoC record in user code.
- **TOTP** — `generateTotpSecret` (base32, RFC 4648), `totpAuthUri` (otpauth:// enrollment URI), `verifyTotp` (HMAC-SHA1, 6 digits, 30 s step, ±1 window, constant-time).

## Recipe: API keys

No dedicated module is needed — an API key is a session token whose record carries scopes and a far-future expiry. Only the SHA-256 hash is ever stored, so a database leak doesn't leak usable keys.

```ts
import {
  createSession,
  generateSessionToken,
  hashToken,
  invalidateSession,
  validateSessionToken,
} from "@chttp/auth";

// Provisioning: show `apiKey` to the caller exactly once.
const TEN_YEARS = 10 * 365 * 24 * 60 * 60;
const apiKey = generateSessionToken(); // id.secret bearer token (~64 chars)
await createSession(store, apiKey, ownerUserId, { scopes: ["read", "deploy"] }, {
  ttlSeconds: TEN_YEARS,
});

// Per request: "Authorization: Bearer <apiKey>". extensionThresholdSeconds: 0
// keeps the record's expiry fixed — API keys shouldn't slide on every call.
const key = bearer(c.req.header("authorization"));
const rec =
  key === null
    ? null
    : await validateSessionToken(store, key, { extensionThresholdSeconds: 0 });
if (rec === null) return c.status(401).text("unauthorized");
const scopes = rec.attributes.scopes as string[];
if (scopes.indexOf("deploy") < 0) return c.status(403).text("forbidden");

// Revocation is the same as sessions:
await invalidateSession(store, leakedKey);
```

Use `store.get(hashToken(key))` directly instead of `validateSessionToken` when you want to skip the expiry check entirely and manage revocation/rotation yourself; stamp `lastUsedAt` into `rec.attributes` on a throttle if you need audit fields.

## Status

v0.1.0. ES256 is recognized but unlowerable under scriptc 0.3.3 (no asymmetric `node:crypto` lowering): `signJwt` throws `E_BAD_ALG`, `verifyJwt` returns null, and the `string | KeyObject` signature is kept for the upstream drop. JWE, JWKS, EdDSA, WebAuthn and Argon2 are out of scope by design — see the package AGENTS.md and the plan in `.agents/plans/`.


---

## [Benchmarks](https://chttpjs.pages.dev/benchmarks/)

# Benchmarks

Shared VM, compare ratios not absolutes. Full matrix, methodology, ceilings (go-chi / axum / mongoose), and a one-command Docker repro: [bench/RESULTS-v2.md](https://github.com/sigilco/chttp/blob/main/bench/RESULTS-v2.md).

| subject            | json           | pipelined (-c100 -p10) | cold start | RSS after 100k req |
| ------------------ | -------------- | ---------------------- | ---------- | ------------------ |
| chttp on node        | 0.87× raw-node | 0.95×                  | 83 ms      | 116 MB             |
| chttp compiled (ELF) | 1.15× raw-node | 1.76× (204k rps)       | 3 ms       | 4 MB               |
| fastify on node    | 0.69×          | 0.65×                  | 111 ms     | 108 MB             |

The compiled build sits at ≥96% of a bare compiled `node:http` server on every cell: the router costs ~0.1-0.3 MB of binary and ~1 MB RSS.


---

## [Typed client](https://chttpjs.pages.dev/client/)

# Typed client

`@chttp/router/client` ships a typed HTTP client for chttp apps. The same source compiles into your ELF — transport is HTTP/1.1 over `node:net` / `node:tls`, so it runs on Node.js and native with no `fetch` dependency.

```ts
import { createClient } from "@chttp/router/client";

interface Api {} // your app's surface, for future manifest typing

const client = createClient<Api>("http://localhost:3000");

const user = await client.get<{ id: string }>("/users/:id", {
  params: { id: "42" },
});
```

## Calls

`get` / `post` / `put` / `patch` / `delete` take a path and an optional input:

```ts
interface ClientInput<P> {
  params?: Record<ParamKey<P>, string>; // '/users/:id' -> { id: string }
  query?: Record<string, string>;
  body?: unknown; // string -> text/plain, else JSON.stringify
  headers?: Record<string, string>;
}
```

- `:param` segments and `*` wildcards are substituted from `params` (URI-encoded). Missing params throw before the wire.
- `query` pairs are appended URI-encoded.
- Return type is caller-declared: `client.get<User>(...)`. JSON responses (by `content-type`) are parsed; everything else resolves to the body string.
- `client.request(method, path, input)` returns `{ status, headers, body }` for full control.

`createClient(baseUrl, opts?)` accepts `{ timeoutMs?, headers? }`; base URLs may include a port and path prefix. `https:` URLs use `node:tls` with certificate verification on.

v1 scope: one request per connection (`Connection: close`), no redirects, no streaming bodies. `Transfer-Encoding: chunked` responses are decoded.

## Compiling to ELF

The typed signatures are a `.d.ts` surface — scriptc dispatches generic methods only through the concrete class. In app code that compiles to native, bind the receiver as `ClientCore`:

```ts
import { createClient } from "@chttp/router/client";
import type { ClientCore } from "@chttp/router/client";

const client: ClientCore = createClient("http://127.0.0.1:3000");
const user = await client.get<{ id: string }>("/users/:id", { params: { id: "42" } });
```

`params` then types as `Record<string, string>` — path keys aren't checked inside the compiled subset. The non-generic `request` works through either receiver.

Coverage is gated by `bench/apps/chttp-client.ts` (100% static) and the loopback ELF smoke in `packages/router/test/elf.test.sh`.


---

## [Context](https://chttpjs.pages.dev/context/)

# Context

Handlers and middleware receive `c`. Request access is synchronous: the body is pre-buffered, so `c.req` never awaits.

## Request

```ts
c.req.param("id"); // string | null, percent-decoded
c.req.query("q"); // string | null
c.req.queries("tag"); // string[], all values for a repeated key
c.req.queryAll(); // Record<string, string>
c.req.header("x-foo");
c.req.body(); // string
c.req.file("f"); // UploadedFile | null — multipart routes only
c.req.field("f"); // string | null — multipart routes only
c.req.method;
c.req.path;
c.req.raw;
```

## Response

Helpers write at statement level and return `c` for chaining. After one runs, the response is sent, so set headers first.

```ts
c.json({ ok: true });
c.text("plain");
c.html("<h1>hi</h1>");
c.bytes(new Uint8Array([0xff, 0xd8]), "image/jpeg"); // binary body
c.status(201).json({ created: true });
c.header("x-trace", "abc");
c.redirect("/elsewhere", 302);
```

Next: [Errors](errors.md). Request bodies and the `{ body: true }` flag: [Middleware](middleware.md).


---

## [Deploy](https://chttpjs.pages.dev/deploy/)

# Deploy

Pick one of three ways to ship a chttp app.

| Option                  | Ships                       | Image or artifact | Cold start |
| ----------------------- | --------------------------- | ----------------- | ---------- |
| Docker (`FROM scratch`) | one static binary           | ~2.4 MB           | unverified |
| Binary only             | one static binary           | ~2.4–2.6 MB       | unverified |
| Node                    | your JS plus `node_modules` | node runtime      | 83 ms      |

Binary sizes measured on macOS arm64 with router 0.3.0 and scriptc 0.3.4: the `examples/hello` app builds to 2,558,232 B, or 2,407,680 B with `--strip` (RSS ~3 MB). The `chttp-scriptc` bench cell ([`bench/RESULTS-v2.md`](../bench/RESULTS-v2.md)) measured a 3 ms median cold start for its own app, but per-app cold start was not re-measured for this release — treat it as unverified until the cell is re-run.

## Docker

Copy [`examples/deploy-docker/Dockerfile`](https://github.com/sigilco/chttp/blob/main/examples/deploy-docker/Dockerfile) next to your app. It builds the binary in an alpine stage and copies it into `scratch`.

```sh
docker build -t my-app .
docker run --rm -p 8080:8080 my-app
```

The image has no shell, so debug with a different base if you need one.

## Binary only

Build, copy the file, run it. No runtime needed on the host.

```sh
scriptc build src/main.ts -o app --strip
./app
```

scriptc cannot cross-compile (no `--target`), so build on the OS and architecture you deploy to. For a linux server, build in CI on linux or inside an alpine container. An alpine build is fully static (musl), so it runs on any linux of the same architecture.

## Node

No build step. Deploy the JS like any node service:

```sh
node app.js
```

Use this when you need npm packages outside the scriptc subset. See [Run targets](targets.md).

## Web Standards adapter

The canonical entry is `app.fetch(req: Request) → Promise<Response>`. The same `createRouter()` symbol works on Cloudflare Workers, Deno Deploy, Bun, Vercel Edge, Netlify Edge, Supabase, and as a Service Worker. `app.handler()` is a thin Node adapter around `fetch()` for `node:http` users.

```ts
import { CtxCore, createRouter } from "@chttp/router";

const app = createRouter();
app.get("/user/:id", (c: CtxCore) => c.json({ id: c.req.param("id") }));

// Cloudflare Workers / Deno Deploy / Bun / Vercel Edge / Service Worker
export default {
  async fetch(req: Request, env: unknown, ctx: unknown): Promise<Response> {
    return app.fetch(req, env, ctx);
  },
};
```

The Node `app.handler()` surface compiles to a native ELF via `scriptc build`. `app.fetch` itself is JS-runtime-only today — `new Request` is not constructible inside the binary under scriptc 0.3.x — but the fetch dispatch path is ELF-verified through the [`app.fetchShim`](targets.md#native-elf) host-shim entry (the `chttp-fetch` gate stays at 100% static coverage). Recipes for the two most common targets:

- [`examples/integrations/cloudflare-workers/`](../examples/integrations/cloudflare-workers/) — `wrangler dev` / `wrangler deploy`, `app.fetch` as the Workerd fetch handler. Needs `nodejs_compat` + `enable_nodejs_fs_module` compat flags (the router statically imports `node:http` and `node:fs`); verified by a real-workerd smoke in the recipe's test suite.
- [`examples/integrations/aws-lambda/`](../examples/integrations/aws-lambda/) — APIGW v2 / Lambda URL bridge (`provided.al2023` ELF or Node runtime).


---

## [Errors](https://chttpjs.pages.dev/errors/)

# Errors

```ts
app.onError((err, c) => {
  c.status(500).json({ message: err.message });
});
```

An error thrown anywhere in the chain (middleware, handler, response) lands here.

Fallback behavior:

- No `onError` registered, or the handler never responds, or the handler itself throws: built-in `500 Internal Server Error`.
- Headers already sent: socket destroy.

The built-in `405` error carries `.allow` (the `Allow` header value), so custom bodies are easy:

```ts
app.onError((err, c) => {
  if ("allow" in err) {
    c.status(405).header("allow", err.allow).text("method not allowed");
    return;
  }
  c.status(500).text("boom");
});
```


---

## [Examples](https://chttpjs.pages.dev/examples/)

# Examples

Standalone templates in [`examples/`](https://github.com/sigilco/chttp/tree/main/examples). Each is a normal project: copy the folder, install, build.

| Template                                                                                  | Shows                                                                                   |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [`hello`](https://github.com/sigilco/chttp/tree/main/examples/hello)                      | Static, param and wildcard GET routes                                                   |
| [`middleware`](https://github.com/sigilco/chttp/tree/main/examples/middleware)            | `app.use` global and per-route middleware                                               |
| [`json-api`](https://github.com/sigilco/chttp/tree/main/examples/json-api)                | POST body, `onError`, `notFound`                                                        |
| [`router-mount`](https://github.com/sigilco/chttp/tree/main/examples/router-mount)        | `app.route` sub-router mounting                                                         |
| [`sse-clock`](https://github.com/sigilco/chttp/tree/main/examples/sse-clock)              | Server-sent events, see [Streaming](streaming.md)                                       |
| [`ws-echo`](https://github.com/sigilco/chttp/tree/main/examples/ws-echo)                  | `@chttp/ws` echo and room, see [WebSocket](websocket.md)                                |
| [`vite-elf`](https://github.com/sigilco/chttp/tree/main/examples/vite-elf)                | Vite with `unplugin-scriptc`                                                            |
| [`vite-lowering`](https://github.com/sigilco/chttp/tree/main/examples/vite-lowering)      | Build-time route lowering, see [Route lowering plugin](unplugin.md)                     |
| [`deploy-docker`](https://github.com/sigilco/chttp/tree/main/examples/deploy-docker)      | Scratch image, see [Deploy](deploy.md)                                                  |
| [`csr-react`](https://github.com/sigilco/chttp/tree/main/examples/integrations/csr-react) | React SPA on `@chttp/static`, baked-assets single binary, see [Static files](static.md) |

```sh
cd examples/hello
pnpm install
pnpm build   # scriptc build src/main.ts -o app
./app        # ELF listening on :3000
```

Full index: [examples/README.md](https://github.com/sigilco/chttp/blob/main/examples/README.md).


---

## [HTML rendering](https://chttpjs.pages.dev/html/)

# HTML rendering

`@chttp/html` renders HTML strings inside the scriptc compilable subset, so server side rendering works in a compiled chttp binary. It is independent of `@chttp/router`: it only produces strings you hand to `c.html(...)`. Names follow [kitajs/html](https://github.com/kitajs/html) where the subset allows; the audit is in `.agents/notes/2026-10-14-kitajs-api-audit.md`.

## API

| Export                                           | Signature                                                          | Notes                                                                                        |
| ------------------------------------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| `escapeHtml`                                     | `(s: string) => string`                                            | Escapes `& < " '` to `&amp; &lt; &#34; &#39;`, same bytes as kitajs. Charcode loop, no regex |
| `h`                                              | `(tag: string, attrs: string[], kids: string[]) => string`         | `attrs` is a flat `[name, value, ...]` array. Void elements self close                       |
| `createElement`                                  | `(name: string, attrs: string[], ...children: string[]) => string` | kitajs shaped alias of `h`                                                                   |
| `Fragment`                                       | `(kids: string[]) => string`                                       | Siblings without a wrapper                                                                   |
| `html`                                           | tagged template                                                    | Escapes interpolations, static text is trusted markup                                        |
| `raw`                                            | tagged template                                                    | No escaping, for composing already rendered markup                                           |
| `BARE`                                           | `string`                                                           | Attribute value sentinel for bare boolean attributes                                         |
| `isVoidElement`, `isValidTag`, `isValidAttrName` | `(s: string) => boolean`                                           | Exposed helpers                                                                              |

```ts
import { CtxCore } from "@chttp/router";
import { BARE, escapeHtml, h, html } from "@chttp/html";

function Todo(props: { text: string; done: boolean }): string {
  return h("li", ["class", props.done ? "done" : "open"], [escapeHtml(props.text)]);
}

app.get("/todos", (c: CtxCore) =>
  c.html(
    h("ul", [], [Todo({ text: "<b>ship</b>", done: false })]) +
      h("input", ["disabled", BARE, "value", "x"], []),
  ),
);
```

## Escaping model

Like kitajs, children are pre-rendered markup and are not escaped by `h`: a string child cannot be told apart from a nested element. Escape text yourself with `escapeHtml`, or write it with the `html` tag, which escapes every interpolation. A `safe` attribute pair escapes the joined children once (`h("p", ["safe", "true"], [userText])`) and is not emitted. Attribute values are always escaped. Tag and attribute names are validated and an invalid name throws, so a user controlled key cannot inject an attribute.

Differences from kitajs on purpose: the `html` tag escapes only interpolations (kitajs `escape` escapes the whole string, static text included), attribute values escape `&`, `<`, `"` and `'` (kitajs escapes only `"`), and there are no attribute objects, async children, or function typed element names.

## Escaping footguns

> **Warning:** `@chttp/html` is not auto escaping. Anything you pass as a string child is emitted as markup.
>
> - `h("p", [], [userText])` writes `userText` verbatim, so `<script>` in it executes. Wrap untrusted text in `escapeHtml(...)`, use the `html` tag, or add the `safe` attribute pair.
> - `safe` escapes all joined children, including nested elements you rendered with `h`, so do not mix trusted markup and `safe` in one parent.
> - Attribute escaping is not URL validation. `h("a", ["href", userUrl], [...])` happily emits `href="javascript:alert(1)"`. Check the scheme (allow `http:`, `https:`, `mailto:` or relative) before building the element.
> - `html` escapes interpolations only. Static template text and everything passed through `raw` are trusted. Interpolating the output of another `html` call escapes it a second time, so compose rendered fragments with `h`, `Fragment` or `raw`.
> - `escapeHtml` is not idempotent: `escapeHtml(escapeHtml("<"))` is `&amp;lt;`. Escape once, at the point you build the element.
> - `escapeHtml` is only correct for text nodes and quoted attribute values. It does nothing for unquoted attributes (always quoted here), `<script>` or `<style>` bodies, inline event handlers, or CSS and URL contexts.
> - The `BARE` sentinel is the single character `\u0000`. An untrusted value equal to it turns a valued attribute into a bare one.

Tag and attribute names are validated and throw, so they cannot be used for injection, but they are not escaped: never derive them from a lookup that can return an unvalidated string you intended as a value. These behaviors are pinned by the `footgun:` tests in `packages/html/test/html.test.js`.

## Namespace form

`import * as Html from "@chttp/html"` gives kitajs style call sites (`Html.escapeHtml`, `Html.createElement`, `Html.Fragment`). It lowers like `import * as v from "@chttp/val"`. A namespace object of functions would be a function-in-record, which the subset bans, so there is no default export.

## JSX in dev and tests

`@chttp/html/jsx-runtime` (and `jsx-dev-runtime`) export `jsx`, `jsxs`, `Fragment` and a `JSX` namespace so `"jsx": "react-jsx"` with `"jsxImportSource": "@chttp/html"` works under Node. Output is produced by `h()`, so it is byte identical to the same tree written with `h`. JSX props map to attrs (`className` to `class`, `true` to a bare attribute, `false`, `null` and `undefined` skipped, `safe` honoured). This runtime is not in the subset and must never be imported by code that compiles to the ELF. Production builds will lower `.tsx` to plain `h`/`html` calls at build time (planned unplugin `jsx` slice).

## Pages, SSG and ISR

`@chttp/html` also ships the page-level surface of issue #14's slice: a document
shell and a revalidate cache. Components stay plain `(props) => string`
functions; there is no component class, virtual DOM, or client runtime.

| Export               | Signature                                                      | Notes                                                                                      |
| -------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `page`               | `(head: string, body: string) => string`                       | Full document: `<!doctype html>` + `<html><head>` + `<body>`. Args are markup, not escaped |
| `IsrPage`            | `new IsrPage(render: () => string, revalidateSeconds: number)` | Caches `render()` output; re-renders on the first `html()` read after the window elapses   |
| `IsrPage.html`       | `() => string`                                                 | The cached document                                                                        |
| `IsrPage.freshUntil` | `() => number`                                                 | Epoch ms of the next re-render instant                                                     |

**SSG** needs no API: call your component once at startup and serve the baked
string from a route. **ISR** wraps a render function in `IsrPage` — revalidation
is synchronous (Next.js blocking-fallback semantics); the reader that hits an
expired window pays the render. There is no background refresh inside the
subset. See `examples/pages` for a working app.

```ts
const index = Layout("posts", PostList(POSTS)); // once — SSG
app.get("/", (c) => c.html(index));

const post = new IsrPage(() => Layout("post", PostCard(loadPost())), 60); // ISR
app.get("/post", (c) => c.html(post.html()));
```

This is a slice, not a framework: no per-request data loading, nested layouts,
streaming, islands/hydration, or build-time prerender yet — see issue #14 for
the remaining surface.

## Compile gate

`scriptc coverage bench/apps/chttp-html.ts` must report 100% static. `pnpm --filter @chttp/html test` runs the unit tests, the XSS payload cases, and the jsx-runtime equivalence test.


---

## [What is chttp](https://chttpjs.pages.dev/)

# What is chttp

chttp is a minimal async-first HTTP router for `node:http`, authored inside the [scriptc](https://github.com/vercel-labs/scriptc) compilable subset so the same source also compiles to a single native ELF.

```ts
import { CtxCore, createRouter } from "@chttp/router";

const app = createRouter();
app.get("/user/:id", async (c: CtxCore) => c.json(await fetchUser(c.req.param("id"))));
app.serve({ port: 3000 });
```

## Why it exists

- Small: zero runtime dependencies, one core file.
- Async-first: handlers and middleware may return a `Promise`. Sync handlers still finish without scheduling a microtask.
- Two targets, one source: run on node, or compile to a ~1 MB native binary with a 3 ms cold start.

## Mental model

- An `App` holds a route trie. Routes are registered per method and path.
- A request is matched, then runs a chain: middleware, then one handler.
- Handlers write through `c` (`c.json`, `c.text`, `c.html`, `c.redirect`), which sets status, headers and ends the response.
- Any throw or rejection in the chain lands in `app.onError`.
- Request access is synchronous: the body is pre-buffered, so `c.req.body()` never awaits.

## Node or native

|                    | node      | native ELF          |
| ------------------ | --------- | ------------------- |
| Build step         | none      | `scriptc build`     |
| Cold start         | 83 ms     | 3 ms                |
| RSS after 100k req | 116 MB    | 4 MB                |
| npm ecosystem      | all of it | scriptc subset only |

Pick node for the ecosystem, native for small images and fast starts. Numbers and method: [Benchmarks](benchmarks.md).

Utility packages for chttp apps — including when compiled to a native ELF — live in [sigilco/cutils](https://github.com/sigilco/cutils): `@cutils/sqlite` (embedded SQLite over a C FFI shim) and `@chttp/cache` (LRU/TTL in-memory cache). `@chttp/mcp` (JSON-RPC 2.0 MCP server) and `@chttp/auth` (session/JWT/OAuth/CSRF/TOTP primitives) live in this repo — see [MCP server](mcp.md) and [Auth primitives](auth.md).

Next: [Quickstart](quickstart.md).


---

## ['@chttp/mcp](https://chttpjs.pages.dev/mcp/)

# @chttp/mcp

Model Context Protocol server (JSON-RPC 2.0, spec revision 2025-06-18) authored in the scriptc-compilable subset — the same source builds to a JS package with `tsc` and lowers into a native ELF with `scriptc build`. Zero runtime dependencies.

```ts
import { Server, StreamableHttpTransport, tool } from "@chttp/mcp";
import * as v from "@chttp/val";

const server = new Server({
  name: "my-server",
  version: "0.1.0",
  emitJsonSchema: (s) => v.toJsonSchema(s),
});

tool(server, "add", v.object({ a: v.number(), b: v.number() }), async (i) =>
  String(i.a + i.b),
);

export default { fetch: StreamableHttpTransport.route(server) };
```

## What it does

- `Server` — `tool`/`resource`/`prompt` registration plus `handleRequest(JsonRpcRequest)` covering the full MCP method table (`initialize`, `ping`, `tools/list`, `tools/call`, `resources/*`, `prompts/*`, `notifications/*`, `logging/setLevel`, `completion/complete`).
- Two injected seams: validation runs through `schema["~standard"].validate` (any [Standard Schema](https://standardschema.dev) validator — `@chttp/val`, valibot, zod); JSON Schema emission is an adapter you pass (`emitJsonSchema`), so no schema code ships in the package.
- Auto-wrap ladder for tool returns: strings become text blocks, plain objects become dual `content` + `structuredContent`, a full `CallToolResult` passes through, thrown errors become `isError` results.
- `StreamableHttpTransport` — POST JSON-RPC plus an SSE stream (`GET ?stream=progress`) carrying `notifications/progress`/`notifications/message` while tools run.
- Progress + log notifications through a server-level sink registry (`ctx.progress`, `ctx.log`, `logging/setLevel` severity filter).
- `@chttp/mcp/client` — typed client on a `./client` subpath: `Client` + `toolDef`/`resourceDef`/`promptDef` schema-first descriptors (the same `ToolDef` registers on `server.toolDef`), three transports (`fetch`, `node:net`/`node:tls` HTTP/1.1+SSE for the ELF path, stdio), `callTool`/`call`/`listTools`/`readResource`/`getPrompt`, progress notification handlers, `JsonRpcError` passthrough.

## Docs

Per-package pages live under [`packages/mcp/docs/`](https://github.com/sigilco/chttp/tree/main/packages/mcp/docs): integration, schema seams, transports, the client, Streamable-HTTP coverage (what v1 does and deliberately skips), the auto-wrap ladder, and scriptc-subset authoring notes. Examples: [`packages/mcp/examples/todo-mcp`](https://github.com/sigilco/chttp/tree/main/packages/mcp/examples/todo-mcp) and [`examples/integrations/mcp-stdio`](https://github.com/sigilco/chttp/tree/main/examples/integrations/mcp-stdio).

## Status

v0.1.0. Covers spec revision 2025-06-18 for tools/resources/prompts + streamable-HTTP POST/SSE. Sessions, resumability, batching, roots/sampling/elicitation, and a packaged stdio transport are out of scope by design — see `docs/streamable-http-coverage.md`.


---

## [Middleware](https://chttpjs.pages.dev/middleware/)

# Middleware

Middleware is `(c, next) => void | Promise<void>` — sync or async. `next()` returns the tail's result, so `await next()` in an async middleware waits for the rest of the chain to settle.

```ts
app.use((c: CtxCore, next) => {
  c.header("x-start", Date.now().toString());
  next();
});
```

Middleware applies to routes registered **after** it (snapshot semantics): `use()` copies the current middleware stack onto every subsequently registered handler, so registration order is the middleware order. This matters for every recipe below: register the middleware first, routes after.

One flush rule all recipes rely on: the response helpers (`c.json`, `c.text`, `c.html`, `c.redirect`) call `res.end()` synchronously. Once the handler calls one, the response is gone; headers set *after* `next()` returns will not land on it. Set headers *before* `next()`, or log instead of decorating when you need post-handler information (see [request logging](#request-logging) and [timing](#timing-header)).

## Body

`c.req.body()` is synchronous because dispatch pre-buffers the request body (`data`/`end` concat) for POST/PUT/PATCH/DELETE before invoking the chain — on routes that declared `{ body: true }`. Other methods dispatch immediately.

## Recipe cookbook

Every snippet below is written in the scriptc subset (indexed `for` loops, `| null` unions, no shorthand or spread or optional chaining, plain records instead of `Map`) and was verified to build and run as an ELF with `scriptc build` (chttp 0.1.0). Node-only recipes are marked.

### CORS

Two pieces, because of how dispatch orders things: an `OPTIONS` request to a path that only has `GET`/`POST` registered fails with 405 *before any middleware runs*, so a middleware alone cannot answer preflight. The working shape is a `use()` middleware for the response headers plus one explicit `app.options()` route per path (or `app.all()` with an in-handler method check) that answers the preflight with 204.

```ts
import type { CtxCore } from "@chttp/router";

// 1. Response headers on every actual request (apply to routes after this use()).
app.use((c: CtxCore, next: () => unknown): unknown => {
  c.header("access-control-allow-origin", "*");
  return next();
});

// 2. Explicit preflight answer: 204, no body.
function preflight(c: CtxCore): void {
  c.status(204)
    .header("access-control-allow-origin", "*")
    .header("access-control-allow-methods", "GET,POST,PUT,DELETE,OPTIONS")
    .header("access-control-allow-headers", "content-type,authorization")
    .header("access-control-max-age", "86400");
  const rs = c.res.nodeRes(); // raw ServerResponse (Node surface only)
  if (rs !== null) {
    rs.end();
  }
  c.sent = true; // tells dispatch this middleware answered
}

app.options("/users", (c: CtxCore) => {
  preflight(c);
});
app.get("/users", (c: CtxCore) => c.json({ users: 1 }));
app.post("/users", (c: CtxCore) => c.json({ ok: true }), { body: true });
```

With credentials instead of `*`: echo the request's `origin` header and add `access-control-allow-credentials: true`. For many paths, a shared `app.all("/*", ...)` fallback also answers preflight (a splat route matches paths with no other registration), but paths that have any method registered need their own `app.options()` entry or the 405 wins.

### ETag / If-None-Match (304)

Strong etag from a simple hash of the exact body string. The hash below is FNV-1a 32-bit implemented inline: no `node:crypto` dependency, deterministic across processes, and honest about collision odds (32 bits, fine for cache revalidation of modest APIs; use `node:crypto` `createHash` if you want more, it does lower and run under scriptc). Note the etag must be computed over the same bytes you send, so the handler serializes once and writes the response itself instead of `c.json`.

```ts
function fnv1a(s: string): string {
  let h: number = 0x811c9dc5;
  for (let i = 0; i < s.length; i++) {
    h = h ^ s.charCodeAt(i);
    h = (h * 16777619) >>> 0; // keep it unsigned 32-bit
  }
  return h.toString(16);
}

app.get("/users", (c: CtxCore) => {
  const body: string = JSON.stringify({ users: [1, 2] });
  const etag: string = '"' + fnv1a(body) + '"';
  const inm: string | null = c.req.header("if-none-match");
  if (inm !== null && inm === etag) {
    c.status(304);
    const rs = c.res.nodeRes(); // raw ServerResponse (Node surface only)
    if (rs !== null) {
      rs.end();
    }
    c.sent = true;
    return;
  }
  c.header("etag", etag);
  const rs = c.res.nodeRes();
  if (rs !== null) {
    rs.setHeader("content-type", "application/json; charset=utf-8");
    rs.end(body);
  }
  c.sent = true;
});
```

The comparison is exact equality against a single etag. Browsers may send a comma-separated list or a `W/` weak prefix; if you need those, split `inm` on `,` and trim before comparing.

### Request logging

Async middleware: `await next()` waits until the chain settles, so `Date.now()` after it includes the handler's async work. Duration goes to stdout, not a response header, because the response may already be flushed (the flush rule above).

```ts
app.use(async (c: CtxCore, next: () => unknown): Promise<void> => {
  const t0: number = Date.now();
  await next();
  console.log(c.req.method + " " + c.req.path + " " + String(Date.now() - t0) + "ms");
});
```

Register it before the routes you want logged; routes registered earlier carry no middleware (snapshot semantics).

### Security headers

Sync middleware that sets headers before `next()`; they land on every response from routes registered after it.

```ts
app.use((c: CtxCore, next: () => unknown): unknown => {
  c.header("x-content-type-options", "nosniff");
  c.header("x-frame-options", "DENY");
  c.header("referrer-policy", "no-referrer");
  c.header("content-security-policy", "default-src 'none'");
  return next();
});
```

For a `strict-transport-security` header that only applies over TLS, put it behind your TLS terminator or set it conditionally on your platform's TLS flag; the ELF itself serves plain HTTP.

### Rate limiting (in-memory fixed window)

Plain record of buckets keyed by API key or client IP, fixed window: no `Map`, no cleanup job, counters reset when the window expires. Single-instance only: state lives in the process, so multiple replicas each get their own full budget. For shared state you need a store the subset can call.

```ts
interface Bucket {
  count: number;
  reset: number;
}

const LIMIT: number = 100;      // requests per window
const WINDOW_MS: number = 60000; // window length

const buckets: { [k: string]: Bucket } = {};

function rateLimit(c: CtxCore, next: () => unknown): unknown {
  const key: string = c.req.header("x-api-key") === null ? "anon" : String(c.req.header("x-api-key"));
  const now: number = Date.now();
  const cur: Bucket | null = buckets[key] === undefined ? null : buckets[key];
  if (cur === null || now >= cur.reset) {
    buckets[key] = { count: 1, reset: now + WINDOW_MS };
  } else {
    cur.count = cur.count + 1;
  }
  const b: Bucket = buckets[key];
  c.header("x-ratelimit-limit", String(LIMIT));
  c.header("x-ratelimit-remaining", String(LIMIT - b.count < 0 ? 0 : LIMIT - b.count));
  if (b.count > LIMIT) {
    c.header("retry-after", String(Math.ceil((b.reset - now) / 1000)));
    return c.status(429).json({ error: "rate_limited" });
  }
  return next();
}

app.use(rateLimit);
```

Fixed windows burst at the seam (up to 2×LIMIT across a boundary). Sliding windows need sorted timestamps per key, which the subset can do with number arrays if you need it.

### Serve static

Do not hand-roll a static handler: reading files as utf8 corrupts binaries, and the traversal, caching and `index.html` details are easy to get wrong. Use [`@chttp/static`](static.md), which serves bytes through `c.bytes()`, handles ETag/304, HEAD, precompressed siblings and an opt-in SPA fallback, and compiles into the ELF.

If you do need a hand-rolled variant (single small asset set, no package), know the traversal pitfall before you start: `c.req.param("*")` is the *decoded* path tail, so `%2e%2e` arrives as `..` before your code sees it, so guard on the decoded value, reject any tail containing `..` or a leading `/`, and write the response manually through `c.res.nodeRes()` (the raw `ServerResponse`, null on the `app.fetch` surface) with `rs.setHeader` + `rs.end()`, because `c.text()` forces its own `content-type`.

### Timing header

A true `server-timing: app;dur=N` header needs the duration *before* the body is written, but sync handlers flush the response inside `next()` (the flush rule), so the duration is only knowable after it is too late to send it. What works, verified: stamp a start time before `next()` (the header lands on every response), and log the duration after `await next()` in an async middleware.

```ts
// start stamp: header lands (set before the handler can flush)
app.use((c: CtxCore, next: () => unknown): unknown => {
  c.header("x-request-start", String(Date.now()));
  return next();
});

// duration: log it, the response is already flushed by the time you know it
app.use(async (c: CtxCore, next: () => unknown): Promise<void> => {
  const t0: number = Date.now();
  await next();
  console.log(c.req.path + " " + String(Date.now() - t0) + "ms");
});
```

Clients that understand `x-request-start` (or a tracing proxy reading it) can compute end-to-end duration from the timestamp. If you control the handlers, the alternative is sending the header from the handler itself, where the duration is known before the send.


---

## [Multipart](https://chttpjs.pages.dev/multipart/)

# Multipart

`multipart/form-data` uploads are opt-in per route — the same seam as `{ body: true }`. Declare `multipart` in the route options and dispatch parses the stream before the handler chain runs, so `c.req` stays synchronous.

```ts
import { CtxCore, createRouter, diskStorage, memoryStorage } from "@chttp/router";

const app = createRouter();

app.post(
  "/api/entries/:entryId/media",
  (c: CtxCore) => {
    const file = c.req.file("file"); // UploadedFile | null
    const title = c.req.field("title"); // string | null
    db.run([file!.path, file!.mimeType, file!.size, title]);
    return c.json({ ok: true });
  },
  { multipart: { storage: diskStorage(MEDIA_DIR) } },
);
```

## Reading uploads

`file`/`field` are last-wins; `files`/`fields` return every part under the name.

```ts
c.req.file("avatar"); // UploadedFile | null
c.req.files("f[]"); // UploadedFile[]
c.req.field("title"); // string | null
c.req.fields("tag"); // string[]
```

`UploadedFile`:

```ts
{
  field: string; // form field name
  filename: string; // basename-sanitized
  mimeType: string;
  size: number; // bytes written
  bytes: Uint8Array | null; // memoryStorage
  path: string | null; // diskStorage (temp file the caller owns)
}
```

## Storage

```ts
memoryStorage(); // default — buffers into UploadedFile.bytes
diskStorage(dir); // streams to dir/chttp-<ts>-<rand>-<n>, returns path
```

`diskStorage` creates `dir` recursively and never overwrites — temp names carry a timestamp, random hex, and a counter. On any parse failure the partial temp file is closed and unlinked. The finished file is the caller's responsibility (move it, keep it, or delete it).

## Limits

Enforced during the streaming parse — a breach answers `413` mid-upload, destroys the socket, and unlinks the partial temp file. No file is held twice, no body is re-buffered.

```ts
app.post("/up", handler, {
  multipart: {
    maxFileBytes: 100 * 1024 * 1024, // per file, default unlimited
    maxFiles: 16, // parts with a filename, default unlimited
    maxFieldBytes: 64 * 1024, // per text field, default unlimited
  },
});
```

Non-`multipart/form-data` content, a missing boundary, or a truncated body answers `400` before the handler runs. `body` and `multipart` in the same route options throw at registration — multipart owns the body.

Routes without the declaration are untouched: the stream is not consumed. The [unplugin](unplugin.md) declines declared-multipart routes at build time with a warning — they stay on internal dispatch, which is what parses them.


---

## [Native FFI](https://chttpjs.pages.dev/native/)

# Native FFI

How a compiled chttp app calls C code, and why this lives in docs instead of a package.

## Why docs, not a package

Outbound FFI in scriptc is build-time plumbing, not a runtime API: a `declare function` in your source plus a JSON manifest passed to `scriptc build`. There is nothing a `@chttp/*` package could wrap that the toolchain does not already do, so chttp documents the pattern and ships a worked example (`examples/ws-echo`) rather than an abstraction.

## N-API is unavailable in ELFs

Under Node, native code usually arrives as a Node-API addon. That path is closed in a compiled binary — the scriptc docs put it plainly: "Compiled programs can't load Node-API (`.node`) addons, because those depend on Node.js itself." Renaming a `.node` file or linking an archive that still calls `napi_*` does not remove the dependency; move the operation into a plain C function and call it through FFI.

## Two runtimes, two FFI styles

| | Node.js | Native ELF (`scriptc build`) |
| --- | --- | --- |
| Mechanism | `koffi`, `node:ffi` (Node 22+), napi-rs addons | `scriptc build --ffi <manifest>` |
| Declaration | Runtime FFI object | `declare function` at module scope |
| Linking | Shared library loaded at runtime | Object/archive linked into the binary |

Same C function, different plumbing. A project targeting both keeps the C code shared and swaps the binding layer.

## Manifest and declaration

The manifest describes the C signature; the declaration gives TypeScript its types. TypeScript only has `number`, so the manifest decides the actual C width:

```ts
declare function nativeScale(value: number, factor: number): number;
```

```json
{
  "ffi_format": 1,
  "functions": [
    {
      "name": "nativeScale",
      "symbol": "native_scale",
      "params": ["f64", "f64"],
      "returns": "f64"
    }
  ],
  "libraries": ["./libnative.a"]
}
```

```sh
scriptc build main.ts --ffi ffi.json -o app
```

Pass the same manifest to `scriptc coverage` so the native calls count as compiled.

## ABI classes

`ffi_format` selects the available classes:

- Formats 1–5: `f64`, `bool`, `u8`, `u32`, `i32` (all `number`), `cstring`/`string`/`bytes` (callback input only), `void`.
- Format 6 adds `f32`, `i8`/`u16`/`i16`, and `mutable-bytes` — a writable borrow of a `Uint8Array`/`Buffer` view; in-place writes are visible through the original array.
- Format 7 adds `i64`, `u64`, `pointer` (`bigint` in TypeScript).

`string`/`bytes` pointers are borrowed for the call duration; native code must not mutate, free, or retain them. String and byte returns are unsupported — they need an ownership contract. Format 7 can return an opaque pointer as a `bigint`; scriptc does not infer its lifetime.

## Callbacks and threads

C APIs that take a function pointer map to a callback descriptor (`"callback"`) in the manifest, with an optional `void *` context entry the compiler supplies:

- `lifetime: "call"` (format 2) — call-scoped; valid only for the duration of the FFI call. No userdata parameter is needed for plain callbacks — scriptc installs the closure in a binding-specific thread-local slot.
- `lifetime: "retained"` (format 4) — same-thread native APIs that store the callback and invoke it later; pair registration with a release binding.
- `invoke: "foreign"` (format 5) — a native thread invokes the closure; delivery is queued onto the JavaScript event loop, so the closure always runs on the main thread.

Foreign-thread delivery is the same trick the router uses internally: `settleChain` in `packages/router/src/index.ts` settles a chain result by `await`ing it inside a scheduled task rather than on the caller's stack. FFI format 5 gives you the same guarantee for C-side threads — the callback fires on the event loop, never re-entrantly inside native code.

## Bridging Node and ELF

Format 7 emits `node:ffi` static bindings: the same manifest and `declare function` shape runs against Node's built-in FFI, so one C library can serve both the Node entrypoint and the compiled ELF without a second binding layer.

## Constraints

- Outbound FFI is an executable feature. Quoting the scriptc docs: "Outbound FFI is currently available for executable builds, not `scriptc build --lib`."
- Build the object/archive for the same target as the scriptc binary. `cc -c` is the portable baseline (`ar rcs` for an archive); `zig cc` works when you need cross-compilation, but adds a toolchain dependency.
- Compiled ELFs can still reach system libraries via `system_libraries` in the manifest.

## Common Node native modules

The question behind most FFI work: "can my compiled app use what npm packages use?" Sort the ecosystem by where the native code lives:

| Module style | Examples | Compiled ELF? |
| --- | --- | --- |
| N-API `.node` addon | `sqlite3`, `better-sqlite3`, `bcrypt`, `sharp`, `argon2` | No — addons depend on Node.js itself. But their C/C++ cores usually can be rebound via `--ffi` with a thin shim. |
| Node builtin | `node:sqlite`, `node:crypto` | Refused by the compiler unless scriptc ships its own lowering (`node:sqlite` is refused; crypto/fs/http are already lowered). |
| Pure-JS package | most of npm | Compiles only if the source stays inside the scriptc subset — real packages rarely do. |
| System C library | `libsqlite3`, `libz`, `libcurl`, OpenSSL | Yes — `libraries`/`system_libraries` link it directly. |

The pattern that works is the one the docs describe for replacing a Node-API addon: keep using the addon's underlying C library, but call it through a fixed-signature shim. Verified with libsqlite3: a 30-line shim (`shim_open`/`shim_exec`/`shim_count`) compiled with `cc -c`, linked via `"libraries": ["./shim.o", "/usr/lib/x86_64-linux-gnu/libsqlite3.a"]` and `"system_libraries": ["pthread", "dl", "m"]`, runs `CREATE TABLE`/`INSERT`/`SELECT count(*)` from a compiled ELF — `i64` results arrive as `bigint` (format 7).

What this means per package:

- **sqlite3 / better-sqlite3** — drop the addon, bind `libsqlite3` through a shim exposing the few calls you need (open/exec/prepare/step). The async and prepared-statement ergonomics live in the shim, not in scriptc.
- **bcrypt / argon2** — same shape: the C core (`crypt_blowfish`, libargon2) links fine; write `hash(password, salt)` / `verify` entry points in the shim.
- **sharp / canvas** — libvips/cairo are linkable C libraries, but expect a real port: these APIs are wide, and the shim becomes a project of its own.
- **Anything pure-JS with native fallback** — try the JS path first; fall back to `--ffi` only where the subset refuses.

Keep the shim minimal and stateless where you can: every fixed signature you add is one manifest entry and one `declare function`.

## Example

`examples/ws-echo` computes FNV-1a in C: `GET /ffi/{text}` passes each byte to native code through a call-scoped `next()` callback (`ffi.json`, `ffi_native.c`), and the build compiles the object before `scriptc build --ffi`. `tests/ws-echo-ffi-smoke/run.sh` builds the ELF and asserts the route end to end.


---

## [Quickstart](https://chttpjs.pages.dev/quickstart/)

# Quickstart

```sh
pnpm add @chttp/router
```

```ts
import { CtxCore, createRouter } from "@chttp/router";

const app = createRouter();

function sleep(ms: number): Promise<void> {
  return new Promise<void>((resolve) => {
    setTimeout(resolve, ms);
  });
}

// Sync handler: returns immediately, no microtask cost.
app.get("/", (c: CtxCore) => c.text("hi"));
app.get("/user/:id", (c: CtxCore) => c.json({ id: c.req.param("id") }));

// Async handler: await anything, the router waits for it to settle.
app.get("/slow", async (c: CtxCore) => {
  await sleep(100);
  c.text("done");
});

// Declare { body: true } or c.req.body() returns "".
app.post("/echo", (c: CtxCore) => c.text(c.req.body()), { body: true });
app.notFound((c: CtxCore) => c.status(404).text("not found"));

app.serve({ port: 3000 });
```

Sync and async handlers mix freely on one router. Write the response on `c` in either style, you do not need to return it.

```sh
node app.js
curl localhost:3000/user/42
curl localhost:3000/slow
curl -d hello localhost:3000/echo
```

## Where to go next

- Run it as a native binary or in Docker: [Run targets](targets.md), [Deploy](deploy.md).
- Add routes, params and sub-routers: [Routing](routing.md).
- Read request data and write responses: [Context](context.md).
- Cross-cutting behavior: [Middleware](middleware.md).
- Copyable projects: [Examples](examples.md).


---

## [Routing](https://chttpjs.pages.dev/routing/)

# Routing

Routes are registered per method: `app.get | post | put | delete | patch | head | options(path, h)`, plus `app.all(path, h)` for any method and `app.on(method, path, h)` for custom ones.

Paths support static segments, `:param`, and a tail `*` wildcard.

```ts
import { CtxCore } from "@chttp/router";

app.get("/user/:id", (c: CtxCore) => c.req.param("id")); // literal-typed: 'id'
app.get("/wild/*", (c: CtxCore) => c.req.param("*"));
```

## Semantics

- Params are percent-decoded and typed from the path literal (`ParamKey<P>`). Param-less paths degrade `param()` to `string | null`.
- `HEAD` requests fall back to the `GET` handler; node suppresses the body.
- Matched path, unknown method: `405` with an `Allow` header built from the route's method table.
- Unmatched path: `404` (customizable via `app.notFound`).
- Duplicate exact `method`+`path`: first registered wins. Match is strict: no trailing-slash normalization.

## Sub-routers

```ts
const api = createRouter();
api.get("/users", handler);

app.route("/api", api);
```

Parent and sub middleware merge.

Next: [Context](context.md).


---

## [Static files](https://chttpjs.pages.dev/static/)

# Static files

`@chttp/static` serves files and single page apps from a directory or from bytes baked into the binary. It depends on `@chttp/router` only and is authored in the scriptc subset, so it compiles into the same native ELF as the rest of your app.

```ts
import { CtxCore, createRouter } from "@chttp/router";
import { DiskAssets, serveStatic } from "@chttp/static";

const app = createRouter();
app.get("/api/ping", (c: CtxCore) => c.json({ ok: true }));
serveStatic(app, "/", new DiskAssets("./web/dist"), { spa: true });
app.serve({ port: 3000 });
```

## Sources

`AssetSource` is the port: one method, `get(path): Asset | null`, where `path` is decoded, relative to the root and has no leading slash. Strategies are subclasses.

| Source             | Reads from                   | Notes                                                                                                            |
| ------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `DiskAssets(root)` | the filesystem, as `Buffer`s | stats on every request, re-reads only when mtime or size changed, SHA-1 ETag computed on first request of a path |
| `EmbeddedAssets`   | bytes held in the program    | `add(path, asset)` or `load(records)` with a baked array of `EmbedRecord`                                        |

An `Asset` is a plain record: `body` (Buffer), `type`, `etag`, `size`, `mtimeMs`, `immutable` and `encodings` (precompressed variants, each with its own `enc`, `body` and `etag`).

Baked data must be an array of records, not a path-keyed object: the subset cannot index a string-keyed JSON object. The `assets` slice recipe emits a subclass of `EmbeddedAssets` whose constructor calls `load()` with such an array (`path`, `type`, `b64`, `etag`, `mtimeMs`, `immutable`, `encs`) — see "Baking assets into the binary" below.

## serveStatic

`serveStatic(app, prefix, src, opts?)` registers a GET splat route (HEAD comes from the router's GET fallback). `"/"` serves from the root, `"/assets"` serves `/assets/*`.

| Behaviour     | Detail                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Traversal     | The splat is already percent-decoded, so `%2e%2e` and `..%2f` arrive as `..` segments and answer 403. Backslash, NUL, drive-letter tails (`C:/...`) and absolute tails are refused too                                                                                                                                                                                                   |
| Dotfiles      | Any segment starting with `.` answers 404, except `.well-known`                                                                                                                                                                                                                                                                                                                          |
| Symlinks      | Paths are resolved with `realpath` before serving. A link that stays inside the root keeps working; one that escapes it answers 404                                                                                                                                                                                                                                                      |
| Directories   | `/docs/` and `/docs` serve `docs/index.html`                                                                                                                                                                                                                                                                                                                                             |
| MIME          | Built-in table by extension, `application/octet-stream` otherwise                                                                                                                                                                                                                                                                                                                        |
| Validators    | Quoted ETag on every response, `Last-Modified` when the mtime is known. `If-None-Match` (including `W/` and `*`) answers 304 with no body                                                                                                                                                                                                                                                |
| Cache-Control | `public, max-age=31536000, immutable` for hashed filenames, `no-cache` for HTML, `opts.cacheControl` (default `no-cache`) for the rest                                                                                                                                                                                                                                                   |
| Compression   | If `app.js.br` or `app.js.gz` sit next to `app.js` (or are in `encodings`), the client's `accept-encoding` picks `br` over `gzip`; `Vary: accept-encoding` is always set for such assets. Codings match exactly and case-insensitively, never by substring. `q=0` (or `q=0.0`, `q=0.000`) excludes a coding; other q-values are not ranked, so the fixed br-over-gzip preference decides |
| SPA fallback  | With `spa: true`: GET or HEAD, `accept` contains `text/html`, and the path has no extension serves the index file. Missing assets with an extension stay 404                                                                                                                                                                                                                             |
| API prefixes  | Paths under `opts.api` (default `["/api"]`) never reach the filesystem or the fallback, and an unmatched one answers `{"error":"not_found"}` with status 404                                                                                                                                                                                                                             |

Hashed filenames are detected by name: the last `-` or `.` separated token of the stem is 8 to 32 alphanumerics mixing letters and digits (`index-Ab3dE9fG.js`, `chunk.3f9a1c2e.css`). Date-like tokens such as `report-20241014.pdf` are not hashed.

## Options

| Option         | Default        | Meaning                         |
| -------------- | -------------- | ------------------------------- |
| `spa`          | `false`        | enable the SPA fallback         |
| `api`          | `["/api"]`     | prefixes owned by the API       |
| `index`        | `"index.html"` | directory index and SPA shell   |
| `cacheControl` | `"no-cache"`   | for non-hashed, non-HTML assets |

## Compiling to an ELF

The package is covered at 100% by `scriptc coverage packages/static/gate.ts`, and `scriptc build` produces a binary that serves images byte for byte (sha256 verified through curl). Two subset notes from authoring it: reading a missing key from a string-keyed record throws in a native binary, so presence is tested with `in` and keys are prefixed to avoid prototype names; and `httpDate()` is hand-rolled from the `getUTC*` getters until `toUTCString` lowers.

Not included: range requests, `If-Modified-Since`, ISR caching.

## Baking assets into the binary

`EmbeddedAssets` holds every byte inside the program, so `scriptc build` emits one binary that needs no filesystem access. The recipe: after `vite build`, run a small script that walks `dist/` and emits a generated `EmbeddedAssets` subclass whose constructor calls `load(records)` — [`examples/integrations/csr-react`](https://github.com/sigilco/chttp/tree/main/examples/integrations/csr-react) ships a working one (`scripts/bake.mjs` → `src/assets.gen.ts`).

Two ways to get the bytes into the binary, measured on the frontend probes (`bench/scriptc-evidence/frontend-probes-2026-10-14.txt`, 273 KB of assets, scriptc 0.3.1):

|                 | JSON-baked (case 6)                                  | FFI blob (case 9)                                   |
| --------------- | ---------------------------------------------------- | --------------------------------------------------- |
| Mechanism       | array of `{path,type,b64,…}` records in program code | static C arrays linked via `--ffi ffi.json`         |
| Binary overhead | ~= base64 size (+365 KB)                             | ~= raw size + page alignment (+303 KB, ~9% smaller) |
| Startup load    | ~0.15 ms base64 decode                               | ~0.055 ms buffer copy                               |
| Toolchain       | none extra                                           | `cc -c` + `ffi.json` manifest                       |

JSON-baked is the default recipe: zero toolchain, and base64 decode cost is noise at any realistic bundle size. Reach for the FFI variant only when binary size is a hard constraint; it needs a C file, an object per target, and a `mutable-bytes` copy function (ffi format ≥ 6).


---

## [Streaming](https://chttpjs.pages.dev/streaming/)

# Streaming

`@chttp/stream` adds Server-Sent Events and chunked text responses to `@chttp/router`. It is authored in the scriptc subset, so it compiles into the same native binary as your app.

```ts
import { CtxCore, createRouter } from "@chttp/router";
import { streamSSE } from "@chttp/stream";

const app = createRouter();

app.get("/clock", (c: CtxCore) =>
  streamSSE(c, (s) => {
    const t = setInterval(() => s.send(new Date().toISOString(), "tick"), 1000);
    s.onAbort(() => clearInterval(t));
  }),
);
```

## How it works

`streamSSE(c, fn)` sends the status line and headers, flushes them, marks the response as sent (`c.sent = true`), then returns `fn(stream)`. Marking it sent matters: the router answers 500 when a handler settles without writing anything, and a stream callback usually returns before the first byte. Because the helper returns whatever `fn` returns, an `async` callback is awaited by the router like any async handler.

The response is `200 text/event-stream` with `cache-control: no-cache, no-transform` and `x-accel-buffering: no`. Headers set with `c.header(...)` before the call are kept.

## SSEStream

| Method | Writes |
|---|---|
| `send(data)` | `data: ...` lines |
| `send(data, event)` | adds `event: ...` |
| `send(data, event, id)` | adds `id: ...` |
| `comment(text)` | `: text`, useful as a keep-alive ping |
| `retry(ms)` | `retry: ms`, the client reconnect delay |
| `close()` | ends the response |
| `onAbort(fn)` | runs `fn` once when the connection closes |

Multi-line data is split on LF, CRLF or CR into one `data:` line each, as the SSE spec requires. CR and LF are stripped from `event` and `id`, so a value cannot inject extra fields. Every write returns `true` while the stream is open and `false` once it is closed.

`onAbort` is wired to the response `close` event. It fires when the client leaves and also after your own `close()`, so it is the one place to clear timers and drop subscriptions. Registering after the connection closed runs the callback immediately.

## streamText

`streamText(c, fn)` is the same shape for `text/plain` chunked output. The stream has `write(s)`, `writeln(s)`, `close()` and `onAbort(fn)`.

```ts
app.get("/log", (c: CtxCore) =>
  streamText(c, (s) => {
    s.writeln("starting");
    s.writeln("done");
    s.close();
  }),
);
```

## Slow consumers

scriptc < 0.3.2 could not observe backpressure: the result of `write()`, the `drain` event and `writableLength` were all refused at compile time. A client that stops reading would otherwise make the server buffer without bound.

As a stand-in, every stream has a pending-bytes cap. If more than `maxPending` bytes (default 1 MiB) are written inside one `windowMs` window (default 1000 ms), the stream is closed and the write returns `false`. Both are plain fields, so tune them per stream:

```ts
streamSSE(c, (s) => {
  s.maxPending = 64 * 1024;
  s.windowMs = 1000;
});
```

This is a rate window, not true queue depth. On scriptc 0.3.2+, the cap is augmented by real backpressure via a compiled `Writable` wrapper; see `docs/native.md`. Real backpressure only engages when the wrapper compiles as program code (the app or sources vendored into it): inside a statically compiled npm package the `Writable` pump is dead on 0.3.2, so `@chttp/stream` detects that and writes to `res` directly, leaving the window cap as the only policy.

## Compiling and testing

`examples/sse-clock` is a complete app. Build it with `scriptc build src/main.ts -o app`, run it, then watch events arrive:

```sh
curl -N http://localhost:3000/clock
```

Stop `curl` and the interval is cleared by the `onAbort` handler. Always register that handler when your callback starts a timer.


---

## [Run targets](https://chttpjs.pages.dev/targets/)

# Run targets

The same source runs on three targets. Pick per deployment.

| Target | Entry | When |
| --- | --- | --- |
| Node | `app.serve({port})` or `app.handler()` | npm packages, fastest iteration, dev workflow |
| Web Standards | `app.fetch(req, env, ctx)` | Cloudflare Workers, Deno Deploy, Bun, Vercel Edge, Netlify Edge, Lambda, Service Worker, anywhere with a `Request` |
| Native ELF | `scriptc build` → static binary | Containers, scratch images, single-digit-ms cold start, no runtime needed |

The Web Standards surface is canonical. `app.handler()` is a 50-80 LOC Node adapter around `app.fetch`; the same `createRouter()` symbol works in every environment.

## Node

```sh
node app.js
```

Any npm package works. `app.serve()` wraps `http.createServer`; use `app.handler()` to mount into your own server.

## Web Standards

```ts
// Anywhere with a `Request` in scope
const res = await app.fetch(new Request("http://localhost/user/42"));

// Cloudflare Workers / Deno Deploy / Bun / Vercel Edge / Service Worker
export default { async fetch(req, env, ctx) { return app.fetch(req, env, ctx); } };
```

The Ctx surface is Web-Standards-shaped: `c.req.{url,method,path,header,query,param,body,raw}`,
`c.set`/`c.get` for request-scoped vars, `c.header(name, value, {append: true})` for
multi-value headers. Off-the-shelf Hono middlewares wire in via the
[`hono-middleware`](../examples/integrations/hono-middleware/) template.

Recipes:
- [`examples/integrations/cloudflare-workers/`](../examples/integrations/cloudflare-workers/) — CF Workers via `app.fetch`
- [`examples/integrations/aws-lambda/`](../examples/integrations/aws-lambda/) — API Gateway v2 / Lambda URL bridge (Node or `provided.al2023` ELF)

## Native ELF

```sh
scriptc build app.js --npm-static @chttp/router --optimization=speed -o app-bin
./app-bin 3000
```

Everything the app imports must stay inside the scriptc subset, so npm packages outside it do not compile. Check with `scriptc coverage`. Rules for authors: [Coding agents](architecture.md). To call C libraries from the ELF, see [Native FFI](native.md).

`app.fetch` itself is JS-runtime-only today: `new Request` is not constructible
under scriptc 0.3.x, so an ELF host cannot call `app.fetch(req)`. The native
entry is the host-shim `app.fetchShim(method, url, headers, body, respond)` —
plain primitives in, a callback out, no WHATWG types on either side — which
runs the same route table through the shared `_dispatchPrim` dispatch
primitive. The gate [`bench/apps/chttp-fetch.ts`](../bench/apps/chttp-fetch.ts)
keeps that path at 100% static coverage as part of the standard gate suite.

## Bundler pipeline

`unplugin-scriptc` runs `scriptc build` inside Vite. `@chttp/unplugin` additionally lowers the route table at build time: [Route lowering plugin](unplugin.md).

## Docker

A `FROM scratch` image carrying a ~2.4 MB binary: [Deploy](deploy.md).

## Benchmarks

Ratios against raw `node:http`, cold start and RSS: [Benchmarks](benchmarks.md).


---

## [Route lowering plugin](https://chttpjs.pages.dev/unplugin/)

# Route lowering plugin

chttp lowers to a native ELF with `scriptc build` directly: the core package is authored in the scriptc compilable subset like any subset library, and no plugin is involved in that step.

`@chttp/unplugin` (a separate workspace package) is an **elective** build-time dispatch specialization on top. It statically recovers the route table from your imperative `app.get()` / `app.use()` / `app.route()` registrations and emits a `CompiledRoutes` dispatch module next to them, so matching requests skip the runtime trie walk. Anything it cannot prove stays on runtime dispatch with a build warning: the plugin bails, it never guesses.

Install:

```sh
npm i -D @chttp/unplugin
```

Full option reference: [packages/unplugin/PLUGIN.md](https://github.com/sigilco/chttp/blob/main/packages/unplugin/PLUGIN.md).

## Two output modes

**JS dist (plugin standalone).** With plain vite or rollup the plugin works on its own: it emits `.chttp/routes.gen.ts`, your bundler bundles the app as ordinary JavaScript, and you run it on node. No scriptc anywhere in the pipeline. See `examples/vite-lowering`.

**ELF (compose with unplugin-scriptc).** The emitted dispatch is authored inside the scriptc-compilable subset, so it composes with [`unplugin-scriptc`](https://github.com/sigilco/unplugin-scriptc): `chttpPlugin` lowers routes, `scriptcPlugin` runs `scriptc coverage` and `scriptc build` in the same pipeline. Compiled dispatch requires chttp as program code (vendored source or workspace layout); see the "Compiling with scriptc" section of [PLUGIN.md](https://github.com/sigilco/chttp/blob/main...

## Contract stamping

The emitted module carries a `ROUTE_CONTRACT_VERSION` stamp (module header constant plus an instance property), mirrored from chttp's exported `ROUTE_CONTRACT_VERSION`. `app.withDispatch(d)` validates the stamp once at startup: a numeric mismatch throws immediately, naming both versions. It means the dispatch was generated against a different route contract than the runtime implements, typically after upgrading one of the two packages; regenerate `.chttp/*.gen.ts` (upgrade `@chttp/unplugin` ...

## What the plugin does

At `buildStart` (and on each watch event for the file) the plugin scans route modules (default `**/*.chttp.ts`, `**/*.chttp.js`) and emits `.chttp/routes.gen.ts` next to them, satisfying the generated-dispatch contract (`contracts/route-contract.md` in the repo):

- `export class CompiledRoutes extends GenDispatch` whose `dispatch(req, res)` runs per-method sections ordered like the runtime trie (static before param before wildcard, then registration order).
- `routeTable`: full-shape literals `{ method, path, kind, handlerIdx, needsBody }[]`.
- Per-route runners: literal send-chains (`c.json`, `c.text`, ...) compile to straight `res` writes with no `Ctx` allocation; ctx routes build `ReqView`/`Ctx` through the contract surface and call the composed middleware+handler at `app._chains[idx]`.
- `constructor(a: App)` injects the router instance (needed for scriptc lowering; see the scriptc section in PLUGIN.md).

## Bail, not guess

The plugin never silently produces wrong routes. Extracted: literal-path `app.<method>()` calls, `app.all`/`app.on`, `app.use` snapshot semantics, same-file mounts, literal send-chains. Bailed to runtime registration (with a build warning):

- Non-literal paths (variables, calls, spreads).
- Conditional or loop-driven registration.
- Registrations whose handler index cannot be proven against the runtime tables.
- Mounts of routers imported from other modules.

If a routes module cannot be analyzed at all, the plugin emits a stub whose `dispatch` always returns `false`, so the app runs entirely on the runtime path.

## Usage (vite)

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { chttpPlugin } from "@chttp/unplugin"

export default defineConfig({
  plugins: [chttpPlugin.vite()],
})
```

Mark a routes module:

```ts
// src/routes.chttp.ts
import { CtxCore, createRouter } from '@chttp/router'

export const app = createRouter()

app.get('/user/:id', (c: CtxCore) => c.json({ id: c.req.param('id') }))
app.post('/echo', (c: CtxCore) => c.text(c.req.body()), { body: true })
```

Wire the generated dispatch:

```ts
// src/main.ts
import { app } from './routes.chttp.ts'
import { CompiledRoutes } from './.chttp/routes.gen.ts'

app.withDispatch(new CompiledRoutes(app))
app.serve({ port: 3000 })
```

`app.serve()` calls the generated dispatch first; `false` declines to the internal dispatch, which covers bails, `notFound`, and misses. Body buffering is opt-in per the contract: a handler reading `c.req.body()` must register with `{ body: true }` or it receives `''`.

The factory is unplugin-based, so `chttpPlugin.rollup()`, `chttpPlugin.webpack()`, and `chttpPlugin.esbuild()` work too. Only vite is verified by a fixture (`fixtures/vite-app/`): run `npm i && npm run build` there, then `node dist/main.js 3100` to hit static, param, middleware, wildcard, bailed, POST-body, and miss routes.

## Parser option

By default (`parser: "classic"`, the default) extraction parses route modules with the `typescript` package's tsc API. `parser: "tsgo"` switches to the typescript-go native compiler's client API (`typescript/sync`, available on `typescript@next` 7.x nightlies): parsing runs in a spawned native server process and the client decodes the binary AST into classic-shaped node objects. It is experimental: the nightly API breaks between versions, so pin the exact nightly you test. Without a resolvab...

## OpenAPI side channel

With `openapi: true` in the plugin options, the plugin writes a second generated file, `.chttp/routes.openapi.ts`: an OpenAPI 3.1 document (`openapiDocument`) assembled from the extracted route table, plus a `chttpRouteTable` passthrough for typed clients. It is a side channel: the router never imports it and it never enters a scriptc build. Route lowering is untouched; `routes.gen.ts` is byte-identical with the option on or off. Default is off.

Schemas come from `@chttp/val` and are attached only when the extractor can prove one in the handler AST: a `v.parse(schema, ...)` or `v.safeParse(schema, ...)` call where the schema is a val factory expression (or a module-level `const` of one, consts referencing consts included) and the target reads the handler's own context: `c.req.body()` (or `JSON.parse(c.req.body())`) becomes `requestBody`, `c.req.query()`/`c.req.queryAll()` become query parameters, `c.req.param()` fills in path parameter detail.

The emitted module does not embed JSON. It re-declares each proven schema as TS source and calls `toOpenApiSchema` from the same specifier your routes module used, so schemas evaluate at import time in your own val graph, with the val copy that actually validates requests.

What cannot be proven (a schema built dynamically, a target read off another variable, a foreign import) is never guessed: the route documents without its schema and the build warns. See the "OpenAPI side channel" section of [PLUGIN.md](https://github.com/sigilco/chttp/blob/main/packages/unplugin/PLUGIN.md) for the full detection rules and the `path` / `title` / `version` / `imports` sub-options.

## Typed client side channel

With `client: true` in the plugin options, the plugin writes a third generated file, `.chttp/routes.client.ts`, exporting a `createClient(opts)` factory whose verb methods (`get`, `post`, `put`, `patch`, `delete`, `all`) are typed against the route table. Like the OpenAPI side channel, the router never imports it, it never enters a scriptc build, and `routes.gen.ts` is byte-identical with the option on or off. Default is off. Setting `client: true` forces `openapi` on (the client re-exports the openapi sibling's `chttpRouteTable`).

Pass an object for `path` (default `routes.client.ts`) or `fetch` (the default fetch implementation, default `globalThis.fetch`; the value is never embedded in the gen output, only mirrored in the `createClient` default).

Usage:

```ts
// src/client.ts
import { createClient } from "./.chttp/routes.client.ts";

export const api = createClient({ baseUrl: "http://localhost:3000" });

const user = await api.get("/user/:id", { params: { id: "42" } });
//    ^? { id: string }

await api.post("/echo", { body: { hello: "world" } });
```

Path params substitute at the `:name` position and the remaining path segments are URL-encoded. `query` becomes a query string. `body` is JSON-serialized when given an object. A non-2xx response throws a `ChttpClientError extends Error { status, body }`; the body is parsed as JSON if the response Content-Type says so. There is no runtime library: `ChttpClientError` is declared inline in the generated module, and `fetch` resolution is `opts.fetch ?? globalThis.fetch`.

Bail, never guess: a route's response type is only inferred when the extractor can prove it. The rules are the same as the openapi table's, plus a "no body/param/query reads" guard:

- Typed response: single-statement literal-send handlers like `(c) => c.json({...})` with no `c.req.param/body/query/queryAll` reads.
- `unknown` (still emitted, with a build warning): multi-statement handlers, or any handler that reads from the request view, or handlers that do not match a literal send chain.
- Excluded entirely: routes where the handler index cannot be proven. `app.all('*', ...)` becomes a top-level `any(path, opts)` method on the client.

See the "Typed client side channel" section of [PLUGIN.md](https://github.com/sigilco/chttp/blob/main/packages/unplugin/PLUGIN.md) for the full detection rules and the `path` / `fetch` sub-options.


---

## [Validation](https://chttpjs.pages.dev/validation/)

# Validation

Runtime validation at the edge. In Node mode any [Standard Schema](https://standardschema.dev) library works. npm schema libraries do not compile into a chttp ELF, so the repo ships `@chttp/val`, a subset-native Standard Schema library. `@chttp/val` itself is verified to compile from its packed npm tarball (with `@chttp/router`) into a native ELF by `pnpm smoke:pack`.

## TL;DR

| Mode                      | Validation             | Throughput (POST /order, `-c64 -d6` x3, median) |
| ------------------------- | ---------------------- | ----------------------------------------------- |
| Node (`node apps/*.ts`)   | none (read body only)  | ~72k req/s                                      |
| Node                      | `JSON.parse` only      | ~65k req/s                                      |
| Node                      | `@chttp/val` `safeParse` | ~57.9k req/s (same band as valibot)             |
| **ELF**                   | `@chttp/val` `safeParse` | **~73k req/s** (-26% vs unvalidated ELF)        |
| **ELF** (`scriptc build`) | none                   | ~97-104k req/s                                  |

- In Node mode validation costs ~10-18% of request throughput, comparable to what `JSON.parse` itself costs. Pick any Standard Schema library on API taste.
- In ELF mode `@chttp/val` is the way to validate inside the compiled binary.

## `@chttp/val`

`packages/val` is a minimal Standard Schema v1 library written inside the same compilable subset as chttp. `scriptc coverage` on a chttp app using it: **100% static**.

API mirrors [valibot](https://github.com/open-circle/valibot) where the subset allows:

```ts
import * as v from "@chttp/val";

const Item = v.strictObject({
  sku: v.pipe(v.string(), v.minLength(1)),
  qty: v.pipe(v.number(), v.integer(), v.minValue(1)),
  price: v.pipe(v.number(), v.finite()),
});

const Order = v.strictObject({
  id: v.pipe(v.string(), v.uuid()),
  email: v.pipe(v.string(), v.email()),
  items: v.pipe(v.array(Item), v.minLength(1)),
  note: v.optional(v.pipe(v.string(), v.maxLength(200))),
  express: v.boolean(),
  coupon: v.nullable(v.string()),
});

const r = v.safeParse(Order, JSON.parse(c.req.body()));
// r = { success, output, issues } — issues carry type/expected/received/
// message/path, paths are plain key arrays: ["items", "1", "qty"]
```

Shipped surface: `string` `number` `boolean` `any` `unknown` `never` `literal` `picklist` `nullable` `optional(+Str/Num/Bool defaults)` `nullish` `array` `tuple` `object` `looseObject` `strictObject` `record` `union` `custom` `pipe`, actions `minLength` `maxLength` `length` `nonEmpty` `empty` `regex` `email` `uuid` `url` `ipv4` `digits` `startsWith` `endsWith` `includes` `integer` `finite` `safeInteger` `minValue` `maxValue` `gtValue` `ltValue` `multipleOf` `check` `transform` `trim` `trimStart` `trimEnd` `toLowerCase` `toUpperCase` `toMinValue` `toMaxValue`, entry points `parse` `safeParse` `is` `assert` `flatten` `summarize` `VError` `InferOutput`, plus spec-conformant `schema["~standard"]`.

### Deliberate divergences

- Results are plain records (`{ success, output, issues }`), not classes.
- `VIssue` has no `input` member.
- `literal()` and `optional()` defaults accept string/number/boolean/null.
- `optional` with a default is `optionalStr`/`optionalNum`/`optionalBool`.
- `InferOutput` resolves concretely for `string`/`number`/`boolean` schemas; objects/arrays/wrappers resolve to open record types.
- No `Date`/`File`/`Map`/`Set` schemas, no async schemas, no `enum_` object (use `picklist`).

### How it stays fast

Kind-tagged schema classes (same pattern as chttp's `Context`/`ReqView`) with a module-level `VFail` sentinel for failure identity, and a shared push/pop `path` stack: no exception or record allocation on the happy path beyond the output record. Validation costs ~26% of ELF request throughput on the bench schema.

### Using results under scriptc

`issues` is `VIssue[] | null` and `success` does not narrow it, so narrow `issues` inline (`r.issues === null ? 0 : r.issues.length`, or `if (r.issues !== null)`). Do not copy it to a local first, because scriptc rejects the inferred union (SC2009). A type error anywhere in the program is reported as SC2013 against an npm package even when the package is fine, so run `tsc --noEmit` first to see the real error.

## Validating environment variables

Env vars arrive as strings, half of them missing, and a bad `PORT` should kill the process at boot, not at first request. The pattern: build a spec record of val schemas, `safeParse` it against `process.env` once at startup, print `summarize()` and exit on failure, and hand the coerced record to the app.

```ts
import * as v from "@chttp/val";

function createEnv(spec) {
  // v.object, not strictObject: process.env carries PATH, HOME, ...
  // plain object validates the spec keys and strips the rest
  const r = v.safeParse(v.object(spec), process.env);
  if (r.success) return { ok: true, env: r.output, report: null };
  return { ok: false, env: null, report: v.summarize(r.issues) };
}

const Env = createEnv({
  // string in, number out: transform coerces, minValue checks the result
  PORT: v.pipe(
    v.string(),
    v.transform((s) => Number(s)),
    v.minValue(1),
    v.maxValue(65535),
  ),
  LOG_LEVEL: v.optionalStr(v.pipe(v.string(), v.toLowerCase()), "info"),
  NEW_FEATURE: v.optionalStr(v.union([v.literal("on"), v.literal("off")]), "off"),
});

if (!Env.ok) {
  console.error("invalid environment:\n" + Env.report); // "PORT: min_value"
  process.exit(1);
}
app.serve({ port: Env.env.PORT });
```

`process.env` reads lower fine under scriptc, so the same file runs in Node (`node --experimental-strip-types`) and compiles into the ELF (`scriptc build`). Full runnable template: [`examples/env`](../examples/env/).

## Recommendation

- **Node builds:** any Standard Schema library; validation is not the bottleneck.
- **ELF builds:** `@chttp/val`.


---

## [WebSocket](https://chttpjs.pages.dev/websocket/)

# WebSocket

`@chttp/ws` adds RFC 6455 WebSockets to `@chttp/router` through the upgrade seam described in `contracts/upgrade-contract.md` in the repo. It depends on `@chttp/router` only and is authored in the scriptc compilable subset.

## Usage

```ts
import { createRouter } from "@chttp/router";
import type { IncomingMessage } from "node:http";
import type { Socket } from "node:net";
import { WsConn, WsHandler, WsRouter } from "@chttp/ws";

class Room extends WsHandler {
  open(c: WsConn): void {
    c.send("joined " + c.param("name"));
  }
  message(c: WsConn, data: string): void {
    c.send(c.param("name") + ": " + data);
  }
}

const app = createRouter();
app.withUpgrade(new WsRouter().ws("/room/:name", new Room()));
const server = app.serve({ port: 3000 });
const up: (req: IncomingMessage, socket: Socket, head: Buffer) => void = app.upgradeHandler();
server.on("upgrade", up);
```

Paths match exactly or with `:param` segments. Param values are the raw path segments (not percent decoded) and are read with `c.param(name)`. The query string is ignored for matching.

## Handlers and connections

`WsHandler` is a base class with four methods, all no-ops by default:

| Method | Called when |
| --- | --- |
| `open(c)` | after the 101 response was written |
| `message(c, data: string)` | a complete text message arrived (valid UTF-8) |
| `binary(c, data: Buffer)` | a complete binary message arrived |
| `close(c, code, reason)` | exactly once: peer close frame, protocol error, `c.close()`, or socket loss (code 1006) |

Handlers are subclasses, not records of functions, because scriptc fences a function value inside a record. The router keeps them in parallel arrays next to their path patterns. One handler instance serves every connection on its path, so keep per connection state in your own structures keyed by the `WsConn`.

`WsConn` has `send(text)`, `sendBinary(buf)`, `ping(buf)` (at most 125 bytes), `close(code, reason)`, `param(name)`, `isOpen()`, and the fields `socket` and `path`. Pings from the peer are answered with a pong automatically.

## Handshake

The path is matched first, then the upgrade headers:

| Condition | Response |
| --- | --- |
| no route matches the path | 404 |
| `Upgrade` is not `websocket`, or `Sec-WebSocket-Version` is not `13` | 426 with `Sec-WebSocket-Version: 13` |
| method is not GET, or `Sec-WebSocket-Key` is missing or is not a base64-encoded 16 byte nonce | 400 |
| an origin allowlist is set and `Origin` does not match exactly | 403 |
| otherwise | 101 with `Sec-WebSocket-Accept` (sha1 of key plus the RFC GUID, base64) |

Error responses are written by the router and the socket is ended. `Connection` is not in the table because `node:http` only emits `"upgrade"` when the header already carries an `upgrade` token — a request reaching the dispatch is guaranteed to have one.

## Origin allowlist

By default every origin is accepted, matching the `ws` library. Apps that authenticate with cookies are exposed to cross-site WebSocket hijacking (CSWSH) under that default; register an exact-match allowlist and handshakes whose `Origin` header is missing or unlisted are rejected with 403:

```ts
new WsRouter().allowOrigin("https://app.example").ws("/echo", new Echo());
```

No subprotocol negotiation happens; check `req` yourself in a custom `UpgradeDispatch` if you need it.

## Framing and limits

The parser is incremental and non-recursive over `Buffer.concat`. It handles 7, 16 and 64 bit lengths, unmasking, fragmented messages with interleaved control frames, ping, pong and close with code validation. It answers violations by sending a close frame and ending the socket:

| Code | Cause |
| --- | --- |
| 1002 | reserved bits, unknown opcode, unmasked client frame, bad control frame, bad continuation order, bad close payload or code |
| 1007 | text message or peer close reason that is not valid UTF-8 |
| 1009 | frame or assembled message above `maxPayload`, or buffered input above `maxPending` |

Limits default to a 1 MiB `maxPayload` and `maxPayload + 128 KiB` for `maxPending` (unparsed bytes held per connection). Change them with `new WsRouter().withLimits(maxPayload, maxPending)`. A single frame is rejected from its header alone, before the payload is buffered. A fragmented message is different: each fragment is buffered as it arrives and the running total is checked, so a connection can hold up to roughly `maxPayload` assembled bytes before the 1009 fires. There is no permessage-deflate.

## Compiling to a native binary

Subclassing a package class (`WsHandler`, `UpgradeDispatch`) from your own program only lowers when the whole graph is program code, the same rule as `GenDispatch` in [unplugin](unplugin). A `node_modules` dist copy fails with "overriding a method with a different signature". Two consequences:

1. Vendor the sources. `examples/ws-echo/scripts/vendor.mjs` copies `@chttp/router` and `@chttp/ws` `src/` into `.vendor/` and points the ws import of `@chttp/router` at the vendored router, so `scriptc build src/main.ts` sees one source graph.
1. Wire the listener inline. `app.serve()` registers no `"upgrade"` listener at all (any attach built inside the package would defer two SC1090 sites under npm-static compilation, for every app importing the router, upgrade or not). Attach an annotated literal listener in your own program, as `examples/ws-echo/src/main.ts` does, or use a typed alias of `app.upgradeHandler()`:

```ts
server.on("upgrade", function (req: IncomingMessage, socket: Socket, head: Buffer): void {
  if (!ws.upgrade(req, socket, head)) {
    socket.destroy();
  }
});
```

`scriptc coverage` reports 100% static for the example after vendoring.

## Status and TODO

- TODO: Autobahn testsuite (fuzzingclient, Docker) against the node and native builds. Sections 1 to 7 are the target; permessage-deflate sections (12, 13) are out of scope. Results will go in `bench/RESULTS-ws.md`.
- TODO: throughput cell against `ws` on node.
- Not implemented: subprotocol negotiation, idle and close-handshake timeouts (a peer that never answers a close frame leaves the socket half-open until TCP teardown).


---