@venn-lang/http 0.1.0

package/dist/node.d.mts

@@ -0,0 +1,63 @@
+//#region src/server/http-server.types.d.ts
+/** One request a server received, as the language sees it. */
+interface ServerRequest {
+  method: string;
+  /** The path with its query string, exactly as it arrived. */
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+}
+/** What a handler answers with. Every field has a sensible default. */
+interface ServerReply {
+  status?: number;
+  headers?: Record<string, string>;
+  /** A string is sent as-is; anything else is sent as JSON. */
+  body?: unknown;
+}
+/** Called once per request. Returning nothing sends `204 No Content`. */
+type RequestHandler = (request: ServerRequest) => ServerReply | undefined | Promise<ServerReply | undefined>;
+/** A server that is listening, and how to stop it. */
+interface RunningServer {
+  /** The port it actually bound to. Asking for 0 gets one chosen for you. */
+  readonly port: number;
+  close(): Promise<void>;
+}
+/**
+ * Accepting requests over HTTP.
+ *
+ * Two implementations: `createNodeServer` binds a real socket, and
+ * `createMemoryServer` keeps the handler in memory so a test can deliver a
+ * request without a network. The conformance suite is what says they agree.
+ */
+interface HttpServer {
+  listen(args: {
+    port: number;
+    host?: string;
+    handle: RequestHandler;
+  }): Promise<RunningServer>;
+}
+//#endregion
+//#region src/server/node-server.d.ts
+/** A node HttpServer, plus the way to hang up everything it still has open. */
+interface NodeHttpServer extends HttpServer {
+  /**
+   * Close every server started here that is still listening.
+   *
+   * A process owns its sockets, so whoever owns the process (the CLI) needs one
+   * call to give them all back on the way out.
+   */
+  closeAll(): Promise<void>;
+}
+/**
+ * The real implementation: a bound socket, on the port the OS gave it.
+ *
+ * Only this file reaches for `node:http`, which is why it sits behind the
+ * `@venn-lang/http/node` subpath. The rest of the package stays platform-neutral and
+ * runs wherever the language runs, the editor's worker included.
+ *
+ * @throws VN7020 if the port is taken, VN7021 if the socket refuses to bind.
+ */
+declare function createNodeServer(): NodeHttpServer;
+//#endregion
+export { type NodeHttpServer, createNodeServer };
+//# sourceMappingURL=node.d.mts.map

package/dist/node.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.mts","names":[],"sources":["../src/server/http-server.types.ts","../src/server/node-server.ts"],"mappings":";;UACiB;EACf;;EAEA;EACA,SAAS;EACT;;;UAIe;EACf;EACA,UAAU;;EAEV;;;KAIU,kBACV,SAAS,kBACN,0BAA0B,QAAQ;;UAGtB;;WAEN;EACT,SAAS;;;;;;;;;UAUM;EACf,OAAO;IAAQ;IAAc;IAAe,QAAQ;MAAmB,QAAQ;;;;;UC1BhE,uBAAuB;;;;;;;EAOtC,YAAY;;;;;;;;;;;iBAYE,oBAAoB"}

package/dist/node.mjs

