@zudojs/http

OVERVIEW

@zudojs/http is the part of Zudo that talks to the web. It gives you a server that listens for requests from browsers and other programs, and a client for sending requests yourself.

HTTP is the language browsers and servers use. A request is a message sent to your server: a method (like GET or POST), a URL, some headers, and maybe a body. A response is your reply: a status code (like 200 or 404), headers, and a body.

Everything in this package works on two objects: HttpRequestContext (what came in) and HttpResponseContext (what goes out). The server, router, middleware, and error helpers all pass these two around.

When you need it

• → You want to expose an API or serve pages from a Node process.
• → You want URL routing (/users/:id), middleware, or CORS and security headers.
• → You want to call another HTTP service with retries and timeouts.

When you don't

• → Your code never listens on a port or calls a URL (a CLI, a background worker).
• → You already run Express, Fastify, or Hono and only need Zudo's other packages.

INSTALLATION

Install the package with npm. Its runtime dependencies (@zudojs/crypto, @zudojs/errors, @zudojs/logger, @zudojs/middleware, @zudojs/openapi, @zudojs/security) are installed automatically. Node 24 or newer is required.

QUICK START

The smallest server needs two things: an adapter and a handler. An adapter is the piece that knows how to talk to a real runtime (here, Node's built-in http module). A handler is your function that receives a request and returns a response.

This code starts a server on port 3000 that answers every request with a small JSON object.

Open a second terminal and send a request. You should see the JSON reply.

Call await adapter.stop() to shut the server down. Pass port: 0 to let the operating system pick a free port; adapter.address.port then tells you which one.

REQUEST & RESPONSE

HttpRequestContext holds everything about the incoming request. You never build one yourself on the server; the adapter creates it and hands it to your handler. HttpResponseContext is what you build and return. Every setter returns the context, so calls chain.

The request body arrives as raw bytes (a Uint8Array), already read for you and capped at maxBodySize (10 MB by default). Decode it and parse it yourself.

This handler reads a query parameter, a header, and a JSON body, then echoes them back.

Any other return value, including a plain object with keys such as status or body, is sent as a 200 JSON response. To choose the status or headers, return createResponseContext({ status, headers, body }). Returning nothing sends an empty 200.

Request: what you can read

Response: what you can set

SERVER

createHttpServer wraps an adapter with lifecycle management: a state you can inspect (created, starting, running, stopping, stopped, failed), events you can listen to, and a graceful shutdown that waits for in-flight requests.

You can run an adapter on its own, as in the quick start. Reach for the server when you want start/stop events, a request counter, or one object to hand to the rest of your application.

This starts a server, prints its state and address, and stops cleanly on Ctrl+C.

server.on(event, listener) adds a listener after construction and returns a function that removes it again. server.snapshot() returns a plain object with the name, state, address, start time, uptime in milliseconds, and request count.

The options object is typed as HttpServerOptions, so TypeScript knows what handler receives. Under strict, handler: async (request) => request.path compiles as written; before v1.4.0 the options were unknown and the same line failed with TS7006: Parameter 'request' implicitly has an 'any' type.

Server options

Node adapter options

Without it, the client address is the socket peer and the protocol reflects the socket's own TLS state. The standalone getRequestProtocol(request, trustProxy?) and getRequestIP(request, trustProxy?) take the same value as an optional second argument, and default to false too.

Request ids

Every request has an id, request.id, that you can write into log lines so all the lines for one request can be found together. When a proxy or another service has already given the request an id in the x-request-id header, the Node adapter reuses it, so the same id follows the request from service to service.

Only a safe value is reused: 1–128 characters of letters, digits, ., _, : and -. Anything else is ignored and a UUID is generated instead, so an id copied into your logs can never carry spaces, quotes or control characters.

The last request never reaches the handler: the adapter's request guard checks the header first and answers 400 to a malformed one. The guard's default requestIdPattern is the same rule as the reuse rule, so ids containing . or : (common in trace ids) now pass; they used to be refused with 400. With security: false a malformed id is simply ignored and a UUID generated.

Before v1.4.0 the Node adapter always generated a new id, although the docs said it reused the header. If your server is reached directly by clients and you don't want them choosing the ids that appear in your logs, pass createNodeHttpAdapter({ trustRequestId: false }). The rule itself is exported as resolveIncomingRequestId(value), which returns the id to reuse or undefined.

ROUTER

A router picks which function runs for a given method and path. Instead of one big handler full of if statements, you register routes like GET /users/:id and the router does the matching.

The router is not wired to the server automatically. Your handler calls router.dispatch(request), which returns { response, route }, and returns the response.

This registers two routes and connects the router to a server. :id is a parameter: it matches one path segment and lands in ctx.params.id.

Unknown paths get a 404 and known paths with the wrong method get a 405, both as JSON, without any extra code.

What a route handler receives

The handler gets one ctx object of type HttpRouterContext. It is not the request itself; the request lives at ctx.request.

What a route handler can return

You don't have to build a response for every route. A route handler may return a plain JSON value — an object, array, string, number or boolean — and it is sent as 200 with a JSON body, exactly like a server handler's return value. Returning undefined or null sends 204 No Content. An HttpResponseContext or a web Response is sent as built, for when you need another status or headers.

Before v1.4.0 a plain object was a type error for a route handler and, if you forced it through, went out as an empty 204. The router and the lower-level RouteDispatcher now agree. The accepted return type is exported as RouterHandlerResult (with RouterJsonValue for the JSON part).

Groups and route middleware

router.group(prefix, fn) registers several routes under one prefix. The middleware option on any route runs those middleware for that route only.

Anything route middleware writes to context.response before calling next() — headers, cookies, status, metadata — survives when the handler returns a response of its own. A guard that sets a security header and delegates therefore affects the response that is sent.

Route parameters are set on the request before route middleware runs, so a guard can read them with ctx.request.getParam("id"), just as the handler reads ctx.params.id. Before v1.4.0 they were only filled in for the handler, so a guard or an extractResource loader that looked up the resource by id always saw nothing and denied the request. The guard example below relies on this.

Route patterns

A pattern is a path split into segments. A literal segment matches itself; the other kinds capture into ctx.params.

When more than one pattern matches, the router compares their segments left to right by kind — literal beats parameter, parameter beats wildcard — and the first difference decides; registration order breaks a tie. So /admin/*rest wins over /:a/:b/:c/:d for GET /admin/a/b/c. Before v1.3.0 the kinds were summed into a single score, which let the longer all-parameter pattern win and bypass the guards registered on the admin route.

Router options

For the lower-level path, createRouteDispatcher(matcher, options) takes RouteDispatchOptions. Its preserveResponse (default false) keeps the response the middleware chain built instead of merging the handler's response into it; before v1.3.0 the option was declared and never read.

MIDDLEWARE

Middleware is a function that runs around your handler. It receives the request and response, plus a next() function that runs whatever comes after it. Middleware can do work before next() (check a token), after it (add a header), or skip next() entirely and answer on its own.

A HttpMiddlewarePipeline holds a list of middleware in order. use() adds one, execute(request, response) runs them all and returns the final response.

This pipeline has three steps: an auth check that runs first, a timer that adds a header, and a final step that produces the response. It runs without a server, which is also how you would unit-test it.

Without the authorization header the first middleware answers by itself, and the other two never run.

Wiring a pipeline into a server

Make the last middleware dispatch the router, then call the pipeline from your server handler.

Rules the pipeline enforces

• → Ordering is by priority (lowest first), then registration order.
• → Calling next() twice throws HttpMiddlewareError.
• → A middleware that throws stops the chain, and the error propagates unchanged: an outer middleware's await next() rejects with it, and so does execute(). Code after await next() does not run unless the middleware catches. The pipeline's onError option can return a recovery response; if onError throws, its own error propagates. See When a middleware throws.
• → use() returns a function that removes the middleware. enable(id) / disable(id) toggle one by id.

When a middleware throws

An error thrown by a middleware or a handler travels back up the chain as the error that was thrown. Every middleware that is waiting on await next() gets it, and if nobody catches it, the server's errorHandler gets it too. So isHttpError(error), error.statusCode and instanceof checks work wherever you catch it.

This middleware turns a 404 thrown further down into a JSON reply and lets every other error continue upward:

Remember that a middleware's code after await next() is skipped when the chain below it throws. Work that must always happen, such as logging how long a request took, belongs in a finally block:

Guards that refuse a request

A guard is a middleware that decides whether a request may go on: is the caller logged in, allowed to do this, asking for their own account? When the answer is no, the guard answers the request itself with a refusal such as 401 or 403, and the handler never runs.

To refuse, return createGuardResponse({ status, body?, headers? }) from @zudojs/middleware instead of calling next(). The router, HttpMiddlewarePipeline and RouteDispatcher send it with its own status, headers and body; a structured body goes out as JSON. This guard only lets a user read their own account, using the route parameter:

In route middleware, headers an outer middleware set on ctx.response before calling next() (CORS headers, for instance) are kept on the refusal. The ready-made guards in other packages use the same contract: @zudojs/permissions' authorize() and @zudojs/tenancy's middleware return a guard response for every 401, 403 and 404, so they drop straight into a route's middleware list.

Built-in guards

• → Requests whose path has . / .. / %2e%2e segments or backslashes are answered 400. Repeated slashes are collapsed once, where the request-target is parsed, so request.path and the router both see //admin/secret as /admin/secret and a guard can no longer disagree with the route it protects. An origin-form target is still never parsed as an authority.
• → createPathMiddleware(path, middleware, { caseSensitive? }) ignores case and trailing slashes by default, matching the router.
• → createRateLimitMiddleware({ max, windowMs }) answers 429 with a JSON body ({"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests"}}, sent as application/json; it used to be text/plain) and always a Retry-After header, even when a custom limiter handler leaves it out. Requests with no usable client address share one bucket (UNKNOWN_CLIENT_RATE_LIMIT_IP, 0.0.0.0); they are never unlimited and never a 500.
• → parseSignedCookie(value, secret, name) verifies a signed cookie; signatures are compared with @zudojs/crypto timingSafeEqualString.
• → The built-in createCorsMiddleware, createSecurityMiddleware and createTimingMiddleware return a cloned HttpResponseContext, so status and body survive.
• → createSecurityMiddleware() with no options emits the package's declared baseline (createDefaultSecurityHeaderOptions): Content-Security-Policy, Strict-Transport-Security, Permissions-Policy, the cross-origin isolation headers and X-Permitted-Cross-Domain-Policies on top of nosniff, X-Frame-Options and Referrer-Policy. Explicit options layer over it; useDefaults: false emits only what you configure. Before v1.3.0 it emitted three headers.
• → createLoggingMiddleware({ includeHeaders: true }) redacts credential headers — authorization, proxy-authorization, cookie, set-cookie and the rest of the @zudojs/logger secret-field set — before the record reaches the logger. Add your own names with redactHeaders.
• → guardRequest's default requestIdPattern accepts 1–128 characters of [A-Za-z0-9._:-], the same rule used to reuse an incoming id. It used to refuse ids containing . or : with 400.
• → guardRequest applies maxHeaderValueSize and the CRLF filter to array-valued headers (set-cookie, and any header supplied as a list) as well as to single values.
• → Stock adapters give each context a redacting @zudojs/logger console logger named http when you supply none.

ERRORS

When a handler throws an HttpError (notFound(), unauthorized(), …), the adapter answers with that error's status, its exposed message and code, and its headers — even when it was thrown inside the middleware pipeline. Any other error answers 500 with the body {"error":"Internal Server Error"}; messages and stacks never reach the client. Errors from the middleware pipeline reach the errorHandler unwrapped (see When a middleware throws); when you wrap an error yourself, the outermost error that carries a status answers the request.

HttpError is an error that carries a status code. The factory functions (notFound(), badRequest(), unauthorized(), and so on) create one with the right code. An errorHandler on the adapter or server turns it into a response.

This handler throws a 404, and the error handler converts any HttpError into a JSON reply while keeping unknown errors hidden.

If the error handler itself throws, the adapter falls back to the plain 500.

Every HttpError has a code, a short machine-readable name clients can match on. The factories set it for you (notFound() gives "NOT_FOUND"). new HttpError(status, message) without a code option now derives it from the status the same way, instead of the generic "ERR_OPERATION_FAILED" it used to get. Without an errorHandler, the adapter's default reply includes it:

OPENAPI FROM YOUR ROUTES

An OpenAPI document is a JSON file that describes every endpoint of an HTTP API: its path, method, inputs and responses. Tools read it to show browsable docs, generate client code, or check the API in CI. Writing it by hand means keeping a second list of routes in sync with the real one, and it drifts.

Here the document is generated from the routes the router actually registered. A route documents itself through the openapi route option; schemas may be @zudojs/schema schemas or raw OpenAPI schema objects. The generation itself is done by @zudojs/openapi.

Dispatch the router from a server as in Router, then open http://127.0.0.1:3000/docs to browse the API. The routes mountOpenAPI adds are hidden from the document themselves, and the document follows the router: a route registered later appears on the next request to /openapi.json.

What the openapi route option takes

How route paths become OpenAPI paths

OpenAPI writes path parameters as {id} and has no optional or wildcard segments, so each router pattern is translated:

Left out of the document: all() routes, CONNECT, routes with openapi: false or { hidden: true }, and anything matched by exclude (an exact path, "/internal/*", a RegExp, or a predicate). The router's automatic HEAD and OPTIONS answers are not registered routes, so they never appear. With undocumented: "exclude", only routes that declare openapi are documented.

Options

Pass onRouteWarning(message) to hear about routes the document can't describe well: duplicates, and routes that document no responses. Earlier releases gave such a route an invented "200": { description: "OK" }, which documented a 204 DELETE as 200.

Adding responses: { "204": { description: "Deleted" } } to the route silences the warning.

mountOpenAPI returns { document(), unmount() }. createRouterOpenAPI(router, options) gives you the underlying OpenAPIManager, rebuilt only when the route table changes.

MOUNTING WEB-STANDARD HANDLERS

A fetch handler is a function that takes a web-standard Request and returns a Response (or a promise of one). It is the shape Bun, Deno and edge runtimes use, and it is what other Zudo packages hand you: createRPCFetchHandler from @zudojs/rpc and createApiFetchHandler from @zudojs/api.

mountFetchHandler(router, basePath, handler, options?) serves one under a path of a router or router group, with no glue code:

The handler sees the original method, query, headers (connection-scoped ones removed) and body. If an earlier middleware already parsed the body into an object, it is re-encoded as JSON and labelled content-type: application/json (unless the request already had a JSON content type), so the handler never receives JSON text under a form or text label. By default the mount path is stripped from its URL and passed along as x-forwarded-prefix, which is why /hello/world arrives as /world. So a handler that has its own base path setting, such as createApiFetchHandler's basePath, should leave it unset. The returned function removes the mount again.

The Response is streamed back with its status, status text and headers intact, and several Set-Cookie headers stay separate instead of being folded into one broken header. A handler that throws, or returns something that is not a Response, fails the request like any route: a generic 500 unless the error carries a status.

Pinning the origin

A web Request always has an absolute URL, such as https://api.example.com/users, but a request arriving over HTTP only carries the path. The scheme and host part, the origin, has to come from somewhere. Without the origin option it comes from the Host header, and the client chooses what that header says. A handler that builds absolute URLs from request.url (a redirect, a password-reset or OAuth callback link) or compares a request's Origin header with its own origin can then be steered to an attacker's host. Set origin to your public origin whenever the handler does either:

When set, the option is used for every request, whatever Host says. Before this release it was only a fallback for requests with no usable host, so the client's header always won. Read the value from configuration rather than hard-coding it, so each environment serves its own origin.

toWebRequest(context, options?) does the request conversion on its own, if you want to call a fetch handler from inside a normal route. It takes the same origin option with the same meaning, plus url, headers and signal.

HTTP CLIENT

HttpClient sends requests to other servers. It wraps the global fetch and adds a base URL, default headers, timeouts, retries with backoff, and interceptors. The response body is parsed for you based on its content-type.

This creates a client and fetches one user. A non-2xx status throws HttpClientError, so success and failure are separated by try/catch.

To send data, pass method and body. A plain object body is turned into JSON with the right content-type.

Request options

Retries and backoff

A retry sends a failed request again after a short wait. It rescues requests that failed for a passing reason, such as a busy server or a dropped connection. Retries are off until you set retries (how many extra attempts after the first).

This example starts a small test server that is slow only on its first request. The first attempt hits the 100 ms timeout, the client waits and tries again, and the second attempt succeeds. The POST is not retried, because a request that timed out may already have been carried out, and sending it again could, say, create the record twice.

client.addRequestInterceptor(fn), addResponseInterceptor(fn), and addErrorInterceptor(fn) register functions that see every request, response, or error. Each returns a function that removes the interceptor.

CORS & SECURITY HEADERS

CORS is the browser rule that a page on one site may only call your API if your response says that site is allowed. The browser sends an Origin header; you answer with Access-Control-Allow-Origin. Some requests are preceded by an OPTIONS preflight asking for permission first.

evaluateCors takes the relevant request headers and your policy and returns the headers to send, whether the request is a preflight, and whether it is allowed. createRecommendedSecurityHeaders returns a safe default set of browser security headers. This middleware applies both.

Register protect on a pipeline with a low priority so it wraps everything else. What evaluateCors returns for an allowed and a rejected origin:

CORS options

createRecommendedSecurityHeaders() with no options emits Content-Security-Policy, Strict-Transport-Security, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy, a deny-by-default Permissions-Policy, and the cross-origin isolation headers. Pass false for csp, hsts, permissionsPolicy, or crossOriginPolicies to drop one.

API REFERENCE

The exports you will actually call. The package exports many more low-level helpers (header parsing, status code tables, cookie serialization, streaming); browse the TypeScript types for those.

Functions

Classes

Types

Errors

Constants

COMMON MISTAKES

• → Importing createHTTPServer or createHttpClient. Neither exists. The server factory is createHttpServer and it requires an adapter; the client is new HttpClient(options).
• → Calling client.get(url). The client has one method, request(url, config). Pass method: "POST" in the config for other verbs.
• → Passing port to createHttpServer. It is silently ignored by JavaScript and rejected by TypeScript. Put host, port, and trustProxy on createNodeHttpAdapter.
• → Expecting request.body to be parsed. It is a Uint8Array. Decode with new TextDecoder().decode(body) and JSON.parse it yourself.
• → Expecting the router to run by itself. Nothing calls it until your handler does router.dispatch(request) and returns result.response.
• → Refusing a request by returning { status: 403, body } from middleware. A plain object is ordinary data, not a response. Return createGuardResponse({ status: 403, body }) from @zudojs/middleware so the client really gets a 403.
• → Unwrapping error.cause in an errorHandler. Since v1.4.0 the handler receives the error that was thrown, not a pipeline wrapper. Check isHttpError(error) or instanceof on it directly.
• → Building links from request.url in a mounted handler without origin. The host part then comes from the client's Host header, so a reset or callback link can point at another site. Pass mountFetchHandler(router, path, handler, { origin }) with your public origin.

RELATED PACKAGES

• → @zudojs/errors — the base classes behind HttpError, HttpClientError, and the server errors.
• → @zudojs/api — define operations once; mount createApiFetchHandler here with mountFetchHandler.
• → @zudojs/rpc — typed procedure calls; mount createRPCFetchHandler here the same way.
• → @zudojs/openapi — the generator behind generateOpenAPIDocument, and the full route metadata shape.
• → @zudojs/security — rate limiting and input validation to run inside middleware.
• → @zudojs/logger — structured logging for request and response events.
• → @zudojs/core — application lifecycle so the server starts and stops with the rest of your app.

COMPLETE EXPORT INDEX

Every name @zudojs/http exports from its package root at v1.4.0 — 1739 in total, generated from the package’s own entry point rather than written by hand. The sections above explain the ones you reach for most; this is the exhaustive list, so nothing shipped is undocumented. Names not covered above are typically internal helpers and supporting types.