@rapidrest/service-core 1.8.0 → 2.1.0

package/dist/types/auth/AuthMiddleware.d.ts

@@ -16,6 +16,12 @@ export declare class AuthMiddleware {
     /**
      * Performs authentication of the given request using one of the provided strategies.
      *
+     * Each strategy is tried in order until one succeeds. A strategy that throws doesn't stop the others from
+     * being tried, since several strategies can claim the same credential (e.g. `jwt` and `oauth_bearer` both
+     * read an `Authorization: Bearer` header). If no strategy succeeds and at least one threw, the first error
+     * thrown is rethrown, whether or not `required` is set, so callers can still tell a bad credential from a
+     * missing one.
+     *
      * @param strategies The list of strategy names to attempt authentication with.
      * @param req The request containing data to perform authenticate with.
      * @param res The response to use when writing back directly to the client.
@@ -25,7 +31,8 @@ export declare class AuthMiddleware {
     /**
      * Performs authentication of the given request using one of the provided strategies.
      *
-     * This is the synchronous version of `authenticate` that performs blocking based authentication.
+     * This is the synchronous version of `authenticate` that performs blocking based authentication. It follows
+     * the same rules for strategies that throw.
      *
      * @param strategies The list of strategy names to attempt authentication with.
      * @param req The request containing data to perform authenticate with.
@@ -33,18 +40,42 @@ export declare class AuthMiddleware {
      * @param required Set to `true` to if authentication is required to pass, otherwise set to `false`.
      */
     authenticateSync(strategies: string[], req: HttpRequest, res?: HttpResponse, required?: boolean): AuthResult | undefined;
+    /**
+     * Returns the registered strategy with the given name, throwing if there is none. A missing strategy is a
+     * configuration error, so it is never treated as an ordinary authentication failure.
+     */
+    private getStrategy;
+    /**
+     * Handles the case where no strategy authenticated the request: rethrows the first strategy error if there was
+     * one, throws if authentication is required, and otherwise returns `undefined`.
+     */
+    private authFailed;
+    /**
+     * Builds a copy of `req` that carries only the given token, as an `Authorization: Bearer` header. Used to run
+     * a WebSocket `LOGIN` message's token through the route's strategies. Query parameters and cookies from the
+     * upgrade request are removed, so a strategy can't authenticate from a credential other than the one supplied.
+     */
+    private createTokenRequest;
     /**
      * Returns a request handler function that will perform authentication of a websocket connection. Authentication
      * can be handled in two ways:
      *
-     * 1. Authorization header
+     * 1. Authorization header (or any other credential a strategy reads from the upgrade request)
      * 2. Negotiation via handshake
      *
-     * This middleware function primarily provides the implementation for item 2 above.
+     * Pre-upgrade auth (see `RouteUtils.registerRoute()`) can only run strategies synchronously. When it didn't
+     * authenticate the connection, this handler first runs the strategies asynchronously against the upgrade
+     * request, which covers async-only strategies such as `oauth_bearer`. If that doesn't authenticate either, it
+     * waits for a `LOGIN` message whose `data` token is also verified through `strategies`, sent to them as an
+     * `Authorization: Bearer` header.
+     *
+     * When `required` is `false`, a failed or missing credential never closes the connection; the handler proceeds
+     * anonymously.
      *
      * @param required Set to `true` to indicate that auth is required, otherwise `false`.
+     * @param strategies The strategy names to authenticate with. Defaults to `["jwt"]`, matching `RouteUtils`.
      */
-    authWebSocket(required: boolean): RequestHandler;
+    authWebSocket(required: boolean, strategies?: string[]): RequestHandler;
     /**
      * Registers the provided authentication strategy to be used
      * @param name The name of the authentication type to associate the given strategy with

package/dist/types/database/ConnectionManager.d.ts

@@ -1,6 +1,24 @@
 import type { DataSource } from "typeorm";
 import { MongoConnection } from "./MongoConnection.js";
 import type { RedisClientType } from "redis";
+/**
+ * Attaches `error`, `reconnecting` and `ready` listeners that log a redis client's connection problems.
+ *
+ * A node-redis client emits `error` whenever its socket fails (e.g. the server restarts or the network drops). An
+ * `EventEmitter` with no `error` listener throws on that event, which crashes the whole process. With a listener,
+ * the client's own reconnect strategy (exponential backoff, retried indefinitely by default) takes over and pending
+ * subscriptions are restored once it reconnects.
+ *
+ * To avoid flooding the log while a server is unreachable, the first error of an outage is logged as an error and
+ * the following ones as debug messages, until the client is `ready` again. Every client this library creates, and
+ * every `duplicate()` of one, must be passed through this function. Calling it again on the same client does nothing.
+ *
+ * @param client The redis client to attach the listeners to. Clients without an `on()` method are ignored.
+ * @param logger The logger to report errors to.
+ * @param name A name for the client, used in log messages.
+ * @returns The given client.
+ */
+export declare function attachRedisErrorHandler<T>(client: T, logger: any, name: string): T;
 /**
  * Provides database connection management.
  *

package/dist/types/database/DatabaseErrors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Determines whether `err` is a unique/primary key violation reported by any of the supported database drivers:
+ * - MongoDB: code `11000` (or `11001`);
+ * - PostgreSQL: SQLSTATE `23505`;
+ * - MySQL/MariaDB: `ER_DUP_ENTRY` (errno `1062`);
+ * - SQLite (`better-sqlite3`/`sqlite3`): `SQLITE_CONSTRAINT_UNIQUE`/`SQLITE_CONSTRAINT_PRIMARYKEY`, or a generic
+ * `SQLITE_CONSTRAINT` whose message is a `UNIQUE constraint failed` error.
+ *
+ * @param err The error to inspect.
+ */
+export declare function isDuplicateKeyError(err: any): boolean;
+/**
+ * Best-effort extraction of the field names involved in a duplicate key error, for telling a primary key/version
+ * clash apart from a clash on some other unique column. Returns `undefined` when the driver's error doesn't say.
+ * The special value `"PRIMARY"` is returned when the driver only names the primary key (MySQL, a PostgreSQL `PK_`
+ * constraint).
+ */
+export declare function duplicateKeyFields(err: any): string[] | undefined;
+/**
+ * Determines whether a duplicate key error is a clash on a record's identity - its `_id`/primary key or its
+ * `(uid, version)` pair - rather than on some other unique column.
+ *
+ * @param err The duplicate key error.
+ * @param fallback The answer to give when the driver's error doesn't name the fields involved.
+ */
+export declare function isIdentityDuplicate(err: any, fallback: boolean): boolean;

package/dist/types/database/MongoRepository.d.ts

@@ -1,4 +1,4 @@
-import type { Abortable, AggregateOptions, AggregationCursor, Collection, CountDocumentsOptions, Db, DeleteOptions, DeleteResult, DistinctOptions, Document, Filter, FindCursor, FindOneAndDeleteOptions, FindOptions, InsertOneOptions, ReplaceOptions, UpdateOptions, UpdateResult } from "mongodb";
+import type { Abortable, AggregateOptions, AggregationCursor, Collection, CountDocumentsOptions, Db, DeleteOptions, DeleteResult, DistinctOptions, Document, Filter, FindCursor, FindOneAndDeleteOptions, FindOneAndUpdateOptions, FindOptions, InsertOneOptions, ReplaceOptions, UpdateOptions, UpdateResult } from "mongodb";
 /**
  * Provides a lightweight repository for performing common operations against a single MongoDB collection using the
  * native `mongodb` driver. Instances of this class are obtained via `MongoConnection.getRepository`.
@@ -93,13 +93,32 @@ export declare class MongoRepository<T extends Document = any> {
      * a plain object) without preserving `_id`, where the default `_id`-only behavior would insert a *second*,
      * duplicate document instead of updating the existing one (see `ACLUtils.saveACL()`).
      *
+     * Pass `insertOnly: true` to always insert, even when `doc` carries an `_id`: the document is inserted with
+     * that `_id`, and the driver's duplicate-key error (code `11000`) is thrown if a document with it already
+     * exists. Use it for any create-style write whose `_id` may have come from untrusted input, where the default
+     * `_id`-present behavior would silently replace whichever existing document owns that `_id` (see
+     * `RepoUtils.create()`). Takes precedence over `mergeByUid`.
+     *
      * @param doc The document to save.
-     * @param options Driver options, plus optionally `mergeByUid` (see above).
+     * @param options Driver options, plus optionally `mergeByUid` or `insertOnly` (see above).
      * @returns The saved document.
      */
     save(doc: any, options?: (InsertOneOptions | ReplaceOptions) & {
         mergeByUid?: boolean;
+        insertOnly?: boolean;
     }): Promise<T>;
+    /**
+     * Atomically finds the first document matching the given filter, applies the given update operations to it and
+     * returns the resulting document (or `null` if none matched). By default the document is returned as it was
+     * *after* the update; pass `returnDocument: "before"` to get the original. A single round trip, so a caller that
+     * needs the exact document its own update produced isn't racing a separate follow-up read against a concurrent
+     * write to the same document (see `RepoUtils.update()`).
+     *
+     * @param filter The query filter to match documents against.
+     * @param update The update operations (e.g. `$set`) to apply.
+     * @param options - Optional settings for the command
+     */
+    findOneAndUpdate(filter: any, update: any, options?: FindOneAndUpdateOptions): Promise<T | null>;
     /**
      * Updates all documents matching the given filter with the provided update operations.
      *

package/dist/types/database/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./ConnectionKinds.js";
 export * from "./ConnectionManager.js";
+export * from "./DatabaseErrors.js";
 export * from "./MongoConnection.js";
 export * from "./MongoRepository.js";
 export * from "./MongoSchemaSync.js";

package/dist/types/decorators/PersistenceDecorators.d.ts

@@ -33,7 +33,38 @@ export interface ColumnOptions {
      * a complex/nested structure that has no direct SQL column equivalent (e.g. `"simple-json"`).
      */
     type?: string | Function;
+    /**
+     * The column's database default, used for rows inserted without a value and, importantly, to fill existing
+     * rows when `synchronize` adds a new `NOT NULL` column to a table that already has data (without a default that
+     * fails with a `NOT NULL constraint failed` error). A function returns a raw SQL expression, e.g.
+     * `() => "CURRENT_TIMESTAMP"`. (SQL only; on MongoDB use a property initializer instead.)
+     */
+    default?: string | number | boolean | null | (() => string);
+    /** The maximum length of a string column, e.g. `varchar(255)`. (SQL only) */
+    length?: number | string;
+    /**
+     * Set to `true` to enforce that every value of the column is unique. Equivalent to also applying `@Unique()` to
+     * the property, so it creates a unique index on both SQL and MongoDB.
+     */
+    unique?: boolean;
+    /** The total number of digits stored by a `decimal`/`numeric` column. (SQL only) */
+    precision?: number;
+    /** The number of digits after the decimal point stored by a `decimal`/`numeric` column. (SQL only) */
+    scale?: number;
+    /** Set to `true` to declare an array column. Only supported by PostgreSQL and CockroachDB. (SQL only) */
+    array?: boolean;
+    /** The allowed values of an `enum`/`simple-enum` column. (SQL only) */
+    enum?: (string | number)[] | object;
+    /** Set to `true` to declare a numeric column `UNSIGNED`. Only supported by MySQL/MariaDB. (SQL only) */
+    unsigned?: boolean;
+    /** A comment stored with the column definition, where the database supports it. (SQL only) */
+    comment?: string;
 }