@@ -0,0 +1,146 @@
+import { createServer } from "node:http";
+import { VennError } from "@venn-lang/contracts";
+//#region src/server/http-server.errors.ts
+/** VN7020: the address the flow asked for is already taken by something else. */
+function portInUse(args) {
+	return new VennError({
+		code: "VN7020",
+		message: `Port ${args.port} is already in use — stop whatever is listening on ${args.host}:${args.port}, or ask for "port: 0" to take any free one.`,
+		detail: {
+			port: args.port,
+			host: args.host,
+			cause: "EADDRINUSE"
+		}
+	});
+}
+/** VN7021: the socket refused to bind for any other reason. */
+function listenFailed(args) {
+	return new VennError({
+		code: "VN7021",
+		message: `Could not listen on ${args.host}:${args.port} — ${args.cause}.`,
+		detail: {
+			port: args.port,
+			host: args.host,
+			cause: args.cause
+		}
+	});
+}
+/**
+* Whatever the socket threw, as a Venn error: VN7020 for `EADDRINUSE`, VN7021
+* for anything else.
+*
+* The translation lives at the producer so no caller has to read a `node:net`
+* errno to know what went wrong.
+*/
+function asListenError(args) {
+	const error = args.error;
+	if (error?.code === "EADDRINUSE") return portInUse({
+		port: args.port,
+		host: args.host
+	});
+	return listenFailed({
+		port: args.port,
+		host: args.host,
+		cause: error?.message ?? String(args.error)
+	});
+}
+//#endregion
+//#region src/server/node-server.ts
+/**
+* The real implementation: a bound socket, on the port the OS gave it.
+*
+* Only this file reaches for `node:http`, which is why it sits behind the
+* `@venn-lang/http/node` subpath. The rest of the package stays platform-neutral and
+* runs wherever the language runs, the editor's worker included.
+*
+* @throws VN7020 if the port is taken, VN7021 if the socket refuses to bind.
+*/
+function createNodeServer() {
+	const open = /* @__PURE__ */ new Set();
+	return {
+		listen: async (args) => {
+			const server = await bind(args);
+			open.add(server);
+			return {
+				port: server.port,
+				close: () => forget(open, server)
+			};
+		},
+		closeAll: async () => {
+			for (const server of [...open]) await forget(open, server);
+		}
+	};
+}
+/** Closing is idempotent from the set's point of view: gone is gone. */
+async function forget(open, server) {
+	open.delete(server);
+	await server.close();
+}
+function bind(args) {
+	const { port, host, handle } = args;
+	return new Promise((resolve, reject) => {
+		const at = host ?? "127.0.0.1";
+		const server = createServer((request, response) => {
+			answer(request, response, handle);
+		});
+		server.once("error", (error) => reject(asListenError({
+			port,
+			host: at,
+			error
+		})));
+		server.listen(port, at, () => resolve(running(server)));
+	});
+}
+function running(server) {
+	const address = server.address();
+	return {
+		port: typeof address === "object" && address ? address.port : 0,
+		close: () => new Promise((resolve) => {
+			server.closeAllConnections?.();
+			server.close(() => resolve());
+		})
+	};
+}
+/** A handler that throws becomes a 500: one bad request must not kill the server. */
+async function answer(request, response, handle) {
+	try {
+		send(response, await handle(await read(request)) ?? { status: 204 });
+	} catch (error) {
+		send(response, {
+			status: 500,
+			body: { error: String(error?.message ?? error) }
+		});
+	}
+}
+function send(response, reply) {
+	const json = typeof reply.body !== "string" && reply.body !== void 0;
+	const headers = {
+		...json ? { "content-type": "application/json" } : {},
+		...reply.headers
+	};
+	response.writeHead(reply.status ?? 200, headers);
+	response.end(body(reply.body, json));
+}
+function body(value, json) {
+	if (value === void 0) return "";
+	return json ? JSON.stringify(value) : String(value);
+}
+async function read(request) {
+	const chunks = [];
+	for await (const chunk of request) chunks.push(chunk);
+	return {
+		method: request.method ?? "GET",
+		url: request.url ?? "/",
+		headers: plain(request.headers),
+		body: Buffer.concat(chunks).toString("utf8")
+	};
+}
+function plain(headers) {
+	const out = {};
+	for (const [key, value] of Object.entries(headers)) if (value !== void 0) out[key] = Array.isArray(value) ? value.join(", ") : value;
+	return out;
+}
+//#endregion
+export { createNodeServer };
+
+//# sourceMappingURL=node.mjs.map

