@thednp/rpc 0.1.0 → 0.2.0

package/AGENTS.md

@@ -8,6 +8,7 @@ pnpm dev:express # Run examples/express dev server
 pnpm dev:fastify # Run examples/fastify dev server
 pnpm dev:hono # Run examples/hono dev server
 pnpm dev:koa # Run examples/koa dev server
+pnpm dev:react-query # Run examples/react-query dev server
 pnpm dev:ssr # Run examples/ssr dev server
 pnpm lint # Lint + typecheck (deno lint + tsc)
 pnpm test # Run tests with coverage
@@ -32,32 +33,45 @@ pnpm release # Publish npm + jsr (scripts/release.js)
 
 ## Examples
 
-The `examples/` directory contains 6 example apps:
-
-| Example   | Adapter                                                           | Type | Run Command        | Config                           |
-| -----------| -------------------------------------------------------------------| ------| --------------------| ----------------------------------|
-| `spa`     | Vite dev server (no adapter)                                      | SPA  | `pnpm dev`         | `examples/spa/rpc.config.ts`     |
-| `express` | Express                                                           | SSR  | `pnpm dev:express` | `examples/express/rpc.config.ts` |
-| `fastify` | Fastify                                                           | SSR  | `pnpm dev:fastify` | `examples/fastify/rpc.config.ts` |
-| `hono`    | Hono                                                              | SSR  | `pnpm dev:hono`    | `examples/hono/rpc.config.ts`    |
-| `koa`     | Koa                                                               | SSR  | `pnpm dev:koa`     | `examples/koa/rpc.config.ts`     |
-| `ssr`     | Custom `http-express.ts` (Express-compatible `node:http` server ) | SSR  | `pnpm dev:ssr`     | `examples/ssr/rpc.config.ts`     |
+The `examples/` directory contains 8 example apps:
+
+| Example       | Adapter                                                           | Type | Run Command             | Config                                  |
+| ----------------| -------------------------------------------------------------------| ------| -------------------------| -----------------------------------------|
+| `spa`          | Vite dev server (no adapter)                                      | SPA  | `pnpm dev`              | `examples/spa/rpc.config.ts`            |
+| `express`      | Express                                                           | SSR  | `pnpm dev:express`      | `examples/express/rpc.config.ts`        |
+| `fastify`      | Fastify                                                           | SSR  | `pnpm dev:fastify`      | `examples/fastify/rpc.config.ts`        |
+| `h3`           | h3                                                                | SSR  | `pnpm dev:h3`           | `examples/h3/rpc.config.ts`             |
+| `hono`         | Hono                                                              | SSR  | `pnpm dev:hono`         | `examples/hono/rpc.config.ts`           |
+| `koa`          | Koa                                                               | SSR  | `pnpm dev:koa`          | `examples/koa/rpc.config.ts`            |
+| `react-query`  | Express (React + @tanstack/react-query SSR)                       | SSR  | `pnpm dev:react-query`  | `examples/react-query/rpc.config.ts`    |
+| `solid-query`  | Express (Solid + @tanstack/solid-query SSR)                       | SSR  | `pnpm dev:solid-query`  | `examples/solid-query/rpc.config.ts`    |
+| `ssr`          | Custom `http-express.ts` (Express-compatible `node:http` server ) | SSR  | `pnpm dev:ssr`          | `examples/ssr/rpc.config.ts`            | `examples/express/rpc.config.ts`        |
+| `fastify`      | Fastify                                                           | SSR  | `pnpm dev:fastify`      | `examples/fastify/rpc.config.ts`        |
+| `hono`         | Hono                                                              | SSR  | `pnpm dev:hono`         | `examples/hono/rpc.config.ts`           |
+| `koa`          | Koa                                                               | SSR  | `pnpm dev:koa`          | `examples/koa/rpc.config.ts`            |
+| `react-query`  | Express (React + @tanstack/react-query SSR)                       | SSR  | `pnpm dev:react-query`  | `examples/react-query/rpc.config.ts`    |
+| `solid-query`  | Express (Solid + @tanstack/solid-query SSR)                       | SSR  | `pnpm dev:solid-query`  | `examples/solid-query/rpc.config.ts`    |
+| `ssr`          | Custom `http-express.ts` (Express-compatible `node:http` server ) | SSR  | `pnpm dev:ssr`          | `examples/ssr/rpc.config.ts`            |
 
 Each example follows the same structure:
 
 - `server.js` / `server.ts` — production server with Vite middleware in dev, static serving in prod
 - `src/api/server.ts` — RPC server functions (auto-scanned by the plugin)
-- `src/entry-server.ts` — SSR entry (hydrates on client)
-- `src/entry-client.ts` — Client entry
+- `src/entry-server.ts` / `src/entry-server.tsx` — SSR entry (hydrates on client)
+- `src/entry-client.ts` / `src/entry-client.tsx` — Client entry
 - `vite.config.ts` + `rpc.config.ts` — Configuration files
 
