@plane31/blind-relay 0.2.0 → 0.4.0

package/dist/client.js

@@ -50,8 +50,16 @@ export function resolvedAccountId(r) {
     return pinFromCertificate(doc).identityId;
 }
 export const DEFAULT_CATCH_UP = { maxRecords: 500, maxMs: 5_000 };
+const emptyTimings = () => ({ resume: 0, bootstrap: 0, metadata: 0, preferences: 0, epoch: 0, outbox: 0, inbox: 0, maintenance: 0, total: 0, bytesSent: 0, bytesReceived: 0 });
+/** A monotonic wall clock for durations; the protocol clock (`now`) is not used, since a test drives it by hand. */
+const wall = () => {
+    const g = globalThis;
+    return typeof g.performance?.now === "function" ? g.performance.now() : Date.now();
+};
 function syncError(operation, e, extra = {}) {
-    return e instanceof KavachError ? { operation, code: e.code, stage: e.stage, retryable: e.retryable, ...extra } : { operation, code: "UNEXPECTED", stage: operation, retryable: false, ...extra };
+    return e instanceof KavachError
+        ? { operation, code: e.code, stage: e.stage, retryable: e.retryable, ...(e.retryAfterMs === undefined ? {} : { retryAfterMs: e.retryAfterMs }), ...extra }
+        : { operation, code: "UNEXPECTED", stage: operation, retryable: false, ...extra };
 }
 const RESET_LIST_RECHECK_MS = 86400000n;
 export async function open(options) {
@@ -84,6 +92,9 @@ class ClientImpl {
     selfPin;
     trust;
     syncing;
+    closed = false;
+    /** Every public operation in flight, so `close()` can wait for them. */
+    running = new Set();
     /** The current sync's reading budget: records, and the links of a succession chain, count against it. */
     syncBudget;
     backupChecked = false;
@@ -99,16 +110,45 @@ class ClientImpl {
         this.now = options.now ?? (() => BigInt(Date.now()));
         this.trust = new ResetTrust(options.resetTrust);
         this.circles = {
-            create: () => this.createCircle(),
-            requestJoin: (c, o, opts) => this.requestJoin(c, o, opts?.shareOnApproval ?? true),
-            approve: (c, n) => this.approve(c, n),
-            remove: (c, m) => this.changeMembership(c, { remove: m }),
-            leave: (c) => this.leave(c),
-            setEnabled: (c, e) => this.setEnabled(c, e),
-            closeCircle: (c) => this.closeCircle(c),
+            create: () => this.track("createCircle", () => this.createCircle()),
+            requestJoin: (c, o, opts) => this.track("requestJoin", () => this.requestJoin(c, o, opts?.shareOnApproval ?? true)),
+            approve: (c, n) => this.track("approve", () => this.approve(c, n)),
+            remove: (c, m) => this.track("changeMembership", () => this.changeMembership(c, { remove: m })),
+            leave: (c) => this.track("leave", () => this.leave(c)),
+            setEnabled: (c, e) => this.track("setEnabled", () => this.setEnabled(c, e)),
+            closeCircle: (c) => this.track("closeCircle", () => this.closeCircle(c)),
             list: () => this.listCircles()
         };
     }
+    // Every public operation that writes enters through `track`, explicitly and typed, so `close()`
+    // refuses new ones and waits for those in flight. Reads stay untracked.
+    initializeAccount() {
+        return this.track("initializeAccount", () => this.initializeAccountNow());
+    }
+    restoreAccount(recoveryCode) {
+        return this.track("restoreAccount", () => this.restoreAccountNow(recoveryCode));
+    }
+    enqueue(kind, payload, options = {}) {
+        return this.track("enqueue", () => this.enqueueNow(kind, payload, options));
+    }
+    receive(wire) {
+        return this.track("receive", () => receiveRecord(this.inboxDeps(), wire));
+    }
+    prepareReplacement() {
+        return this.track("prepareReplacement", () => this.prepareReplacementNow());
+    }
+    completeReplacement(input) {
+        return this.track("completeReplacement", () => this.completeReplacementNow(input));
+    }
+    resetAccount(options) {
+        return this.track("resetAccount", () => this.resetAccountNow(options));
+    }
+    replaceDevice(options) {
+        return this.track("replaceDevice", () => this.replaceDeviceNow(options));
+    }
+    syncUntilDrained(options = {}) {
+        return this.track("syncUntilDrained", () => this.drainNow(options));
+    }
     // Loading ---------------------------------------------------------------------------------------
     async load() {
         await this.finishInterruptedReset();
@@ -143,8 +183,19 @@ class ClientImpl {
             retired: rows.retired
         });
     }
-    /** Each listener on its own: a throwing subscriber affects neither the other listeners nor the protocol. */
+    /** Refuse after `close()`, and keep the operation's promise until it settles. */
+    track(stage, fn) {
+        if (this.closed)
+            return Promise.reject(new KavachError("CLOSED", stage, "the client is closed"));
+        const p = fn();
+        this.running.add(p);
+        void p.finally(() => this.running.delete(p)).catch(() => undefined);
+        return p;
+    }
+    /** Each listener on its own: a throwing subscriber affects neither the other listeners nor the protocol. Nothing after `close()`. */
     emit(event) {
+        if (this.closed)
+            return;
         for (const l of this.listeners) {
             try {
                 l(event);
@@ -284,7 +335,7 @@ class ClientImpl {
         });
     }
     // Enrollment ------------------------------------------------------------------------------------
-    async initializeAccount() {
+    async initializeAccountNow() {
         const stage = "initializeAccount";
         const opened = await openStore(this.store, this.secrets, this.accountName);
         if (opened.kind !== "fresh" && opened.kind !== "initializing")
@@ -351,7 +402,7 @@ class ClientImpl {
             throw new KavachError("ACCOUNT_RECOVERY_REQUIRED", "recoveryCode");
         return encodeRecoveryCode(key);
     }
-    async restoreAccount(recoveryCode) {
+    async restoreAccountNow(recoveryCode) {
         const stage = "restoreAccount";
         const opened = await openStore(this.store, this.secrets, this.accountName);
         if (opened.kind === "ACTIVE" || opened.kind === "RETIRED")
@@ -528,7 +579,7 @@ class ClientImpl {
         this.emit({ kind: "stateChanged", state: await this.getState() });
     }
     // Sending ---------------------------------------------------------------------------------------
-    async enqueue(kind, payload, options = {}) {
+    async enqueueNow(kind, payload, options) {
         const deps = this.outboxDeps();
         // A key answered before anything that may need the network: the record it names is already
         // durable, so a retry offline, or with a rotation due, returns it. The outbox checks the key
@@ -658,20 +709,151 @@ class ClientImpl {
     async sync(options = {}) {
         if (this.syncing)
             return this.syncing;
-        this.syncing = this.runSync(options).finally(() => {
+        if (this.closed)
+            throw new KavachError("CLOSED", "sync", "the client is closed");
+        this.syncing = this.track("sync", () => this.runSync(options)).finally(() => {
             this.syncing = undefined;
         });
         return this.syncing;
     }
+    async drainNow(options) {
+        const maxRounds = Math.max(1, Math.floor(options.maxRounds ?? 10));
+        const maxMs = Math.max(0, Math.floor(options.maxMs ?? 30_000));
+        const deadline = this.now() + BigInt(maxMs);
+        const merged = {
+            metadata: { certificates: 0, snapshots: 0, rotations: 0, quarantined: 0, resets: 0, successions: 0 },
+            epoch: "unchanged",
+            outbox: { sent: 0, accepted: 0, cancelled: 0, unknown: 0, retry: 0 },
+            inbox: { streams: 0, stored: 0, keyPending: 0, invalid: 0, acked: 0, hasMore: false },
+            purged: 0,
+            maintenance: options.skipMaintenance ? "skipped" : "done",
+            timings: emptyTimings(),
+            errors: []
+        };
+        let rounds = 0;
+        let previousErrors;
+        let stop = "drained";
+        let last;
+        // An inbox this device could not fully read this round: discovery or a stream failed, or metadata it
+        // depends on did. Such a round never establishes that the inbox is empty.
+        const inboxUncertain = (r) => r.errors.some((e) => e.operation === "listSubscriptions" || e.operation === "inbox" || e.operation === "metadata");
+        // Chains verified only partly: remaining work, and their cursors moving is progress.
+        const chains = () => this.store.read((tx) => new Map(tx.list("chainProgress").filter(([, c]) => !c.complete).map(([k, c]) => [k, c.nextGeneration])));
+        let previousChains = await chains();
+        for (;;) {
+            if (this.closed) {
+                stop = "closed";
+                break;
+            }
+            // The time left is this round's reading budget too, so a round never starts work the deadline
+            // does not cover; a transport call already in flight ends on its own timeout.
+            const remainingMs = Number(deadline - this.now());
+            if (rounds > 0 && remainingMs <= 0) {
+                stop = "maxMs";
+                break;
+            }
+            const roundMs = Math.max(0, Math.min(remainingMs, options.catchUp?.maxMs ?? DEFAULT_CATCH_UP.maxMs));
+            const r = await this.sync({ catchUp: { maxMs: roundMs, ...(options.catchUp?.maxRecords !== undefined ? { maxRecords: options.catchUp.maxRecords } : {}) }, ...(options.skipMaintenance ? { skipMaintenance: true } : {}) });
+            rounds++;
+            last = r;
+            // The round's work counts whether or not it was the last: what it accepted, stored and failed
+            // is merged first, and only then is a close that landed meanwhile reported.
+            for (const k of Object.keys(merged.metadata))
+                merged.metadata[k] += r.metadata[k];
+            for (const k of Object.keys(merged.outbox))
+                merged.outbox[k] += r.outbox[k];
+            merged.inbox.streams += r.inbox.streams;
+            merged.inbox.stored += r.inbox.stored;
+            merged.inbox.keyPending += r.inbox.keyPending;
+            merged.inbox.invalid += r.inbox.invalid;
+            merged.inbox.acked += r.inbox.acked;
+            merged.purged += r.purged;
+            for (const k of Object.keys(merged.timings))
+                merged.timings[k] += r.timings[k];
+            merged.epoch = r.epoch;
+            merged.errors.push(...r.errors);
+            if (r.bootstrap)
+                merged.bootstrap = r.bootstrap;
+            if (this.closed) {
+                // The round may have stopped at a boundary before its inbox: nothing it reports is complete.
+                stop = "closed";
+                break;
+            }
+            if (r.errors.some((e) => e.code === "RATE_LIMITED")) {
+                // The host asked for a pause: no further round now; the wait goes back to the product.
+                stop = "rateLimited";
+                break;
+            }
+            const bootstrapIncomplete = (await this.inspect()).bootstrap?.complete === false;
+            const currentChains = await chains();
+            const more = r.inbox.hasMore || bootstrapIncomplete || currentChains.size > 0;
+            const status = (await this.getState()).status;
+            if (status === "replacementPrepared" || status === "accountRecoveryRequired") {
+                stop = "authentication";
+                break;
+            }
+            if (!more) {
+                stop = inboxUncertain(r) ? "incomplete" : "drained";
+                break;
+            }
+            const signature = r.errors.map((e) => `${e.operation}:${e.code}`).sort().join(",");
+            const chainsAdvanced = [...currentChains].some(([k, next]) => previousChains.get(k) !== next) || [...previousChains.keys()].some((k) => !currentChains.has(k));
+            previousChains = currentChains;
+            const changed = chainsAdvanced || r.inbox.stored + r.metadata.certificates + r.metadata.snapshots + r.metadata.successions + (r.bootstrap?.circles ?? 0) + (r.bootstrap?.pending ?? 0) > 0;
+            if (!changed && signature !== "" && signature === previousErrors) {
+                stop = r.errors.some((e) => e.code === "METADATA_REQUIRED" || e.code === "RESET_KEYS_REQUIRED" || e.code === "RESET_CLOCK_UNTRUSTED") ? "metadata" : "noProgress";
+                break;
+            }
+            previousErrors = signature;
+            if (rounds >= maxRounds) {
+                stop = "maxRounds";
+                break;
+            }
+            if (this.now() >= deadline) {
+                stop = "maxMs";
+                break;
+            }
+        }
+        merged.inbox.hasMore = last?.inbox.hasMore ?? false;
+        const bootstrapIncomplete = this.closed ? false : (await this.inspect()).bootstrap?.complete === false;
+        const chainsIncomplete = this.closed ? previousChains.size : (await chains()).size;
+        const waitingFor = this.closed ? 0 : (await this.getState()).waitingFor.length;
+        const inboxHasMore = !last || inboxUncertain(last) || stop === "closed" || stop === "rateLimited" ? "unknown" : merged.inbox.hasMore;
+        const waits = (last?.errors ?? []).flatMap((e) => (e.code === "RATE_LIMITED" && e.retryAfterMs !== undefined ? [e.retryAfterMs] : []));
+        const retryAfterMs = waits.length ? Math.max(...waits) : undefined;
+        return { ...merged, rounds, stoppedBecause: stop, remaining: { inboxHasMore, bootstrapIncomplete, chainsIncomplete, waitingFor, ...(retryAfterMs === undefined ? {} : { retryAfterMs }) } };
+    }
     async runSync(options) {
+        const started = wall();
         const report = {
             metadata: { certificates: 0, snapshots: 0, rotations: 0, quarantined: 0, resets: 0, successions: 0 },
             epoch: "unchanged",
             outbox: { sent: 0, accepted: 0, cancelled: 0, unknown: 0, retry: 0 },
             inbox: { streams: 0, stored: 0, keyPending: 0, invalid: 0, acked: 0, hasMore: false },
             purged: 0,
+            maintenance: options.skipMaintenance ? "skipped" : "done",
+            timings: emptyTimings(),
             errors: []
         };
+        const maintain = !options.skipMaintenance;
+        let mark = started;
+        const phase = (name) => {
+            const now = wall();
+            report.timings[name] += now - mark;
+            mark = now;
+        };
+        const finish = () => {
+            report.timings.total = wall() - started;
+            return report;
+        };
+        try {
+            return await this.runSyncPhases(options, report, maintain, phase);
+        }
+        finally {
+            finish();
+        }
+    }
+    async runSyncPhases(options, report, maintain, phase) {
         this.syncBudget = {
             remainingRecords: Math.max(1, Math.floor(options.catchUp?.maxRecords ?? DEFAULT_CATCH_UP.maxRecords)),
             deadline: this.now() + BigInt(Math.max(0, Math.floor(options.catchUp?.maxMs ?? DEFAULT_CATCH_UP.maxMs)))
@@ -691,6 +873,7 @@ class ClientImpl {
                 }
             }
         }
+        phase("resume");
         if (!this.account || !this.selfPin)
             return report;
         const meta = await this.store.read((tx) => tx.get("meta", META));
@@ -721,7 +904,10 @@ class ClientImpl {
         }
         else if (meta.state !== "ACTIVE")
             return report;
-        await this.ensureBackup();
+        phase("resume");
+        if (maintain)
+            await this.ensureBackup();
+        phase("maintenance");
         if (meta.bootstrap && !meta.bootstrap.complete) {
             try {
                 report.bootstrap = await this.bootstrap(report, meta.bootstrap);
@@ -730,20 +916,23 @@ class ClientImpl {
                 report.errors.push(syncError("bootstrap", e));
             }
         }
+        phase("bootstrap");
         try {
-            await this.syncMetadata(report);
+            await this.syncMetadata(report, maintain);
         }
         catch (e) {
             report.errors.push(syncError("metadata", e));
         }
+        phase("metadata");
         try {
             await this.pushPreferences(report);
         }
         catch (e) {
             report.errors.push(syncError("preference", e));
         }
+        phase("preferences");
         const after = await this.store.read((tx) => tx.get("meta", META));
-        if (after?.state === "RETIRED")
+        if (after?.state === "RETIRED" || this.closed)
             return report;
         try {
             report.epoch = await this.ensureEpoch();
@@ -751,12 +940,22 @@ class ClientImpl {
         catch (e) {
             report.errors.push(syncError("epoch", e));
         }
+        phase("epoch");
+        if (this.closed)
+            return report;
         try {
-            report.outbox = await drain(this.outboxDeps());
+            const drained = await drain(this.outboxDeps());
+            report.outbox = { sent: drained.sent, accepted: drained.accepted, cancelled: drained.cancelled, unknown: drained.unknown, retry: drained.retry };
+            report.timings.bytesSent += drained.bytes;
+            if (drained.blocked)
+                report.errors.push(syncError("outbox", drained.blocked)); // the records stay queued
         }
         catch (e) {
             report.errors.push(syncError("outbox", e));
         }
+        phase("outbox");
+        if (this.closed)
+            return report;
         let subs = [];
         try {
             subs = await this.transport.relay.listSubscriptions();
@@ -771,15 +970,23 @@ class ClientImpl {
         if (budget.remainingRecords < 1)
             budget.remainingRecords = 1; // every stream reads at least one page
         for (const s of subs) {
+            if (this.closed)
+                return report;
             try {
                 const known = await this.store.read((tx) => tx.list("certificates").some(([, c]) => c.streamId === toHex(s.streamId)));
                 if (!known)
                     continue;
                 const r = await syncStream(this.inboxDeps(), s.streamId, s.authorIdentityId, budget);
-                report.inbox.streams++;
+                // What landed counts, whether or not the stream then failed; a failed stream is not synced.
                 report.inbox.stored += r.stored;
                 report.inbox.keyPending += r.keyPending;
                 report.inbox.invalid += r.invalid;
+                report.timings.bytesReceived += r.bytes;
+                if (r.failure !== undefined) {
+                    report.errors.push({ ...syncError("inbox", r.failure), streamId: s.streamId, authorIdentityId: s.authorIdentityId });
+                    continue;
+                }
+                report.inbox.streams++;
                 if (r.acked !== undefined)
                     report.inbox.acked++;
                 if (r.hasMore)
@@ -789,11 +996,14 @@ class ClientImpl {
                 report.errors.push({ ...syncError("inbox", e), streamId: s.streamId, authorIdentityId: s.authorIdentityId });
             }
         }
-        report.purged = (await purgeHistory(this.store, this.policy, this.now())) + (await purgeOutbox(this.store, this.policy, this.now()));
+        phase("inbox");
+        if (maintain)
+            report.purged = (await purgeHistory(this.store, this.policy, this.now())) + (await purgeOutbox(this.store, this.policy, this.now()));
+        phase("maintenance");
         await this.emitState();
         return report;
     }
-    async syncMetadata(report) {
+    async syncMetadata(report, maintain = true) {
         const { pin } = this.requireAccount("sync");
         // Own account: has this device been superseded?
         const [me] = await this.transport.directory.resolveAccounts([this.accountName]);
@@ -816,9 +1026,9 @@ class ClientImpl {
                 return;
             }
         }
-        // Reset-key list when due.
+        // Reset-key list when due: always when stale (verification needs it), periodically unless maintenance is skipped.
         const now = this.now();
-        const due = !this.trust.fresh(now) || now - this.trust.state.timeHighWater >= RESET_LIST_RECHECK_MS;
+        const due = !this.trust.fresh(now) || (maintain && now - this.trust.state.timeHighWater >= RESET_LIST_RECHECK_MS);
         if (due) {
             const wire = await this.transport.directory.getResetKeyList();
             if (wire) {
@@ -1383,9 +1593,6 @@ class ClientImpl {
         await this.emitState();
     }
     // Receiving and reads ---------------------------------------------------------------------------
-    receive(wire) {
-        return receiveRecord(this.inboxDeps(), wire);
-    }
     history(query) {
         return history(this.store, this.policy, query);
     }
@@ -1578,7 +1785,7 @@ class ClientImpl {
         const [resolved] = await this.transport.directory.resolveAccounts([accountName]);
         if (!resolved)
             throw new KavachError("METADATA_REQUIRED", "approve", "unknown account");
-        const report = { metadata: { certificates: 0, snapshots: 0, rotations: 0, quarantined: 0, resets: 0, successions: 0 }, epoch: "unchanged", outbox: { sent: 0, accepted: 0, cancelled: 0, unknown: 0, retry: 0 }, inbox: { streams: 0, stored: 0, keyPending: 0, invalid: 0, acked: 0, hasMore: false }, purged: 0, errors: [] };
+        const report = { metadata: { certificates: 0, snapshots: 0, rotations: 0, quarantined: 0, resets: 0, successions: 0 }, epoch: "unchanged", outbox: { sent: 0, accepted: 0, cancelled: 0, unknown: 0, retry: 0 }, inbox: { streams: 0, stored: 0, keyPending: 0, invalid: 0, acked: 0, hasMore: false }, purged: 0, maintenance: "done", timings: emptyTimings(), errors: [] };
         await this.acceptMemberCertificate(resolved, report);
         const requester = resolvedAccountId(resolved);
         const pinned = await this.pinFor(requester);
@@ -1760,7 +1967,7 @@ class ClientImpl {
         await this.changeMembership(circleId, { close: true });
     }
     // Account recovery (amendment A1) ---------------------------------------------------------------
-    async prepareReplacement() {
+    async prepareReplacementNow() {
         const stage = "prepareReplacement";
         if (!acceptsSuccession(this.policy))
             throw new KavachError("NOT_AUTHORIZED", stage, "this deployment does not use account recovery");
@@ -1808,7 +2015,7 @@ class ClientImpl {
         await this.emitState();
         return proposalOf(row);
     }
-    async completeReplacement(input) {
+    async completeReplacementNow(input) {
         const stage = "completeReplacement";
         // Already activated (by an earlier call, or by a sync that found the commit on the chain): idempotent.
         if (this.selfPin && this.account && !this.retired)
@@ -2088,7 +2295,7 @@ class ClientImpl {
         return state.status === "requested" ? "pending" : "member";
     }
     // Reset -----------------------------------------------------------------------------------------
-    async resetAccount(options) {
+    async resetAccountNow(options) {
         const stage = "resetAccount";
         if (!options.confirmed)
             throw new KavachError("NOT_AUTHORIZED", stage, "reset requires confirmation");
@@ -2177,7 +2384,55 @@ class ClientImpl {
         await this.finishReset("load", row, roots);
     }
     async close() {
+        this.closed = true;
+        // Everything in flight finishes its current transaction; a sync stops at its next boundary.
+        while (this.running.size > 0)
+            await Promise.allSettled([...this.running]);
         this.listeners.clear();
     }
+    // The replacement helper ------------------------------------------------------------------------
+    async replaceDeviceNow(options) {
+        const maxAttempts = Math.max(1, Math.floor(options.maxAttempts ?? 3));
+        const activated = () => (this.selfPin && this.account && !this.retired ? { status: "activated", identityId: this.selfPin.identityId, generation: this.selfPin.generation } : undefined);
+        const done = activated();
+        if (done)
+            return done;
+        // A proposal left by an earlier run may have committed: the chain settles it before anything else.
+        const existing = await this.store.read((tx) => tx.get("replacement", "pending"));
+        if (existing && !existing.stale) {
+            await this.sync();
+            const settled = activated();
+            if (settled)
+                return settled;
+        }
+        const proposal = await this.prepareReplacementNow();
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const authorization = await options.authorize(proposal);
+            if (authorization === "reauthenticate")
+                return { status: "reauthenticate", proposal };
+            for (;;) {
+                try {
+                    const r = await this.completeReplacementNow({ successionId: proposal.successionId, authorization });
+                    return { status: "activated", identityId: r.identityId, generation: r.generation };
+                }
+                catch (e) {
+                    if (isKavachError(e, "SUCCESSION_PENDING")) {
+                        // The same call again with the same bytes; the host answers a committed id first.
+                        if (++attempt >= maxAttempts)
+                            return { status: "pending", proposal };
+                        continue;
+                    }
+                    if (isKavachError(e, "AUTHORIZATION_REQUIRED"))
+                        break; // a fresh token for the same proposal
+                    if (isKavachError(e, "REPLACEMENT_CONFLICT")) {
+                        const conflict = (await this.inspect()).replacement;
+                        return { status: "conflict", currentGeneration: conflict?.conflictGeneration };
+                    }
+                    throw e;
+                }
+            }
+        }
+        return { status: "pending", proposal };
+    }
 }
 //# sourceMappingURL=client.js.map