@znight/http 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,144 @@
 {
   "name": "@znight/http",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Znight HTTP plugin: controllers, routing, guards, interceptors, validation with Fastify, Express or Hono",
+  "license": "MIT",
+  "author": "Ugho STEPHAN",
+  "homepage": "https://github.com/znight-org/znight/tree/main/packages/http#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/znight-org/znight.git",
+    "directory": "packages/http"
+  },
+  "bugs": "https://github.com/znight-org/znight/issues",
+  "keywords": [
+    "znight",
+    "http",
+    "rest",
+    "controllers",
+    "routing",
+    "guards",
+    "interceptors",
+    "validation",
+    "standard-schema",
+    "fastify",
+    "express",
+    "hono",
+    "bun"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "@znight/source": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./path": {
+      "@znight/source": "./src/path.ts",
+      "types": "./dist/path.d.mts",
+      "default": "./dist/path.mjs"
+    },
+    "./node": {
+      "@znight/source": "./src/adapters/node.ts",
+      "types": "./dist/node.d.mts",
+      "default": "./dist/node.mjs"
+    },
+    "./fastify": {
+      "@znight/source": "./src/adapters/fastify.ts",
+      "types": "./dist/fastify.d.mts",
+      "default": "./dist/fastify.mjs"
+    },
+    "./express": {
+      "@znight/source": "./src/adapters/express.ts",
+      "types": "./dist/express.d.mts",
+      "default": "./dist/express.mjs"
+    },
+    "./hono": {
+      "@znight/source": "./src/adapters/hono.ts",
+      "types": "./dist/hono.d.mts",
+      "default": "./dist/hono.mjs"
+    },
+    "./compiler": {
+      "@znight/source": "./src/compiler/index.ts",
+      "types": "./dist/compiler.d.mts",
+      "default": "./dist/compiler.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@znight/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@hono/node-server": "^2.1.5",
+    "express": "^5.3.0",
+    "fastify": "^5.12.7",
+    "hono": "^4.13.14",
+    "light-my-request": "^6.8.0",
+    "@znight/compiler": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@hono/node-server": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "light-my-request": {
+      "optional": true
+    },
+    "@znight/compiler": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@hono/node-server": "2.1.5",
+    "@types/express": "5.0.6",
+    "express": "5.3.0",
+    "fastify": "5.12.7",
+    "hono": "4.13.14",
+    "valibot": "1.5.0",
+    "zod": "4.6.7",
+    "light-my-request": "6.8.0",
+    "@znight/compiler": "0.1.0"
+  },
+  "znight": {
+    "apiVersion": 1,
+    "compiler": "@znight/http/compiler",
+    "provides": [
+      {
+        "export": "HttpContext",
+        "plugin": "HttpPlugin",
+        "scope": "request"
+      },
+      {
+        "export": "RequestId",
+        "plugin": "HttpPlugin",
+        "scope": "request"
+      },
+      {
+        "export": "HttpPlugin",
+        "plugin": "HttpPlugin",
+        "scope": "singleton"
+      }
+    ]
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,240 @@
+/**
+ * Contract between the HTTP plugin and the server adapters (`@znight/http/node`, `/fastify`,
+ * `/express`, `/hono`). Adapters only route requests to handlers (with their native router) and
+ * translate I/O; everything else (parameters, query and body parsing, guards, serialisation, errors)
+ * is done by the plugin so that every adapter behaves the same.
+ */
+import type { SetCookieInfo } from './cookies.ts'
+import type { HeaderValue } from './exceptions.ts'
+import type { HttpMethod } from './metadata.ts'
+import type { RoutePath } from './path.ts'
+
+/** A request, as seen by the plugin. */
+export interface AdapterRequest {
+  /** Upper-case method. */
+  readonly method: string
+  /** Raw request target: path and query string, percent-encoded (`/users/a%20b?page=2`). */
+  readonly url: string
+  /** Request headers with lower-case names (repeated headers joined with `, `). */
+  readonly headers: Readonly<Record<string, string | undefined>>
+  /**
+   * Client address, when known: the socket peer, or the address the server framework derives from
+   * its own proxy settings (Fastify `trustProxy`, Express `trust proxy`). This is `ctx.ip` unless
+   * the plugin option `trustProxy` is set.
+   */
+  readonly ip: string | undefined
+  /**
+   * Address of the socket peer, **never** taken from headers: where the plugin starts walking
+   * `x-forwarded-for` with `trustProxy`. Optional (`ip` is used without it); the built-in adapters
+   * set it.
+   */
+  readonly remoteAddress?: string | undefined
+  /** `true` when the connection uses TLS (`ctx.protocol` without a trusted proxy). Optional. */
+  readonly encrypted?: boolean
+  /** Native request object (`@Req()`). */
+  readonly raw: unknown
+  /** Native response object (`@Res()`). */
+  readonly rawResponse: unknown
+  /**
+   * Reads the whole body (once). Rejects with a `PayloadTooLargeException` when it exceeds `limit`
+   * bytes (checked on `content-length` first, then while reading).
+   */
+  readBody(limit: number): Promise<Uint8Array>
+  /**
+   * The body as a Web stream, read as the consumer pulls it (once; exclusive with `readBody`). It
+   * errors with a `PayloadTooLargeException` past `limit` bytes (`content-length` checked first) and
+   * with a `BadRequestException` when the client aborts. Cancelling it discards the rest of the body
+   * without closing the connection before the response is written. Optional: without it the plugin
+   * streams the result of `readBody` (multipart uploads are then buffered before being parsed).
+   */
+  streamBody?(limit: number): ReadableStream<Uint8Array>
+  /**
+   * Whether the request has a body, asked only when its headers declare none (neither
+   * `content-length` nor `transfer-encoding`: Web `Request`s built in memory). Return `false` for
+   * requests read from an HTTP/1.1 connection (without those headers they have no body). Optional:
+   * no body is assumed otherwise.
+   */
+  hasBody?(): boolean
+  /** Status written by a handler that took over the response with `@Res()`, when known. */
+  rawStatus?(): number | undefined
+  /**
+   * Registers a listener called once when the client disconnects before the response was fully
+   * written. When it already happened, the listener is called on the next microtask. Never called
+   * after a complete response. Optional: without it, `ctx.signal` only aborts when the response
+   * body is cancelled or an event stream is closed by the server.
+   */
+  onAbort?(listener: () => void): void
+}
+
+/**
+ * Body of a reply: bytes, a stream or nothing. Adapters MUST either read a stream to its end or
+ * cancel it (client disconnected, response not sent...): the request scope and the in-flight count
+ * are released then. A `Blob` is sent with its size; the plugin itself never passes one: it sends
+ * files as a stream reading the `Blob`, given in {@link AdapterReply.blob}.
+ */
+export type ReplyBody = Uint8Array | ReadableStream<Uint8Array> | Blob | null
+
+/** A response computed by the plugin, written by the adapter. */
+export interface AdapterReply {
+  readonly status: number
+  /** Response headers, lower-case names (validated: every name and value can be sent). */
+  readonly headers: Readonly<Record<string, HeaderValue>>
+  /** `null` for HEAD requests and bodyless statuses (headers such as `content-length` are kept). */
+  readonly body: ReplyBody
+  /**
+   * The `Blob` (file) that `body` streams, for adapters able to send it natively (`sendfile`, exact
+   * length: `new Response(blob)` on `Bun.serve()`). An adapter sending it instead of reading `body`
+   * MUST cancel `body` once the server holds the blob (file opened): that releases the request
+   * scope, which may delete the file. Headers (`content-length`...) are the same either way.
+   */
+  readonly blob?: Blob
+  /** The handler wrote the response itself through `@Res()`: write nothing. */
+  readonly raw?: boolean
+  /**
+   * The body is a long-lived event stream (a streamed `text/event-stream` body: `@Sse`,
+   * `HttpResponse.sse()`, a proxied `fetch()` response...). Adapters MUST send the headers without
+   * waiting for the first chunk (a quiet stream may send nothing for a while), MUST NOT apply idle or
+   * inactivity timeouts to the response while it is sent, and MUST write each chunk as soon as it is
+   * read (no buffering, no compression).
+   */
+  readonly eventStream?: boolean
+}
+
+/** Handles one request. Never rejects: errors are already mapped to a reply. */
+export type AdapterHandler = (request: AdapterRequest) => Promise<AdapterReply>
+
+/**
+ * Handles requests no route matched (`404`/`405`, automatic `OPTIONS`) and errors raised by the
+ * server framework before a route handler ran (`error`, e.g. a malformed URL). Never rejects.
+ */
+export type FallbackHandler = (request: AdapterRequest, error?: unknown) => Promise<AdapterReply>
+
+/** A concrete route to register (the plugin expands `ALL` and adds `HEAD` for `GET` routes). */
+export interface AdapterRoute {
+  readonly method: Exclude<HttpMethod, 'ALL'>
+  /** Parsed full path (plugin prefix included). Translate it with the helpers of `@znight/http/path`. */
+  readonly path: RoutePath
+  readonly handler: AdapterHandler
+}
+
+/** Address of a listening server. Converts to its URL (`String(address)`). */
+export interface HttpServerAddress {
+  /** Host the server is bound to (`0.0.0.0`, `::`, `127.0.0.1`...). */
+  readonly host: string
+  readonly port: number
+  /** `IPv4` or `IPv6`. */
+  readonly family: string
+  /** Base URL usable by clients (`http://127.0.0.1:3000`; wildcard hosts become loopback addresses). */
+  readonly url: string
+  toString(): string
+}
+
+/** A request for {@link HttpAdapter.inject} (in-memory, no network). */
+export interface InjectRequest {
+  readonly method: string
+  /** Path and optional query string (`/users?page=2`). */
+  readonly url: string
+  readonly headers?: Readonly<Record<string, string>>
+  /**
+   * Request body: a string or bytes are sent as is (`text/plain` / `application/octet-stream` when
+   * no `content-type` is given), a `FormData` as `multipart/form-data` (files included), a `Blob` /
+   * `File` with its type, anything else as JSON (`application/json`).
+   */
+  readonly body?: unknown
+  /** Query parameters appended to `url`. */
+  readonly query?: Readonly<Record<string, string | readonly string[]>>
+  /**
+   * Request cookies (name → value), sent in a `cookie` header after any `cookie` header of
+   * `headers`. Values are encoded like the values of `serializeCookie`, so a value read from
+   * `response.cookies` can be sent back as is (signed values included).
+   */
+  readonly cookies?: Readonly<Record<string, string>>
+  /**
+   * Cookies signed by `HttpPlugin` with its first secret (`cookies.secrets`) and merged into
+   * `cookies` before dispatch: the way to send a valid `@SignedCookie`. Adapters never receive this
+   * field.
+   */
+  readonly signedCookies?: Readonly<Record<string, string>>
+}
+
+/** A request for {@link HttpAdapter.injectStream}: an {@link InjectRequest} that can be aborted. */
+export interface InjectStreamRequest extends InjectRequest {
+  /** Aborting it disconnects the client (like cancelling the response body). */
+  readonly signal?: AbortSignal
+}
+
+/**
+ * A request for `HttpPlugin.injectStream()` / `injectSse()`: an {@link InjectStreamRequest} whose
+ * method defaults to `GET`.
+ */
+export type InjectStreamOptions = Omit<InjectStreamRequest, 'method'> & { readonly method?: string }
+
+/** The response of {@link HttpAdapter.inject}. */
+export interface InjectResponse {
+  readonly status: number
+  /**
+   * Lower-case header names; repeated headers are joined with `, `, except `set-cookie`: an array
+   * with one entry per cookie (cookie values may contain `, `).
+   */
+  readonly headers: Record<string, string | string[]>
+  /** Body decoded as UTF-8. */
+  readonly body: string
+  /** Raw body bytes (binary downloads). */
+  readonly bytes: Uint8Array
+  /** `JSON.parse(body)`. */
+  json<T = unknown>(): T
+  /** `set-cookie` parsed, by cookie name (the last one wins). */
+  readonly cookies: Readonly<Record<string, SetCookieInfo>>
+}
+
+/**
+ * The response of {@link HttpAdapter.injectStream}: available as soon as the headers are sent, its
+ * body read as it is produced.
+ */
+export interface InjectStreamResponse {
+  readonly status: number
+  /** Like {@link InjectResponse.headers} (`set-cookie` as an array). */
+  readonly headers: Record<string, string | string[]>
+  readonly cookies: Readonly<Record<string, SetCookieInfo>>
+  /** The body as it is produced. Cancelling it disconnects the client (the server sees `onAbort` and a cancelled reply body). */
+  readonly body: ReadableStream<Uint8Array>
+}
+
+/** Options of {@link HttpAdapter.close}. */
+export interface AdapterCloseOptions {
+  /** Destroy open connections instead of waiting for in-flight requests. */
+  readonly force?: boolean
+}
+
+/**
+ * A server implementation. Create one with `nodeAdapter()` (default), `fastifyAdapter()`,
+ * `expressAdapter()` or `honoAdapter()`. An adapter instance serves one plugin.
+ */
+export interface HttpAdapter {
+  /** `node`, `fastify`, `express`, `hono`... (exposed as `ctx.adapter`). */
+  readonly name: string
+  /** Registers a route. Called during `onBootstrap`, before `listen`/`inject`. */
+  registerRoute(route: AdapterRoute): void
+  /** Sets the handler of unmatched requests and framework errors. Called once, before `listen`/`inject`. */
+  setFallbackHandler(handler: FallbackHandler): void
+  /** Starts listening. `port` 0 picks a free port. */
+  listen(port: number, host: string): Promise<HttpServerAddress>
+  /**
+   * Stops accepting connections, closes idle ones and resolves once in-flight requests completed and
+   * every connection is closed (`force`: destroys them). Idempotent; also releases what the adapter
+   * created when it never listened.
+   */
+  close(options?: AdapterCloseOptions): Promise<void>
+  /**
+   * Sends a request in memory (no socket), through the same routing and pipeline, and reads the
+   * whole response. The built-in adapters reject an event stream (`text/event-stream`, which would
+   * never end) with a hint to `injectSse()` / `injectStream()`.
+   */
+  inject(request: InjectRequest): Promise<InjectResponse>
+  /**
+   * In-memory request whose response body is returned as it is produced (resolves at the headers).
+   * Cancelling `body` (or aborting `signal`) disconnects the client. Optional for third-party
+   * adapters; the four built-in adapters implement it.
+   */
+  injectStream?(request: InjectStreamRequest): Promise<InjectStreamResponse>
+}

package/src/adapters/express.ts

@@ -0,0 +1,201 @@
+/**
+ * `@znight/http/express`: serves Znight routes with [Express](https://expressjs.com) 5 (optional
+ * peer dependency `express`). Routes are mounted on a dedicated router, after the middleware of the
+ * application you pass. `inject()` uses the optional peer `light-my-request`.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type {
+  AdapterCloseOptions,
+  AdapterRoute,
+  FallbackHandler,
+  HttpAdapter,
+  HttpServerAddress,
+  InjectRequest,
+  InjectResponse,
+  InjectStreamRequest,
+  InjectStreamResponse,
+} from '../adapter.ts'
+
+import { createServer, type Server } from 'node:http'
+import express, { type Express, type NextFunction, type Request, type Response, type Router } from 'express'
+
+import { toRegExpSource } from '../path.ts'
+import { ConnectionTracker, closeServer, nodeAdapterRequest, writeNodeFailure, writeNodeReply } from './node-io.ts'
+import { bufferInjectStream, injectNodeStream, serverAddress } from './shared.ts'
+
+/** Options of {@link expressAdapter}. */
+export interface ExpressAdapterOptions {
+  /**
+   * An existing application: its middleware (CORS, helmet, sessions...) runs before the Znight
+   * routes. Do not add body parsers for Znight routes: Znight reads bodies itself.
+   */
+  readonly app?: Express
+  /**
+   * The server to listen with (e.g. `https.createServer({ key, cert })`): the adapter adds its
+   * `request` listener. Default: a new `http.createServer()`.
+   */
+  readonly server?: Server
+}
+
+/** The Express adapter. */
+export interface ExpressAdapter extends HttpAdapter {
+  readonly name: 'express'
+  /** The Express application. */
+  readonly app: Express
+  /** The router holding the Znight routes (mounted on {@link app}). */
+  readonly router: Router
+  /** The HTTP server, once listening. */
+  readonly server: Server | undefined
+}
+
+/**
+ * Creates an Express adapter.
+ *
+ * ```ts
+ * import { expressAdapter } from '@znight/http/express'
+ *
+ * const app = express()
+ * app.use(cors())
+ * HttpPlugin.configure({ adapter: expressAdapter({ app }) })
+ * ```
+ */
+export function expressAdapter(options: ExpressAdapterOptions = {}): ExpressAdapter {
+  return new ExpressHttpAdapter(options)
+}
+
+type Method = 'get' | 'head' | 'post' | 'put' | 'patch' | 'delete' | 'options'
+
+class ExpressHttpAdapter implements ExpressAdapter {
+  readonly name = 'express' as const
+  readonly app: Express
+  readonly router: Router
+  #fallback: FallbackHandler | undefined
+  #mounted = false
+  #server: Server | undefined
+  #tracker: ConnectionTracker | undefined
+  #closing: Promise<void> | undefined
+
+  readonly #givenServer: Server | undefined
+
+  constructor(options: ExpressAdapterOptions) {
+    this.#givenServer = options.server
+    if (options.app === undefined) {
+      this.app = express()
+      this.app.disable('x-powered-by')
+    } else {
+      this.app = options.app
+    }
+    this.router = express.Router({ caseSensitive: true, strict: true })
+  }
+
+  get server(): Server | undefined {
+    return this.#server
+  }
+
+  registerRoute(route: AdapterRoute): void {
+    const handler = route.handler
+    // anchored regular expressions without capture groups: Express decodes nothing, Znight extracts parameters
+    this.router[route.method.toLowerCase() as Method](new RegExp(toRegExpSource(route.path)), (request, response) => {
+      handler(adapterRequest(request, response)).then(
+        reply => writeNodeReply(response, reply),
+        () => writeNodeFailure(response),
+      )
+    })
+  }
+
+  setFallbackHandler(handler: FallbackHandler): void {
+    this.#fallback = handler
+  }
+
+  #mount(): void {
+    if (this.#mounted) return
+    this.#mounted = true
+    // Express answers unmatched OPTIONS requests itself (200): route them to the Znight fallback
+    this.router.options(/^.*$/, (request: Request, response: Response) =>
+      this.#dispatchFallback(request, response, undefined),
+    )
+    this.app.use(this.router)
+    this.app.use((request: Request, response: Response) => this.#dispatchFallback(request, response, undefined))
+    this.app.use((error: unknown, request: Request, response: Response, _next: NextFunction) =>
+      this.#dispatchFallback(request, response, error),
+    )
+  }
+
+  #dispatchFallback(request: Request, response: Response, error: unknown): void {
+    if (this.#fallback === undefined) {
+      writeNodeFailure(response)
+      return
+    }
+    this.#fallback(adapterRequest(request, response), error).then(
+      reply => writeNodeReply(response, reply),
+      () => writeNodeFailure(response),
+    )
+  }
+
+  readonly #listener = (request: IncomingMessage, response: ServerResponse): void => {
+    this.app(request as Request, response as Response)
+  }
+
+  async listen(port: number, host: string): Promise<HttpServerAddress> {
+    this.#mount()
+    const server = this.#givenServer ?? createServer()
+    if (!server.listeners('request').includes(this.#listener)) server.on('request', this.#listener)
+    this.#server = server
+    this.#tracker ??= new ConnectionTracker(server)
+    this.#closing = undefined
+    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> {
+    this.#mount()
+    return injectNodeStream('express', this.#injectListener as (req: never, res: never) => void, request)
+  }
+
+  /**
+   * Express replaces the prototype of `req`/`res` with its own, which drops the overrides of the
+   * light-my-request fakes (payload capture, body streaming): pin them as own properties first.
+   */
+  readonly #injectListener = (request: IncomingMessage, response: ServerResponse): void => {
+    pinPrototype(request)
+    pinPrototype(response)
+    this.#listener(request, response)
+  }
+}
+
+function pinPrototype(target: object): void {
+  const prototype: unknown = Object.getPrototypeOf(target)
+  if (prototype === null || typeof prototype !== 'object') return
+  for (const key of Object.getOwnPropertyNames(prototype)) {
+    if (key === 'constructor' || Object.hasOwn(target, key)) continue
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, key)
+    if (typeof descriptor?.value === 'function') {
+      Object.defineProperty(target, key, { value: descriptor.value, writable: true, configurable: true })
+    }
+  }
+}
+
+function adapterRequest(request: Request, response: Response): ReturnType<typeof nodeAdapterRequest> {
+  return nodeAdapterRequest(request, response, { url: request.originalUrl ?? request.url, ip: request.ip })
+}