@earendil-works/chord 1.4.0 → 1.5.1

package/dist/link/part.d.ts

@@ -0,0 +1,80 @@
+import type { Context } from "../context/index.ts";
+import { ChordError } from "../data/index.ts";
+/**
+ * A part (R1): a value as JSON text at its origin (and after a text decode), its UTF-8 bytes once a binary codec
+ * received it (or at an origin that encoded it already), or those bytes deflated by an origin that compresses. Opaque
+ * on the way: only the end that owns it opens and parses it, while handling its message (a malformed part is a protocol
+ * error then), so a relay forwards it unparsed and still deflated.
+ */
+export type Part = string | Uint8Array | DeflatedPart;
+/** What inflating a deflated part gave: its JSON bytes, more than the decoded limit, or data that is no raw deflate. */
+export type Inflated = {
+    readonly kind: "bytes";
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: "too_large";
+} | {
+    readonly kind: "corrupt";
+    readonly error: unknown;
+};
+/**
+ * A JSON part deflated (raw deflate) by its origin. A host without a synchronous compressor inflates it before its
+ * owner handles the message (`inflateAsync`) and keeps the outcome here for the owner to open.
+ */
+export declare class DeflatedPart {
+    readonly bytes: Uint8Array;
+    /** The asynchronous inflate's outcome; `undefined` until one ran. */
+    inflated: Inflated | undefined;
+    constructor(bytes: Uint8Array);
+}
+/**
+ * A synchronous compressor (`createHost({ compression })`; `nodeCompression` for Node). `deflate` is raw deflate at
+ * level 1. `inflate` gives at most `limit` bytes (`Infinity`: no limit; 0 allowed), `too_large` when the output would
+ * be larger, `corrupt` for data that is no raw deflate stream.
+ */
+export interface Compression {
+    deflate(bytes: Uint8Array): Uint8Array;
+    inflate(bytes: Uint8Array, limit: number): Inflated;
+}
+/** A link's limits per part as `accept`, `connect` and `resolve` take them, in bytes. */
+export type PartLimits = {
+    /** A part's size on the wire. */
+    readonly part?: number;
+    /** A part's size after inflating it. */
+    readonly decoded?: number;
+};
+/** A link's limits in force; `Infinity` for none. */
+export type Limits = {
+    readonly part: number;
+    readonly decoded: number;
+};
+/** The limits of a link: the ones set, the defaults of its trust for the others. */
+export declare function linkLimits(trusted: boolean, limits?: PartLimits): Limits;
+/** JSON parts above this many UTF-8 bytes are compressed at their origin (a protocol constant). */
+export declare const COMPRESS_ABOVE: number;
+/**
+ * A JSON part at its origin: deflated when the host compresses, its UTF-8 bytes are above `COMPRESS_ABOVE` and
+ * deflating made it smaller; otherwise the text, or its bytes once they were encoded (never encoded twice). Counts one
+ * deflate (`chord.link.deflates`).
+ */
+export declare function originPart(json: string, compression: Compression | undefined, context: Context): Part;
+/**
+ * The `too_large/part` error of a part whose size on the wire (its UTF-8 bytes; a deflated part's deflated bytes) is
+ * above `limit`; `undefined` within it. Nothing is parsed or inflated.
+ */
+export declare function oversized(part: Part, limit: number): ChordError | undefined;
+/**
+ * The JSON of a part its owner is about to parse: its size checked against `limits.part` first, then its decoded size
+ * against `limits.decoded`, a deflated part inflated within it (synchronously with `compression`, or by the
+ * asynchronous inflate that ran ahead of its owner). Throws `too_large/part` past a limit; throws a plain error for a
+ * deflated part nothing inflated or that is no raw deflate stream (a protocol error). Counts one synchronous inflate
+ * (`chord.link.inflates`).
+ */
+export declare function openPart(part: Part, limits: Limits, compression: Compression | undefined, context: Context): string | Uint8Array;
+/**
+ * Inflates `part` with the web `DecompressionStream` (a host without a synchronous compressor), counting output bytes
+ * and stopping past `limit`; the outcome is kept on the part. `signal` (the link's close) cancels the stream at once,
+ * leaving no outcome. Counts one inflate (`chord.link.inflates`).
+ */
+export declare function inflateAsync(part: DeflatedPart, limit: number, signal: AbortSignal, context: Context): Promise<void>;
+//# sourceMappingURL=part.d.ts.map

