@jaredwray/mockhttp 2.1.0 → 3.0.1

package/dist/index.d.mts

@@ -1,6 +1,100 @@
 import { RateLimitPluginOptions } from "@fastify/rate-limit";
 import { FastifyInstance, FastifyRequest } from "fastify";
 import { Hookified, HookifiedOptions } from "hookified";
+import Keyv from "keyv";
+//#region src/bin-store-diagnostics.d.ts
+type BinStoreErrorInfo = {
+  name: string;
+  message: string;
+  code: string | number | null;
+};
+type BinHealth = {
+  status: "ok";
+  bins: {
+    store: "mongo" | "memory";
+    connected: true;
+    latencyMs: number;
+    uriPresent: boolean;
+    uri?: UriDiagnostics;
+  };
+} | {
+  status: "error";
+  bins: {
+    store: "mongo" | "memory";
+    connected: false;
+    uriPresent: boolean;
+    uri?: UriDiagnostics;
+    error: BinStoreErrorInfo;
+  };
+};
+/** Redacted URI facts for `GET /healthz`. No password and no full URI. */
+type UriDiagnostics = {
+  length: number;
+  leadingWhitespace: boolean;
+  trailingWhitespace: boolean;
+  newline: boolean;
+  wrappedQuotes: boolean;
+  atCount: number;
+  passwordReserved: string[];
+  passwordHasPercent: boolean;
+};
+//#endregion
+//#region src/certificate.d.ts
+type CertificateOptions = {
+  /**
+   * Common Name for the certificate subject. Defaults to 'localhost'.
+   */
+  commonName?: string;
+  /**
+   * Subject Alternative Names. Defaults to [dns:localhost, ip:127.0.0.1, ip:::1].
+   */
+  altNames?: Array<{
+    type: "dns";
+    value: string;
+  } | {
+    type: "ip";
+    value: string;
+  }>;
+  /**
+   * Number of days the certificate is valid. Defaults to 365.
+   */
+  validityDays?: number;
+  /**
+   * RSA key size in bits. Defaults to 2048.
+   */
+  keySize?: number;
+};
+type CertificateResult = {
+  /**
+   * PEM-encoded X.509 certificate.
+   */
+  cert: string;
+  /**
+   * PEM-encoded PKCS#8 private key.
+   */
+  key: string;
+};
+type CertificateFileOptions = CertificateOptions & {
+  /**
+   * File path to write the certificate PEM.
+   */
+  certPath: string;
+  /**
+   * File path to write the private key PEM.
+   */
+  keyPath: string;
+};
+/**
+ * Generate a self-signed certificate using only Node.js built-in crypto.
+ * Returns PEM-encoded certificate and private key strings.
+ */
+export declare function generateCertificate(options?: CertificateOptions): CertificateResult;
+/**
+ * Generate a self-signed certificate and write PEM files to disk.
+ * Returns the same CertificateResult as generateCertificate().
+ */
+export declare function generateCertificateFiles(options: CertificateFileOptions): Promise<CertificateResult>;
+//#endregion
 //#region src/bin-store.d.ts
 /**
  * A request captured by a bin, including method, headers, body and metadata.
@@ -48,179 +142,110 @@ type Bin = {
   /** Number of requests currently stored in the bin */
   requestCount: number;
 };
+//#endregion
+//#region src/mock-http-bins.d.ts
 /**
- * Storage backend for bins and their captured requests. The default
- * implementation is in-memory; alternative backends (Redis, SQLite, etc.) can
- * implement this interface without changes to the rest of the codebase.
- */
-interface BinStore {
-  /** Create a new bin record. */
-  createBin(bin: Bin): void;
-  /** Look up a bin by id. */
-  getBin(id: string): Bin | undefined;
-  /** Return all bins. */
-  listBins(): Bin[];
-  /** Remove a bin and all its captured requests. Returns true if removed. */
-  deleteBin(id: string): boolean;
-  /**
-   * Append a captured request to a bin, dropping the oldest if the bin has
-   * already reached `max` requests (FIFO).
-   */
-  addRequest(binId: string, req: CapturedRequest, max: number): void;
-  /** List captured requests for a bin (newest first). */
-  getRequests(binId: string): CapturedRequest[];
-  /** Look up a single captured request by id. */
-  getRequest(binId: string, reqId: string): CapturedRequest | undefined;
-  /** Clear all captured requests in a bin (the bin itself is preserved). */
-  clearRequests(binId: string): void;
-  /**
-   * Remove bins whose `expiresAt` is in the past relative to `now`.
-   * Returns the ids of bins that were removed.
-   */
-  cleanupExpired(now: number): string[];
-}
-/**
- * In-memory implementation of {@link BinStore} backed by two Maps. State is
- * lost when the process exits.
+ * One bin and its captured requests, stored as a single Keyv value.
  */
