@askrjs/node 0.0.8 → 0.0.11

package/README.md

@@ -28,7 +28,21 @@ createServer(createNodeHandler(app, { baseUrl: "http://localhost:3000" })).liste
 
 `createNodeHandler` also works as Connect middleware because it accepts an optional `next`
 callback. It preserves streaming bodies, repeated `Set-Cookie` headers, aborts, backpressure,
-status text, and HEAD responses.
+status text, and HEAD responses. `next` receives adapter failures; application responses, including
+`404`, remain owned by the `ServerApp` and do not fall through.
+
+Every dispatched request includes `CLIENT_ADDRESS_HEADER` (`x-askr-client-address`) set from the
+TCP socket peer. The adapter overwrites a client-supplied value and does not interpret
+`X-Forwarded-For`, so applications can use this header for direct-listener IP controls without
+trusting attacker-controlled forwarding metadata. Deployments behind a reverse proxy see the
+proxy peer by default. Supporting original client addresses requires an explicit trusted-proxy
+boundary; do not read `X-Forwarded-For` directly in application code.
+
+Every handler must have a trusted URL boundary. Pass `baseUrl` when the external origin is fixed,
+or `allowedHosts` when the request `Host` determines the origin. Host names are canonicalized and
+compared case-insensitively; entries without a port allow that host on any port, while entries with
+a port require that exact authority. Absolute-form request targets must retain the trusted origin,
+and ambiguous network-path targets are rejected.
 
 ## Listen directly
 
@@ -48,8 +62,12 @@ Pass an `AbortSignal` to integrate shutdown with your process lifecycle.
 
 Enable the built-in `ws` transport with `websocket: true`. It defaults to a
 1 MiB maximum message payload with compression disabled; pass
-`websocket: { maxPayload, maxRejectionBodyBytes, perMessageDeflate }` to override
-those settings. Rejected upgrade bodies are capped at 64 KiB by default.
+`websocket: { closeTimeout, maxPayload, maxRejectionBodyBytes, perMessageDeflate }` to override
+those settings. Rejected upgrade bodies are capped at 64 KiB by default. Shutdown gives clients five
+seconds to complete the close handshake by default, then terminates any remaining connections.
+Upgrades require an `Origin`. The request origin is allowed by default; set
+`websocket.allowedOrigins` to a canonical allowlist when trusted browser origins differ from the
+application origin.
 
 ```ts
 router.ws("/echo", (socket) => {
@@ -77,8 +95,26 @@ await running.close();
 ```
 
 `serve` handles static assets and closes both the HTTP server and the application during shutdown.
+When an asset root is configured, extension-bearing `GET` and `HEAD` paths are reserved for static
+files: missing files return `404` without falling through to application routing, source maps are not
+served, and resolved files must remain inside the configured root. Fingerprinted files under
+`/assets/` receive immutable caching; other files receive `no-cache`.
 Both `listen` and `serve` bind to `127.0.0.1` by default. A non-loopback
-`host` also requires `allowPublicBind: true` so public exposure is explicit.
+`host` also requires `allowPublicBind: true` so public exposure is explicit. Public listeners should
+declare every external host name through `allowedHosts`; the bind host and `localhost` remain allowed
+automatically:
+
+```ts
+await serve(app, {
+  host: "0.0.0.0",
+  allowPublicBind: true,
+  allowedHosts: ["app.example.com"],
+});
+```
+
+`listen` and `serve` fail before binding when their `AbortSignal` is already aborted. Later aborts
+start shutdown. `serve().close()` is idempotent, waits for HTTP and WebSocket closure, and then closes
+the application exactly once.
 
 ## MCP over stdio
 
