@jaredwray/mockhttp 2.1.0 → 3.0.0

package/README.md

@@ -618,13 +618,13 @@ curl -s "http://localhost:3000/bins/$ID/requests" \
 
 ### Truncation
 
-Bodies larger than `maxBodySize` (1 MiB by default) are cut off and flagged:
+Bodies larger than `maxBodySize` (128 KiB by default) are cut off and flagged:
 
 ```javascript
 // In test setup
-import { MockHttp, BinManager } from '@jaredwray/mockhttp';
+import { MockHttp, MockHttpBins } from '@jaredwray/mockhttp';
 const mock = new MockHttp();
-mock.bins = new BinManager({ maxBodySize: 1024 }); // 1 KiB cap
+mock.bins = new MockHttpBins({ maxBodySize: 1024 }); // 1 KiB cap
 await mock.start();
 ```
 
@@ -664,8 +664,7 @@ curl -s "http://localhost:3000/bins/$ID/requests" | jq '.requests[0].path'
 
 ## Programmatic Access
 
-The bin manager is exposed on the `MockHttp` instance as `mock.bins`. This
-makes it easy to drive bins from a test suite without going through HTTP:
+Use `mock.bins` to control request bins from a test. You do not need an HTTP call:
 
 ```javascript
 import { MockHttp } from '@jaredwray/mockhttp';
@@ -674,13 +673,13 @@ const mock = new MockHttp({ logging: false });
 await mock.start();
 
 // Create a bin
-const bin = mock.bins.createBin();
+const bin = await mock.bins.createBin();
 console.log(`Webhook target: http://localhost:${mock.port}/b/${bin.id}`);
 
 // ... point your code-under-test at that URL ...
 
 // Read captured requests (newest first)