package/dist/node.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.mjs","names":[],"sources":["../src/server/http-server.errors.ts","../src/server/node-server.ts"],"sourcesContent":["import { VennError } from \"@venn-lang/contracts\";\n\n/** VN7020: the address the flow asked for is already taken by something else. */\nexport function portInUse(args: { port: number; host: string }): VennError {\n  return new VennError({\n    code: \"VN7020\",\n    message: `Port ${args.port} is already in use — stop whatever is listening on ${args.host}:${args.port}, or ask for \"port: 0\" to take any free one.`,\n    detail: { port: args.port, host: args.host, cause: \"EADDRINUSE\" },\n  });\n}\n\n/** VN7021: the socket refused to bind for any other reason. */\nexport function listenFailed(args: { port: number; host: string; cause: string }): VennError {\n  return new VennError({\n    code: \"VN7021\",\n    message: `Could not listen on ${args.host}:${args.port} — ${args.cause}.`,\n    detail: { port: args.port, host: args.host, cause: args.cause },\n  });\n}\n\n/**\n * Whatever the socket threw, as a Venn error: VN7020 for `EADDRINUSE`, VN7021\n * for anything else.\n *\n * The translation lives at the producer so no caller has to read a `node:net`\n * errno to know what went wrong.\n */\nexport function asListenError(args: { port: number; host: string; error: unknown }): VennError {\n  const error = args.error as { code?: string; message?: string } | undefined;\n  if (error?.code === \"EADDRINUSE\") return portInUse({ port: args.port, host: args.host });\n  return listenFailed({\n    port: args.port,\n    host: args.host,\n    cause: error?.message ?? String(args.error),\n  });\n}\n","import { createServer, type IncomingMessage, type ServerResponse } from \"node:http\";\nimport { asListenError } from \"./http-server.errors.js\";\nimport type {\n  HttpServer,\n  RequestHandler,\n  RunningServer,\n  ServerReply,\n  ServerRequest,\n} from \"./http-server.types.js\";\n\n/** A node HttpServer, plus the way to hang up everything it still has open. */\nexport interface NodeHttpServer extends HttpServer {\n  /**\n   * Close every server started here that is still listening.\n   *\n   * A process owns its sockets, so whoever owns the process (the CLI) needs one\n   * call to give them all back on the way out.\n   */\n  closeAll(): Promise<void>;\n}\n\n/**\n * The real implementation: a bound socket, on the port the OS gave it.\n *\n * Only this file reaches for `node:http`, which is why it sits behind the\n * `@venn-lang/http/node` subpath. The rest of the package stays platform-neutral and\n * runs wherever the language runs, the editor's worker included.\n *\n * @throws VN7020 if the port is taken, VN7021 if the socket refuses to bind.\n */\nexport function createNodeServer(): NodeHttpServer {\n  const open = new Set<RunningServer>();\n  return {\n    listen: async (args) => {\n      const server = await bind(args);\n      open.add(server);\n      return { port: server.port, close: () => forget(open, server) };\n    },\n    closeAll: async () => {\n      for (const server of [...open]) await forget(open, server);\n    },\n  };\n}\n\n/** Closing is idempotent from the set's point of view: gone is gone. */\nasync function forget(open: Set<RunningServer>, server: RunningServer): Promise<void> {\n  open.delete(server);\n  await server.close();\n}\n\nfunction bind(args: {\n  port: number;\n  host?: string;\n  handle: RequestHandler;\n}): Promise<RunningServer> {\n  const { port, host, handle } = args;\n  return new Promise<RunningServer>((resolve, reject) => {\n    const at = host ?? \"127.0.0.1\";\n    const server = createServer((request, response) => {\n      void answer(request, response, handle);\n    });\n    // A busy port is the flow's problem, not a `node:net` errno: translate here.\n    server.once(\"error\", (error) => reject(asListenError({ port, host: at, error })));\n    server.listen(port, at, () => resolve(running(server)));\n  });\n}\n\nfunction running(server: ReturnType<typeof createServer>): RunningServer {\n  const address = server.address();\n  return {\n    port: typeof address === \"object\" && address ? address.port : 0,\n    close: () =>\n      new Promise<void>((resolve) => {\n        server.closeAllConnections?.();\n        server.close(() => resolve());\n      }),\n  };\n}\n\n/** A handler that throws becomes a 500: one bad request must not kill the server. */\nasync function answer(\n  request: IncomingMessage,\n  response: ServerResponse,\n  handle: RequestHandler,\n): Promise<void> {\n  try {\n    send(response, (await handle(await read(request))) ?? { status: 204 });\n  } catch (error) {\n    send(response, { status: 500, body: { error: String((error as Error)?.message ?? error) } });\n  }\n}\n\nfunction send(response: ServerResponse, reply: ServerReply): void {\n  const json = typeof reply.body !== \"string\" && reply.body !== undefined;\n  const headers = { ...(json ? { \"content-type\": \"application/json\" } : {}), ...reply.headers };\n  response.writeHead(reply.status ?? 200, headers);\n  response.end(body(reply.body, json));\n}\n\nfunction body(value: unknown, json: boolean): string {\n  if (value === undefined) return \"\";\n  return json ? JSON.stringify(value) : String(value);\n}\n\nasync function read(request: IncomingMessage): Promise<ServerRequest> {\n  const chunks: Buffer[] = [];\n  for await (const chunk of request) chunks.push(chunk as Buffer);\n  return {\n    method: request.method ?? \"GET\",\n    url: request.url ?? \"/\",\n    headers: plain(request.headers),\n    body: Buffer.concat(chunks).toString(\"utf8\"),\n  };\n}\n\nfunction plain(headers: IncomingMessage[\"headers\"]): Record<string, string> {\n  const out: Record<string, string> = {};\n  for (const [key, value] of Object.entries(headers)) {\n    if (value !== undefined) out[key] = Array.isArray(value) ? value.join(\", \") : value;\n  }\n  return out;\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@venn-lang/http",
+  "version": "0.1.0",
+  "description": "The http namespace: seven request verbs, a server, and the two ports they ride.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "http"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-http#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-http"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "development": "./src/node.ts",
+      "types": "./dist/node.d.mts",
+      "import": "./dist/node.mjs",
+      "default": "./dist/node.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@venn-lang/sdk": "0.1.0",
+    "@venn-lang/types": "0.1.0",
+    "@venn-lang/contracts": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "@types/node": "^24"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions/build-request.ts

