@earendil-works/chord 1.4.0 → 1.5.1

package/dist/host/route.d.ts

@@ -0,0 +1,64 @@
+import { type Context } from "../context/index.ts";
+import type { Address, HostKind, KindShape } from "../contracts/index.ts";
+import { type Principal } from "../data/index.ts";
+import type { Codec, Link, PartLimits } from "../link/index.ts";
+import { type HostLink, Path, type Upstream } from "../remote/internal.ts";
+import type { AnyHost } from "./host.ts";
+/** What `host.route` takes for a kind. */
+export type RouteOptions<P extends Principal, K extends KindShape> = {
+    /** Whether `principal` may reach `address`; runs for every hold routed over the route, before anything starts. */
+    authorize(principal: P, address: Address<K>): boolean;
+    /**
+     * The link to `address`: `principal` is who the host at the other end is, `trusted` skips the message check on it,
+     * `limits` bound its parts (as `accept`'s). `context` is the route's, aborted when this host closes. Runs at most
+     * once at a time per address.
+     */
+    resolve(address: Address<K>, context: Context): Promise<{
+        readonly link: Link;
+        readonly principal: P;
+        readonly trusted?: boolean;
+        readonly codec?: Codec;
+        readonly limits?: PartLimits;
+    }>;
+};
+/** What `host.route` returns: the app's controls of its addresses (D10b, R1). */
+export type RouteHandle<K extends KindShape> = {
+    /**
+     * Resolves `address` again now if it has holders and no link: its failure and its suspension end (a Retry button);
+     * an address nobody holds resolves at its next hold.
+     */
+    retry(address: Address<K>): void;
+    /**
+     * Resolves nothing for `address` while it has holders: they wait `failed { waiting }` ("suspended") once its link is
+     * gone; the suspension ends with its last holder or `retry`.
+     */
+    suspend(address: Address<K>): void;
+};
+/**
+ * A host's route for one kind. An address is kept while it has holders, a link or a running `resolve`: a resolve whose
+ * holds were all released meanwhile finishes, and its link is kept until it closes.
+ */
+export declare class Route {
+    #private;
+    readonly kind: string;
+    constructor(kind: HostKind, options: RouteOptions<Principal, KindShape>, host: AnyHost, context: Context);
+    /**
+     * The path to the address with `params`, for a hold acting as `principal`: the params checked against the kind
+     * (`invalid/host_address`), then `authorize` (`forbidden` when it refuses; a throw is the hold's failure).
+     */
+    path(params: unknown, principal: Principal | undefined, context: Context): Path;
+    /** `RouteHandle.retry`: the address's failure and suspension end; it resolves now if held and unlinked. */
+    retry(key: string): void;
+    /** `RouteHandle.suspend`: a held address resolves nothing until `retry` or its last holder; unheld, nothing is kept. */
+    suspend(key: string): void;
+    /** One of this route's links completed its handshake: a later drop of it resolves its address again. */
+    opened(link: HostLink): void;
+    /**
+     * One of this route's links closed: its address resolves again once while held if the link had completed its
+     * handshake, else its holders fail (no loop over a worker that dies at start).
+     */
+    closed(link: HostLink): boolean;
+    /** Every holder of every path of this route, linked or not (revocation ends a revoked principal's). */
+    holders(): Upstream[];
+}
+//# sourceMappingURL=route.d.ts.map

package/dist/host/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/host/route.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,OAAO,EAAiB,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE1E,OAAO,EAAyB,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEzE,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,KAAK,QAAQ,EAAE,IAAI,EAAkB,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAE3F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,0CAA0C;AAC1C,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,SAAS,IAAI;IACpE,kHAAkH;IAClH,SAAS,CAAC,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IACtD;;;;OAIG;IACH,OAAO,CACN,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,OAAO,EAAE,OAAO,GACd,OAAO,CAAC;QACV,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;QACpB,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;QACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;QACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;KAC7B,CAAC,CAAC;CACH,CAAC;AAEF,iFAAiF;AACjF,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,SAAS,IAAI;IAC9C;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CACnC,CAAC;AAiBF;;;GAGG;AACH,qBAAa,KAAK;;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAUtB,YAAY,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAMvG;IAED;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAmB9E;IAED,2GAA2G;IAC3G,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAMvB;IAED,wHAAwH;IACxH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKzB;IAED,wGAAwG;IACxG,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAG3B;IAED;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAa9B;IAED,uGAAuG;IACvG,OAAO,IAAI,QAAQ,EAAE,CAEpB;CAsGD"}