-const requests = mock.bins.getRequests(bin.id);
+const requests = await mock.bins.getRequests(bin.id);
 console.log(`Captured ${requests.length} requests`);
 
 for (const req of requests) {
@@ -688,8 +687,8 @@ for (const req of requests) {
 }
 
 // Clean up
-mock.bins.deleteBin(bin.id);
-await mock.close(); // also stops the bin cleanup timer
+await mock.bins.deleteBin(bin.id);
+await mock.close();
 ```
 
 ### Using Bins in a Vitest Test
@@ -710,14 +709,14 @@ afterAll(async () => {
 });
 
 test('my SDK sends the right webhook payload', async () => {
-  const bin = mock.bins.createBin();
+  const bin = await mock.bins.createBin();
   const webhookUrl = `http://localhost:${mock.port}/b/${bin.id}`;
 
   // Drive your SDK at the bin
   await mySdk.notify(webhookUrl, { event: 'user.created', id: 42 });
 
   // Assert on what actually arrived
-  const [captured] = mock.bins.getRequests(bin.id);
+  const [captured] = await mock.bins.getRequests(bin.id);
   expect(captured.method).toBe('POST');
   expect(captured.contentType).toBe('application/json');
   expect(JSON.parse(captured.body!)).toEqual({
@@ -738,18 +737,17 @@ const mock = new MockHttp({
 });
 ```
 
-To tune limits, replace the default `BinManager` before starting:
+To change the limits, replace the default `MockHttpBins` before you start the server:
 
 ```javascript
-import { MockHttp, BinManager } from '@jaredwray/mockhttp';
+import { MockHttp, MockHttpBins } from '@jaredwray/mockhttp';
 
 const mock = new MockHttp();
-mock.bins = new BinManager({
+mock.bins = new MockHttpBins({
   defaultTtlMs: 60 * 60 * 1000,    // 1 hour (default: 24h)
   maxRequestsPerBin: 500,           // (default: 100)
-  maxBodySize: 5 * 1024 * 1024,     // 5 MiB (default: 1 MiB)
+  maxBodySize: 512 * 1024,          // 512 KiB (default: 128 KiB)
   idLength: 16,                     // (default: 12)
-  cleanupIntervalMs: 30 * 1000,     // sweep every 30s (default: 60s)
 });
 
 await mock.start();
@@ -759,44 +757,40 @@ await mock.start();
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `defaultTtlMs` | `86400000` (24h) | Bin lifetime. Expired bins return 404 and are lazily removed. |
+| `defaultTtlMs` | `86400000` (24h) | Bin lifetime, set as the Keyv TTL. An expired bin returns 404. |
 | `maxRequestsPerBin` | `100` | When exceeded, oldest captures are dropped (FIFO). |
-| `maxBodySize` | `1048576` (1 MiB) | Larger bodies are truncated; `truncated: true` is set on the capture. |
+| `maxBodySize` | `131072` (128 KiB) | Larger bodies are truncated; `truncated: true` is set on the capture. |
 | `idLength` | `12` | Length of generated bin and request ids. |
-| `cleanupIntervalMs` | `60000` (1 min) | How often expired bins are swept. The timer is `unref()`'d so it never keeps the process alive. |
+| `keyv` | `new Keyv()` | Keyv store for bins. The default keeps bins in memory. |
+
+### Storage
 
-### Pluggable Storage
+`MockHttpBins` stores each bin in [Keyv](https://github.com/jaredwray/keyv) 6. The default is `new Keyv()`. That store keeps the data in memory for this process.
 
-`BinManager` accepts a `store: BinStore` so you can plug in alternative
-backends (Redis, SQLite, etc.) without changing the rest of the codebase. The
-default `InMemoryBinStore` keeps state in process memory.
+Pass a Keyv 6 instance when you want a different adapter. Install the adapter in your project. This package does not include an adapter. `@keyv/redis` 6 matches this Keyv version.
 
 ```typescript
-import {
-  BinManager,
-  InMemoryBinStore,
-  type Bin,
-  type BinStore,
-  type CapturedRequest,
-} from '@jaredwray/mockhttp';
-
-class RedisBinStore implements BinStore {
-  createBin(bin: Bin): void { /* SET bin:${bin.id} ... */ }
-  getBin(id: string): Bin | undefined { /* GET ... */ }
-  listBins(): Bin[] { /* SCAN ... */ }
-  deleteBin(id: string): boolean { /* DEL ... */ }
-  addRequest(binId: string, req: CapturedRequest, max: number): void {
-    /* LPUSH bin:${binId}:requests + LTRIM to max */
-  }
-  getRequests(binId: string): CapturedRequest[] { /* LRANGE ... */ }
-  getRequest(binId: string, reqId: string): CapturedRequest | undefined { /* ... */ }
-  clearRequests(binId: string): void { /* DEL bin:${binId}:requests */ }
-  cleanupExpired(now: number): string[] { /* scan + delete */ return []; }
-}
+import Keyv from 'keyv';
+import KeyvRedis from '@keyv/redis'; // pnpm add @keyv/redis
+import { MockHttpBins } from '@jaredwray/mockhttp';
 
-mock.bins = new BinManager({ store: new RedisBinStore() });
+mock.bins = new MockHttpBins({
+  keyv: new Keyv({ store: new KeyvRedis('redis://localhost:6379') }),
+});
 ```
 
+Each capture writes the full bin again. A large body or a high request limit makes that write large. Set `maxBodySize` and `maxRequestsPerBin` to limit the size. With the defaults, a full bin of binary bodies is about 17 MB.
+
+Two processes that share one Keyv can lose a capture. This occurs when both processes write the same bin at the same time.
+
+If Keyv does not store a write, the bin route returns `500` with the standard Fastify error body: `statusCode`, `error`, and `message`.
+
+A failed read depends on the Keyv `error` listener. Without a listener, Keyv throws the store error and the route returns `500`. With a listener, Keyv does not throw. A failed read then looks like a missing bin, and the route returns `404`. `listBins()` returns only the bins that it read before the error.
+
+`listBins()` throws an error when the adapter has no iterator.
+
+An expired bin returns 404. The in-memory Keyv store deletes an expired bin only when a read or `listBins()` reaches it. Until then, the bin stays in memory.
+
 # Rate Limiting
 
 MockHttp supports rate limiting using [@fastify/rate-limit](https://github.com/fastify/fastify-rate-limit). Rate limiting is **enabled by default** at **1000 requests per minute** with **localhost (127.0.0.1 and ::1) excluded** from rate limiting.
@@ -1012,7 +1006,6 @@ new MockHttp(options?)
   - `logging?`: boolean - Enable logging (default: true)
   - `staticFiles?`: boolean - Serve files from the package `public/` directory (default: true)
   - `pluginTimeout?`: number - Fastify plugin boot timeout in milliseconds; `0` disables it (default: Fastify's timeout)
-  - `startBins?`: boolean - Start the request-bin cleanup timer during `initialize()` (default: true)
   - `httpBin?`: HttpBinOptions - Configure which httpbin routes to enable
     - `httpMethods?`: boolean - Enable HTTP method routes (default: true)
     - `redirects?`: boolean - Enable redirect routes (default: true)
@@ -1041,7 +1034,6 @@ new MockHttp(options?)
 - `logging`: boolean - Get/set logging enabled state
 - `staticFiles`: boolean - Get/set whether files from `public/` are served
 - `pluginTimeout`: number | undefined - Get/set Fastify plugin boot timeout
-- `startBins`: boolean - Get/set whether bin cleanup starts during `initialize()`
 - `rateLimit`: RateLimitPluginOptions | undefined - Get/set rate limiting options
 - `httpBin`: HttpBinOptions - Get/set httpbin route options
 - `https`: HttpsOptions | undefined - Get/set HTTPS configuration
@@ -1050,7 +1042,7 @@ new MockHttp(options?)
 - `http1`: boolean - Get/set HTTP/1.1 fallback for HTTP/2 with HTTPS
 - `server`: FastifyInstance - Get/set the Fastify server instance
 - `taps`: TapManager - Get/set the TapManager instance
-- `bins`: BinManager - Get/set the BinManager instance for request bins
+- `bins`: MockHttpBins - Get or set the request bins
 
 ### Methods
 
@@ -1130,57 +1122,55 @@ Register the request bin routes — management at `/bins` and capture at `/b/:id
 
 ## Bins (Request Capture)
 
-Access the BinManager via `mockHttp.bins` to manage request bins programmatically. See [Request Bins](#request-bins) for usage examples.
+Use `mockHttp.bins` to control request bins. See [Request Bins](#request-bins) for usage examples.
 
 ### `bins.createBin()`
 
-Create a new bin with the configured TTL.
+Create a new bin with the configured TTL. Throws when Keyv does not store the bin.
 
-**Returns:** `Bin` — `{ id, createdAt, expiresAt, requestCount }`
+**Returns:** `Promise<Bin>` — `{ id, createdAt, expiresAt, requestCount }`
 
 ### `bins.getBin(id)`
 
-Look up a bin by id. Returns `undefined` if the bin does not exist or has expired (and lazily removes the expired entry).
+Look up a bin by id. Returns `undefined` if the bin does not exist or Keyv has expired it. When the Keyv instance has an `error` listener, a failed read also returns `undefined`.
 
-**Returns:** `Bin | undefined`
+**Returns:** `Promise<Bin | undefined>`
 
 ### `bins.listBins()`
 
-List all non-expired bins.
+List the bins that Keyv still holds.
 
-**Returns:** `Bin[]`
+**Returns:** `Promise<Bin[]>`
 
 ### `bins.deleteBin(id)`
 
-Delete a bin and all its captured requests.
+Delete a bin and all its captured requests. The delete waits for captures already queued for that bin.
 
-**Returns:** `boolean` — `true` if the bin existed
+**Returns:** `Promise<boolean>` — `true` when the bin existed
 
 ### `bins.getRequests(binId)`
 
 List captured requests for a bin, newest first.
 
-**Returns:** `CapturedRequest[]`
+**Returns:** `Promise<CapturedRequest[]>`
 
 ### `bins.getRequest(binId, reqId)`
 
 Look up a single captured request.
 
-**Returns:** `CapturedRequest | undefined`
+**Returns:** `Promise<CapturedRequest | undefined>`
 
 ### `bins.clearRequests(binId)`
 
-Clear all captured requests in a bin (the bin itself is preserved).
+Clear all captured requests in a bin. The bin stays. Throws when Keyv does not store the change.
 
-### `bins.recordRequest(binId, raw)`
-
-Manually record a captured request. Returns `undefined` if the bin does not exist or is expired. Normally invoked by the capture route, but available for programmatic use.
+**Returns:** `Promise<boolean>` — `false` when the bin does not exist
 
-**Returns:** `CapturedRequest | undefined`
+### `bins.recordRequest(binId, raw)`
 
-### `bins.start()` / `bins.stop()`
+Manually record a captured request. Returns `undefined` if the bin does not exist. Throws when Keyv does not store the capture. Normally invoked by the capture route, but available for programmatic use.
 
-Start or stop the periodic cleanup of expired bins. `MockHttp.start()` and `MockHttp.close()` call these automatically. The interval is `unref()`'d so it never keeps the Node process alive.
+**Returns:** `Promise<CapturedRequest | undefined>`
 
 ### `bins.maxBodySize` / `bins.maxRequestsPerBin` / `bins.defaultTtlMs`
 
@@ -1240,7 +1230,7 @@ A getter that returns whether there are any active injections.
 
 # About mockhttp.org
 
-[mockhttp.org](https://mockhttp.org) is a free hosted instance of this codebase for testing. It runs on a [Cloudflare Worker](https://developers.cloudflare.com/workers/) (no containers): documentation is served from Workers Assets, and mock APIs such as `/get` and `/post` run in the Worker. The service is globally available and rate-limited (1000 requests per minute per IP) to prevent abuse.
+[mockhttp.org](https://mockhttp.org) is a free hosted instance of this codebase for testing. It runs on a [Cloudflare Worker](https://developers.cloudflare.com/workers/) (no containers): documentation is served from Workers Assets, and mock APIs such as `/get` and `/post` run in the Worker. The service is globally available and rate-limited (1000 requests per minute per IP) to prevent abuse. Request bins on this service are stored in MongoDB Atlas, in the `bins` collection, so they are shared across isolates.
 
 All [mockhttp.org](https://mockhttp.org) traffic stays on Cloudflare. A separate test app runs the Node server on Wasmer Edge at [mockhttp.wasmer.app](https://mockhttp.wasmer.app).
 

package/dist/index.d.mts

@@ -1,6 +1,63 @@
 import { RateLimitPluginOptions } from "@fastify/rate-limit";
 import { FastifyInstance, FastifyRequest } from "fastify";
 import { Hookified, HookifiedOptions } from "hookified";
+import Keyv from "keyv";
+//#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 +105,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 +418,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 +446,6 @@ declare class MockHttp extends Hookified {
   private _siteDistPath;
   private _logging;
   private _pluginTimeout?;
-  private _startBins;
   private _httpBin;
   private _rateLimit?;
   private _http2;
@@ -563,16 +544,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 +617,13 @@ declare class MockHttp extends Hookified {
    */
   set taps(taps: TapManager);
   /**
-   * The BinManager instance for managing request bins.
+   * The MockHttpBins instance for request bins.
    */
-  get bins(): BinManager;
+  get bins(): MockHttpBins;
   /**
-   * The BinManager instance for managing request bins.
+   * The MockHttpBins instance for request bins.
    */
-  set bins(bins: BinManager);
+  set bins(bins: MockHttpBins);
   /**
    * Register plugins and routes without listening. Use `inject()` against
    * `server`, or call `start()` to bind a port.
@@ -749,4 +720,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 };