@jaredwray/mockhttp 2.1.0 → 3.0.1

package/site/dist/llms-full.txt

@@ -489,6 +489,74 @@ curl http://localhost:3000/bins/abc123def456/requests
 | DELETE | `/bins/:id/requests` | Clear all captured requests in a bin |
 | DELETE | `/bins/:id` | Delete a bin |
 | ANY | `/b/:id` and `/b/:id/*` | Capture requests sent to a bin |
+| GET | `/healthz` | Check whether bin storage is reachable |
+
+## Storage health
+
+`GET /healthz` is on the Node server and the Worker. This route does not create a bin.
+
+A memory store sends HTTP 200:
+
+```json
+{
+  "status": "ok",
+  "bins": {
+    "store": "memory",
+    "connected": true,
+    "latencyMs": 1,
+    "uriPresent": false
+  }
+}
+```
+
+The Worker uses MongoDB when `MONGODB_URI` is set. The check opens a client, sends an admin ping, and then closes the client. The timeout is short. The check does not keep the client after a failure.
+
+A successful ping sends HTTP 200. `store` is `mongo`.
+
+A failed ping sends HTTP 503:
+
+```json
+{
+  "status": "error",
+  "bins": {
+    "store": "mongo",
+    "connected": false,
+    "uriPresent": true,
+    "uri": {
+      "length": 78,
+      "leadingWhitespace": false,
+      "trailingWhitespace": false,
+      "newline": false,
+      "wrappedQuotes": false,
+      "atCount": 2,
+      "passwordReserved": ["@"],
+      "passwordHasPercent": false
+    },
+    "error": {
+      "name": "MongoParseError",
+      "message": "Invalid connection string. Percent-encode reserved characters in the username and password (@ : / ? # [ ] $).",
+      "code": null
+    }
+  }
+}
+```
+
+A MongoDB result includes `bins.uri` on success and on failure. A memory result omits `bins.uri`. The response does not include the scheme, the host, the username, or the password length.
+
+`uri.passwordReserved` lists raw reserved characters in the password. The list is empty when the password has only reserved characters. `uri.passwordHasPercent` is true when the password contains `%`. The response does not contain the connection string or the password. The logs do not contain the connection string, the username, the password, or the host. `uriPresent` is a boolean.
+
+`Invalid connection string` is the driver text. MockHTTP adds the percent-encode hint only for that text or for `unescaped characters`. A DNS error stays a DNS error. `Invalid connection string` means that the URI has a second `@`. It also means that you did not encode a reserved character in the username or the password. Encode these characters:
+
+- `@` as `%40`
+- `:` as `%3A`
+- `/` as `%2F`
+- `?` as `%3F`
+- `#` as `%23`
+- `[` as `%5B`
+- `]` as `%5D`
+- `$` as `%24`
+
+A correct `mongodb+srv://` URI does not fail at parse time. A DNS failure or a network failure has a different error name.
 
 ## End-to-End Webhook Debugging Example
 
@@ -617,13 +685,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();
 ```
 
@@ -663,8 +731,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';
@@ -673,13 +740,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) {
@@ -687,8 +754,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
@@ -709,14 +776,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({
@@ -737,18 +804,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();
@@ -758,44 +824,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.
+
 ### Configuration
 URL: https://mockhttp.org/docs/configuration/
 
@@ -1017,7 +1079,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)
@@ -1046,7 +1107,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
@@ -1055,7 +1115,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
 
@@ -1131,61 +1191,59 @@ Register image routes (jpeg, png, svg, webp) with content negotiation support.
 
 #### `async registerBinRoutes(fastifyInstance?)`
 
-Register the request bin routes — management at `/bins` and capture at `/b/:id`.
+Register the request bin routes. Management is at `/bins` and capture is at `/b/:id`. `GET /healthz` reports whether bin storage is reachable.
 
 ## 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`
 
@@ -1248,7 +1306,7 @@ URL: https://mockhttp.org/docs/hosted/
 
 # About mockhttp.org
 
