@pi-harness/pi-harness 0.1.1

package/packages/host-webserver/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AACpF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChG;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,IAAI,CAAC;IACtC,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,MAAM,IAAI,CAAC;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,SAAS,EAAE,SAAS,CAAC;KACtB;CACF;;;mBAkBsB,OAAO,UAAU,eAAe;;AAFvD,wBAsDE"}

package/packages/host-webserver/dist/index.js

@@ -0,0 +1,73 @@
+import { createServer } from "node:http";
+function normalizePath(path) {
+    if (!path.startsWith("/") || (path.length > 1 && path.endsWith("/")))
+        throw new Error("Web route path must be absolute without a trailing slash: " + path);
+    return path;
+}
+function notFound(response) {
+    response.writeHead(404, { "content-type": "application/json; charset=utf-8" });
+    response.end(JSON.stringify({ error: "Not found" }));
+}
+function hostForUrl(host) {
+    return host.includes(":") && !host.startsWith("[") ? "[" + host + "]" : host;
+}
+export default {
+    name: "pi-webserver",
+    async apply(context, config) {
+        const host = config.host ?? "127.0.0.1";
+        const port = config.port ?? 3080;
+        const routes = new Map();
+        let fallback;
+        const server = createServer((request, response) => {
+            const path = new URL(request.url ?? "/", "http://" + hostForUrl(host)).pathname;
+            const handler = routes.get(path) ?? fallback;
+            if (handler === undefined) {
+                notFound(response);
+                return;
+            }
+            void Promise.resolve(handler(request, response)).catch((error) => {
+                if (response.headersSent) {
+                    response.destroy(error instanceof Error ? error : new Error(String(error)));
+                    return;
+                }
+                response.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            });
+        });
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(port, host, () => {
+                server.off("error", reject);
+                resolve();
+            });
+        });
+        const address = server.address();
+        if (address === null || typeof address === "string")
+            throw new Error("Web server did not expose a TCP address");
+        const service = {
+            host,
+            port: address.port,
+            url: "http://" + hostForUrl(host) + ":" + address.port,
+            register(route) {
+                const path = normalizePath(route.path);
+                if (routes.has(path))
+                    throw new Error("Web route already registered: " + path);
+                routes.set(path, route.handler);
+                return () => routes.delete(path);
+            },
+            registerFallback(handler) {
+                if (fallback !== undefined)
+                    throw new Error("Web fallback is already registered");
+                fallback = handler;
+                return () => {
+                    if (fallback === handler)
+                        fallback = undefined;
+                };
+            },
+            close: () => new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve())),
+        };
+        context.provide("webServer", service);
+        context.effect(() => async () => service.close());
+    },
+};
+//# sourceMappingURL=index.js.map

package/packages/host-webserver/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/packages/host-webserver/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@pi-harness/host-webserver",
+  "version": "0.1.1",
+  "description": "Cordis route-registration service for the Pi Harness web host",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.1"
+  }
+}

package/packages/host-webserver/src/index.ts