-export declare class InMemoryBinStore implements BinStore {
-  private readonly _bins;
-  private readonly _requests;
-  createBin(bin: Bin): void;
-  getBin(id: string): Bin | undefined;
-  listBins(): Bin[];
-  deleteBin(id: string): boolean;
-  addRequest(binId: string, req: CapturedRequest, max: number): void;
-  getRequests(binId: string): CapturedRequest[];
-  getRequest(binId: string, reqId: string): CapturedRequest | undefined;
-  clearRequests(binId: string): void;
-  cleanupExpired(now: number): string[];
-}
-//#endregion
-//#region src/bin-manager.d.ts
+type BinDocument = {
+  bin: Bin;
+  requests: CapturedRequest[];
+};
 /**
- * Configuration options for {@link BinManager}.
+ * Options for a {@link MockHttpBins} instance.
  */
-type BinManagerOptions = {
-  /** Storage backend. Defaults to a new {@link InMemoryBinStore}. */
-  store?: BinStore;
-  /** Bin lifetime in milliseconds. Defaults to 24 hours. */
+type MockHttpBinsOptions = {
+  /**
+   * Keyv store for bins. The default is `new Keyv()`, which keeps data in memory.
+   * Pass an instance when you want a different Keyv adapter.
+   */
+  keyv?: Keyv<BinDocument>;
+  /** Bin lifetime in milliseconds. The default is 24 hours. */
   defaultTtlMs?: number;
-  /** Maximum number of requests retained per bin (FIFO). Defaults to 100. */
+  /** Maximum number of requests in one bin. The default is 100. */
   maxRequestsPerBin?: number;
-  /** Maximum captured body size in bytes. Larger bodies are truncated. Defaults to 1 MiB. */
+  /** Maximum captured body size in bytes. The default is 128 KiB. */
   maxBodySize?: number;
-  /** Length of generated bin and request ids. Defaults to 12. */
+  /** Length of a generated bin id or request id. The default is 12. */
   idLength?: number;
-  /** Interval between cleanup sweeps in milliseconds. Defaults to 1 minute. */
-  cleanupIntervalMs?: number;
 };
 /**
- * Manages request bins: ephemeral URL endpoints that capture incoming HTTP
- * requests so they can be inspected later.
+ * Stores request bins in Keyv.
+ * The default store is `new Keyv()`, which keeps data in memory.
  */
-export declare class BinManager {
-  private readonly _store;
+export declare class MockHttpBins {
+  private readonly _keyv;
   private readonly _defaultTtlMs;
   private readonly _maxRequestsPerBin;
   private readonly _maxBodySize;
   private readonly _idLength;
-  private readonly _cleanupIntervalMs;
-  private _cleanupTimer;
-  constructor(options?: BinManagerOptions);
-  /** Underlying storage backend. */
-  get store(): BinStore;
+  private readonly _locks;
+  constructor(options?: MockHttpBinsOptions);
+  /** Keyv instance that stores the bins. */
+  get keyv(): Keyv<BinDocument>;
   /** Maximum captured body size in bytes. */
   get maxBodySize(): number;
-  /** Maximum number of requests retained per bin. */
+  /** Maximum number of requests in one bin. */
   get maxRequestsPerBin(): number;
   /** Default bin lifetime in milliseconds. */
   get defaultTtlMs(): number;
-  /** Create a new bin with the configured TTL. */
-  createBin(): Bin;
-  /**
-   * Look up a bin by id. Returns `undefined` if the bin does not exist or
-   * has expired (in which case it is also lazily removed).
-   */
-  getBin(id: string): Bin | undefined;
-  /** List all non-expired bins. */
-  listBins(): Bin[];
-  /** Delete a bin. Returns true if the bin existed. */
-  deleteBin(id: string): boolean;
-  /**
-   * Record an incoming request against a bin. Returns the stored
-   * {@link CapturedRequest}, or `undefined` if the bin does not exist or is
-   * expired.
-   */
-  recordRequest(binId: string, raw: Omit<CapturedRequest, "id" | "binId" | "capturedAt">): CapturedRequest | undefined;
-  /** List captured requests for a bin (newest first). */
-  getRequests(binId: string): CapturedRequest[];
-  /** Look up a single captured request. */
-  getRequest(binId: string, reqId: string): CapturedRequest | undefined;
-  /** Clear all captured requests in a bin. */
-  clearRequests(binId: string): void;
-  /** Start the periodic cleanup of expired bins. */
-  start(): void;
-  /** Stop the periodic cleanup. Idempotent. */
-  stop(): void;
-  private generateId;
-}
-//#endregion
-//#region src/certificate.d.ts
-type CertificateOptions = {
   /**
-   * Common Name for the certificate subject. Defaults to 'localhost'.
+   * Create a new bin with the configured lifetime.
+   * Throws when Keyv does not store the bin.
    */
-  commonName?: string;
+  createBin(): Promise<Bin>;
   /**
-   * Subject Alternative Names. Defaults to [dns:localhost, ip:127.0.0.1, ip:::1].
+   * Look up a bin by id.
+   * Returns `undefined` when the bin does not exist or Keyv has expired it.
+   * A failed read also returns `undefined` when the Keyv instance has an `error` listener.
    */
-  altNames?: Array<{
-    type: "dns";
-    value: string;
-  } | {
-    type: "ip";
-    value: string;
-  }>;
+  getBin(id: string): Promise<Bin | undefined>;
   /**
-   * Number of days the certificate is valid. Defaults to 365.
+   * List the bins that Keyv still holds.
+   * Throws when the Keyv store has no iterator.
+   * When the Keyv instance has an `error` listener, a failed walk returns the bins read before the error.
    */
-  validityDays?: number;
+  listBins(): Promise<Bin[]>;
   /**
-   * RSA key size in bits. Defaults to 2048.
+   * Delete a bin. Returns true when the bin existed.
+   * The delete waits for captures already queued for that bin, so a capture cannot write the bin back.
    */
-  keySize?: number;
-};
-type CertificateResult = {
+  deleteBin(id: string): Promise<boolean>;
   /**
-   * PEM-encoded X.509 certificate.
+   * Record a request for a bin.
+   * Returns `undefined` when the bin does not exist.
+   * Throws when Keyv does not store the capture.
    */
-  cert: string;
+  recordRequest(binId: string, raw: Omit<CapturedRequest, "id" | "binId" | "capturedAt">): Promise<CapturedRequest | undefined>;
+  /** List captured requests for a bin, newest first. */
+  getRequests(binId: string): Promise<CapturedRequest[]>;
+  /** Look up one captured request. */
+  getRequest(binId: string, reqId: string): Promise<CapturedRequest | undefined>;
   /**
-   * PEM-encoded PKCS#8 private key.
+   * Remove captured requests and keep the bin.
+   * Returns false when the bin does not exist.
+   * Throws when Keyv does not store the change.
    */
-  key: string;
-};
-type CertificateFileOptions = CertificateOptions & {
+  clearRequests(binId: string): Promise<boolean>;
+  /** Keyv 6 yields nothing when the store has no iterator. Listing must fail instead. */
+  private canIterate;
+  /** Returns false when the bin does not exist. */
+  private appendRequest;
   /**
-   * File path to write the certificate PEM.
+   * Write a bin document with a TTL from its lifetime.
+   * Keyv returns false or throws when the write fails. Both cases throw here.
    */
-  certPath: string;
+  private save;
   /**
-   * File path to write the private key PEM.
+   * Run writes for one bin in order.
+   * A failed write does not block the next write for that bin.
    */
-  keyPath: string;
-};
-/**
- * Generate a self-signed certificate using only Node.js built-in crypto.
- * Returns PEM-encoded certificate and private key strings.
- */
-export declare function generateCertificate(options?: CertificateOptions): CertificateResult;
-/**
- * Generate a self-signed certificate and write PEM files to disk.
- * Returns the same CertificateResult as generateCertificate().
- */
-export declare function generateCertificateFiles(options: CertificateFileOptions): Promise<CertificateResult>;
+  private enqueue;
+  /** Keyv keeps a key without a TTL forever, so the TTL never drops below 1 ms. */
+  private ttlFor;
+  private binKey;
+  private generateId;
+}
 //#endregion
 //#region src/tap-manager.d.ts
 /**
@@ -430,12 +455,6 @@ type MockHttpOptions = {
    * timeout (needed on Cloudflare Workers, where avvio timers are unreliable).
    */
   pluginTimeout?: number;
-  /**
-   * Whether to start the request-bin cleanup timer during `initialize()`.
-   * Defaults to true. Disable this on Cloudflare Workers, where `setInterval`
-   * during startup can hang the isolate.
-   */
-  startBins?: boolean;
   /**
    * HTTPS configuration. Set to true to auto-generate a self-signed certificate,
    * or provide an object with cert/key strings/paths or auto-generation options.
@@ -464,7 +483,6 @@ declare class MockHttp extends Hookified {
   private _siteDistPath;
   private _logging;
   private _pluginTimeout?;
-  private _startBins;
   private _httpBin;
   private _rateLimit?;
   private _http2;
@@ -474,6 +492,7 @@ declare class MockHttp extends Hookified {
   private _server;
   private _taps;
   private _bins;
+  private _binHealthCheck?;
   constructor(options?: MockHttpOptions);
   /**
    * The port to listen on. If not provided, defaults to 3000 and detects the next available port if in use.
@@ -563,16 +582,6 @@ declare class MockHttp extends Hookified {
    * Fastify plugin boot timeout in milliseconds. `undefined` uses Fastify's default.
    */
   set pluginTimeout(pluginTimeout: number | undefined);
-  /**
-   * Whether to start the request-bin cleanup timer during `initialize()`.
-   * @default true
-   */
-  get startBins(): boolean;
-  /**
-   * Whether to start the request-bin cleanup timer during `initialize()`.
-   * @default true
-   */
-  set startBins(startBins: boolean);
   /**
    * HTTPS configuration. Set to true to auto-generate a self-signed certificate,
    * or provide an HttpsOptions object with cert/key or auto-generation options.
@@ -646,13 +655,20 @@ declare class MockHttp extends Hookified {
    */
   set taps(taps: TapManager);
   /**
-   * The BinManager instance for managing request bins.
+   * The MockHttpBins instance for request bins.
+   */
+  get bins(): MockHttpBins;
+  /**
+   * The MockHttpBins instance for request bins.
    */
-  get bins(): BinManager;
+  set bins(bins: MockHttpBins);
   /**
-   * The BinManager instance for managing request bins.
+   * Override the bin storage probe used by `GET /healthz`.
+   * The default probe reads the in-memory Keyv.
    */
-  set bins(bins: BinManager);
+  set binHealthCheck(check: () => Promise<BinHealth>);
+  /** Whether bin storage can serve a read or a MongoDB ping. */
+  checkBinStore(): Promise<BinHealth>;
   /**
    * Register plugins and routes without listening. Use `inject()` against
    * `server`, or call `start()` to bind a port.
@@ -749,4 +765,4 @@ declare class MockHttp extends Hookified {
 //#region src/index.d.ts
 export declare const start: () => Promise<MockHttp>;
 //#endregion
-export { type Bin, type BinManagerOptions, type BinStore, type CapturedRequest, type CertificateFileOptions, type CertificateOptions, type CertificateResult, type HttpsOptions, type InjectionMatcher, type InjectionResponse, type InjectionTap, MockHttp as default, MockHttp as mockhttp };
+export { type Bin, type CapturedRequest, type CertificateFileOptions, type CertificateOptions, type CertificateResult, type HttpsOptions, type InjectionMatcher, type InjectionResponse, type InjectionTap, type MockHttpBinsOptions, MockHttp as default, MockHttp as mockhttp };