+> Note: the `react-query` example is SSR with React 19 + `@tanstack/react-query` (Express adapter). It prefetches queries in `entry-server.tsx`, dehydrates them into `window.__REACT_QUERY_STATE__`, and hydrates on the client via `HydrationBoundary`.
+>
+> Note: the `solid-query` example is SSR with Solid + `@tanstack/solid-query` (Express adapter). The greeting is prefetched and serialized with `renderToStringAsync`; the GET form does **not** use a disabled `createQuery` (which would hang SSR — see `wiki/client-usage.md`), it calls `queryClient.fetchQuery()` on submit instead.
+
 ## Key Directories
 
 - `src/` — source for all packages (vite plugin, server, express, fastify, hono, koa adapters)
 - `dist/` — build output (not committed, generated by tsdown)
 - `tests/` — test files (one per adapter + plugin)
 - `tests/fixtures/` — test fixtures (config files, vite-mock.ts)
-- `examples/` — example apps (spa, express, fastify, hono, koa, ssr)
+- `examples/` — example apps (spa, express, fastify, hono, koa, react-query, solid-query, ssr)
 
 ## Build Output (tsdown)
 
@@ -136,9 +150,10 @@ The framework's security boundary is the **RPC prefix-gated HTTP endpoint**. Inp
 - `wiki/quickstart.md` — Rebuild the Express SSR example from `create-vite` in under a minute (copy-paste)
 - `wiki/getting-started.md` — Installation, project structure, auto-scanning, and your first function
 - `wiki/configuration.md` — Configuration reference (`rpc.config.ts`, `vite.config.ts`, options)
-- `wiki/server-functions.md` — `createServerFunction` API, methods, validation
+- `wiki/server-functions.md` — `createServerFunction` API, methods, validation, **request context (`getRequestContext`/`provideRequestContext`)** for per-request data access across async call stacks
+- `wiki/nojs-fallback.md` — native (no-JS) `<form>` fallback / progressive enhancement pattern
 - `wiki/client-usage.md` — Client-side usage, type safety, react-query integration
 - `wiki/wire-protocol.md` — HTTP contract, request/response bodies, curl debugging
