nervur 0.20.0 → 0.20.2

package/dist/harbor/relay.js

@@ -0,0 +1,387 @@
+// 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 } from '../being/index.js';
+import { hex, isHex, unhex } from '../crypto/index.js';
+import { readInvitation } from '../quo/index.js';
+import { ownerAsk } from '../ward/index.js';
+import { CarrierFaculty, UNDIALED } from './carrying.js';
+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 class Push extends Faculty {
+    static kind = PUSH;
+}
+const text = (v) => typeof v === 'string';
+const wardsOf = (notes) => (Array.isArray(notes?.relay) ? notes.relay.filter(text) : []);
+const collects = (_, notes) => wardsOf(notes).length > 0;
+const clientAsk = (description, input = {}) => ({ description, input: { type: 'object', ...input }, for: collects });
+const readReplies = (v) => v === undefined
+    ? []
+    : Array.isArray(v) && v.every((r) => typeof r === 'object' && r !== null && Number.isInteger(r.n) && (r.box === null || isHex(r.box, (r.box ?? '').length / 2)))
+        ? v
+        : null;
+// An answer, or the error it stands for.
+const answered = (out) => (isSilence(out) ? { error: 'silence' } : isWord(out) ? { error: told(out) } : out);
+export const relayFaculty = (clock) => class Relay extends CarrierFaculty {
+    static kind = RELAY;
+    static cells = { clients: {}, bells: {} };
+    static asks = {
+        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;
+    #waiting = [];
+    #taken = new Map();
+    #collectors = new Set();
+    // The clients rung since they last collected.
+    #rung = new Set();
+    #lending;
+    accepts() {
+        return false;
+    }
+    dial() {
+        return Promise.resolve(UNDIALED);
+    }
+    get #clients() {
+        return this.cells.clients;
+    }
+    get #bells() {
+        return this.cells.bells;
+    }
+    relays(pk) {
+        return Object.values(this.#clients).some((wards) => wards.includes(pk));
+    }
+    relay(pk, bytes) {
+        if (!this.relays(pk) || bytes.length > RELAYED)
+            return Promise.resolve(null);
+        return new Promise((resolve) => {
+            const wait = clock.wait(RELAY_WAIT);
+            const box = { 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.
+    sleep() {
+        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) {
+        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];
+        return { invitation };
+    }
+    release(args) {
+        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, asker) {
+        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, asker) {
+        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() {
+        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) {
+        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) {
+        return new Promise((resolve) => {
+            const wait = clock.wait(RELAY_HOLD);
+            const collector = {
+                wards,
+                wake: () => {
+                    wait.cancel();
+                    this.#collectors.delete(collector);
+                    resolve();
+                },
+            };
+            this.#collectors.add(collector);
+            void wait.done.then(collector.wake);
+        });
+    }
+    #settle(box, reply) {
+        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, clock) => class RelayClient extends CarrierFaculty {
+    static kind = RELAY_CLIENT;
+    static asks = {
+        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 = [];
+    // Ends every rest and schedule when the client sleeps or lets go.
+    #stop = () => { };
+    accepts() {
+        return false;
+    }
+    dial() {
+        return Promise.resolve(UNDIALED);
+    }
+    awake() {
+        if (!this.#awake) {
+            this.#awake = true;
+            this.#start();
+        }
+        return Promise.resolve();
+    }
+    sleep() {
+        this.#awake = false;
+        this.#stop();
+        return Promise.resolve();
+    }
+    async hold(args) {
+        const invitation = readInvitation(args.invitation);
+        const { line, every } = args;
+        if (invitation === null || (line !== undefined && typeof line !== 'boolean') || (every !== undefined && !(Number.isInteger(every) && every > 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() {
+        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) {
+        return this.#relay('bell', { endpoint: args.endpoint ?? null });
+    }
+    key() {
+        return this.#relay('key');
+    }
+    drop() {
+        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, args = {}) {
+        const standing = this.stance.standings.get(CLIENT);
+        return standing ? answered(await standing.ask(method, args)) : { error: 'no relay is held' };
+    }
+    #start() {
+        if (!this.#awake || !this.stance.standings.get(CLIENT))
+            return;
+        this.#stop();
+        let stopped = false;
+        const rests = new Set();
+        this.#stop = () => {
+            stopped = true;
+            for (const end of rests)
+                end();
+        };
+        const rest = (ms) => 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;
+        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) {
+        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.boxes) ? out.boxes : 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, box: reply === null ? null : hex(reply) });
+        }
+        return boxes.length;
+    }
+};

package/dist/harbor/root-line.d.ts

@@ -0,0 +1,9 @@
+import { type JsonObject } from '../being/index.ts';
+import type { Harbor } from './harbor.ts';
+export type RootRequest = {
+    ward?: string;
+    method?: string;
+    args?: JsonObject;
+};
+export declare const readRootRequest: (value: unknown) => RootRequest | null;
+export declare const rootLine: (harbor: Harbor, value: unknown) => Promise<JsonObject>;

package/dist/harbor/root-line.js

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+// The root line: one request, one answer, both plain JSON, for whatever
+// carries the root's asks to a harbor in its own process. The command line
+// carries it over a local socket, and an edge route carries it the same way.
+//
+//   request  { ward?, method?, args? }    no ward is the box ward, no
+//                                         method the census
+//   answer   { answer }                   what the ward-being said
+//            { silence: true }            she said nothing
+//            { word }                     a kit word: unreached, late, ...
+//            { error }                    the request was not one, or the
+//                                         ward is none this harbor holds
+import { isSilence, isWord, told } from '../being/index.js';
+const object = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export const readRootRequest = (value) => {
+    if (!object(value))
+        return null;
+    const { ward, method, args } = value;
+    if ((ward !== undefined && typeof ward !== 'string') || (method !== undefined && typeof method !== 'string') || (args !== undefined && !object(args)))
+        return null;
+    return { ...(ward === undefined ? {} : { ward }), ...(method === undefined ? {} : { method }), ...(args === undefined ? {} : { args }) };
+};
+export const rootLine = async (harbor, value) => {
+    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) {
+        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) };
+    return { answer: out };
+};

package/dist/harbor/terrain.d.ts

@@ -1,8 +1,21 @@
-import type { Carrier, Clock, Custody, Entropy, Memory } from '../contract/index.ts';
+import type { Carrier, Clock, Custody, Entropy, Loader, Memory } from '../contract/index.ts';
+import type { GroundFaculty } from './carrying.ts';
+import type { Harbor } from './harbor.ts';
+export type Opening = {
+    readonly key: string;
+    readonly kind: string;
+};
 export declare abstract class Terrain {
     abstract readonly entropy: Entropy;
     abstract readonly clock: Clock;
     abstract readonly custody: Custody;
     abstract readonly memory: Memory;
+    abstract readonly loader: Loader;
     abstract readonly carrier: Carrier;
+    readonly faculties: readonly GroundFaculty[];
+    readonly opens: readonly Opening[];
+    readonly wakes: boolean;
+    claim(): Promise<void>;
+    stand(_harbor: Harbor): Promise<void>;
+    release(): Promise<void>;
 }

package/dist/harbor/terrain.js

@@ -1,2 +1,21 @@
 export class Terrain {
+    // The faculty classes this ground ships, its carriers among them, and
+    // those a new harbor opens.
+    faculties = [];
+    opens = [];
+    // Whether its carriers wake and listen where their cells say. A harbor
+    // opened for one ask and closed again dials and hears nothing.
+    wakes = 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() {
+        return Promise.resolve();
+    }
+    stand(_harbor) {
+        return Promise.resolve();
+    }
+    release() {
+        return Promise.resolve();
+    }
 }

package/dist/http/index.d.ts

@@ -0,0 +1,4 @@
+import type { Ground, GroundFaculty } from '../harbor/index.ts';
+import { type WebListen, type WebListener } from '../line/index.ts';
+export declare const webServe: (ground: Ground, listen: WebListen) => Promise<WebListener>;
+export declare const webGround: GroundFaculty;

package/dist/http/index.js

@@ -0,0 +1,156 @@
+// 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 } from 'node:http';
+import { MAX_BODY, MAX_POST, nothingBody, readBody, readPost, replyBody, webFaculty } from '../line/index.js';
+import { hex } from '../crypto/index.js';
+import { tcpAt } from '../quo/index.js';
+import { acceptKey, frameOf, isClientKey, OP, WsReader } from './websocket.js';
+const pathOf = (url) => {
+    const at = (url ?? '/').indexOf('?');
+    return at < 0 ? (url ?? '/') : (url ?? '/').slice(0, at);
+};
+const originOf = (origins, origin) => {
+    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, max) => new Promise((resolve, reject) => {
+    const parts = [];
+    let length = 0;
+    request.on('data', (chunk) => {
+        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, listen, request, response) => {
+    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 = 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, listen, request, socket) => {
+    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, payload) => {
+        if (!socket.destroyed)
+            socket.write(frameOf(opcode, payload));
+    };
+    const close = () => {
+        send(OP.close);
+        socket.end();
+    };
+    socket.on('data', (chunk) => {
+        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, listen) => {
+    const sockets = new Set();
+    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, 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();
+            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 = webFaculty(webServe);

package/dist/http/websocket.d.ts

@@ -0,0 +1,29 @@
+export declare const OP: {
+    readonly continuation: 0;
+    readonly text: 1;
+    readonly binary: 2;
+    readonly close: 8;
+    readonly ping: 9;
+    readonly pong: 10;
+};
+export declare const acceptKey: (key: string) => string;
+export declare const isClientKey: (key: unknown) => key is string;
+export declare const frameOf: (opcode: number, payload?: Uint8Array) => Uint8Array;
+export type WsEvent = {
+    type: 'binary';
+    data: Uint8Array;
+} | {
+    type: 'text';
+} | {
+    type: 'ping';
+    data: Uint8Array;
+} | {
+    type: 'close';
+} | {
+    type: 'bad';
+};
+export declare class WsReader {
+    #private;
+    constructor(max: number);
+    push(chunk: Uint8Array): WsEvent[];
+}