package/dist/host/route.js

@@ -0,0 +1,227 @@
+// Routes (§3): how a host reaches hosts of one kind. `authorize` admits each hold routed over the route; `resolve`
+// makes the link of one address, at most once at a time. No timer (slice 10 R2): an address resolves for a new hold,
+// on `RouteHandle.retry`, or once after its link dropped while held; a rejected `resolve` (or a link closed before its
+// handshake) fails its holders `failed { waiting }` until then, and a suspended address resolves nothing while held.
+// Each `resolve` is a `chord.resolve` root span linked to the hold that started it (slice 9).
+import { withTelemetry } from "../context/index.js";
+import { kindParams } from "../contracts/internal.js";
+import { ChordError, forbidden } from "../data/index.js";
+import { asChordError, checkAddress } from "../data/internal.js";
+import { Path } from "../remote/internal.js";
+import { capped, OpenSpan, spanFailed, untraced } from "../telemetry.js";
+/**
+ * A host's route for one kind. An address is kept while it has holders, a link or a running `resolve`: a resolve whose
+ * holds were all released meanwhile finishes, and its link is kept until it closes.
+ */
+export class Route {
+    kind;
+    #params;
+    #options;
+    #host;
+    /** The route's context, aborted when the host closes: every `resolve` and its links' work run under it. */
+    #context;
+    #addresses = new Map();
+    /** The addresses' links, which tell their address when they close, and whether each completed its handshake. */
+    #links = new Map();
+    constructor(kind, options, host, context) {
+        this.kind = kind.kind;
+        this.#params = kindParams(kind);
+        this.#options = options;
+        this.#host = host;
+        this.#context = context;
+    }
+    /**
+     * The path to the address with `params`, for a hold acting as `principal`: the params checked against the kind
+     * (`invalid/host_address`), then `authorize` (`forbidden` when it refuses; a throw is the hold's failure).
+     */
+    path(params, principal, context) {
+        const address = checkAddress(this.kind, this.#params, params, context);
+        if (principal === undefined || !this.#options.authorize(principal, address)) {
+            throw forbidden(`${address.key}: not authorized`);
+        }
+        let routed = this.#addresses.get(address.key);
+        if (routed === undefined) {
+            const made = {
+                address,
+                path: new Path((event) => this.#changed(made, event)),
+                resolving: false,
+                span: undefined,
+                failure: undefined,
+                suspended: false,
+            };
+            routed = made;
+            this.#addresses.set(address.key, made);
+        }
+        return routed.path;
+    }
+    /** `RouteHandle.retry`: the address's failure and suspension end; it resolves now if held and unlinked. */
+    retry(key) {
+        const routed = this.#addresses.get(key);
+        if (routed === undefined)
+            return;
+        routed.failure = undefined;
+        routed.suspended = false;
+        this.#resolveIfHeld(routed);
+    }
+    /** `RouteHandle.suspend`: a held address resolves nothing until `retry` or its last holder; unheld, nothing is kept. */
+    suspend(key) {
+        const routed = this.#addresses.get(key);
+        if (routed === undefined || !routed.path.held)
+            return;
+        routed.suspended = true;
+        if (routed.path.link === undefined && !routed.resolving)
+            routed.path.unreachable(suspended(routed));
+    }
+    /** One of this route's links completed its handshake: a later drop of it resolves its address again. */
+    opened(link) {
+        const entry = this.#links.get(link);
+        if (entry !== undefined)
+            entry.greeted = true;
+    }
+    /**
+     * One of this route's links closed: its address resolves again once while held if the link had completed its
+     * handshake, else its holders fail (no loop over a worker that dies at start).
+     */
+    closed(link) {
+        const entry = this.#links.get(link);
+        if (entry === undefined)
+            return false;
+        this.#links.delete(link);
+        const { routed } = entry;
+        if (!entry.greeted) {
+            routed.failure = new ChordError({
+                code: "unavailable",
+                message: `${routed.address.key}: the link closed before its handshake`,
+            });
+        }
+        routed.path.disconnected(link);
+        return true;
+    }
+    /** Every holder of every path of this route, linked or not (revocation ends a revoked principal's). */
+    holders() {
+        return [...this.#addresses.values()].flatMap(({ path }) => path.holders());
+    }
+    /**
+     * An address's path changed without a link: a new holder resolves it (a failed address too: a new hold is a new
+     * request), a dropped link resolves it once (or fails it, closed before its handshake), the last holder's release
+     * forgets it (its failure and suspension too) unless its link or `resolve` keeps it.
+     */
+    #changed(routed, event) {
+        if (this.#host.closing)
+            return;
+        switch (event.kind) {
+            case "released":
+                routed.suspended = false;
+                if (routed.path.link === undefined && !routed.resolving)
+                    this.#addresses.delete(routed.address.key);
+                return;
+            case "attached":
+                if (routed.suspended)
+                    event.holder.unreachable(suspended(routed));
+                else if (!routed.resolving)
+                    void this.#resolve(routed, event.holder.span);
+                else if (routed.span !== undefined)
+                    event.holder.span?.addLink({ context: routed.span });
+                return;
+            case "dropped":
+                if (!routed.path.held)
+                    this.#addresses.delete(routed.address.key);
+                else if (routed.suspended)
+                    routed.path.unreachable(suspended(routed));
+                else if (routed.failure !== undefined)
+                    routed.path.unreachable(routed.failure);
+                else
+                    void this.#resolve(routed);
+        }
+    }
+    /** Resolves the address if it has holders, no link, no running `resolve` and no suspension. */
+    #resolveIfHeld(routed) {
+        const { path } = routed;
+        if (!path.held || path.link !== undefined || routed.resolving || this.#host.closing)
+            return;
+        void this.#resolve(routed);
+    }
+    /**
+     * Runs `resolve` once for the address, in a `chord.resolve` root span linked to `trigger` (the span of the hold that
+     * started it, which links back). A rejection, or a link closed already, fails its holders with the error until the
+     * next resolve; a link returned after the host closed is closed at once.
+     */
+    async #resolve(routed, trigger) {
+        const key = routed.address.key;
+        const adapter = this.#host.telemetry;
+        const span = untraced(adapter)
+            ? undefined
+            : new OpenSpan(adapter, "chord.resolve", {
+                "chord.host": this.#host.spanHost,
+                kind: this.kind,
+                address: capped(key),
+            });
+        if (span !== undefined && trigger !== undefined) {
+            span.span.addLink({ context: trigger });
+            trigger.addLink({ context: span.span });
+        }
+        routed.resolving = true;
+        routed.span = span?.span;
+        let resolved;
+        try {
+            const context = span === undefined ? this.#context : withTelemetry(span.span, this.#context);
+            resolved = await this.#options.resolve(routed.address, context);
+        }
+        catch (error) {
+            routed.resolving = false;
+            routed.span = undefined;
+            resolveEnded(span, error);
+            if (this.#host.closing)
+                return;
+            this.#host.report({ kind: "resolve_failed", address: key, error });
+            this.#settle(routed, asChordError(error, key));
+            return;
+        }
+        routed.resolving = false;
+        routed.span = undefined;
+        if (this.#host.closing) {
+            resolveEnded(span, new ChordError({ code: "released", reason: "closed", message: "the host is closed" }));
+            resolved.link.close();
+            return;
+        }
+        const { link: made, ...options } = resolved;
+        const link = this.#host.routeLink(made, options, this.#context);
+        if (!link.open) {
+            const error = new ChordError({ code: "unavailable", message: `${key}: the link closed before its handshake` });
+            resolveEnded(span, error);
+            this.#settle(routed, error);
+            return;
+        }
+        resolveEnded(span, undefined);
+        routed.failure = undefined;
+        // A peer that greeted first had its `hello` handled while the link was made, before it was registered here.
+        this.#links.set(link, { routed, greeted: link.greeted });
+        routed.path.connected(link);
+    }
+    /**
+     * A resolve failed with `error`: its holders fail `failed { waiting }` with it (they stay on its path for its next
+     * link), or the address goes when nobody holds it any more.
+     */
+    #settle(routed, error) {
+        if (!routed.path.held) {
+            this.#addresses.delete(routed.address.key);
+            return;
+        }
+        routed.failure = error;
+        routed.path.unreachable(routed.suspended ? suspended(routed) : error);
+    }
+}
+/** A resolve's span ends: `linked`, or `failed` with `error`. */
+function resolveEnded(span, error) {
+    if (span === undefined)
+        return;
+    if (error !== undefined)
+        spanFailed(span.span, "resolve_failed", error);
+    span.span.setAttributes({ outcome: error === undefined ? "linked" : "failed" });
+    span.end();
+}
+/** The failure holders of a suspended address see. */
+function suspended(routed) {
+    return new ChordError({ code: "unavailable", message: `${routed.address.key}: suspended` });
+}
+//# sourceMappingURL=route.js.map

package/dist/host/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../src/host/route.ts"],"names":[],"mappings":"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","sourcesContent":["// Routes (§3): how a host reaches hosts of one kind. `authorize` admits each hold routed over the route; `resolve`\n// makes the link of one address, at most once at a time. No timer (slice 10 R2): an address resolves for a new hold,\n// on `RouteHandle.retry`, or once after its link dropped while held; a rejected `resolve` (or a link closed before its\n// handshake) fails its holders `failed { waiting }` until then, and a suspended address resolves nothing while held.\n// Each `resolve` is a `chord.resolve` root span linked to the hold that started it (slice 9).\n\nimport type { TelemetrySpan } from \"@earendil-works/pi-telemetry\";\nimport { type Context, withTelemetry } from \"../context/index.ts\";\nimport type { Address, HostKind, KindShape } from \"../contracts/index.ts\";\nimport { kindParams, type ParamsData } from \"../contracts/internal.ts\";\nimport { ChordError, forbidden, type Principal } from \"../data/index.ts\";\nimport { asChordError, checkAddress } from \"../data/internal.ts\";\nimport type { Codec, Link, PartLimits } from \"../link/index.ts\";\nimport { type HostLink, Path, type PathEvent, type Upstream } from \"../remote/internal.ts\";\nimport { capped, OpenSpan, spanFailed, untraced } from \"../telemetry.ts\";\nimport type { AnyHost } from \"./host.ts\";\n\n/** What `host.route` takes for a kind. */\nexport type RouteOptions<P extends Principal, K extends KindShape> = {\n\t/** Whether `principal` may reach `address`; runs for every hold routed over the route, before anything starts. */\n\tauthorize(principal: P, address: Address<K>): boolean;\n\t/**\n\t * The link to `address`: `principal` is who the host at the other end is, `trusted` skips the message check on it,\n\t * `limits` bound its parts (as `accept`'s). `context` is the route's, aborted when this host closes. Runs at most\n\t * once at a time per address.\n\t */\n\tresolve(\n\t\taddress: Address<K>,\n\t\tcontext: Context,\n\t): Promise<{\n\t\treadonly link: Link;\n\t\treadonly principal: P;\n\t\treadonly trusted?: boolean;\n\t\treadonly codec?: Codec;\n\t\treadonly limits?: PartLimits;\n\t}>;\n};\n\n/** What `host.route` returns: the app's controls of its addresses (D10b, R1). */\nexport type RouteHandle<K extends KindShape> = {\n\t/**\n\t * Resolves `address` again now if it has holders and no link: its failure and its suspension end (a Retry button);\n\t * an address nobody holds resolves at its next hold.\n\t */\n\tretry(address: Address<K>): void;\n\t/**\n\t * Resolves nothing for `address` while it has holders: they wait `failed { waiting }` (\"suspended\") once its link is\n\t * gone; the suspension ends with its last holder or `retry`.\n\t */\n\tsuspend(address: Address<K>): void;\n};\n\n/**\n * One address of a route: its path, whether its `resolve` runs (and its span, when recorded), why it fails its holders,\n * whether it is suspended.\n */\ntype Routed = {\n\treadonly address: Address;\n\treadonly path: Path;\n\tresolving: boolean;\n\t/** The running `resolve`'s span: holders attaching meanwhile link to it (decision \"Shared work\"). */\n\tspan: TelemetrySpan | undefined;\n\t/** A rejected `resolve`, or a link closed before its handshake: its holders fail with it until the next resolve. */\n\tfailure: ChordError | undefined;\n\tsuspended: boolean;\n};\n\n/**\n * A host's route for one kind. An address is kept while it has holders, a link or a running `resolve`: a resolve whose\n * holds were all released meanwhile finishes, and its link is kept until it closes.\n */\nexport class Route {\n\treadonly kind: string;\n\treadonly #params: ParamsData;\n\treadonly #options: RouteOptions<Principal, KindShape>;\n\treadonly #host: AnyHost;\n\t/** The route's context, aborted when the host closes: every `resolve` and its links' work run under it. */\n\treadonly #context: Context;\n\treadonly #addresses = new Map<string, Routed>();\n\t/** The addresses' links, which tell their address when they close, and whether each completed its handshake. */\n\treadonly #links = new Map<HostLink, { readonly routed: Routed; greeted: boolean }>();\n\n\tconstructor(kind: HostKind, options: RouteOptions<Principal, KindShape>, host: AnyHost, context: Context) {\n\t\tthis.kind = kind.kind;\n\t\tthis.#params = kindParams(kind);\n\t\tthis.#options = options;\n\t\tthis.#host = host;\n\t\tthis.#context = context;\n\t}\n\n\t/**\n\t * The path to the address with `params`, for a hold acting as `principal`: the params checked against the kind\n\t * (`invalid/host_address`), then `authorize` (`forbidden` when it refuses; a throw is the hold's failure).\n\t */\n\tpath(params: unknown, principal: Principal | undefined, context: Context): Path {\n\t\tconst address = checkAddress(this.kind, this.#params, params, context);\n\t\tif (principal === undefined || !this.#options.authorize(principal, address)) {\n\t\t\tthrow forbidden(`${address.key}: not authorized`);\n\t\t}\n\t\tlet routed = this.#addresses.get(address.key);\n\t\tif (routed === undefined) {\n\t\t\tconst made: Routed = {\n\t\t\t\taddress,\n\t\t\t\tpath: new Path((event) => this.#changed(made, event)),\n\t\t\t\tresolving: false,\n\t\t\t\tspan: undefined,\n\t\t\t\tfailure: undefined,\n\t\t\t\tsuspended: false,\n\t\t\t};\n\t\t\trouted = made;\n\t\t\tthis.#addresses.set(address.key, made);\n\t\t}\n\t\treturn routed.path;\n\t}\n\n\t/** `RouteHandle.retry`: the address's failure and suspension end; it resolves now if held and unlinked. */\n\tretry(key: string): void {\n\t\tconst routed = this.#addresses.get(key);\n\t\tif (routed === undefined) return;\n\t\trouted.failure = undefined;\n\t\trouted.suspended = false;\n\t\tthis.#resolveIfHeld(routed);\n\t}\n\n\t/** `RouteHandle.suspend`: a held address resolves nothing until `retry` or its last holder; unheld, nothing is kept. */\n\tsuspend(key: string): void {\n\t\tconst routed = this.#addresses.get(key);\n\t\tif (routed === undefined || !routed.path.held) return;\n\t\trouted.suspended = true;\n\t\tif (routed.path.link === undefined && !routed.resolving) routed.path.unreachable(suspended(routed));\n\t}\n\n\t/** One of this route's links completed its handshake: a later drop of it resolves its address again. */\n\topened(link: HostLink): void {\n\t\tconst entry = this.#links.get(link);\n\t\tif (entry !== undefined) entry.greeted = true;\n\t}\n\n\t/**\n\t * One of this route's links closed: its address resolves again once while held if the link had completed its\n\t * handshake, else its holders fail (no loop over a worker that dies at start).\n\t */\n\tclosed(link: HostLink): boolean {\n\t\tconst entry = this.#links.get(link);\n\t\tif (entry === undefined) return false;\n\t\tthis.#links.delete(link);\n\t\tconst { routed } = entry;\n\t\tif (!entry.greeted) {\n\t\t\trouted.failure = new ChordError({\n\t\t\t\tcode: \"unavailable\",\n\t\t\t\tmessage: `${routed.address.key}: the link closed before its handshake`,\n\t\t\t});\n\t\t}\n\t\trouted.path.disconnected(link);\n\t\treturn true;\n\t}\n\n\t/** Every holder of every path of this route, linked or not (revocation ends a revoked principal's). */\n\tholders(): Upstream[] {\n\t\treturn [...this.#addresses.values()].flatMap(({ path }) => path.holders());\n\t}\n\n\t/**\n\t * An address's path changed without a link: a new holder resolves it (a failed address too: a new hold is a new\n\t * request), a dropped link resolves it once (or fails it, closed before its handshake), the last holder's release\n\t * forgets it (its failure and suspension too) unless its link or `resolve` keeps it.\n\t */\n\t#changed(routed: Routed, event: PathEvent): void {\n\t\tif (this.#host.closing) return;\n\t\tswitch (event.kind) {\n\t\t\tcase \"released\":\n\t\t\t\trouted.suspended = false;\n\t\t\t\tif (routed.path.link === undefined && !routed.resolving) this.#addresses.delete(routed.address.key);\n\t\t\t\treturn;\n\t\t\tcase \"attached\":\n\t\t\t\tif (routed.suspended) event.holder.unreachable(suspended(routed));\n\t\t\t\telse if (!routed.resolving) void this.#resolve(routed, event.holder.span);\n\t\t\t\telse if (routed.span !== undefined) event.holder.span?.addLink({ context: routed.span });\n\t\t\t\treturn;\n\t\t\tcase \"dropped\":\n\t\t\t\tif (!routed.path.held) this.#addresses.delete(routed.address.key);\n\t\t\t\telse if (routed.suspended) routed.path.unreachable(suspended(routed));\n\t\t\t\telse if (routed.failure !== undefined) routed.path.unreachable(routed.failure);\n\t\t\t\telse void this.#resolve(routed);\n\t\t}\n\t}\n\n\t/** Resolves the address if it has holders, no link, no running `resolve` and no suspension. */\n\t#resolveIfHeld(routed: Routed): void {\n\t\tconst { path } = routed;\n\t\tif (!path.held || path.link !== undefined || routed.resolving || this.#host.closing) return;\n\t\tvoid this.#resolve(routed);\n\t}\n\n\t/**\n\t * Runs `resolve` once for the address, in a `chord.resolve` root span linked to `trigger` (the span of the hold that\n\t * started it, which links back). A rejection, or a link closed already, fails its holders with the error until the\n\t * next resolve; a link returned after the host closed is closed at once.\n\t */\n\tasync #resolve(routed: Routed, trigger?: TelemetrySpan): Promise<void> {\n\t\tconst key = routed.address.key;\n\t\tconst adapter = this.#host.telemetry;\n\t\tconst span = untraced(adapter)\n\t\t\t? undefined\n\t\t\t: new OpenSpan(adapter, \"chord.resolve\", {\n\t\t\t\t\t\"chord.host\": this.#host.spanHost,\n\t\t\t\t\tkind: this.kind,\n\t\t\t\t\taddress: capped(key),\n\t\t\t\t});\n\t\tif (span !== undefined && trigger !== undefined) {\n\t\t\tspan.span.addLink({ context: trigger });\n\t\t\ttrigger.addLink({ context: span.span });\n\t\t}\n\t\trouted.resolving = true;\n\t\trouted.span = span?.span;\n\t\tlet resolved: Awaited<ReturnType<RouteOptions<Principal, KindShape>[\"resolve\"]>>;\n\t\ttry {\n\t\t\tconst context = span === undefined ? this.#context : withTelemetry(span.span, this.#context);\n\t\t\tresolved = await this.#options.resolve(routed.address, context);\n\t\t} catch (error) {\n\t\t\trouted.resolving = false;\n\t\t\trouted.span = undefined;\n\t\t\tresolveEnded(span, error);\n\t\t\tif (this.#host.closing) return;\n\t\t\tthis.#host.report({ kind: \"resolve_failed\", address: key, error });\n\t\t\tthis.#settle(routed, asChordError(error, key));\n\t\t\treturn;\n\t\t}\n\t\trouted.resolving = false;\n\t\trouted.span = undefined;\n\t\tif (this.#host.closing) {\n\t\t\tresolveEnded(span, new ChordError({ code: \"released\", reason: \"closed\", message: \"the host is closed\" }));\n\t\t\tresolved.link.close();\n\t\t\treturn;\n\t\t}\n\t\tconst { link: made, ...options } = resolved;\n\t\tconst link = this.#host.routeLink(made, options, this.#context);\n\t\tif (!link.open) {\n\t\t\tconst error = new ChordError({ code: \"unavailable\", message: `${key}: the link closed before its handshake` });\n\t\t\tresolveEnded(span, error);\n\t\t\tthis.#settle(routed, error);\n\t\t\treturn;\n\t\t}\n\t\tresolveEnded(span, undefined);\n\t\trouted.failure = undefined;\n\t\t// A peer that greeted first had its `hello` handled while the link was made, before it was registered here.\n\t\tthis.#links.set(link, { routed, greeted: link.greeted });\n\t\trouted.path.connected(link);\n\t}\n\n\t/**\n\t * A resolve failed with `error`: its holders fail `failed { waiting }` with it (they stay on its path for its next\n\t * link), or the address goes when nobody holds it any more.\n\t */\n\t#settle(routed: Routed, error: ChordError): void {\n\t\tif (!routed.path.held) {\n\t\t\tthis.#addresses.delete(routed.address.key);\n\t\t\treturn;\n\t\t}\n\t\trouted.failure = error;\n\t\trouted.path.unreachable(routed.suspended ? suspended(routed) : error);\n\t}\n}\n\n/** A resolve's span ends: `linked`, or `failed` with `error`. */\nfunction resolveEnded(span: OpenSpan<\"chord.resolve\"> | undefined, error: unknown): void {\n\tif (span === undefined) return;\n\tif (error !== undefined) spanFailed(span.span, \"resolve_failed\", error);\n\tspan.span.setAttributes({ outcome: error === undefined ? \"linked\" : \"failed\" });\n\tspan.end();\n}\n\n/** The failure holders of a suspended address see. */\nfunction suspended(routed: Routed): ChordError {\n\treturn new ChordError({ code: \"unavailable\", message: `${routed.address.key}: suspended` });\n}\n"]}

package/dist/host/routines.d.ts

@@ -0,0 +1,78 @@
+import { type Context } from "../context/index.ts";
+import type { Principal } from "../data/index.ts";
+import { type NativeWatchable, type NativeWatchCall, type Watchable, type WatchCall } from "../watch.ts";
+import { type Caller, type Ctx } from "./ctx.ts";
+import type { AnyHost } from "./host.ts";
+/**
+ * Where routines run: their owner's label (for reports), its host, whom their calls act for, and the context of their
+ * calls, aborted when the owner ends. `admit` adds a running call to the owner's drain.
+ */
+export type RoutineOwner = {
+    readonly label: string;
+    /** Its type's name (routine spans). */
+    readonly type: string;
+    readonly host: AnyHost;
+    readonly caller: Caller;
+    readonly context: Context;
+    /**
+     * Adds a running call to the drain; `cleanup` (its bookkeeping) runs once, when it settles or when the attempt ends
+     * with it still running.
+     */
+    admit(running: Promise<unknown>, cleanup: () => void): void;
+};
+/**
+ * A routine's handler of a JSON source: the value call (the value, the ops since the previous call, whether the
+ * source's document was retired since then) and the call's ctx. Failures are not calls of a handler (design §11): the
+ * routine waits for the next value.
+ */
+export type OnHandler<T, C extends Ctx = Ctx> = (call: WatchValueCall<T>, ctx: C) => void | Promise<void>;
+/** A JSON watch's value call: what an `on` handler gets. */
+export type WatchValueCall<T> = Extract<WatchCall<T>, {
+    readonly kind: "value";
+}>;
+/** A native watch's value call. */
+export type NativeWatchValueCall<T> = Extract<NativeWatchCall<T>, {
+    readonly kind: "value";
+}>;
+/** A routine's handler of a native source: the value call (the value) and the call's ctx. */
+export type OnNativeHandler<T, C extends Ctx = Ctx> = (call: NativeWatchValueCall<T>, ctx: C) => void | Promise<void>;
+/** An `onLive` routine: called once its owner is live. */
+export type OnLiveHandler<C extends Ctx = Ctx> = (ctx: C) => void | Promise<void>;
+/** What the declarations of an owner (`on`, `onLive`) take; part of the factory's `self` and the facet's. */
+export interface RoutineDeclarations<P extends Principal = Principal> {
+    /**
+     * A routine over `source`: `fn` gets its current value first (ops `[["r", value]]`), then one call per change,
+     * never overlapping: changes during a call fold into one next call (the newest value, the ops since the previous
+     * call, `retired` when any of them was a retirement). After a call that threw, it is called again with the whole
+     * newest value (`retired` again if the call that threw had it) after a backoff (1 s doubling to 60 s), or at once on
+     * a change during the backoff. Ends with its source. A JSON watchable is one whose watch is Chord's shared `Watch`
+     * (every Chord and Durable source).
+     */
+    on<T>(source: Watchable<T>, fn: OnHandler<T, Ctx<P>>): void;
+    /**
+     * A routine over a native source (a registry value, `ref.state`): one whose watch is Chord's shared `NativeWatch`.
+     * As above without ops: after a busy call, one call with the newest value.
+     */
+    on<T>(source: NativeWatchable<T>, fn: OnNativeHandler<T, Ctx<P>>): void;
+    /**
+     * A routine called once its owner is live. Returning ends it; a throw is reported and restarts it after a backoff
+     * (1 s doubling to 60 s, reset after a run of a minute); the owner's end aborts its ctx.
+     */
+    onLive(fn: OnLiveHandler<Ctx<P>>): void;
+}
+/** An owner's routines: declared while its factory (or setup) runs, started once when it went live. */
+export declare class Routines {
+    #private;
+    /** Declares `on(source, fn)`; whether the source is JSON or native is decided by its watch (`OnRoutine`). */
+    on(source: Watchable<unknown> | NativeWatchable<unknown>, fn: (...args: never[]) => void | Promise<void>): void;
+    /** Whether nothing was declared. */
+    get empty(): boolean;
+    /** Declares `onLive(fn)`. */
+    onLive(fn: OnLiveHandler): void;
+    /**
+     * Starts every routine for `owner`, which went live; they stop when its context is aborted. A routine whose
+     * synchronous start ends the owner (an `onLive` releasing its last reference) starts none of the later ones.
+     */
+    start(owner: RoutineOwner): void;
+}
+//# sourceMappingURL=routines.d.ts.map

package/dist/host/routines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routines.d.ts","sourceRoot":"","sources":["../../src/host/routines.ts"],"names":[],"mappings":"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"}