package/dist/link/part.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"part.d.ts","sourceRoot":"","sources":["../../src/link/part.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,UAAU,GAAG,YAAY,CAAC;AAEtD,wHAAwH;AACxH,MAAM,MAAM,QAAQ,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEzD;;;GAGG;AACH,qBAAa,YAAY;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IAE/B,YAAY,KAAK,EAAE,UAAU,EAE5B;CACD;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC;IACvC,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;CACpD;AAED,yFAAyF;AACzF,MAAM,MAAM,UAAU,GAAG;IACxB,iCAAiC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,qDAAqD;AACrD,MAAM,MAAM,MAAM,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AASzE,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAE,UAAe,GAAG,MAAM,CAG5E;AAED,mGAAmG;AACnG,eAAO,MAAM,cAAc,QAAY,CAAC;AAIxC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAQrG;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAI3E;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACvB,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,OAAO,EAAE,OAAO,GACd,MAAM,GAAG,UAAU,CAuBrB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CACjC,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC,CAqCf"}

package/dist/link/part.js

@@ -0,0 +1,165 @@
+// Parts on links (R1, R2, Q2, §22): a value as it crosses a link (JSON text at its origin, its bytes once received, or
+// deflated by its origin), the size limits per part, compression at the origin, and opening a part where it is owned:
+// its size checked before anything is parsed or inflated, a deflated part inflated within the decoded limit.
+import { ChordError } from "../data/index.js";
+import { chordMetrics } from "../telemetry.js";
+/**
+ * A JSON part deflated (raw deflate) by its origin. A host without a synchronous compressor inflates it before its
+ * owner handles the message (`inflateAsync`) and keeps the outcome here for the owner to open.
+ */
+export class DeflatedPart {
+    bytes;
+    /** The asynchronous inflate's outcome; `undefined` until one ran. */
+    inflated;
+    constructor(bytes) {
+        this.bytes = bytes;
+    }
+}
+const MiB = 1024 * 1024;
+/** The limits of untrusted links unless set (Q2); trusted links (IPC) have none. */
+const UNTRUSTED = { part: 16 * MiB, decoded: 64 * MiB };
+const NONE = { part: Number.POSITIVE_INFINITY, decoded: Number.POSITIVE_INFINITY };
+/** The limits of a link: the ones set, the defaults of its trust for the others. */
+export function linkLimits(trusted, limits = {}) {
+    const defaults = trusted ? NONE : UNTRUSTED;
+    return { part: limits.part ?? defaults.part, decoded: limits.decoded ?? defaults.decoded };
+}
+/** JSON parts above this many UTF-8 bytes are compressed at their origin (a protocol constant). */
+export const COMPRESS_ABOVE = 16 * 1024;
+const UTF8 = new TextEncoder();
+/**
+ * A JSON part at its origin: deflated when the host compresses, its UTF-8 bytes are above `COMPRESS_ABOVE` and
+ * deflating made it smaller; otherwise the text, or its bytes once they were encoded (never encoded twice). Counts one
+ * deflate (`chord.link.deflates`).
+ */
+export function originPart(json, compression, context) {
+    // A UTF-16 unit is at most three UTF-8 bytes: a text this short is within the threshold without encoding it.
+    if (compression === undefined || json.length * 3 <= COMPRESS_ABOVE)
+        return json;
+    const bytes = UTF8.encode(json);
+    if (bytes.byteLength <= COMPRESS_ABOVE)
+        return bytes;
+    chordMetrics(context.telemetry.metrics).counter("chord.link.deflates").add(1);
+    const deflated = compression.deflate(bytes);
+    return deflated.byteLength < bytes.byteLength ? new DeflatedPart(deflated) : bytes;
+}
+/**
+ * The `too_large/part` error of a part whose size on the wire (its UTF-8 bytes; a deflated part's deflated bytes) is
+ * above `limit`; `undefined` within it. Nothing is parsed or inflated.
+ */
+export function oversized(part, limit) {
+    if (limit === Number.POSITIVE_INFINITY)
+        return undefined;
+    const size = sizeOf(part);
+    return size > limit ? tooLarge(size, limit, "wire") : undefined;
+}
+/**
+ * The JSON of a part its owner is about to parse: its size checked against `limits.part` first, then its decoded size
+ * against `limits.decoded`, a deflated part inflated within it (synchronously with `compression`, or by the
+ * asynchronous inflate that ran ahead of its owner). Throws `too_large/part` past a limit; throws a plain error for a
+ * deflated part nothing inflated or that is no raw deflate stream (a protocol error). Counts one synchronous inflate
+ * (`chord.link.inflates`).
+ */
+export function openPart(part, limits, compression, context) {
+    const wire = oversized(part, limits.part);
+    if (wire !== undefined)
+        throw wire;
+    if (!(part instanceof DeflatedPart)) {
+        // Not deflated: its decoded size is its size.
+        const size = limits.decoded === Number.POSITIVE_INFINITY ? 0 : sizeOf(part);
+        if (size > limits.decoded)
+            throw tooLarge(size, limits.decoded, "decoded");
+        return part;
+    }
+    let inflated = part.inflated;
+    if (inflated === undefined) {
+        if (compression === undefined)
+            throw new Error("part: a deflated part this host did not inflate");
+        chordMetrics(context.telemetry.metrics).counter("chord.link.inflates").add(1);
+        inflated = compression.inflate(part.bytes, limits.decoded);
+    }
+    switch (inflated.kind) {
+        case "bytes":
+            return inflated.bytes;
+        case "too_large":
+            throw tooLarge(undefined, limits.decoded, "decoded");
+        case "corrupt":
+            throw new Error("part: no raw deflate stream", { cause: inflated.error });
+    }
+}
+/**
+ * Inflates `part` with the web `DecompressionStream` (a host without a synchronous compressor), counting output bytes
+ * and stopping past `limit`; the outcome is kept on the part. `signal` (the link's close) cancels the stream at once,
+ * leaving no outcome. Counts one inflate (`chord.link.inflates`).
+ */
+export async function inflateAsync(part, limit, signal, context) {
+    chordMetrics(context.telemetry.metrics).counter("chord.link.inflates").add(1);
+    const reader = new Blob([part.bytes])
+        .stream()
+        .pipeThrough(new DecompressionStream("deflate-raw"))
+        .getReader();
+    // A pending read settles once cancelled: nothing of the stream outlives the link.
+    const cancel = () => void reader.cancel().catch(() => { });
+    signal.addEventListener("abort", cancel, { once: true });
+    const chunks = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done || signal.aborted)
+                break;
+            length += value.byteLength;
+            if (length > limit) {
+                cancel();
+                part.inflated = { kind: "too_large" };
+                return;
+            }
+            chunks.push(value);
+        }
+    }
+    catch (error) {
+        if (!signal.aborted)
+            part.inflated = { kind: "corrupt", error };
+        return;
+    }
+    finally {
+        signal.removeEventListener("abort", cancel);
+    }
+    if (signal.aborted)
+        return;
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    part.inflated = { kind: "bytes", bytes };
+}
+/** A part's size on the wire: its UTF-8 bytes (counted for text, without encoding it). */
+function sizeOf(part) {
+    if (typeof part !== "string")
+        return part instanceof DeflatedPart ? part.bytes.byteLength : part.byteLength;
+    let size = part.length;
+    for (let index = 0; index < part.length; index++) {
+        const unit = part.charCodeAt(index);
+        if (unit < 0x80)
+            continue;
+        if (unit < 0x800)
+            size += 1;
+        else if (unit >= 0xd800 && unit < 0xdc00 && (part.charCodeAt(index + 1) & 0xfc00) === 0xdc00) {
+            // A surrogate pair: four bytes for two units.
+            size += 2;
+            index++;
+        }
+        else
+            size += 2;
+    }
+    return size;
+}
+/** The error of a part past a limit (`size` unknown while inflating). */
+function tooLarge(size, limit, measure) {
+    const what = size === undefined ? "a part" : `a part of ${size} bytes`;
+    const message = `${what} is over the ${measure} limit of ${limit} bytes`;
+    return new ChordError({ code: "too_large", reason: "part", message });
+}
+//# sourceMappingURL=part.js.map

