@jaredwray/mockhttp 2.0.0 → 3.0.0

package/site/dist/llms-full.txt

@@ -28,7 +28,7 @@ A simple HTTP server for mocking responses in tests. Inspired by [httpbin](https
 - [Bins](/docs/bins/) — capture and inspect incoming HTTP requests (great for webhook debugging)
 - `@fastify/helmet` built in by default
 - Built with Node.js, TypeScript, and Fastify
-- Deploy via Docker or Node.js
+- Run it in Node.js, or deploy with [Docker](/docs/how-to-deploy/docker/), [Cloudflare Workers](/docs/how-to-deploy/cloudflare/), or [Wasmer Edge](/docs/how-to-deploy/wasmer/)
 - Free hosted service at [mockhttp.org](https://mockhttp.org), running on Cloudflare
 - Documentation site and interactive [OpenAPI reference](/api/)
 - Auto-detect the next port that is not in use
@@ -78,6 +78,8 @@ console.log(response);
 await mock.close(); // stop the server
 ```
 
+Step-by-step deploy guides: [Docker](/docs/how-to-deploy/docker/), [Cloudflare](/docs/how-to-deploy/cloudflare/), and [Wasmer](/docs/how-to-deploy/wasmer/).
+
 ### HTTPS and HTTP/2
 URL: https://mockhttp.org/docs/https/
 
@@ -615,13 +617,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();
 ```
 
@@ -661,8 +663,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';
@@ -671,13 +672,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) {
@@ -685,8 +686,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
@@ -707,14 +708,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({
@@ -735,18 +736,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();
@@ -756,44 +756,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/
 
@@ -1015,7 +1011,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)
@@ -1044,7 +1039,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
@@ -1053,7 +1047,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
 
@@ -1133,57 +1127,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`
 
@@ -1241,15 +1233,216 @@ A getter that returns whether there are any active injections.
 
 **Returns:** boolean - `true` if there are active injections, `false` otherwise
 
-### Hosted Service
+### MockHttp.org Live
 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](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](/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).
 
 Getting Started is served at `/` and `/docs`, other guides at `/docs/...`, and the interactive HTTP API reference at `/api`. Mock endpoints such as `/get` and `/post` are unchanged.
 
+### Cloudflare
+URL: https://mockhttp.org/docs/how-to-deploy/cloudflare/
+Description: Deploy MockHTTP as a Cloudflare Worker. Workers Assets serve the docs site, and the Worker handles mock API routes.
+
+# Deploy on Cloudflare
+
+MockHTTP runs on Cloudflare as a Worker, not a container. [mockhttp.org](https://mockhttp.org) is this deployment: [Workers Assets](https://developers.cloudflare.com/workers/static-assets/) serve the documentation site, and the Worker handles mock APIs such as `/get` and `/post`.
+
+The Worker entry is [`worker/index.ts`](https://github.com/jaredwray/mockhttp/blob/main/worker/index.ts). It listens with the Node.js compatibility layer and forwards each request into the Fastify app. Configuration lives in [`wrangler.jsonc`](https://github.com/jaredwray/mockhttp/blob/main/wrangler.jsonc).
+
+## What the Worker does differently
+
+The Worker starts the same MockHTTP app as Node.js, with a few options set for the Workers runtime:
+
+| Option | Worker value | Why |
+| --- | --- | --- |
+| `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. |
+| `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.
+
+Taps are a library API (`mock.taps.inject`). They have no HTTP routes, so a deployed Worker has no way to inject one.
+
+Assets are checked before the Worker. A file under `site/dist` (the docs site, favicon, logos) is served as a static asset. A path that is not a file, such as `/get` or `/post`, is handled by the Worker.
+
+## Deploy your own Worker
+
+You need a Cloudflare account and permission to deploy Workers. This repository pins Wrangler to `4.127.0`.
+
+Change `name` and `routes` in `wrangler.jsonc` before you deploy a fork. The route in this repo attaches the custom domain `mockhttp.org`. `workers_dev` is enabled, so a `*.workers.dev` hostname is available as well. Adjust the `RATE_LIMITER` binding if you want a different limit than 1000 requests per 60 seconds.
+
+Also change `siteUrl` in `site/docula.config.ts`. The sitemap is a static file, and this repo sets it to `https://mockhttp.org`. The `migrations` block records a container class that this Worker no longer uses. A brand-new Worker can omit that block.
+
+Wrangler bundles `worker/index.ts` from source, so you do not need `pnpm build` for this deploy. `pnpm website:build` produces `site/dist`.
+
+```bash
+pnpm install
+pnpm website:build
+pnpm prepare:worker-assets
+npx wrangler@4.127.0 deploy
+```
+
+`pnpm prepare:worker-assets` copies `public/` into `site/dist` so favicon and logo files ship with the docs site. Wrangler reads `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` from the environment when you are not logged in locally.
+
+After deploy, open the workers.dev hostname or your custom domain and request `/get`. The docs are at `/docs`, and the OpenAPI reference is at `/api`.
+
+## Deploy from GitHub Actions
+
+[`.github/workflows/deploy-site.yaml`](https://github.com/jaredwray/mockhttp/blob/main/.github/workflows/deploy-site.yaml) deploys this Worker on the `released` event (a published release, not a prerelease) and when the workflow is started by hand. The `production` environment provides `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`. The deploy job installs production dependencies, downloads the built site, copies `public/` into `site/dist`, installs Wrangler `4.127.0`, and runs `wrangler deploy`.
+
+That workflow does not deploy the [Wasmer](/docs/how-to-deploy/wasmer/) app. Docker image publishing is a separate workflow, documented in [Docker](/docs/how-to-deploy/docker/).
+
+### Docker
+URL: https://mockhttp.org/docs/how-to-deploy/docker/
+Description: Run MockHTTP from the jaredwray/mockhttp image, with Docker Compose, or by building the image from this repository.
+
+# Deploy with Docker
+
+The published image is [`jaredwray/mockhttp`](https://hub.docker.com/r/jaredwray/mockhttp) on Docker Hub. It runs the Node.js server and the documentation site in one container. The `latest` tag is `linux/amd64` only. Apple Silicon runs it under emulation. On arm64 Linux, build the image from this repository instead.
+
+## Run the image
+
+```bash
+docker run -d -p 3000:3000 jaredwray/mockhttp
+```
+
+The server listens on port 3000. Open `http://localhost:3000/get` for a mock response, `http://localhost:3000/docs` for these guides, and `http://localhost:3000/api` for the OpenAPI reference.
+
+`pnpm docker:run` is `docker run -p 3000:3000 jaredwray/mockhttp`. It stays in the foreground. Docker pulls the Hub image when it is not already local.
+
+Rate limiting is on: 1000 requests per minute. The allow list is only `127.0.0.1` and `::1`. A published port delivers traffic from the Docker bridge address, not from loopback inside the container, so those requests count against the limit. None of the environment variables below turn it off. Change or disable it with the library [`rateLimit` option](/docs/configuration/). A test suite that sends more than 1000 requests a minute to the published port will get `429` responses.
+
+## Docker Compose
+
+```yaml
+services:
+  mockhttp:
+    image: jaredwray/mockhttp:latest
+    ports:
+      - "3000:3000"
+```
+
+The Compose file in this repository publishes port 3001 and sets `PORT` so the process listens on that same port:
+
+```yaml
+services:
+  mockhttp:
+    image: jaredwray/mockhttp:latest
+    ports:
+      - "3001:3001"
+    environment:
+      - PORT=3001
+```
+
+`pnpm docker:compose:up` and `pnpm docker:compose:down` call the `docker-compose` binary. Current Docker installs often provide `docker compose` instead, which you can run against the same file.
+
+## Environment variables
+
+The container starts `node dist/index.mjs`. That process reads these variables:
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `PORT` | `3000` | Port the server listens on. Match it to the published container port. |
+| `HOST` | `0.0.0.0` | Bind address. |
+| `LOGGING` | enabled | Set to `false` to turn logging off. |
+| `HTTP2` | off | Set to `true` to enable HTTP/2 cleartext (h2c). The image does not load a TLS certificate. |
+| `AUTO_DETECT_PORT` | `true` | Set to `false` to keep `PORT` even when that port is already in use. |
+
+HTTPS certificates are configured in the [library](/docs/https/), not through container environment variables. Put a TLS proxy in front of the container when you need HTTPS.
+
+## Build the image
+
+The [`Dockerfile`](https://github.com/jaredwray/mockhttp/blob/main/Dockerfile) copies `node_modules`, `package.json`, `public/`, `dist/`, and `site/dist/` from the build context. Build the package and the docs site before `docker build`.
+
+```bash
+pnpm install
+pnpm build
+pnpm website:build
+docker build -t jaredwray/mockhttp .
+docker run -d -p 3000:3000 jaredwray/mockhttp
+```
+
+`pnpm docker:build` is the `docker build` step. The image is based on Node.js 24 Alpine, runs as the `node` user, exposes port 3000, and starts `node dist/index.mjs`.
+
+## Publish to Docker Hub
+
+[`.github/workflows/docker-publish.yaml`](https://github.com/jaredwray/mockhttp/blob/main/.github/workflows/docker-publish.yaml) runs on the `released` event (a published release, not a prerelease) and when the workflow is started by hand. It builds `jaredwray/mockhttp:<version>` and `jaredwray/mockhttp:latest` with `docker build` on `ubuntu-latest`, pushes both tags, and updates the Docker Hub description from `DOCKER.md`. That build is `linux/amd64`.
+
+The same Node server can run on [Wasmer Edge](/docs/how-to-deploy/wasmer/). The public site at [mockhttp.org](https://mockhttp.org) is the [Cloudflare Worker](/docs/how-to-deploy/cloudflare/), not this image.
+
+### Wasmer
+URL: https://mockhttp.org/docs/how-to-deploy/wasmer/
+Description: Deploy the MockHTTP Node.js server to Wasmer Edge with app.yaml, Anybuild, and wasmer deploy.
+
+# Deploy on Wasmer
+
+Wasmer Edge runs the same Node.js server as [Docker](/docs/how-to-deploy/docker/). The test app for this repository is [mockhttp.wasmer.app](https://mockhttp.wasmer.app).
+
+This deploy does not publish the [Cloudflare Worker](/docs/how-to-deploy/cloudflare/). [mockhttp.org](https://mockhttp.org) stays on Cloudflare.
+
+## App configuration
+
+[`app.yaml`](https://github.com/jaredwray/mockhttp/blob/main/app.yaml) describes the Edge app:
+
+```yaml
+kind: wasmer.io/App.v0
+name: mockhttp
+owner: jaredwray
+package: .
+env:
+  HOST: "0.0.0.0"
+  LOGGING: "false"
+  AUTO_DETECT_PORT: "false"
+```
+
+`package: .` deploys the repository directory. `HOST` binds the server on all interfaces. Logging is off. Wasmer injects `PORT`. `AUTO_DETECT_PORT=false` keeps that port instead of scanning for another one.
+
+Change `name` and `owner` before you deploy your own app. The environment variables are the same ones the Docker image reads (`PORT`, `HOST`, `LOGGING`, `HTTP2`, and `AUTO_DETECT_PORT`). See [Docker](/docs/how-to-deploy/docker/) for what each one does.
+
+## Build with Anybuild
+
+[`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.12.1`
+- Build command: `pnpm run build && pnpm website:build`
+- Start command: `node dist/index.mjs`
+
+The build command produces `dist/` and `site/dist/` while Docula is still installed. Wasmer then prunes dev dependencies. The docs site has to exist before that prune, because Docula is a dev dependency.
+
+## Deploy from the CLI
+
+Install the [Wasmer CLI](https://docs.wasmer.io/install) and log in, then from the repository root:
+
+```bash
+wasmer deploy --build-remote
+```
+
+`--build-remote` uploads the source and runs the Anybuild file on Wasmer's builders. When the deploy finishes, the CLI prints the app URL.
+
+## Deploy from GitHub Actions
+
+[`.github/workflows/deploy-wasmer.yaml`](https://github.com/jaredwray/mockhttp/blob/main/.github/workflows/deploy-wasmer.yaml) runs on the `released` event (a published release, not a prerelease) and when the workflow is started by hand. The `wasmer` environment provides `WASMER_TOKEN`. The deploy step runs:
+
+```bash
+wasmer deploy --non-interactive --build-remote
+```
+
+## Runtime behavior
+
+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).
+
+The process listens with HTTP. Wasmer terminates TLS for the `*.wasmer.app` hostname.
+
 ## API Reference
 URL: https://mockhttp.org/api
 
@@ -1260,7 +1453,7 @@ 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.0.0"
+    "version": "3.0.0"
   },
   "components": {
     "schemas": {}
@@ -1394,7 +1587,11 @@ OpenAPI Spec Source: /home/runner/work/mockhttp/mockhttp/site/api/swagger.json
                           "type": "string"
                         },
                         {
-                          "type": "null"
+                          "type": "object",
+                          "nullable": true,
+                          "enum": [
+                            null
+                          ]
                         }
                       ]
                     }
@@ -5636,10 +5833,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",
@@ -5806,10 +6001,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",
@@ -6746,6 +6939,124 @@ OpenAPI Spec Source: /home/runner/work/mockhttp/mockhttp/site/api/swagger.json
 ## Changelog
 URL: https://mockhttp.org/changelog
 
+### 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
+Tag: Release
+
+## @jaredwray/mockhttp@2.1.0 — 2026-10-03
+
+Add AUTO_DETECT_PORT=false so the process keeps PORT, and include the docs site in the npm package.
+
+### Features
+- Deploy the Node server to Wasmer Edge (#225)
+
+  ```bash
+  PORT=3000 AUTO_DETECT_PORT=false node dist/index.mjs
+  ```
+
+### Bug Fixes
+- include Docula site in the npm tarball (#222)
+- deploy Wasmer with a remote build (#226)
+- deploy Wasmer through the Anybuild file (#228)
+
+### Documentation
+- add Drydock review badge to README (#224)
+- rename Hosted Service page to MockHttp.org Live (#230)
+- add How to Deploy guides for Cloudflare, Docker, and Wasmer (#229)
+
+### Internal
+- root - defense - close catalog gaps from current skill (#221)
+- Publish the GitHub Actions build to Wasmer (#227)
+
+### Contributors
+- @jaredwray (owner)
+
+### Full List of Changes
+- root - chore: defense - close catalog gaps from current skill by @jaredwray in #221
+- fix: include Docula site in the npm tarball by @jaredwray in #222
+- docs: add Drydock review badge to README by @jaredwray in #224
+- Deploy the Node server to Wasmer Edge by @jaredwray in #225
+- Fix the Wasmer deploy by using a remote build by @jaredwray in #226
+- Publish the GitHub Actions build to Wasmer by @jaredwray in #227
+- Deploy Wasmer with the Anybuild file by @jaredwray in #228
+- docs: rename Hosted Service to MockHttp.org Live by @jaredwray in #230
+- docs: add How to Deploy guides for Cloudflare, Docker, and Wasmer by @jaredwray in #229
+
+**Full diff:** [https://github.com/jaredwray/mockhttp/compare/v2.0.0...v2.1.0](https://github.com/jaredwray/mockhttp/compare/v2.0.0...v2.1.0)
+
 ### v2.0.0
 URL: https://mockhttp.org/changelog/v2-0-0
 Date: September 18, 2026
@@ -7377,39 +7688,3 @@ Tag: Release
 
 
 **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)
-
-### v0.1.0
-URL: https://mockhttp.org/changelog/v0-1-0
-Date: December 12, 2024
-Tag: Release
-
-## What's Changed
-* adding in contributing and code of conduct by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/1](https://github.com/jaredwray/mockhttp/pull/1)
-* migrating to correct folder format by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/2](https://github.com/jaredwray/mockhttp/pull/2)
-* adding in logo and favicon by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/3](https://github.com/jaredwray/mockhttp/pull/3)
-* adding in headers and user-agent endpoints by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/4](https://github.com/jaredwray/mockhttp/pull/4)
-* moving to scalar by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/5](https://github.com/jaredwray/mockhttp/pull/5)
-* adding in status codes by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/6](https://github.com/jaredwray/mockhttp/pull/6)
-* adding in unit tests and workflows by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/7](https://github.com/jaredwray/mockhttp/pull/7)
-* fixing the title that had an extra space by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/8](https://github.com/jaredwray/mockhttp/pull/8)
-* moving to scalar locally instead of via CDN by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/9](https://github.com/jaredwray/mockhttp/pull/9)
-* adding in dynamic version from package.json by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/10](https://github.com/jaredwray/mockhttp/pull/10)
-* adding in fastify helmet by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/11](https://github.com/jaredwray/mockhttp/pull/11)
-* upgrading xo to 0.60.0 by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/12](https://github.com/jaredwray/mockhttp/pull/12)
-* updating build to tsup and upgrading vitest by @jaredwray in [https://github.com/jaredwray/mockhttp/pull/13](https://github.com/jaredwray/mockhttp/pull/13)
-
-## New Contributors
-* @jaredwray made their first contribution in [https://github.com/jaredwray/mockhttp/pull/1](https://github.com/jaredwray/mockhttp/pull/1)
-
-**Full Changelog**: [https://github.com/jaredwray/mockhttp/commits/v0.1.0](https://github.com/jaredwray/mockhttp/commits/v0.1.0)