@bymax-one/nest-core 1.6.6 → 1.6.8

package/dist/health/index.d.cts

@@ -49,8 +49,9 @@ interface HealthIndicatorResult {
     /** Whether the checked dependency is reachable and healthy. */
     status: 'up' | 'down';
     /**
-     * Optional diagnostic detail. Must never include secrets, connection
-     * strings, credentials, or a raw internal error object: only safe,
+     * Optional diagnostic detail, served in the readiness response only when
+     * `health.exposeIndicatorErrors` is on. Must never include secrets,
+     * connection strings, credentials, or a raw internal error object: only safe,
      * human-readable fields belong here.
      */
     details?: Record<string, unknown>;
@@ -66,11 +67,13 @@ interface IHealthIndicator {
     /**
      * Perform the check.
      *
+     * @param signal - Aborted when the aggregator stops waiting for this check. An indicator that
+     *   can cancel its query should pass it on; one that cannot may ignore it.
      * @returns The indicator's outcome.
      * @throws Any error; a rejection is converted to a `down` entry by the
      *   aggregator and never propagates to the caller.
      */
-    check(): Promise<HealthIndicatorResult>;
+    check(signal?: AbortSignal): Promise<HealthIndicatorResult>;
 }
 /**
  * One entry in a {@link HealthResponse.checks} array: an indicator's result,

package/dist/health/index.d.ts

@@ -49,8 +49,9 @@ interface HealthIndicatorResult {
     /** Whether the checked dependency is reachable and healthy. */
     status: 'up' | 'down';
     /**
-     * Optional diagnostic detail. Must never include secrets, connection
-     * strings, credentials, or a raw internal error object: only safe,
+     * Optional diagnostic detail, served in the readiness response only when
+     * `health.exposeIndicatorErrors` is on. Must never include secrets,
+     * connection strings, credentials, or a raw internal error object: only safe,
      * human-readable fields belong here.
      */
     details?: Record<string, unknown>;
@@ -66,11 +67,13 @@ interface IHealthIndicator {
     /**
      * Perform the check.
      *
+     * @param signal - Aborted when the aggregator stops waiting for this check. An indicator that
+     *   can cancel its query should pass it on; one that cannot may ignore it.
      * @returns The indicator's outcome.
      * @throws Any error; a rejection is converted to a `down` entry by the
      *   aggregator and never propagates to the caller.
      */
-    check(): Promise<HealthIndicatorResult>;
+    check(signal?: AbortSignal): Promise<HealthIndicatorResult>;
 }
 /**
  * One entry in a {@link HealthResponse.checks} array: an indicator's result,

package/dist/http/index.cjs

@@ -0,0 +1,73 @@
+'use strict';
+
+// src/optional-peer.ts
+function isMissingModuleError(cause) {
+  const code = cause.code;
+  return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+
+// src/http/http.loader.ts
+var MISSING_PEER_MESSAGE = "applyHttpFloors needs the optional peer helmet, which is not installed. Run: pnpm add helmet";
+async function loadHelmet() {
+  try {
+    const loaded = await import('helmet');
+    return loaded.default;
+  } catch (cause) {
+    if (isMissingModuleError(cause)) {
+      throw new Error(MISSING_PEER_MESSAGE, { cause });
+    }
+    throw cause;
+  }
+}
+
+// src/http/http-floors.ts
+var DEFAULT_HEADERS_TIMEOUT_MS = 15e3;
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+var DEFAULT_CONNECTIONS_CHECKING_INTERVAL_MS = 1e3;
+function assertPositiveInteger(name, value) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`${name} must be a positive integer, received ${String(value)}`);
+  }
+}
+function assertBootstrapState(express) {
+  if (express.getHttpAdapter().getType?.() !== "express") {
+    throw new Error("applyHttpFloors supports the Express adapter only");
+  }
+  const server = express.getHttpServer();
+  if (server.listening) {
+    throw new Error("applyHttpFloors must run before listen(): the server is already listening");
+  }
+  if (express.isInitialized === true) {
+    throw new Error(
+      "applyHttpFloors must run before app.init(): the application is already initialised"
+    );
+  }
+  return server;
+}
+async function applyHttpFloors(app, options = {}) {
+  const headersTimeoutMs = options.headersTimeoutMs ?? DEFAULT_HEADERS_TIMEOUT_MS;
+  const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  assertPositiveInteger("headersTimeoutMs", headersTimeoutMs);
+  assertPositiveInteger("requestTimeoutMs", requestTimeoutMs);
+  if (headersTimeoutMs > requestTimeoutMs) {
+    throw new Error(
+      `headersTimeoutMs (${headersTimeoutMs}) must not exceed requestTimeoutMs (${requestTimeoutMs})`
+    );
+  }
+  const checkingIntervalMs = options.connectionsCheckingIntervalMs ?? Math.min(DEFAULT_CONNECTIONS_CHECKING_INTERVAL_MS, headersTimeoutMs);
+  assertPositiveInteger("connectionsCheckingIntervalMs", checkingIntervalMs);
+  const express = app;
+  const server = assertBootstrapState(express);
+  const given = options.helmet ?? {};
+  if (given !== false) {
+    const helmet = await loadHelmet();
+    express.use(helmet("hsts" in given ? given : { strictTransportSecurity: false, ...given }));
+  }
+  express.useBodyParser("json", { inflate: false });
+  express.useBodyParser("urlencoded", { inflate: false, extended: true });
+  server.headersTimeout = headersTimeoutMs;
+  server.requestTimeout = requestTimeoutMs;
+  server.connectionsCheckingInterval = checkingIntervalMs;
+}
+
+exports.applyHttpFloors = applyHttpFloors;

package/dist/http/index.d.cts

@@ -0,0 +1,59 @@
+import { INestApplication } from '@nestjs/common';
+
+/**
+ * @fileoverview `applyHttpFloors`, the HTTP-level protections every backend wants and none should
+ * tune per deployment: security headers without HSTS, compressed request bodies refused, and
+ * timeouts that bound how long a client may hold a socket, enforced to within a second.
+ *
+ * Order is part of the contract. Call it before `app.init()`, right after the access log is installed
+ * (`applyAccessLog` from `@bymax-one/nest-logger`) and before anything that reads the request:
+ * helmet is mounted first so even a request the body parsers refuse carries the headers, and the
+ * parsers are registered here so Nest's defaults (which accept gzip) are not. Cookie parsing, the
+ * trusted-proxy setting and OpenAPI stay with the caller and go after this call.
+ *
+ * Express only. `helmet` is an optional peer, loaded when this runs.
+ * @layer Bootstrap
+ */
+
+/** The `helmet()` options object; any option `helmet` accepts. */
+type HttpFloorsHelmetOptions = Readonly<Record<string, unknown>>;
+/** Options for {@link applyHttpFloors}. */
+interface HttpFloorsOptions {
+    /**
+     * Options handed to `helmet()`, over `{ strictTransportSecurity: false }` (TLS is normally
+     * terminated in front of the application, which owns HSTS). A browser-serving backend tunes
+     * `contentSecurityPolicy` here. `false` leaves helmet out entirely.
+     */
+    readonly helmet?: HttpFloorsHelmetOptions | false;
+    /**
+     * Longest a client may take to send its complete header block before the socket is closed.
+     * Positive integer, at most `requestTimeoutMs`. Default: `15000`.
+     */
+    readonly headersTimeoutMs?: number;
+    /**
+     * Longest a single request may take, headers and body together. Positive integer.
+     * Default: `30000`.
+     */
+    readonly requestTimeoutMs?: number;
+    /**
+     * How often the server sweeps its open connections for expired timeouts. Positive integer.
+     * Default: `1000`, or `headersTimeoutMs` when that is shorter. Node enforces both timeouts from
+     * this sweep rather than from a timer per connection, and its own default is `30000`, so a
+     * `headersTimeoutMs` of 15 s would cut anywhere between 15 and 45 s. The sweep walks every open
+     * connection each time, so a server holding very many sockets may set it higher, at the cost
+     * of cutting up to that long after the timeout.
+     */
+    readonly connectionsCheckingIntervalMs?: number;
+}
+/**
+ * Apply the HTTP floors to an Express application. Call it before `app.init()` or `listen`.
+ *
+ * @param app - The Nest application, created on the Express adapter.
+ * @param options - Overrides for the helmet options and the two timeouts.
+ * @throws Error When a timeout is unusable, the application is not on Express, or `helmet` is
+ * needed and not installed. Nothing is applied in those cases.
+ */
+declare function applyHttpFloors(app: INestApplication, options?: HttpFloorsOptions): Promise<void>;
+
+export { applyHttpFloors };
+export type { HttpFloorsHelmetOptions, HttpFloorsOptions };

package/dist/http/index.d.ts

@@ -0,0 +1,59 @@
+import { INestApplication } from '@nestjs/common';
+
+/**
+ * @fileoverview `applyHttpFloors`, the HTTP-level protections every backend wants and none should
+ * tune per deployment: security headers without HSTS, compressed request bodies refused, and
+ * timeouts that bound how long a client may hold a socket, enforced to within a second.
+ *
+ * Order is part of the contract. Call it before `app.init()`, right after the access log is installed
+ * (`applyAccessLog` from `@bymax-one/nest-logger`) and before anything that reads the request:
+ * helmet is mounted first so even a request the body parsers refuse carries the headers, and the
+ * parsers are registered here so Nest's defaults (which accept gzip) are not. Cookie parsing, the
+ * trusted-proxy setting and OpenAPI stay with the caller and go after this call.
+ *
+ * Express only. `helmet` is an optional peer, loaded when this runs.
+ * @layer Bootstrap
+ */
+
+/** The `helmet()` options object; any option `helmet` accepts. */
+type HttpFloorsHelmetOptions = Readonly<Record<string, unknown>>;
+/** Options for {@link applyHttpFloors}. */
+interface HttpFloorsOptions {
+    /**
+     * Options handed to `helmet()`, over `{ strictTransportSecurity: false }` (TLS is normally
+     * terminated in front of the application, which owns HSTS). A browser-serving backend tunes
+     * `contentSecurityPolicy` here. `false` leaves helmet out entirely.
+     */
+    readonly helmet?: HttpFloorsHelmetOptions | false;
+    /**
+     * Longest a client may take to send its complete header block before the socket is closed.
+     * Positive integer, at most `requestTimeoutMs`. Default: `15000`.
+     */
+    readonly headersTimeoutMs?: number;
+    /**
+     * Longest a single request may take, headers and body together. Positive integer.
+     * Default: `30000`.
+     */
+    readonly requestTimeoutMs?: number;
+    /**
+     * How often the server sweeps its open connections for expired timeouts. Positive integer.
+     * Default: `1000`, or `headersTimeoutMs` when that is shorter. Node enforces both timeouts from
+     * this sweep rather than from a timer per connection, and its own default is `30000`, so a
+     * `headersTimeoutMs` of 15 s would cut anywhere between 15 and 45 s. The sweep walks every open
+     * connection each time, so a server holding very many sockets may set it higher, at the cost
+     * of cutting up to that long after the timeout.
+     */
+    readonly connectionsCheckingIntervalMs?: number;
+}
+/**
+ * Apply the HTTP floors to an Express application. Call it before `app.init()` or `listen`.
+ *
+ * @param app - The Nest application, created on the Express adapter.
+ * @param options - Overrides for the helmet options and the two timeouts.
+ * @throws Error When a timeout is unusable, the application is not on Express, or `helmet` is
+ * needed and not installed. Nothing is applied in those cases.
+ */
+declare function applyHttpFloors(app: INestApplication, options?: HttpFloorsOptions): Promise<void>;
+
+export { applyHttpFloors };
+export type { HttpFloorsHelmetOptions, HttpFloorsOptions };

package/dist/http/index.mjs

@@ -0,0 +1,71 @@
+// src/optional-peer.ts
+function isMissingModuleError(cause) {
+  const code = cause.code;
+  return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+
+// src/http/http.loader.ts
+var MISSING_PEER_MESSAGE = "applyHttpFloors needs the optional peer helmet, which is not installed. Run: pnpm add helmet";
+async function loadHelmet() {
+  try {
+    const loaded = await import('helmet');
+    return loaded.default;
+  } catch (cause) {
+    if (isMissingModuleError(cause)) {
+      throw new Error(MISSING_PEER_MESSAGE, { cause });
+    }
+    throw cause;
+  }
+}
+
+// src/http/http-floors.ts
+var DEFAULT_HEADERS_TIMEOUT_MS = 15e3;
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+var DEFAULT_CONNECTIONS_CHECKING_INTERVAL_MS = 1e3;
+function assertPositiveInteger(name, value) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`${name} must be a positive integer, received ${String(value)}`);
+  }
+}
+function assertBootstrapState(express) {
+  if (express.getHttpAdapter().getType?.() !== "express") {
+    throw new Error("applyHttpFloors supports the Express adapter only");
+  }
+  const server = express.getHttpServer();
+  if (server.listening) {
+    throw new Error("applyHttpFloors must run before listen(): the server is already listening");
+  }
+  if (express.isInitialized === true) {
+    throw new Error(
+      "applyHttpFloors must run before app.init(): the application is already initialised"
+    );
+  }
+  return server;
+}
+async function applyHttpFloors(app, options = {}) {
+  const headersTimeoutMs = options.headersTimeoutMs ?? DEFAULT_HEADERS_TIMEOUT_MS;
+  const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  assertPositiveInteger("headersTimeoutMs", headersTimeoutMs);
+  assertPositiveInteger("requestTimeoutMs", requestTimeoutMs);
+  if (headersTimeoutMs > requestTimeoutMs) {
+    throw new Error(
+      `headersTimeoutMs (${headersTimeoutMs}) must not exceed requestTimeoutMs (${requestTimeoutMs})`
+    );
+  }
+  const checkingIntervalMs = options.connectionsCheckingIntervalMs ?? Math.min(DEFAULT_CONNECTIONS_CHECKING_INTERVAL_MS, headersTimeoutMs);
+  assertPositiveInteger("connectionsCheckingIntervalMs", checkingIntervalMs);
+  const express = app;
+  const server = assertBootstrapState(express);
+  const given = options.helmet ?? {};
+  if (given !== false) {
+    const helmet = await loadHelmet();
+    express.use(helmet("hsts" in given ? given : { strictTransportSecurity: false, ...given }));
+  }
+  express.useBodyParser("json", { inflate: false });
+  express.useBodyParser("urlencoded", { inflate: false, extended: true });
+  server.headersTimeout = headersTimeoutMs;
+  server.requestTimeout = requestTimeoutMs;
+  server.connectionsCheckingInterval = checkingIntervalMs;
+}
+
+export { applyHttpFloors };