@venn-lang/http 0.1.0

package/src/node.ts

@@ -0,0 +1,6 @@
+/**
+ * The node-only corner of `@venn-lang/http`. Everything reachable from here touches
+ * `node:*`, which is why it sits behind its own subpath: the package's main
+ * entry stays platform-neutral and loads in a Web Worker.
+ */
+export { createNodeServer, type NodeHttpServer } from "./server/node-server.js";

package/src/plugin.ts

@@ -0,0 +1,22 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { httpActions } from "./actions/index.js";
+import { httpMatchers } from "./matchers/index.js";
+import { httpTypeDefs } from "./types.js";
+
+/**
+ * The `http` namespace: the request verbs, `http.serve`/`http.on`, the `header`
+ * matcher and the types they trade in.
+ *
+ * Requires the `net` capability, so a host without it refuses the plugin at load
+ * time rather than failing mid-flow. The compiler treats it exactly as it treats
+ * a third-party plugin.
+ */
+export const httpPlugin: PluginDefinition = definePlugin({
+  name: "venn/http",
+  version: "0.0.0",
+  namespace: "http",
+  requires: ["net"],
+  actions: httpActions,
+  matchers: httpMatchers,
+  typeDefs: httpTypeDefs,
+});

package/src/port/http-client.port.ts

@@ -0,0 +1,15 @@
+import type { Port } from "@venn-lang/contracts";
+import type { HttpClient } from "./http-client.types.js";
+
+/**
+ * The port descriptor an http verb resolves through `ctx.port(...)`.
+ *
+ * Declares the `net` capability, so a host that cannot open sockets refuses the
+ * binding at load time with a readable diagnostic.
+ */
+export const HttpClientPort: Port<HttpClient> = {
+  id: "venn.port.http-client",
+  version: 1,
+  requires: ["net"],
+  methods: ["request"],
+};

package/src/port/http-client.types.ts

@@ -0,0 +1,29 @@
+/** One request, ready to send: the verb, the absolute URL and the payload. */
+export interface HttpRequest {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: string;
+  /** Aborted when a `race` this request runs inside has already been won. */
+  signal?: AbortSignal;
+}
+
+/** What an http verb hands back, and what `res` holds in a flow. */
+export interface HttpResponse {
+  status: number;
+  ok: boolean;
+  headers: Record<string, string>;
+  body: string;
+  json: unknown;
+  time: number;
+}
+
+/**
+ * Sending one request and reading the reply.
+ *
+ * Two implementations: `createFetchClient` over a real socket and
+ * `createFakeClient` for tests. The conformance suite is what says they agree.
+ */
+export interface HttpClient {
+  request(req: HttpRequest): Promise<HttpResponse>;
+}

package/src/port/index.ts

@@ -0,0 +1,2 @@
+export { HttpClientPort } from "./http-client.port.js";
+export type { HttpClient, HttpRequest, HttpResponse } from "./http-client.types.js";

package/src/server/http-server.errors.ts

@@ -0,0 +1,36 @@
+import { VennError } from "@venn-lang/contracts";
+
+/** VN7020: the address the flow asked for is already taken by something else. */
+export function portInUse(args: { port: number; host: string }): VennError {
+  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. */
+export function listenFailed(args: { port: number; host: string; cause: string }): VennError {
+  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.
+ */
+export function asListenError(args: { port: number; host: string; error: unknown }): VennError {
+  const error = args.error as { code?: string; message?: string } | undefined;
+  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),
+  });
+}

package/src/server/http-server.port.ts

@@ -0,0 +1,15 @@
+import type { Port } from "@venn-lang/contracts";
+import type { HttpServer } from "./http-server.types.js";
+
+/**
+ * The port descriptor `http.serve` resolves through `ctx.port(...)`.
+ *
+ * Declares the `net` capability, so a host that cannot bind a socket refuses the
+ * binding at load time rather than mid-flow.
+ */
+export const HttpServerPort: Port<HttpServer> = {
+  id: "venn.port.http-server",
+  version: 1,
+  requires: ["net"],
+  methods: ["listen"],
+};

package/src/server/http-server.types.ts