-- `wiki/adapters.md` — Framework adapters (Express, Fastify, Hono, Koa)
+- `wiki/adapters.md` — Framework adapters (Express, Fastify, Hono, Koa, h3)
 - `wiki/security.md` — Security hardening
 - `wiki/best-practices.md` — Production patterns (auth, rate limiting, body limits, CSRF)

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## [0.2.0] - 2026-08-09
+
+### Features
+
+- **h3 adapter**: new `@thednp/rpc/h3` adapter with `createRPCMiddleware`, `viteMiddleware`, `attachRPC`, `attachVite`, `readBody`, `redirect` — fully typed, 100% test coverage, SSR example at `examples/h3`
+- **Request Context API**: `provideRequestContext(init, cb)` / `getRequestContext()` — per-request `AsyncLocalStorage` context available to all server function code; `RequestEvent` includes `nativeEvent`, `locals`, adapter-bound `redirect`; works across Express, Fastify, Hono, Koa, and h3
+- **`redirect` helper**: a new `redirect(res, location, status?)` server utility exported from `@thednp/rpc/server` and every adapter. It defaults to `303 See Other` for Post/Redirect/Get flows. The core version accepts an Express `Response` or a raw Node `ServerResponse`, delegating to native `res.redirect()` when available and otherwise writing the status code and `Location` header directly — the raw path is safe on Connect-compatible middlewares and serverless adapters (e.g. Netlify's `serverless-http` mock). Each adapter exports a redirect typed for its response object: Fastify `reply.redirect(location, status)` (v5 URL-first), Koa `ctx.redirect(location)` then `ctx.status = status` (setting status *after*, per koajs/koa#857), and Hono `return redirect(c, location, status)` (the `Response` is returned from the handler)
+
+- **`application/x-www-form-urlencoded` content type**: the `contentType` option and `BodyResult` now include urlencoded. The generated client serializes the single object argument with `new URLSearchParams(args[0]).toString()`, so native HTML forms can POST straight to an RPC endpoint without client-side serialization. Adapters parse `key=value&key2=value2` into an object via `URLSearchParams` (every value arrives as a string; repeated keys collapse to the last value) and use the framework's pre-parsed body (`express.urlencoded()`, `@fastify/formbody`, `koa-body`) when one ran first
+- **Content-type enforcement**: the RPC middleware now validates the request's `Content-Type` against the function's declared `contentType` before parsing the body, rejecting mismatches with `415 Unsupported Media Type` on all four adapters. JSON and text functions are enforced strictly (exact match wins after stripping `charset`/`boundary` parameters); form functions (`multipart/form-data` or `application/x-www-form-urlencoded`) are lenient between the two encodings so native urlencoded form submissions keep working on multipart-declared endpoints. Requests without a `Content-Type` header (curl, GET, legacy clients) are exempt from enforcement. The check lives in the new `hasContentTypeMismatch`/`isFormContentType` helpers exported from `@thednp/rpc/server`
+
+### Examples
+
+- Add the `h3` example (`examples/h3`): SSR with [h3](https://h3.unjs.io/) using `createRPCMiddleware`, `serveStatic`, `toNodeListener`, and `viteMiddleware`. Dev mode bridges Vite's connect stack; prod serves static assets via `serveStatic` and falls through to SSR.
+- The `demo` form-fallback middleware now uses the new `redirect` helper from `@thednp/rpc/express` instead of hand-writing the `303` + `Location` response
+- Add a nojs fallback to the `demo` contact form (progressive enhancement): the form now carries native `action="/@demo/submit-contact" method="post"` attributes, and a small app-layer `createFormFallback` middleware (mounted before the RPC middleware) intercepts browser form navigations — recognized by `POST` + `application/x-www-form-urlencoded` + `Accept: text/html`, which the JS client never sends. Valid submissions get a `303` redirect to the pre-filled GitHub issue URL; invalid ones get a `303` redirect back to `/?name=..&errors=..`, where the server-rendered page (and hydration) recover the form values and show the same field-level error messages the RPC path would have returned. Validation, issue-URL building, and field lists are shared with the server function via the new `demo/src/lib/contact-form.ts`, and the server function now normalizes both multipart (`{ raw }`) and plain-object (urlencoded/JSON-with-fields) payloads
+- Add the `react-query` example (Express + React 19 + `@tanstack/react-query` SSR): prefetches the greeting in `entry-server.tsx`, dehydrates it into `window.__REACT_QUERY_STATE__`, and hydrates on the client via `HydrationBoundary`
+- Add the `solid-query` example (Express + Solid + `@tanstack/solid-query` SSR): prefetches the greeting, serializes it with `renderToStringAsync`, and documents the disabled-query SSR gotcha — a disabled `createQuery` hangs `renderToStringAsync` because the observer result carries a never-settling `promise` (from `experimental_prefetchInRender`) that seroval awaits forever; the example calls `queryClient.fetchQuery()` on submit instead
+
+### Docs
+
+- Document Request Context API (`provideRequestContext`/`getRequestContext`) in `wiki/server-functions.md` — per-request `AsyncLocalStorage` context with `nativeEvent`, `locals`, adapter-bound `redirect` across all 5 adapters
+- Document urlencoded content type in `wiki/server-functions.md` and `wiki/wire-protocol.md` (new `POST + application/x-www-form-urlencoded` section)
+- Document the `415 Unsupported Media Type` response and content-type enforcement rules in `wiki/wire-protocol.md`
+- Document the strict/lenient content-type behavior in `wiki/server-functions.md`
+- Add a "Content-Type Enforcement" section to `wiki/security.md`
+- Document the `redirect` helper in `wiki/server-functions.md` (new "Redirects (`redirect`)" section) and cross-reference it from `wiki/adapters.md`
+- Add h3 adapter section to `wiki/adapters.md` (installation, usage, body limits)
+- Add h3 body limits to `wiki/best-practices.md` (Content-Length fast path + streaming cap via `for await (const chunk of event.req.body)`)
+- Update `llms.txt`, `AGENTS.md`, and `README.md` for the new adapter, examples, content type, enforcement behavior, redirect helper, and request context
+
+### Tests
+
+- **100% coverage achieved** across all adapters (express, fastify, h3, hono, koa) — 920/920 statements, 559/559 branches, 144/144 functions, 898/898 lines
+- Add h3 adapter test suite (`tests/h3.test.ts`): viteMiddleware (node/web runtime paths, settle-twice guard), createMiddleware (prefix/path filtering, name deduplication), createRPCMiddleware (dispatch, content-type enforcement, origin check, redirect default 303, cancel on close, error handling)
+- Add redirect default-status tests to Express, Fastify, Hono, and Koa adapter suites (covers `status = 303` default param branch)
+- Add urlencoded `readBody` tests for all four adapters (pre-parsed and raw stream paths), a urlencoded client-module codegen test in `plugin.test.ts`, and an end-to-end RPC middleware dispatch test
+- Add content-type enforcement tests to the Express, Fastify, Hono, and Koa adapter suites (415 on json↔urlencoded/text↔json mismatch, lenient acceptance of urlencoded on multipart-declared functions) and unit tests for `hasContentTypeMismatch`/`isFormContentType` (parameter stripping, case insensitivity, no-header exemption, form leniency both directions)
+- Add `redirect` tests: raw `ServerResponse` write path and native `.redirect()` delegation in `server-helpers.test.ts`, plus per-adapter suites asserting each framework API (Express `res.redirect(status, url)` vs raw write, Fastify URL-first `reply.redirect`, Koa status-after-`ctx.redirect`, Hono returning `c.redirect`'s `Response`)
+- Fix `scripts/dev-test.js` to verify the query-framework examples' dynamically rendered greeting (`Hello Jane!`) instead of only the static `Hello World!` SSR marker; register the `solid-query` example prefix
+
+### Chores
+
+- Bump version to `0.2.0`
+- Sync `deno.json` version with `package.json`
+
+### Security
+
+- **Content-type check moved before body read**: all four adapters now evaluate `hasContentTypeMismatch` *before* calling `readBody`, so mismatched requests are rejected with `415 Unsupported Media Type` without ever buffering/parsing the body (previously the body was read first, contradicting the documented behavior)
+- **Streaming body-limit in the demo**: `demo/body-limit.ts` no longer buffers the entire body via `readBody` before checking the cap. It enforces the 1MB limit while the request stream is being read (dropping buffered chunks and destroying the request on overflow) and adds a `Content-Length` fast-path for obviously oversized requests — closing a memory-exhaustion gap on the demo's raw `node:http` and Netlify entry points
+- **Netlify URL rewrite tightened**: `demo/netlify/functions/rpc.ts` now matches the `/.netlify/functions/rpc/` marker against the parsed `pathname` only (prefix match), instead of `indexOf` on the raw URL which could match inside a query string and rewrite unintended requests
+- **`@hono/node-server` dedupe**: add a workspace `overrides: { '@hono/node-server': '>=2.0.5' }` in `pnpm-workspace.yaml` to collapse the vulnerable `1.19.17` transitive dependency (via `@hono/vite-dev-server`, which pins `^1.19.11`) onto the already-used patched `2.1.0`. `pnpm audit` is now clean
+
+## [0.1.1] - 2026-08-07
+
+### Security
+
+- Unexpected exceptions no longer expose their message in development responses: `formatError` returns the generic `{ error: "Internal Server Error" }` for any non-`RPCError` error in every environment. `RPCError` payloads (developer-authored `message`, `code`, optional `data`) are still included in development so client-side error handling keeps working, while diagnostics stay server-side via the middleware's `console.error` logging (addresses the GitHub CodeQL `js/exception-information-leak` finding)
+
+### Refactor
+
+- `scanForServerFiles` lazy-imports Vite inside the scan function instead of importing it statically at the top of the module — the standalone server entry no longer carries a static Vite dependency, so serverless function bundles that register API modules directly no longer drag Vite's node chunk (which imports esbuild, absent with Vite 8's rolldown) into the bundle
+- Drop the redundant `config as ScanConfig` casts in `scanForServerFiles` (the merged config is already typed)
+
+### Fixes
+
+- Netlify serverless deployment: externalize Vite from the function bundle via `[functions] external_node_modules = ["vite"]` in `netlify.toml`, so `@netlify/zip-it-and-ship-it` no longer fails with "Could not resolve 'esbuild'" when bundling the RPC function
+- Fix broken documentation links in all 6 example READMEs (`wiki/setup.md` → `wiki/wire-protocol.md`, the former never existed)
+- Remove stale `demo/src/render-bak.ts`; clean up the pnpm lockfile
+
+### Docs
+
+- Update `wiki/security.md`, `wiki/wire-protocol.md`, `README.md`, and `llms.txt` to reflect that unexpected exception details never reach clients — only `RPCError` payloads, and only in development
+
+### Tests
+
+- `formatError` dev-mode tests updated to assert the generic message for unexpected exceptions (plain `Error` and non-`Error` values), keeping the `RPCError` payload assertions
+
+### Chores
+
+- Sync demo and all 6 examples to `@thednp/rpc ^0.1.0`
+- Remove the leftover `0.0.14` changelog header (its entry was merged into `0.1.0`)
+
 ## [0.1.0] - 2026-08-06
 
 ### Features

package/README.md

@@ -6,7 +6,7 @@
 [![JSR Version](https://img.shields.io/jsr/v/@thednp/rpc.svg)](https://jsr.io/@thednp/rpc)
 [![NPM Downloads](https://img.shields.io/npm/dm/@thednp/rpc.svg)](http://npm-stat.com/charts.html?package=@thednp/rpc)
 
-A Vite plugin for automatic RPC generation — simple, framework agnostic, and easy to use.
+A Vite plugin for automatic RPC generation — write server functions, re-export them, call them. Simple and framework agnostic.
 
 ## Isomorphic Design
 
@@ -35,7 +35,7 @@ You define them in a file, import and call them where you need them. The plugin
 * `createFunction.ts` — server-side definition (wrapped handler with `AbortController`)
 * `getClientModules.ts` — build-time code generation (string template with validation)
 * `client-helpers.ts` — client-side runtime (thin `fetch` based modules)
-* `server-helpers.ts` — server-only utilities (`RPCError`, error formatting, glob file walking)
+* `server-helpers.ts` — server-only utilities (`RPCError`, error formatting, `redirect`, glob file walking)
 * `scanForServerFiles.ts` — file discovery
 * **Adapters** — thin middleware wrappers
 </details>
@@ -90,7 +90,7 @@ Scan `src/api/` for classic `server.ts|js|mjs|mts` files, or switch to glob mode
 <details>
 <summary><b>Typed errors, safe by default</b></summary>
 
-Server errors return a generic `Internal Server Error` in production — no messages, codes, or stacks leak to clients. In development the message (and `code`/`data` for `RPCError`) is included so you can debug instantly. `multipart/form-data` content type is supported for file uploads via your framework's multipart parser.
+Server errors return a generic `Internal Server Error` — no messages, codes, or stacks leak to clients, in any environment. Only `RPCError` payloads (developer-authored `message`/`code`/`data`) reach the client, and only in development, so you can debug instantly. `multipart/form-data` content type is supported for file uploads via your framework's multipart parser, and json/text/urlencoded requests are validated against the function's declared content type (`415 Unsupported Media Type` on mismatch; form encodings are interchangeable for nojs form fallbacks).
 </details>
 
 <details>
@@ -99,29 +99,29 @@ Server errors return a generic `Internal Server Error` in production — no mess
 Generic type inference flows from your server function's arguments and return type all the way to the client stub. You get autocomplete for function names, argument types, and return types without writing a single type annotation on the client side.
 </details>
 
-## Demos
-
-| Example         | Source Code                                                                    | Try online                                                                               |
-| -----------------| --------------------------------------------------------------------------------| ------------------------------------------------------------------------------------------|
-| SPA - node:http | [examples/spa](https://github.com/thednp/rpc/tree/master/examples/spa)         | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/spa)     |
-| SSR - node:http | [examples/ssr](https://github.com/thednp/rpc/tree/master/examples/ssr)         | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/ssr)     |
-| Express         | [examples/express](https://github.com/thednp/rpc/tree/master/examples/express) | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/express) |
-| Fastify         | [examples/fastify](https://github.com/thednp/rpc/tree/master/examples/fastify) | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/fastify) |
-| Hono            | [examples/hono](https://github.com/thednp/rpc/tree/master/examples/hono)       | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/hono)    |
-| Koa             | [examples/koa](https://github.com/thednp/rpc/tree/master/examples/koa)         | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/koa)     |
+## Examples
 
-> **NOTE**: Stackblitz is currently working on upgrading their platform. Demos may not work properly. 
+| Source                                                                                 | Demo                                                                                         | Clone                                                   |
+| ----------------------------------------------------------------------------------------| ----------------------------------------------------------------------------------------------| ---------------------------------------------------------|
+| [examples/spa](https://github.com/thednp/rpc/tree/master/examples/spa)                 | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/spa)         | `pmpm dlx degit thednp/rpc/examples/spa my-app`         |
+| [examples/ssr](https://github.com/thednp/rpc/tree/master/examples/ssr)                 | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/ssr)         | `pnpm dlx degit thednp/rpc/examples/ssr my-app`         |
+| [examples/express](https://github.com/thednp/rpc/tree/master/examples/express)         | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/express)     | `pnpm dlx degit thednp/rpc/examples/express my-app`     |
+| [examples/fastify](https://github.com/thednp/rpc/tree/master/examples/fastify)         | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/fastify)     | `pnpm dlx degit thednp/rpc/examples/fastify my-app`     |
+| [examples/h3](https://github.com/thednp/rpc/tree/master/examples/h3)                   | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/h3)          | `pnpm dlx degit thednp/rpc/examples/h3 my-app`          |
+| [examples/hono](https://github.com/thednp/rpc/tree/master/examples/hono)               | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/hono)        | `pnpm dlx degit thednp/rpc/examples/hono my-app`        |
+| [examples/koa](https://github.com/thednp/rpc/tree/master/examples/koa)                 | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/koa)         | `pnpm dlx degit thednp/rpc/examples/koa my-app`         |
+| [examples/react-query](https://github.com/thednp/rpc/tree/master/examples/react-query) | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/react-query) | `pnpm dlx degit thednp/rpc/examples/react-query my-app` |
+| [examples/solid-query](https://github.com/thednp/rpc/tree/master/examples/solid-query) | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/solid-query) | `pnpm dlx degit thednp/rpc/examples/solid-query my-app` |
 
-## Examples
+> **Clone an example**: `degit` scaffolds a fresh copy straight from the repo — no git history, ready to run:
 
-| Example | Adapter                                       | Type | Run Command        | RPC Approach                       |
-| ---------| -----------------------------------------------| ------| --------------------| ------------------------------------|
-| spa     | Vite dev server (Connect, Express-compatible) | SPA  | `pnpm dev`         | Client stubs only                  |
-| express | Express                                       | SSR  | `pnpm dev:express` | Direct import (SSR) + client stubs |
-| fastify | Fastify                                       | SSR  | `pnpm dev:fastify` | Direct import (SSR) + client stubs |
-| hono    | Hono                                          | SSR  | `pnpm dev:hono`    | Direct import (SSR) + client stubs |
-| koa     | Koa                                           | SSR  | `pnpm dev:koa`     | Direct import (SSR) + client stubs |
-| ssr     | Custom `node:http` (Express-compatible)       | SSR  | `pnpm dev:ssr`     | Direct import (SSR) + client stubs |
+```bash
+# Scaffold the Express example
+pnpm dlx degit thednp/rpc/examples/express my-rpc-app
+cd my-rpc-app
+pnpm install
+pnpm dev
+```
 
 SSR examples demonstrate isomorphic usage: server functions are imported directly during server-side rendering (`entry-server.ts`) and also called from the client via auto-generated fetch stubs. The SPA example uses only the client-side stubs.
 
@@ -319,6 +319,12 @@ The `readBody` utility of each adapter doesn't cap raw request bodies by default
 Server functions only support `GET` and `POST` (default `POST`). RPC dispatch is not REST — `PUT`/`PATCH`/`DELETE` carry resource semantics that don't apply to function calls, and `OPTIONS` must stay reserved for CORS preflight. Every accepted method is another dispatch path to validate; keeping the surface minimal (and defaulting to `POST`) reduces CSRF and parsing attack surface. See [Server Functions Guide](./wiki/server-functions.md) for details.
 </details>
 
+<details>
+<summary><b>Content-type enforcement</b></summary>
+
+Request bodies are validated against the function's declared `contentType` before parsing — mismatches get a `415 Unsupported Media Type`. JSON and text functions require an exact match (after stripping `charset`/`boundary` parameters); the two form encodings are interchangeable so native urlencoded `<form>` submissions keep working on multipart-declared endpoints (nojs progressive enhancement). Requests without a `Content-Type` header are exempt, so curl and `GET` keep working unchanged. See [Wire Protocol](./wiki/wire-protocol.md) for details.
+</details>
+
 ---
 The full threat model, including edge cases and configuration options for tightening things further, is documented in [Security](./wiki/security.md).
 
@@ -327,13 +333,13 @@ The full threat model, including edge cases and configuration options for tighte
 
 - [Quick Start](./wiki/quickstart.md) — Rebuild the Express SSR example from `create-vite` in under a minute
 - [Getting Started](./wiki/getting-started.md) — Installation, project structure, and your first function
-- [Configuration](./wiki/configuration.md)
-- [Server Functions](./wiki/server-functions.md)
-- [Client Usage](./wiki/client-usage.md)
+- [Configuration](./wiki/configuration.md) — Full configuration reference
+- [Server Functions](./wiki/server-functions.md) — Creating server functions
+- [Client Usage](./wiki/client-usage.md) — Client-side usage
 - [Wire Protocol](./wiki/wire-protocol.md) — The HTTP contract behind the generated clients (curl debugging)
-- [Adapters](./wiki/adapters.md)
-- [Best Practices](./wiki/best-practices.md)
-- [Security](./wiki/security.md)
+- [Adapters](./wiki/adapters.md) — Framework adapters
+- [Best Practices](./wiki/best-practices.md) — Tips and best practices
+- [Security](./wiki/security.md) — Security hardening
 
 ## License
 

package/dist/express/express.d.mts

@@ -107,6 +107,18 @@ declare const isExpressRequest: (req: IncomingMessage | Request) => req is Reque
  * @returns True if the response is an Express Response
  */
 declare const isExpressResponse: (res: ServerResponse | Response) => res is Response;
+/**
+ * Issues an HTTP redirect on an Express or raw Node ServerResponse.
+ * Uses Express's native `res.redirect(status, location)` when an Express
+ * Response is provided, otherwise writes the status code and `Location`
+ * header directly on the raw `ServerResponse` (safe for Connect-compatible
+ * middlewares and serverless adapters whose mock responses lack `.redirect`).
+ * Defaults to `303 See Other` for convention (Post/Redirect/Get).
+ * @param res - Express Response or raw Node ServerResponse
+ * @param location - The URL to redirect to
+ * @param status - HTTP status code, defaults to 303
+ */
+declare const redirect: (res: ServerResponse | Response, location: string, status?: number) => void;
 /**
  * Type guard that checks whether a request has a pre-parsed body (`body` property).
  * Used to detect if a body-parser middleware already consumed the stream.
@@ -129,5 +141,5 @@ declare const getRequestDetails: (request: Request | IncomingMessage) => Request
  */
 declare const getResponseDetails: (response: Response | ServerResponse) => ResponseDetails;
 //#endregion
-export { type ExpressMiddlewareFn, type ExpressMiddlewareHooks, type ExpressMiddlewareOptions, type RequestDetails, type ResponseDetails, attachRPC, attachVite, createMiddleware, createRPCMiddleware, getRequestDetails, getResponseDetails, hasPreParsedBody, isExpressRequest, isExpressResponse, readBody };
+export { type ExpressMiddlewareFn, type ExpressMiddlewareHooks, type ExpressMiddlewareOptions, type RequestDetails, type ResponseDetails, attachRPC, attachVite, createMiddleware, createRPCMiddleware, getRequestDetails, getResponseDetails, hasPreParsedBody, isExpressRequest, isExpressResponse, readBody, redirect };
 //# sourceMappingURL=express.d.mts.map

package/dist/express/express.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"express.d.mts","names":[],"sources":["../../src/express/types.d.ts","../../src/express/createMiddleware.ts","../../src/express/helpers.ts"],"mappings":";;;;;;;;KAgBY,2BAA2B;;;;;KAM3B,uBACV,UAAU,yCAEV,iBAAiB,QAAQ,8BACtB;;;;UAKY;;;;;;;EAOf,UACE,KAAK,kBAAkB,SACvB,KAAK,iBAAiB,UACtB,MAAM,QAAQ,eAAe,iBAC1B;;;;;;KAOK;;EAEV;;EAEA,YAAY,cAAc;;EAE1B;;EAEA,gBAAgB;;EAEhB,eAAe,cAAc,QAAQ,eAAe;;;;;KAM1C;;EAEV;;EAEA;;EAEA,cAAc;;EAEd,SAAS;;EAET;;;;;;;;;;;cCvCW,kBAAkB;;;;;;;;cAyElB,qBAAqB;;;;;;;;iBC3FZ,UAAU,KAAK,UAAO;;;;;;iBAW5B,WAAW,KAAK,SAAS,MAAM;;;;;;;;cAWlC,WAAQ,KACd,UAAiB,oBACrB,QAAQ;;;;;;cAyEE,mBAAgB,KACtB,kBAAkB,YACtB,OAAO;;;;;;cASG,oBAAiB,KACvB,iBAAiB,aACrB,OAAO;;;;;;;cAUG,mBAAgB,KACtB,kBAAkB,YACtB,OAAO;;;;;;;cAUG,oBAAiB,SACnB,UAAiB,oBACzB;;;;;;;cAqBU,qBAAkB,UACnB,WAAkB,mBAC3B"}
+{"version":3,"file":"express.d.mts","names":[],"sources":["../../src/express/types.d.ts","../../src/express/createMiddleware.ts","../../src/express/helpers.ts"],"mappings":";;;;;;;;KAgBY,2BAA2B;;;;;KAM3B,uBACV,UAAU,yCAEV,iBAAiB,QAAQ,8BACtB;;;;UAKY;;;;;;;EAOf,UACE,KAAK,kBAAkB,SACvB,KAAK,iBAAiB,UACtB,MAAM,QAAQ,eAAe,iBAC1B;;;;;;KAOK;;EAEV;;EAEA,YAAY,cAAc;;EAE1B;;EAEA,gBAAgB;;EAEhB,eAAe,cAAc,QAAQ,eAAe;;;;;KAM1C;;EAEV;;EAEA;;EAEA,cAAc;;EAEd,SAAS;;EAET;;;;;;;;;;;cC3BW,kBAAkB;;;;;;;;cAyElB,qBAAqB;;;;;;;;iBCvGZ,UAAU,KAAK,UAAO;;;;;;iBAc5B,WAAW,KAAK,SAAS,MAAM;;;;;;;;cAWlC,WAAQ,KACd,UAAiB,oBACrB,QAAQ;;;;;;cAqFE,mBAAgB,KACtB,kBAAkB,YACtB,OAAO;;;;;;cASG,oBAAiB,KACvB,iBAAiB,aACrB,OAAO;;;;;;;;;;;;cAeG,WAAQ,KACd,iBAAiB,UAAe,kBACrB;;;;;;;cAkBL,mBAAgB,KACtB,kBAAkB,YACtB,OAAO;;;;;;;cAUG,oBAAiB,SACnB,UAAiB,oBACzB;;;;;;;cAqBU,qBAAkB,UACnB,WAAkB,mBAC3B"}

package/dist/express/express.mjs

@@ -1,4 +1,4 @@
-import { scanForServerFiles, serverFunctionsMap } from "@thednp/rpc/server";
+import { escapeRegExp, formatError, hasContentTypeMismatch, provideRequestContext, scanForServerFiles, serverFunctionsMap } from "@thednp/rpc/server";
 //#region src/options.ts
 const defaultRPCOptions = {
 	rpcPrefix: "__rpc",
@@ -44,9 +44,10 @@ const readBody = (req) => {
 			const contentType = req.headers["content-type"]?.toLowerCase() || "";
 			const isJSON = contentType.includes("json");
 			const isMultipart = contentType.includes("multipart/form-data");
+			const isUrlEncoded = contentType.includes("urlencoded");
 			resolve({
-				contentType: isMultipart ? "multipart/form-data" : isJSON ? "application/json" : "text/plain",
-				data: isMultipart ? req.body : isJSON ? req.body : String(req.body)
+				contentType: isMultipart ? "multipart/form-data" : isJSON ? "application/json" : isUrlEncoded ? "application/x-www-form-urlencoded" : "text/plain",
+				data: isMultipart ? req.body : isJSON ? req.body : isUrlEncoded ? req.body : String(req.body)
 			});
 			return;
 		}
@@ -65,10 +66,11 @@ const readBody = (req) => {
 			const incomingType = req.headers["content-type"]?.toLowerCase() || "";
 			const isJSON = incomingType.includes("json");
 			const isMultipart = incomingType.includes("multipart/form-data");
+			const isUrlEncoded = incomingType.includes("urlencoded");
 			try {
-				const data = isMultipart ? { raw: body } : JSON.parse(body);
+				const data = isMultipart ? { raw: body } : isUrlEncoded ? Object.fromEntries(new URLSearchParams(body)) : JSON.parse(body);
 				resolve({
-					contentType: isMultipart ? "multipart/form-data" : isJSON ? "application/json" : "text/plain",
+					contentType: isMultipart ? "multipart/form-data" : isJSON ? "application/json" : isUrlEncoded ? "application/x-www-form-urlencoded" : "text/plain",
 					data: isMultipart ? data : data
 				});
 			} catch (_e) {
@@ -102,6 +104,26 @@ const isExpressResponse = (res) => {
 	return "json" in res && "send" in res;
 };
 /**
+* Issues an HTTP redirect on an Express or raw Node ServerResponse.
+* Uses Express's native `res.redirect(status, location)` when an Express
+* Response is provided, otherwise writes the status code and `Location`
+* header directly on the raw `ServerResponse` (safe for Connect-compatible
+* middlewares and serverless adapters whose mock responses lack `.redirect`).
+* Defaults to `303 See Other` for convention (Post/Redirect/Get).
+* @param res - Express Response or raw Node ServerResponse
+* @param location - The URL to redirect to
+* @param status - HTTP status code, defaults to 303
+*/
+const redirect = (res, location, status = 303) => {
+	if (isExpressResponse(res)) {
+		res.redirect(status, location);
+		return;
+	}
+	res.statusCode = status;
+	res.setHeader("Location", location);
+	res.end();
+};
+/**
 * Type guard that checks whether a request has a pre-parsed body (`body` property).
 * Used to detect if a body-parser middleware already consumed the stream.
 * @param req - A Node IncomingMessage or Express Request
@@ -158,66 +180,15 @@ const getResponseDetails = (response) => {
 	};
 };
 //#endregion
-//#region src/tools.ts
-/**
-* Escapes special regex metacharacters in a string.
-* Used to safely embed user-configurable values (like rpcPrefix) into regular expressions,
-* preventing ReDoS and regex injection attacks.
-* @param s - The raw string to escape
-* @returns The escaped string safe for use in new RegExp()
-*/
-function escapeRegExp(s) {
-	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-//#endregion
 //#region src/constants.ts
 const FUNCTION_NOT_FOUND = "Function not found";
 const METHOD_NOT_ALLOWED = "Method Not Allowed";
 const REQUEST_FORBIDDEN = "Forbidden";
-const INTERNAL_SERVER_ERROR = "Internal Server Error";
+const UNSUPPORTED_MEDIA_TYPE = "Unsupported Media Type";
 const CLIENT_DISCONNECTED = "client disconnected";
 /** Returns a warning when a middleware name is reused, preventing registration conflicts. @param name - The duplicate middleware name */
 const MIDDLEWARE_NAME_USED = (name) => `The middleware name "${name}" is already used.`;
 //#endregion
-//#region src/server-helpers.ts
-/**
-* A typed error thrown from server functions.
-* The middleware serializes the `message` and `code` in the response,
-* allowing clients to recognise and handle specific error conditions.
-*/
-var RPCError = class extends Error {
-	/** Machine-readable error code (e.g. "VALIDATION_FAILED", "UNAUTHORIZED") */
-	code;
-	/** Optional diagnostic payload */
-	data;
-	constructor(message, code = "INTERNAL", data) {
-		super(message);
-		this.name = "RPCError";
-		this.code = code;
-		this.data = data;
-	}
-};
-/**
-* Formats an error for the RCP middleware response.
-* In development the full message and stack are included so developers
-* can quickly identify issues. In production only the generic
-* "Internal Server Error" is sent, preventing information disclosure.
-*/
-const formatError = (err, isProduction) => {
-	if (!isProduction) {
-		if (err instanceof RPCError) {
-			const payload = {
-				error: err.message || "Internal Server Error",
-				code: err.code
-			};
-			if (err.data !== void 0) payload.data = err.data;
-			return payload;
-		}
-		return { error: (err instanceof Error ? err.message : String(err)) || "Internal Server Error" };
-	}
-	return { error: INTERNAL_SERVER_ERROR };
-};
-//#endregion
 //#region src/express/createMiddleware.ts
 let middlewareCount = 0;
 const middlewareStack = /* @__PURE__ */ new Set();
@@ -295,15 +266,35 @@ const createRPCMiddleware = (initialOptions = {}) => {
 					const raw = searchParams.get("args");
 					if (raw) args = JSON.parse(raw);
 				} else {
+					if (hasContentTypeMismatch(serverFunction.options?.contentType ?? "application/json", req.headers["content-type"])) {
+						sendResponse(415, { error: UNSUPPORTED_MEDIA_TYPE });
+						return;
+					}
 					const body = await readBody(req);
 					args = Array.isArray(body.data) ? body.data : [body.data];
 				}
-				const { data, cancel } = serverFunction.handler(...args);
+				const requestEvent = {
+					request: req,
+					response: res,
+					nativeEvent: {
+						req,
+						res
+					},
+					locals: res.locals ?? {},
+					redirect: (location, status = 303) => {
+						requestEvent.redirected = {
+							location,
+							status
+						};
+						redirect(res, location, status);
+					}
+				};
+				const { data, cancel } = provideRequestContext(requestEvent, () => serverFunction.handler(...args));
 				const onClose = () => cancel(CLIENT_DISCONNECTED);
 				req.on("close", onClose);
 				const result = await data;
 				req.off("close", onClose);
-				if (!res.headersSent) sendResponse(200, { data: result });
+				if (!requestEvent.redirected && !res.headersSent) sendResponse(200, { data: result });
 			} catch (err) {
 				console.error(String(err));
 				const isProduction = process.env.NODE_ENV === "production";
@@ -313,6 +304,6 @@ const createRPCMiddleware = (initialOptions = {}) => {
 	});
 };
 //#endregion
-export { attachRPC, attachVite, createMiddleware, createRPCMiddleware, getRequestDetails, getResponseDetails, hasPreParsedBody, isExpressRequest, isExpressResponse, readBody };
+export { attachRPC, attachVite, createMiddleware, createRPCMiddleware, getRequestDetails, getResponseDetails, hasPreParsedBody, isExpressRequest, isExpressResponse, readBody, redirect };
 
 //# sourceMappingURL=express.mjs.map