@askrjs/node

CLIENT_ADDRESS_HEADERtype

CLIENT_ADDRESS_HEADER: "x-askr-client-address"

Reserved request header containing the TCP peer address authenticated by the Node adapter. Any value supplied by the HTTP client is overwritten before application dispatch.

ConnectNexttype

ConnectNext: (error?: unknown) => void

Connect/Express-style `next` callback used to hand off unhandled requests.

createNodeHandlertype

createNodeHandler: (app: ServerApp, options: NodeHandlerOptions) => NodeHandler

Wraps an `@askrjs/server` application as a Node-style request handler. Converts each incoming `IncomingMessage`/`ServerResponse` pair into a web `Request`, dispatches it through `app.fetch`, and writes the resulting web `Response` back to Node. Errors are reported to `next` when provided, otherwise a minimal 400/500 response is written directly.

listentype

listen: (app: ServerApp, options?: ListenOptions) => Promise<ListeningServer>

Starts a Node HTTP server for an `@askrjs/server` application and resolves once it is listening. Optionally installs WebSocket support and wires up graceful shutdown on `options.signal`. Unlike {@link serve}, this does not serve static assets or install OS signal handlers.

const server = await listen(app, { port: 3000 });

ListeningServertype

ListeningServer: Server & {
  address(): AddressInfo | string | null;
}

A Node HTTP server that is guaranteed to be listening for connections.

ListenOptionstype

ListenOptions: any

Options for {@link listen}, controlling how the Node HTTP server binds and behaves.

port

Port to listen on; defaults to an ephemeral port when omitted.

host

Host/address to bind to.

allowPublicBind

Allows binding to a non-loopback host without the usual safety check.

backlog

Maximum length of the queue of pending connections.

signal

Aborting this signal stops the server.

requestTimeout

Node HTTP server `requestTimeout`, enforced from server construction, in milliseconds.

headersTimeout

Node HTTP server `headersTimeout`, enforced from server construction, in milliseconds.

keepAliveTimeout

Node HTTP server `keepAliveTimeout`, in milliseconds.

websocket

Enables WebSocket support, optionally with detailed options.

NodeHandlertype

NodeHandler: (request: IncomingMessage, response: ServerResponse, next?: ConnectNext) => void

A Node-style request handler compatible with `http.Server` and Connect-style middleware chains.

NodeHandlerOptionstype

NodeHandlerOptions: any

Options shared by anything that turns Node HTTP requests into `@askrjs/server` fetch calls.

baseUrl

Base URL used to resolve request paths into absolute URLs.

allowedHosts

Hosts allowed in the request's `Host` header; requests for other hosts are rejected.

NodeWebSocketOptionstype

NodeWebSocketOptions: any

Options controlling how WebSocket upgrades are handled on a Node server.

closeTimeout

Milliseconds to wait for a peer to acknowledge a close handshake before the socket is force-closed.

maxPayload

Maximum allowed size, in bytes, of a single WebSocket message.

maxRejectionBodyBytes

Maximum number of body bytes read from a rejected upgrade request before the connection is destroyed.

perMessageDeflate

Enables or configures the permessage-deflate WebSocket extension.

allowedOrigins

Origins allowed to open a WebSocket connection; when omitted, all origins are allowed.

normalizeClientAddresstype

normalizeClientAddress: (address: string | undefined) => string

Normalizes the socket peer address used for the adapter-authenticated request header.

servetype

serve: (app: ServerApp & { close?: () => void | Promise<void>; }, options?: ServeOptions) => Promise<ServedApplication>

Serves an `@askrjs/server` application over Node HTTP, with optional static asset serving, WebSocket support, and graceful shutdown on OS signals or an abort signal. Requests for paths with a file extension are first checked against `options.assets.root` (path-traversal safe, following symlinks) and served directly with appropriate `content-type`/`cache-control` headers before falling back to the application handler. HTML responses from the application get a `no-cache` header when they don't already set `cache-control`.

const app = await serve(myApp, { port: 3000, assets: { root: "./public" } });
// ...
await app.close();

ServedApplicationtype

ServedApplication: any

A running application returned by {@link serve}.

server

The underlying Node HTTP server.

url

The base URL the server is listening on.

close

Gracefully shuts down the server, any WebSocket connections, and the application.

ServeOptionstype

ServeOptions: any

Options for {@link serve}, extending {@link ListenOptions} with static asset serving and shutdown behavior.

assets

Serves static files from this directory before falling back to the application.

signals

OS signals that trigger a graceful shutdown; pass `false` to disable automatic shutdown handling.