@nxtedition/http 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) nxtedition
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# @nxtedition/http
+
+HTTP/HTTP2 server middleware framework with priority-based scheduling, request lifecycle tracking, and Koa-style middleware composition.
+
+## Install
+
+```bash
+npm install @nxtedition/http
+```
+
+## Usage
+
+### Basic Server
+
+```js
+import { createServer } from '@nxtedition/http'
+
+const server = createServer({ keepAliveTimeout: 120_000 }, { logger: pino() }, (ctx) => {
+  ctx.res.writeHead(200, { 'content-type': 'text/plain' })
+  ctx.res.end('Hello World')
+})
+
+server.listen(3000)
+```
+
+### Middleware Composition
+
+```js
+import { createServer, compose } from '@nxtedition/http'
+
+const auth = async (ctx, next) => {
+  if (!ctx.req.headers.authorization) {
+    const err = new Error('Unauthorized')
+    err.statusCode = 401
+    err.expose = true
+    throw err
+  }
+  await next()
+}
+
+const handler = async (ctx) => {
+  ctx.res.writeHead(200)
+  ctx.res.end(JSON.stringify({ user: 'authenticated' }))
+}
+
+const server = createServer({ logger: pino() }, [auth, handler])
+```
+
+### Priority-Based Scheduling
+
+Requests are automatically prioritized based on the `nxt-priority` header or user-agent detection. Priority maps to DSCP/ToS values on the socket:
+
+| Priority | Value | DSCP | Use Case         |
+| -------- | ----- | ---- | ---------------- |
+| highest  | 3     | EF   | Realtime         |
+| higher   | 2     | AF41 | High priority    |
+| high     | 1     | AF31 | User experience  |
+| normal   | 0     | BE   | Default traffic  |
+| low      | -1    | LE   | Background tasks |
+| lower    | -2    | LE   | Replication      |
+| lowest   | -3    | LE   | Batch jobs       |
+
+### Error Handling
+
+Thrown errors are automatically serialized to HTTP responses:
+
+```js
+const handler = (ctx) => {
+  const err = new Error('Validation failed')
+  err.statusCode = 422
+  err.body = { errors: [{ field: 'email', message: 'required' }] }
+  err.headers = { 'x-request-id': ctx.id }
+  throw err
+}
+```
+
+Error properties:
+
+- `statusCode` - HTTP status code (default: 500)
+- `body` - Response body (object, string, or Buffer)
+- `headers` - Additional response headers (object or flat array)
+- `expose` - If `true`, includes `err.message` as JSON response body
+
+### Context Factory
+
+```js
+import { createServer, Context } from '@nxtedition/http'
+
+const server = createServer((req, res) => {
+  const ctx = new Context(req, res, logger)
+  ctx.db = database
+  return ctx
+}, handler)
+```
+
+### AbortSignal Support
+
+```js
+const handler = async (ctx) => {
+  // ctx.signal is aborted when the request errors or is aborted
+  const data = await fetch('http://upstream/api', { signal: ctx.signal })
+  ctx.res.writeHead(200)
+  ctx.res.end(await data.text())
+}
+```
+
+## API
+
+### `createServer(ctx, middleware?)`
+
+### `createServer(options, ctx, middleware?)`
+
+Creates an HTTP server with enhanced request/response classes.
+
+- **options** - Server options (extends `http.ServerOptions`)
+  - `logger` - Pino-compatible logger
+  - `signal` - `AbortSignal` for graceful shutdown
+  - `socketTimeout` / `timeout` - Socket timeout (default: 120s)
+- **ctx** - Context config object `{ logger, ...opaque }` or factory function `(req, res) => Context`
+- **middleware** - Handler function or array of middleware functions
+
+### `compose(...middleware)`
+
+Composes middleware functions into a single middleware. Supports arrays and variadic arguments. In development mode, validates that `next()` is not called multiple times and that middleware properly awaits downstream.
+
+### `Context`
+
+Request context wrapping `req` and `res` with:
+
+- `id` - Unique request ID
+- `req` - `IncomingMessage` instance
+- `res` - `ServerResponse` instance
+- `target` - Parsed URL target (protocol, hostname, port, pathname, search)
+- `query` - Parsed query parameters
+- `userAgent` - User-Agent header value
+- `priority` - Resolved request priority
+- `signal` - `AbortSignal` (lazily created)
+- `logger` - Child logger with request ID
+
+### `IncomingMessage`
+
+Extended `http.IncomingMessage` with computed `id`, `target`, and `query` properties. Results are lazily cached and invalidated when URL or host changes.
+
+### `ServerResponse`
+
+Extended `http.ServerResponse` with:
+
+- `timing` - Request timing metrics (created, connect, headers, data, end)
+- `bytesWritten` - Total bytes written to response
+- Custom header tracking that is independent of Node.js internals
+
+### `requestMiddleware(ctx, next)`
+
+Core middleware that handles request lifecycle:
+
+- Sets `request-id` response header
+- Fast-dumps GET/HEAD request bodies
+- Tracks pending requests
+- Serializes errors to HTTP responses
+- Logs request lifecycle events
+
+### `upgradeMiddleware(ctx, next)`
+
+Middleware for WebSocket/upgrade request handling with lifecycle logging.
+
+### `genReqId()`
+
+Generates unique request IDs using V8 SMI-optimized integers (`req-{base36}`).
+
+## License
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1,112 @@
+import http2 from 'node:http2';
+import type net from 'node:net';
+import type { RequestTarget } from 'request-target';
+import http from 'http';
+import type { Logger } from 'pino';
+export type { RequestTarget };
+export declare const kAbortController: unique symbol;
+export declare function genReqId(): string;
+declare const kPendingIndex: unique symbol;
+export declare class Context {
+    #private;
+    [kPendingIndex]: number;
+    constructor(req: IncomingMessage, res: ServerResponse, logger: Logger);
+    get priority(): -3 | -2 | -1 | 0 | 1 | 2 | 3;
+    get id(): string;
+    get logger(): Logger;
+    get req(): IncomingMessage;
+    get res(): ServerResponse;
+    get target(): Readonly<RequestTarget> | null;
+    get query(): Record<string, string>;
+    get userAgent(): string;
+    get [kAbortController](): AbortController | undefined;
+    get signal(): AbortSignal;
+}
+export declare function upgradeMiddleware(ctx: Context & {
+    req: http.IncomingMessage;
+    socket: net.Socket;
+}, next: () => unknown): Promise<void>;
+export declare function requestMiddleware(ctx: Context & {
+    stats?: {
+        pending?: number;
+        completed?: number;
+        failed?: number;
+    };
+}, next: () => unknown): Promise<void>;
+export declare class IncomingMessage extends http.IncomingMessage {
+    #private;
+    get id(): string;
+    get target(): Readonly<RequestTarget> | null;
+    get query(): Record<string, string>;
+}
+export declare class ServerResponse extends http.ServerResponse {
+    #private;
+    get timing(): {
+        created: number;
+        connect: number;
+        headers: number;
+        data: number;
+        end: number;
+    };
+    get bytesWritten(): number;
+    setHeader(key: string, val: string | number): this;
+    removeHeader(key: string): void;
+    getHeaderNames(): string[];
+    getHeaders(): Record<string, string | undefined>;
+    get headersSent(): boolean;
+    writeHead(statusCode: number, statusMessage?: string, headers?: http.OutgoingHttpHeaders): this;
+    writeHead(statusCode: number, headers?: http.OutgoingHttpHeaders): this;
+    assignSocket(socket: net.Socket): void;
+    write(chunk: string | Buffer, callback?: (error: Error | null | undefined) => void): boolean;
+    write(chunk: string | Buffer, encoding: BufferEncoding, callback?: (error: Error | null | undefined) => void): boolean;
+    end(callback?: () => void): this;
+    end(data: string | Uint8Array, callback?: () => void): this;
+    end(data: string | Uint8Array, encoding: BufferEncoding, callback?: () => void): this;
+    destroy(err?: Error): this;
+}
+export declare class Http2ServerRequest extends http2.Http2ServerRequest {
+    #private;
+    get id(): string;
+    get target(): Readonly<RequestTarget> | null;
+    get query(): Record<string, string>;
+}
+export declare class Http2ServerResponse extends http2.Http2ServerResponse {
+    #private;
+    get timing(): {
+        created: number;
+        connect: number;
+        headers: number;
+        data: number;
+        end: number;
+    };
+    get bytesWritten(): number;
+    setHeader(key: string, val: string | number): this;
+    removeHeader(key: string): void;
+    getHeaderNames(): string[];
+    getHeaders(): Record<string, string | undefined>;
+    get headersSent(): boolean;
+    writeHead(statusCode: number, headers?: http2.OutgoingHttpHeaders): this;
+    writeHead(statusCode: number, statusMessage: string, headers?: http2.OutgoingHttpHeaders): this;
+    write(chunk: string | Uint8Array, callback?: (err: Error) => void): boolean;
+    write(chunk: string | Uint8Array, encoding: BufferEncoding, callback?: (err: Error) => void): boolean;
+    end(callback?: () => void): this;
+    end(data: string | Uint8Array, callback?: () => void): this;
+    end(data: string | Uint8Array, encoding: BufferEncoding, callback?: () => void): this;
+    destroy(err?: Error): this;
+}
+interface CreateServerOptions extends http.ServerOptions {
+    logger?: Logger;
+    signal?: AbortSignal;
+    socketTimeout?: number;
+    keepAliveTimeout?: number;
+    headersTimeout?: number;
+    requestTimeout?: number;
+}
+type ContextFactory = (req: IncomingMessage, res: ServerResponse) => Context;
+type ContextOptions = Record<string, unknown> & {
+    logger?: Logger;
+};
+export declare function createServer(ctx: ContextFactory | ContextOptions, middleware?: MiddlewareFn | MiddlewareFn[]): http.Server;
+export declare function createServer(options: CreateServerOptions, ctx: ContextOptions | ContextFactory, middleware?: MiddlewareFn | MiddlewareFn[]): http.Server;
+type MiddlewareFn = (ctx: Context, next: () => unknown) => unknown;
+export declare const compose: (...middleware: (MiddlewareFn | MiddlewareFn[])[]) => MiddlewareFn;

