nervur 0.20.1 → 0.20.2

package/src/harbor/relay.ts

@@ -0,0 +1,399 @@
+// SPDX-License-Identifier: Apache-2.0
+// The relay: a harbor nobody dials is reached through a harbor that is,
+// by relations alone. Both sides are kit faculties, opened by the root.
+//
+// On the reached harbor, `org.nervur.relay`:
+//
+//   invite   { id, wards }        a relay client invited under `id`, its
+//                                 notes naming the ward pks it collects for
+//   release  { id }               that client let go, and every box waiting
+//                                 for its wards answered with nothing
+//   collect  { replies?, wait? }  asked by a client: the replies to the boxes
+//                                 it took last, handed to their callers, then
+//                                 the boxes waiting for its wards; with
+//                                 `wait`, it waits for one first
+//   bell     { endpoint }         asked by a client: the push endpoint rung
+//                                 when a box waits for it, or null for none
+//   key                           asked by a client: the key its device
+//                                 subscribes to pushes with
+//
+// A box for a ward a client collects for reaches this harbor on any
+// carrier, and the caller's dial waits for its reply, or for nothing once
+// `RELAY_WAIT` passes. No box is opened here. A box no waiting collect
+// takes rings the client's bell once, through a `Push` faculty the relay
+// lends, until the client collects again.
+//
+// On the harbor nobody dials, `org.nervur.relay-client`:
+//
+//   hold  { invitation, line?, every? }  the relay's invitation taken; a
+//                                        line collects always, `every`
+//                                        rings on a schedule, in ms
+//   ring                                 every waiting box collected, handed
+//                                        to this harbor's doors, and the
+//                                        replies returned: a doorbell
+//   bell  { endpoint }                   the relay's `bell`, asked
+//   key                                  the relay's `key`, asked
+//   drop                                 the relay let go
+//
+// Its harbor's `reach` names the relay's address, so every invitation it
+// gives sends callers there. Whatever hears a push on the device asks
+// `ring`.
+import { Faculty, isSilence, isWord, told, type Asker, type AskSpec, type BeingClass, type JsonObject } from '../being/index.ts';
+import type { Clock } from '../contract/index.ts';
+import { hex, isHex, unhex } from '../crypto/index.ts';
+import { readInvitation } from '../quo/index.ts';
+import { ownerAsk } from '../ward/index.ts';
+import { CarrierFaculty, UNDIALED, type Dialed, type Ground } from './carrying.ts';
+
+export const RELAY = 'org.nervur.relay';
+export const RELAY_CLIENT = 'org.nervur.relay-client';
+export const PUSH = 'org.nervur.push';
+// How long a box waits for its reply: a caller's allowance, unless it
+// asks for another.
+export const RELAY_WAIT = 30_000;
+// How long a collect with `wait` holds, inside the client's allowance.
+export const RELAY_HOLD = 20_000;
+// How long a line rests after a collect that reached nothing.
+export const RELAY_REST = 1_000;
+// The largest box a relay carries, so the collect answering it stays a
+// box Quo carries.
+export const RELAYED = 262_144;
+// The longest push endpoint a relay keeps.
+const ENDPOINT = 2_048;
+// The most boxes one collect hands over.
+const BATCH = 16;
+const CLIENT = 'relay';
+const PUSHER = 'push';
+
+// The contract of a ring with no content: `key` answers the key a device
+// subscribes with, and `ring { endpoint }` answers `rung`, `gone` where
+// the push service has let the endpoint go, or an error.
+export abstract class Push extends Faculty {
+  static override readonly kind: string = PUSH;
+}
+
+type Waiting = { n: number; ward: string; bytes: Uint8Array; answer: (reply: Uint8Array | null) => void; cancel: () => void; collector?: string };
+type Collector = { wards: readonly string[]; wake: () => void };
+type Reply = { n: number; box: string | null };
+
+const text = (v: unknown): v is string => typeof v === 'string';
+const wardsOf = (notes: JsonObject | undefined): string[] => (Array.isArray(notes?.relay) ? notes.relay.filter(text) : []);
+const collects: AskSpec['for'] = (_: Asker, notes) => wardsOf(notes).length > 0;
+const clientAsk = (description: string, input: JsonObject = {}): AskSpec => ({ description, input: { type: 'object', ...input }, for: collects });
+const readReplies = (v: unknown): Reply[] | null =>
+  v === undefined
+    ? []
+    : Array.isArray(v) && v.every((r) => typeof r === 'object' && r !== null && Number.isInteger((r as Reply).n) && ((r as Reply).box === null || isHex((r as Reply).box, ((r as Reply).box ?? '').length / 2)))
+      ? (v as Reply[])
+      : null;
+// An answer, or the error it stands for.
+const answered = (out: unknown): JsonObject => (isSilence(out) ? { error: 'silence' } : isWord(out) ? { error: told(out) as string } : (out as JsonObject));
+
+export const relayFaculty = (clock: Clock): BeingClass =>
+  class Relay extends CarrierFaculty {
+    static override readonly kind: string = RELAY;
+    static override cells: JsonObject = { clients: {}, bells: {} };
+    static override asks: Record<string, AskSpec> = {
+      invite: ownerAsk('a relay client, collecting for the ward pks named', { required: ['id', 'wards'] }),
+      release: ownerAsk('a relay client let go', { required: ['id'] }),
+      collect: clientAsk('the replies to the boxes taken last, then the boxes waiting'),
+      bell: clientAsk('the push endpoint rung when a box waits, or null', { required: ['endpoint'] }),
+      key: clientAsk('the key a device subscribes to pushes with'),
+    };
+
+    #n = 0;
+    readonly #waiting: Waiting[] = [];
+    readonly #taken = new Map<number, Waiting>();
+    readonly #collectors = new Set<Collector>();
+    // The clients rung since they last collected.
+    readonly #rung = new Set<string>();
+    #lending: Promise<string | null> | undefined;
+
+    accepts(): boolean {
+      return false;
+    }
+
+    dial(): Promise<Dialed> {
+      return Promise.resolve(UNDIALED);
+    }
+
+    get #clients(): Record<string, string[]> {
+      return this.cells.clients as Record<string, string[]>;
+    }
+
+    get #bells(): Record<string, string> {
+      return this.cells.bells as Record<string, string>;
+    }
+
+    override relays(pk: string): boolean {
+      return Object.values(this.#clients).some((wards) => wards.includes(pk));
+    }
+
+    override relay(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+      if (!this.relays(pk) || bytes.length > RELAYED) return Promise.resolve(null);
+      return new Promise((resolve) => {
+        const wait = clock.wait(RELAY_WAIT);
+        const box: Waiting = { n: ++this.#n, ward: pk, bytes, answer: resolve, cancel: wait.cancel };
+        void wait.done.then(() => this.#settle(box, null));
+        this.#waiting.push(box);
+        let woken = false;
+        for (const collector of this.#collectors) {
+          if (!collector.wards.includes(pk)) continue;
+          collector.wake();
+          woken = true;
+        }
+        if (woken) return;
+        for (const [id, wards] of Object.entries(this.#clients)) {
+          if (!wards.includes(pk) || !Object.hasOwn(this.#bells, id) || this.#rung.has(id)) continue;
+          this.#rung.add(id);
+          void this.#ring(id);
+        }
+      });
+    }
+
+    // Every box answered with nothing, and every collect woken.
+    override sleep(): Promise<void> {
+      for (const box of [...this.#waiting, ...this.#taken.values()]) this.#settle(box, null);
+      for (const collector of this.#collectors) collector.wake();
+      return Promise.resolve();
+    }
+
+    async invite(args: JsonObject): Promise<JsonObject> {
+      const { id, wards } = args;
+      if (!text(id) || !Array.isArray(wards) || wards.length === 0 || !wards.every((w) => isHex(w, 64))) return { error: 'id is text and wards a list of ward pks' };
+      if (Object.hasOwn(this.#clients, id)) return { error: 'that client is invited' };
+      const invitation = await this.stance.occupants.invite(id, { relay: wards });
+      if (invitation === null) return { error: 'not invited' };
+      this.#clients[id] = [...(wards as string[])];
+      return { invitation };
+    }
+
+    release(args: JsonObject): JsonObject {
+      if (!text(args.id) || !Object.hasOwn(this.#clients, args.id)) return { error: 'no such client' };
+      this.stance.occupants.remove(args.id);
+      delete this.#clients[args.id];
+      delete this.#bells[args.id];
+      this.#rung.delete(args.id);
+      for (const box of [...this.#waiting, ...this.#taken.values()]) if (!this.relays(box.ward)) this.#settle(box, null);
+      return { released: args.id };
+    }
+
+    async collect(args: JsonObject, asker: Asker): Promise<JsonObject> {
+      const replies = readReplies(args.replies);
+      if (replies === null) return { error: 'replies are a list of { n, box }' };
+      const id = asker.id!;
+      this.#rung.delete(id);
+      for (const { n, box } of replies) {
+        const taken = this.#taken.get(n);
+        if (taken?.collector === id) this.#settle(taken, box === null ? null : unhex(box));
+      }
+      const wards = wardsOf(this.notes(asker));
+      if (args.wait === true && !this.#waiting.some((b) => wards.includes(b.ward))) await this.#hold(wards);
+      const boxes = this.#waiting.filter((b) => wards.includes(b.ward)).slice(0, BATCH);
+      for (const box of boxes) {
+        this.#waiting.splice(this.#waiting.indexOf(box), 1);
+        box.collector = id;
+        this.#taken.set(box.n, box);
+      }
+      return { boxes: boxes.map(({ n, ward, bytes }) => ({ n, ward, box: hex(bytes) })) };
+    }
+
+    bell(args: JsonObject, asker: Asker): JsonObject {
+      const { endpoint } = args;
+      const id = asker.id!;
+      if (endpoint === null) {
+        delete this.#bells[id];
+        return { bell: null };
+      }
+      if (!text(endpoint) || endpoint.length > ENDPOINT || !/^https?:\/\//.test(endpoint)) return { error: 'endpoint is a web URL, or null' };
+      this.#bells[id] = endpoint;
+      return { bell: endpoint };
+    }
+
+    async key(): Promise<JsonObject> {
+      const push = await this.#push();
+      return push ? answered(await push.ask('key')) : { error: 'no push faculty is open' };
+    }
+
+    // The client's bell rung. An endpoint the push service calls gone is
+    // forgotten, and kept at the relay's next arrival.
+    async #ring(id: string): Promise<void> {
+      const push = await this.#push();
+      const endpoint = this.#bells[id];
+      if (!push || endpoint === undefined) return;
+      const out = answered(await push.ask('ring', { endpoint }));
+      if (out.gone === true && this.#bells[id] === endpoint) delete this.#bells[id];
+    }
+
+    async #push() {
+      if (!this.stance.standings.get(PUSHER)) {
+        this.#lending ??= this.stance.lend(Push, PUSHER).finally(() => (this.#lending = undefined));
+        await this.#lending;
+      }
+      return this.stance.standings.get(PUSHER);
+    }
+
+    #hold(wards: readonly string[]): Promise<void> {
+      return new Promise((resolve) => {
+        const wait = clock.wait(RELAY_HOLD);
+        const collector: Collector = {
+          wards,
+          wake: () => {
+            wait.cancel();
+            this.#collectors.delete(collector);
+            resolve();
+          },
+        };
+        this.#collectors.add(collector);
+        void wait.done.then(collector.wake);
+      });
+    }
+
+    #settle(box: Waiting, reply: Uint8Array | null): void {
+      box.cancel();
+      const at = this.#waiting.indexOf(box);
+      if (at >= 0) this.#waiting.splice(at, 1);
+      this.#taken.delete(box.n);
+      box.answer(reply);
+    }
+  };
+
+export const relayClient = (ground: Ground, clock: Clock): BeingClass =>
+  class RelayClient extends CarrierFaculty {
+    static override readonly kind: string = RELAY_CLIENT;
+    static override asks: Record<string, AskSpec> = {
+      hold: ownerAsk("a relay's invitation, collected from on a line, a schedule or a ring", { required: ['invitation'] }),
+      ring: ownerAsk('every waiting box collected and answered now'),
+      bell: ownerAsk('the push endpoint the relay rings, or null', { required: ['endpoint'] }),
+      key: ownerAsk('the key this device subscribes to pushes with'),
+      drop: ownerAsk('the relay let go'),
+    };
+
+    #awake = false;
+    #replies: Reply[] = [];
+    // Ends every rest and schedule when the client sleeps or lets go.
+    #stop: () => void = () => {};
+
+    accepts(): boolean {
+      return false;
+    }
+
+    dial(): Promise<Dialed> {
+      return Promise.resolve(UNDIALED);
+    }
+
+    override awake(): Promise<void> {
+      if (!this.#awake) {
+        this.#awake = true;
+        this.#start();
+      }
+      return Promise.resolve();
+    }
+
+    override sleep(): Promise<void> {
+      this.#awake = false;
+      this.#stop();
+      return Promise.resolve();
+    }
+
+    async hold(args: JsonObject): Promise<JsonObject> {
+      const invitation = readInvitation(args.invitation);
+      const { line, every } = args;
+      if (invitation === null || (line !== undefined && typeof line !== 'boolean') || (every !== undefined && !(Number.isInteger(every) && (every as number) > 0))) {
+        return { error: 'an invitation, line a boolean and every a positive integer' };
+      }
+      if (this.stance.standings.get(CLIENT)) return { error: 'a relay is held' };
+      if ((await this.stance.standings.take(CLIENT, invitation)) === null) return { error: 'not taken' };
+      this.cells.line = line === true;
+      if (every !== undefined) this.cells.every = every;
+      this.#start();
+      return { held: invitation.ward };
+    }
+
+    async ring(): Promise<JsonObject> {
+      if (!this.stance.standings.get(CLIENT)) return { error: 'no relay is held' };
+      let carried = 0;
+      for (;;) {
+        const sent = this.#replies.length;
+        const got = await this.#collect(false);
+        if (got === null) return { error: 'the relay was not reached', carried };
+        carried += got;
+        if (got === 0 && sent === 0) return { carried };
+      }
+    }
+
+    bell(args: JsonObject): Promise<JsonObject> {
+      return this.#relay('bell', { endpoint: args.endpoint ?? null });
+    }
+
+    key(): Promise<JsonObject> {
+      return this.#relay('key');
+    }
+
+    drop(): JsonObject {
+      if (!this.stance.standings.remove(CLIENT)) return { error: 'no relay is held' };
+      delete this.cells.line;
+      delete this.cells.every;
+      this.#stop();
+      return { dropped: true };
+    }
+
+    async #relay(method: string, args: JsonObject = {}): Promise<JsonObject> {
+      const standing = this.stance.standings.get(CLIENT);
+      return standing ? answered(await standing.ask(method, args)) : { error: 'no relay is held' };
+    }
+
+    #start(): void {
+      if (!this.#awake || !this.stance.standings.get(CLIENT)) return;
+      this.#stop();
+      let stopped = false;
+      const rests = new Set<() => void>();
+      this.#stop = () => {
+        stopped = true;
+        for (const end of rests) end();
+      };
+      const rest = (ms: number): Promise<void> =>
+        new Promise((resolve) => {
+          const wait = clock.wait(ms);
+          const end = () => {
+            wait.cancel();
+            rests.delete(end);
+            resolve();
+          };
+          rests.add(end);
+          void wait.done.then(end);
+        });
+      const going = () => !stopped && this.stance.standings.get(CLIENT) !== undefined;
+      if (this.cells.line === true) {
+        void (async () => {
+          while (going()) if ((await this.#collect(true)) === null && going()) await rest(RELAY_REST);
+        })();
+      }
+      const every = this.cells.every as number | undefined;
+      if (every !== undefined) {
+        void (async () => {
+          for (await rest(every); going(); await rest(every)) await this.ring();
+        })();
+      }
+    }
+
+    // One collect: the replies owed go with it, and each box it brings is
+    // handed to this harbor's doors. The number of boxes, or null where the
+    // relay was not reached.
+    async #collect(wait: boolean): Promise<number | null> {
+      const standing = this.stance.standings.get(CLIENT);
+      if (!standing) return null;
+      const replies = this.#replies.splice(0);
+      const out = await standing.ask('collect', { replies, wait });
+      const boxes = !isSilence(out) && !isWord(out) && Array.isArray((out as JsonObject).boxes) ? ((out as JsonObject).boxes as JsonObject[]) : null;
+      if (boxes === null) {
+        this.#replies.unshift(...replies);
+        return null;
+      }
+      for (const { n, ward, box } of boxes) {
+        const reply = text(ward) && text(box) && isHex(box, box.length / 2) ? await ground.arrive(ward, unhex(box)) : null;
+        this.#replies.push({ n: n as number, box: reply === null ? null : hex(reply) });
+      }
+      return boxes.length;
+    }
+  };

package/src/harbor/root-line.ts

@@ -28,7 +28,10 @@ export const rootLine = async (harbor: Harbor, value: unknown): Promise<JsonObje
   const request = readRootRequest(value);
   if (request === null) return { error: 'not a root request' };
   const ward = request.ward === undefined ? harbor.box : harbor.ward(request.ward);
-  if (ward === undefined) return { error: 'no such ward' };
+  if (ward === undefined) {
+    const failed = request.ward === undefined ? undefined : harbor.failures().wards[request.ward];
+    return failed === undefined ? { error: 'no such ward' } : { error: 'the ward did not stand', reason: failed };
+  }
   const out = await ward.root(request.method, request.args);
   if (isSilence(out)) return { silence: true };
   if (isWord(out)) return { word: told(out) as string };

package/src/harbor/terrain.ts

@@ -1,7 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
 // Where a harbor runs. A terrain hands the harbor one body for each
-// contract the onion cannot unpack from cells.
+// contract the onion cannot unpack from cells, and the carriers its
+// ground speaks.
 import type { Carrier, Clock, Custody, Entropy, Loader, Memory } from '../contract/index.ts';
+import type { GroundFaculty } from './carrying.ts';
+import type { Harbor } from './harbor.ts';
+
+// A faculty a harbor opens at its genesis, under a key, by kind.
+export type Opening = { readonly key: string; readonly kind: string };
 
 export abstract class Terrain {
   abstract readonly entropy: Entropy;
@@ -10,6 +16,26 @@ export abstract class Terrain {
   abstract readonly memory: Memory;
   // The code the catalogue's cells name.
   abstract readonly loader: Loader;
-  // What reaches a ward pk this harbor does not hold.
+  // What reaches a ward pk this harbor holds no route for.
   abstract readonly carrier: Carrier;
+  // The faculty classes this ground ships, its carriers among them, and
+  // those a new harbor opens.
+  readonly faculties: readonly GroundFaculty[] = [];
+  readonly opens: readonly Opening[] = [];
+  // Whether its carriers wake and listen where their cells say. A harbor
+  // opened for one ask and closed again dials and hears nothing.
+  readonly wakes: boolean = true;
+
+  // Before the harbor opens: a terrain whose ground another run holds
+  // refuses here. Once it stands: whatever the ground serves beside it.
+  // Once its carriers sleep: what that served, gone.
+  claim(): Promise<void> {
+    return Promise.resolve();
+  }
+  stand(_harbor: Harbor): Promise<void> {
+    return Promise.resolve();
+  }
+  release(): Promise<void> {
+    return Promise.resolve();
+  }
 }

package/src/http/index.ts

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur/http`: the web carrier's listener on Node's HTTP server, an entry
+// that names a platform.
+//
+//   webServe   answers posts at a path, and held lines opened to that path
+//              with the subprotocol `quo`, for the ground it is handed
+//   webGround  the web carrier faculty of a Node ground, able to listen
+//
+// A post is one ask: 200 with the reply's box, or 204 for nothing. A post
+// to another path is 404, another method 405, a body that is no ask 400.
+// A page of an origin the cells name, or of any origin under `*`, is
+// answered as the CORS protocol says, its preflight included. A held line
+// carries one frame body to a binary message; a text message, a body that
+// is no frame, or bytes that break RFC 6455 close it, and nothing after
+// them is read.
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import type { Socket } from 'node:net';
+import type { Ground, GroundFaculty } from '../harbor/index.ts';
+import { MAX_BODY, MAX_POST, nothingBody, readBody, readPost, replyBody, webFaculty, type WebListen, type WebListener } from '../line/index.ts';
+import { hex } from '../crypto/index.ts';
+import { tcpAt } from '../quo/index.ts';
+import { acceptKey, frameOf, isClientKey, OP, WsReader } from './websocket.ts';
+
+const pathOf = (url: string | undefined): string => {
+  const at = (url ?? '/').indexOf('?');
+  return at < 0 ? (url ?? '/') : (url ?? '/').slice(0, at);
+};
+
+const originOf = (origins: readonly string[], origin: string | undefined): string | null => {
+  if (origin === undefined) return null;
+  if (origins.includes('*')) return '*';
+  return origins.includes(origin) ? origin : null;
+};
+
+// The bytes of a request, up to one more than `max`, as they came.
+const bodyOf = (request: IncomingMessage, max: number): Promise<Uint8Array> =>
+  new Promise((resolve, reject) => {
+    const parts: Uint8Array[] = [];
+    let length = 0;
+    request.on('data', (chunk: Uint8Array) => {
+      if (length > max) return;
+      parts.push(chunk);
+      length += chunk.length;
+    });
+    request.on('end', () => {
+      const out = new Uint8Array(length);
+      let at = 0;
+      for (const part of parts) {
+        out.set(part, at);
+        at += part.length;
+      }
+      resolve(out);
+    });
+    request.on('error', reject);
+  });
+
+const post = async (ground: Ground, listen: WebListen, request: IncomingMessage, response: ServerResponse): Promise<void> => {
+  const allowed = originOf(listen.origins, request.headers.origin);
+  if (allowed !== null) response.setHeader('access-control-allow-origin', allowed);
+  if (pathOf(request.url) !== listen.path) return void response.writeHead(404).end();
+  if (request.method === 'OPTIONS') {
+    if (allowed !== null) {
+      response.setHeader('access-control-allow-methods', 'POST');
+      response.setHeader('access-control-allow-headers', 'content-type');
+    }
+    return void response.writeHead(204).end();
+  }
+  if (request.method !== 'POST') return void response.writeHead(405, { allow: 'POST, OPTIONS' }).end();
+  const ask = readPost(await bodyOf(request, MAX_POST));
+  if (ask === null) return void response.writeHead(400).end();
+  let reply: Uint8Array | null = null;
+  try {
+    reply = await ground.arrive(ask.pk, ask.box);
+  } catch {
+    reply = null;
+  }
+  if (reply === null || reply.length === 0) return void response.writeHead(204).end();
+  response.writeHead(200, { 'content-type': 'application/octet-stream' }).end(reply);
+};
+
+const upgrade = (ground: Ground, listen: WebListen, request: IncomingMessage, socket: Socket): void => {
+  const key = request.headers['sec-websocket-key'];
+  const offered = String(request.headers['sec-websocket-protocol'] ?? '')
+    .split(',')
+    .map((p) => p.trim());
+  const fine = pathOf(request.url) === listen.path && request.headers['sec-websocket-version'] === '13' && isClientKey(key) && offered.includes('quo');
+  if (!fine) {
+    socket.end('HTTP/1.1 400 Bad Request\r\nconnection: close\r\ncontent-length: 0\r\n\r\n');
+    return;
+  }
+  socket.write(`HTTP/1.1 101 Switching Protocols\r\nupgrade: websocket\r\nconnection: Upgrade\r\nsec-websocket-accept: ${acceptKey(key)}\r\nsec-websocket-protocol: quo\r\n\r\n`);
+  const reader = new WsReader(MAX_BODY);
+  const send = (opcode: number, payload?: Uint8Array): void => {
+    if (!socket.destroyed) socket.write(frameOf(opcode, payload));
+  };
+  const close = (): void => {
+    send(OP.close);
+    socket.end();
+  };
+  socket.on('data', (chunk: Uint8Array) => {
+    for (const event of reader.push(chunk)) {
+      if (event.type === 'ping') send(OP.pong, event.data);
+      else if (event.type !== 'binary') return close();
+      else {
+        const frame = readBody(event.data);
+        if (frame === null) return close();
+        if (frame.kind !== 'ask') continue;
+        void ground
+          .arrive(hex(frame.pk), frame.box)
+          .catch(() => null)
+          .then((reply) => send(OP.binary, reply === null ? nothingBody(frame.id) : replyBody(frame.id, reply)));
+      }
+    }
+  });
+  socket.on('error', () => socket.destroy());
+};
+
+// A listener of the web carrier for one ground.
+export const webServe = (ground: Ground, listen: WebListen): Promise<WebListener> => {
+  const sockets = new Set<Socket>();
+  const server = createServer((request, response) => {
+    void post(ground, listen, request, response).catch(() => {
+      if (!response.headersSent) response.writeHead(400);
+      response.end();
+    });
+  });
+  server.on('connection', (socket) => {
+    sockets.add(socket);
+    socket.on('close', () => sockets.delete(socket));
+  });
+  server.on('upgrade', (request: IncomingMessage, socket: Socket) => upgrade(ground, listen, request, socket));
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(listen.port, listen.host, () => {
+      const { address, port } = server.address() as { address: string; port: number };
+      const authority = tcpAt(address, port).slice('tcp://'.length);
+      resolve({
+        port,
+        at: [`http://${authority}${listen.path}`, `ws://${authority}${listen.path}`],
+        close: () => {
+          for (const socket of sockets) socket.destroy();
+          return new Promise((done) => server.close(() => done()));
+        },
+      });
+    });
+  });
+};
+
+// The web carrier of a Node ground: it dials, and listens through `webServe`.
+export const webGround: GroundFaculty = webFaculty(webServe);