-[mockhttp.org](https://mockhttp.org) is a free hosted instance of this codebase for testing. It runs on a [Cloudflare Worker](/docs/how-to-deploy/cloudflare/) (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](/docs/how-to-deploy/cloudflare/) (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](/docs/how-to-deploy/wasmer/) at [mockhttp.wasmer.app](https://mockhttp.wasmer.app).
 
@@ -1273,12 +1331,21 @@ The Worker starts the same MockHTTP app as Node.js, with a few options set for t
 | `rateLimit` | `false` | [`@fastify/rate-limit`](https://github.com/fastify/fastify-rate-limit) is off. A Cloudflare rate limiting binding allows 1000 requests per 60 seconds per IP. |
 | `siteDistPath` | unused path | Fastify does not serve the docs. Workers Assets serve `site/dist`. |
 | `staticFiles` | `false` | Logos and other `public/` files are copied into `site/dist` and read through the `ASSETS` binding. |
-| `startBins` | `false` | The bin cleanup timer uses `setInterval`, which can hang a Worker isolate during startup. Bin routes still register. Expired bins are removed when that bin is read, not by a sweep of every bin. |
 | `pluginTimeout` | `0` | Disables Fastify's plugin boot timeout. Those timers are unreliable on Workers. |
 | `logging` | `false` | Request logging is off. |
 | `autoDetectPort` | `false` | The app always listens on port 3000 inside the isolate. |
 
-The rate limiter key is the `cf-connecting-ip` header, then the first address in `x-forwarded-for`, then `unknown`. A limited request returns `429` with `retry-after: 60`. That limiter is shared across isolates. Bins are not. The default store is in memory inside the isolate that handled the request, so a bin created on one request can be missing when another isolate or location handles the next one.
+The rate limiter key is the `cf-connecting-ip` header, then the first address in `x-forwarded-for`, then `unknown`. A limited request returns `429` with `retry-after: 60`. That limiter is shared across isolates.
+
+Bins stay in memory in the isolate when `MONGODB_URI` is not set. A bin from one request can be absent when a different isolate handles the next request. When `MONGODB_URI` is set, bins are stored in MongoDB. Each request opens its own client on its first bin operation and closes it after the response, through `ctx.waitUntil`. No client is shared between requests: workerd rejects I/O on a socket that a different request opened, and a shared client made bin requests fail with error 1101. It does not connect while the isolate starts. Each bin request therefore pays one connection setup, which is a few round trips to Atlas.
+
+Percent-encode reserved characters in the username and the password. `@` is `%40`. An unencoded `@` makes the driver throw `Invalid connection string` before it contacts Atlas.
+
+`GET /healthz` reports the bin store. A successful admin ping returns HTTP 200 and `bins.connected: true`. A failed ping returns HTTP 503 with the driver error name, a redacted message, and a code. The body has `uriPresent` (boolean). It does not have the scheme. On the Node server, this route reports the memory store.
+
+When `MONGODB_URI` is set, `bins.uri` has the URI length and the `@` count. It also has flags for whitespace, a newline, and quote marks. It does not have the host, the username, or the password length. The body does not have the password or the full URI.
+
+The percent-encode hint is added only for `Invalid connection string` or `unescaped characters`. A DNS error keeps the driver text. `uri.passwordReserved` is empty when the password has only reserved characters. Worker logs still omit the URI, the username, the password, and the host.
 
 Taps are a library API (`mock.taps.inject`). They have no HTTP routes, so a deployed Worker has no way to inject one.
 
@@ -1422,7 +1489,7 @@ Change `name` and `owner` before you deploy your own app. The environment variab
 
 [`Anybuild`](https://github.com/jaredwray/mockhttp/blob/main/Anybuild) tells Wasmer how to build the package on a remote builder:
 
-- Node.js 24 and pnpm `12.4.1`
+- Node.js 24 and pnpm `12.12.1`
 - Build command: `pnpm run build && pnpm website:build`
 - Start command: `node dist/index.mjs`
 
@@ -1448,7 +1515,7 @@ wasmer deploy --non-interactive --build-remote
 
 ## Runtime behavior
 
-Bins use the default in-memory store, so a bin exists only on the instance that created it. Taps are a library API (`mock.taps.inject`) and have no HTTP routes, so a deployed app cannot inject one.
+Bins use `new Keyv()` by default. The store keeps each bin in memory on the instance that created it. Give `MockHttpBins` a shared Keyv when bins must be visible on more than one instance. Two processes can lose a capture when they write the same bin at the same time. Taps are a library API (`mock.taps.inject`) and have no HTTP routes, so a deployed app cannot inject one.
 
 `@fastify/rate-limit` is on at 1000 requests per minute. It keys on the address that connects to the process. The server does not trust proxy headers, and the allow list is only `127.0.0.1` and `::1`. On the test app, `/ip` reports `127.0.0.100`, which is the edge proxy rather than the caller, and the response includes `x-ratelimit-limit: 1000`. Clients that share that proxy address share one limit on that instance. This is not the Cloudflare limiter used by [mockhttp.org](https://mockhttp.org).
 
@@ -1464,12 +1531,237 @@ OpenAPI Spec Source: /home/runner/work/mockhttp/mockhttp/site/api/swagger.json
   "info": {
     "title": "Mock HTTP API",
     "description": "\nA simple HTTP server that can be used to mock HTTP responses for testing purposes. Inspired by [httpbin](https://httpbin.org/) and built using `nodejs` and `fastify` with the idea of running it via https://mockhttp.org, via docker `jaredwray/mockhttp`, or nodejs `npm install @jaredwray/mockhttp`.\n\n* [GitHub Repository](https://github.com/jaredwray/mockhttp)\n* [Docker Image](https://hub.docker.com/r/jaredwray/mockhttp)\n* [NPM Package](https://www.npmjs.com/package/@jaredwray/mockhttp)\n\n# About mockhttp.org\n\n[mockhttp.org](https://mockhttp.org) is a free hosted instance of this codebase for testing. It runs on a Cloudflare Worker (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.\n",
-    "version": "2.1.0"
+    "version": "3.0.1"
   },
   "components": {
     "schemas": {}
   },
   "paths": {
+    "/healthz": {
+      "get": {
+        "tags": [
+          "Health"
+        ],
+        "description": "Report whether bin storage is reachable. MongoDB failures include the driver error. The scheme, the host, the username, the password, the password length, and the full URI are never returned.",
+        "responses": {
+          "200": {
+            "description": "Default Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "ok"
+                      ]
+                    },
+                    "bins": {
+                      "type": "object",
+                      "properties": {
+                        "store": {
+                          "type": "string",
+                          "enum": [
+                            "mongo",
+                            "memory"
+                          ]
+                        },
+                        "connected": {
+                          "type": "boolean"
+                        },
+                        "latencyMs": {
+                          "type": "integer"
+                        },
+                        "uriPresent": {
+                          "type": "boolean"
+                        },
+                        "uri": {
+                          "type": "object",
+                          "properties": {
+                            "length": {
+                              "type": "integer"
+                            },
+                            "leadingWhitespace": {
+                              "type": "boolean"
+                            },
+                            "trailingWhitespace": {
+                              "type": "boolean"
+                            },
+                            "newline": {
+                              "type": "boolean"
+                            },
+                            "wrappedQuotes": {
+                              "type": "boolean"
+                            },
+                            "atCount": {
+                              "type": "integer"
+                            },
+                            "passwordReserved": {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            },
+                            "passwordHasPercent": {
+                              "type": "boolean"
+                            }
+                          },
+                          "required": [
+                            "length",
+                            "leadingWhitespace",
+                            "trailingWhitespace",
+                            "newline",
+                            "wrappedQuotes",
+                            "atCount",
+                            "passwordReserved",
+                            "passwordHasPercent"
+                          ]
+                        }
+                      },
+                      "required": [
+                        "store",
+                        "connected",
+                        "latencyMs",
+                        "uriPresent"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "status",
+                    "bins"
+                  ]
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Default Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "error"
+                      ]
+                    },
+                    "bins": {
+                      "type": "object",
+                      "properties": {
+                        "store": {
+                          "type": "string",
+                          "enum": [
+                            "mongo",
+                            "memory"
+                          ]
+                        },
+                        "connected": {
+                          "type": "boolean"
+                        },
+                        "latencyMs": {
+                          "type": "integer"
+                        },
+                        "uriPresent": {
+                          "type": "boolean"
+                        },
+                        "uri": {
+                          "type": "object",
+                          "properties": {
+                            "length": {
+                              "type": "integer"
+                            },
+                            "leadingWhitespace": {
+                              "type": "boolean"
+                            },
+                            "trailingWhitespace": {
+                              "type": "boolean"
+                            },
+                            "newline": {
+                              "type": "boolean"
+                            },
+                            "wrappedQuotes": {
+                              "type": "boolean"
+                            },
+                            "atCount": {
+                              "type": "integer"
+                            },
+                            "passwordReserved": {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            },
+                            "passwordHasPercent": {
+                              "type": "boolean"
+                            }
+                          },
+                          "required": [
+                            "length",
+                            "leadingWhitespace",
+                            "trailingWhitespace",
+                            "newline",
+                            "wrappedQuotes",
+                            "atCount",
+                            "passwordReserved",
+                            "passwordHasPercent"
+                          ]
+                        },
+                        "error": {
+                          "type": "object",
+                          "properties": {
+                            "name": {
+                              "type": "string"
+                            },
+                            "message": {
+                              "type": "string"
+                            },
+                            "code": {
+                              "anyOf": [
+                                {
+                                  "type": "string"
+                                },
+                                {
+                                  "type": "number"
+                                },
+                                {
+                                  "type": "object",
+                                  "nullable": true,
+                                  "enum": [
+                                    null
+                                  ]
+                                }
+                              ]
+                            }
+                          },
+                          "required": [
+                            "name",
+                            "message",
+                            "code"
+                          ]
+                        }
+                      },
+                      "required": [
+                        "store",
+                        "connected",
+                        "uriPresent",
+                        "error"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "status",
+                    "bins"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/get": {
       "get": {
         "tags": [
@@ -1598,7 +1890,11 @@ OpenAPI Spec Source: /home/runner/work/mockhttp/mockhttp/site/api/swagger.json
                           "type": "string"
                         },
                         {
-                          "type": "null"
+                          "type": "object",
+                          "nullable": true,
+                          "enum": [
+                            null
+                          ]
                         }
                       ]
                     }
@@ -5840,10 +6136,8 @@ OpenAPI Spec Source: /home/runner/work/mockhttp/mockhttp/site/api/swagger.json
                             "type": "integer"
                           },
                           "body": {
-                            "type": [
-                              "null",
-                              "string"
-                            ]
+                            "type": "string",
+                            "nullable": true
                           },
                           "bodyEncoding": {
                             "type": "string",
@@ -6010,10 +6304,8 @@ OpenAPI Spec Source: /home/runner/work/mockhttp/mockhttp/site/api/swagger.json
                       "type": "integer"
                     },
                     "body": {
-                      "type": [
-                        "null",
-                        "string"
-                      ]
+                      "type": "string",
+                      "nullable": true
                     },
                     "bodyEncoding": {
                       "type": "string",
@@ -6950,6 +7242,143 @@ OpenAPI Spec Source: /home/runner/work/mockhttp/mockhttp/site/api/swagger.json
 ## Changelog
 URL: https://mockhttp.org/changelog
 
+### v3.0.1
+URL: https://mockhttp.org/changelog/v3-0-1
+Date: October 28, 2026
+Tag: Release
+
+## @jaredwray/mockhttp@3.0.1 — 2026-10-28
+
+Security patches and Worker fixes. /healthz omits scheme, host, username, and password length.
+
+### Bug Fixes
+- start the Worker during isolate startup (#248)
+- report bin store health and keep a failed connect in process (#249)
+- drop every second socket error that has no listener (#250)
+- Add redacted URI diagnostics to /healthz (#254)
+- open one MongoDB client per Worker request to stop 1101s on bins (#255)
+- pin Node 24.22.1 and patched undici (#256)
+- force miniflare's sharp pin to 0.35.5 (#257)
+- bump zod to 4.6.7 for GHSA-mrhx-c7xc-m3w5 (#258)
+- security - markdown-it 15.0.3 (CVE-2026-111758) (#260)
+- omit scheme and URI identity from /healthz (#262)
+
+  ```json
+  {
+    "status": "ok",
+    "bins": {
+      "connected": true,
+      "uriPresent": true,
+      "uri": {
+        "atCount": 1,
+        "passwordHasPercent": false
+      }
+    }
+  }
+  ```
+
+### Documentation
+- remove the empty vars note from the Cloudflare page (#253)
+
+### Internal
+- point worker URI fixtures at example.invalid (#251)
+- declare empty Worker vars in Wrangler (#252)
+- list LICENSE in the published package files (#259)
+
+### Contributors
+- @jaredwray (13)
+- @cursoragent (1)
+
+### Full List of Changes
+- fix: restore Cloudflare Worker routes after the v3.0.0 startup crash by @jaredwray in #248
+- Add GET /healthz and redact bin store errors by @jaredwray in #249
+- Use example.invalid for worker test URI fixtures by @jaredwray in #251
+- Drop every second socket error that has no listener by @jaredwray in #250
+- Declare empty Worker vars in Wrangler by @jaredwray in #252
+- Remove the empty vars note from the Cloudflare page by @jaredwray in #253
+- Add redacted URI diagnostics to /healthz by @jaredwray in #254
+- fix: open one MongoDB client per Worker request to stop 1101s on bins by @jaredwray in #255
+- security: pin Node 24.22.1 and patched undici by @jaredwray in #256
+- fix: security - upgrade sharp to 0.35.5 (libheif RCE) by @jaredwray in #257
+- fix: security - bump zod to 4.6.7 (GHSA-mrhx-c7xc-m3w5) by @jaredwray in #258
+- chore: list LICENSE in the published package files by @jaredwray in #259
+- fix: security - markdown-it 15.0.3 (CVE-2026-111758) by @jaredwray in #260
+- fix: omit scheme and URI identity from /healthz by @jaredwray in #262
+
+**Full diff:** [https://github.com/jaredwray/mockhttp/compare/v3.0.0...v3.0.1](https://github.com/jaredwray/mockhttp/compare/v3.0.0...v3.0.1)
+
+### v3.0.0
+URL: https://mockhttp.org/changelog/v3-0-0
+Date: October 20, 2026
+Tag: Release
+
+## @jaredwray/mockhttp@3.0.0 — 2026-10-19
+
+Request bins now use Keyv via MockHttpBins, and the Worker can store them in MongoDB Atlas.
+
+### ⚠ BREAKING CHANGES
+- Replace `BinManager`, `BinStore`, and `InMemoryBinStore` with async `MockHttpBins`. `mock.bins.start()` and `mock.bins.stop()` are removed. The default `maxBodySize` is 128 KiB (was 1 MiB). Node engines are now `>=22.19.0` (was `>=22.18.0`). (`b1ddcc0`, #246)
+  Migration: assign `mock.bins = new MockHttpBins({ keyv })` before `start()` (default store is `new Keyv()`) and `await` the bin methods.
+
+  ```ts
+  import Keyv from "keyv";
+  import { MockHttp, MockHttpBins } from "@jaredwray/mockhttp";
+
+  const mock = new MockHttp();
+  mock.bins = new MockHttpBins({ keyv: new Keyv(), maxBodySize: 128 * 1024 });
+  await mock.start();
+  const bin = await mock.bins.createBin();
+  ```
+
+### Features
+- Store Worker request bins in MongoDB Atlas when `MONGODB_URI` is set (`266157b`, #247)
+
+  ```bash
+  # Cloudflare Worker secret. Bins go in the Atlas `bins` collection.
+  # Leave MONGODB_URI unset to keep the in-memory Keyv.
+  wrangler secret put MONGODB_URI
+  ```
+
+### Bug Fixes
+- security - upgrade fastify proxy-addr, fast-uri, find-my-way, undici (`9c52869`, #233)
+- security - upgrade handlebars, source-map-js (`28aa662`, #236)
+
+### Internal
+- sync defense-in-depth files from agentic (`7fb3ce4`, #234)
+- upgrade code quality dependencies (`a57b990`, #235)
+- upgrade TypeScript and build tooling (`b11fa0f`, #237)
+- upgrade monorepo tooling (`58e8596`, #238)
+- upgrade GitHub Actions (`58bc448`, #239)
+- upgrade Dev Container images (`2047c3c`, #240)
+- upgrade Fastify dependencies (`3e93bea`, #241)
+- upgrade hookified (`d938e6e`, #242)
+- upgrade pino and pino-pretty (`c2a94ad`, #243)
+- upgrade Docker Node.js runtime image (`cd5decf`, #244)
+- pin the Compose image (`74ad4ea`, #245)
+
+### Contributors
+- @jaredwray (11)
+- @cursoragent (5)
+
+### Full List of Changes
+- fix: security - upgrade fastify proxy-addr, fast-uri, find-my-way, undici by @jaredwray in #233
+- mono - chore: sync defense-in-depth files from agentic by @jaredwray in #234
+- mono - chore: upgrade code quality dependencies by @jaredwray in #235
+- fix: security - upgrade handlebars, source-map-js by @jaredwray in #236
+- mono - chore: upgrade TypeScript and build tooling by @jaredwray in #237
+- mono - chore: upgrade monorepo tooling by @jaredwray in #238
+- mono - chore: upgrade GitHub Actions by @jaredwray in #239
+- mono - chore: upgrade Dev Container images by @jaredwray in #240
+- mono - chore: upgrade Fastify dependencies by @jaredwray in #241
+- mono - chore: upgrade hookified by @jaredwray in #242
+- mono - chore: upgrade pino and pino-pretty by @jaredwray in #243
+- mono - chore: upgrade Docker Node.js runtime image by @jaredwray in #244
+- mono - chore: pin the Compose image by @jaredwray in #245
+- Store request bins in Keyv by @jaredwray in #246
+- Store Worker request bins in MongoDB Atlas by @jaredwray in #247
+
+**Full diff:** [https://github.com/jaredwray/mockhttp/compare/v2.1.0...v3.0.0](https://github.com/jaredwray/mockhttp/compare/v2.1.0...v3.0.0)
+
 ### v2.1.0
 URL: https://mockhttp.org/changelog/v2-1-0
 Date: October 3, 2026
@@ -7615,26 +8044,3 @@ Tag: Release
 
 ## What's Changed
 * Adding in docker description and CORS for allowing logo.svg access
-
-### v0.2.1
-URL: https://mockhttp.org/changelog/v0-2-1
-Date: December 13, 2024
-Tag: Release
-
-## What's Changed
-* moving to logging on a single line by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/15](https://github.com/jaredwray/mockhttp/pull/15)
-* upgrading scalar to 1.25.82 by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/16](https://github.com/jaredwray/mockhttp/pull/16)
-
-
-**Full Changelog**: [https://github.com/jaredwray/mockhttp/compare/v0.2.0...v0.2.1](https://github.com/jaredwray/mockhttp/compare/v0.2.0...v0.2.1)
-
-### v0.2.0
-URL: https://mockhttp.org/changelog/v0-2-0
-Date: December 13, 2024
-Tag: Release
-
-## What's Changed
-* response inspection by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/14](https://github.com/jaredwray/mockhttp/pull/14)
-
-
-**Full Changelog**: [https://github.com/jaredwray/mockhttp/compare/v0.1.0...v0.2.0](https://github.com/jaredwray/mockhttp/compare/v0.1.0...v0.2.0)