@atproto/lex-server 0.0.8 → 0.0.9

package/dist/nodejs.d.ts

@@ -1,34 +1,312 @@
 import { IncomingMessage, Server as HttpServer, ServerOptions, ServerResponse } from 'node:http';
 import { ListenOptions } from 'node:net';
 import { FetchHandler } from './lex-server.js';
+/**
+ * Upgrades an HTTP request to a WebSocket connection for Node.js.
+ *
+ * This function must be passed to the {@link LexRouter} constructor to enable
+ * subscription (WebSocket) support on Node.js. It creates a WebSocket instance
+ * and a placeholder response that signals the need for protocol upgrade.
+ *
+ * The actual upgrade is handled internally when the response is sent through
+ * {@link sendResponse}.
+ *
+ * @param request - The incoming HTTP request to upgrade
+ * @returns An object containing the WebSocket and upgrade response
+ * @throws {TypeError} If the request is not a valid WebSocket upgrade request
+ *
+ * @example
+ * ```typescript
+ * import { LexRouter } from '@atproto/lex-server'
+ * import { upgradeWebSocket } from '@atproto/lex-server/nodejs'
+ *
+ * // Pass to router for subscription support
+ * const router = new LexRouter({ upgradeWebSocket })
+ *
+ * // Now you can add subscription handlers
+ * router.add(subscribeRepos, async function* (ctx) {
+ *   for await (const event of eventStream) {
+ *     yield event
+ *   }
+ * })
+ * ```
+ */
 export declare function upgradeWebSocket(request: Request): {
     response: Response;
     socket: WebSocket;
 };
+/**
+ * Sends a fetch API Response through a Node.js ServerResponse.
+ *
+ * Handles both regular HTTP responses and WebSocket upgrades. For WebSocket
+ * upgrades (status 101), delegates to the WebSocket upgrade handler.
+ *
+ * This function is used internally by {@link toRequestListener} and
+ * {@link createServer}, but can be used directly for custom integrations.
+ *
+ * @param req - The Node.js IncomingMessage
+ * @param res - The Node.js ServerResponse to write to
+ * @param response - The fetch API Response to send
+ * @throws {TypeError} If headers have already been sent
+ *
+ * @example
+ * ```typescript
+ * import http from 'node:http'
+ * import { sendResponse } from '@atproto/lex-server/nodejs'
+ *
+ * const server = http.createServer(async (req, res) => {
+ *   const response = new Response('Hello, World!', {
+ *     headers: { 'Content-Type': 'text/plain' }
+ *   })
+ *   await sendResponse(req, res, response)
+ * })
+ * ```
+ */
 export declare function sendResponse(req: IncomingMessage, res: ServerResponse, response: Response): Promise<void>;
+/**
+ * Network address type for Node.js TCP connections.
+ *
+ * @example
+ * ```typescript
+ * const addr: NetAddr = {
+ *   transport: 'tcp',
+ *   hostname: '192.168.1.100',
+ *   port: 54321
+ * }
+ * ```
+ */
 export type NetAddr = {
+    /** Always 'tcp' for Node.js HTTP connections. */
     transport: 'tcp';
+    /** The IP address of the remote client. */
     hostname: string;
+    /** The port number of the remote client. */
     port: number;
 };
+/**
+ * Connection metadata for Node.js HTTP requests.
+ *
+ * Provides information about the client connection, including the remote
+ * address and a promise that resolves when the connection is fully closed
+ * (including WebSocket connections).
+ */
 export type NodeConnectionInfo = {
+    /** Promise that resolves when the connection is fully closed. */
     completed: Promise<void>;
+    /** The remote address of the client, if available. */
     remoteAddr: NetAddr | undefined;
 };
+/**
+ * Interface for objects that can handle fetch-style requests.
+ *
+ * Used by {@link createServer} and {@link serve} to accept either
+ * a fetch handler function or an object with a `fetch` method
+ * (like {@link LexRouter}).
+ */
 export interface HandlerObject {
+    /** The fetch handler method. */
     fetch: FetchHandler;
 }
+/**
+ * Converts a fetch-style handler to a Node.js request listener.
+ *
+ * The returned listener can be used with Node.js HTTP servers directly,
+ * or as middleware in frameworks like Express (supports the `next` callback).
+ *
+ * @typeParam Request - The request class type (default: IncomingMessage)
+ * @typeParam Response - The response class type (default: ServerResponse)
+ * @param fetchHandler - The fetch-style handler function
+ * @returns A Node.js RequestListener compatible with http.createServer
+ *
+ * @example Using as Express middleware
+ * ```typescript
+ * import express from 'express'
+ * import { toRequestListener } from '@atproto/lex-server/nodejs'
+ * import { LexRouter } from '@atproto/lex-server'
+ *
+ * const router = new LexRouter()
+ * // Register handlers...
+ *
+ * const app = express()
+ *
+ * // Mount the XRPC router
+ * app.use('/xrpc', toRequestListener(router.fetch))
+ * ```
+ */
 export declare function toRequestListener<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse<InstanceType<Request>> = typeof ServerResponse>(fetchHandler: FetchHandler): (req: InstanceType<Request>, res: InstanceType<Response> & {
     req: InstanceType<Request>;
 }, next?: (err?: unknown) => void) => void;
+/**
+ * Options for creating an XRPC server.
+ *
+ * Extends Node.js {@link ServerOptions} with additional options for graceful shutdown.
+ */
 export type CreateServerOptions<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse<InstanceType<Request>> = typeof ServerResponse> = ServerOptions<Request, Response> & {
+    /**
+     * Timeout in milliseconds for graceful termination.
+     *
+     * When `terminate()` is called, the server will wait up to this duration
+     * for active connections to complete before forcibly closing them.
+     */
     gracefulTerminationTimeout?: number;
 };
