@crvouga/mockingbird-adapter-node 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# @crvouga/mockingbird-adapter-node
+
+Serve any Mockingbird `FetchAPI` (a provider mock such as `StripeAPI`, or your own) as a real HTTP
+server over `node:http`. Use it when the code under test needs a URL (a subprocess, a browser, an
+SDK you cannot hand a `fetch`). If you can inject `fetch`, call the mock's `fetch` directly instead;
+on Bun, `@crvouga/mockingbird-adapter-bun` is lighter.
+
+## Install
+
+```bash
+npm install @crvouga/mockingbird-adapter-node
+```
+
+Requires Node >=22 (also runs on Bun, which implements `node:http`). ESM only.
+
+## Usage
+
+```ts
+import type { AddressInfo } from "node:net"
+import { serve } from "@crvouga/mockingbird-adapter-node"
+import type { FetchAPI } from "@crvouga/mockingbird-core"
+
+// Any FetchAPI works, e.g. `new StripeAPI()` from @crvouga/mockingbird-service-stripe.
+const api: FetchAPI = {
+  fetch: async (request) =>
+    Response.json({ method: request.method, url: request.url, body: await request.text() }),
+}
+
+// Port defaults to 0: the OS picks a free port.
+const server = await serve(api, { host: "127.0.0.1" })
+const { port } = server.address() as AddressInfo
+const baseUrl = `http://127.0.0.1:${port}`
+
+const response = await fetch(`${baseUrl}/v1/customers`, { method: "POST", body: "email=a@b.c" })
+console.log(await response.json())
+
+// Tear down (e.g. in afterAll). closeAllConnections drops keep-alive sockets so the process exits.
+server.close()
+server.closeAllConnections()
+```
+
+## API
+
+| Export | Signature | Description |
+| --- | --- | --- |
+| `serve` | `(api: FetchAPI, options?: NodeServeOptions) => Promise<http.Server>` | Start listening; resolves once bound, rejects on listen errors (e.g. `EADDRINUSE`). |
+
+Types:
+
+- `NodeServeOptions`: `{ port?: number; host?: string }`. `port` defaults to `0` (ephemeral; read it
+  from `server.address()`); `host` is passed to `server.listen` (Node's default when omitted).
+
+Behavior:
+
+- Each incoming request is buffered and converted to a Fetch `Request`. The URL is built from the
+  `Host` header; leading repeated slashes in the path collapse to one.
+- The body is forwarded only for methods other than `GET`/`HEAD`, and only when non-empty.
+- The `Response` status, headers and body are written back in full (no streaming). Repeated
+  `Set-Cookie` headers are preserved, one header line per cookie.
+- Errors thrown by `api.fetch` are not caught by the adapter; return error responses from your
+  `FetchAPI` instead.
+
+## Related
+
+- `@crvouga/mockingbird-core`: the `FetchAPI` contract.
+- `@crvouga/mockingbird-adapter-bun`: the same adapter for `Bun.serve`.
+
+Part of [mockingbird](https://github.com/crvouga/mockingbird) — agent integration guide: [`@crvouga/mockingbird`](https://github.com/crvouga/mockingbird/tree/main/packages/facade#readme).

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import type { FetchAPI } from "@crvouga/mockingbird-core";
+/** Options for {@link serve}. */
+export type NodeServeOptions = {
+    port?: number;
+    host?: string;
+};
+/**
+ * Serve any Mockingbird {@link FetchAPI} over `node:http`.
+ * Port defaults to `0`, so the OS assigns an ephemeral port (read from `server.address()`).
+ */
+export declare const serve: (api: FetchAPI, options?: NodeServeOptions) => Promise<import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAA;AAEzD,iCAAiC;AACjC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,GAAU,KAAK,QAAQ,EAAE,UAAS,gBAAqB,gHA+BxE,CAAA"}

package/dist/index.js

@@ -0,0 +1,39 @@
+import { createServer } from "node:http";
+/**
+ * Serve any Mockingbird {@link FetchAPI} over `node:http`.
+ * Port defaults to `0`, so the OS assigns an ephemeral port (read from `server.address()`).
+ */
+export const serve = async (api, options = {}) => {
+    const server = createServer(async (req, res) => {
+        const chunks = [];
+        for await (const chunk of req) {
+            chunks.push(Buffer.from(chunk));
+        }
+        const body = Buffer.concat(chunks);
+        const address = server.address();
+        const port = typeof address === "object" && address !== null ? address.port : undefined;
+        const base = `http://${req.headers.host ?? `localhost:${port ?? 80}`}`;
+        const raw = req.url ?? "/";
+        const url = new URL(raw.replace(/^\/+/, "/"), base);
+        const method = req.method ?? "GET";
+        const init = { method, headers: req.headers };
+        if (method !== "GET" && method !== "HEAD" && body.length > 0) {
+            init.body = body;
+        }
+        const request = new Request(url, init);
+        const response = await api.fetch(request);
+        // Headers#entries() joins repeated headers; Set-Cookie must stay one header per cookie.
+        const headers = Object.fromEntries(response.headers);
+        const cookies = response.headers.getSetCookie();
+        if (cookies.length > 0)
+            headers["set-cookie"] = cookies;
+        res.writeHead(response.status, headers);
+        res.end(Buffer.from(await response.arrayBuffer()));
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port ?? 0, options.host, resolve);
+    });
+    return server;
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AASxC;;;GAGG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,KAAK,EAAE,GAAa,EAAE,UAA4B,EAAE,EAAE,EAAE;IAC3E,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC7C,MAAM,MAAM,GAAa,EAAE,CAAA;QAC3B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;QACjC,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAClC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAA;QAChC,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;QACvF,MAAM,IAAI,GAAG,UAAU,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,aAAa,IAAI,IAAI,EAAE,EAAE,EAAE,CAAA;QACtE,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,GAAG,CAAA;QAC1B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,CAAC,CAAA;QACnD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,KAAK,CAAA;QAClC,MAAM,IAAI,GAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,OAAiC,EAAE,CAAA;QACpF,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7D,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAClB,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;QACtC,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QACzC,wFAAwF;QACxF,MAAM,OAAO,GAAsC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;QACvF,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,CAAA;QAC/C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,CAAC,YAAY,CAAC,GAAG,OAAO,CAAA;QACvD,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACvC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAA;IACpD,CAAC,CAAC,CAAA;IACF,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAC5B,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACzD,CAAC,CAAC,CAAA;IACF,OAAO,MAAM,CAAA;AACf,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@crvouga/mockingbird-adapter-node",
+  "version": "0.1.0",
+  "description": "Serve any Mockingbird FetchAPI over node:http.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crvouga/mockingbird.git",
+    "directory": "packages/adapters/node"
+  },
+  "homepage": "https://github.com/crvouga/mockingbird/tree/main/packages/adapters/node#readme",
+  "keywords": [
+    "mockingbird",
+    "adapter",
+    "node"
+  ],
+  "mockingbird": {
+    "runtime": "node",
+    "layer": "adapter"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome check .",
+    "test": "bun test",
+    "portability": "bun ../../../scripts/portability.ts",
+    "pack:check": "bun ../../../scripts/pack-check.ts"
+  },
+  "dependencies": {
+    "@crvouga/mockingbird-core": "0.0.0-development"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "fast-check": "4.9.0",
+    "@crvouga/mockingbird-testing": "0.1.0"
+  }
+}