nervur 0.19.2 → 0.20.1

package/dist/quo/standing.d.ts

@@ -0,0 +1,39 @@
+import type { Invitation } from './invitation.ts';
+import { Ephemeral, type Draw } from './keys.ts';
+import { type Reply } from './reply.ts';
+export type Read = Reply | {
+    readonly nothing: true;
+};
+type Knock = {
+    readonly bytes: string;
+    readonly lid: string;
+    readonly next: string;
+    readonly edge: string;
+    readonly seq: number;
+};
+export type StandingState = {
+    readonly key: string | null;
+    readonly edge: string | null;
+    readonly sent: number;
+    readonly moved: number;
+    readonly knock: Knock | null;
+    readonly probed: boolean;
+};
+export declare const freshStanding: () => StandingState;
+export type Sent = {
+    readonly bytes: Uint8Array;
+    readonly lid: Ephemeral;
+    readonly next: string;
+    readonly edge: string;
+    readonly seq: number;
+};
+export declare class Standing {
+    #private;
+    readonly invitation: Invitation;
+    state: StandingState;
+    readonly draw: Draw;
+    constructor(invitation: Invitation, state: StandingState, draw: Draw);
+    ask(method?: string, args?: string): Promise<Sent | null>;
+    read(sent: Sent, bytes: Uint8Array | null): Promise<Read>;
+}
+export {};

package/dist/quo/standing.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+// The standing's side of a relation: it seals asks and reads replies, and
+// moves to its announced key and the following edge key when an object
+// comes back to an ask above every ask it has moved on, and on nothing else.
+//
+// Its state is a value, so a ward keeps it in its partition.
+import { encapsulate, hex, unhex } from '../crypto/index.js';
+import { Ephemeral, SigningKey, wardHalves } from './keys.js';
+import { writePayload } from './payload.js';
+import { readReply } from './reply.js';
+import { checkBody, follow, knockEdge, openReply, sealAsk, signBody, splitBody } from './seal.js';
+export const freshStanding = () => ({ key: null, edge: null, sent: 0, moved: 0, knock: null, probed: false });
+export class Standing {
+    invitation;
+    state;
+    draw;
+    constructor(invitation, state, draw) {
+        this.invitation = invitation;
+        this.state = state;
+        this.draw = draw;
+    }
+    async ask(method, args) {
+        const s = this.state;
+        if (s.key !== null)
+            return this.#ask(unhex(s.key), unhex(s.edge), method, args);
+        if (s.knock === null)
+            return this.#knock(method, args);
+        if (!s.probed) {
+            this.state = { ...s, probed: true };
+            return this.#ask(unhex(s.knock.next), unhex(s.knock.edge), method, args);
+        }
+        this.state = { ...s, probed: false };
+        // The same bytes again: a new lid would be a new box.
+        return { bytes: unhex(s.knock.bytes), lid: await Ephemeral.from(unhex(s.knock.lid)), next: s.knock.next, edge: s.knock.edge, seq: s.knock.seq };
+    }
+    async read(sent, bytes) {
+        if (bytes === null)
+            return { nothing: true };
+        const reply = await this.#open(sent, bytes);
+        if (reply === null)
+            return { silence: true };
+        if ('object' in reply.text && sent.seq > this.state.moved) {
+            const edge = await follow(unhex(sent.edge), reply.agreement);
+            this.state = { ...this.state, key: sent.next, edge: hex(edge), moved: sent.seq, knock: null, probed: false };
+        }
+        return reply.text;
+    }
+    async #knock(method, args) {
+        const heir = await SigningKey.from(unhex(this.invitation.secret));
+        const next = await SigningKey.draw(this.draw);
+        const lid = await Ephemeral.draw(this.draw);
+        const sent = encapsulate(unhex(this.invitation.lock), this.draw(32));
+        if (sent === null)
+            return null;
+        const edge = await knockEdge(sent.shared);
+        const seq = this.state.sent + 1;
+        const body = await this.#body(heir, next, seq, method, args);
+        const bytes = await sealAsk(lid, unhex(wardHalves(this.invitation.ward).padlock), unhex(this.invitation.heir), edge, body, sent.ciphertext);
+        if (bytes === null)
+            return null;
+        this.state = { ...this.state, sent: seq, knock: { bytes: hex(bytes), lid: hex(lid.secret), next: hex(next.secret), edge: hex(edge), seq } };
+        return { bytes, lid, next: hex(next.secret), edge: hex(edge), seq };
+    }
+    async #ask(secret, edge, method, args) {
+        const by = await SigningKey.from(secret);
+        const next = await SigningKey.draw(this.draw);
+        const lid = await Ephemeral.draw(this.draw);
+        const seq = this.state.sent + 1;
+        const body = await this.#body(by, next, seq, method, args);
+        const bytes = await sealAsk(lid, unhex(wardHalves(this.invitation.ward).padlock), unhex(this.invitation.heir), edge, body);
+        if (bytes === null)
+            return null;
+        this.state = { ...this.state, sent: seq };
+        return { bytes, lid, next: hex(next.secret), edge: hex(edge), seq };
+    }
+    #body(by, next, seq, method, args) {
+        const text = writePayload({ to: this.invitation.heir, by: by.id, next: next.id, seq, ...(method === undefined ? {} : { method }), ...(args === undefined ? {} : { args }) });
+        return signBody(new TextEncoder().encode(text), by);
+    }
+    async #open(sent, bytes) {
+        const opened = await openReply(bytes, sent.lid);
+        const body = opened && splitBody(opened.bytes);
+        if (!opened || !body)
+            return null;
+        if (!(await checkBody(unhex(wardHalves(this.invitation.ward).signing), body)))
+            return null;
+        const text = readReply(body.text);
+        return text && { text, agreement: opened.agreement };
+    }
+}

