@openlfcp/client 0.2.0 → 0.2.2

package/dist/invite.d.ts

@@ -77,7 +77,9 @@ export interface CreatedInvitation {
 /**
  * The inviter's side (§18, §73). The grant must validate on the stored
  * chain and the package must pass §25.2 at the grant's head, both checked
- * before anything is queued; the grant is queued before the package.
+ * before anything is queued, and so is the link. The grant and the package
+ * are queued in one atomic commit, the grant first: a refused or failed
+ * commit queues neither, and a retry starts afresh.
  * Share the link once both are ACKed: until then the grant is not on the
  * coordinator's chain.
  */

package/dist/invite.js

@@ -4,7 +4,7 @@ import { dekSecretRef } from "@openlfcp/storage";
 import { ABILITY, assembleInviteUri, createMessage, ERROR_CODE, invitationPrincipal, isGrantActive, parseControlRecord, parseInviteUri, parseKeyPackage, receiveKeyPackage, sealKeyPackage, signControlRecord, validateControlChain, verifyInvitationSecret, verifyKeyPackage, } from "@openlfcp/wire";
 import { clearClaimJournal, journaledDeks, readClaimJournal, writeClaimJournal, } from "./claim-journal.js";
 import { LfcpConnection } from "./connection.js";
-import { queueControlRecord, queueKeyPackage } from "./queue.js";
+import { controlRecordWrites, keyPackageWrites } from "./queue.js";
 import { loadControlChain, localControlChain, saveControlChain } from "./storage.js";
 /**
  * Link invitations and the one-time capability claim (LFCP-WIRE-01 §18,
@@ -94,7 +94,9 @@ function resolveInvitationGrant(state, linkGrantId, secret) {
 /**
  * The inviter's side (§18, §73). The grant must validate on the stored
  * chain and the package must pass §25.2 at the grant's head, both checked
- * before anything is queued; the grant is queued before the package.
+ * before anything is queued, and so is the link. The grant and the package
+ * are queued in one atomic commit, the grant first: a refused or failed
+ * commit queues neither, and a retry starts afresh.
  * Share the link once both are ACKed: until then the grant is not on the
  * coordinator's chain.
  */
@@ -141,16 +143,27 @@ export async function createInvitation(options) {
     const check = verifyKeyPackage(next, parseKeyPackage(sealed.bytes));
     if (check.kind !== "authorized")
         fail("AUTHORIZATION_FAILED", `the invitation Key Package is refused: ${check.message}`);
-    await queueControlRecord(options.storage, grant.bytes);
-    const keyPackageId = await queueKeyPackage(options.storage, sealed.bytes);
+    // The link is built (and its endpoints checked) before storage changes, so
+    // a refused link leaves nothing queued; then the grant and its Key Package
+    // go into ONE commit, grant first, so either both are queued, in sending
+    // order, or neither is (no grant without its package).
     const uri = assembleInviteUri({
         resourceId: R,
         endpoints: options.endpoints,
         grantId: grant.recordId,
         secret,
     });
+    const link = new InvitationLink(uri);
+    const keyPackageId = hash32(parseKeyPackage(sealed.bytes).signed.id);
+    const r = await options.storage.commit([
+        ...controlRecordWrites(grant.bytes),
+        ...keyPackageWrites(sealed.bytes),
+    ]);
+    // The same refusal as the queue helpers (queue.ts): a plain Error.
+    if (!r.ok)
+        throw new Error(`the object was not queued: ${r.reason}`);
     return Object.freeze({
-        link: new InvitationLink(uri),
+        link,
         grantId: grant.recordId,
         invitationPrincipal: invitee,
         keyPackageId,

package/dist/sync-client.d.ts

@@ -100,7 +100,7 @@ export interface StagedOperation<T> {
     writes(units: readonly {
         readonly unitId: DataUnitId;
     }[]): readonly StorageWrite[];
-    /** Called once the commit is durable, with the units in order. */
+    /** Called once the commit is durable, with the units in order; revert() is never called after it. */
     committed(unitIds: readonly DataUnitId[]): void;
 }
 /** How a Resource's Data Profile commits local batches (§3.1). */
@@ -375,7 +375,10 @@ export declare class SyncClient {
      * SDK-SECTIONS-INTEGRATION-01 §3.1: commits a batch of intents on an open
      * Resource and returns its receipt once the batch is durable: its Data
      * Units, outbound entries, the profile checkpoint and the receipt are
-     * stored in one transaction, then the batch is sent. An operation that
+     * stored in one transaction, then the batch is sent. Once it is stored
+     * the batch stands: a send that fails leaves it queued for the next
+     * connection, and a throwing listener is reported as an error event;
+     * neither reverts it or fails the commit (LFCP-03-034). An operation that
      * has a receipt returns it for the same intents and writes nothing, and
      * throws OperationIdReusedError for different ones (§3.3). Runs between
      * received units, never during their merge.

package/dist/sync-client.js

@@ -103,6 +103,8 @@ export class SyncClient {
     #sentAt = new Map();
     #requestTimeoutMs;
     #listeners = new Set();
+    /** #emit is reporting a listener's failure: a failure in that report is dropped. */
+    #reportingListenerError = false;
     /** Re-proposal attempts per Control Record (item ID hex), bounded; cleared on ACK (repropose.ts). */
     #reproposeAttempts = new Map();
     #antiEntropyMs;
@@ -145,9 +147,42 @@ export class SyncClient {
         this.#listeners.add(listener);
         return () => this.#listeners.delete(listener);
     }
+    /**
+     * LFCP-03-034: every listener gets the event, and a listener that throws
+     * never interrupts the SDK's own work (a commit, an ACK, received units,
+     * a loaded Snapshot): its failure is reported as an INTERNAL error event,
+     * and a failure while reporting one is dropped (no recursion). An engine
+     * trap is the exception and is thrown on, as before: reached from message
+     * handling (#serial) it stops the session; a call such as commit,
+     * publishSnapshot or revokeAccess rejects with it, and the session is not
+     * stopped.
+     */
     #emit(event) {
+        let failed;
+        let trap;
         for (const l of this.#listeners)
-            l(event);
+            try {
+                l(event);
+            }
+            catch (error) {
+                if (isEngineTrap(error))
+                    trap ??= { error };
+                else
+                    failed ??= { error };
+            }
+        if (trap !== undefined)
+            throw trap.error;
+        if (failed === undefined || this.#reportingListenerError)
+            return;
+        this.#reportingListenerError = true;
+        try {
+            const e = failed.error;
+            const resourceId = "resourceId" in event ? event.resourceId : undefined;
+            this.#error("INTERNAL", `a listener of a ${event.type} event failed: ${e instanceof Error ? e.message : String(e)}`, resourceId);
+        }
+        finally {
+            this.#reportingListenerError = false;
+        }
     }
     // -------------------------------------------------------------------------
     // Status (SDK-SECTIONS-INTEGRATION-01 §4, §5; LFCP-02-026)
@@ -1398,8 +1433,9 @@ export class SyncClient {
         ]);
         if (!r.ok)
             throw new Error(`the revocation was not queued: ${r.reason}`);
-        await this.#refreshAccess(ctx);
-        await this.#flush(ctx);
+        // Queued: the revocation stands whatever the report or the send does.
+        await this.#afterStored(resource, () => this.#refreshAccess(ctx));
+        await this.#afterStored(resource, () => this.#flush(ctx));
         return Object.freeze({
             kind: "queued",
             revoked: plan.revoked,
@@ -1414,7 +1450,10 @@ export class SyncClient {
      * SDK-SECTIONS-INTEGRATION-01 §3.1: commits a batch of intents on an open
      * Resource and returns its receipt once the batch is durable: its Data
      * Units, outbound entries, the profile checkpoint and the receipt are
-     * stored in one transaction, then the batch is sent. An operation that
+     * stored in one transaction, then the batch is sent. Once it is stored
+     * the batch stands: a send that fails leaves it queued for the next
+     * connection, and a throwing listener is reported as an error event;
+     * neither reverts it or fails the commit (LFCP-03-034). An operation that
      * has a receipt returns it for the same intents and writes nothing, and
      * throws OperationIdReusedError for different ones (§3.3). Runs between
      * received units, never during their merge.
@@ -1552,8 +1591,9 @@ export class SyncClient {
         await this.#guardCreate(ctx, view, intents);
         const staged = binding.stage(intents);
         staged?.apply();
+        let stored;
         try {
-            const { receipt, committed } = await commitOperation(storage, {
+            stored = await commitOperation(storage, {
                 view,
                 controlHead: view.state.head,
                 actor: this.#o.signer,
@@ -1565,23 +1605,51 @@ export class SyncClient {
                 affectedNodeIds: staged?.affectedNodeIds ?? [],
                 modelRevision: staged?.modelRevision ?? "",
             }, (units) => staged?.writes(units) ?? []);
-            if (!committed)
-                staged?.revert();
-            else
-                staged?.committed(receipt.unitIds);
-            if (committed) {
-                // Our own units grow the history a Snapshot covers, as received ones do.
-                ctx.unitsSinceSnapshot += receipt.unitIds.length;
-                await this.#reportBatches(R, [receipt.operationId]);
-                this.#refreshSection(ctx);
-            }
-            await this.#flush(ctx);
-            return receipt;
         }
         catch (e) {
+            // Not stored: the batch did not happen.
             staged?.revert();
             throw e;
         }
+        const { receipt, committed } = stored;
+        // The operation had a receipt already (a concurrent commit of it): this
+        // staging did not happen.
+        if (!committed)
+            staged?.revert();
+        // LFCP-03-034: from here the batch is durable and will be sent; nothing
+        // below may undo it in the profile state or fail the commit. A failed
+        // step is reported, and a failed send means the queue sends it later.
+        else {
+            await this.#afterStored(R, () => staged?.committed(receipt.unitIds));
+            // Our own units grow the history a Snapshot covers, as received ones do.
+            ctx.unitsSinceSnapshot += receipt.unitIds.length;
+            await this.#afterStored(R, () => this.#reportBatches(R, [receipt.operationId]));
+            await this.#afterStored(R, () => this.#refreshSection(ctx));
+        }
+        await this.#afterStored(R, () => this.#flush(ctx));
+        return receipt;
+    }
+    /**
+     * LFCP-03-034: a step after a local write is durable (the profile's
+     * bookkeeping, status reports, the send). Its failure never undoes the
+     * write or fails the call that made it: a lost connection leaves the
+     * write in the outbound queue for the next one, and anything else (the
+     * profile's committed() throwing, say) is reported as an error event, as
+     * #emit reports a throwing listener. An engine trap is thrown on: the
+     * call rejects with it.
+     */
+    async #afterStored(resource, step) {
+        try {
+            await step();
+        }
+        catch (e) {
+            if (isEngineTrap(e))
+                throw e;
+            if (e instanceof ConnectionNotReady)
+                return;
+            // #emit does not throw a listener's failure: the report cannot undo the write.
+            this.#error("INTERNAL", `a step after a durable local write failed; the write stands (${e instanceof Error ? e.message : String(e)})`, resource);
+        }
     }
     async publishSnapshot(resource) {
         const ctx = this.#resources.get(toHex(resource));
@@ -1622,8 +1690,9 @@ export class SyncClient {
             value: binding.current(),
         });
         ctx.unitsSinceSnapshot = 0;
-        this.#emit({ type: "snapshot-published", resourceId: R, snapshotId: created.snapshotId });
-        await this.#flush(ctx);
+        // Queued: the Snapshot stands whatever a listener or the send does.
+        await this.#afterStored(R, () => this.#emit({ type: "snapshot-published", resourceId: R, snapshotId: created.snapshotId }));
+        await this.#afterStored(R, () => this.#flush(ctx));
         return created.snapshotId;
     }
     async #dataRound(ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlfcp/client",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "LFCP client: session, Control Plane and Data Plane synchronization.",
   "keywords": [
     "openlfcp",
@@ -42,9 +42,9 @@
     "tag": "latest"
   },
   "dependencies": {
-    "@openlfcp/core": "^0.2.0",
-    "@openlfcp/crypto": "^0.2.0",
-    "@openlfcp/storage": "^0.2.0",
-    "@openlfcp/wire": "^0.2.0"
+    "@openlfcp/crypto": "^0.2.2",
+    "@openlfcp/storage": "^0.2.2",
+    "@openlfcp/wire": "^0.2.2",
+    "@openlfcp/core": "^0.2.2"
   }
 }