package/dist/link/part.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"part.js","sourceRoot":"","sources":["../../src/link/part.ts"],"names":[],"mappings":"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","sourcesContent":["// Parts on links (R1, R2, Q2, §22): a value as it crosses a link (JSON text at its origin, its bytes once received, or\n// deflated by its origin), the size limits per part, compression at the origin, and opening a part where it is owned:\n// its size checked before anything is parsed or inflated, a deflated part inflated within the decoded limit.\n\nimport type { Context } from \"../context/index.ts\";\nimport { ChordError } from \"../data/index.ts\";\nimport { chordMetrics } from \"../telemetry.ts\";\n\n/**\n * A part (R1): a value as JSON text at its origin (and after a text decode), its UTF-8 bytes once a binary codec\n * received it (or at an origin that encoded it already), or those bytes deflated by an origin that compresses. Opaque\n * on the way: only the end that owns it opens and parses it, while handling its message (a malformed part is a protocol\n * error then), so a relay forwards it unparsed and still deflated.\n */\nexport type Part = string | Uint8Array | DeflatedPart;\n\n/** What inflating a deflated part gave: its JSON bytes, more than the decoded limit, or data that is no raw deflate. */\nexport type Inflated =\n\t| { readonly kind: \"bytes\"; readonly bytes: Uint8Array }\n\t| { readonly kind: \"too_large\" }\n\t| { readonly kind: \"corrupt\"; readonly error: unknown };\n\n/**\n * A JSON part deflated (raw deflate) by its origin. A host without a synchronous compressor inflates it before its\n * owner handles the message (`inflateAsync`) and keeps the outcome here for the owner to open.\n */\nexport class DeflatedPart {\n\treadonly bytes: Uint8Array;\n\t/** The asynchronous inflate's outcome; `undefined` until one ran. */\n\tinflated: Inflated | undefined;\n\n\tconstructor(bytes: Uint8Array) {\n\t\tthis.bytes = bytes;\n\t}\n}\n\n/**\n * A synchronous compressor (`createHost({ compression })`; `nodeCompression` for Node). `deflate` is raw deflate at\n * level 1. `inflate` gives at most `limit` bytes (`Infinity`: no limit; 0 allowed), `too_large` when the output would\n * be larger, `corrupt` for data that is no raw deflate stream.\n */\nexport interface Compression {\n\tdeflate(bytes: Uint8Array): Uint8Array;\n\tinflate(bytes: Uint8Array, limit: number): Inflated;\n}\n\n/** A link's limits per part as `accept`, `connect` and `resolve` take them, in bytes. */\nexport type PartLimits = {\n\t/** A part's size on the wire. */\n\treadonly part?: number;\n\t/** A part's size after inflating it. */\n\treadonly decoded?: number;\n};\n\n/** A link's limits in force; `Infinity` for none. */\nexport type Limits = { readonly part: number; readonly decoded: number };\n\nconst MiB = 1024 * 1024;\n\n/** The limits of untrusted links unless set (Q2); trusted links (IPC) have none. */\nconst UNTRUSTED: Limits = { part: 16 * MiB, decoded: 64 * MiB };\n\nconst NONE: Limits = { part: Number.POSITIVE_INFINITY, decoded: Number.POSITIVE_INFINITY };\n\n/** The limits of a link: the ones set, the defaults of its trust for the others. */\nexport function linkLimits(trusted: boolean, limits: PartLimits = {}): Limits {\n\tconst defaults = trusted ? NONE : UNTRUSTED;\n\treturn { part: limits.part ?? defaults.part, decoded: limits.decoded ?? defaults.decoded };\n}\n\n/** JSON parts above this many UTF-8 bytes are compressed at their origin (a protocol constant). */\nexport const COMPRESS_ABOVE = 16 * 1024;\n\nconst UTF8 = new TextEncoder();\n\n/**\n * A JSON part at its origin: deflated when the host compresses, its UTF-8 bytes are above `COMPRESS_ABOVE` and\n * deflating made it smaller; otherwise the text, or its bytes once they were encoded (never encoded twice). Counts one\n * deflate (`chord.link.deflates`).\n */\nexport function originPart(json: string, compression: Compression | undefined, context: Context): Part {\n\t// A UTF-16 unit is at most three UTF-8 bytes: a text this short is within the threshold without encoding it.\n\tif (compression === undefined || json.length * 3 <= COMPRESS_ABOVE) return json;\n\tconst bytes = UTF8.encode(json);\n\tif (bytes.byteLength <= COMPRESS_ABOVE) return bytes;\n\tchordMetrics(context.telemetry.metrics).counter(\"chord.link.deflates\").add(1);\n\tconst deflated = compression.deflate(bytes);\n\treturn deflated.byteLength < bytes.byteLength ? new DeflatedPart(deflated) : bytes;\n}\n\n/**\n * The `too_large/part` error of a part whose size on the wire (its UTF-8 bytes; a deflated part's deflated bytes) is\n * above `limit`; `undefined` within it. Nothing is parsed or inflated.\n */\nexport function oversized(part: Part, limit: number): ChordError | undefined {\n\tif (limit === Number.POSITIVE_INFINITY) return undefined;\n\tconst size = sizeOf(part);\n\treturn size > limit ? tooLarge(size, limit, \"wire\") : undefined;\n}\n\n/**\n * The JSON of a part its owner is about to parse: its size checked against `limits.part` first, then its decoded size\n * against `limits.decoded`, a deflated part inflated within it (synchronously with `compression`, or by the\n * asynchronous inflate that ran ahead of its owner). Throws `too_large/part` past a limit; throws a plain error for a\n * deflated part nothing inflated or that is no raw deflate stream (a protocol error). Counts one synchronous inflate\n * (`chord.link.inflates`).\n */\nexport function openPart(\n\tpart: Part,\n\tlimits: Limits,\n\tcompression: Compression | undefined,\n\tcontext: Context,\n): string | Uint8Array {\n\tconst wire = oversized(part, limits.part);\n\tif (wire !== undefined) throw wire;\n\tif (!(part instanceof DeflatedPart)) {\n\t\t// Not deflated: its decoded size is its size.\n\t\tconst size = limits.decoded === Number.POSITIVE_INFINITY ? 0 : sizeOf(part);\n\t\tif (size > limits.decoded) throw tooLarge(size, limits.decoded, \"decoded\");\n\t\treturn part;\n\t}\n\tlet inflated = part.inflated;\n\tif (inflated === undefined) {\n\t\tif (compression === undefined) throw new Error(\"part: a deflated part this host did not inflate\");\n\t\tchordMetrics(context.telemetry.metrics).counter(\"chord.link.inflates\").add(1);\n\t\tinflated = compression.inflate(part.bytes, limits.decoded);\n\t}\n\tswitch (inflated.kind) {\n\t\tcase \"bytes\":\n\t\t\treturn inflated.bytes;\n\t\tcase \"too_large\":\n\t\t\tthrow tooLarge(undefined, limits.decoded, \"decoded\");\n\t\tcase \"corrupt\":\n\t\t\tthrow new Error(\"part: no raw deflate stream\", { cause: inflated.error });\n\t}\n}\n\n/**\n * Inflates `part` with the web `DecompressionStream` (a host without a synchronous compressor), counting output bytes\n * and stopping past `limit`; the outcome is kept on the part. `signal` (the link's close) cancels the stream at once,\n * leaving no outcome. Counts one inflate (`chord.link.inflates`).\n */\nexport async function inflateAsync(\n\tpart: DeflatedPart,\n\tlimit: number,\n\tsignal: AbortSignal,\n\tcontext: Context,\n): Promise<void> {\n\tchordMetrics(context.telemetry.metrics).counter(\"chord.link.inflates\").add(1);\n\tconst reader = new Blob([part.bytes as Uint8Array<ArrayBuffer>])\n\t\t.stream()\n\t\t.pipeThrough(new DecompressionStream(\"deflate-raw\"))\n\t\t.getReader();\n\t// A pending read settles once cancelled: nothing of the stream outlives the link.\n\tconst cancel = (): void => void reader.cancel().catch(() => {});\n\tsignal.addEventListener(\"abort\", cancel, { once: true });\n\tconst chunks: Uint8Array[] = [];\n\tlet length = 0;\n\ttry {\n\t\tfor (;;) {\n\t\t\tconst { done, value } = await reader.read();\n\t\t\tif (done || signal.aborted) break;\n\t\t\tlength += value.byteLength;\n\t\t\tif (length > limit) {\n\t\t\t\tcancel();\n\t\t\t\tpart.inflated = { kind: \"too_large\" };\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tchunks.push(value);\n\t\t}\n\t} catch (error) {\n\t\tif (!signal.aborted) part.inflated = { kind: \"corrupt\", error };\n\t\treturn;\n\t} finally {\n\t\tsignal.removeEventListener(\"abort\", cancel);\n\t}\n\tif (signal.aborted) return;\n\tconst bytes = new Uint8Array(length);\n\tlet offset = 0;\n\tfor (const chunk of chunks) {\n\t\tbytes.set(chunk, offset);\n\t\toffset += chunk.byteLength;\n\t}\n\tpart.inflated = { kind: \"bytes\", bytes };\n}\n\n/** A part's size on the wire: its UTF-8 bytes (counted for text, without encoding it). */\nfunction sizeOf(part: Part): number {\n\tif (typeof part !== \"string\") return part instanceof DeflatedPart ? part.bytes.byteLength : part.byteLength;\n\tlet size = part.length;\n\tfor (let index = 0; index < part.length; index++) {\n\t\tconst unit = part.charCodeAt(index);\n\t\tif (unit < 0x80) continue;\n\t\tif (unit < 0x800) size += 1;\n\t\telse if (unit >= 0xd800 && unit < 0xdc00 && (part.charCodeAt(index + 1) & 0xfc00) === 0xdc00) {\n\t\t\t// A surrogate pair: four bytes for two units.\n\t\t\tsize += 2;\n\t\t\tindex++;\n\t\t} else size += 2;\n\t}\n\treturn size;\n}\n\n/** The error of a part past a limit (`size` unknown while inflating). */\nfunction tooLarge(size: number | undefined, limit: number, measure: \"wire\" | \"decoded\"): ChordError {\n\tconst what = size === undefined ? \"a part\" : `a part of ${size} bytes`;\n\tconst message = `${what} is over the ${measure} limit of ${limit} bytes`;\n\treturn new ChordError({ code: \"too_large\", reason: \"part\", message });\n}\n"]}