+/**
+ * Extended HTTP server with graceful shutdown support.
+ *
+ * Extends the standard Node.js HttpServer with a `terminate()` method
+ * for graceful shutdown and implements `AsyncDisposable` for use with
+ * `await using`.
+ *
+ * @typeParam Request - The request class type
+ * @typeParam Response - The response class type
+ *
+ * @example Graceful shutdown
+ * ```typescript
+ * const server = createServer(router)
+ * server.listen(3000)
+ *
+ * process.on('SIGTERM', async () => {
+ *   console.log('Shutting down...')
+ *   await server.terminate()
+ *   console.log('Server stopped')
+ * })
+ * ```
+ *
+ * @example Using with await using
+ * ```typescript
+ * await using server = await serve(router, { port: 3000 })
+ * // Server will be automatically terminated when scope exits
+ * ```
+ */
 export interface Server<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse<InstanceType<Request>> = typeof ServerResponse> extends HttpServer<Request, Response>, AsyncDisposable {
+    /**
+     * Gracefully terminates the server.
+     *
+     * Stops accepting new connections and waits for active connections
+     * to complete (up to `gracefulTerminationTimeout`).
+     *
+     * @returns Promise that resolves when the server is fully stopped
+     */
     terminate(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }
+/**
+ * Creates an HTTP server configured for XRPC request handling.
+ *
+ * The server includes graceful shutdown support and can be used with
+ * either a fetch handler function or an object with a `fetch` method
+ * (like {@link LexRouter}).
+ *
+ * Note: This creates the server but does not start listening. Call
+ * `server.listen()` to start the server, or use {@link serve} for
+ * a combined create-and-listen operation.
+ *
+ * @typeParam Request - The request class type
+ * @typeParam Response - The response class type
+ * @param handler - A fetch handler or object with fetch method
+ * @param options - Server configuration options
+ * @returns An HTTP server with graceful shutdown support
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { LexRouter } from '@atproto/lex-server'
+ * import { createServer, upgradeWebSocket } from '@atproto/lex-server/nodejs'
+ *
+ * const router = new LexRouter({ upgradeWebSocket })
+ * router.add(myMethod, myHandler)
+ *
+ * const server = createServer(router)
+ * server.listen(3000, () => {
+ *   console.log('Server listening on port 3000')
+ * })
+ * ```
+ *
+ * @example With graceful termination timeout
+ * ```typescript
+ * const server = createServer(router, {
+ *   gracefulTerminationTimeout: 10000 // 10 seconds
+ * })
+ * ```
+ */
 export declare function createServer<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse<InstanceType<Request>> = typeof ServerResponse>(handler: FetchHandler | HandlerObject, options?: CreateServerOptions<Request, Response>): Server<Request, Response>;
+/**
+ * Combined options for creating and starting an XRPC server.
+ *
+ * Includes both server creation options and network listen options.
+ *
+ * @typeParam Request - The request class type
+ * @typeParam Response - The response class type
+ *
+ * @example
+ * ```typescript
+ * const options: StartServerOptions = {
+ *   port: 3000,
+ *   host: '0.0.0.0',
+ *   gracefulTerminationTimeout: 10000
+ * }
+ * ```
+ */
 export type StartServerOptions<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse<InstanceType<Request>> = typeof ServerResponse> = ListenOptions & CreateServerOptions<Request, Response>;
+/**
+ * Creates and starts an HTTP server, returning when it's ready to accept connections.
+ *
+ * This is a convenience function that combines {@link createServer} and `server.listen()`
+ * into a single async operation. The returned promise resolves once the server
+ * is actively listening.
+ *
+ * @typeParam Request - The request class type
+ * @typeParam Response - The response class type
+ * @param handler - A fetch handler or object with fetch method (like {@link LexRouter})
+ * @param options - Combined server and listen options
+ * @returns Promise resolving to the running server
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { LexRouter } from '@atproto/lex-server'
+ * import { serve, upgradeWebSocket } from '@atproto/lex-server/nodejs'
+ *
+ * const router = new LexRouter({ upgradeWebSocket })
+ *
+ * // Register handlers
+ * router.add(getProfile, async (ctx) => {
+ *   return { body: await db.getProfile(ctx.params.actor) }
+ * })
+ *
+ * // Start server on port 3000
+ * const server = await serve(router, { port: 3000 })
+ * console.log('Server listening on port 3000')
+ *
+ * // Graceful shutdown
+ * process.on('SIGTERM', () => server.terminate())
+ * process.on('SIGINT', () => server.terminate())
+ * ```
+ *
+ * @example With all options
+ * ```typescript
+ * const server = await serve(router, {
+ *   port: 3000,
+ *   host: '0.0.0.0',
+ *   gracefulTerminationTimeout: 15000,
+ * })
+ * ```
+ *
+ * @example Using with await using (auto-cleanup)
+ * ```typescript
+ * async function main() {
+ *   await using server = await serve(router, { port: 3000 })
+ *
+ *   // Server is running...
+ *   console.log('Server listening on port 3000')
+ *
+ *   // Wait for termination signal
+ *   await Promise.race([
+ *     once(process, 'SIGINT'),
+ *     once(process, 'SIGTERM'),
+ *   ])
+ *
+ *   // Server will be automatically terminated when scope exits
+ * }
+ * ```
+ */
 export declare function serve<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse<InstanceType<Request>> = typeof ServerResponse>(handler: FetchHandler | HandlerObject, options?: StartServerOptions<Request, Response>): Promise<Server<Request, Response>>;
 //# sourceMappingURL=nodejs.d.ts.map

package/dist/nodejs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nodejs.d.ts","sourceRoot":"","sources":["../src/nodejs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"nodejs.d.ts","sourceRoot":"","sources":["../src/nodejs.ts"],"names":[],"mappings":"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"}

package/dist/nodejs.js

@@ -19,6 +19,36 @@ function isUpgradeRequest(request, upgrade) {
         request.headers.get('connection')?.toLowerCase() === 'upgrade' &&
         request.headers.get('upgrade')?.toLowerCase() === upgrade);
 }
+/**
+ * Upgrades an HTTP request to a WebSocket connection for Node.js.
+ *
+ * This function must be passed to the {@link LexRouter} constructor to enable
+ * subscription (WebSocket) support on Node.js. It creates a WebSocket instance
+ * and a placeholder response that signals the need for protocol upgrade.
+ *
+ * The actual upgrade is handled internally when the response is sent through
+ * {@link sendResponse}.
+ *
+ * @param request - The incoming HTTP request to upgrade
+ * @returns An object containing the WebSocket and upgrade response
+ * @throws {TypeError} If the request is not a valid WebSocket upgrade request
+ *
+ * @example
+ * ```typescript
+ * import { LexRouter } from '@atproto/lex-server'
+ * import { upgradeWebSocket } from '@atproto/lex-server/nodejs'
+ *
+ * // Pass to router for subscription support
+ * const router = new LexRouter({ upgradeWebSocket })
+ *
+ * // Now you can add subscription handlers
+ * router.add(subscribeRepos, async function* (ctx) {
+ *   for await (const event of eventStream) {
+ *     yield event
+ *   }
+ * })
+ * ```
+ */
 function upgradeWebSocket(request) {
     if (!isUpgradeRequest(request, 'websocket')) {
         throw new TypeError('upgradeWebSocket() expects a WebSocket upgrade');
@@ -80,6 +110,33 @@ function handleWebSocketUpgrade(req, response) {
         req.emit(kUpgradeEvent, ws);
     });
 }