@@ -0,0 +1,39 @@
+/** One request a server received, as the language sees it. */
+export 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. */
+export 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`. */
+export type RequestHandler = (
+  request: ServerRequest,
+) => ServerReply | undefined | Promise<ServerReply | undefined>;
+
+/** A server that is listening, and how to stop it. */
+export 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.
+ */
+export interface HttpServer {
+  listen(args: { port: number; host?: string; handle: RequestHandler }): Promise<RunningServer>;
+}

package/src/server/index.ts

@@ -0,0 +1,12 @@
+export { asListenError, listenFailed, portInUse } from "./http-server.errors.js";
+export { HttpServerPort } from "./http-server.port.js";
+export type {
+  HttpServer,
+  RequestHandler,
+  RunningServer,
+  ServerReply,
+  ServerRequest,
+} from "./http-server.types.js";
+export { createMemoryServer, type MemoryHttpServer, type MemoryServer } from "./memory-server.js";
+export { onAction } from "./on-action.js";
+export { type ServeHandle, serveAction } from "./serve-action.js";

package/src/server/memory-server.ts

@@ -0,0 +1,78 @@
+import { portInUse } from "./http-server.errors.js";
+import type {
+  HttpServer,
+  RequestHandler,
+  RunningServer,
+  ServerReply,
+  ServerRequest,
+} from "./http-server.types.js";
+
+/** Where the double starts handing out ports when a flow asks for any free one. */
+const EPHEMERAL_START = 49152;
+
+/** A server that is listening in memory, plus the way to knock on its door. */
+export interface MemoryServer extends RunningServer {
+  /** Deliver a request as though it had arrived over the network. */
+  deliver(request: Partial<ServerRequest>): Promise<ServerReply>;
+  readonly closed: boolean;
+}
+
+/** The double factory, which keeps every server it started so a test can find it. */
+export interface MemoryHttpServer extends HttpServer {
+  /** Every server started through this, newest last. */
+  readonly started: readonly MemoryServer[];
+}
+
+/**
+ * The double: no socket, no network, no waiting.
+ *
+ * A test starts the flow that serves, hands it a request and reads the reply,
+ * running the same handler the real server would call. Ports are book-kept here
+ * rather than by the operating system, so tests beside each other never collide.
+ */
+export function createMemoryServer(): MemoryHttpServer {
+  const started: MemoryServer[] = [];
+  const bound = new Set<number>();
+  let next = EPHEMERAL_START;
+  return {
+    started,
+    // Binding the same port twice must fail here exactly as it would against a
+    // real socket, so the double tracks what it has handed out.
+    listen: async ({ port, host, handle }) => {
+      const chosen = port === 0 ? next++ : port;
+      if (bound.has(chosen)) throw portInUse({ port: chosen, host: host ?? "127.0.0.1" });
+      bound.add(chosen);
+      const server = memoryServer({ port: chosen, handle, release: () => bound.delete(chosen) });
+      started.push(server);
+      return server;
+    },
+  };
+}
+
+function memoryServer(args: {
+  port: number;
+  handle: RequestHandler;
+  release: () => void;
+}): MemoryServer {
+  const state = { closed: false };
+  return {
+    port: args.port,
+    get closed() {
+      return state.closed;
+    },
+    close: async () => {
+      state.closed = true;
+      args.release();
+    },
+    deliver: async (request) => (await args.handle(fill(request))) ?? { status: 204 },
+  };
+}
+
+function fill(request: Partial<ServerRequest>): ServerRequest {
+  return {
+    method: request.method ?? "GET",
+    url: request.url ?? "/",
+    headers: request.headers ?? {},
+    body: request.body ?? "",
+  };
+}

package/src/server/node-server.ts

@@ -0,0 +1,122 @@
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { asListenError } from "./http-server.errors.js";
+import type {
+  HttpServer,
+  RequestHandler,
+  RunningServer,
+  ServerReply,
+  ServerRequest,
+} from "./http-server.types.js";
+
+/** A node HttpServer, plus the way to hang up everything it still has open. */
+export 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.
+ */
+export function createNodeServer(): NodeHttpServer {
+  const open = new Set<RunningServer>();
+  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: Set<RunningServer>, server: RunningServer): Promise<void> {
+  open.delete(server);
+  await server.close();
+}
+
+function bind(args: {
+  port: number;
+  host?: string;
+  handle: RequestHandler;
+}): Promise<RunningServer> {
+  const { port, host, handle } = args;
+  return new Promise<RunningServer>((resolve, reject) => {
+    const at = host ?? "127.0.0.1";
+    const server = createServer((request, response) => {
+      void answer(request, response, handle);
+    });
+    // A busy port is the flow's problem, not a `node:net` errno: translate here.
+    server.once("error", (error) => reject(asListenError({ port, host: at, error })));
+    server.listen(port, at, () => resolve(running(server)));
+  });
+}
+
+function running(server: ReturnType<typeof createServer>): RunningServer {
+  const address = server.address();
+  return {
+    port: typeof address === "object" && address ? address.port : 0,
+    close: () =>
+      new Promise<void>((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: IncomingMessage,
+  response: ServerResponse,
+  handle: RequestHandler,
+): Promise<void> {
+  try {
+    send(response, (await handle(await read(request))) ?? { status: 204 });
+  } catch (error) {
+    send(response, { status: 500, body: { error: String((error as Error)?.message ?? error) } });
+  }
+}
+
+function send(response: ServerResponse, reply: ServerReply): void {
+  const json = typeof reply.body !== "string" && reply.body !== undefined;
+  const headers = { ...(json ? { "content-type": "application/json" } : {}), ...reply.headers };
+  response.writeHead(reply.status ?? 200, headers);
+  response.end(body(reply.body, json));
+}
+
+function body(value: unknown, json: boolean): string {
+  if (value === undefined) return "";
+  return json ? JSON.stringify(value) : String(value);
+}
+
+async function read(request: IncomingMessage): Promise<ServerRequest> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of request) chunks.push(chunk as Buffer);
+  return {
+    method: request.method ?? "GET",
+    url: request.url ?? "/",
+    headers: plain(request.headers),
+    body: Buffer.concat(chunks).toString("utf8"),
+  };
+}
+
+function plain(headers: IncomingMessage["headers"]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (value !== undefined) out[key] = Array.isArray(value) ? value.join(", ") : value;
+  }
+  return out;
+}

package/src/server/on-action.ts

@@ -0,0 +1,42 @@
+import { type ActionDefinition, arg, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import type { ServeHandle } from "./serve-action.js";
+
+/**
+ * `http.on server handler`: say what the server answers with.
+ *
+ * The handler is an ordinary `fn`, so everything the language already does
+ * applies inside it: it can call any verb, and it waits for what it reaches for
+ * without saying so. Whatever it returns becomes the reply. Calling `http.on`
+ * again replaces the handler.
+ */
+export function onAction(): ActionDefinition {
+  return defineAction({
+    name: "on",
+    doc: "Answer this server's requests with a function. `fn (req) => { … }` is the reply.",
+    // The callback type is what gives `req` its shape, so `http.on api req => …`
+    // needs no annotation in the flow.
+    args: [
+      arg("server", t.ref("http.Server"), "The handle `http.serve` gave back."),
+      arg(
+        "handler",
+        t.callback([t.ref("http.Request")], t.dynamic, 1),
+        "Called for every request. What it returns is the reply.",
+      ),
+    ],
+    result: t.void,
+    run: (ctx, input) => {
+      const server = asServer(input.args[0]);
+      const handler = input.args[1];
+      if (!server) throw new Error("`http.on` needs a server, as `http.serve` returns.");
+      if (handler === undefined) throw new Error("`http.on` needs a function to answer with.");
+      server.onRequest((request) => ctx.invoke(handler, [request]));
+      return undefined;
+    },
+  });
+}
+
+function asServer(value: unknown): ServeHandle | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  return (value as ServeHandle).kind === "http-server" ? (value as ServeHandle) : undefined;
+}

package/src/server/serve-action.ts

@@ -0,0 +1,99 @@
+import { type ActionDefinition, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { HttpServerPort } from "./http-server.port.js";
+import type { ServerReply, ServerRequest } from "./http-server.types.js";
+
+const serveParams = z.object({
+  port: z.number().optional().describe("Which port to bind. 0 asks for any free one."),
+  host: z.string().optional().describe("Which interface to bind. Defaults to 127.0.0.1."),
+});
+
+/**
+ * The value `http.serve` hands back, seen by flows as `http.Server`.
+ *
+ * A server is not a request-response verb: it stays, and the requests arrive
+ * afterwards. So the verb returns something the program holds on to: the port it
+ * got, and what it may do with it.
+ */
+export interface ServeHandle {
+  kind: "http-server";
+  port: number;
+  /** Deliver one request to whatever `handle` was last given. Used by tests. */
+  deliver: (request: Partial<ServerRequest>) => Promise<ServerReply>;
+  close: () => Promise<void>;
+  /** Replace the handler. `http.on` is how a flow reaches this. */
+  onRequest: (handle: (request: ServerRequest) => unknown) => void;
+}
+
+/**
+ * `let api = http.serve { port: 8080 }`: start listening.
+ *
+ * The handler starts as a 404 and `http.on` replaces it, so a request arriving
+ * before the flow has said what to do with it gets an answer instead of hanging.
+ */
+export function serveAction(): ActionDefinition {
+  return defineAction({
+    name: "serve",
+    doc: "Start an HTTP server and hand back a handle. `http.on` says what to answer.",
+    params: serveParams.optional(),
+    result: t.ref("http.Server"),
+    run: async (ctx, input) => {
+      const params = (input.params ?? {}) as { port?: number; host?: string };
+      const state: HandlerState = { handle: notFound };
+      const running = await ctx.port(HttpServerPort).listen({
+        port: params.port ?? 0,
+        host: params.host,
+        handle: (request: ServerRequest) => state.handle(request),
+      });
+      return handle(running, state);
+    },
+  });
+}
+
+interface HandlerState {
+  handle: (request: ServerRequest) => ServerReply | Promise<ServerReply>;
+}
+
+function handle(
+  running: { port: number; close: () => Promise<void> },
+  state: HandlerState,
+): ServeHandle {
+  return {
+    kind: "http-server",
+    port: running.port,
+    close: () => running.close(),
+    deliver: async (request) => state.handle(fill(request)),
+    onRequest: (given) => {
+      state.handle = async (request) => asReply(await given(request));
+    },
+  };
+}
+
+/**
+ * Whatever the flow answered, as a reply. A map with a `status` is taken at its
+ * word; anything else is the body, so `=> { ok: true }` does the obvious thing.
+ */
+function asReply(value: unknown): ServerReply {
+  if (value === undefined || value === null) return { status: 204 };
+  if (isReplyShape(value)) return value as ServerReply;
+  return { status: 200, body: value };
+}
+
+function isReplyShape(value: unknown): boolean {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const shape = value as Record<string, unknown>;
+  return "status" in shape || "headers" in shape || "body" in shape;
+}
+
+function notFound(): ServerReply {
+  return { status: 404, body: { error: "This server has no handler yet." } };
+}
+
+function fill(request: Partial<ServerRequest>): ServerRequest {
+  return {
+    method: request.method ?? "GET",
+    url: request.url ?? "/",
+    headers: request.headers ?? {},
+    body: request.body ?? "",
+  };
+}

package/src/types.ts

@@ -0,0 +1,51 @@
+import { type TypeSpec, t } from "@venn-lang/types";
+
+/**
+ * The types the plugin publishes to flows: `http.Request`, `http.Reply`,
+ * `http.Server` and `http.Response`.
+ *
+ * They are data, not TypeScript, because the compiler and the editor read them
+ * without loading the plugin's implementation. Keep them in step by hand with
+ * `server/http-server.types.ts` and `port/http-client.types.ts`.
+ */
+export const httpTypeDefs: Readonly<Record<string, TypeSpec>> = {
+  /** One request, as the handler receives it. */
+  Request: t.record({
+    method: t.string,
+    url: t.string,
+    headers: t.map(t.string),
+    body: t.string,
+  }),
+  /** What a handler may answer with. Anything else is taken as the body. */
+  Reply: t.record(
+    { status: t.number, headers: t.map(t.string), body: t.dynamic },
+    { optional: ["status", "headers", "body"], open: true },
+  ),
+  /**
+   * A bound socket: the port it got, and how to give it back.
+   *
+   * Attaching a handler is `http.on`, so the handle does not offer that itself.
+   * The type names only what a program may do with the value, which is why it is
+   * opaque with two visible members rather than fully opaque.
+   */
+  Server: t.opaque("http.Server", { port: t.number, close: t.fn([], t.void) }),
+  /**
+   * One response, as the client verbs give it back.
+   *
+   * `body` is the raw text, always a string whatever came over the wire. `json`
+   * is that text parsed, and is the one field nothing can know the shape of: it
+   * is whatever the far end chose to send. Name a shape for it, as in
+   * `const price: Price = res.json`, and everything after reads as that shape.
+   */
+  Response: t.record(
+    {
+      status: t.number,
+      ok: t.bool,
+      headers: t.map(t.string),
+      body: t.string,
+      json: t.dynamic,
+      time: t.number,
+    },
+    { open: true },
+  ),
+};