package/dist/link/text.d.ts

@@ -0,0 +1,6 @@
+import { type Codec, type Message } from "./message.ts";
+/** Messages as JSON tuples: readable on the wire, for debugging links. */
+export declare const textCodec: Codec;
+/** A message in the text codec's tuple form, for logs and tests (byte segments show as `{"$bytes": i}`). */
+export declare function describeMessage(message: Message): string;
+//# sourceMappingURL=text.d.ts.map

package/dist/link/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/link/text.ts"],"names":[],"mappings":"AASA,OAAO,EAGN,KAAK,KAAK,EAEV,KAAK,OAAO,EAGZ,MAAM,cAAc,CAAC;AAMtB,0EAA0E;AAC1E,eAAO,MAAM,SAAS,EAAE,KA0BvB,CAAC;AAEF,4GAA4G;AAC5G,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAExD"}

package/dist/link/text.js

@@ -0,0 +1,355 @@
+// The text codec (2b): one JSON tuple per message, Delta style (a short kind tag, positional fields, no field names),
+// and `describeMessage`, which prints any message in that form. A part's JSON text is spliced into the tuple as it is;
+// decoding parses the tuple and writes each part back as text (one parse per part per hop: a debugging codec). Byte
+// segments of a payload marked as carrying bytes follow the tuple after a newline (JSON text never contains a raw
+// one), their lengths the tuple's last field. A message with an origin is wrapped: `["@", origin, tuple]`. Every part
+// is tagged with its codec, so no JSON value is reserved: `[0, json]`, or `[1, base64]` for a part its origin deflated
+// (the text codec itself never compresses). A `hold`'s or `call`'s trace carrier is an optional element after its
+// other fields (slice 9); a `call`'s old-work flag (`old`) follows it as `true` (the carrier then `null` when absent).
+import { CAUSE_KINDS, NO_RETIRED, } from "./message.js";
+import { parseJson, partText, textPart } from "./values.js";
+const UTF8 = new TextEncoder();
+/** Messages as JSON tuples: readable on the wire, for debugging links. */
+export const textCodec = {
+    name: "text",
+    encode(message) {
+        const json = UTF8.encode(tuple(message));
+        const segments = segmentsOf(message);
+        if (segments === undefined)
+            return json;
+        let length = json.byteLength + 1;
+        for (const segment of segments)
+            length += segment.byteLength;
+        const bytes = new Uint8Array(length);
+        bytes.set(json, 0);
+        bytes[json.byteLength] = NEWLINE;
+        let offset = json.byteLength + 1;
+        for (const segment of segments) {
+            bytes.set(segment, offset);
+            offset += segment.byteLength;
+        }
+        return bytes;
+    },
+    decode(bytes) {
+        const newline = bytes.indexOf(NEWLINE);
+        const json = newline === -1 ? bytes : bytes.subarray(0, newline);
+        const rest = newline === -1 ? bytes.subarray(bytes.byteLength) : bytes.subarray(newline + 1);
+        const fields = parseJson(json);
+        if (!Array.isArray(fields))
+            throw new Error("text: a message is a tuple");
+        return fromTuple(fields, rest);
+    },
+};
+/** A message in the text codec's tuple form, for logs and tests (byte segments show as `{"$bytes": i}`). */
+export function describeMessage(message) {
+    return tuple(message);
+}
+const NEWLINE = 0x0a;
+/** The segments following a payload's tuple; `undefined` without a payload marked as carrying bytes. */
+function segmentsOf(message) {
+    return message.kind === "call" || message.kind === "result" ? message.segments : undefined;
+}
+/** The tuple's JSON text, parts spliced in; wrapped with its origin when it has one. */
+function tuple(message) {
+    const origin = "origin" in message ? message.origin : undefined;
+    return origin === undefined ? ownTuple(message) : `["@",${origin},${ownTuple(message)}]`;
+}
+/** The tuple of a message's own fields. */
+function ownTuple(message) {
+    switch (message.kind) {
+        case "hello":
+            return json(["h", message.protocol, message.incarnation, message.calls]);
+        case "hold": {
+            const { address, principal, incarnation, chain, limit, trace } = message;
+            const head = json(["H", message.hold, message.type, message.version, message.fingerprint]).slice(0, -1);
+            // Optional trailing fields: an absent one in the middle is null, absent ones at the end are left out.
+            const optional = [principal ?? null, incarnation ?? null, chain ?? null, limit ?? null, trace ?? null];
+            while (optional.length > 0 && optional.at(-1) === null)
+                optional.pop();
+            const rest = optional.map((field) => `,${json(field)}`).join("");
+            return `${head},${partText(message.params)},${json([address.kind, address.params])}${rest}]`;
+        }
+        case "release":
+            return json(["R", message.hold]);
+        case "call": {
+            const head = json(["c", message.call, message.hold, message.method]);
+            const { args, segments, trace, old } = message;
+            if (trace === undefined && old !== true)
+                return withPayload(head, args, segments);
+            // With a trace or the old-work flag the payload's fields are positional (null when absent), the carrier next
+            // (null when absent before the flag), the flag last.
+            const lengths = segments === undefined ? "null" : json(segments.map((segment) => segment.byteLength));
+            const part = args === undefined ? "null" : partText(args);
+            const tail = old === true ? `${json(trace ?? null)},true` : json(trace);
+            return `${head.slice(0, -1)},${part},${lengths},${tail}]`;
+        }
+        case "abort":
+            return json(["x", message.call]);
+        case "bound":
+            return `["b",[${message.holds.map(boundEntry).join(",")}]]`;
+        case "state":
+            return `["s",[${message.holds.map(stateEntry).join(",")}]]`;
+        case "failed": {
+            const kind = message.cause.kind[0];
+            const retryIn = message.retryIn === undefined ? [] : [message.retryIn];
+            return json(["f", message.hold, kind, message.cause.error, ...retryIn]);
+        }
+        case "result":
+            return withPayload(json(["r", message.call]), message.value, message.segments);
+        case "error":
+            return json(["e", message.call, message.error]);
+        case "gone":
+            return json(["g", message.hold, message.error]);
+        case "revoke":
+            return json(["V", message.revocation]);
+        case "retry":
+            return json(["T", message.hold, message.hops]);
+        case "loading":
+            return json(["l", message.hold]);
+        case "ack":
+            return json(["a"]);
+        case "closed":
+            return json(["C"]);
+        case "ping":
+            return json(["p"]);
+        case "pong":
+            return json(["P"]);
+    }
+}
+function json(value) {
+    return JSON.stringify(value);
+}
+/** `[hold, variant, [[member, value]…], failed?]`. */
+function boundEntry({ hold, variant, members, failed }) {
+    const pairs = members.map(({ member, value }) => `[${member},${partText(value)}]`).join(",");
+    return `[${hold},${variant},[${pairs}]${failedField(failed)}]`;
+}
+/** `[hold, [[member, ops]…], failed?, retired?]`; `failed` is `[]` when only `retired` follows. */
+function stateEntry({ hold, members, failed, retired }) {
+    const pairs = members.map(({ member, ops }) => `[${member},${partText(ops)}]`).join(",");
+    if (retired.length === 0)
+        return `[${hold},[${pairs}]${failedField(failed)}]`;
+    return `[${hold},[${pairs}],${json(failed.map(({ member, error }) => [member, error]))},${json(retired)}]`;
+}
+/** The failures as an entry's optional last field: left out when there are none. */
+function failedField(failed) {
+    return failed.length === 0 ? "" : `,${json(failed.map(({ member, error }) => [member, error]))}`;
+}
+/**
+ * A tuple (its closed JSON `head`) ending in a payload part; one marked as carrying bytes adds the segments' lengths
+ * as the last field.
+ */
+function withPayload(head, part, segments) {
+    if (part === undefined)
+        return head;
+    const prefix = `${head.slice(0, -1)},${partText(part)}`;
+    if (segments === undefined)
+        return `${prefix}]`;
+    return `${prefix},${json(segments.map((segment) => segment.byteLength))}]`;
+}
+/**
+ * A message from its tuple: the tag and arity checked, lists of pairs checked as lists, parts written back as text;
+ * the field types are the message schema's to check. `rest` holds the segments, which only a payload marked as
+ * carrying bytes may have.
+ */
+function fromTuple(fields, rest) {
+    if (fields[0] !== "@")
+        return fromFields(fields, rest);
+    const inner = fields.length === 3 ? list(fields[2]) : [];
+    if (inner[0] === "@" || inner.length === 0)
+        throw new Error("text: an origin wraps one message");
+    const message = fromFields(inner, rest);
+    // A fresh object; the message schema checks the origin and refuses one on a kind without it.
+    message.origin = fields[1];
+    return message;
+}
+/** A message from its own fields' tuple (see `fromTuple`). */
+function fromFields(fields, rest) {
+    const [tag, ...f] = fields;
+    const arity = (...allowed) => {
+        if (!allowed.includes(f.length))
+            throw new Error(`text: a "${String(tag)}" message with ${f.length} fields`);
+    };
+    if (tag !== "c" && tag !== "r" && rest.byteLength > 0) {
+        throw new Error("text: byte segments without a payload that carries them");
+    }
+    // The message schema establishes the types of the fields taken here.
+    const field = (index) => f[index];
+    switch (tag) {
+        case "h":
+            arity(3);
+            return { kind: "hello", protocol: field(0), incarnation: field(1), calls: field(2) };
+        case "H": {
+            arity(6, 7, 8, 9, 10, 11);
+            const address = list(f[5]);
+            if (address.length !== 2)
+                throw new Error("text: an address is a pair");
+            const [principal, incarnation, chain, limit, trace] = [6, 7, 8, 9, 10].map((index) => f[index] ?? null);
+            return {
+                kind: "hold",
+                hold: field(0),
+                type: field(1),
+                version: field(2),
+                fingerprint: field(3),
+                params: textPart(f[4]),
+                address: { kind: address[0], params: address[1] },
+                ...(principal === null ? {} : { principal: principal }),
+                ...(incarnation === null ? {} : { incarnation: incarnation }),
+                ...(chain === null ? {} : { chain: chain }),
+                ...(limit === null ? {} : { limit: limit }),
+                ...(trace === null ? {} : { trace: trace }),
+            };
+        }
+        case "R":
+            arity(1);
+            return { kind: "release", hold: field(0) };
+        case "c": {
+            arity(3, 4, 5, 6, 7);
+            const call = {
+                kind: "call",
+                call: field(0),
+                hold: field(1),
+                method: field(2),
+            };
+            if (f.length < 6)
+                return { ...call, ...payload("args", f.slice(3), rest) };
+            // With a trace or the old-work flag: the payload's fields positional, null when absent.
+            const fields = f[3] === null ? [] : f[4] === null ? [f[3]] : [f[3], f[4]];
+            // The message schema checks the carrier and the flag (`true` only).
+            const trace = f[5] === null ? {} : { trace: f[5] };
+            const old = f.length === 7 ? { old: f[6] } : {};
+            return { ...call, ...payload("args", fields, rest), ...trace, ...old };
+        }
+        case "x":
+            arity(1);
+            return { kind: "abort", call: field(0) };
+        case "b":
+            arity(1);
+            return {
+                kind: "bound",
+                holds: list(f[0]).map((entry) => {
+                    const fields = list(entry);
+                    if (fields.length !== 3 && fields.length !== 4) {
+                        throw new Error(`text: a bound entry with ${fields.length} fields`);
+                    }
+                    const [hold, variant, members, failed] = fields;
+                    return {
+                        hold: hold,
+                        variant: variant,
+                        members: pairs(members).map(([member, value]) => ({
+                            member: member,
+                            value: textPart(value),
+                        })),
+                        failed: failures(failed),
+                    };
+                }),
+            };
+        case "s":
+            arity(1);
+            return {
+                kind: "state",
+                holds: list(f[0]).map((entry) => {
+                    const fields = list(entry);
+                    if (fields.length < 2 || fields.length > 4) {
+                        throw new Error(`text: a state entry with ${fields.length} fields`);
+                    }
+                    const [hold, members, failed, retired] = fields;
+                    return {
+                        hold: hold,
+                        members: pairs(members).map(([member, ops]) => ({ member: member, ops: textPart(ops) })),
+                        failed: failures(failed),
+                        // The message schema checks each index.
+                        retired: retired === undefined ? NO_RETIRED : list(retired),
+                    };
+                }),
+            };
+        case "f": {
+            arity(3, 4);
+            const causeKind = CAUSE_KINDS.find((each) => each[0] === f[1]);
+            if (causeKind === undefined)
+                throw new Error("text: an unknown failure kind");
+            // The schema check after decoding establishes the wire error.
+            const error = f[2];
+            const cause = { kind: causeKind, error };
+            return { kind: "failed", hold: field(0), cause, ...(f.length === 4 ? { retryIn: field(3) } : {}) };
+        }
+        case "r":
+            arity(1, 2, 3);
+            return { kind: "result", call: field(0), ...payload("value", f.slice(1), rest) };
+        case "e":
+            arity(2);
+            return { kind: "error", call: field(0), error: field(1) };
+        case "g":
+            arity(2);
+            return { kind: "gone", hold: field(0), error: field(1) };
+        case "V":
+            arity(1);
+            return { kind: "revoke", revocation: f[0] };
+        case "T":
+            arity(2);
+            return { kind: "retry", hold: field(0), hops: field(1) };
+        case "l":
+            arity(1);
+            return { kind: "loading", hold: field(0) };
+        case "a":
+            arity(0);
+            return { kind: "ack" };
+        case "C":
+            arity(0);
+            // Its origin is the wrapper's; 0 without one, which the message schema refuses.
+            return { kind: "closed", origin: 0 };
+        case "p":
+            arity(0);
+            return { kind: "ping" };
+        case "P":
+            arity(0);
+            return { kind: "pong" };
+        default:
+            throw new Error("text: an unknown kind");
+    }
+}
+/**
+ * A payload part from its fields: none, the value, or the value and its segments' lengths (marked as carrying bytes,
+ * the segments views of `rest`).
+ */
+function payload(key, fields, rest) {
+    if (fields.length < 2) {
+        if (rest.byteLength > 0)
+            throw new Error("text: byte segments without a payload that carries them");
+        return (fields.length === 0 ? {} : { [key]: textPart(fields[0]) });
+    }
+    const lengths = list(fields[1]);
+    let offset = 0;
+    const segments = lengths.map((length) => {
+        if (!Number.isSafeInteger(length) || length < 0)
+            throw new Error("text: a segment length");
+        const segment = rest.subarray(offset, offset + length);
+        offset += length;
+        return segment;
+    });
+    if (offset !== rest.byteLength)
+        throw new Error("text: the segments do not fill the message");
+    return { [key]: textPart(fields[0]), segments };
+}
+function list(value) {
+    if (!Array.isArray(value))
+        throw new Error("text: expected a list");
+    return value;
+}
+/** A list of `[index, value]` pairs. */
+function pairs(value) {
+    return list(value).map((pair) => {
+        const entry = list(pair);
+        if (entry.length !== 2)
+            throw new Error("text: expected a pair");
+        return entry;
+    });
+}
+/** The optional failures field; absent means none. */
+function failures(value) {
+    if (value === undefined)
+        return [];
+    // The message schema checks each error's shape.
+    return pairs(value).map(([member, error]) => ({ member, error }));
+}
+//# sourceMappingURL=text.js.map