@serfab/cadre-host 1.13.0 → 1.15.0

package/dist/hosted/hosted-node-watcher.js

@@ -0,0 +1,260 @@
+import debug from 'debug';
+import { decodeCadreInvitation } from '@serfab/cadre-core';
+import { errorMessage, readWatchedNodeStatus, reportsClaim, reportsRemoval } from './node-status.js';
+const log = debug('cadre:host:hosted-node-watcher');
+/** How often an unclaimed node's `/status` is read for the claim, and a joining node's for its redemption. */
+export const HOSTED_NODE_CLAIM_POLL_MS = 2000;
+/** How often a joined node's `/status` is read for its connection count. */
+export const HOSTED_NODE_CONNECTED_POLL_MS = 15000;
+/** The `error` a node an owner removed from its cadre is recorded with. */
+const REMOVED_BY_OWNER_ERROR = 'Removed from its cadre by an owner';
+/** Statuses the watcher reads every tick: a node still on its way into its cadre. */
+const PENDING_STATUSES = new Set(['unclaimed', 'joining']);
+/**
+ * Follows each hosted node's `/status`: an `unclaimed` record becomes `joined` when
+ * the node reports a finished claim; a `joining` record becomes `joined` when a member
+ * accepted its invitation, or `error` when the redemption failed; a `joined`
+ * record's `connected` follows the node's control-connection count; and any of them
+ * becomes `error` when the node reports that an owner removed it from its cadre.
+ * Best-effort: a poll that fails is retried on the next tick, and nothing here throws
+ * out of the timer.
+ *
+ * One timer at the claim cadence drives all three: every tick polls every unclaimed and
+ * joining node, and each joined node every {@link HOSTED_NODE_CONNECTED_POLL_MS}, or at once when it
+ * was poked — the orchestrator's state change on a respawn pokes the node, and the
+ * poke stands until a poll succeeds, so a respawned child is noticed on its first
+ * answer rather than at the next 15 s mark. Polls are serialized on one promise
+ * tail so a timer pass and a poked pass cannot both write one record.
+ *
+ * NOTE: the 2 s timer ticks while nothing is unclaimed (one cached store read, no
+ * I/O per tick); if it ever shows up in a profile, stop it when no record is
+ * unclaimed and restart it from `poke`.
+ */
+export class HostedNodeWatcher {
+    constructor(opts) {
+        this.tail = Promise.resolve();
+        /** When each joined node's `/status` last answered (ms since epoch). */
+        this.lastPolledAt = new Map();
+        /** Joined nodes to poll on the next pass regardless of cadence. */
+        this.due = new Set();
+        this.store = opts.store;
+        this.orchestrator = opts.orchestrator;
+        this.now = opts.now;
+        this.emit = opts.emit;
+    }
+    /** Start the timer and the state-change subscription, and poll once. Idempotent. */
+    start() {
+        if (this.timer)
+            return;
+        this.unsubscribe = this.orchestrator.onStateChange?.((info) => { this.poke(info.id); });
+        this.timer = setInterval(() => { this.poke(); }, HOSTED_NODE_CLAIM_POLL_MS);
+        this.timer.unref();
+        this.poke();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+    }
+    /** Ask for a pass now; `id` names a joined node to poll ahead of its cadence. Fire-and-forget. */
+    poke(id) {
+        if (id)
+            this.due.add(id);
+        void this.poll().catch((err) => { log('status poll failed: %s', errorMessage(err)); });
+    }
+    /** One pass over every unclaimed, joining and due joined record, serialized against the others. */
+    poll() {
+        const next = this.tail.then(() => this.pollOnce(), () => this.pollOnce());
+        this.tail = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    async pollOnce() {
+        let records;
+        try {
+            records = this.store.list().filter((n) => PENDING_STATUSES.has(n.status) || n.status === 'joined');
+        }
+        catch (err) {
+            // A malformed hosted-nodes.json throws on every load; log rather than let it escape the timer.
+            log('poll could not list hosted nodes: %s', errorMessage(err));
+            return;
+        }
+        this.forgetRemoved(new Set(records.map((r) => r.id)));
+        for (const record of records) {
+            if (this.shouldPoll(record))
+                await this.pollOne(record);
+        }
+    }
+    /** Drop the cadence and poke bookkeeping of nodes no longer on record, so neither map grows with removals. */
+    forgetRemoved(live) {
+        for (const id of this.lastPolledAt.keys())
+            if (!live.has(id))
+                this.lastPolledAt.delete(id);
+        for (const id of this.due)
+            if (!live.has(id))
+                this.due.delete(id);
+    }
+    shouldPoll(record) {
+        if (PENDING_STATUSES.has(record.status) || this.due.has(record.id))
+            return true;
+        const last = this.lastPolledAt.get(record.id);
+        return last === undefined || this.now().getTime() - last >= HOSTED_NODE_CONNECTED_POLL_MS;
+    }
+    async pollOne(record) {
+        if (!record.statusEndpoint)
+            return;
+        let status;
+        try {
+            status = await readWatchedNodeStatus(record.statusEndpoint);
+        }
+        catch (err) {
+            log('hosted node %s did not answer /status (retried next tick): %s', record.id, errorMessage(err));
+            return;
+        }
+        this.lastPolledAt.set(record.id, this.now().getTime());
+        this.due.delete(record.id);
+        // Re-read: `record` predates the round-trip and `store.put` replaces the whole
+        // row, so writing that copy back would resurrect a node removed meanwhile, or
+        // undo a respawn's new handles. The store is synchronous, so this read-decide-
+        // write is atomic against the event loop as long as no `await` sneaks in.
+        const current = this.store.get(record.id);
+        if (!current || current.status !== record.status)
+            return;
+        if (reportsRemoval(status)) {
+            await this.applyRemoved(current, status);
+        }
+        else if (current.status === 'unclaimed') {
+            this.applyUnclaimed(current, status);
+        }
+        else if (current.status === 'joining') {
+            await this.applyJoining(current, status);
+        }
+        else {
+            this.applyJoined(current, status);
+        }
+    }
+    /** An unclaimed node that reports a finished claim is `joined`, with the party and owner the claim named. */
+    applyUnclaimed(current, status) {
+        if (!reportsClaim(status))
+            return;
+        this.store.put({
+            ...current,
+            status: 'joined',
+            partyId: status.node.partyId,
+            ownerKey: status.node.claimedBy,
+            peerId: current.peerId ?? status.peerId,
+            connected: status.node.connectionPaths.total > 0,
+            updatedAt: this.now().toISOString(),
+        });
+        log('hosted node %s was claimed by owner %s into cadre %s', current.id, status.node.claimedBy.slice(0, 8), status.node.partyId);
+        this.emit({ kind: 'claimed', id: current.id });
+    }
+    /**
+     * A joining node whose redemption settled: `joined` with the member that admitted it and
+     * the invitation's issuer as its owner, or `error` with the reason and whether Retry may
+     * help. A failed node's child is stopped after the write, as a give-up's is, and kept
+     * with its workdir for Retry; the write comes first so the exit the stop raises finds
+     * a record the supervisor leaves alone. Still `pending`: nothing.
+     */
+    async applyJoining(current, status) {
+        const invitation = status.node.invitation;
+        if (invitation?.state === 'accepted') {
+            const ownerKey = issuerOf(current);
+            this.store.put({
+                ...current,
+                status: 'joined',
+                ...(ownerKey ? { ownerKey } : {}),
+                ...(invitation.memberPeerId ? { memberPeerId: invitation.memberPeerId } : {}),
+                peerId: current.peerId ?? status.peerId,
+                connected: status.node.connectionPaths.total > 0,
+                updatedAt: this.now().toISOString(),
+            });
+            log('hosted node %s joined cadre %s at member %s', current.id, current.partyId, invitation.memberPeerId ?? '(unnamed)');
+            this.emit({ kind: 'joined', id: current.id });
+            return;
+        }
+        if (invitation?.state !== 'failed')
+            return;
+        const error = invitation.error ?? 'the invitation could not be redeemed';
+        this.store.put({
+            ...current,
+            status: 'error',
+            error,
+            retryable: invitation.retryable === true,
+            peerId: current.peerId ?? status.peerId,
+            updatedAt: this.now().toISOString(),
+        });
+        log('hosted node %s could not join cadre %s (%s): %s', current.id, current.partyId, invitation.retryable ? 'retryable' : 'final', error);
+        this.emit({ kind: 'changed', id: current.id });
+        await this.stopChild(current, 'its invitation failed');
+    }
+    /**
+     * A node that reports an owner removed it from its cadre: `error`, not retryable, its child
+     * stopped after the write as a failed invitation's is, and its workdir kept for Remove (or a
+     * claim node's Reset). The child had already stopped its node, and stays up only to report
+     * the removal, so stopping it loses nothing. The party and owner come from the report, for an
+     * `unclaimed` record whose claim this watcher never saw: its own party is the placeholder.
+     */
+    async applyRemoved(current, status) {
+        const partyId = status.node.partyId || current.partyId;
+        const ownerKey = current.ownerKey ?? status.node.claimedBy;
+        this.store.put({
+            ...current,
+            status: 'error',
+            partyId,
+            ...(ownerKey ? { ownerKey } : {}),
+            error: REMOVED_BY_OWNER_ERROR,
+            retryable: false,
+            removedByOwner: true,
+            updatedAt: this.now().toISOString(),
+        });
+        log('hosted node %s was removed from cadre %s by an owner', current.id, partyId);
+        this.emit({ kind: 'changed', id: current.id });
+        await this.stopChild(current, 'an owner removed it');
+    }
+    /** Stop a node's child after its record went `error`; a failed stop is logged, the record stands. */
+    async stopChild(current, why) {
+        if (!current.dockerId)
+            return;
+        try {
+            await this.orchestrator.stopContainer(current.dockerId);
+        }
+        catch (err) {
+            log('failed to stop hosted node %s after %s: %s', current.id, why, errorMessage(err));
+        }
+    }
+    /**
+     * A joined node's `connected` follows its control-connection count; published only on a
+     * change. Its `/status` keeps reporting the invitation for as long as the child that
+     * redeemed it runs, and whatever it says there is ignored: the node is a member, and the
+     * record says so.
+     */
+    applyJoined(current, status) {
+        const connected = status.node.connectionPaths.total > 0;
+        if (current.connected === connected)
+            return;
+        this.store.put({ ...current, connected, updatedAt: this.now().toISOString() });
+        log('hosted node %s is now %s', current.id, connected ? 'connected' : 'disconnected');
+        this.emit({ kind: 'changed', id: current.id });
+    }
+}
+/**
+ * The owner a joined invitation node is shown under: the issuer of its invitation. The
+ * record's bundle decoded at `join`, so this fails only on a hand-edited
+ * `hosted-nodes.json` or on a record written before invitations carried their
+ * `sereus-invite:1.` prefix; the node is a member either way, so the record says so without one.
+ */
+function issuerOf(node) {
+    if (node.join.kind !== 'invitation')
+        return undefined;
+    try {
+        return decodeCadreInvitation(node.join.encoded).invite.issuerKey;
+    }
+    catch (err) {
+        log('hosted node %s carries an invitation that no longer decodes: %s', node.id, errorMessage(err));
+        return undefined;
+    }
+}
+//# sourceMappingURL=hosted-node-watcher.js.map

package/dist/hosted/hosted-node-watcher.js.map

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

package/dist/hosted/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Hosted nodes: the host's "Join a cadre" action and what follows from it. See
+ * ./types.ts for the record, ./hosted-node-service.ts for the lifecycle,
+ * ./hosted-node-watcher.ts for following each node's `/status`, ./claim-details.ts for
+ * the QR payload, and ./hosted-node-supervisor.ts for the respawn invariant.
+ */
+export { HostedNodeStore } from './hosted-node-store.js';
+export { HostedNodeService, HOSTED_NODE_SPAWNING_TTL_MS, HOSTED_NODE_REAP_SWEEP_MS, } from './hosted-node-service.js';
+export type { HostedNodeOrchestrator, HostedNodeServiceOptions, JoinOptions, RespawnOptions, RespawnResult, } from './hosted-node-service.js';
+export type { ClaimDetails, HostedNodeAddressSource } from './claim-details.js';
+export { HOSTED_NODE_CLAIM_POLL_MS, HOSTED_NODE_CONNECTED_POLL_MS, } from './hosted-node-watcher.js';
+export { HostedNodeSupervisor, HOSTED_NODE_RESPAWN_BACKOFF_BASE_MS, HOSTED_NODE_RESPAWN_BACKOFF_MAX_MS, HOSTED_NODE_RESPAWN_MAX_ATTEMPTS, HOSTED_NODE_RESPAWN_HEALTHY_MS, HOSTED_NODE_RESPAWN_SWEEP_MS, } from './hosted-node-supervisor.js';
+export type { HostedNodeSupervisorOptions, SupervisedOrchestrator, } from './hosted-node-supervisor.js';
+export { PLACEHOLDER_PARTY } from './node-status.js';
+export { HostedNodeError } from './types.js';
+export type { HostedNode, HostedNodeChange, HostedNodeChangeKind, HostedNodeChangeListener, HostedNodeErrorCode, HostedNodeClaimJoin, HostedNodeFile, HostedNodeInvitationJoin, HostedNodeJoin, HostedNodeJoinView, HostedNodeStatus, HostedNodeView, } from './types.js';

package/dist/hosted/index.js

@@ -0,0 +1,13 @@
+/**
+ * Hosted nodes: the host's "Join a cadre" action and what follows from it. See
+ * ./types.ts for the record, ./hosted-node-service.ts for the lifecycle,
+ * ./hosted-node-watcher.ts for following each node's `/status`, ./claim-details.ts for
+ * the QR payload, and ./hosted-node-supervisor.ts for the respawn invariant.
+ */
+export { HostedNodeStore } from './hosted-node-store.js';
+export { HostedNodeService, HOSTED_NODE_SPAWNING_TTL_MS, HOSTED_NODE_REAP_SWEEP_MS, } from './hosted-node-service.js';
+export { HOSTED_NODE_CLAIM_POLL_MS, HOSTED_NODE_CONNECTED_POLL_MS, } from './hosted-node-watcher.js';
+export { HostedNodeSupervisor, HOSTED_NODE_RESPAWN_BACKOFF_BASE_MS, HOSTED_NODE_RESPAWN_BACKOFF_MAX_MS, HOSTED_NODE_RESPAWN_MAX_ATTEMPTS, HOSTED_NODE_RESPAWN_HEALTHY_MS, HOSTED_NODE_RESPAWN_SWEEP_MS, } from './hosted-node-supervisor.js';
+export { PLACEHOLDER_PARTY } from './node-status.js';
+export { HostedNodeError } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/hosted/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hosted/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,yBAAyB,GAC1B,MAAM,0BAA0B,CAAC;AASlC,OAAO,EACL,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oBAAoB,EACpB,mCAAmC,EACnC,kCAAkC,EAClC,gCAAgC,EAChC,8BAA8B,EAC9B,4BAA4B,GAC7B,MAAM,6BAA6B,CAAC;AAKrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/hosted/node-status.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Reading a hosted child's `/status` — the one window the host has onto a node it
+ * runs: its peer id and addresses before the claim, the claim itself, the party
+ * and the owner key after it, and its removal by an owner. Shared by
+ * `HostedNodeService.claimDetails` and the status watcher.
+ */
+import type { HealthStatus } from '@serfab/cadre-cli';
+/** The party an unclaimed child's config names; the claim replaces it. */
+export declare const PLACEHOLDER_PARTY = "unclaimed";
+/** The `/status` URL for a spawn's `/health` URL (same server and port). */
+export declare function statusUrlFor(healthEndpoint: string): string;
+/** A `/status` answer from a node that has its peer identity. */
+export type NodeStatus = HealthStatus & {
+    peerId: string;
+};
+/**
+ * A `/status` answer from a child an owner removed from its cadre. The child stopped its node
+ * and stays up only to report this, so it has no peer identity.
+ */
+export type RemovedNodeStatus = HealthStatus & {
+    node: {
+        removed: NonNullable<HealthStatus['node']['removed']>;
+    };
+};
+/**
+ * The child's `/status`, fresh every call. Throws `node_unavailable` while the child
+ * does not answer, answers with an error, or has no peer identity yet — every one of
+ * which a caller retries.
+ */
+export declare function readNodeStatus(statusEndpoint: string): Promise<NodeStatus>;
+/**
+ * {@link readNodeStatus} for the watcher, which also has to hear a removal: a child reporting
+ * one is answered as it is rather than refused for having no peer identity.
+ */
+export declare function readWatchedNodeStatus(statusEndpoint: string): Promise<NodeStatus | RemovedNodeStatus>;
+/** Whether the child reports that an owner removed it from its cadre. */
+export declare function reportsRemoval(status: HealthStatus): status is RemovedNodeStatus;
+/**
+ * Whether `/status` reports a finished claim: a claim on record AND the party it
+ * named. `claim` flips to `claimed` the moment the node records the claim, but the
+ * node then restarts in-process into the claimed party, and until that restart
+ * finishes `partyId` is still the placeholder (or empty while the node object is
+ * being rebuilt). Writing `joined` on the flag alone would record the placeholder
+ * as the node's cadre.
+ */
+export declare function reportsClaim(status: NodeStatus): status is NodeStatus & {
+    node: {
+        claimedBy: string;
+    };
+};
+export declare function errorMessage(err: unknown): string;

package/dist/hosted/node-status.js

@@ -0,0 +1,77 @@
+/**
+ * Reading a hosted child's `/status` — the one window the host has onto a node it
+ * runs: its peer id and addresses before the claim, the claim itself, the party
+ * and the owner key after it, and its removal by an owner. Shared by
+ * `HostedNodeService.claimDetails` and the status watcher.
+ */
+import { HostedNodeError } from './types.js';
+/** The party an unclaimed child's config names; the claim replaces it. */
+export const PLACEHOLDER_PARTY = 'unclaimed';
+/** The `/status` URL for a spawn's `/health` URL (same server and port). */
+export function statusUrlFor(healthEndpoint) {
+    const url = new URL(healthEndpoint);
+    url.pathname = '/status';
+    return url.toString();
+}
+/**
+ * The child's `/status`, fresh every call. Throws `node_unavailable` while the child
+ * does not answer, answers with an error, or has no peer identity yet — every one of
+ * which a caller retries.
+ */
+export async function readNodeStatus(statusEndpoint) {
+    return requirePeerIdentity(await fetchNodeStatus(statusEndpoint));
+}
+/**
+ * {@link readNodeStatus} for the watcher, which also has to hear a removal: a child reporting
+ * one is answered as it is rather than refused for having no peer identity.
+ */
+export async function readWatchedNodeStatus(statusEndpoint) {
+    const status = await fetchNodeStatus(statusEndpoint);
+    return reportsRemoval(status) ? status : requirePeerIdentity(status);
+}
+/** Whether the child reports that an owner removed it from its cadre. */
+export function reportsRemoval(status) {
+    return Boolean(status.node.removed);
+}
+async function fetchNodeStatus(statusEndpoint) {
+    let res;
+    try {
+        res = await fetch(statusEndpoint);
+    }
+    catch (err) {
+        throw new HostedNodeError('node_unavailable', `Hosted node unreachable: ${errorMessage(err)}`);
+    }
+    if (!res.ok) {
+        throw new HostedNodeError('node_unavailable', `Hosted node /status returned ${res.status}`);
+    }
+    try {
+        return (await res.json());
+    }
+    catch (err) {
+        throw new HostedNodeError('node_unavailable', `Hosted node /status is not JSON: ${errorMessage(err)}`);
+    }
+}
+function requirePeerIdentity(status) {
+    if (!status.peerId || !status.multiaddrs?.length) {
+        throw new HostedNodeError('node_unavailable', 'Hosted node has no peer identity yet');
+    }
+    return status;
+}
+/**
+ * Whether `/status` reports a finished claim: a claim on record AND the party it
+ * named. `claim` flips to `claimed` the moment the node records the claim, but the
+ * node then restarts in-process into the claimed party, and until that restart
+ * finishes `partyId` is still the placeholder (or empty while the node object is
+ * being rebuilt). Writing `joined` on the flag alone would record the placeholder
+ * as the node's cadre.
+ */
+export function reportsClaim(status) {
+    return status.node.claim === 'claimed'
+        && status.node.claimedBy !== undefined
+        && status.node.partyId !== ''
+        && status.node.partyId !== PLACEHOLDER_PARTY;
+}
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=node-status.js.map

package/dist/hosted/node-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-status.js","sourceRoot":"","sources":["../../src/hosted/node-status.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,0EAA0E;AAC1E,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAE7C,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAC,cAAsB;IACjD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,CAAC;IACpC,GAAG,CAAC,QAAQ,GAAG,SAAS,CAAC;IACzB,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC;AAWD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,cAAsB;IACzD,OAAO,mBAAmB,CAAC,MAAM,eAAe,CAAC,cAAc,CAAC,CAAC,CAAC;AACpE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,cAAsB;IAChE,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,cAAc,CAAC,CAAC;IACrD,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACvE,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,cAAc,CAAC,MAAoB;IACjD,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,cAAsB;IACnD,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,cAAc,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,eAAe,CAAC,kBAAkB,EAAE,4BAA4B,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjG,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,eAAe,CAAC,kBAAkB,EAAE,gCAAgC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAiB,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,eAAe,CAAC,kBAAkB,EAAE,oCAAoC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACzG,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAoB;IAC/C,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;QACjD,MAAM,IAAI,eAAe,CAAC,kBAAkB,EAAE,sCAAsC,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,MAAoB,CAAC;AAC9B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,MAAkB;IAC7C,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS;WACjC,MAAM,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS;WACnC,MAAM,CAAC,IAAI,CAAC,OAAO,KAAK,EAAE;WAC1B,MAAM,CAAC,IAAI,CAAC,OAAO,KAAK,iBAAiB,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC"}

package/dist/hosted/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Hosted-node types for cadre-host.
+ *
+ * A **hosted node** is a child process the host runs for some cadre. It gets into its
+ * cadre one of two ways: the host starts it waiting to be claimed and shows its addresses
+ * and claim secret as a QR code, which the owner's phone scans to claim the node
+ * (`CadreNode.claimNode`); or the host starts it with a cadre invitation the owner's app
+ * minted, which the node redeems at a member of the cadre. Either way the host holds no
+ * owner key and is not an owner of any cadre its nodes serve.
+ *
+ * Records live in `<dataDir>/hosted-nodes.json` (`HostedNodeStore`). A record's id is also
+ * its orchestrator container id and the name of its working directory.
+ */
+/**
+ * Lifecycle of one hosted node:
+ *   spawning   → the record is written, the child not yet spawned.
+ *   unclaimed  → (claim) the child is up with a claim secret, waiting for a phone to claim it.
+ *   joining    → (invitation) the child is up, its redemption of the invitation not yet settled.
+ *   joined     → in its cadre: claimed, or the invitation accepted by a member.
+ *   error      → the supervisor gave up on it, the stuck-`spawning` reap found it, the
+ *                invitation was refused or no member could be reached (`retryable` says which),
+ *                or an owner removed it from its cadre (`removedByOwner`).
+ *
+ * Removal deletes the row; there is no terminal "removed" status, and a node an owner removed
+ * from its cadre is, to the host, a node that failed and waits for the admin. An `error`
+ * record keeps its working directory (its identity key) until it is removed or reset.
+ */
+export type HostedNodeStatus = 'spawning' | 'unclaimed' | 'joining' | 'joined' | 'error';
+/**
+ * The node was started with a claim secret and waits for a phone to present it.
+ */
+export interface HostedNodeClaimJoin {
+    kind: 'claim';
+    /** The node's one-time claim secret, base64url. Only `claimDetails` ever returns it. */
+    secret: string;
+}
+/**
+ * The node was started with a cadre invitation and redeems it at a member of the cadre.
+ * Kept for a respawn while `joining`: the child redeems again, and a member answers a node
+ * that already got in as accepted.
+ */
+export interface HostedNodeInvitationJoin {
+    kind: 'invitation';
+    /**
+     * The bundle as the owner's app encoded it (`encodeCadreInvitation`). It carries the
+     * invitation's private key, so it is redacted like the claim secret.
+     *
+     * NOTE: kept on disk after the node joins, though nothing reads it then (a joined node is
+     * respawned without it). An invitation with uses left admits whoever reads it; if
+     * multi-use invitations get pasted into hosts, drop it at the watcher's `joined` write.
+     */
+    encoded: string;
+}
+/** How a node gets into its cadre. */
+export type HostedNodeJoin = HostedNodeClaimJoin | HostedNodeInvitationJoin;
+/** One hosted node, as persisted in `hosted-nodes.json`. */
+export interface HostedNode {
+    /** `hn_<base64url of 12 random bytes>` — also the orchestrator container id and workdir name. */
+    id: string;
+    join: HostedNodeJoin;
+    /**
+     * A claim node: `unclaimed` (the placeholder party the child's config names) until the
+     * claim reports the party; the claimant's party after. An invitation node: the
+     * invitation's party from the start.
+     */
+    partyId: string;
+    /** Hosted nodes run the `storage` profile: they participate in strands and are dialable. */
+    profile: 'storage';
+    status: HostedNodeStatus;
+    /** Orchestrator handle (opaque `pid:token`), set once the child is spawned. */
+    dockerId?: string;
+    /** The child's loopback `/status` URL, from the spawn result. */
+    statusEndpoint?: string;
+    /** Read once from `/status`; the claim details need it before the claim. */
+    peerId?: string;
+    /**
+     * Set when the node joins: `/status.node.claimedBy` for a claim, the invitation's issuer
+     * key for an invitation. The UI shows its first 8 characters.
+     */
+    ownerKey?: string;
+    /** An invitation node, once joined: the member that admitted it, when its address named one. */
+    memberPeerId?: string;
+    /** From the last status poll: the node holds at least one control connection. */
+    connected?: boolean;
+    /**
+     * Respawn bookkeeping, owned by the supervisor's backoff. Absent until the first
+     * respawn attempt. Not secret — it rides along in `HostedNodeView`.
+     */
+    respawn?: {
+        attempts: number;
+        lastAttemptAt: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    /** Failure detail when `status === 'error'`. */
+    error?: string;
+    /**
+     * Set with `error` when an invitation failed: whether Retry may start the node again with
+     * the same invitation (no member could be reached), or the invitation itself was refused.
+     * False on a node an owner removed; absent on every other `error`.
+     */
+    retryable?: boolean;
+    /**
+     * Set with `error` when the node reported that an owner removed it from its cadre, so the
+     * UI words it as a removal rather than a failure to join or to stay up.
+     */
+    removedByOwner?: true;
+}
+/** `join` without its secret: what `list`, `get`, the routes and the events carry. */
+export type HostedNodeJoinView = {
+    kind: HostedNodeJoin['kind'];
+};
+/** The wire shape of a hosted node: the record with the claim secret or the invitation stripped. */
+export interface HostedNodeView extends Omit<HostedNode, 'join'> {
+    join: HostedNodeJoinView;
+}
+/** On-disk shape of `hosted-nodes.json`. Keyed by node id. */
+export interface HostedNodeFile {
+    version: 1;
+    nodes: Record<string, Omit<HostedNode, 'id'>>;
+}
+/** Error codes thrown by the hosted-node service, mapped to HTTP status by `server/error-handler.ts`. */
+export type HostedNodeErrorCode = 'not_found' | 'invalid_state' | 'invalid_request' | 'node_unavailable' | 'orchestrator_error' | 'storage_error';
+/** Typed hosted-node error carrying a stable `code` for HTTP mapping. */
+export declare class HostedNodeError extends Error {
+    readonly code: HostedNodeErrorCode;
+    constructor(code: HostedNodeErrorCode, message: string);
+}
+/**
+ * What changed about a hosted node: `added` (a join started the node), `claimed` (the
+ * watcher saw the claim), `joined` (the watcher saw a member accept the invitation),
+ * `removed`, or `changed` (anything else: a respawn, a liveness change, a refused
+ * invitation, a retry, a give-up). The server publishes each as the `hosted-nodes-changed`
+ * SSE event.
+ */
+export type HostedNodeChangeKind = 'added' | 'claimed' | 'joined' | 'removed' | 'changed';
+export interface HostedNodeChange {
+    kind: HostedNodeChangeKind;
+    id: string;
+}
+export type HostedNodeChangeListener = (change: HostedNodeChange) => void;

package/dist/hosted/types.js

@@ -0,0 +1,22 @@
+/**
+ * Hosted-node types for cadre-host.
+ *
+ * A **hosted node** is a child process the host runs for some cadre. It gets into its
+ * cadre one of two ways: the host starts it waiting to be claimed and shows its addresses
+ * and claim secret as a QR code, which the owner's phone scans to claim the node
+ * (`CadreNode.claimNode`); or the host starts it with a cadre invitation the owner's app
+ * minted, which the node redeems at a member of the cadre. Either way the host holds no
+ * owner key and is not an owner of any cadre its nodes serve.
+ *
+ * Records live in `<dataDir>/hosted-nodes.json` (`HostedNodeStore`). A record's id is also
+ * its orchestrator container id and the name of its working directory.
+ */
+/** Typed hosted-node error carrying a stable `code` for HTTP mapping. */
+export class HostedNodeError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'HostedNodeError';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/hosted/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/hosted/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA0HH,yEAAyE;AACzE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAGxC,YAAY,IAAyB,EAAE,OAAe;QACpD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}