@@ -90,4 +126,6 @@ await connection.closed;
 ```
 
 Protocol messages use stdin/stdout; diagnostics remain isolated on stderr. Authentication may be
-provided directly or resolved from the process environment for each message.
+provided directly or resolved from the process environment for each message. Closing stdin, calling
+`connection.close()`, or aborting its signal detaches the transport, cancels active requests,
+terminates the MCP session, and prevents late protocol output.

package/dist/index.d.ts

@@ -1,55 +1,139 @@
+import { AddressInfo } from "node:net";
 import { IncomingMessage, Server, ServerResponse } from "node:http";
 import { PerMessageDeflateOptions } from "ws";
 import { ServerApp } from "@askrjs/server";
-import { AddressInfo } from "node:net";
+//#region src/client-address.d.ts
+/**
+ * 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.
+ */
+declare const CLIENT_ADDRESS_HEADER = "x-askr-client-address";
+/** Normalizes the socket peer address used for the adapter-authenticated request header. */
+declare function normalizeClientAddress(address: string | undefined): string;
+//#endregion
 //#region src/contracts.d.ts
+/** Options controlling how WebSocket upgrades are handled on a Node server. */
 interface NodeWebSocketOptions {
+  /** Milliseconds to wait for a peer to acknowledge a close handshake before the socket is force-closed. */
+  readonly closeTimeout?: number;
+  /** Maximum allowed size, in bytes, of a single WebSocket message. */
   readonly maxPayload?: number;
+  /** Maximum number of body bytes read from a rejected upgrade request before the connection is destroyed. */
   readonly maxRejectionBodyBytes?: number;
+  /** Enables or configures the permessage-deflate WebSocket extension. */
   readonly perMessageDeflate?: boolean | PerMessageDeflateOptions;
+  /** Origins allowed to open a WebSocket connection; when omitted, all origins are allowed. */
   readonly allowedOrigins?: readonly string[];
 }
+/** Options shared by anything that turns Node HTTP requests into `@askrjs/server` fetch calls. */
 interface NodeHandlerOptions {
-  baseUrl?: string;
-  allowedHosts?: readonly string[];
+  /** Base URL used to resolve request paths into absolute URLs. */
+  readonly baseUrl?: string;
+  /** Hosts allowed in the request's `Host` header; requests for other hosts are rejected. */
+  readonly allowedHosts?: readonly string[];
 }
-interface ListenOptions {
+/** Options for {@link listen}, controlling how the Node HTTP server binds and behaves. */
+interface ListenOptions extends NodeHandlerOptions {
+  /** Port to listen on; defaults to an ephemeral port when omitted. */
   port?: number;
+  /** Host/address to bind to. */
   host?: string;
+  /** Allows binding to a non-loopback host without the usual safety check. */
   allowPublicBind?: boolean;
+  /** Maximum length of the queue of pending connections. */
   backlog?: number;
+  /** Aborting this signal stops the server. */
   signal?: AbortSignal;
+  /** Node HTTP server `requestTimeout`, in milliseconds. */
   requestTimeout?: number;
+  /** Node HTTP server `headersTimeout`, in milliseconds. */
   headersTimeout?: number;
+  /** Node HTTP server `keepAliveTimeout`, in milliseconds. */
   keepAliveTimeout?: number;
+  /** Enables WebSocket support, optionally with detailed options. */
   websocket?: boolean | NodeWebSocketOptions;
 }
+/** Options for {@link serve}, extending {@link ListenOptions} with static asset serving and shutdown behavior. */
 interface ServeOptions extends ListenOptions {
+  /** Serves static files from this directory before falling back to the application. */
   readonly assets?: {
     readonly root: string;
   };
+  /** OS signals that trigger a graceful shutdown; pass `false` to disable automatic shutdown handling. */
   readonly signals?: false | readonly NodeJS.Signals[];
 }
+/** A running application returned by {@link serve}. */
 interface ServedApplication {
+  /** The underlying Node HTTP server. */
   readonly server: import("node:http").Server;
+  /** The base URL the server is listening on. */
   readonly url: string;
+  /** Gracefully shuts down the server, any WebSocket connections, and the application. */
   close(): Promise<void>;
 }
+/** Connect/Express-style `next` callback used to hand off unhandled requests. */
 type ConnectNext = (error?: unknown) => void;
+/** A Node-style request handler compatible with `http.Server` and Connect-style middleware chains. */
 type NodeHandler = (request: IncomingMessage, response: ServerResponse, next?: ConnectNext) => void;
 //#endregion
 //#region src/handler.d.ts
-declare function 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.
+ *
+ * @param app - The application to dispatch requests to.
+ * @param options - Options controlling base URL resolution and host validation.
+ * @returns A handler usable with `http.createServer` or Connect-style middleware.
+ */
+declare function createNodeHandler(app: ServerApp, options: NodeHandlerOptions): NodeHandler;
 //#endregion
 //#region src/listen.d.ts
+/** A Node HTTP server that is guaranteed to be listening for connections. */
 type ListeningServer = Server & {
   address(): AddressInfo | string | null;
 };
+/**
+ * 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.
+ *
+ * @param app - The application to serve.
+ * @param options - Listen options such as port, host, timeouts, and WebSocket support.
+ * @returns A promise resolving to the listening server once it has bound successfully.
+ * @example
+ * const server = await listen(app, { port: 3000 });
+ */
 declare function listen(app: ServerApp, options?: ListenOptions): Promise<ListeningServer>;
 //#endregion
 //#region src/serve.d.ts
+/**
+ * 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`.
+ *
+ * @param app - The application to serve; may expose an optional `close()` for cleanup.
+ * @param options - Serve options such as port, host, static assets, and shutdown signals.
+ * @returns The served application, including its bound `url` and a `close()` for shutdown.
+ * @example
+ * const app = await serve(myApp, { port: 3000, assets: { root: "./public" } });
+ * // ...
+ * await app.close();
+ */
 declare function serve(app: ServerApp & {
   close?: () => void | Promise<void>;
 }, options?: ServeOptions): Promise<ServedApplication>;
 //#endregion
-export { ConnectNext, ListenOptions, ListeningServer, NodeHandler, NodeHandlerOptions, NodeWebSocketOptions, ServeOptions, ServedApplication, createNodeHandler, listen, serve };
+export { CLIENT_ADDRESS_HEADER, ConnectNext, ListenOptions, ListeningServer, NodeHandler, NodeHandlerOptions, NodeWebSocketOptions, ServeOptions, ServedApplication, createNodeHandler, listen, normalizeClientAddress, serve };