@znight/http 0.0.0-stage → 0.1.0

package/src/adapters/node-io.ts

@@ -0,0 +1,368 @@
+/** Node.js `IncomingMessage` / `ServerResponse` helpers shared by the Node and Express adapters (internal). */
+import type { IncomingHttpHeaders, IncomingMessage, OutgoingHttpHeaders, Server, ServerResponse } from 'node:http'
+import type { Socket } from 'node:net'
+import type { AdapterReply, AdapterRequest } from '../adapter.ts'
+import type { HeaderValue } from '../exceptions.ts'
+
+import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+
+import { BadRequestException } from '../exceptions.ts'
+import { discardStream, failedStream } from '../stream.ts'
+import { concat, exceedsDeclaredLength, payloadTooLarge } from './shared.ts'
+
+/** Bytes buffered by a request body stream before the request is paused. */
+const BODY_HIGH_WATER_MARK = 64 * 1024
+
+/** Request headers with array values (only `set-cookie` in Node.js) joined with `, `. */
+export function normalizeNodeHeaders(headers: IncomingHttpHeaders): Record<string, string | undefined> {
+  for (const name in headers) {
+    if (typeof headers[name] !== 'string') return copyHeaders(headers)
+  }
+  return headers as Record<string, string | undefined>
+}
+
+function copyHeaders(headers: IncomingHttpHeaders): Record<string, string | undefined> {
+  const result: Record<string, string | undefined> = {}
+  for (const name in headers) {
+    const value = headers[name]
+    result[name] = Array.isArray(value) ? value.join(', ') : value
+  }
+  return result
+}
+
+/**
+ * Whether the body was already read by someone else: an Express body parser (`express.json()`...)
+ * marks the request with `_body`; otherwise a declared body that already ended.
+ */
+function consumedElsewhere(request: IncomingMessage): boolean {
+  if ((request as { _body?: unknown })._body === true) return true
+  if (!request.readableEnded) return false
+  const length = request.headers['content-length']
+  return request.headers['transfer-encoding'] !== undefined || (length !== undefined && length.trim() !== '0')
+}
+
+/** The error of a body consumed before Znight read it (an empty body would be silently wrong). */
+function consumedError(): Error {
+  return new Error(
+    'The request body was already read by a middleware (an Express body parser such as express.json()?): ' +
+      'Znight reads the bodies of its routes itself, do not register body parsers for them',
+  )
+}
+
+/** Reads a Node.js request body, enforcing `limit` (on `content-length`, then while streaming). */
+export function readNodeBody(request: IncomingMessage, limit: number): Promise<Uint8Array> {
+  if (exceedsDeclaredLength(request.headers['content-length'], limit)) {
+    request.resume()
+    return Promise.reject(payloadTooLarge(limit))
+  }
+  if (consumedElsewhere(request)) return Promise.reject(consumedError())
+  if (request.readableEnded) return Promise.resolve(new Uint8Array(0))
+  if (request.destroyed) return Promise.reject(new BadRequestException('The request was aborted'))
+  return new Promise((resolve, reject) => {
+    const chunks: Uint8Array[] = []
+    let size = 0
+    const cleanup = (): void => {
+      request.off('data', onData)
+      request.off('end', onEnd)
+      request.off('error', onError)
+      request.off('close', onClose)
+    }
+    const onData = (chunk: Uint8Array | string): void => {
+      const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk
+      size += bytes.byteLength
+      if (size > limit) {
+        cleanup()
+        request.resume() // discard the rest; the 413 response closes the connection
+        reject(payloadTooLarge(limit))
+        return
+      }
+      chunks.push(bytes)
+    }
+    const onEnd = (): void => {
+      cleanup()
+      resolve(concat(chunks, size))
+    }
+    const onError = (error: Error): void => {
+      cleanup()
+      reject(new BadRequestException('Failed to read the request body', undefined, { cause: error }))
+    }
+    const onClose = (): void => {
+      if (request.complete) return
+      cleanup()
+      reject(new BadRequestException('The request was aborted'))
+    }
+    request.on('data', onData)
+    request.on('end', onEnd)
+    request.on('error', onError)
+    request.on('close', onClose)
+  })
+}
+
+/**
+ * A Node.js request body as a Web stream (see `AdapterRequest.streamBody`): the request is paused
+ * while the consumer does not read (backpressure); past `limit` bytes the stream errors with 413 and
+ * the rest of the body is discarded (`request.resume()`), like when the consumer cancels the stream,
+ * so the response can still be written (it carries `connection: close`).
+ */
+export function nodeBodyStream(request: IncomingMessage, limit: number): ReadableStream<Uint8Array> {
+  if (exceedsDeclaredLength(request.headers['content-length'], limit)) {
+    request.resume()
+    return failedStream(payloadTooLarge(limit))
+  }
+  if (consumedElsewhere(request)) return failedStream(consumedError())
+  if (request.readableEnded) return new ReadableStream<Uint8Array>({ start: controller => controller.close() })
+  if (request.destroyed) return failedStream(new BadRequestException('The request was aborted'))
+  let size = 0
+  let cleanup = (): void => undefined
+  return new ReadableStream<Uint8Array>(
+    {
+      start(controller) {
+        const onData = (chunk: Uint8Array | string): void => {
+          const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk
+          size += bytes.byteLength
+          if (size > limit) {
+            cleanup()
+            request.resume() // discard the rest; the 413 response closes the connection
+            controller.error(payloadTooLarge(limit))
+            return
+          }
+          controller.enqueue(bytes)
+          if ((controller.desiredSize ?? 0) <= 0) request.pause()
+        }
+        const onEnd = (): void => {
+          cleanup()
+          controller.close()
+        }
+        const onError = (error: Error): void => {
+          cleanup()
+          controller.error(new BadRequestException('Failed to read the request body', undefined, { cause: error }))
+        }
+        const onClose = (): void => {
+          if (request.complete) return
+          cleanup()
+          controller.error(new BadRequestException('The request was aborted'))
+        }
+        cleanup = (): void => {
+          request.off('data', onData)
+          request.off('end', onEnd)
+          request.off('error', onError)
+          request.off('close', onClose)
+        }
+        request.on('data', onData)
+        request.on('end', onEnd)
+        request.on('error', onError)
+        request.on('close', onClose)
+      },
+      pull() {
+        if (request.isPaused()) request.resume()
+      },
+      cancel() {
+        cleanup()
+        request.resume() // discard the rest of the body
+      },
+    },
+    { highWaterMark: BODY_HIGH_WATER_MARK, size: (chunk: Uint8Array | undefined) => chunk?.byteLength ?? 0 },
+  )
+}
+
+/** Options of {@link nodeAdapterRequest}. */
+export interface NodeRequestOptions {
+  /** Request target (default: `request.url`). */
+  readonly url?: string
+  /** `@Req()` value (default: the `IncomingMessage`). */
+  readonly raw?: unknown
+  /** `@Res()` value (default: the `ServerResponse`). */
+  readonly rawResponse?: unknown
+  readonly ip?: string | undefined
+}
+
+/** Wraps a Node.js request/response pair as an {@link AdapterRequest}. */
+export function nodeAdapterRequest(
+  request: IncomingMessage,
+  response: ServerResponse,
+  options: NodeRequestOptions = {},
+): AdapterRequest {
+  let body: Promise<Uint8Array> | undefined
+  return {
+    method: request.method ?? 'GET',
+    url: options.url ?? request.url ?? '/',
+    headers: normalizeNodeHeaders(request.headers),
+    ip: options.ip ?? request.socket?.remoteAddress,
+    remoteAddress: request.socket?.remoteAddress,
+    encrypted: isEncrypted(request),
+    raw: options.raw ?? request,
+    rawResponse: options.rawResponse ?? response,
+    readBody: (limit: number): Promise<Uint8Array> => {
+      body ??= readNodeBody(request, limit)
+      return body
+    },
+    streamBody: (limit: number): ReadableStream<Uint8Array> => nodeBodyStream(request, limit),
+    rawStatus: (): number => response.statusCode,
+    onAbort: (listener: () => void): void => onResponseAbort(response, listener),
+  }
+}
+
+/**
+ * Calls `listener` once when `response` closes before it was fully written (the client left): on
+ * the next microtask when it is already destroyed, never after a complete response.
+ */
+export function onResponseAbort(response: ServerResponse, listener: () => void): void {
+  if (response.writableFinished) return
+  if (response.destroyed) {
+    queueMicrotask(listener)
+    return
+  }
+  response.once('close', () => {
+    if (!response.writableFinished) listener()
+  })
+}
+
+/** Whether the request came over TLS (`node:https`, `node:http2` secure servers). */
+export function isEncrypted(request: IncomingMessage): boolean {
+  return (request.socket as { readonly encrypted?: unknown } | undefined)?.encrypted === true
+}
+
+/**
+ * Writes a reply to a `ServerResponse`. Resolves when the response is complete (streams included);
+ * never rejects (a failing stream destroys the response).
+ */
+export async function writeNodeReply(response: ServerResponse, reply: AdapterReply): Promise<void> {
+  if (reply.raw === true) {
+    discardStream(reply.body instanceof ReadableStream ? reply.body : null)
+    return
+  }
+  if (response.headersSent || response.destroyed) {
+    discardStream(reply.body instanceof ReadableStream ? reply.body : null)
+    if (!response.writableEnded && !response.destroyed) response.end()
+    return
+  }
+  try {
+    // one call (merged over headers set earlier with setHeader(), e.g. by Express middleware); the
+    // cookies set earlier are kept before the reply's own (writeHead would replace them)
+    const headers = withNativeCookies(response.getHeader('set-cookie'), reply.headers)
+    response.writeHead(reply.status, headers as OutgoingHttpHeaders)
+  } catch {
+    // invalid header name or value set by user code
+    discardStream(reply.body instanceof ReadableStream ? reply.body : null)
+    if (!response.headersSent) {
+      for (const name of response.getHeaderNames()) response.removeHeader(name)
+      response.statusCode = 500
+      response.setHeader('content-type', 'application/json; charset=utf-8')
+      response.end('{"statusCode":500,"error":"Internal Server Error"}')
+    }
+    return
+  }
+  const body = reply.body
+  if (body === null) {
+    response.end()
+    return
+  }
+  // an event stream may stay quiet longer than a socket timeout (`server.timeout`, Bun's emulation)
+  if (reply.eventStream === true && (response as { isLightMyRequest?: boolean }).isLightMyRequest !== true) {
+    response.setTimeout(0)
+  }
+  if (body instanceof Uint8Array) {
+    response.end(body)
+    return
+  }
+  const stream = body instanceof Blob ? body.stream() : body
+  try {
+    await pipeline(Readable.fromWeb(stream as import('node:stream/web').ReadableStream), response)
+  } catch {
+    if (!response.destroyed) response.destroy()
+  }
+}
+
+/**
+ * `headers` with the `set-cookie` lines already set on the native response (Express middleware
+ * `res.cookie()`, Fastify hooks `reply.header('set-cookie', ...)`) before its own: `headers`
+ * unchanged when either side has none.
+ */
+export function withNativeCookies(
+  native: number | string | readonly string[] | undefined,
+  headers: Readonly<Record<string, HeaderValue>>,
+): Readonly<Record<string, HeaderValue>> {
+  const own = headers['set-cookie']
+  if (own === undefined || native === undefined || typeof native === 'number') return headers
+  const before = typeof native === 'string' ? [native] : native
+  if (before.length === 0) return headers
+  return { ...headers, 'set-cookie': [...before, ...(typeof own === 'string' ? [own] : own)] }
+}
+
+/** Last-resort 500 when a handler promise rejected (should not happen: the pipeline maps errors). */
+export function writeNodeFailure(response: ServerResponse): void {
+  if (response.headersSent) {
+    if (!response.writableEnded) response.destroy()
+    return
+  }
+  response.statusCode = 500
+  response.setHeader('content-type', 'application/json; charset=utf-8')
+  response.end('{"statusCode":500,"error":"Internal Server Error"}')
+}
+
+/**
+ * Tracks the connections of a `node:http` server to close them on shutdown: idle keep-alive
+ * connections first (graceful), every connection when forced. `server.closeIdleConnections()` /
+ * `closeAllConnections()` are not reliable on every runtime (Bun), so sockets are tracked here.
+ */
+export class ConnectionTracker {
+  /** Socket → number of requests in progress. */
+  readonly #sockets = new Map<Socket, number>()
+  #closing = false
+
+  constructor(server: Server) {
+    server.on('connection', (socket: Socket) => {
+      this.#sockets.set(socket, 0)
+      socket.once('close', () => this.#sockets.delete(socket))
+    })
+    server.on('request', (request: IncomingMessage, response: ServerResponse) => {
+      const socket = request.socket
+      if (!this.#sockets.has(socket)) return
+      this.#sockets.set(socket, (this.#sockets.get(socket) ?? 0) + 1)
+      response.once('close', () => {
+        const active = this.#sockets.get(socket)
+        if (active === undefined) return
+        this.#sockets.set(socket, active - 1)
+        if (active - 1 === 0 && this.#closing) socket.end()
+      })
+    })
+  }
+
+  /** Ends idle connections now and the others once their requests completed. */
+  closeIdle(): void {
+    this.#closing = true
+    for (const [socket, active] of this.#sockets) if (active === 0) socket.end()
+  }
+
+  /** Destroys every connection. */
+  destroyAll(): void {
+    this.#closing = true
+    for (const socket of this.#sockets.keys()) socket.destroy()
+  }
+}
+
+/** Closes a `node:http` server: graceful (idle connections ended), then forced when asked. */
+export function closeServer(
+  server: Server,
+  tracker: ConnectionTracker,
+  closing: Promise<void> | undefined,
+  force: boolean,
+): Promise<void> {
+  const promise =
+    closing ??
+    new Promise<void>(resolve => {
+      if (!server.listening) {
+        resolve()
+        return
+      }
+      server.close(() => resolve())
+      server.closeIdleConnections?.()
+      tracker.closeIdle()
+    })
+  if (force) {
+    server.closeAllConnections?.()
+    tracker.destroyAll()
+  }
+  return promise
+}

package/src/adapters/node.ts

@@ -0,0 +1,135 @@
+/**
+ * `@znight/http/node`: the built-in, zero-dependency adapter on `node:http` (default adapter of
+ * `HttpPlugin`). Works on Node.js and Bun. `inject()` uses the optional peer `light-my-request`.
+ */
+import type {
+  AdapterCloseOptions,
+  AdapterHandler,
+  AdapterRoute,
+  FallbackHandler,
+  HttpAdapter,
+  HttpServerAddress,
+  InjectRequest,
+  InjectResponse,
+  InjectStreamRequest,
+  InjectStreamResponse,
+} from '../adapter.ts'
+
+import { createServer, type IncomingMessage, type Server, type ServerOptions, type ServerResponse } from 'node:http'
+
+import { RouteTable } from '../router.ts'
+import { ConnectionTracker, closeServer, nodeAdapterRequest, writeNodeFailure, writeNodeReply } from './node-io.ts'
+import { bufferInjectStream, injectNodeStream, serverAddress } from './shared.ts'
+
+/** Options of {@link nodeAdapter}. */
+export interface NodeAdapterOptions {
+  /** Options of `http.createServer()` (timeouts, `maxHeaderSize`...). Ignored with {@link server}. */
+  readonly serverOptions?: ServerOptions
+  /**
+   * An existing server (e.g. `https.createServer({ key, cert })`). The adapter adds its `request`
+   * listener on `listen()` and closes the server on shutdown.
+   */
+  readonly server?: Server
+}
+
+/** The built-in Node.js adapter. */
+export interface NodeAdapter extends HttpAdapter {
+  readonly name: 'node'
+  /** Request listener serving the routes, to mount the application in a server you manage. */
+  readonly handler: (request: IncomingMessage, response: ServerResponse) => void
+  /** The server, once listening (or the one given in the options). */
+  readonly server: Server | undefined
+}
+
+/**
+ * Creates the built-in `node:http` adapter: a segment-trie router (static > `:param` > `*`, with
+ * backtracking), zero dependencies.
+ *
+ * ```ts
+ * HttpPlugin.configure({ adapter: nodeAdapter({ serverOptions: { requestTimeout: 30_000 } }) })
+ * ```
+ */
+export function nodeAdapter(options: NodeAdapterOptions = {}): NodeAdapter {
+  return new NodeHttpAdapter(options)
+}
+
+class NodeHttpAdapter implements NodeAdapter {
+  readonly name = 'node' as const
+  readonly #routes = new RouteTable<AdapterHandler>()
+  readonly #options: NodeAdapterOptions
+  #fallback: FallbackHandler | undefined
+  #server: Server | undefined
+  #tracker: ConnectionTracker | undefined
+  #closing: Promise<void> | undefined
+
+  constructor(options: NodeAdapterOptions) {
+    this.#options = options
+    this.#server = options.server
+  }
+
+  get server(): Server | undefined {
+    return this.#server
+  }
+
+  registerRoute(route: AdapterRoute): void {
+    if (this.#routes.add(route.method, route.path, route.handler) !== undefined) {
+      throw new Error(`Duplicate route ${route.method} ${route.path.path}`)
+    }
+  }
+
+  setFallbackHandler(handler: FallbackHandler): void {
+    this.#fallback = handler
+  }
+
+  readonly handler = (request: IncomingMessage, response: ServerResponse): void => {
+    const url = request.url ?? '/'
+    const query = url.indexOf('?')
+    const handler = this.#routes.find(request.method ?? 'GET', query === -1 ? url : url.slice(0, query))
+    const adapterRequest = nodeAdapterRequest(request, response)
+    let reply: ReturnType<AdapterHandler>
+    if (handler !== undefined) reply = handler(adapterRequest)
+    else if (this.#fallback === undefined) {
+      writeNodeFailure(response)
+      return
+    } else reply = this.#fallback(adapterRequest)
+    reply.then(
+      result => writeNodeReply(response, result),
+      () => writeNodeFailure(response),
+    )
+  }
+
+  async listen(port: number, host: string): Promise<HttpServerAddress> {
+    const server = this.#server ?? createServer(this.#options.serverOptions ?? {})
+    this.#server = server
+    this.#tracker ??= new ConnectionTracker(server)
+    this.#closing = undefined
+    if (!server.listeners('request').includes(this.handler)) server.on('request', this.handler)
+    await new Promise<void>((resolve, reject) => {
+      const onError = (error: Error): void => reject(error)
+      server.once('error', onError)
+      server.listen(port, host, () => {
+        server.off('error', onError)
+        resolve()
+      })
+    })
+    const address = server.address()
+    if (address === null || typeof address === 'string') return serverAddress(host, port)
+    return serverAddress(address.address, address.port, address.family)
+  }
+
+  close(options: AdapterCloseOptions = {}): Promise<void> {
+    const server = this.#server
+    const tracker = this.#tracker
+    if (server === undefined || tracker === undefined) return Promise.resolve()
+    this.#closing = closeServer(server, tracker, this.#closing, options.force === true)
+    return this.#closing
+  }
+
+  inject(request: InjectRequest): Promise<InjectResponse> {
+    return bufferInjectStream(stream => this.injectStream(stream), request)
+  }
+
+  injectStream(request: InjectStreamRequest): Promise<InjectStreamResponse> {
+    return injectNodeStream('node', this.handler as (req: never, res: never) => void, request)
+  }
+}