@nervur-org/dock 0.3.0

package/harbor/http.ts

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: Apache-2.0
+// The HTTP door: one listener on loopback that a reverse proxy fronts, and
+// the routes mount on it by path prefix. `/health` is the harbor's own: the
+// wards it hosts, by name and pk, and nothing a stranger can use. Each route
+// lives in its own folder, `human/web.ts`, `harbor/quo.ts`, `mcp/route.ts`,
+// and this file knows none of them: a route is a handler under a prefix.
+//
+// This is the route contract every side is written against, and it stands
+// beside the disk harbor whose door it is. A route is `Request` in and
+// `Response` out, the shapes every runtime speaks, so a side runs on this
+// daemon, on a worker at the edge, in a browser's own service worker, on
+// Deno or on Bun without a line of it changing. A handler answering nothing
+// declines, and the mount tries what comes after it. A folder writing a
+// route takes `Handler`, `readAll` and `Quo` from here and nothing of the
+// daemon that mounts them.
+//
+// `listenHttp` is the one place Node's own objects appear: its door turns an
+// `IncomingMessage` into a `Request` and writes a `Response` back onto a
+// `ServerResponse`, and nothing downstream of it names either. The
+// translation runs that one way only: a `Request` is never dressed up as an
+// `IncomingMessage`, because a route writes headers and there would be
+// nothing to write them onto.
+//
+// The listener half of the socket reach is here too, and for the same reason:
+// holding a socket is the one thing no two runtimes do alike, so it stands
+// with the terrain's own door and never in a route. `ws` is that half on
+// Node; at the edge it is a `WebSocketPair` in the harbor there.
+import { createServer as createHttp, type Server as HttpServer } from 'node:http';
+import { Readable } from 'node:stream';
+import { WebSocketServer } from 'ws';
+import type { IncomingMessage } from 'node:http';
+import { Socket as Held } from '@nervur-org/nervur/harbor';
+import type { Dialer } from '@nervur-org/nervur/harbor';
+import type { DiskHarbor } from './disk.ts';
+
+export type Handler = (req: Request, rest: string) => Response | undefined | Promise<Response | undefined>;
+export type Http = { port: number; host: string; mount(prefix: string, handler: Handler): void };
+// What the quo. route holds: the sockets held here and the dialers this
+// daemon runs. `/health` reports them.
+export type Quo = { sockets: Set<Held>; dialers: Dialer[] };
+
+// What a request may carry, on the doors that read a body: enough for any ask
+// a ward seals, and not a body chosen by whoever is on the other end.
+// The bytes are a `Uint8Array` and not a `Buffer`: a route runs on every
+// runtime, and node's own type is not one of the shapes they all speak.
+const BODY = 1 << 20;
+export async function readAll(req: Request): Promise<Uint8Array | undefined> {
+  if (!req.body) return new Uint8Array(0);
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  const reader = req.body.getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.length;
+    if (size > BODY) {
+      await reader.cancel().catch(() => {});
+      return undefined;
+    }
+    chunks.push(value);
+  }
+  const all = new Uint8Array(size);
+  let at = 0;
+  for (const c of chunks) {
+    all.set(c, at);
+    at += c.length;
+  }
+  return all;
+}
+
+// The same body as text, for the doors that read one: JSON, a form, or a
+// vendor's signed bytes a being reads as a string.
+export async function readText(req: Request): Promise<string | undefined> {
+  const raw = await readAll(req);
+  return raw === undefined ? undefined : new TextDecoder().decode(raw);
+}
+
+export async function listenHttp(harbor: DiskHarbor, host: string, port: number, quo: Quo): Promise<Http & { server: HttpServer }> {
+  const mounts = new Map<string, Handler>();
+  const server = createHttp((req, res) => {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+    const answer = async (): Promise<Response> => {
+      if (url.pathname === '/health') {
+        // the wards it hosts, and the directory: pks and whether each is a
+        // socket held here, which is what an operator needs to see a dialer.
+        // Open to any origin: a tab reads it, and it holds nothing a stranger can use.
+        return Response.json(
+          {
+            ok: true,
+            wards: Object.fromEntries([...harbor.wards].map(([n, h]) => [n, h.pk])),
+            reaches: Object.fromEntries([...harbor.reaches].map(([pk, b]) => [pk, b.held ? 'held' : 'reach'])),
+            sockets: quo.sockets.size,
+            dialers: quo.dialers.map((d) => ({ url: d.url, open: d.socket !== null })),
+            // How many saves the disk refused, per ward. The asker whose
+            // write was refused was told at the door; this is the operator's
+            // half, and a box that says nothing about it looks healthy while
+            // one world stops keeping anything.
+            faults: Object.fromEntries([...harbor.faults]),
+          },
+          { headers: { 'access-control-allow-origin': '*' } },
+        );
+      }
+      for (const [prefix, handler] of mounts) {
+        if (url.pathname === prefix || url.pathname.startsWith(prefix + '/')) {
+          const out = await handler(asRequest(req, url), url.pathname.slice(prefix.length));
+          if (out) return out;
+          break;
+        }
+      }
+      return Response.json({ error: 'no such route' }, { status: 404 });
+    };
+    void answer()
+      .then((out) => writeResponse(out, res))
+      .catch(() => {
+        if (!res.headersSent) res.writeHead(500);
+        res.end();
+      });
+  });
+  await new Promise<void>((ok, no) => {
+    server.once('error', no);
+    server.listen(port, host, () => ok());
+  });
+  hold(server, harbor, quo);
+  const address = server.address();
+  const bound = typeof address === 'object' && address !== null ? address.port : port;
+  return { server, host, port: bound, mount: (prefix, handler) => mounts.set(prefix.replace(/\/$/, ''), handler) };
+}
+
+// A dialer's held socket, this terrain's way: an upgrade at the quo route on
+// the daemon's own listener, held as the library's `Socket`. Its pks are bound
+// at announce, each proven at its door, and unbound when the line drops. The
+// route itself reads no socket, and every runtime holds one differently.
+function hold(server: HttpServer, harbor: DiskHarbor, quo: Quo): void {
+  const wss = new WebSocketServer({ noServer: true });
+  server.on('upgrade', (req: IncomingMessage, socket, head) => {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (url.pathname.replace(/\/$/, '') !== '/quo') return void socket.destroy(); // the proxy rewrites the route root to /quo/
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      const s: Held = new Held(
+        ws,
+        (pk, bytes) => harbor.deliver(pk, bytes),
+        (far) => void harbor.bind(far, s, true), // a dialer's claims, each proven at its door: held here, reachable through this socket
+        () => {
+          harbor.unbind(s);
+          quo.sockets.delete(s);
+        },
+      );
+      quo.sockets.add(s);
+      s.announce([...harbor.doors.keys()]);
+    });
+  });
+}
+
+// Node's request as a `Request`: the one translation in, at the daemon's own
+// door. A method that carries no body carries none here either, since the
+// web shape refuses one.
+function asRequest(req: import('node:http').IncomingMessage, url: URL): Request {
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (v === undefined) continue;
+    if (Array.isArray(v)) for (const one of v) headers.append(k, one);
+    else headers.set(k, v);
+  }
+  const method = req.method ?? 'GET';
+  const bodied = method !== 'GET' && method !== 'HEAD';
+  return new Request(url, {
+    method,
+    headers,
+    ...(bodied ? { body: Readable.toWeb(req) as ReadableStream<Uint8Array>, duplex: 'half' } : {}),
+  } as RequestInit);
+}
+
+// And the one translation out.
+async function writeResponse(out: Response, res: import('node:http').ServerResponse): Promise<void> {
+  const headers: Record<string, string | string[]> = {};
+  out.headers.forEach((v, k) => {
+    headers[k] = k === 'set-cookie' ? [...(Array.isArray(headers[k]) ? (headers[k] as string[]) : []), v] : v;
+  });
+  res.writeHead(out.status, headers);
+  if (!out.body) return void res.end();
+  const reader = out.body.getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    res.write(Buffer.from(value));
+  }
+  res.end();
+}