+/**
+ * The `ColumnOptions` keys that are forwarded to TypeORM verbatim when set. `unique` is not among them: it is
+ * registered as a unique index instead (see `Column`), so both backends enforce it the same way.
+ */
+export declare const FORWARDED_SQL_COLUMN_OPTIONS: readonly ["name", "nullable", "default", "length", "precision", "scale", "array", "enum", "unsigned", "comment"];
 /**
  * The set of options to use when declaring a persistent class type via the `@Entity` decorator.
  */

package/dist/types/decorators/RouteDecorators.d.ts

@@ -146,8 +146,10 @@ export interface RateLimitOptions extends RateLimitConfig {
  * endpoints in the class will have rate limiting applied.
  *
  * Optionally pass in options to control the identifier of the rate limit. Set `options.id` to set an explicit identifier.
- * By default, the method and path of the request (without the query portion) is used as the identifier. Set
- * the `options.perUser` option to `true` to have the limit scoped to each user individually.
+ * By default, the method and the percent-decoded, normalized path of the request (without the query portion) is used
+ * as the identifier. Set the `options.perUser` option to `true` to have the limit scoped to each user individually;
+ * anonymous callers are then scoped by client IP address (see `trusted_proxies`). Calling `@RateLimit()` with no
+ * options enables `perUser`. See `RouteUtils.checkRateLimiter()`.
  */
 export declare function RateLimit(options?: RateLimitOptions): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
 /**

package/dist/types/http/bun/BunRouter.d.ts

@@ -1,4 +1,4 @@
-import type { IHttpRouter, RequestHandler } from "../types.js";
+import { type IHttpRouter, type RequestHandler, type WebSocketOptions } from "../types.js";
 import { type WsUpgradeAuth } from "../MiddlewareChain.js";
 /**
  * Bun-native HTTP/WebSocket router built on `Bun.serve()`. Exposes the same public surface as the
@@ -21,6 +21,8 @@ export declare class BunRouter implements IHttpRouter {
      * global CORS middleware so a real app-defined `OPTIONS` handler gets a chance to run). */
     private readonly explicitOptionsPaths;
     private readonly maxBodySize;
+    /** The HTTP requests currently being handled. */
+    private inFlight;
     private readonly sslConfig;
     private _bunServer;
     /** The port the server is currently listening on (set after a successful `listen()` call). */
@@ -59,8 +61,18 @@ export declare class BunRouter implements IHttpRouter {
      * is aborted. If it returns `{ user, ... }`, those credentials are attached to the request so
      * downstream middleware sees an authenticated user. If it returns `{}`, auth falls through to
      * the post-upgrade message-based LOGIN flow.
+     *
+     * `wsOptions` uses the uWS option names (`maxPayloadLength`, `idleTimeout`, `maxBackpressure`) over
+     * `DEFAULT_WS_OPTIONS`. `Bun.serve()` only accepts one WebSocket configuration for the whole server, so
+     * `maxPayloadLength` is additionally enforced per route (a larger message closes the socket with 1009), while
+     * `idleTimeout` and `maxBackpressure` are applied server-wide using the largest value any route registered.
+     */
+    ws(routePath: string, handlers: RequestHandler[], wsOptions?: WebSocketOptions, upgradeAuth?: WsUpgradeAuth): this;
+    /**
+     * Builds the server-wide `Bun.serve()` WebSocket limits from every registered WebSocket route: the largest value
+     * of each option, or `DEFAULT_WS_OPTIONS` when no route is registered.
      */
-    ws(routePath: string, handlers: RequestHandler[], _wsOptions?: any, upgradeAuth?: WsUpgradeAuth): this;
+    private buildWebSocketLimits;
     /**
      * Matches a request against the route table. Exact-length static/param routes always outrank
      * wildcard-suffixed routes, matching uWS's `best ?? wildcard` fallback behavior. Among wildcard
@@ -84,5 +96,14 @@ export declare class BunRouter implements IHttpRouter {
     listen(host: string, port: number): Promise<void>;
     /** Stops the server, closing the listen socket. */
     close(): void;
+    /** The number of HTTP requests currently being handled. */
+    get inFlightRequests(): number;
+    /**
+     * Stops accepting new connections, waits up to `timeoutMs` for in-flight HTTP requests to finish, then closes
+     * every remaining connection (keep-alive and WebSocket connections included).
+     *
+     * @param timeoutMs The maximum time to wait for in-flight requests, in milliseconds.
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
     [key: string]: any;
 }

package/dist/types/http/index.d.ts

@@ -1,4 +1,5 @@
-export type { ErrorHandler, HttpRequest, HttpResponse, IHttpRouter, NextFunction, RequestHandler } from "./types.js";
+export type { ErrorHandler, HttpRequest, HttpResponse, IHttpRouter, NextFunction, RequestHandler, WebSocketOptions, } from "./types.js";
+export { DEFAULT_WS_OPTIONS } from "./types.js";
 export { isBunRuntime } from "./RuntimeDetect.js";
 export type { IWebSocketShim } from "./IWebSocketShim.js";
 export { extractParamNames, makeWsStubResponse, runChain } from "./MiddlewareChain.js";

package/dist/types/http/session/sessionMiddleware.d.ts

@@ -2,9 +2,19 @@ import type { RequestHandler } from "../types.js";
 import type { SessionManager } from "./SessionManager.js";
 /**
  * Builds a global, framework-agnostic session middleware backed by the given `SessionManager`.
- * Lazily loads-or-creates `req.session` and persists any mutations back to the store once the
- * response finishes. Cheap for requests that never touch sessions: no store round-trip unless a
- * valid session cookie was actually sent, and no `Set-Cookie`/store write for sessions that end up
- * empty.
+ *
+ * `req.session` is always an object, and `req.sessionIsNew` tells whether it is backed by a stored session:
+ *
+ * - When the request carries a validly signed session cookie whose session still exists, `req.session` holds that
+ * session's data (`req.sessionIsNew === false`) and any non-empty data is saved back once the response finishes.
+ * - Otherwise `req.session` starts out as an empty, unsaved object (`req.sessionIsNew === true`). Nothing is stored
+ * and no cookie is sent unless a handler explicitly asks for a session by writing to it (setting, defining or
+ * deleting a property, or assigning a new object to `req.session`). The first such write issues a fresh session ID
+ * via `Set-Cookie`, and the data is saved once the response finishes. A write after the response headers were sent
+ * can no longer deliver the cookie, so it isn't saved.
+ *
+ * This keeps clients that never send cookies (e.g. API clients authenticating with a bearer token) from creating a
+ * new stored session on every request. Middleware that only records bookkeeping about the caller (last access time,
+ * IP address, ...) should skip `req.session` when `req.sessionIsNew` is `true`.
  */
 export declare function createSessionMiddleware(mgr: SessionManager): RequestHandler;

package/dist/types/http/types.d.ts

@@ -20,6 +20,12 @@ export interface HttpRequest {
      * session middleware is registered (i.e. the `session` config block is absent).
      */
     session?: Record<string, any>;
+    /**
+     * Set by the session middleware. `true` when `session` is not backed by a stored session yet (the request carried
+     * no valid session cookie): nothing is stored and no cookie is sent unless a handler writes to `session`.
+     * Bookkeeping-only writes (last access time, IP address, ...) should be skipped while this is `true`.
+     */
+    sessionIsNew?: boolean;
     /** Minimal socket interface; populated with remote address for IP extraction. */
     socket: {
         remoteAddress?: string;
@@ -30,6 +36,13 @@ export interface HttpRequest {
     authPayload?: any;
     /** Raw JWT token string, set by JWT auth middleware. */
     authToken?: string;
+    /**
+     * The registered route pattern that matched this request (e.g. `/items/:id`), set by the router before any
+     * middleware runs. `undefined` when no application route matched, i.e. the request is handled by the router's
+     * own not-found or CORS preflight fallback. Unlike `path`, the set of possible values is bounded by the
+     * application's routes, so it is safe to use as a metrics label.
+     */
+    routePattern?: string;
     /** Allow arbitrary per-request properties (e.g. req.websocket, req.wsHandled). */
     [key: string]: any;
 }
@@ -92,8 +105,35 @@ export interface IHttpRouter {
     hasExplicitOptionsRoute(path: string): boolean;
     ws(path: string, handlers: RequestHandler[], wsOptions?: any, upgradeAuth?: any): this;
     listen(host: string, port: number): Promise<void>;
+    /** Stops accepting new connections. Connections that are already open (including keep-alive and WebSocket
+     * connections) are left alone. */
     close(): void;
+    /**
+     * Gracefully shuts the server down: stops accepting new connections, waits up to `timeoutMs` milliseconds for
+     * HTTP requests that are still being handled to finish, then force-closes every remaining connection
+     * (keep-alive and WebSocket connections included). Optional, so custom routers without it keep working;
+     * `Server.stop()` falls back to `close()` for those.
+     */
+    shutdown?(timeoutMs: number): Promise<void>;
     readonly isListening: boolean;
     listenPort: number;
     [key: string]: any;
 }
+/**
+ * WebSocket options shared by every router implementation. Names follow uWebSockets.js' `WebSocketBehavior`.
+ */
+export interface WebSocketOptions {
+    /** Maximum size of a single incoming message, in bytes. A larger message closes the connection. */
+    maxPayloadLength?: number;
+    /** Seconds without any received data after which the connection is closed. `0` disables the timeout. */
+    idleTimeout?: number;
+    /** Maximum number of bytes that may be queued for sending before further messages are dropped. */
+    maxBackpressure?: number;
+    [key: string]: any;
+}
+/**
+ * The WebSocket defaults used by both the uWS and Bun routers when a route doesn't override them. These match
+ * uWebSockets.js' own defaults, so a route behaves the same on both runtimes (Bun's own defaults are far larger,
+ * e.g. a 16 MiB payload limit).
+ */
+export declare const DEFAULT_WS_OPTIONS: Readonly<Required<Pick<WebSocketOptions, "maxPayloadLength" | "idleTimeout" | "maxBackpressure">>>;

package/dist/types/http/uWS/Adapters.d.ts

@@ -2,7 +2,16 @@ import type { HttpRequest, HttpResponse } from "../types.js";
 import type { HttpRequest as UWSHttpRequest, HttpResponse as UWSHttpResponse } from "uWebSockets.js";
 /** Parses a `cookie` header string into a key/value map. */
 export declare function parseCookies(cookieHeader: string): Record<string, string>;
-/** Parses a URL query string (without leading `?`) into a key/value map. */
+/**
+ * Parses a URL query string (without leading `?`) into a key/value map. A key given more than once becomes an array
+ * of its values.
+ *
+ * The result is a plain object, so spreading it and calling `Object.prototype` methods through it behave as usual.
+ * Only own properties are considered when detecting a repeated key, so a key like `hasOwnProperty` or `constructor`
+ * is stored as a normal value instead of being merged with the inherited function. `__proto__` keys are dropped:
+ * assigning one would replace the object's prototype, and even as an own property it would do so again when the
+ * object is later copied with `Object.assign()` or a deep merge.
+ */
 export declare function parseQueryString(qs: string): Record<string, string | string[]>;
 /**
  * Parses a raw request body Buffer according to its content-type header. Shared by both the

package/dist/types/http/uWS/Router.d.ts

@@ -1,5 +1,5 @@
 import uWS from "uWebSockets.js";
-import type { IHttpRouter, RequestHandler } from "../types.js";
+import { type IHttpRouter, type RequestHandler, type WebSocketOptions } from "../types.js";
 import { type WsUpgradeAuth } from "../MiddlewareChain.js";
 export { runChain, extractParamNames } from "../MiddlewareChain.js";
 export type { WsUpgradeAuth, WsUpgradeAuthResult } from "../MiddlewareChain.js";
@@ -40,6 +40,8 @@ export declare class HttpRouter implements IHttpRouter {
     private readonly explicitOptionsPaths;
     /** Maximum accepted request body size, in bytes. */
     private readonly maxBodySize;
+    /** The HTTP requests currently being handled. */
+    private readonly inFlight;
     constructor(uwsApp: uWS.TemplatedApp, maxBodySize?: number);
     /** Returns `true` if the server is currently listening. */
     get isListening(): boolean;
@@ -51,6 +53,8 @@ export declare class HttpRouter implements IHttpRouter {
      * everything added after is "post-route" (error handlers, metrics, etc.).
      */
     private capturePreRouteCount;
+    /** Builds the uWS handler for a route registered at `routePattern` (`undefined` for the router's own fallbacks). */
+    private makeHandler;
     get(routePath: string, ...handlers: RequestHandler[]): this;
     post(routePath: string, ...handlers: RequestHandler[]): this;
     put(routePath: string, ...handlers: RequestHandler[]): this;
@@ -77,7 +81,7 @@ export declare class HttpRouter implements IHttpRouter {
      *
      * Both `path` and `path + "/"` are registered to avoid trailing-slash mismatch.
      */
-    ws(routePath: string, handlers: RequestHandler[], wsOptions?: Partial<uWS.WebSocketBehavior<any>>, upgradeAuth?: WsUpgradeAuth): this;
+    ws(routePath: string, handlers: RequestHandler[], wsOptions?: Partial<uWS.WebSocketBehavior<any>> | WebSocketOptions, upgradeAuth?: WsUpgradeAuth): this;
     /**
      * Starts listening on the given host and port.
      * Resolves when the server is ready; rejects if the port cannot be bound.
@@ -85,5 +89,14 @@ export declare class HttpRouter implements IHttpRouter {
     listen(host: string, port: number): Promise<void>;
     /** Closes the listen socket, stopping the server from accepting new connections. */
     close(): void;
+    /** The number of HTTP requests currently being handled. */
+    get inFlightRequests(): number;
+    /**
+     * Stops accepting new connections, waits up to `timeoutMs` for in-flight HTTP requests to finish, then closes
+     * every remaining connection (keep-alive and WebSocket connections included).
+     *
+     * @param timeoutMs The maximum time to wait for in-flight requests, in milliseconds.
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
     [key: string]: any;
 }