@@ -0,0 +1,110 @@
+import type { HttpRequest } from "../port/index.js";
+import type { RequestParams } from "./request.types.js";
+
+interface Payload {
+  body?: string;
+  contentType?: string;
+}
+
+export interface BuildArgs {
+  method: string;
+  url: unknown;
+  params: RequestParams;
+  baseUrl: unknown;
+  signal?: AbortSignal;
+}
+
+/** Turn one action call into the request the HttpClient port sends. */
+export function buildRequest(args: BuildArgs): HttpRequest {
+  const payload = bodyOf(args.params);
+  return {
+    method: args.method,
+    url: withQuery(absoluteUrl(String(args.url ?? ""), args.baseUrl), args.params.query),
+    headers: headersOf(args.params, payload.contentType),
+    body: payload.body,
+    signal: args.signal,
+  };
+}
+
+const BOUNDARY = "----vennFormBoundary";
+
+/** A map means JSON and a string means raw, unless `encode` says otherwise. */
+function bodyOf(params: RequestParams): Payload {
+  if (params.body === undefined) return {};
+  switch (params.encode ?? defaultEncoding(params.body)) {
+    case "raw":
+      return { body: String(params.body) };
+    case "form":
+      return { body: encode(asMap(params.body)), contentType: FORM_TYPE };
+    case "multipart":
+      return multipart(asMap(params.body));
+    default:
+      return { body: JSON.stringify(params.body), contentType: "application/json" };
+  }
+}
+
+function defaultEncoding(body: unknown): string {
+  return typeof body === "string" ? "raw" : "json";
+}
+
+const FORM_TYPE = "application/x-www-form-urlencoded";
+
+function multipart(values: Record<string, string | number | boolean>): Payload {
+  const parts = Object.entries(values).map(
+    ([key, value]) =>
+      `--${BOUNDARY}\r\nContent-Disposition: form-data; name="${key}"\r\n\r\n${value}\r\n`,
+  );
+  return {
+    body: `${parts.join("")}--${BOUNDARY}--\r\n`,
+    contentType: `multipart/form-data; boundary=${BOUNDARY}`,
+  };
+}
+
+function asMap(body: unknown): Record<string, string | number | boolean> {
+  return (body ?? {}) as Record<string, string | number | boolean>;
+}
+
+function headersOf(params: RequestParams, contentType: string | undefined): Record<string, string> {
+  const headers: Record<string, string> = {};
+  for (const [key, value] of Object.entries(params.headers ?? {})) headers[key] = String(value);
+  if (contentType && !hasHeader(headers, "content-type")) headers["Content-Type"] = contentType;
+  const auth = authorization(params);
+  if (auth && !hasHeader(headers, "authorization")) headers.Authorization = auth;
+  return headers;
+}
+
+function authorization(params: RequestParams): string | undefined {
+  if (params.bearer) return `Bearer ${params.bearer}`;
+  if (!params.basic) return undefined;
+  return `Basic ${base64(`${params.basic.user}:${params.basic.pass}`)}`;
+}
+
+function withQuery(url: string, query: RequestParams["query"]): string {
+  const encoded = query ? encode(query) : "";
+  if (!encoded) return url;
+  return `${url}${url.includes("?") ? "&" : "?"}${encoded}`;
+}
+
+function encode(values: Record<string, string | number | boolean>): string {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(values)) search.append(key, String(value));
+  return search.toString();
+}
+
+function hasHeader(headers: Record<string, string>, name: string): boolean {
+  return Object.keys(headers).some((key) => key.toLowerCase() === name);
+}
+
+function base64(text: string): string {
+  return btoa(text);
+}
+
+/** Resolve a relative path against `config.baseUrl`; absolute URLs pass through. */
+function absoluteUrl(url: string, baseUrl: unknown): string {
+  if (typeof baseUrl !== "string" || baseUrl === "" || hasScheme(url)) return url;
+  return `${baseUrl.replace(/\/+$/, "")}/${url.replace(/^\/+/, "")}`;
+}
+
+function hasScheme(url: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(url);
+}