package/lib/index.js

@@ -0,0 +1,1076 @@
+import http2 from 'node:http2'
+import assert from 'node:assert'
+import { TLSSocket } from 'node:tls'
+                               
+import { performance } from 'perf_hooks'
+import requestTarget from 'request-target'
+                                                   
+import querystring from 'fast-querystring'
+import http from 'http'
+import { parsePriority, Scheduler } from '@nxtedition/scheduler'
+                                  
+
+                             
+
+export const kAbortController                = Symbol('abortController')
+
+const kEmptyObj                                   = Object.freeze({})
+const kEmptyArr                    = Object.freeze([]            )
+
+const ERR_HEADER_EXPR =
+  /^(content-length|content-type|te|host|upgrade|trailers|connection|keep-alive|http2-settings|transfer-encoding|proxy-connection|proxy-authenticate|proxy-authorization)$/i
+
+// https://github.com/fastify/fastify/blob/main/lib/reqIdGenFactory.js
+// 2,147,483,647 (2^31 − 1) stands for max SMI value (an internal optimization of V8).
+// With this upper bound, if you'll be generating 1k ids/sec, you're going to hit it in ~25 days.
+// This is very likely to happen in real-world applications, hence the limit is enforced.
+// Growing beyond this value will make the id generation slower and cause a deopt.
+// In the worst cases, it will become a float, losing accuracy.
+const maxInt = 2147483647
+let nextReqId = Math.floor(Math.random() * maxInt)
+export function genReqId()         {
+  nextReqId = (nextReqId + 1) & maxInt
+  return 'req-' + nextReqId.toString(36)
+}
+
+function requestTargetSlow(req                          )                       {
+  let base        
+  if (req.httpVersionMajor === 2) {
+    base = `${req.headers[':scheme']}://${req.headers[':authority'] || 'localhost'}`
+  } else {
+    const scheme = req.socket instanceof TLSSocket ? 'https:' : 'http:'
+    base = `${scheme}://${req.headers.host || 'localhost'}`
+  }
+  try {
+    const url = new URL(req.url, base)
+    return {
+      protocol: url.protocol,
+      hostname: url.hostname,
+      port: url.port || (url.protocol === 'https:' ? '443' : '80'),
+      pathname: url.pathname,
+      search: url.search || '',
+    }
+  } catch {
+    return null
+  }
+}
+
+const pending            = ((
+  globalThis                                      
+).__nxt_lib_http_pending = [])
+const kPendingIndex                = Symbol('pendingIndex')
+
+// # | highest | 0 | 0 | EF(0x2e → TOS )       | 7 | Realtime CasparCG |
+// # | higher  | 1 | 1 | AF41(0x22 → TOS 0x88) | 6 | Deepstream |
+// # | high    | 2 | 2 | AF31(0x1a → TOS 0x68) | 5 | User - experience: drive cache, hub request |
+// # | normal  | 3 | 3 | BE(0x00 → TOS 0x00)   | 0 | Default traffic, record updates, live changes |
+// # | low     | 4 | 4 | LE(0x01 → TOS 0x04)   | 4 | Scheduled renders, background proxies |
+// # | lower   | 5 | 5 | LE(0x01 → TOS 0x04)   | 3 | Replication, index rebuilds, design views |
+// # | lowest  | 6 | 6 | LE(0x01 → TOS 0x04)   | 1 | Transcription, AI analysis, batch jobs |
+const PRIORITY_TOS           = []
+assert(Scheduler.LOWEST === -3)
+PRIORITY_TOS[Scheduler.HIGHEST + 3] = 0xb8 // EF
+PRIORITY_TOS[Scheduler.HIGHER + 3] = 0x88 // AF41
+PRIORITY_TOS[Scheduler.HIGH + 3] = 0x68 // AF31
+PRIORITY_TOS[Scheduler.NORMAL + 3] = 0x00 // BE
+PRIORITY_TOS[Scheduler.LOW + 3] = 0x04 // LE
+PRIORITY_TOS[Scheduler.LOWER + 3] = 0x04 // LE
+PRIORITY_TOS[Scheduler.LOWEST + 3] = 0x04 // LE
+
+function isPlainObject(value         )                                   {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+function getHeader(
+  val                                               ,
+  key        ,
+)                     {
+  const v = val[key]
+  return typeof v === 'string' ? v : undefined
+}
+
+export class Context {
+  #id        
+  #req                 
+  #res                
+  #ac                             
+  #logger        
+  #query                                    
+  #target                                            
+  #priority                              ;
+  [kPendingIndex] = -1
+
+  constructor(req                 , res                , logger        ) {
+    assert(req)
+    assert(res)
+
+    this.#id =
+      req.id ||
+      getHeader(req.headers, 'request-id') ||
+      getHeader(req.headers, 'Request-Id') ||
+      genReqId()
+    this.#req = req
+    this.#res = res
+
+    const p = getHeader(req.headers, 'nxt-priority')
+    if (!p) {
+      this.#priority = (
+        getHeader(req.headers, 'user-agent') || getHeader(req.headers, 'User-Agent')
+      )?.startsWith('caspar/')
+        ? Scheduler.HIGHEST
+        : Scheduler.NORMAL
+    } else {
+      this.#priority = parsePriority(p)
+    }
+
+    this.#logger = logger.child({ rid: this.#id, priority: this.#priority })
+
+    if (!('stream' in res) && res.socket && 'setTypeOfService' in res.socket) {
+      ;(res.socket                                                      ).setTypeOfService(
+        PRIORITY_TOS[this.#priority + 3] ?? 0x0,
+      )
+    }
+  }
+
+  get priority()                               {
+    return this.#priority
+  }
+
+  get id()         {
+    return this.#id
+  }
+
+  get logger()         {
+    return this.#logger
+  }
+
+  get req()                  {
+    return this.#req
+  }
+
+  get res()                 {
+    return this.#res
+  }
+
+  get target()                                 {
+    if (this.#req.target) {
+      return this.#req.target
+    }
+    if (this.#target === undefined) {
+      const t = requestTarget(this.#req)
+      this.#target = t ? Object.freeze(t) : null
+    }
+    return this.#target
+  }
+
+  get query()                         {
+    if (this.#req.query) {
+      return this.#req.query
+    }
+
+    const search = this.target?.search
+
+    return (this.#query ??=
+      search && search.length > 1 ? Object.freeze(querystring.parse(search.slice(1))) : {})
+  }
+
+  get userAgent()         {
+    return (
+      getHeader(this.#req.headers, 'user-agent') || getHeader(this.#req.headers, 'User-Agent') || ''
+    )
+  }
+
+  get [kAbortController]()                              {
+    return this.#ac
+  }
+
+  get signal()              {
+    this.#ac ??= new AbortController()
+    return this.#ac.signal
+  }
+}
+
+function noop() {}
+
+export async function upgradeMiddleware(
+  ctx                                                             ,
+  next               ,
+)                {
+  const { req, socket } = ctx
+  const startTime = performance.now()
+
+  let aborted = false
+
+  req.on('error', noop)
+  socket.on('error', (err       ) => {
+    // NOTE: Special case where the client becomes unreachable.
+    if (err.message.startsWith('read ')) {
+      aborted = true
+    }
+  })
+
+  const reqLogger = ctx.logger?.child({ req })
+  try {
+    const isHealthcheck = req.url === '/healthcheck' || req.url === '/_up'
+    if (!isHealthcheck) {
+      reqLogger?.debug({ req }, 'request started')
+    }
+
+    const thenable = next()
+
+    if (Object.hasOwnProperty.call(thenable, 'then')) {
+      await thenable
+    }
+
+    if (!socket.destroyed && !socket.writableEnded) {
+      throw new Error('Stream not completed')
+    }
+
+    const elapsedTime = performance.now() - startTime
+
+    if (isHealthcheck) {
+      // Do nothing...
+    } else if (socket.errored) {
+      reqLogger?.error({ err: socket.errored, req, socket, elapsedTime }, 'stream error')
+    } else if (!socket.writableEnded) {
+      reqLogger?.debug({ socket, elapsedTime }, 'stream aborted')
+    } else if ((socket                                     ).statusCode >= 500) {
+      reqLogger?.error({ socket, elapsedTime }, 'stream error')
+    } else if ((socket                                     ).statusCode >= 400) {
+      reqLogger?.warn({ socket, elapsedTime }, 'stream failed')
+    } else {
+      reqLogger?.debug({ socket, elapsedTime }, 'stream completed')
+    }
+  } catch (err) {
+    ctx[kAbortController]?.abort(err)
+
+    const statusCode = err.statusCode || err.$metadata?.httpStatusCode || 500
+    const elapsedTime = performance.now() - startTime
+
+    if (req.aborted || aborted || (!socket.errored && socket.closed) || err.name === 'AbortError') {
+      reqLogger?.debug({ err, req, socket, elapsedTime }, 'stream aborted')
+    } else if (
+      statusCode < 500 ||
+      err.code === 'ERR_STREAM_PREMATURE_CLOSE' ||
+      err.code === 'EPIPE'
+    ) {
+      reqLogger?.warn({ err, req, socket, elapsedTime }, 'stream failed')
+    } else {
+      reqLogger?.error({ err, req, socket, elapsedTime }, 'stream error')
+    }
+    socket.destroy(err         )
+  } finally {
+    if (!socket.writableEnded && !socket.destroyed) {
+      socket.destroy()
+      reqLogger?.warn('socket destroyed')
+    }
+  }
+}
+
+export async function requestMiddleware(
+  ctx                                                                                 ,
+  next               ,
+)                {
+  const { req, res, target, stats } = ctx
+  const startTime = performance.now()
+
+  const reqLogger = ctx.logger?.child({ req })
+
+  if (stats?.pending != null) {
+    stats.pending++
+  }
+
+  if (ctx[kPendingIndex] !== -1) {
+    throw new Error('context is already pending')
+  }
+
+  ctx[kPendingIndex] = pending.push(ctx) - 1
+  try {
+    const isHealthcheck = req.url === '/healthcheck' || req.url === '/_up'
+    if (!isHealthcheck) {
+      reqLogger?.debug({ req }, 'request started')
+    }
+
+    if (!target) {
+      throw Object.assign(new Error('invalid url'), { statusCode: 400, expose: true })
+    }
+
+    if (ctx.id) {
+      res.setHeader('request-id', ctx.id)
+    }
+
+    if (req.httpVersionMajor === 1 && (req.method === 'HEAD' || req.method === 'GET')) {
+      // Fast dump where request "has" already emitted all lifecycle events.
+      // This avoid a lot of unnecessary overhead otherwise introduced by
+      // stream.Readable life cycle rules. The downside is that this will
+      // break some servers that read GET bodies.
+      const r = req                
+                        
+                                               
+                     
+       
+      r._dumped = true
+      r._readableState.ended = true
+      r._readableState.endEmitted = true
+      r._readableState.destroyed = true
+      r._readableState.closed = true
+      r._readableState.closeEmitted = true
+
+      r._read()
+    }
+
+    await next()
+
+    if (!res.destroyed && !res.writableEnded) {
+      throw new Error('Response not completed')
+    }
+
+    if (stats?.completed != null) {
+      stats.completed++
+    }
+
+    const elapsedTime = performance.now() - startTime
+
+    if (isHealthcheck) {
+      // Do nothing...
+    } else if (res.errored) {
+      reqLogger?.error({ err: res.errored, res, elapsedTime }, 'request error')
+    } else if (!res.writableEnded) {
+      reqLogger?.debug({ res, elapsedTime }, 'request aborted')
+    } else if (res.statusCode >= 500) {
+      reqLogger?.error({ res, elapsedTime }, 'request error')
+    } else if (res.statusCode >= 400) {
+      reqLogger?.warn({ res, elapsedTime }, 'request failed')
+    } else {
+      reqLogger?.debug({ res, elapsedTime }, 'request completed')
+    }
+  } catch (err) {
+    if (stats?.failed != null) {
+      stats.failed++
+    }
+
+    ctx[kAbortController]?.abort(err)
+
+    if (!req.closed) {
+      req.on('error', (err       ) => {
+        reqLogger?.warn({ err }, 'request error')
+      })
+    }
+
+    if (!res.closed) {
+      res.on('error', (err       ) => {
+        reqLogger?.warn({ err }, 'response error')
+      })
+    }
+
+    const statusCode = err.statusCode || err.$metadata?.httpStatusCode || 500
+    const elapsedTime = performance.now() - startTime
+
+    // res.destroyed is not properly set by http2 compat so we need to
+    // also check res.closed.
+    if (!res.headersSent && !res.destroyed && !res.closed && !req.aborted) {
+      res.statusCode = statusCode
+
+      for (const name of res.getHeaderNames()) {
+        res.removeHeader(name)
+      }
+
+      if (ctx.id) {
+        res.setHeader('request-id', ctx.id)
+      }
+
+      const { headers } = err
+
+      if (isPlainObject(headers)) {
+        for (const [key, val] of Object.entries(headers)) {
+          if (typeof key === 'string' && !ERR_HEADER_EXPR.test(key)) {
+            res.setHeader(key, val          )
+          }
+        }
+      } else if (Array.isArray(err.headers)) {
+        assert(headers.length % 2 === 0)
+        assert(headers.length === 0 || typeof headers[0] === 'string')
+        for (let n = 0; n < headers.length; n += 2) {
+          const key = headers[n + 0]
+          const val = headers[n + 1]
+          if (typeof key === 'string' && !ERR_HEADER_EXPR.test(key)) {
+            res.setHeader(key, val          )
+          }
+        }
+      } else if (err.headers != null) {
+        reqLogger?.warn({ req, err }, 'invalid headers')
+      }
+
+      if (isPlainObject(err.body)) {
+        res.setHeader('content-type', 'application/json')
+        res.end(JSON.stringify(err.body))
+      } else if (typeof err.body === 'string') {
+        res.end(err.body          )
+      } else if (Buffer.isBuffer(err.body)) {
+        res.end(err.body          )
+      } else if (err.expose === true && typeof err.message === 'string') {
+        res.setHeader('content-type', 'application/json')
+        res.end(JSON.stringify({ message: err.message }))
+      } else {
+        res.end()
+      }
+
+      if (statusCode < 500) {
+        reqLogger?.warn({ req, res, err, elapsedTime }, 'request failed')
+      } else {
+        reqLogger?.error({ req, res, err, elapsedTime }, 'request error')
+      }
+    } else {
+      if (req.aborted || (!res.errored && res.closed) || err.name === 'AbortError') {
+        reqLogger?.debug({ req, res, err, elapsedTime }, 'request aborted')
+      } else if (statusCode < 500) {
+        reqLogger?.warn({ req, res, err, elapsedTime }, 'request failed')
+      } else {
+        reqLogger?.error({ req, res, err, elapsedTime }, 'request error')
+      }
+      res.destroy(err         )
+    }
+  } finally {
+    if (stats?.pending != null) {
+      stats.pending--
+    }
+
+    if (ctx[kPendingIndex] !== -1) {
+      const idx = ctx[kPendingIndex]
+      ctx[kPendingIndex] = -1
+
+      const tmp = pending.pop() 
+      if (tmp !== ctx) {
+        pending[idx] = tmp
+        tmp[kPendingIndex] = idx
+      }
+    }
+
+    if (
+      res.writableEnded ||
+      res.destroyed ||
+      ('stream' in res && (res                                                  ).stream?.destroyed)
+    ) {
+      // Do nothing..
+    } else {
+      res.on('error', noop)
+      res.destroy()
+      ctx.logger?.warn('request destroyed')
+    }
+  }
+}
+
+export class IncomingMessage extends http.IncomingMessage {
+  #host                    
+  #url                    
+  #socket                        
+  #target                                            
+
+  #id                    
+  #search                    
+  #query                                    
+
+  get id()         {
+    return (this.#id ??= (this.headers['request-id']          ) || genReqId())
+  }
+
+  get target()                                 {
+    if (
+      this.#host !== this.headers.host ||
+      this.#url !== this.url ||
+      this.#socket !== this.socket
+    ) {
+      this.#socket = this.socket 
+      this.#host = this.headers.host
+      this.#url = this.url 
+      this.#target = undefined
+    }
+
+    if (this.#target === undefined) {
+      const t = requestTarget(this)
+      this.#target = t ? Object.freeze(t) : null
+    }
+    return this.#target
+  }
+
+  get query()                         {
+    const search = this.target?.search
+
+    if (this.#search !== search) {
+      this.#search = search
+      this.#query = undefined
+    }
+
+    return (this.#query ??=
+      search && search.length > 1 ? Object.freeze(querystring.parse(search.slice(1))) : {})
+  }
+}
+
+export class ServerResponse extends http.ServerResponse {
+  #bytesWritten = 0
+
+  #created = performance.now()
+  #connect = -1
+  #headers = -1
+  #data = -1
+  #end = -1
+
+  #headersObj                                     = kEmptyObj                                      
+  #headersSent = false
+
+  get timing()   
+                   
+                   
+                   
+                
+               
+    {
+    return {
+      created: performance.timeOrigin + this.#created,
+      connect: this.#connect,
+      headers: this.#headers,
+      data: this.#data,
+      end: this.#end,
+    }
+  }
+
+  get bytesWritten()         {
+    return this.#bytesWritten
+  }
+
+  setHeader(key        , val                 )       {
+    if (this.#headersSent) {
+      throw new Error('headers already sent')
+    }
+
+    if (this.#headersObj === (kEmptyObj           )) {
+      this.#headersObj = {}
+    }
+
+    this.#headersObj[key] = val === undefined ? undefined : `${val}`
+    return this
+  }
+
+  removeHeader(key        )       {
+    if (this.#headersSent) {
+      throw new Error('headers already sent')
+    }
+
+    if (this.#headersObj !== (kEmptyObj           )) {
+      delete this.#headersObj[key]
+    }
+  }
+
+  getHeaderNames()           {
+    return this.#headersObj === (kEmptyObj           )
+      ? (kEmptyArr            )
+      : Object.keys(this.#headersObj)
+  }
+
+  getHeaders()                                     {
+    return this.#headersObj
+  }
+
+  // @ts-expect-error override property with accessor
+  get headersSent()          {
+    return this.#headersSent
+  }
+
+                                                                                                 
+                                                                         
+  writeHead(
+    statusCode        ,
+    statusMessageOrHeaders                                    ,
+    maybeHeaders                           ,
+  )       {
+    if (this.#headersSent) {
+      throw new Error('headers already sent')
+    }
+
+    let headers                                      
+    let statusMessage                    
+    if (typeof statusMessageOrHeaders === 'string') {
+      statusMessage = statusMessageOrHeaders
+      headers = maybeHeaders
+    } else {
+      headers = statusMessageOrHeaders
+    }
+
+    if (this.#headersObj !== (kEmptyObj           )) {
+      headers = headers ? Object.assign(this.#headersObj, headers) : this.#headersObj
+    }
+
+    if (!this.destroyed) {
+      if (this.#headers === -1) {
+        this.#headers = performance.now() - this.#created
+      }
+    }
+
+    this.#headersSent = true
+
+    if (statusMessage) {
+      return super.writeHead(statusCode, statusMessage, headers)
+    }
+    return super.writeHead(statusCode, headers)
+  }
+
+  assignSocket(socket            )       {
+    if (!this.destroyed) {
+      if (this.#connect === -1) {
+        this.#connect = performance.now() - this.#created
+      }
+    }
+    return super.assignSocket(socket)
+  }
+
+                                                                                              
+        
+                           
+                             
+                                                         
+            
+  write(
+    chunk                 ,
+    encoding                                                               ,
+    callback                                            ,
+  )          {
+    if (!this.destroyed) {
+      if (this.#data === -1) {
+        this.#data = performance.now() - this.#created
+      }
+
+      if (this.#headers === -1) {
+        this.#headers = this.#data
+      }
+    }
+
+    if (chunk != null && typeof chunk !== 'function') {
+      if (typeof chunk !== 'string' && this.#bytesWritten >= 0) {
+        this.#bytesWritten += chunk.byteLength
+      } else {
+        this.#bytesWritten = -1
+      }
+    }
+
+    return super.write(chunk, encoding                  , callback)
+  }
+
+                                  
+                                                             
+                                                                                       
+  end(
+    chunk                                     ,
+    encoding                                ,
+    callback             ,
+  )       {
+    if (!this.destroyed) {
+      this.#end = performance.now() - this.#created
+
+      if (this.#data === -1) {
+        this.#data = this.#end
+      }
+
+      if (this.#headers === -1) {
+        this.#headers = this.#end
+      }
+    }
+
+    if (chunk != null && typeof chunk !== 'function') {
+      if (typeof chunk !== 'string' && this.#bytesWritten >= 0) {
+        this.#bytesWritten += chunk.byteLength
+      } else {
+        this.#bytesWritten = -1
+      }
+    }
+
+    return super.end(chunk, encoding                  , callback)
+  }
+
+  destroy(err        )       {
+    if (!this.destroyed) {
+      if (this.#end === -1) {
+        this.#end = performance.now() - this.#created
+      }
+    }
+
+    return super.destroy(err)
+  }
+}
+
+export class Http2ServerRequest extends http2.Http2ServerRequest {
+  #host                    
+  #url                    
+  #socket                                    
+  #target                                            
+
+  #id                    
+  #search                    
+  #query                                    
+
+  get id()         {
+    return (this.#id ??= (this.headers['request-id']          ) || genReqId())
+  }
+
+  get target()                                 {
+    if (
+      this.#host !== this.headers.host ||
+      this.#url !== this.url ||
+      this.#socket !== this.socket
+    ) {
+      this.#socket = this.socket
+      this.#host = this.headers.host
+      this.#url = this.url 
+      this.#target = undefined
+    }
+
+    if (this.#target === undefined) {
+      const t = requestTargetSlow(this)
+      this.#target = t ? Object.freeze(t) : null
+    }
+    return this.#target
+  }
+
+  get query()                         {
+    const search = this.target?.search
+
+    if (this.#search !== search) {
+      this.#search = search
+      this.#query = undefined
+    }
+
+    return (this.#query ??=
+      search && search.length > 1 ? Object.freeze(querystring.parse(search.slice(1))) : {})
+  }
+}
+
+export class Http2ServerResponse extends http2.Http2ServerResponse {
+  #created = performance.now()
+  #bytesWritten = 0
+  #connect = -1
+  #headers = -1
+  #data = -1
+  #end = -1
+
+  #headersObj                                     = kEmptyObj                                      
+  #headersSent = false
+
+  get timing()   
+                   
+                   
+                   
+                
+               
+    {
+    return {
+      created: performance.timeOrigin + this.#created,
+      connect: this.#connect,
+      headers: this.#headers,
+      data: this.#data,
+      end: this.#end,
+    }
+  }
+
+  get bytesWritten()         {
+    return this.#bytesWritten
+  }
+
+  setHeader(key        , val                 )       {
+    if (this.#headersSent) {
+      throw new Error('headers already sent')
+    }
+
+    if (this.#headersObj === (kEmptyObj           )) {
+      this.#headersObj = {}
+    }
+
+    this.#headersObj[key] = val === undefined ? undefined : `${val}`
+    return this
+  }
+
+  removeHeader(key        )       {
+    if (this.#headersSent) {
+      throw new Error('headers already sent')
+    }
+
+    if (this.#headersObj !== (kEmptyObj           )) {
+      delete this.#headersObj[key]
+    }
+  }
+
+  getHeaderNames()           {
+    return this.#headersObj === (kEmptyObj           )
+      ? (kEmptyArr            )
+      : Object.keys(this.#headersObj)
+  }
+
+  getHeaders()                                     {
+    return this.#headersObj
+  }
+
+  // @ts-expect-error override property with accessor
+  get headersSent()          {
+    return this.#headersSent
+  }
+
+                                                                          
+                                                                                                 
+  writeHead(
+    statusCode        ,
+    statusMessageOrHeaders                                     ,
+    maybeHeaders                            ,
+  )       {
+    if (this.#headersSent) {
+      throw new Error('headers already sent')
+    }
+
+    let headers                                       
+    let statusMessage                    
+    if (typeof statusMessageOrHeaders === 'string') {
+      statusMessage = statusMessageOrHeaders
+      headers = maybeHeaders
+    } else {
+      headers = statusMessageOrHeaders
+    }
+
+    if (this.#headersObj !== (kEmptyObj           )) {
+      headers = headers ? Object.assign(this.#headersObj, headers) : this.#headersObj
+    }
+
+    if (!this.destroyed) {
+      if (this.#headers === -1) {
+        this.#headers = performance.now() - this.#created
+      }
+    }
+
+    this.#headersSent = true
+
+    if (statusMessage) {
+      return super.writeHead(statusCode, statusMessage, headers)
+    }
+    return super.writeHead(statusCode, headers)
+  }
+
+                                                                             
+        
+                               
+                             
+                                    
+            
+  write(
+    chunk                     ,
+    encoding                                          ,
+    callback                       ,
+  )          {
+    if (!this.destroyed) {
+      if (this.#data === -1) {
+        this.#data = performance.now() - this.#created
+      }
+
+      if (this.#headers === -1) {
+        this.#headers = this.#data
+      }
+    }
+
+    if (chunk != null) {
+      if (typeof chunk !== 'string' && this.#bytesWritten >= 0) {
+        this.#bytesWritten += chunk.byteLength
+      } else {
+        this.#bytesWritten = -1
+      }
+    }
+
+    return super.write(chunk, encoding                  , callback)
+  }
+
+                                  
+                                                             
+                                                                                       
+  end(
+    chunk                                     ,
+    encoding                                ,
+    callback             ,
+  )       {
+    if (!this.destroyed) {
+      this.#end = performance.now() - this.#created
+
+      if (this.#data === -1) {
+        this.#data = this.#end
+      }
+
+      if (this.#headers === -1) {
+        this.#headers = this.#end
+      }
+    }
+
+    if (chunk != null && typeof chunk !== 'function') {
+      if (typeof chunk !== 'string' && this.#bytesWritten >= 0) {
+        this.#bytesWritten += chunk.byteLength
+      } else {
+        this.#bytesWritten = -1
+      }
+    }
+
+    return super.end(chunk                       , encoding                  , callback)
+  }
+
+  destroy(err        )       {
+    if (!this.destroyed) {
+      if (this.#end === -1) {
+        this.#end = performance.now() - this.#created
+      }
+    }
+
+    return super.destroy(err)
+  }
+}
+
+                                                          
+                 
+                      
+                        
+                           
+                         
+                         
+ 
+
+                                                                            
+                                                                   
+
+const httpServers = ((globalThis                                      ).__nxt_lib_http_servers =
+  new Array             ())
+                             
+                                       
+                                             
+              
+                             
+                               
+                                       
+                                             
+              
+export function createServer(...args           )              {
+  let options                                 
+  let ctx                                             
+  let middleware                                           
+
+  if (typeof args[0] === 'function') {
+    ctx = args[0]                  
+    middleware = args[1]                                             
+  } else {
+    options = args[0]                                   
+    ctx = args[1]                                               
+    middleware = args[2]                                             
+  }
+
+  if (middleware) {
+    middleware = [middleware].flat(16).filter(Boolean)
+    middleware = middleware.includes(requestMiddleware)
+      ? middleware
+      : [requestMiddleware, ...middleware]
+    middleware = compose(middleware)
+  }
+
+  let factory                                                        
+  if (typeof ctx === 'function') {
+    factory = ctx                                                          
+  } else {
+    const ctxObj = (ctx ?? {})                           
+    const { logger: ctxLogger, ...opaque } = ctxObj
+    const hasOpaque = Object.keys(opaque).length > 0
+
+    factory = (req                 , res                ) => {
+      const context = new Context(req, res, (ctxLogger ?? options?.logger)          )
+      if (hasOpaque) {
+        Object.assign(context, opaque)
+      }
+      return context
+    }
+  }
+
+  const server = http.createServer(
+    {
+      IncomingMessage,
+      ServerResponse,
+      keepAliveTimeout: 2 * 60e3,
+      headersTimeout: 2 * 60e3,
+      requestTimeout: 48 * 60e3,
+      ...options,
+    },
+    (req, res) =>
+      middleware
+        ? middleware(factory(req                   , res                  ), noop)
+        : factory(req                   , res                  ),
+  )
+
+  server.setTimeout(options?.socketTimeout ?? 2 * 60e3)
+
+  if (options?.signal?.aborted) {
+    queueMicrotask(() => server.close())
+  } else {
+    options?.signal?.addEventListener('abort', () => server.close())
+  }
+
+  httpServers.push(server)
+
+  return server
+}
+
+                                                                  
+
+const composeSlim =
+  (middleware                )               =>
+  (ctx, next) => {
+    const dispatch = (i        ) => ()          => {
+      const fn = i === middleware.length ? next : middleware[i]
+      return fn ? fn(ctx, dispatch(i + 1)) : undefined
+    }
+    return dispatch(0)()
+  }
+
+export const compose = (...middleware                                   )               => {
+  const funcs = middleware.flat()
+
+  for (const fn of funcs) {
+    if (typeof fn !== 'function') {
+      throw new TypeError('Middleware must be composed of functions!')
+    }
+  }
+
+  if (process.env.NODE_ENV === 'production') {
+    return composeSlim(funcs)
+  }
+
+  return async (ctx         , next                = noop) => {
+    const dispatch = async (i        )                   => {
+      const fn = i === funcs.length ? next : funcs[i]
+      if (!fn) {
+        return
+      }
+
+      let nextCalled = false
+      let nextResolved = false
+      const nextProxy = async () => {
+        if (nextCalled) {
+          throw Error('next() called multiple times')
+        }
+        nextCalled = true
+        try {
+          return await dispatch(i + 1)
+        } finally {
+          nextResolved = true
+        }
+      }
+      const result = await fn(ctx, nextProxy)
+      if (nextCalled && !nextResolved) {
+        throw Error(
+          'Middleware resolved before downstream.\n\tYou are probably missing an await or return',
+        )
+      }
+      return result
+    }
+    return dispatch(0)
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@nxtedition/http",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf lib && tsc && amaroc ./src/index.ts && mv src/index.js lib/",
+    "prepublishOnly": "yarn build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --experimental-test-coverage --test-coverage-include=src/index.ts --test-coverage-lines=65 --test-coverage-branches=80 --test-coverage-functions=60",
+    "test:ci": "node --test --experimental-test-coverage --test-coverage-include=src/index.ts --test-coverage-lines=65 --test-coverage-branches=80 --test-coverage-functions=60"
+  },
+  "dependencies": {
+    "@nxtedition/scheduler": "^3.0.9",
+    "fast-querystring": "^1.1.2",
+    "request-target": "^1.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "amaroc": "^1.0.1",
+    "oxlint-tsgolint": "^0.12.2",
+    "rimraf": "^6.1.2",
+    "typescript": "^5.9.3"
+  },
+  "gitHead": "64c1bd97cf9a785ca4a750b5380418878cbed2d2"
+}