@earendil-works/chord 1.0.4 → 1.2.0

package/dist/connection.d.ts

@@ -0,0 +1,157 @@
+import type { HostImpl } from "./host.ts";
+import type { Link } from "./link.ts";
+import { HandleImpl } from "./record.ts";
+import type { RemoteChannel, RemoteHandle, StateSink } from "./remote.ts";
+import type { Principal } from "./types.ts";
+import { type Frame, type RootRef } from "./wire.ts";
+export interface LinkOptions {
+    /** Milliseconds between pings (default 15000). */
+    readonly pingInterval?: number;
+    /** Close the link when nothing arrived for this long (default 45000). Everything held through it is released. */
+    readonly pingTimeout?: number;
+}
+export interface AcceptOptions extends LinkOptions {
+    /** The principal of whatever connects, from the app's authenticator. Every request on the link acts as it. */
+    readonly principal: Principal;
+    /**
+     * What the peer is, decided here and never by its `hello`: `client` (default; a browser: no roots, no epochs, not
+     * a reload participant, not addressable) or `host` (a child host; needs `name`).
+     */
+    readonly kind?: "host" | "client";
+    /** A child host's name: its hello must match, and it is reachable `at` this name. */
+    readonly name?: string;
+    /** On `invalidatePrincipal`: a new principal keeps the link, `undefined` closes it (default: close). */
+    readonly restamp?: (principal: Principal) => Principal | undefined;
+}
+export interface Peer {
+    readonly kind: "host" | "client";
+    /** Configured (downstream hosts) or announced by the trusted parent (upstream). */
+    readonly name: string | undefined;
+}
+/** A hold the peer made on this host: served locally or relayed to another link. */
+type Served = {
+    readonly kind: "local";
+    readonly handle: HandleImpl;
+    readonly principal: Principal;
+    readonly feeds: Set<number>;
+} | {
+    readonly kind: "relay";
+    readonly relay: RelayHold;
+};
+type Pending = {
+    readonly resolve: (value: unknown) => void;
+    readonly reject: (error: unknown) => void;
+};
+/**
+ * A hold relayed from an origin link to a downstream link. It owns everything done through it: subscriptions and
+ * calls queued while the route resolves, and the downstream twins once forwarded. `close` undoes all of it exactly
+ * once (cancels calls downstream, drops subscriptions, releases the downstream hold, rejects waiters).
+ */
+export declare class RelayHold {
+    #private;
+    readonly origin: Connection;
+    readonly frame: Extract<Frame, {
+        t: "hold";
+    }>;
+    readonly principal: Principal;
+    readonly client: boolean;
+    /** The origin's authorization generation when the hold arrived; a revocation bumps it. */
+    readonly generation: number;
+    down: Connection | undefined;
+    downId: number;
+    closed: boolean;
+    readonly calls: Map<number, RelayCall>;
+    readonly subs: Map<number, {
+        readonly member: string;
+        downId: number | undefined;
+    }>;
+    constructor(origin: Connection, frame: Extract<Frame, {
+        t: "hold";
+    }>, principal: Principal, client: boolean);
+    get originId(): number;
+    /** Still authorized as it was when it arrived. */
+    get current(): boolean;
+    /** The downstream connection once the route resolved; rejects if the relay closes first. */
+    ready(): Promise<Connection>;
+    /** Forwards the hold (and what queued meanwhile) to `down`. */
+    open(down: Connection): void;
+    subscribe(originSubId: number, member: string): void;
+    unsubscribe(originSubId: number, forward?: boolean): void;
+    /**
+     * Closes the relay. `releaseDown`: the downstream hold is still there (origin released, disconnected, or was
+     * revoked): cancel its calls and release it. `notify`: tell the origin the hold is gone.
+     */
+    close(error: unknown, options: {
+        readonly releaseDown: boolean;
+        readonly notify: boolean;
+    }): void;
+}
+/** One relayed call: settles once, by result, cancellation or the relay closing; removes both mappings. */
+export declare class RelayCall {
+    #private;
+    readonly relay: RelayHold;
+    readonly originId: number;
+    readonly downId: number;
+    constructor(relay: RelayHold, originId: number, downId: number, pending: Pending);
+    finish(error: unknown, value?: unknown): void;
+    /** Cancels downstream (when the downstream hold still exists) and settles with `error`. */
+    cancel(error: unknown, forward: boolean): void;
+}
+/** One end of a link on a host: consumer of remote handles, provider for the peer's holds, and relay. */
+export declare class Connection implements RemoteChannel {
+    #private;
+    readonly host: HostImpl;
+    readonly link: Link;
+    /** `upstream`: the link to this host's parent. `downstream`: a link this host accepted. */
+    readonly role: "upstream" | "downstream";
+    readonly peer: Peer;
+    principal: Principal;
+    readonly restamp: ((principal: Principal) => Principal | undefined) | undefined;
+    /** Bumped when the stamped principal is revoked or re-stamped: relays from before are refused. */
+    generation: number;
+    /** The epoch a downstream host peer runs (from its hello, then from commits). */
+    peerEpoch: number | undefined;
+    /** A downstream host peer is usable once it runs this host's current epoch (see `HostImpl.peerHello`). */
+    synced: boolean;
+    /** Epochs this child announced while behind this host (fenced): this host never ran them. */
+    readonly fencedEpochs: Set<number>;
+    readonly remotes: Map<number, RemoteHandle>;
+    readonly calls: Map<number, Pending>;
+    readonly subs: Map<number, (frame: StateSink) => void>;
+    readonly served: Map<number, Served>;
+    readonly incoming: Map<number, AbortController>;
+    readonly feeds: Map<number, () => void>;
+    /** Origin side of relays: the peer's sub ids that are relayed. */
+    readonly relaySubs: Map<number, RelayHold>;
+    readonly relayedHolds: Map<number, RelayHold>;
+    readonly relayedCalls: Map<number, RelayCall>;
+    readonly relayedSubs: Map<number, {
+        readonly relay: RelayHold;
+        readonly originSubId: number;
+    }>;
+    /** Reload votes awaited from this (child) peer. */
+    readonly votes: Map<number, Pending>;
+    constructor(host: HostImpl, link: Link, config: {
+        readonly role: "upstream" | "downstream";
+        readonly principal: Principal;
+        readonly peer: Peer;
+        readonly restamp?: (principal: Principal) => Principal | undefined;
+    } & LinkOptions);
+    get open(): boolean;
+    /** The peer's name: configured for downstream hosts, announced by the parent upstream. */
+    get name(): string | undefined;
+    send(frame: Frame): void;
+    nextId(): number;
+    /** Resolves once the peer is usable (a host peer runs this host's epoch); rejects if the link closes first. */
+    whenSynced(): Promise<void>;
+    markSynced(epoch: number): void;
+    /** Revokes the stamped principal: relays made under it close at once (also those still resolving a route). */
+    revoke(next: Principal | undefined): void;
+    hold(handle: RemoteHandle): number;
+    release(id: number): void;
+    call(hold: number, member: string, args: unknown, root: RootRef | undefined, signal: AbortSignal): Promise<unknown>;
+    sub(hold: number, member: string, sink: (frame: StateSink) => void): number;
+    unsub(id: number): void;
+}
+export {};
+//# sourceMappingURL=connection.d.ts.map

package/dist/connection.d.ts.map

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