package/src/actions/http-action.ts

@@ -0,0 +1,36 @@
+import { type ActionDefinition, arg, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { HttpClientPort } from "../port/index.js";
+import { buildRequest } from "./build-request.js";
+import type { RequestParams } from "./request.types.js";
+import { requestParams } from "./request-params.js";
+
+/**
+ * Build the action for one HTTP verb.
+ *
+ * Every verb has the same shape: the URL is the single positional argument and
+ * everything else rides in the options map, so `http.get` and `http.post` read
+ * alike at the call site.
+ *
+ * @param config.name The verb as a flow writes it, such as `get`.
+ * @param config.method The method put on the wire, such as `GET`.
+ */
+export function httpAction(config: { name: string; method: string }): ActionDefinition {
+  return defineAction({
+    name: config.name,
+    doc: `HTTP ${config.method} request.`,
+    params: requestParams.optional(),
+    args: [arg("url", t.string, "Where to send it. Relative paths join the configured base URL.")],
+    result: t.ref("http.Response"),
+    run: (ctx, input) =>
+      ctx.port(HttpClientPort).request(
+        buildRequest({
+          method: config.method,
+          url: input.args[0],
+          params: (input.params ?? {}) as RequestParams,
+          baseUrl: ctx.config.baseUrl,
+          signal: ctx.signal,
+        }),
+      ),
+  });
+}

package/src/actions/index.ts

@@ -0,0 +1,18 @@
+import type { ActionDefinition } from "@venn-lang/sdk";
+import { onAction } from "../server/on-action.js";
+import { serveAction } from "../server/serve-action.js";
+import { httpAction } from "./http-action.js";
+
+/** The http namespace's verbs. Adding one is a single line here. */
+export const httpActions: ActionDefinition[] = [
+  httpAction({ name: "get", method: "GET" }),
+  httpAction({ name: "post", method: "POST" }),
+  httpAction({ name: "put", method: "PUT" }),
+  httpAction({ name: "patch", method: "PATCH" }),
+  httpAction({ name: "delete", method: "DELETE" }),
+  httpAction({ name: "head", method: "HEAD" }),
+  httpAction({ name: "options", method: "OPTIONS" }),
+  // Serving, not requesting: a server stays, and the requests arrive later.
+  serveAction(),
+  onAction(),
+];

package/src/actions/request-params.ts

@@ -0,0 +1,32 @@
+import { type ZodType, z } from "@venn-lang/sdk";
+import type { RequestParams } from "./request.types.js";
+
+const scalar = z.union([z.string(), z.number(), z.boolean()]);
+const scalarMap = z.record(z.string(), scalar);
+
+/**
+ * Validation for {@link RequestParams}, the options map every http verb accepts.
+ *
+ * Each key carries its own `.describe()` because the editor reads this schema to
+ * offer the keys, document them and reject the ones that do not exist. Keeping
+ * the wording here keeps it beside the rule it describes.
+ */
+export const requestParams: ZodType<RequestParams> = z.object({
+  headers: scalarMap
+    .optional()
+    .describe("Extra headers. Anything you set here wins over what Venn would infer."),
+  query: scalarMap.optional().describe("Appended to the URL as a query string, encoded for you."),
+  body: z
+    .unknown()
+    .optional()
+    .describe("What to send. A map becomes JSON; a string is sent as written."),
+  encode: z
+    .enum(["json", "form", "multipart", "raw"])
+    .optional()
+    .describe("How to serialise `body`. Defaults to `json` for a map, `raw` for a string."),
+  bearer: z.string().optional().describe("Shorthand for `Authorization: Bearer …`."),
+  basic: z
+    .object({ user: z.string(), pass: z.string() })
+    .optional()
+    .describe("Shorthand for HTTP basic auth."),
+});

package/src/actions/request.types.ts

@@ -0,0 +1,28 @@
+/** A value that may appear in a header, a query string or a form field. */
+export type Scalar = string | number | boolean;
+
+/** How `body` is put on the wire. */
+export type Encoding = "json" | "form" | "multipart" | "raw";
+
+/**
+ * Everything a request may carry. One map keeps the call site flat:
+ * `http.post "/token" { body: { … }, encode: "form", bearer: token }`.
+ *
+ * There is a single payload key, `body`, as `fetch` and `axios` have. Separate
+ * `json:` and `form:` keys would make one idea look like two; the wire format is
+ * {@link Encoding}'s job instead.
+ */
+export interface RequestParams {
+  /** Extra headers. Anything set here wins over what Venn would infer. */
+  headers?: Record<string, Scalar>;
+  /** Appended as a query string, encoded for you. */
+  query?: Record<string, Scalar>;
+  /** What to send. A map becomes JSON; a string is sent as written. */
+  body?: unknown;
+  /** Override the serialisation of {@link body}. */
+  encode?: Encoding;
+  /** Shorthand for `Authorization: Bearer …`. */
+  bearer?: string;
+  /** Shorthand for HTTP basic auth. */
+  basic?: { user: string; pass: string };
+}

package/src/clients/fake-client.ts

@@ -0,0 +1,37 @@
+import type { HttpClient, HttpResponse } from "../port/index.js";
+
+/**
+ * A 200 response with a small JSON body, for tests that only care about a field
+ * or two.
+ *
+ * @param overrides Fields to replace on the default response.
+ * @returns A complete {@link HttpResponse}.
+ */
+export function okResponse(overrides: Partial<HttpResponse> = {}): HttpResponse {
+  return {
+    status: 200,
+    ok: true,
+    headers: {},
+    body: '{"ok":true}',
+    json: { ok: true },
+    time: 0,
+    ...overrides,
+  };
+}
+
+/**
+ * The double: answers from a table keyed by the request's full URL.
+ *
+ * A URL with no entry gets {@link okResponse}, so a test only has to name the
+ * responses it cares about. Never touches the network.
+ *
+ * @param args.responses Canned responses, keyed by the URL the flow requests.
+ */
+export function createFakeClient(
+  args: { responses?: Record<string, HttpResponse> } = {},
+): HttpClient {
+  const responses = args.responses ?? {};
+  return {
+    request: async (req) => responses[req.url] ?? okResponse(),
+  };
+}

package/src/clients/fetch-client.ts

@@ -0,0 +1,59 @@
+import type { HttpClient, HttpResponse } from "../port/index.js";
+
+/**
+ * The real client, over the global `fetch`. Requires the `net` capability.
+ *
+ * The body is always read as text and parsed afterwards, so a reply that claims
+ * JSON but is not still arrives whole in `body` instead of throwing.
+ */
+export function createFetchClient(): HttpClient {
+  return {
+    async request(req): Promise<HttpResponse> {
+      const response = await fetch(req.url, {
+        method: req.method,
+        headers: req.headers,
+        body: req.body,
+        signal: req.signal,
+      });
+      const body = await response.text();
+      return mapResponse({
+        status: response.status,
+        ok: response.ok,
+        headers: response.headers,
+        body,
+      });
+    },
+  };
+}
+
+function mapResponse(args: {
+  status: number;
+  ok: boolean;
+  headers: Headers;
+  body: string;
+}): HttpResponse {
+  return {
+    status: args.status,
+    ok: args.ok,
+    headers: toObject(args.headers),
+    body: args.body,
+    json: tryJson(args.body),
+    time: 0,
+  };
+}
+
+function toObject(headers: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    out[key] = value;
+  });
+  return out;
+}
+
+function tryJson(body: string): unknown {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return undefined;
+  }
+}

