@zudojs/http 1.2.0 → 1.4.0

package/README.md

@@ -33,6 +33,10 @@ const server = createHttpServer({
 await server.start();
 ```
 
+`createHttpServer` takes `HttpServerOptions`, so `request` in the handler
+above is typed `HttpRequestContext` without an annotation (the options used
+to be typed `unknown`, which failed `strict` builds with TS7006).
+
 A handler receives an `HttpRequestContext` and may return an
 `HttpResponseContext` or any JSON value. **Every value that is not an
 `HttpResponseContext` is data**: a plain object such as `{ status: "ok" }` is
@@ -72,6 +76,15 @@ answers 502 and never exposes the cause.
   wraps `@zudojs/security`'s `createRateLimiter`. Requests with no usable
   client address share one bucket (`UNKNOWN_CLIENT_RATE_LIMIT_IP`,
   `0.0.0.0`): they are limited together, never unlimited and never a 500.
+  The 429 carries a JSON body sent as `application/json` and always a
+  `Retry-After` header, even when a custom limiter handler omits it.
+- **Request ids.** `request.id` reuses the client's `x-request-id` when it is
+  1-128 characters of `[A-Za-z0-9._:-]`; any other value is ignored and a
+  UUID is generated, so an id copied into logs can never carry spaces,
+  quotes or control characters. `createNodeHttpAdapter({ trustRequestId:
+  false })` always generates one. The request guard's own `X-Request-Id`
+  check (letters, digits, `_`, `-`) still answers 400 to a malformed header
+  first unless it is tuned or turned off.
 - Signed-cookie signatures are compared with `@zudojs/crypto`'s constant-time
   `timingSafeEqualString`.
 - Contexts built by the stock adapters log through a `@zudojs/logger` console
@@ -82,12 +95,220 @@ answers 502 and never exposes the cause.
 - `HttpServer.stop()` gives in-flight requests the full
   `gracefulShutdownTimeout`.
 
+## Routes
+
+A route handler returns what a server handler returns:
+
+```typescript
+router.get("/health", () => ({ status: "ok" }));          // 200, JSON body
+router.get("/users/:id", async (ctx) => loadUser(ctx.params.id));
+router.post("/users", () =>
+  createResponseContext({ status: 201, body: { created: true } }),
+);
+router.delete("/users/:id", () => undefined);              // 204
+```
+
+A plain value (object, array, string, number, boolean) is sent as `200`
+with a JSON body; `undefined` or `null` is `204 No Content`; an
+`HttpResponseContext` or a web `Response` is sent as built. (A plain
+object used to be a type error and was sent as an empty `204`.) The
+router and `RouteDispatcher` behave the same.
+
+Route parameters are set on the request before route middleware runs, so
+`ctx.request.getParam("id")` works in a guard or an `extractResource`
+loader as well as in the handler (`ctx.params`).
+
+## Middleware errors
+
+An error thrown by a middleware or handler propagates **as the error that
+was thrown**. An outer middleware's `await next()` rejects with it, the
+pipeline's `onError` receives it, and so does the server's `errorHandler`,
+so `error instanceof NotFoundError` works in each. It used to arrive wrapped
+in `HttpMiddlewareError` (inside a middleware) or
+`HttpMiddlewarePipelineError` (in `errorHandler`), with the original only in
+`cause` / `errors[0].cause`.
+
+Code after `await next()` does not run when the chain below it throws,
+unless the middleware catches the error:
+
+```typescript
+pipeline.use(async (ctx, next) => {
+  const started = Date.now();
+  try {
+    return await next();
+  } finally {
+    log.info("request", { path: ctx.request.path, ms: Date.now() - started });
+  }
+});
+```
+
+If `onError` returns a response, that is the recovery; if it throws, what
+it threw propagates (rethrow the error to pass it on, or throw a different
+one to translate it).
+
+`new HttpError(415, "No XML")` without a `code` gets its code from the
+status (`"UNSUPPORTED_MEDIA_TYPE"`, `"NOT_FOUND"`, ...), matching the
+`notFound()`-style factories, instead of `ERR_OPERATION_FAILED`.
+
+## HTTP client: retries and backoff
+
+```typescript
+const client = new HttpClient({
+  timeout: 5_000,
+  retry: { retries: 3, retryDelay: 200, maxRetryDelay: 5_000 },
+});
+```
+
+- **What is retried:** responses with a status in `retryStatusCodes`
+  (default 429, 502, 503, 504); transport failures such as a refused
+  connection (`retryOnNetworkError`, default `true`); and requests that hit
+  `timeout` (`retryOnTimeout`, default: the `retryOnNetworkError` value).
+  Timeouts used to be excluded, so a `GET` with retries still failed on
+  the first timeout. Aborting through your own `signal` is never retried.
+- **Which methods:** only `retryMethods` (default `GET`, `HEAD`,
+  `OPTIONS`). A `POST` that timed out may already have been processed, so
+  it is not replayed unless you list it.
+- **Backoff:** the delay is `retryDelay` (default 1000 ms) times
+  `2^attempt` with `backoff: "exponential"` (the default), or `retryDelay`
+  every time with `"fixed"`, capped at `maxRetryDelay` (default 30 s).
+- **Jitter:** each wait is drawn uniformly between 0 and that delay (full
+  jitter), so clients that failed together do not retry in lockstep.
+  `jitter: false` waits exactly the delay. Jitter used to add up to a fixed
+  second regardless of `retryDelay`.
+- `retries` counts retries after the first attempt (default 0).
+
+## OpenAPI from your routes
+
+Routes carry their own documentation through the `openapi` option, and the
+document is generated from the routes the router actually registered — no
+second list to keep in sync. Schemas may be `@zudojs/schema` schemas or raw
+OpenAPI schemas.
+
+```typescript
+import { objectSchema, stringSchema, numberSchema, optionalSchema } from "@zudojs/schema";
+import { createRouter, generateOpenAPIDocument, mountOpenAPI } from "@zudojs/http";
+
+const user = objectSchema({ id: stringSchema().uuid(), name: stringSchema() });
+
+const router = createRouter();
+router.get("/users/:id", getUser, {
+  openapi: {
+    summary: "Get a user",
+    tags: ["users"],
+    params: objectSchema({ id: stringSchema().uuid() }),
+    responses: { "200": { schema: user }, "404": { description: "No such user" } },
+  },
+});
+router.get("/users", listUsers, {
+  openapi: { query: objectSchema({ limit: optionalSchema(numberSchema().int()) }) },
+});
+router.post("/users", createUser, {
+  openapi: { body: objectSchema({ name: stringSchema() }), responses: { "201": { schema: user } } },
+});
+router.get("/health", health, { openapi: false }); // never documented
+
+// One-off document:
+const document = generateOpenAPIDocument(router, {
+  info: { title: "Users API", version: "1.0.0" },
+  exclude: ["/internal/*"],
+  validate: true,
+});
+
+// Or serve it: GET /openapi.json and a Swagger UI page at GET /docs.
+mountOpenAPI(router, {
+  info: { title: "Users API", version: "1.0.0" },
+  yamlPath: "/openapi.yaml",        // optional
+  ui: { renderer: "redoc" },        // optional; any renderOpenAPIUI option
+});
+```
+
+- `:id` and `{id}` become `{id}`; every template slot is documented even when
+  nothing declares it. A regex-constrained `:id(\d+)` becomes a parameter
+  with that `pattern`, an optional `:id?` is documented as both paths, and a
+  wildcard `*rest` becomes a `{rest}` slot (`wildcards: "exclude"` drops such
+  routes instead).
+- Left out: `all()` routes, `CONNECT`, routes with `openapi: false` or
+  `{ hidden: true }`, and anything matched by `exclude` (exact path,
+  `"/prefix/*"`, a `RegExp`, or a predicate). The router's automatic `HEAD`
+  and `OPTIONS` answers are not registered routes and never appear.
+  `undocumented: "exclude"` documents only routes that declare `openapi`.
+- Router groups pass `openapi` defaults to their routes: tags are unioned,
+  everything else is overridden by the route.
+- The document follows the router: a route added later is in the next
+  `generateOpenAPIDocument` call and the next request to a mounted
+  `/openapi.json`. `createRouterOpenAPI(router, options)` gives the
+  underlying `OpenAPIManager`, re-read only when the route table changed.
+- Paths are configurable (`path`, `docsPath: false` to disable the page,
+  `ui.specUrl` when served under a prefix), and `middleware` protects the
+  documentation routes.
+
+## Mounting web-standard handlers
+
+`mountFetchHandler` serves any `(request: Request) => Response | Promise<Response>`
+handler — an `@zudojs/rpc` server, `@zudojs/api` operations, another
+fetch-style app — under a path of a router or router group.
+
+```typescript
+import { mountFetchHandler } from "@zudojs/http";
+import { createRPCFetchHandler } from "@zudojs/rpc";
+
+const unmount = mountFetchHandler(router, "/rpc", createRPCFetchHandler(rpcServer));
+// { methods: ["POST"], stripPrefix: false, middleware: [auth] } are optional
+```
+
+The handler sees the original method, query, headers (connection-scoped ones
+removed) and body; the mount path is stripped from its URL by default and
+passed as `x-forwarded-prefix`. Its `Response` is streamed back with status,
+status text and headers intact, each `Set-Cookie` kept separate. The
+request's `signal` aborts when the client disconnects. A handler that throws
+or returns something other than a `Response` fails the request like any
+route (a generic 500 unless the error carries a status). `toWebRequest(context)`
+does the request conversion on its own.
+
+The origin of the handler's `request.url` comes from the client's `Host`
+header (or `X-Forwarded-Host` from a trusted proxy) unless you pin it with
+`{ origin: "https://api.example.com" }`. Pin it whenever the handler builds
+absolute URLs or compares `Origin` against its own.
+
+Every Node request context now carries that signal too: `request.signal` and
+the router's `ctx.signal` abort when the client goes away, and a streamed
+response body stops being read.
+
+## Guards that refuse a request
+
+A middleware answers a request itself — 401, 403, 404 — by returning a
+`GuardResponse` from `@zudojs/middleware`. The router, `HttpMiddlewarePipeline`
+and `RouteDispatcher` send it with its own status, headers and body; headers an
+outer middleware already set (CORS, for instance) are kept.
+
+```typescript
+import { createGuardResponse } from "@zudojs/middleware";
+import { authorize } from "@zudojs/permissions";
+
+router.delete("/posts/:id", deletePost, {
+  middleware: [
+    authorize(engine, "post:delete", { extractActor }), // 401 / 403
+    async (ctx, next) =>
+      ctx.request.getHeader("x-confirm")
+        ? next()
+        : createGuardResponse({ status: 400, body: { error: "Confirm first" } }),
+  ],
+});
+```
+
+A route middleware's return value used to be ignored unless it was an
+`HttpResponseContext` or a web `Response`, so `authorize()` and the tenancy
+middleware refused requests with `200`. Only the branded object is honoured: an ordinary
+object with a `status` key keeps its old meaning.
+
 ## Features
 
 - Runtime-independent HTTP server abstraction
 - Request/response wrappers with full Web API compatibility
 - Middleware pipeline with error handling
 - Router with parameter extraction
+- OpenAPI documents generated from the registered routes
+- Mounting of web-standard fetch handlers
 - CORS, security headers, and content negotiation
 - HTTP client with interceptors
 

package/dist/httpAdapter/http.adapters.d.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { HTTPContext, HTTPHandler, HTTPMiddleware, HTTPRequest, HTTPResponse, HTTPRouteMatch, HTTPState } from "../httpTypes/http.types.js";
+import type { TrustProxy } from "../httpTrustProxy/httpTrustProxy.type.js";
 export interface HTTPAdapter<State extends HTTPState = HTTPState> {
     readonly name: string;
     createRequest(request: IncomingMessage): HTTPRequest;
@@ -9,9 +10,21 @@ export interface HTTPAdapter<State extends HTTPState = HTTPState> {
         readonly signal?: AbortSignal;
     }): HTTPContext<State>;
 }
+/**
+ * Options every Node request built by this module accepts.
+ *
+ * `trustProxy` defaults to `false`, so `X-Forwarded-For` and
+ * `X-Forwarded-Proto` are ignored and the socket peer decides `request.ip`,
+ * `request.protocol` and `request.secure`.
+ */
+export interface NodeRequestTrustOptions {
+    readonly trustProxy?: TrustProxy;
+}
 export declare class NodeHTTPAdapter<State extends HTTPState = HTTPState> implements HTTPAdapter<State> {
     readonly name = "node";
-    createRequest(request: IncomingMessage): HTTPRequest;
+    private readonly trustProxy;
+    constructor(options?: NodeRequestTrustOptions);
+    createRequest(request: IncomingMessage, options?: NodeRequestTrustOptions): HTTPRequest;
     createResponse(response: ServerResponse): HTTPResponse;
     createContext(request: HTTPRequest, response: HTTPResponse, options?: {
         readonly state?: State;
@@ -20,12 +33,19 @@ export declare class NodeHTTPAdapter<State extends HTTPState = HTTPState> implem
 }
 export interface HTTPAdapterOptions<State extends HTTPState = HTTPState> {
     readonly adapter?: HTTPAdapter<State>;
+    /**
+     * Which socket peers may speak for a client through `X-Forwarded-*`.
+     * Defaults to `false` — forwarded headers are ignored.
+     */
+    readonly trustProxy?: TrustProxy;
 }
-export declare function createHTTPAdapter<State extends HTTPState = HTTPState>(): NodeHTTPAdapter<State>;
+export declare function createHTTPAdapter<State extends HTTPState = HTTPState>(options?: NodeRequestTrustOptions): NodeHTTPAdapter<State>;
 export interface RequestAdapter {
     toHTTPRequest(request: IncomingMessage): HTTPRequest;
 }
 export declare class NodeRequestAdapter implements RequestAdapter {
+    private readonly trustProxy;
+    constructor(options?: NodeRequestTrustOptions);
     toHTTPRequest(request: IncomingMessage): HTTPRequest;
 }
 export interface ResponseAdapter {
@@ -61,11 +81,12 @@ export declare class DefaultHTTPMiddlewareAdapter<State extends HTTPState = HTTP
 export interface HTTPRouteAdapter<State extends HTTPState = HTTPState> {
     match(method: string, path: string): HTTPRouteMatch<State> | undefined;
 }
-export declare function adaptNodeRequest(request: IncomingMessage): HTTPRequest;
+export declare function adaptNodeRequest(request: IncomingMessage, options?: NodeRequestTrustOptions): HTTPRequest;
 export declare function adaptNodeResponse(response: ServerResponse): HTTPResponse;
 export declare function adaptNodeContext<State extends HTTPState = HTTPState>(request: IncomingMessage, response: ServerResponse, options?: {
     readonly state?: State;
     readonly signal?: AbortSignal;
+    readonly trustProxy?: TrustProxy;
 }): HTTPContext<State>;
 export declare function isHTTPAdapter(value: unknown): value is HTTPAdapter;
 //# sourceMappingURL=http.adapters.d.ts.map

package/dist/httpAdapter/http.adapters.js

@@ -2,13 +2,16 @@ import { createHTTPContext } from "../httpContext/http.context.js";
 import { createHTTPRequest } from "../httpRequest/http.request.js";
 import { createHTTPResponse } from "../httpResponse/http.response.js";
 import { createDefaultContextLogger } from "./httpAdapter.logger.js";
-/* -------------------------------------------------------------------------- */
-/* Node Adapter                                                               */
-/* -------------------------------------------------------------------------- */
 export class NodeHTTPAdapter {
     name = "node";
-    createRequest(request) {
-        return createHTTPRequest(request);
+    trustProxy;
+    constructor(options = {}) {
+        this.trustProxy = options.trustProxy ?? false;
+    }
+    createRequest(request, options = {}) {
+        return createHTTPRequest(request, {
+            trustProxy: options.trustProxy ?? this.trustProxy,
+        });
     }
     createResponse(response) {
         return createHTTPResponse(response);
@@ -26,12 +29,16 @@ export class NodeHTTPAdapter {
 /* -------------------------------------------------------------------------- */
 /* Adapter Factory                                                             */
 /* -------------------------------------------------------------------------- */
-export function createHTTPAdapter() {
-    return new NodeHTTPAdapter();
+export function createHTTPAdapter(options = {}) {
+    return new NodeHTTPAdapter(options);
 }
 export class NodeRequestAdapter {
+    trustProxy;
+    constructor(options = {}) {
+        this.trustProxy = options.trustProxy ?? false;
+    }
     toHTTPRequest(request) {
-        return createHTTPRequest(request);
+        return createHTTPRequest(request, { trustProxy: this.trustProxy });
     }
 }
 export class NodeResponseAdapter {
@@ -76,15 +83,17 @@ export class DefaultHTTPMiddlewareAdapter {
 /* -------------------------------------------------------------------------- */
 /* Request Conversion Helpers                                                  */
 /* -------------------------------------------------------------------------- */
-export function adaptNodeRequest(request) {
-    return createHTTPRequest(request);
+export function adaptNodeRequest(request, options = {}) {
+    return createHTTPRequest(request, {
+        trustProxy: options.trustProxy ?? false,
+    });
 }
 export function adaptNodeResponse(response) {
     return createHTTPResponse(response);
 }
 export function adaptNodeContext(request, response, options = {}) {
     return createHTTPContext({
-        request: adaptNodeRequest(request),
+        request: adaptNodeRequest(request, { trustProxy: options.trustProxy }),
         response: adaptNodeResponse(response),
         state: options.state ?? {},
         signal: options.signal,

package/dist/httpAdapter/node/httpNode.adapter.d.ts

@@ -22,6 +22,7 @@ export declare class NodeHttpAdapter extends BaseHttpAdapter {
     private readonly keepAliveTimeout;
     private readonly connectionTimeout;
     private readonly trustProxy;
+    private readonly trustRequestId;
     private readonly maxConnections;
     private readonly connectionsCheckingInterval;
     private readonly shutdownGraceMs;
@@ -39,7 +40,7 @@ export declare class NodeHttpAdapter extends BaseHttpAdapter {
     constructor(options?: NodeAdapterOptions);
     get httpServer(): Server | undefined;
     get address(): NodeServerAddress | undefined;
-    createRequest(input: unknown): HttpRequestContext;
+    createRequest(input: unknown, signal?: AbortSignal): HttpRequestContext;
     createResponse(input?: unknown): HttpResponseContext;
     createWriter(response: unknown): HttpResponseWriter;
     handle(input: unknown): Promise<void>;

package/dist/httpAdapter/node/httpNode.adapter.js

@@ -30,6 +30,7 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
     keepAliveTimeout;
     connectionTimeout;
     trustProxy;
+    trustRequestId;
     maxConnections;
     connectionsCheckingInterval;
     shutdownGraceMs;
@@ -76,6 +77,7 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
                 Math.min(30_000, this.headersTimeout);
         this.shutdownGraceMs = options.shutdownGraceMs;
         this.trustProxy = options.trustProxy;
+        this.trustRequestId = options.trustRequestId ?? true;
         if (options.trustProxy !== undefined) {
             compileTrustProxy(options.trustProxy);
         }
@@ -109,13 +111,15 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
     /* ------------------------------------------------------------------------ */
     /* Request / Response                                                       */
     /* ------------------------------------------------------------------------ */
-    createRequest(input) {
+    createRequest(input, signal) {
         if (!isIncomingMessage(input)) {
             throw new TypeError("NodeHttpAdapter.createRequest expected an IncomingMessage.");
         }
         return createNodeRequestContext(input, {
             maxBodySize: this.maxBodySize,
             trustProxy: this.trustProxy,
+            trustRequestId: this.trustRequestId,
+            signal,
         });
     }
     createResponse(input) {
@@ -144,8 +148,19 @@ export class NodeHttpAdapter extends BaseHttpAdapter {
             return;
         }
         let context;
+        const disconnect = new AbortController();
+        /*
+         * `close` before the response finished means the client went away.
+         * Handlers see it as `request.signal` / the router's `ctx.signal`, and a
+         * streamed response body stops being pulled.
+         */
+        response.once("close", () => {
+            if (!response.writableFinished) {
+                disconnect.abort();
+            }
+        });
         try {
-            context = this.createRequest(request);
+            context = this.createRequest(request, disconnect.signal);
         }
         catch (error) {
             /*

package/dist/httpAdapter/node/httpNode.request.js

@@ -6,8 +6,9 @@
 import { HttpRequestContext, createRequestContext, } from "../../httpRequest/httpRequest.context.js";
 import { getClientIp, isTrustedProxy, } from "../../httpTrustProxy/httpTrustProxy.core.js";
 import { removePort, extractPort } from "./httpNode.server.js";
-import { parseQueryString } from "../../httpQuery/http.query.js";
+import { parseQueryString } from "../../httpQuery/index.js";
 import { findRequestTargetViolation } from "../../httpRequest/target/httpRequest.target.js";
+import { resolveIncomingRequestId } from "../../httpRequest/requestId/httpRequest.requestId.js";
 /* -------------------------------------------------------------------------- */
 /* Proxy Trust                                                                */
 /* -------------------------------------------------------------------------- */
@@ -159,7 +160,11 @@ export function createNodeRequestContext(request, options = {}) {
     const port = getNodeRequestPort(request, options);
     const remoteAddress = getNodeRemoteAddress(request, options);
     const query = parseNodeQuery(request);
+    const id = options.trustRequestId === false
+        ? undefined
+        : resolveIncomingRequestId(request.headers["x-request-id"]);
     return createRequestContext({
+        ...(id === undefined ? {} : { id }),
         method: request.method?.toUpperCase() ?? "GET",
         url,
         protocol,
@@ -168,6 +173,7 @@ export function createNodeRequestContext(request, options = {}) {
         headers,
         query,
         remoteAddress,
+        signal: options.signal,
     });
 }
 //# sourceMappingURL=httpNode.request.js.map

package/dist/httpAdapter/node/httpNode.type.d.ts

@@ -13,6 +13,11 @@ export interface NodeAdapterOptions extends HttpAdapterOptions, NodeAdapterSecur
     readonly server?: Server;
     readonly maxBodySize?: number;
     readonly trustProxy?: boolean | number | string | readonly string[];
+    /**
+     * Whether `request.id` reuses a well-formed incoming `x-request-id`
+     * header (default: `true`); see {@link NodeRequestOptions.trustRequestId}.
+     */
+    readonly trustRequestId?: boolean;
     readonly requestTimeout?: number;
     readonly headersTimeout?: number;
     readonly keepAliveTimeout?: number;
@@ -54,6 +59,15 @@ export interface NodeRequestOptions {
      * - string[]: Trust specific IP addresses
      */
     readonly trustProxy?: TrustProxy;
+    /** Signal carried by the context; aborted when the client disconnects. */
+    readonly signal?: AbortSignal;
+    /**
+     * Whether `request.id` reuses the client's `x-request-id` header
+     * (default: `true`). The header is used only when it is at most 128
+     * characters of `[A-Za-z0-9._:-]`; any other value is ignored and an id
+     * is generated. `false` always generates one.
+     */
+    readonly trustRequestId?: boolean;
 }
 export interface NodeServerAddress {
     readonly host: string;

package/dist/httpAgent/http.agent.d.ts

@@ -46,9 +46,28 @@ export interface AgentRegistryKey {
     readonly name?: string;
 }
 export declare function getOrCreateAgent(key: string | AgentRegistryKey, options?: HTTPAgentConfig | HTTPSAgentConfig): HTTPAgentInstance;
-export declare function getAgent(key: string | AgentRegistryKey): HTTPAgentInstance | undefined;
-export declare function hasAgent(key: string | AgentRegistryKey): boolean;
-export declare function removeAgent(key: string | AgentRegistryKey, destroy?: boolean): boolean;
+/**
+ * Looks up a registered agent.
+ *
+ * `options` must be the same TLS-relevant options `getOrCreateAgent` was
+ * given, because they are part of the key; omitting them looks up the agent
+ * created with no options.
+ */
+export declare function getAgent(key: string | AgentRegistryKey, options?: HTTPAgentConfig | HTTPSAgentConfig): HTTPAgentInstance | undefined;
+/**
+ * Whether an agent is registered for this key and TLS option set.
+ */
+export declare function hasAgent(key: string | AgentRegistryKey, options?: HTTPAgentConfig | HTTPSAgentConfig): boolean;
+/**
+ * Removes registered agents for a key.
+ *
+ * With `options` the single matching agent is removed; without them every
+ * agent registered for that host is removed, whatever TLS options it was
+ * created with, so a per-host teardown releases all of its sockets.
+ *
+ * @returns Whether anything was removed.
+ */
+export declare function removeAgent(key: string | AgentRegistryKey, destroy?: boolean, options?: HTTPAgentConfig | HTTPSAgentConfig): boolean;
 export declare function clearAgents(destroy?: boolean): void;
 export declare function getRegisteredAgentKeys(): string[];
 export declare function getDefaultHTTPAgent(): HTTPAgent;

package/dist/httpAgent/http.agent.js

@@ -113,7 +113,7 @@ export function getOrCreateAgent(key, options = {}) {
      * passing `rejectUnauthorized: false` would have disabled certificate
      * verification for a caller that had pinned a CA, with no way to detect it.
      */
-    const cacheKey = `${registryKey}|${tlsFingerprint(options)}`;
+    const cacheKey = agentCacheKey(registryKey, options);
     const existing = agentRegistry.get(cacheKey);
     if (existing) {
         return existing;
@@ -127,6 +127,18 @@ export function getOrCreateAgent(key, options = {}) {
     agentRegistry.set(cacheKey, agent);
     return agent;
 }
+/**
+ * Builds the registry key an agent is stored under.
+ *
+ * Every read and write goes through this one helper. `getOrCreateAgent` used
+ * to append the TLS fingerprint while `getAgent`, `hasAgent` and
+ * `removeAgent` looked up the bare registry key, so every lookup missed and
+ * the documented per-host teardown silently leaked the agent and its
+ * keep-alive sockets.
+ */
+function agentCacheKey(registryKey, options) {
+    return `${registryKey}|${tlsFingerprint(options)}`;
+}
 /**
  * Builds a stable fingerprint of the TLS-relevant fields of an agent config.
  */
@@ -156,23 +168,49 @@ function describeCredential(value) {
     }
     return "opaque";
 }
-export function getAgent(key) {
-    return agentRegistry.get(normalizeRegistryKey(key));
+/**
+ * Looks up a registered agent.
+ *
+ * `options` must be the same TLS-relevant options `getOrCreateAgent` was
+ * given, because they are part of the key; omitting them looks up the agent
+ * created with no options.
+ */
+export function getAgent(key, options = {}) {
+    return agentRegistry.get(agentCacheKey(normalizeRegistryKey(key), options));
 }
-export function hasAgent(key) {
-    return agentRegistry.has(normalizeRegistryKey(key));
+/**
+ * Whether an agent is registered for this key and TLS option set.
+ */
+export function hasAgent(key, options = {}) {
+    return agentRegistry.has(agentCacheKey(normalizeRegistryKey(key), options));
 }
-export function removeAgent(key, destroy = true) {
+/**
+ * Removes registered agents for a key.
+ *
+ * With `options` the single matching agent is removed; without them every
+ * agent registered for that host is removed, whatever TLS options it was
+ * created with, so a per-host teardown releases all of its sockets.
+ *
+ * @returns Whether anything was removed.
+ */
+export function removeAgent(key, destroy = true, options) {
     const registryKey = normalizeRegistryKey(key);
-    const agent = agentRegistry.get(registryKey);
-    if (!agent) {
-        return false;
-    }
-    agentRegistry.delete(registryKey);
-    if (destroy) {
-        agent.destroy();
+    const cacheKeys = options === undefined
+        ? Array.from(agentRegistry.keys()).filter((candidate) => candidate.startsWith(`${registryKey}|`))
+        : [agentCacheKey(registryKey, options)];
+    let removed = false;
+    for (const cacheKey of cacheKeys) {
+        const agent = agentRegistry.get(cacheKey);
+        if (!agent) {
+            continue;
+        }
+        agentRegistry.delete(cacheKey);
+        if (destroy) {
+            agent.destroy();
+        }
+        removed = true;
     }
-    return true;
+    return removed;
 }
 export function clearAgents(destroy = true) {
     if (destroy) {

package/dist/httpCacheControl/httpCacheControl.freshness.d.ts

@@ -12,11 +12,17 @@ import type { CacheFreshness } from "./core/httpCacheControl.type.js";
  * the origin marked must-revalidate-before-reuse must never be reported
  * fresh.
  *
+ * The response's current age follows RFC 9111 section 4.2.3: the `Age`
+ * header plus the time elapsed since the response's `Date`. Reading `Age`
+ * alone — as this used to — left every response without that header aged
+ * `0` forever, so `isFresh()` answered `true` for a response of any age.
+ *
  * @param responseHeaders - The cached response's headers.
  * @param responseDate - The response's `Date`, if already parsed.
+ * @param now - The current time, defaulting to `Date.now()`.
  * @returns The freshness calculation.
  */
-export declare function calculateFreshness(responseHeaders: Readonly<Record<string, string>>, responseDate?: Date): CacheFreshness;
+export declare function calculateFreshness(responseHeaders: Readonly<Record<string, string>>, responseDate?: Date, now?: Date): CacheFreshness;
 /**
  * Determines if a cached response is still fresh.
  */