# @askrjs/node

> Published API exports for @askrjs/node.

Source: [https://askrjs.com/docs/reference/api/node/root](https://askrjs.com/docs/reference/api/node/root)

Status: stable. Packages: @askrjs/node.

**Published packages are authoritative.** Examples may lag behind a published contract. When guidance differs, verify the exports and TypeScript declarations in your installed package, then file an issue.

## Exports

This entrypoint publishes 13 exports from the declarations shipped by @askrjs/node.

### `CLIENT_ADDRESS_HEADER`

```ts
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.

### `ConnectNext`

```ts
ConnectNext: (error?: unknown) => void
```

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

### `createNodeHandler`

```ts
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.

### `listen`

```ts
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.

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

### `ListeningServer`

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

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

### `ListenOptions`

```ts
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.

### `NodeHandler`

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

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

### `NodeHandlerOptions`

```ts
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.

### `NodeWebSocketOptions`

```ts
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.

### `normalizeClientAddress`

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

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

### `serve`

```ts
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`.

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

### `ServedApplication`

```ts
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.

### `ServeOptions`

```ts
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.

## Documentation navigation

[Previous](https://askrjs.com/docs/reference/api/monaco/testing/index.md) | [Next](https://askrjs.com/docs/reference/api/node/mcp/index.md)