package/dist/tcp/frame.d.ts

@@ -0,0 +1,29 @@
+export declare const ASK = 0;
+export declare const REPLY = 1;
+export declare const NOTHING = 2;
+export declare const MAX_BODY = 1048645;
+export type Frame = {
+    kind: 'ask';
+    id: number;
+    pk: Uint8Array;
+    box: Uint8Array;
+} | {
+    kind: 'reply';
+    id: number;
+    box: Uint8Array;
+} | {
+    kind: 'nothing';
+    id: number;
+};
+export declare const askFrame: (id: number, pk: Uint8Array, box: Uint8Array) => Uint8Array;
+export declare const replyFrame: (id: number, box: Uint8Array) => Uint8Array;
+export declare const nothingFrame: (id: number) => Uint8Array;
+export declare class FrameReader {
+    #private;
+    get bad(): boolean;
+    push(chunk: Uint8Array): Frame[];
+}
+export declare const parseAt: (at: unknown) => {
+    host: string;
+    port: number;
+} | null;

package/dist/tcp/frame.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+// The frames of Quo over TCP, `quo/CARRIER-TCP.md`:
+//
+//   frame = length (4, big-endian) || kind (1) || id (4, big-endian) || rest
+//   00 ask      rest = ward pk (64) || box
+//   01 reply    rest = box
+//   02 nothing  rest = empty
+//
+// A reader says a stream is not a frame as soon as its bytes say so, and
+// reads nothing after it.
+import { concat } from '../crypto/index.js';
+export const ASK = 0;
+export const REPLY = 1;
+export const NOTHING = 2;
+export const MAX_BODY = 1_048_645;
+const PK = 64;
+const frame = (kind, id, ...rest) => {
+    const head = new Uint8Array(9);
+    const view = new DataView(head.buffer);
+    view.setUint32(0, 5 + rest.reduce((n, r) => n + r.length, 0));
+    head[4] = kind;
+    view.setUint32(5, id >>> 0);
+    return concat(head, ...rest);
+};
+export const askFrame = (id, pk, box) => frame(ASK, id, pk, box);
+export const replyFrame = (id, box) => frame(REPLY, id, box);
+export const nothingFrame = (id) => frame(NOTHING, id);
+// Whether a body of this length, and this first byte when known, is no frame.
+const notAFrame = (length, kind) => length > MAX_BODY || length < 5 || (kind !== undefined && (kind > NOTHING || (kind === ASK && length < 5 + PK) || (kind === NOTHING && length !== 5)));
+export class FrameReader {
+    #buffer = new Uint8Array(0);
+    #bad = false;
+    // True once bytes that are not a frame arrived; nothing is read after.
+    get bad() {
+        return this.#bad;
+    }
+    push(chunk) {
+        if (this.#bad)
+            return [];
+        this.#buffer = this.#buffer.length === 0 ? chunk.slice() : concat(this.#buffer, chunk);
+        const out = [];
+        while (this.#buffer.length >= 4) {
+            const view = new DataView(this.#buffer.buffer, this.#buffer.byteOffset);
+            const length = view.getUint32(0);
+            if (notAFrame(length, this.#buffer.length > 4 ? this.#buffer[4] : undefined)) {
+                this.#bad = true;
+                this.#buffer = new Uint8Array(0);
+                return out;
+            }
+            if (this.#buffer.length < 4 + length)
+                break;
+            const body = this.#buffer.subarray(4, 4 + length);
+            this.#buffer = this.#buffer.slice(4 + length);
+            const id = new DataView(body.buffer, body.byteOffset).getUint32(1);
+            if (body[0] === ASK)
+                out.push({ kind: 'ask', id, pk: body.slice(5, 5 + PK), box: body.slice(5 + PK) });
+            else if (body[0] === REPLY)
+                out.push({ kind: 'reply', id, box: body.slice(5) });
+            else
+                out.push({ kind: 'nothing', id });
+        }
+        return out;
+    }
+}
+// "host:port" to its parts, or null. A host in brackets is an IPv6 address.
+export const parseAt = (at) => {
+    if (typeof at !== 'string')
+        return null;
+    const m = /^(?:\[([^\]]+)\]|([^:[\]]+)):(\d{1,5})$/.exec(at);
+    if (!m)
+        return null;
+    const port = Number(m[3]);
+    return port > 0 && port < 65_536 ? { host: m[1] ?? m[2], port } : null;
+};

package/dist/tcp/index.d.ts

@@ -0,0 +1,18 @@
+import { Carrier } from '../contract/index.ts';
+export { parseAt } from './frame.ts';
+export interface Doors {
+    arrive(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+}
+export declare class TcpCarrier extends Carrier {
+    #private;
+    route(pk: string, at: string | null): boolean;
+    carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+    close(): Promise<void>;
+}
+export declare class TcpListener {
+    #private;
+    private constructor();
+    static listen(doors: Doors, host?: string, port?: number): Promise<TcpListener>;
+    get at(): string;
+    close(): Promise<void>;
+}

package/dist/tcp/index.js

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: Apache-2.0
+// Quo over TCP: `nervur/tcp`, an entry that names a platform, Node's
+// sockets.
+//
+//   TcpCarrier    a Carrier that dials: bytes to a ward pk go in an ask
+//                 frame to the address its book holds for that pk
+//   TcpListener   answers ask frames for the doors it is handed, a harbor
+//                 among them
+//
+// Where a ward is reached is the carrier's own, and never on the wire. A
+// connection is opened per address, carries many asks at once, and is
+// dropped when either side closes it; the next ask dials again.
+import { connect, createServer } from 'node:net';
+import { hex, isHex, unhex } from '../crypto/index.js';
+import { Carrier } from '../contract/index.js';
+import { askFrame, FrameReader, nothingFrame, parseAt, replyFrame } from './frame.js';
+export { parseAt } from './frame.js';
+const MAX_ID = 0xffff_ffff;
+class Dialed {
+    #socket;
+    #reader = new FrameReader();
+    #waiting = new Map();
+    #next = 1;
+    closed = false;
+    constructor(socket, onClose) {
+        this.#socket = socket;
+        socket.on('data', (chunk) => {
+            for (const f of this.#reader.push(new Uint8Array(chunk))) {
+                if (f.kind === 'ask')
+                    continue;
+                const resolve = this.#waiting.get(f.id);
+                this.#waiting.delete(f.id);
+                resolve?.(f.kind === 'reply' ? f.box : null);
+            }
+            if (this.#reader.bad)
+                socket.destroy();
+        });
+        socket.on('error', () => socket.destroy());
+        socket.on('close', () => {
+            this.closed = true;
+            onClose();
+            for (const resolve of this.#waiting.values())
+                resolve(null);
+            this.#waiting.clear();
+        });
+    }
+    static open(host, port, onClose) {
+        return new Promise((resolve) => {
+            const socket = connect({ host, port });
+            socket.once('connect', () => resolve(new Dialed(socket, onClose)));
+            socket.once('error', () => {
+                socket.destroy();
+                resolve(null);
+            });
+        });
+    }
+    ask(pk, box) {
+        if (this.closed)
+            return Promise.resolve(null);
+        const id = this.#next;
+        this.#next = this.#next === MAX_ID ? 1 : this.#next + 1;
+        return new Promise((resolve) => {
+            this.#waiting.set(id, resolve);
+            this.#socket.write(askFrame(id, pk, box));
+        });
+    }
+    close() {
+        this.#socket.destroy();
+    }
+}
+export class TcpCarrier extends Carrier {
+    #routes = new Map();
+    #lines = new Map();
+    // The address a ward pk is reached at, replacing any before, or null to
+    // forget it.
+    route(pk, at) {
+        if (!isHex(pk, 64) || (at !== null && parseAt(at) === null))
+            return false;
+        if (at === null)
+            this.#routes.delete(pk);
+        else
+            this.#routes.set(pk, at);
+        return true;
+    }
+    // Nothing where the pk has no route, the address is not reached, or the
+    // connection closed before an answer.
+    async carry(pk, bytes) {
+        const at = this.#routes.get(pk);
+        if (at === undefined)
+            return null;
+        const line = await this.#line(at);
+        return line ? line.ask(unhex(pk), bytes) : null;
+    }
+    #line(at) {
+        let line = this.#lines.get(at);
+        if (!line) {
+            const { host, port } = parseAt(at);
+            line = Dialed.open(host, port, () => this.#lines.delete(at)).then((dialed) => {
+                if (!dialed)
+                    this.#lines.delete(at);
+                return dialed;
+            });
+            this.#lines.set(at, line);
+        }
+        return line;
+    }
+    async close() {
+        const lines = [...this.#lines.values()];
+        this.#lines.clear();
+        for (const line of await Promise.all(lines))
+            line?.close();
+    }
+}
+export class TcpListener {
+    #server;
+    #doors;
+    #sockets = new Set();
+    constructor(doors) {
+        this.#doors = doors;
+        this.#server = createServer((socket) => this.#serve(socket));
+    }
+    // A listener on `host` and `port`, 127.0.0.1 and a free port unless named.
+    static listen(doors, host = '127.0.0.1', port = 0) {
+        const listener = new TcpListener(doors);
+        return new Promise((resolve, reject) => {
+            listener.#server.once('error', reject);
+            listener.#server.listen(port, host, () => resolve(listener));
+        });
+    }
+    get at() {
+        const address = this.#server.address();
+        return address.family === 'IPv6' ? `[${address.address}]:${address.port}` : `${address.address}:${address.port}`;
+    }
+    #serve(socket) {
+        this.#sockets.add(socket);
+        const reader = new FrameReader();
+        socket.on('data', (chunk) => {
+            for (const f of reader.push(new Uint8Array(chunk))) {
+                if (f.kind === 'ask')
+                    void this.#answer(socket, f.id, f.pk, f.box);
+            }
+            if (reader.bad)
+                socket.destroy();
+        });
+        socket.on('error', () => socket.destroy());
+        socket.on('close', () => this.#sockets.delete(socket));
+    }
+    async #answer(socket, id, pk, box) {
+        let reply = null;
+        try {
+            reply = await this.#doors.arrive(hex(pk), box);
+        }
+        catch {
+            reply = null;
+        }
+        if (!socket.destroyed)
+            socket.write(reply === null ? nothingFrame(id) : replyFrame(id, reply));
+    }
+    close() {
+        for (const socket of this.#sockets)
+            socket.destroy();
+        return new Promise((resolve) => this.#server.close(() => resolve()));
+    }
+}

package/dist/ward/allowance.d.ts

@@ -1,10 +1,14 @@
-import type { Wanted } from '../being/types.ts';
-export type Allowance = {
-    time: number;
-};
-export declare const DEFAULT: Allowance;
-export declare const CEILING: Allowance;
-export declare function allow(wanted: Wanted | undefined, ceiling?: Allowance, base?: Allowance): Allowance;
-export declare const spent: (a: Allowance) => boolean;
+import type { Clock } from '../contract/index.ts';
+import type { Wanted } from '../being/index.ts';
+export declare const DEFAULT = 30000;
+export declare const CEILING = 300000;
+export declare const allow: (wanted: Wanted | undefined) => number;
 export declare const LATE: unique symbol;
-export declare function within<T>(ms: number, work: Promise<T>, rang?: () => void): Promise<T | typeof LATE>;
+export type Late = typeof LATE;
+export declare class Bell {
+    #private;
+    constructor(clock: Clock, ms: number);
+    get rang(): boolean;
+    race<T>(work: Promise<T>): Promise<T | Late>;
+    cancel(): void;
+}

package/dist/ward/allowance.js

@@ -1,71 +1,32 @@
-// SPDX-License-Identifier: Apache-2.0
-// The allowance. Every ask carries, in its signed body, the time it may still
-// spend, in milliseconds. A being who says nothing gets her ward's default and
-// never thinks about it; one who wants to say so passes a third argument, and
-// is held to the ward's ceiling. The door reads it before anything is done
-// under it and refuses a budget already gone, as one silence like every other
-// refusal there. The sender bounds the whole of her ask to the same number,
-// and a wait that ran out is the word late, never silence and never unreached.
-//
-// Each ask is bounded on its own. The time an arriving call has left does not
-// bound the asks a being makes while answering it: attributing her onward ask
-// to the arrival that caused it needs a context the ward cannot get without
-// naming a runtime, and the ward names none. Every wait still ends.
-// How wide the default is, and how wide she may ask for, are the ward's own —
-// wider is more patient, and no peer can tell the difference except by being
-// refused. A being who never learns the third parameter exists writes correct
-// code forever under these. They are two numbers because the third argument
-// goes both ways: less for the ask she wants back quickly, more for the one
-// she knows is slow.
-export const DEFAULT = { time: 30_000 };
-export const CEILING = { time: 300_000 };
-// What she asked for, held to what her ward allows. A being cannot mint budget
-// nobody granted her: asking for a minute where the ward gives thirty seconds
-// is thirty seconds, silently, because the ceiling is not hers to know.
-// Asking for nothing at all is the default, which is the whole point.
-export function allow(wanted, ceiling = CEILING, base = DEFAULT) {
-    // Floored first, then tested: a fraction of a millisecond is not a budget,
-    // and falls to the default like every other number that is not a positive
-    // whole one.
-    const whole = (n, fallback) => {
-        const w = typeof n === 'number' ? Math.floor(n) : NaN;
-        return Number.isFinite(w) && w > 0 ? w : fallback;
-    };
-    return { time: Math.min(whole(wanted?.time, base.time), ceiling.time) };
-}
-// Whether a budget has anything left to spend, and the one reader of it: the
-// door calls this on arrival and nothing else asks the question anywhere. A
-// time that is not a whole number above zero is not a budget that ran out, it
-// is no budget at all, and the door refuses both the same way, since a peer
-// learns nothing from the difference. `allow` never makes one, so only bytes
-// off the road ever carry one.
-export const spent = (a) => !(Number.isSafeInteger(a.time) && a.time > 0);
-// What a wait that ran out comes back as. Its own value, held by nobody
-// outside the ward, so no answer from any door can be mistaken for it.
+export const DEFAULT = 30_000;
+export const CEILING = 300_000;
+export const allow = (wanted) => {
+    const whole = typeof wanted?.time === 'number' ? Math.floor(wanted.time) : NaN;
+    return Math.min(Number.isFinite(whole) && whole > 0 ? whole : DEFAULT, CEILING);
+};
 export const LATE = Symbol('late');
-// A wait with an end. This is the one thing the ward times, and it covers the
-// whole of an ask, not only the wire: a relation that comes back round is
-// stopped at its own lane, before a single byte is sealed, and a bound that
-// only watched the wire would never see it. A timer is the only way to stop
-// waiting and every language that runs Quo has one; no runtime is named here.
-//
-// `rang` is called the moment the bell rings, before anyone waiting on the
-// wait is told: whoever holds work that has not started yet reads it and does
-// not start it. What comes back late is not read, and what has not left yet
-// does not leave.
-export async function within(ms, work, rang) {
-    let timer;
-    const bell = new Promise((ring) => {
-        timer = setTimeout(() => {
-            rang?.();
-            ring(LATE);
-        }, ms);
-    });
-    try {
-        return await Promise.race([work, bell]);
+// One ask's bell. It bounds the wait of the being who asked and the send
+// that holds the relation's line, so a far side that never answers holds
+// neither for longer than the allowance.
+export class Bell {
+    #wait;
+    #late;
+    #rang = false;
+    constructor(clock, ms) {
+        this.#wait = clock.wait(ms);
+        this.#late = this.#wait.done.then(() => {
+            this.#rang = true;
+            return LATE;
+        });
+    }
+    get rang() {
+        return this.#rang;
+    }
+    race(work) {
+        work.catch(() => { });
+        return Promise.race([work, this.#late]);
     }
-    finally {
-        clearTimeout(timer);
-        void work.then(() => { }, () => { }); // whatever it was, it is nobody's answer now
+    cancel() {
+        this.#wait.cancel();
     }
 }

package/dist/ward/cells.d.ts

@@ -1,7 +1,7 @@
-import type { Cells } from '../being/types.ts';
+import type { JsonObject } from '../being/index.ts';
 export declare const DEPTH = 64;
-export declare const BREADTH: number;
-export declare const cellFault: (v: unknown, path: string) => string | null;
-export declare const unkeepable: (k: string) => boolean;
-export declare const guardCells: (cells: Cells, wrote?: () => void) => Cells;
-export declare const unguarded: (cells: Cells) => Cells;
+export declare class Cells {
+    #private;
+    constructor(wrote: () => void);
+    guard(cells: JsonObject): JsonObject;
+}