@astrosheep/square 0.4.4 → 0.4.6

package/dist/delivery-ledger-sqlite.js

@@ -22,7 +22,7 @@ export const { DatabaseSync } = await (process.versions.bun
         },
     }))
     : import('node:sqlite'));
-import { inSqliteTransaction } from './sqlite-transaction.js';
+import { inSqliteTransaction, retrySqliteBusy, awaitSqliteQueue } from './sqlite-transaction.js';
 import { validateSchema } from './sqlite-framing.js';
 const FORMAT = 3;
 const APPLICATION_ID = 0x444c4752;
@@ -70,12 +70,16 @@ export class LedgerStore {
     clock;
     pending = Promise.resolve();
     closed = false;
+    cancellation = new AbortController();
+    ordinaryCancellation = new AbortController();
+    closing;
     constructor(location, db, clock) {
         this.location = location;
         this.db = db;
         this.clock = clock;
     }
-    static async open(location, clock) {
+    static async open(location, clock, signal) {
+        signal?.throwIfAborted();
         try {
             await fs.access(location);
         }
@@ -87,14 +91,15 @@ export class LedgerStore {
             let initial;
             try {
                 await (await fs.open(temporary, 'wx', 0o600)).close();
-                initial = new DatabaseSync(temporary);
+                initial = await retrySqliteBusy(() => new DatabaseSync(temporary), signal);
                 await inSqliteTransaction(initial, true, () => undefined, () => {
                     initial.exec(SCHEMA);
                     initial.prepare('INSERT INTO meta VALUES(?,1)').run(FORMAT);
                     initial.exec(`PRAGMA application_id=${APPLICATION_ID}; PRAGMA user_version=${FORMAT}`);
-                });
+                }, signal);
                 initial.close();
                 initial = undefined;
+                signal?.throwIfAborted();
                 try {
                     await fs.link(temporary, location);
                 }
@@ -109,16 +114,16 @@ export class LedgerStore {
             }
         }
         // Existing formats are inspected on a read-only connection before any writable open.
-        const probe = new DatabaseSync(location, { readOnly: true });
+        const probe = await retrySqliteBusy(() => new DatabaseSync(location, { readOnly: true }), signal);
         try {
-            validate(probe, location);
+            await retrySqliteBusy(() => validate(probe, location), signal);
         }
         finally {
             probe.close();
         }
-        const db = new DatabaseSync(location);
+        const db = await retrySqliteBusy(() => new DatabaseSync(location), signal);
         try {
-            validate(db, location);
+            await retrySqliteBusy(() => { validate(db, location); db.exec('PRAGMA busy_timeout=0; PRAGMA synchronous=FULL'); }, signal);
             return new LedgerStore(location, db, clock);
         }
         catch (error) {
@@ -126,27 +131,37 @@ export class LedgerStore {
             throw error;
         }
     }
+    /** Stop ordinary work while captured effects retain access to settlement. */
+    retire() { this.ordinaryCancellation.abort(new Error('Delivery ledger is closed')); }
     close() {
+        this.retire();
         this.closed = true;
-        return this.pending.then(() => this.db.close());
+        this.cancellation.abort(new Error('Delivery ledger is closed'));
+        return this.closing ??= this.pending.then(() => this.db.close());
     }
-    transaction(write, change, signal) {
-        if (this.closed)
+    transaction(write, change, signal, settlement = false) {
+        if (this.closed || !settlement && this.ordinaryCancellation.signal.aborted)
             return Promise.reject(new Error('Delivery ledger is closed'));
-        const result = this.pending.then(() => inSqliteTransaction(this.db, write, () => validate(this.db, this.location), () => {
-            const now = this.clock();
-            if (!Number.isFinite(now))
-                throw new TypeError('Expected finite ledger time');
-            const changes = Number(this.db.prepare('SELECT total_changes() AS n').get().n);
-            const result = change(now);
-            if (write && Number(this.db.prepare('SELECT total_changes() AS n').get().n) > changes) {
-                this.normalize(now);
-                this.gc(now);
-            }
-            return result;
-        }, signal));
+        signal = AbortSignal.any([this.cancellation.signal, ...(!settlement ? [this.ordinaryCancellation.signal] : []), ...(signal ? [signal] : [])]);
+        let started = false;
+        const result = this.pending.then(() => {
+            signal.throwIfAborted();
+            started = true;
+            return inSqliteTransaction(this.db, write, () => validate(this.db, this.location), () => {
+                const now = this.clock();
+                if (!Number.isFinite(now))
+                    throw new TypeError('Expected finite ledger time');
+                const changes = Number(this.db.prepare('SELECT total_changes() AS n').get().n);
+                const result = change(now);
+                if (write && Number(this.db.prepare('SELECT total_changes() AS n').get().n) > changes) {
+                    this.normalize(now);
+                    this.gc(now);
+                }
+                return result;
+            }, signal);
+        });
         this.pending = result.catch(() => undefined);
-        return result;
+        return awaitSqliteQueue(result, signal, () => started);
     }
     getSession(owner) {
         return session(this.db.prepare('SELECT * FROM sessions WHERE owner=?').get(owner));
@@ -215,19 +230,19 @@ export class LedgerStore {
             this.deleteCard(row.seq, now);
         this.db.prepare('DELETE FROM receipts WHERE rowid IN (SELECT rowid FROM receipts WHERE at<? ORDER BY at LIMIT 100)').run(cutoff);
     }
-    session(owner) { return this.transaction(false, () => this.getSession(owner)); }
-    sessions() {
-        return this.transaction(false, () => this.db.prepare('SELECT * FROM sessions ORDER BY owner').all().map(row => session(row)));
+    session(owner, signal) { return this.transaction(false, () => this.getSession(owner), signal); }
+    sessions(signal) {
+        return this.transaction(false, () => this.db.prepare('SELECT * FROM sessions ORDER BY owner').all().map(row => session(row)), signal);
     }
-    pendingCards(owner, generation) {
+    pendingCards(owner, generation, signal) {
         return this.transaction(false, now => this.attached(owner, generation)
-            ? this.db.prepare('SELECT * FROM cards WHERE owner=? ORDER BY seq').all(owner).filter(row => this.eligible(row, now)).map(card) : []);
+            ? this.db.prepare('SELECT * FROM cards WHERE owner=? ORDER BY seq').all(owner).filter(row => this.eligible(row, now)).map(card) : [], signal);
     }
-    handoffs(owner, generation) {
+    handoffs(owner, generation, signal) {
         return this.transaction(false, () => this.db.prepare(`SELECT a.* FROM attempts a JOIN cards c ON c.seq=a.seq
-      WHERE c.owner=? AND a.generation=? AND a.track='handoff' ORDER BY a.rowid`).all(owner, generation).map(attempt));
+      WHERE c.owner=? AND a.generation=? AND a.track='handoff' ORDER BY a.rowid`).all(owner, generation).map(attempt), signal);
     }
-    attach(input) {
+    attach(input, signal) {
         const encoded = JSON.stringify(input.routes);
         return this.transaction(true, now => {
             const previous = this.getSession(input.owner);
@@ -237,27 +252,27 @@ export class LedgerStore {
             this.db.prepare(`INSERT INTO sessions VALUES(?,?,'attached',?,?) ON CONFLICT(owner)
         DO UPDATE SET generation=excluded.generation,state=excluded.state,routes_json=excluded.routes_json,at=excluded.at`).run(input.owner, generation, encoded, now);
             return this.getSession(input.owner);
-        });
+        }, signal);
     }
-    updateRoutes(input) {
+    updateRoutes(input, signal) {
         const encoded = JSON.stringify(input.routes);
         return this.transaction(true, now => {
             if (!this.attached(input.owner, input.generation))
                 return false;
             this.db.prepare('UPDATE sessions SET routes_json=?,at=? WHERE owner=?').run(encoded, now, input.owner);
             return true;
-        });
+        }, signal);
     }
-    lifecycle(input, state) {
+    lifecycle(input, state, signal) {
         return this.transaction(true, now => {
             const s = this.getSession(input.owner);
             if (!s || s.generation !== input.generation || s.state === 'deleted')
                 return false;
             this.db.prepare('UPDATE sessions SET state=?,at=? WHERE owner=?').run(state, now, input.owner);
             return true;
-        });
+        }, signal);
     }
-    post(input) {
+    post(input, signal) {
         return this.transaction(true, now => {
             const s = this.getSession(input.owner);
             if (!s)
@@ -279,9 +294,9 @@ export class LedgerStore {
             this.db.prepare('UPDATE meta SET next_seq=?').run(seq + 1);
             this.db.prepare('INSERT INTO cards VALUES(?,?,?,?,?,?)').run(seq, input.owner, input.key, input.text, input.details, now);
             return { status: suppressed ? 'suppressed' : 'posted' };
-        });
+        }, signal);
     }
-    suppress(input) {
+    suppress(input, signal) {
         return this.transaction(true, now => {
             const permanentId = input.scope === 'exact' && input.expiresAt === undefined
                 ? this.db.prepare("SELECT id FROM suppressions WHERE owner=? AND key=? AND scope='exact' AND expires_at IS NULL").get(input.owner, input.key)?.id
@@ -298,22 +313,22 @@ export class LedgerStore {
                         this.deleteCard(row.seq);
                 }
             return { id, status: inCustody ? 'in-custody' : 'suppressed' };
-        });
+        }, signal);
     }
-    renewSuppression(input) {
-        return this.transaction(true, now => this.db.prepare('UPDATE suppressions SET expires_at=? WHERE owner=? AND id=? AND (expires_at IS NULL OR expires_at>?)').run(input.expiresAt, input.owner, input.id, now).changes > 0);
+    renewSuppression(input, signal) {
+        return this.transaction(true, now => this.db.prepare('UPDATE suppressions SET expires_at=? WHERE owner=? AND id=? AND (expires_at IS NULL OR expires_at>?)').run(input.expiresAt, input.owner, input.id, now).changes > 0, signal);
     }
-    releaseSuppression(input) {
-        return this.transaction(true, () => this.db.prepare('DELETE FROM suppressions WHERE owner=? AND id=?').run(input.owner, input.id).changes > 0);
+    releaseSuppression(input, signal) {
+        return this.transaction(true, () => this.db.prepare('DELETE FROM suppressions WHERE owner=? AND id=?').run(input.owner, input.id).changes > 0, signal);
     }
-    cancel(input) {
+    cancel(input, signal) {
         return this.transaction(true, () => {
             if (!this.attached(input.owner, input.generation))
                 return false;
             this.db.prepare(`INSERT INTO cancellations VALUES(?,?,(SELECT next_seq-1 FROM meta))
         ON CONFLICT(owner) DO UPDATE SET generation=excluded.generation,through_seq=MAX(through_seq,excluded.through_seq)`).run(input.owner, input.generation);
             return true;
-        });
+        }, signal);
     }
     isSuppressed(owner, key, now) {
         return !!this.db.prepare(`SELECT 1 FROM suppressions WHERE owner=? AND (expires_at IS NULL OR expires_at>?)
@@ -413,7 +428,7 @@ export class LedgerStore {
         this.receipt(handoff.seq, now);
         return true;
     }
-    settle(tokens, outcome) {
+    settle(tokens, outcome, signal) {
         return this.transaction(true, now => {
             const attempts = tokens.map(token => this.getAttempt(token));
             if (attempts.some(a => !a || a.track === 'presentation' && outcome === 'accepted'
@@ -440,7 +455,7 @@ export class LedgerStore {
                 }
             }
             return true;
-        });
+        }, signal, true);
     }
     handoffFacts(token) {
         const a = this.getAttempt(token);
@@ -463,16 +478,16 @@ export class LedgerStore {
         const s = this.attached(facts.ref.owner, facts.ref.generation);
         return facts.attempt.expiresAt > now && !!s && s.routes.some(route => route.kind === facts.ref.routeKind) && this.eligible(facts.row, now);
     }
-    handoff(token) {
-        return this.transaction(false, () => this.handoffFacts(token)?.ref);
+    handoff(token, signal) {
+        return this.transaction(false, () => this.handoffFacts(token)?.ref, signal);
     }
-    guardHandoff(ref) {
+    guardHandoff(ref, signal) {
         return this.transaction(false, now => {
             const facts = this.matchingHandoff(ref);
             return !!facts && ['dispatching', 'unknown'].includes(facts.attempt.outcome) && this.currentHandoff(facts, now);
-        });
+        }, signal);
     }
-    acceptHandoff(ref) {
+    acceptHandoff(ref, signal) {
         return this.transaction(true, now => {
             const a = this.matchingHandoff(ref)?.attempt;
             if (!a || !['dispatching', 'unknown', 'accepted'].includes(a.outcome))
@@ -480,9 +495,9 @@ export class LedgerStore {
             if (a.outcome !== 'accepted')
                 this.db.prepare("UPDATE attempts SET outcome='accepted',settled_at=? WHERE token=?").run(now, a.token);
             return true;
-        });
+        }, signal);
     }
-    observePresentation(handoff, options) {
+    observePresentation(handoff, options, signal) {
         return this.transaction(true, now => {
             const facts = typeof handoff === 'string' ? undefined : this.matchingHandoff(handoff);
             if (options?.requireCurrent) {
@@ -494,14 +509,14 @@ export class LedgerStore {
             }
             const a = typeof handoff === 'string' ? this.getAttempt(handoff) : facts?.attempt;
             return a ? this.confirm(a, now) : false;
-        });
+        }, signal);
     }
-    receipts(owner, options) {
+    receipts(owner, options, signal) {
         return this.transaction(false, () => this.db.prepare('SELECT * FROM receipts WHERE owner=? AND at>=? ORDER BY at,key').all(owner, options.since ?? -Number.MAX_VALUE)
             .filter(row => options.keys === undefined || options.keys.includes(row.key))
-            .map(row => ({ owner: row.owner, key: row.key, at: row.at })));
+            .map(row => ({ owner: row.owner, key: row.key, at: row.at })), signal);
     }
-    health(owner) {
+    health(owner, signal) {
         return this.transaction(false, now => {
             const all = this.db.prepare('SELECT a.* FROM attempts a JOIN cards c ON c.seq=a.seq WHERE (? IS NULL OR c.owner=?) ORDER BY a.started_at,a.token').all(owner ?? null, owner ?? null).map(attempt);
             const repeatedFailures = this.db.prepare(`SELECT c.owner,c.key,COUNT(*) AS count FROM attempts a JOIN cards c ON c.seq=a.seq
@@ -511,6 +526,6 @@ export class LedgerStore {
             return { unknownAttempts: all.filter(a => a.outcome === 'unknown' || a.outcome === 'dispatching' && a.expiresAt <= now)
                     .map(a => a.outcome === 'dispatching' ? { ...a, outcome: 'unknown' } : a), repeatedFailures,
                 sessionsWithoutRoute: sessions.filter(s => s.routes.length === 0).map(s => s.owner) };
-        });
+        }, signal);
     }
 }

package/dist/delivery-ledger.d.ts

@@ -109,83 +109,88 @@ export declare function deliveryLedgerLocation(env?: NodeJS.ProcessEnv, homeDir?
 export declare class DeliveryLedger {
     private readonly store;
     private readonly leaseMs;
+    private readonly settlements;
+    private retired;
     private constructor();
     static open(options?: {
         readonly location?: string;
         readonly clock?: () => number;
         readonly leaseMs?: number;
+        readonly signal?: AbortSignal;
     }): Promise<DeliveryLedger>;
     close(): Promise<void>;
+    private retainSettlement;
+    private diagnose;
     attach(input: {
         readonly owner: Owner;
         readonly expectedGeneration: string | null;
         readonly routes: readonly DeliveryRoute[];
-    }): Promise<DeliverySession | false>;
+    }, signal?: AbortSignal): Promise<DeliverySession | false>;
     updateRoutes(input: {
         readonly owner: Owner;
         readonly generation: string;
         readonly routes: readonly DeliveryRoute[];
-    }): Promise<boolean>;
+    }, signal?: AbortSignal): Promise<boolean>;
     detach(input: {
         readonly owner: Owner;
         readonly generation: string;
-    }): Promise<boolean>;
+    }, signal?: AbortSignal): Promise<boolean>;
     markDeleted(input: {
         readonly owner: Owner;
         readonly generation: string;
-    }): Promise<boolean>;
+    }, signal?: AbortSignal): Promise<boolean>;
     private lifecycle;
-    session(owner: Owner): Promise<DeliverySession | undefined>;
-    sessions(): Promise<readonly DeliverySession[]>;
+    session(owner: Owner, signal?: AbortSignal): Promise<DeliverySession | undefined>;
+    sessions(signal?: AbortSignal): Promise<readonly DeliverySession[]>;
     pending(owner: Owner, options: {
         readonly generation: string;
-    }): Promise<readonly DeliveryCard[]>;
+    }, signal?: AbortSignal): Promise<readonly DeliveryCard[]>;
     handoffs(owner: Owner, options: {
         readonly generation: string;
-    }): Promise<readonly DeliveryAttempt[]>;
+    }, signal?: AbortSignal): Promise<readonly DeliveryAttempt[]>;
     post(input: {
         readonly owner: Owner;
         readonly key: string;
         readonly text: string;
         readonly details?: Readonly<Record<string, unknown>>;
-    }): Promise<PostResult>;
+    }, signal?: AbortSignal): Promise<PostResult>;
     suppress(input: {
         readonly owner: Owner;
         readonly key: string;
         readonly scope: 'exact' | 'prefix';
         readonly expiresAt?: number;
-    }): Promise<SuppressionResult>;
+    }, signal?: AbortSignal): Promise<SuppressionResult>;
     renewSuppression(input: {
         readonly owner: Owner;
         readonly id: string;
         readonly expiresAt: number;
-    }): Promise<boolean>;
+    }, signal?: AbortSignal): Promise<boolean>;
     releaseSuppression(input: {
         readonly owner: Owner;
         readonly id: string;
-    }): Promise<boolean>;
+    }, signal?: AbortSignal): Promise<boolean>;
     cancel(input: {
         readonly owner: Owner;
         readonly generation: string;
-    }): Promise<boolean>;
+    }, signal?: AbortSignal): Promise<boolean>;
     receipts(owner: Owner, options?: {
         readonly keys?: readonly string[];
         readonly since?: number;
-    }): Promise<readonly DeliveryReceipt[]>;
+    }, signal?: AbortSignal): Promise<readonly DeliveryReceipt[]>;
     claimPresentation(owner: Owner, options: {
         readonly generation: string;
         readonly budgetChars: number;
         readonly signal?: AbortSignal;
     }): Promise<PresentationClaim | undefined>;
     /** Resolve the original prepared handoff, including its stored route kind. */
-    handoff(token: string): Promise<DeliveryHandoffRef | undefined>;
-    guardHandoff(ref: DeliveryHandoffRef): Promise<boolean>;
-    acceptHandoff(ref: DeliveryHandoffRef): Promise<boolean>;
+    handoff(token: string, signal?: AbortSignal): Promise<DeliveryHandoffRef | undefined>;
+    guardHandoff(ref: DeliveryHandoffRef, signal?: AbortSignal): Promise<boolean>;
+    acceptHandoff(ref: DeliveryHandoffRef, signal?: AbortSignal): Promise<boolean>;
     /** Confirms the exact existing external effect; never sends or returns text. */
     observePresentation(handoff: string | DeliveryHandoffRef, options?: {
         readonly requireCurrent?: boolean;
-    }): Promise<boolean>;
-    health(owner?: Owner): Promise<DeliveryHealth>;
+    }, signal?: AbortSignal): Promise<boolean>;
+    health(owner?: Owner, signal?: AbortSignal): Promise<DeliveryHealth>;
     /** Subscribe first; read the returned version, inspect state, then await changed(version,...). */
     observe(owner: Owner): Promise<VersionObserver<string>>;
     dispatchHandoff(owner: Owner, key: string, transport: DeliveryTransport, options: {