package/src/clients/index.ts

@@ -0,0 +1,2 @@
+export { createFakeClient, okResponse } from "./fake-client.js";
+export { createFetchClient } from "./fetch-client.js";

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * The `http` plugin: request verbs, a server, and the types they trade in.
+ *
+ * Every byte on the wire crosses the `HttpClient` or `HttpServer` port, so a
+ * flow runs unchanged against a real socket or against the in-memory double.
+ */
+
+export * from "./clients/index.js";
+export { httpPlugin, httpPlugin as default } from "./plugin.js";
+export * from "./port/index.js";
+export * from "./server/index.js";

package/src/matchers/header.ts

@@ -0,0 +1,29 @@
+import { arg, defineMatcher, type MatcherDefinition, optionalArg } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+
+/**
+ * `expect res header "content-type"`: passes if the response carries the header.
+ *
+ * The lookup is case-insensitive, because header casing is whatever the far end
+ * happened to send.
+ */
+export const header: MatcherDefinition = defineMatcher({
+  name: "header",
+  args: [
+    arg("name", t.string, "Which header to read."),
+    optionalArg(
+      "value",
+      t.string,
+      "What it should say. Omit it to check the header is merely present.",
+    ),
+  ],
+  appliesTo: "Response",
+  test: ({ subject, args }) => hasHeader(subject, String(args[0])),
+  message: ({ args }) => `expected the response to carry header "${String(args[0])}"`,
+});
+
+function hasHeader(subject: unknown, name: string): boolean {
+  const headers = (subject as { headers?: Record<string, string> }).headers ?? {};
+  const target = name.toLowerCase();
+  return Object.keys(headers).some((key) => key.toLowerCase() === target);
+}

package/src/matchers/index.ts

@@ -0,0 +1,4 @@
+import type { MatcherDefinition } from "@venn-lang/sdk";
+import { header } from "./header.js";
+
+export const httpMatchers: MatcherDefinition[] = [header];