@@ -0,0 +1,97 @@
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { Context } from "@deepseek-ai/cordis";
+
+export interface WebRoute {
+  readonly path: string;
+  readonly handler: (request: IncomingMessage, response: ServerResponse) => void | Promise<void>;
+}
+
+export interface WebServerConfig {
+  readonly host?: string;
+  readonly port?: number;
+}
+
+export interface WebServer {
+  readonly host: string;
+  readonly port: number;
+  readonly url: string;
+  register(route: WebRoute): () => void;
+  registerFallback(handler: WebRoute["handler"]): () => void;
+  close(): Promise<void>;
+}
+
+declare module "@deepseek-ai/cordis" {
+  interface Context {
+    webServer: WebServer;
+  }
+}
+
+function normalizePath(path: string): string {
+  if (!path.startsWith("/") || (path.length > 1 && path.endsWith("/"))) throw new Error("Web route path must be absolute without a trailing slash: " + path);
+  return path;
+}
+
+function notFound(response: ServerResponse): void {
+  response.writeHead(404, { "content-type": "application/json; charset=utf-8" });
+  response.end(JSON.stringify({ error: "Not found" }));
+}
+
+function hostForUrl(host: string): string {
+  return host.includes(":") && !host.startsWith("[") ? "[" + host + "]" : host;
+}
+
+export default {
+  name: "pi-webserver",
+  async apply(context: Context, config: WebServerConfig) {
+    const host = config.host ?? "127.0.0.1";
+    const port = config.port ?? 3080;
+    const routes = new Map<string, WebRoute["handler"]>();
+    let fallback: WebRoute["handler"] | undefined;
+    const server = createServer((request, response) => {
+      const path = new URL(request.url ?? "/", "http://" + hostForUrl(host)).pathname;
+      const handler = routes.get(path) ?? fallback;
+      if (handler === undefined) {
+        notFound(response);
+        return;
+      }
+      void Promise.resolve(handler(request, response)).catch((error: unknown) => {
+        if (response.headersSent) {
+          response.destroy(error instanceof Error ? error : new Error(String(error)));
+          return;
+        }
+        response.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+        response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+      });
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(port, host, () => {
+        server.off("error", reject);
+        resolve();
+      });
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") throw new Error("Web server did not expose a TCP address");
+    const service: WebServer = {
+      host,
+      port: address.port,
+      url: "http://" + hostForUrl(host) + ":" + address.port,
+      register(route) {
+        const path = normalizePath(route.path);
+        if (routes.has(path)) throw new Error("Web route already registered: " + path);
+        routes.set(path, route.handler);
+        return () => routes.delete(path);
+      },
+      registerFallback(handler) {
+        if (fallback !== undefined) throw new Error("Web fallback is already registered");
+        fallback = handler;
+        return () => {
+          if (fallback === handler) fallback = undefined;
+        };
+      },
+      close: () => new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve())),
+    };
+    context.provide("webServer", service);
+    context.effect(() => async () => service.close());
+  },
+};

package/packages/host-webserver/test/index.test.ts

@@ -0,0 +1,43 @@
+import { Context } from "@deepseek-ai/cordis";
+import { afterEach, describe, expect, test } from "vitest";
+import webServerPlugin from "../src/index.js";
+
+const contexts: Context[] = [];
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map(async (context) => context.fiber.dispose()));
+});
+
+describe("web server plugin", () => {
+  test("serves registered routes and disposes the listener with the Cordis fiber", async () => {
+    const context = new Context();
+    contexts.push(context);
+    await context.plugin(webServerPlugin, { host: "127.0.0.1", port: 0 });
+    const server = context.webServer;
+    const disposeRoute = server.register({
+      path: "/health",
+      handler(_request, response) {
+        response.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+        response.end("ok");
+      },
+    });
+
+    await expect(fetch(server.url + "/health").then(async (response) => ({ status: response.status, body: await response.text() }))).resolves.toEqual({ status: 200, body: "ok" });
+    expect(() => server.register({ path: "/health", handler() {} })).toThrow(/already registered/);
+
+    disposeRoute();
+    await expect(fetch(server.url + "/health")).resolves.toMatchObject({ status: 404 });
+    await context.fiber.dispose();
+    await expect(fetch(server.url + "/health")).rejects.toThrow();
+    contexts.splice(contexts.indexOf(context), 1);
+  });
+
+  test("rejects malformed route paths", async () => {
+    const context = new Context();
+    contexts.push(context);
+    await context.plugin(webServerPlugin, { port: 0 });
+
+    expect(() => context.webServer.register({ path: "health", handler() {} })).toThrow(/absolute/);
+    expect(() => context.webServer.register({ path: "/health/", handler() {} })).toThrow(/trailing slash/);
+  });
+});

package/packages/host-webserver/tsconfig.build.json

@@ -0,0 +1 @@
+{"extends":"../../tsconfig.build.json","compilerOptions":{"outDir":"dist","paths":{},"rootDir":"src"},"include":["src/**/*.ts"]}

package/packages/host-webserver/tsconfig.json

@@ -0,0 +1 @@
+{"extends":"../../tsconfig.json","compilerOptions":{"paths":{}},"include":["src/**/*.ts"]}