@askrjs/node 0.0.9 → 0.0.11

package/README.md

@@ -31,6 +31,13 @@ callback. It preserves streaming bodies, repeated `Set-Cookie` headers, aborts,
 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

package/dist/index.d.ts

@@ -2,55 +2,138 @@ import { AddressInfo } from "node:net";
 import { IncomingMessage, Server, ServerResponse } from "node:http";
 import { PerMessageDeflateOptions } from "ws";
 import { ServerApp } from "@askrjs/server";
+//#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 {
+  /** 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[];
 }
+/** 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
+/**
+ * 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 };

package/dist/index.js

@@ -6,6 +6,22 @@ import { createReadStream } from "node:fs";
 import { realpath, stat } from "node:fs/promises";
 import { extname, resolve, sep } from "node:path";
 import { pipeline } from "node:stream";
+//#region src/client-address.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.
+*/
+const CLIENT_ADDRESS_HEADER = "x-askr-client-address";
+/** Normalizes the socket peer address used for the adapter-authenticated request header. */
+function normalizeClientAddress(address) {
+	if (!address) return "unknown";
+	if (address.toLowerCase().startsWith("::ffff:")) {
+		const mapped = address.slice(7);
+		if (isIP(mapped) === 4) return mapped;
+	}
+	return address;
+}
+//#endregion
 //#region src/request.ts
 var NodeRequestError = class extends TypeError {};
 function explicitPort(authority) {
@@ -69,6 +85,7 @@ function requestHeaders(request) {
 		if (Array.isArray(value)) for (const item of value) headers.append(key, item);
 		else headers.set(key, value);
 	}
+	headers.set(CLIENT_ADDRESS_HEADER, normalizeClientAddress(request.socket.remoteAddress));
 	return headers;
 }
 function resolveNodeRequestHref(request, options) {
@@ -255,6 +272,18 @@ async function handleNodeRequest(app, preparedOptions, request, response, signal
 		cleanup();
 	}
 }
+/**
+* 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.
+*/
 function createNodeHandler(app, options) {
 	const preparedOptions = prepareNodeHandlerOptions(options);
 	return (request, response, next) => {
@@ -499,6 +528,19 @@ function installWebSockets(server, app, options, handlerOptions) {
 }
 //#endregion
 //#region src/listen.ts
+/**
+* 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 });
+*/
 function listen(app, options = {}) {
 	options.signal?.throwIfAborted();
 	const host = resolveBindHost(options);
@@ -576,6 +618,26 @@ function isWithinRoot(root, candidate) {
 	const prefix = root.endsWith(sep) ? root : `${root}${sep}`;
 	return candidate === root || candidate.startsWith(prefix);
 }
+/**
+* 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();
+*/
 async function serve(app, options = {}) {
 	options.signal?.throwIfAborted();
 	const host = resolveBindHost(options);
@@ -711,4 +773,4 @@ async function serve(app, options = {}) {
 	});
 }
 //#endregion
-export { createNodeHandler, listen, serve };
+export { CLIENT_ADDRESS_HEADER, createNodeHandler, listen, normalizeClientAddress, serve };

package/dist/mcp.d.ts

@@ -2,21 +2,47 @@ import { Readable, Writable } from "node:stream";
 import { AuthContext } from "@askrjs/auth";
 import { McpServer } from "@askrjs/server/mcp";
 //#region src/mcp.d.ts
+/** Options for {@link connectMcpStdio}. */
 interface McpStdioOptions<Dependencies = undefined> {
+  /** Application dependencies passed through to each MCP request. */
   dependencies: Dependencies;
+  /** Stream to read newline-delimited JSON-RPC requests from; defaults to `process.stdin`. */
   input?: Readable;
+  /** Stream to write newline-delimited JSON-RPC responses to; defaults to `process.stdout`. */
   output?: Writable;
+  /** Stream that non-protocol errors are reported to; defaults to `process.stderr`. */
   diagnostics?: Writable;
+  /** Aborting this signal closes the connection. */
   signal?: AbortSignal;
+  /** Auth context to use for requests, or a function that derives one from the environment. */
   auth?: AuthContext | ((environment: NodeJS.ProcessEnv) => AuthContext | Promise<AuthContext>);
+  /** Environment passed to the `auth` function; defaults to `process.env`. */
   environment?: NodeJS.ProcessEnv;
+  /** Maximum size, in bytes, of a single input line before it is rejected; defaults to 1 MiB. */
   maxLineBytes?: number;
+  /** Maximum number of requests handled concurrently; defaults to 16. */
   maxConcurrency?: number;
 }
+/** A live MCP stdio connection returned by {@link connectMcpStdio}. */
 interface McpStdioConnection {
+  /** Resolves once the connection has fully closed. */
   readonly closed: Promise<void>;
+  /** Closes the connection, aborting in-flight requests and terminating the MCP session. */
   close(): Promise<void>;
 }
+/**
+ * Connects an MCP server to newline-delimited JSON-RPC over stdio (or any
+ * pair of readable/writable streams).
+ *
+ * Reads one JSON-RPC message per line, dispatches it to `mcp.handle`, and
+ * writes the response back as a line of JSON. Handles request cancellation
+ * notifications, enforces `maxConcurrency` and `maxLineBytes`, and cleans up
+ * the MCP session when the connection closes.
+ *
+ * @param mcp - The MCP server to dispatch requests to.
+ * @param options - Stdio connection options, including dependencies and stream overrides.
+ * @returns A handle exposing `closed` and `close()` for the connection's lifecycle.
+ */
 declare function connectMcpStdio<Dependencies>(mcp: McpServer<Dependencies>, options: McpStdioOptions<Dependencies>): McpStdioConnection;
 //#endregion
 export { McpStdioConnection, McpStdioOptions, connectMcpStdio };

package/dist/mcp.js

@@ -7,6 +7,19 @@ const anonymous = Object.freeze({
 	session: null,
 	tenant: null
 });
+/**
+* Connects an MCP server to newline-delimited JSON-RPC over stdio (or any
+* pair of readable/writable streams).
+*
+* Reads one JSON-RPC message per line, dispatches it to `mcp.handle`, and
+* writes the response back as a line of JSON. Handles request cancellation
+* notifications, enforces `maxConcurrency` and `maxLineBytes`, and cleans up
+* the MCP session when the connection closes.
+*
+* @param mcp - The MCP server to dispatch requests to.
+* @param options - Stdio connection options, including dependencies and stream overrides.
+* @returns A handle exposing `closed` and `close()` for the connection's lifecycle.
+*/
 function connectMcpStdio(mcp, options) {
 	const input = options.input ?? process.stdin;
 	const output = options.output ?? process.stdout;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askrjs/node",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Node http adapter for @askrjs/server",
   "keywords": [
     "askr",