+/**
+ * Sends a fetch API Response through a Node.js ServerResponse.
+ *
+ * Handles both regular HTTP responses and WebSocket upgrades. For WebSocket
+ * upgrades (status 101), delegates to the WebSocket upgrade handler.
+ *
+ * This function is used internally by {@link toRequestListener} and
+ * {@link createServer}, but can be used directly for custom integrations.
+ *
+ * @param req - The Node.js IncomingMessage
+ * @param res - The Node.js ServerResponse to write to
+ * @param response - The fetch API Response to send
+ * @throws {TypeError} If headers have already been sent
+ *
+ * @example
+ * ```typescript
+ * import http from 'node:http'
+ * import { sendResponse } from '@atproto/lex-server/nodejs'
+ *
+ * const server = http.createServer(async (req, res) => {
+ *   const response = new Response('Hello, World!', {
+ *     headers: { 'Content-Type': 'text/plain' }
+ *   })
+ *   await sendResponse(req, res, response)
+ * })
+ * ```
+ */
 async function sendResponse(req, res, response) {
     // Invalid usage
     if (res.headersSent) {
@@ -211,6 +268,32 @@ function toConnectionInfo(req) {
             : undefined,
     };
 }
+/**
+ * Converts a fetch-style handler to a Node.js request listener.
+ *
+ * The returned listener can be used with Node.js HTTP servers directly,
+ * or as middleware in frameworks like Express (supports the `next` callback).
+ *
+ * @typeParam Request - The request class type (default: IncomingMessage)
+ * @typeParam Response - The response class type (default: ServerResponse)
+ * @param fetchHandler - The fetch-style handler function
+ * @returns A Node.js RequestListener compatible with http.createServer
+ *
+ * @example Using as Express middleware
+ * ```typescript
+ * import express from 'express'
+ * import { toRequestListener } from '@atproto/lex-server/nodejs'
+ * import { LexRouter } from '@atproto/lex-server'
+ *
+ * const router = new LexRouter()
+ * // Register handlers...
+ *
+ * const app = express()
+ *
+ * // Mount the XRPC router
+ * app.use('/xrpc', toRequestListener(router.fetch))
+ * ```
+ */
 function toRequestListener(fetchHandler) {
     return ((req, res, next) => {
         handleRequest(req, res, fetchHandler).catch((err) => {
@@ -229,6 +312,44 @@ function toRequestListener(fetchHandler) {
         });
     });
 }
+/**
+ * Creates an HTTP server configured for XRPC request handling.
+ *
+ * The server includes graceful shutdown support and can be used with
+ * either a fetch handler function or an object with a `fetch` method
+ * (like {@link LexRouter}).
+ *
+ * Note: This creates the server but does not start listening. Call
+ * `server.listen()` to start the server, or use {@link serve} for
+ * a combined create-and-listen operation.
+ *
+ * @typeParam Request - The request class type
+ * @typeParam Response - The response class type
+ * @param handler - A fetch handler or object with fetch method
+ * @param options - Server configuration options
+ * @returns An HTTP server with graceful shutdown support
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { LexRouter } from '@atproto/lex-server'
+ * import { createServer, upgradeWebSocket } from '@atproto/lex-server/nodejs'
+ *
+ * const router = new LexRouter({ upgradeWebSocket })
+ * router.add(myMethod, myHandler)
+ *
+ * const server = createServer(router)
+ * server.listen(3000, () => {
+ *   console.log('Server listening on port 3000')
+ * })
+ * ```
+ *
+ * @example With graceful termination timeout
+ * ```typescript
+ * const server = createServer(router, {
+ *   gracefulTerminationTimeout: 10000 // 10 seconds
+ * })
+ * ```
+ */
 function createServer(handler, options = {}) {
     const fetchHandler = typeof handler === 'function' ? handler : handler.fetch.bind(handler);
     const listener = toRequestListener(fetchHandler);
@@ -258,6 +379,67 @@ function createServer(handler, options = {}) {
     });
     return server;
 }
+/**
+ * Creates and starts an HTTP server, returning when it's ready to accept connections.
+ *
+ * This is a convenience function that combines {@link createServer} and `server.listen()`
+ * into a single async operation. The returned promise resolves once the server
+ * is actively listening.
+ *
+ * @typeParam Request - The request class type
+ * @typeParam Response - The response class type
+ * @param handler - A fetch handler or object with fetch method (like {@link LexRouter})
+ * @param options - Combined server and listen options
+ * @returns Promise resolving to the running server
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { LexRouter } from '@atproto/lex-server'
+ * import { serve, upgradeWebSocket } from '@atproto/lex-server/nodejs'
+ *
+ * const router = new LexRouter({ upgradeWebSocket })
+ *
+ * // Register handlers
+ * router.add(getProfile, async (ctx) => {
+ *   return { body: await db.getProfile(ctx.params.actor) }
+ * })
+ *
+ * // Start server on port 3000
+ * const server = await serve(router, { port: 3000 })
+ * console.log('Server listening on port 3000')
+ *
+ * // Graceful shutdown
+ * process.on('SIGTERM', () => server.terminate())
+ * process.on('SIGINT', () => server.terminate())
+ * ```
+ *
+ * @example With all options
+ * ```typescript
+ * const server = await serve(router, {
+ *   port: 3000,
+ *   host: '0.0.0.0',
+ *   gracefulTerminationTimeout: 15000,
+ * })
+ * ```
+ *
+ * @example Using with await using (auto-cleanup)
+ * ```typescript
+ * async function main() {
+ *   await using server = await serve(router, { port: 3000 })
+ *
+ *   // Server is running...
+ *   console.log('Server listening on port 3000')
+ *
+ *   // Wait for termination signal
+ *   await Promise.race([
+ *     once(process, 'SIGINT'),
+ *     once(process, 'SIGTERM'),
+ *   ])
+ *
+ *   // Server will be automatically terminated when scope exits
+ * }
+ * ```
+ */
 async function serve(handler, options) {
     const server = createServer(handler, options);
     server.listen(options);

package/dist/nodejs.js.map

@@ -1 +1 @@
-{"version":3,"file":"nodejs.js","sourceRoot":"","sources":["../src/nodejs.ts"],"names":[],"mappings":"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","sourcesContent":["import { once } from 'node:events'\nimport {\n  IncomingHttpHeaders,\n  IncomingMessage,\n  RequestListener,\n  Server as HttpServer,\n  ServerOptions,\n  ServerResponse,\n  createServer as createHttpServer,\n} from 'node:http'\nimport { ListenOptions } from 'node:net'\nimport { Readable } from 'node:stream'\nimport { pipeline } from 'node:stream/promises'\nimport { createHttpTerminator } from 'http-terminator'\nimport { WebSocket as WebSocketPonyfill, WebSocketServer } from 'ws'\nimport { FetchHandler } from './lex-server.js'\n\n// @ts-expect-error\nSymbol.asyncDispose ??= Symbol.for('Symbol.asyncDispose')\n\nconst kResponseWs = Symbol.for('@atproto/lex-server:WebSocket')\n\nfunction isUpgradeRequest(request: Request, upgrade: string): boolean {\n  return (\n    request.method === 'GET' &&\n    request.headers.get('connection')?.toLowerCase() === 'upgrade' &&\n    request.headers.get('upgrade')?.toLowerCase() === upgrade\n  )\n}\n\nexport function upgradeWebSocket(request: Request): {\n  response: Response\n  socket: WebSocket\n} {\n  if (!isUpgradeRequest(request, 'websocket')) {\n    throw new TypeError('upgradeWebSocket() expects a WebSocket upgrade')\n  }\n\n  // Placeholder response for WebSocket upgrade. The actual handling will happen\n  // through the handleWebSocketUpgrade function. Headers set on the response\n  // will be applied during the upgrade.\n  const response = new Response(null, { status: 200 })\n\n  // The Response constructor does not allow setting status 101, so we\n  // define it directly. The purpose of this response is just to signal\n  // that an upgrade is needed, and to carry any headers.\n  Object.defineProperty(response, 'status', {\n    value: 101,\n    enumerable: false,\n    configurable: false,\n    writable: false,\n  })\n\n  // @ts-expect-error\n  const socket: WebSocket = new WebSocketPonyfill(null, undefined, {\n    autoPong: true,\n  })\n\n  // Attach the WebSocket to the response for later retrieval\n  Object.defineProperty(response, kResponseWs, {\n    value: socket,\n    enumerable: false,\n    configurable: false,\n    writable: false,\n  })\n\n  return { response, socket }\n}\n\nconst kUpgradeEvent = Symbol.for('@atproto/lex-server:upgrade')\n\nfunction handleWebSocketUpgrade(\n  req: IncomingMessage,\n  response: Response,\n): void {\n  const ws = (response as { [kResponseWs]?: WebSocketPonyfill })[kResponseWs]\n  if (!ws) throw new TypeError('Response not created by upgradeWebSocket()')\n\n  // Create a one time use WebSocketServer to handle the upgrade\n  const wss = new WebSocketServer({\n    autoPong: true,\n    noServer: true,\n    clientTracking: false,\n    perMessageDeflate: true,\n    // @ts-expect-error\n    WebSocket: function () {\n      // Return the websocket that was created earlier instead of a new instance\n      return ws\n    },\n  })\n\n  // Apply headers that might have been set on the response object during\n  // handling. This will be called during wss.handleUpgrade().\n  wss.on('headers', (headers) => {\n    for (const [name, value] of response.headers) {\n      headers.push(`${name}: ${value}`)\n    }\n  })\n\n  wss.handleUpgrade(req, req.socket, Buffer.alloc(0), (_socket) => {\n    // @TODO find a way to properly \"close\" the _socket when the server is\n    // shutting down (might require replacing http-terminator with a local\n    // implementation)\n\n    req.emit(kUpgradeEvent, ws)\n  })\n}\n\nexport async function sendResponse(\n  req: IncomingMessage,\n  res: ServerResponse,\n  response: Response,\n): Promise<void> {\n  // Invalid usage\n  if (res.headersSent) {\n    throw new TypeError('Response has already been sent')\n  }\n\n  if (response.status === 101) {\n    return handleWebSocketUpgrade(req, response)\n  }\n\n  res.statusCode = response.status\n  res.statusMessage = response.statusText\n\n  for (const [key, value] of response.headers) {\n    res.setHeader(key, value)\n  }\n\n  if (response.body != null && req.method !== 'HEAD') {\n    const stream = Readable.fromWeb(response.body as any)\n    await pipeline(stream, res)\n  } else {\n    await response.body?.cancel()\n    res.end()\n  }\n}\n\nfunction toRequest(req: IncomingMessage): Request {\n  const host = req.headers.host ?? req.socket?.localAddress ?? 'localhost'\n  const isEncrypted = (req.socket as any).encrypted === true\n  const protocol = isEncrypted ? 'https' : 'http'\n  const url = new URL(req.url ?? '/', `${protocol}://${host}`)\n  const headers = toHeaders(req.headers)\n  const body = toBody(req)\n  const signal = requestSignal(req)\n\n  return new Request(url, {\n    signal,\n    method: req.method,\n    headers,\n    body,\n    referrer: headers.get('referrer') ?? headers.get('referer') ?? undefined,\n    redirect: 'manual',\n    // @ts-expect-error\n    duplex: body ? 'half' : undefined,\n  })\n}\n\nfunction requestSignal(req: IncomingMessage): AbortSignal {\n  if (req.destroyed) return AbortSignal.abort()\n\n  const abortController = new AbortController()\n\n  const abort = (err?: Error | WebSocket) => {\n    abortController.abort(err instanceof Error ? err : undefined)\n\n    req.off('close', abort)\n    req.off('error', abort)\n    req.off('end', abort)\n    req.off(kUpgradeEvent, abort)\n  }\n\n  req.on('close', abort)\n  req.on('error', abort)\n  req.on('end', abort)\n  req.on(kUpgradeEvent, abort)\n\n  return abortController.signal\n}\n\nfunction requestCompletion(req: IncomingMessage): Promise<void> {\n  if (req.destroyed) return Promise.resolve()\n\n  // Unlike the abort signal, we complete the promise only when the request\n  // is fully done, accounting for websocket upgrade.\n  return new Promise((resolve) => {\n    const cleanup = () => {\n      req.off('close', done)\n      req.off('error', done)\n      req.off('end', done)\n      req.off(kUpgradeEvent, onUpgrade)\n    }\n\n    const onUpgrade = (ws: WebSocket) => {\n      cleanup()\n      ws.addEventListener('close', () => resolve())\n    }\n\n    const done = () => {\n      resolve()\n      cleanup()\n    }\n\n    req.on('close', done)\n    req.on('error', done)\n    req.on('end', done)\n    req.on(kUpgradeEvent, onUpgrade)\n  })\n}\n\nfunction toHeaders(headers: IncomingHttpHeaders): Headers {\n  const result = new Headers()\n  for (const [key, value] of Object.entries(headers)) {\n    if (value === undefined) continue\n    if (Array.isArray(value)) {\n      for (const v of value) result.append(key, v)\n    } else {\n      result.set(key, value)\n    }\n  }\n  return result\n}\n\nfunction toBody(req: IncomingMessage): null | ReadableStream<Uint8Array> {\n  if (\n    req.method === 'GET' ||\n    req.method === 'HEAD' ||\n    req.method === 'OPTIONS'\n  ) {\n    return null\n  }\n\n  if (\n    req.headers['content-type'] == null &&\n    req.headers['transfer-encoding'] == null &&\n    req.headers['content-length'] == null\n  ) {\n    return null\n  }\n\n  return Readable.toWeb(req) as ReadableStream<Uint8Array>\n}\n\nexport type NetAddr = {\n  transport: 'tcp'\n  hostname: string\n  port: number\n}\n\nexport type NodeConnectionInfo = {\n  completed: Promise<void>\n  remoteAddr: NetAddr | undefined\n}\n\nexport interface HandlerObject {\n  fetch: FetchHandler\n}\n\nasync function handleRequest(\n  req: IncomingMessage,\n  res: ServerResponse,\n  fetchHandler: FetchHandler,\n) {\n  const request = toRequest(req)\n  const info = toConnectionInfo(req)\n  const response = await fetchHandler(request, info)\n  await sendResponse(req, res, response)\n}\n\nfunction toConnectionInfo(req: IncomingMessage): NodeConnectionInfo {\n  const { socket } = req\n\n  return {\n    completed: requestCompletion(req),\n    remoteAddr:\n      socket.remoteAddress != null\n        ? {\n            transport: 'tcp',\n            hostname: socket.remoteAddress,\n            port: socket.remotePort!,\n          }\n        : undefined,\n  }\n}\n\nexport function toRequestListener<\n  Request extends typeof IncomingMessage = typeof IncomingMessage,\n  Response extends typeof ServerResponse<\n    InstanceType<Request>\n  > = typeof ServerResponse,\n>(fetchHandler: FetchHandler) {\n  return ((\n    req: InstanceType<Request>,\n    res: InstanceType<Response> & { req: InstanceType<Request> },\n    next?: (err?: unknown) => void,\n  ): void => {\n    handleRequest(req, res, fetchHandler).catch((err) => {\n      if (next) next(err)\n      else {\n        if (!res.headersSent) {\n          res.statusCode = 500\n          res.setHeader('content-type', 'text/plain; charset=utf-8')\n          res.end('Internal Server Error')\n        } else if (!res.writableEnded) {\n          res.destroy()\n        }\n      }\n    })\n  }) satisfies RequestListener<Request, Response>\n}\n\nexport type CreateServerOptions<\n  Request extends typeof IncomingMessage = typeof IncomingMessage,\n  Response extends typeof ServerResponse<\n    InstanceType<Request>\n  > = typeof ServerResponse,\n> = ServerOptions<Request, Response> & {\n  gracefulTerminationTimeout?: number\n}\n\nexport interface Server<\n  Request extends typeof IncomingMessage = typeof IncomingMessage,\n  Response extends typeof ServerResponse<\n    InstanceType<Request>\n  > = typeof ServerResponse,\n> extends HttpServer<Request, Response>,\n    AsyncDisposable {\n  terminate(): Promise<void>\n  [Symbol.asyncDispose](): Promise<void>\n}\n\nexport function createServer<\n  Request extends typeof IncomingMessage = typeof IncomingMessage,\n  Response extends typeof ServerResponse<\n    InstanceType<Request>\n  > = typeof ServerResponse,\n>(\n  handler: FetchHandler | HandlerObject,\n  options: CreateServerOptions<Request, Response> = {},\n): Server<Request, Response> {\n  const fetchHandler =\n    typeof handler === 'function' ? handler : handler.fetch.bind(handler)\n\n  const listener = toRequestListener(fetchHandler)\n  const server = createHttpServer(options, listener)\n\n  const terminator = createHttpTerminator({\n    server: server as HttpServer,\n    gracefulTerminationTimeout: options?.gracefulTerminationTimeout,\n  })\n\n  const terminate = async function terminate(this: Server<Request, Response>) {\n    if (this !== server) {\n      throw new TypeError('Server.terminate called with incorrect context')\n    }\n    // @TODO properly close all active WebSocket connections\n    return terminator.terminate()\n  }\n\n  Object.defineProperty(server, 'terminate', {\n    value: terminate,\n    enumerable: false,\n    configurable: false,\n    writable: false,\n  })\n\n  Object.defineProperty(server, Symbol.asyncDispose, {\n    value: terminate,\n    enumerable: false,\n    configurable: false,\n    writable: false,\n  })\n\n  return server as Server<Request, Response>\n}\n\nexport type StartServerOptions<\n  Request extends typeof IncomingMessage = typeof IncomingMessage,\n  Response extends typeof ServerResponse<\n    InstanceType<Request>\n  > = typeof ServerResponse,\n> = ListenOptions & CreateServerOptions<Request, Response>\n\nexport async function serve<\n  Request extends typeof IncomingMessage = typeof IncomingMessage,\n  Response extends typeof ServerResponse<\n    InstanceType<Request>\n  > = typeof ServerResponse,\n>(\n  handler: FetchHandler | HandlerObject,\n  options?: StartServerOptions<Request, Response>,\n): Promise<Server<Request, Response>> {\n  const server = createServer(handler, options)\n  server.listen(options)\n  await once(server, 'listening')\n  return server\n}\n"]}
+{"version":3,"file":"nodejs.js","sourceRoot":"","sources":["../src/nodejs.ts"],"names":[],"mappings":"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","sourcesContent":["import { once } from 'node:events'\nimport {\n  IncomingHttpHeaders,\n  IncomingMessage,\n  RequestListener,\n  Server as HttpServer,\n  ServerOptions,\n  ServerResponse,\n  createServer as createHttpServer,\n} from 'node:http'\nimport { ListenOptions } from 'node:net'\nimport { Readable } from 'node:stream'\nimport { pipeline } from 'node:stream/promises'\nimport { createHttpTerminator } from 'http-terminator'\nimport { WebSocket as WebSocketPonyfill, WebSocketServer } from 'ws'\nimport { FetchHandler } from './lex-server.js'\n\n// @ts-expect-error\nSymbol.asyncDispose ??= Symbol.for('Symbol.asyncDispose')\n\nconst kResponseWs = Symbol.for('@atproto/lex-server:WebSocket')\n\nfunction isUpgradeRequest(request: Request, upgrade: string): boolean {\n  return (\n    request.method === 'GET' &&\n    request.headers.get('connection')?.toLowerCase() === 'upgrade' &&\n    request.headers.get('upgrade')?.toLowerCase() === upgrade\n  )\n}\n\n/**\n * Upgrades an HTTP request to a WebSocket connection for Node.js.\n *\n * This function must be passed to the {@link LexRouter} constructor to enable\n * subscription (WebSocket) support on Node.js. It creates a WebSocket instance\n * and a placeholder response that signals the need for protocol upgrade.\n *\n * The actual upgrade is handled internally when the response is sent through\n * {@link sendResponse}.\n *\n * @param request - The incoming HTTP request to upgrade\n * @returns An object containing the WebSocket and upgrade response\n * @throws {TypeError} If the request is not a valid WebSocket upgrade request\n *\n * @example\n * ```typescript\n * import { LexRouter } from '@atproto/lex-server'\n * import { upgradeWebSocket } from '@atproto/lex-server/nodejs'\n *\n * // Pass to router for subscription support\n * const router = new LexRouter({ upgradeWebSocket })\n *\n * // Now you can add subscription handlers\n * router.add(subscribeRepos, async function* (ctx) {\n *   for await (const event of eventStream) {\n *     yield event\n *   }\n * })\n * ```\n */\nexport function upgradeWebSocket(request: Request): {\n  response: Response\n  socket: WebSocket\n} {\n  if (!isUpgradeRequest(request, 'websocket')) {\n    throw new TypeError('upgradeWebSocket() expects a WebSocket upgrade')\n  }\n\n  // Placeholder response for WebSocket upgrade. The actual handling will happen\n  // through the handleWebSocketUpgrade function. Headers set on the response\n  // will be applied during the upgrade.\n  const response = new Response(null, { status: 200 })\n\n  // The Response constructor does not allow setting status 101, so we\n  // define it directly. The purpose of this response is just to signal\n  // that an upgrade is needed, and to carry any headers.\n  Object.defineProperty(response, 'status', {\n    value: 101,\n    enumerable: false,\n    configurable: false,\n    writable: false,\n  })\n\n  // @ts-expect-error\n  const socket: WebSocket = new WebSocketPonyfill(null, undefined, {\n    autoPong: true,\n  })\n\n  // Attach the WebSocket to the response for later retrieval\n  Object.defineProperty(response, kResponseWs, {\n    value: socket,\n    enumerable: false,\n    configurable: false,\n    writable: false,\n  })\n\n  return { response, socket }\n}\n\nconst kUpgradeEvent = Symbol.for('@atproto/lex-server:upgrade')\n\nfunction handleWebSocketUpgrade(\n  req: IncomingMessage,\n  response: Response,\n): void {\n  const ws = (response as { [kResponseWs]?: WebSocketPonyfill })[kResponseWs]\n  if (!ws) throw new TypeError('Response not created by upgradeWebSocket()')\n\n  // Create a one time use WebSocketServer to handle the upgrade\n  const wss = new WebSocketServer({\n    autoPong: true,\n    noServer: true,\n    clientTracking: false,\n    perMessageDeflate: true,\n    // @ts-expect-error\n    WebSocket: function () {\n      // Return the websocket that was created earlier instead of a new instance\n      return ws\n    },\n  })\n\n  // Apply headers that might have been set on the response object during\n  // handling. This will be called during wss.handleUpgrade().\n  wss.on('headers', (headers) => {\n    for (const [name, value] of response.headers) {\n      headers.push(`${name}: ${value}`)\n    }\n  })\n\n  wss.handleUpgrade(req, req.socket, Buffer.alloc(0), (_socket) => {\n    // @TODO find a way to properly \"close\" the _socket when the server is\n    // shutting down (might require replacing http-terminator with a local\n    // implementation)\n\n    req.emit(kUpgradeEvent, ws)\n  })\n}\n\n/**\n * Sends a fetch API Response through a Node.js ServerResponse.\n *\n * Handles both regular HTTP responses and WebSocket upgrades. For WebSocket\n * upgrades (status 101), delegates to the WebSocket upgrade handler.\n *\n * This function is used internally by {@link toRequestListener} and\n * {@link createServer}, but can be used directly for custom integrations.\n *\n * @param req - The Node.js IncomingMessage\n * @param res - The Node.js ServerResponse to write to\n * @param response - The fetch API Response to send\n * @throws {TypeError} If headers have already been sent\n *\n * @example\n * ```typescript\n * import http from 'node:http'\n * import { sendResponse } from '@atproto/lex-server/nodejs'\n *\n * const server = http.createServer(async (req, res) => {\n *   const response = new Response('Hello, World!', {\n *     headers: { 'Content-Type': 'text/plain' }\n *   })\n *   await sendResponse(req, res, response)\n * })\n * ```\n */\nexport async function sendResponse(\n  req: IncomingMessage,\n  res: ServerResponse,\n  response: Response,\n): Promise<void> {\n  // Invalid usage\n  if (res.headersSent) {\n    throw new TypeError('Response has already been sent')\n  }\n\n  if (response.status === 101) {\n    return handleWebSocketUpgrade(req, response)\n  }\n\n  res.statusCode = response.status\n  res.statusMessage = response.statusText\n\n  for (const [key, value] of response.headers) {\n    res.setHeader(key, value)\n  }\n\n  if (response.body != null && req.method !== 'HEAD') {\n    const stream = Readable.fromWeb(response.body as any)\n    await pipeline(stream, res)\n  } else {\n    await response.body?.cancel()\n    res.end()\n  }\n}\n\nfunction toRequest(req: IncomingMessage): Request {\n  const host = req.headers.host ?? req.socket?.localAddress ?? 'localhost'\n  const isEncrypted = (req.socket as any).encrypted === true\n  const protocol = isEncrypted ? 'https' : 'http'\n  const url = new URL(req.url ?? '/', `${protocol}://${host}`)\n  const headers = toHeaders(req.headers)\n  const body = toBody(req)\n  const signal = requestSignal(req)\n\n  return new Request(url, {\n    signal,\n    method: req.method,\n    headers,\n    body,\n    referrer: headers.get('referrer') ?? headers.get('referer') ?? undefined,\n    redirect: 'manual',\n    // @ts-expect-error\n    duplex: body ? 'half' : undefined,\n  })\n}\n\nfunction requestSignal(req: IncomingMessage): AbortSignal {\n  if (req.destroyed) return AbortSignal.abort()\n\n  const abortController = new AbortController()\n\n  const abort = (err?: Error | WebSocket) => {\n    abortController.abort(err instanceof Error ? err : undefined)\n\n    req.off('close', abort)\n    req.off('error', abort)\n    req.off('end', abort)\n    req.off(kUpgradeEvent, abort)\n  }\n\n  req.on('close', abort)\n  req.on('error', abort)\n  req.on('end', abort)\n  req.on(kUpgradeEvent, abort)\n\n  return abortController.signal\n}\n\nfunction requestCompletion(req: IncomingMessage): Promise<void> {\n  if (req.destroyed) return Promise.resolve()\n\n  // Unlike the abort signal, we complete the promise only when the request\n  // is fully done, accounting for websocket upgrade.\n  return new Promise((resolve) => {\n    const cleanup = () => {\n      req.off('close', done)\n      req.off('error', done)\n      req.off('end', done)\n      req.off(kUpgradeEvent, onUpgrade)\n    }\n\n    const onUpgrade = (ws: WebSocket) => {\n      cleanup()\n      ws.addEventListener('close', () => resolve())\n    }\n\n    const done = () => {\n      resolve()\n      cleanup()\n    }\n\n    req.on('close', done)\n    req.on('error', done)\n    req.on('end', done)\n    req.on(kUpgradeEvent, onUpgrade)\n  })\n}\n\nfunction toHeaders(headers: IncomingHttpHeaders): Headers {\n  const result = new Headers()\n  for (const [key, value] of Object.entries(headers)) {\n    if (value === undefined) continue\n    if (Array.isArray(value)) {\n      for (const v of value) result.append(key, v)\n    } else {\n      result.set(key, value)\n    }\n  }\n  return result\n}\n\nfunction toBody(req: IncomingMessage): null | ReadableStream<Uint8Array> {\n  if (\n    req.method === 'GET' ||\n    req.method === 'HEAD' ||\n    req.method === 'OPTIONS'\n  ) {\n    return null\n  }\n\n  if (\n    req.headers['content-type'] == null &&\n    req.headers['transfer-encoding'] == null &&\n    req.headers['content-length'] == null\n  ) {\n    return null\n  }\n\n  return Readable.toWeb(req) as ReadableStream<Uint8Array>\n}\n\n/**\n * Network address type for Node.js TCP connections.\n *\n * @example\n * ```typescript\n * const addr: NetAddr = {\n *   transport: 'tcp',\n *   hostname: '192.168.1.100',\n *   port: 54321\n * }\n * ```\n */\nexport type NetAddr = {\n  /** Always 'tcp' for Node.js HTTP connections. */\n  transport: 'tcp'\n  /** The IP address of the remote client. */\n  hostname: string\n  /** The port number of the remote client. */\n  port: number\n}\n\n/**\n * Connection metadata for Node.js HTTP requests.\n *\n * Provides information about the client connection, including the remote\n * address and a promise that resolves when the connection is fully closed\n * (including WebSocket connections).\n */\nexport type NodeConnectionInfo = {\n  /** Promise that resolves when the connection is fully closed. */\n  completed: Promise<void>\n  /** The remote address of the client, if available. */\n  remoteAddr: NetAddr | undefined\n}\n\n/**\n * Interface for objects that can handle fetch-style requests.\n *\n * Used by {@link createServer} and {@link serve} to accept either\n * a fetch handler function or an object with a `fetch` method\n * (like {@link LexRouter}).\n */\nexport interface HandlerObject {\n  /** The fetch handler method. */\n  fetch: FetchHandler\n}\n\nasync function handleRequest(\n  req: IncomingMessage,\n  res: ServerResponse,\n  fetchHandler: FetchHandler,\n) {\n  const request = toRequest(req)\n  const info = toConnectionInfo(req)\n  const response = await fetchHandler(request, info)\n  await sendResponse(req, res, response)\n}\n\nfunction toConnectionInfo(req: IncomingMessage): NodeConnectionInfo {\n  const { socket } = req\n\n  return {\n    completed: requestCompletion(req),\n    remoteAddr:\n      socket.remoteAddress != null\n        ? {\n            transport: 'tcp',\n            hostname: socket.remoteAddress,\n            port: socket.remotePort!,\n          }\n        : undefined,\n  }\n}\n\n/**\n * Converts a fetch-style handler to a Node.js request listener.\n *\n * The returned listener can be used with Node.js HTTP servers directly,\n * or as middleware in frameworks like Express (supports the `next` callback).\n *\n * @typeParam Request - The request class type (default: IncomingMessage)\n * @typeParam Response - The response class type (default: ServerResponse)\n * @param fetchHandler - The fetch-style handler function\n * @returns A Node.js RequestListener compatible with http.createServer\n *\n * @example Using as Express middleware\n * ```typescript\n * import express from 'express'\n * import { toRequestListener } from '@atproto/lex-server/nodejs'\n * import { LexRouter } from '@atproto/lex-server'\n *\n * const router = new LexRouter()\n * // Register handlers...\n *\n * const app = express()\n *\n * // Mount the XRPC router\n * app.use('/xrpc', toRequestListener(router.fetch))\n * ```\n */\nexport function toRequestListener<\n  Request extends typeof IncomingMessage = typeof IncomingMessage,\n  Response extends typeof ServerResponse<\n    InstanceType<Request>\n  > = typeof ServerResponse,\n>(fetchHandler: FetchHandler) {\n  return ((\n    req: InstanceType<Request>,\n    res: InstanceType<Response> & { req: InstanceType<Request> },\n    next?: (err?: unknown) => void,\n  ): void => {\n    handleRequest(req, res, fetchHandler).catch((err) => {\n      if (next) next(err)\n      else {\n        if (!res.headersSent) {\n          res.statusCode = 500\n          res.setHeader('content-type', 'text/plain; charset=utf-8')\n          res.end('Internal Server Error')\n        } else if (!res.writableEnded) {\n          res.destroy()\n        }\n      }\n    })\n  }) satisfies RequestListener<Request, Response>\n}\n\n/**\n * Options for creating an XRPC server.\n *\n * Extends Node.js {@link ServerOptions} with additional options for graceful shutdown.\n */\nexport type CreateServerOptions<\n  Request extends typeof IncomingMessage = typeof IncomingMessage,\n  Response extends typeof ServerResponse<\n    InstanceType<Request>\n  > = typeof ServerResponse,\n> = ServerOptions<Request, Response> & {\n  /**\n   * Timeout in milliseconds for graceful termination.\n   *\n   * When `terminate()` is called, the server will wait up to this duration\n   * for active connections to complete before forcibly closing them.\n   */\n  gracefulTerminationTimeout?: number\n}\n\n/**\n * Extended HTTP server with graceful shutdown support.\n *\n * Extends the standard Node.js HttpServer with a `terminate()` method\n * for graceful shutdown and implements `AsyncDisposable` for use with\n * `await using`.\n *\n * @typeParam Request - The request class type\n * @typeParam Response - The response class type\n *\n * @example Graceful shutdown\n * ```typescript\n * const server = createServer(router)\n * server.listen(3000)\n *\n * process.on('SIGTERM', async () => {\n *   console.log('Shutting down...')\n *   await server.terminate()\n *   console.log('Server stopped')\n * })\n * ```\n *\n * @example Using with await using\n * ```typescript\n * await using server = await serve(router, { port: 3000 })\n * // Server will be automatically terminated when scope exits\n * ```\n */\nexport interface Server<\n  Request extends typeof IncomingMessage = typeof IncomingMessage,\n  Response extends typeof ServerResponse<\n    InstanceType<Request>\n  > = typeof ServerResponse,\n> extends HttpServer<Request, Response>,\n    AsyncDisposable {\n  /**\n   * Gracefully terminates the server.\n   *\n   * Stops accepting new connections and waits for active connections\n   * to complete (up to `gracefulTerminationTimeout`).\n   *\n   * @returns Promise that resolves when the server is fully stopped\n   */\n  terminate(): Promise<void>\n  [Symbol.asyncDispose](): Promise<void>\n}\n\n/**\n * Creates an HTTP server configured for XRPC request handling.\n *\n * The server includes graceful shutdown support and can be used with\n * either a fetch handler function or an object with a `fetch` method\n * (like {@link LexRouter}).\n *\n * Note: This creates the server but does not start listening. Call\n * `server.listen()` to start the server, or use {@link serve} for\n * a combined create-and-listen operation.\n *\n * @typeParam Request - The request class type\n * @typeParam Response - The response class type\n * @param handler - A fetch handler or object with fetch method\n * @param options - Server configuration options\n * @returns An HTTP server with graceful shutdown support\n *\n * @example Basic usage\n * ```typescript\n * import { LexRouter } from '@atproto/lex-server'\n * import { createServer, upgradeWebSocket } from '@atproto/lex-server/nodejs'\n *\n * const router = new LexRouter({ upgradeWebSocket })\n * router.add(myMethod, myHandler)\n *\n * const server = createServer(router)\n * server.listen(3000, () => {\n *   console.log('Server listening on port 3000')\n * })\n * ```\n *\n * @example With graceful termination timeout\n * ```typescript\n * const server = createServer(router, {\n *   gracefulTerminationTimeout: 10000 // 10 seconds\n * })\n * ```\n */\nexport function createServer<\n  Request extends typeof IncomingMessage = typeof IncomingMessage,\n  Response extends typeof ServerResponse<\n    InstanceType<Request>\n  > = typeof ServerResponse,\n>(\n  handler: FetchHandler | HandlerObject,\n  options: CreateServerOptions<Request, Response> = {},\n): Server<Request, Response> {\n  const fetchHandler =\n    typeof handler === 'function' ? handler : handler.fetch.bind(handler)\n\n  const listener = toRequestListener(fetchHandler)\n  const server = createHttpServer(options, listener)\n\n  const terminator = createHttpTerminator({\n    server: server as HttpServer,\n    gracefulTerminationTimeout: options?.gracefulTerminationTimeout,\n  })\n\n  const terminate = async function terminate(this: Server<Request, Response>) {\n    if (this !== server) {\n      throw new TypeError('Server.terminate called with incorrect context')\n    }\n    // @TODO properly close all active WebSocket connections\n    return terminator.terminate()\n  }\n\n  Object.defineProperty(server, 'terminate', {\n    value: terminate,\n    enumerable: false,\n    configurable: false,\n    writable: false,\n  })\n\n  Object.defineProperty(server, Symbol.asyncDispose, {\n    value: terminate,\n    enumerable: false,\n    configurable: false,\n    writable: false,\n  })\n\n  return server as Server<Request, Response>\n}\n\n/**\n * Combined options for creating and starting an XRPC server.\n *\n * Includes both server creation options and network listen options.\n *\n * @typeParam Request - The request class type\n * @typeParam Response - The response class type\n *\n * @example\n * ```typescript\n * const options: StartServerOptions = {\n *   port: 3000,\n *   host: '0.0.0.0',\n *   gracefulTerminationTimeout: 10000\n * }\n * ```\n */\nexport type StartServerOptions<\n  Request extends typeof IncomingMessage = typeof IncomingMessage,\n  Response extends typeof ServerResponse<\n    InstanceType<Request>\n  > = typeof ServerResponse,\n> = ListenOptions & CreateServerOptions<Request, Response>\n\n/**\n * Creates and starts an HTTP server, returning when it's ready to accept connections.\n *\n * This is a convenience function that combines {@link createServer} and `server.listen()`\n * into a single async operation. The returned promise resolves once the server\n * is actively listening.\n *\n * @typeParam Request - The request class type\n * @typeParam Response - The response class type\n * @param handler - A fetch handler or object with fetch method (like {@link LexRouter})\n * @param options - Combined server and listen options\n * @returns Promise resolving to the running server\n *\n * @example Basic usage\n * ```typescript\n * import { LexRouter } from '@atproto/lex-server'\n * import { serve, upgradeWebSocket } from '@atproto/lex-server/nodejs'\n *\n * const router = new LexRouter({ upgradeWebSocket })\n *\n * // Register handlers\n * router.add(getProfile, async (ctx) => {\n *   return { body: await db.getProfile(ctx.params.actor) }\n * })\n *\n * // Start server on port 3000\n * const server = await serve(router, { port: 3000 })\n * console.log('Server listening on port 3000')\n *\n * // Graceful shutdown\n * process.on('SIGTERM', () => server.terminate())\n * process.on('SIGINT', () => server.terminate())\n * ```\n *\n * @example With all options\n * ```typescript\n * const server = await serve(router, {\n *   port: 3000,\n *   host: '0.0.0.0',\n *   gracefulTerminationTimeout: 15000,\n * })\n * ```\n *\n * @example Using with await using (auto-cleanup)\n * ```typescript\n * async function main() {\n *   await using server = await serve(router, { port: 3000 })\n *\n *   // Server is running...\n *   console.log('Server listening on port 3000')\n *\n *   // Wait for termination signal\n *   await Promise.race([\n *     once(process, 'SIGINT'),\n *     once(process, 'SIGTERM'),\n *   ])\n *\n *   // Server will be automatically terminated when scope exits\n * }\n * ```\n */\nexport async function serve<\n  Request extends typeof IncomingMessage = typeof IncomingMessage,\n  Response extends typeof ServerResponse<\n    InstanceType<Request>\n  > = typeof ServerResponse,\n>(\n  handler: FetchHandler | HandlerObject,\n  options?: StartServerOptions<Request, Response>,\n): Promise<Server<Request, Response>> {\n  const server = createServer(handler, options)\n  server.listen(options)\n  await once(server, 'listening')\n  return server\n}\n"]}