@openlfcp/client 0.1.0-rc.1 → 0.1.1

package/README.md

@@ -3,7 +3,7 @@
 An LFCP client on top of the other packages: the WebSocket session (`SyncClient`), Control and Data Plane synchronization, the outbound queue, applying received units to a Data Profile (`DataUnitApplier`) with the crash-loop breaker, invitations, Snapshots and storage helpers.
 
 ```sh
-npm install @openlfcp/client@next
+npm install @openlfcp/client
 ```
 
 ESM only; Node.js 24 or later (browsers and Electron for every package except `@openlfcp/storage-node`).
@@ -13,8 +13,8 @@ ESM only; Node.js 24 or later (browsers and Electron for every package except `@
 Part of the OpenLFCP TypeScript SDK, which implements the OpenLFCP MVP 0.1
 subset of [LFCP-WIRE-01](https://github.com/openlfcp/spec/blob/main/wire/LFCP-WIRE-01.md)
 at `mvp-0.1-baseline.8`, not every deferred WIRE-01 feature. It does not
-claim full LFCP-WIRE-01 conformance. This is a release candidate
-(`0.1.0-rc.1`, npm dist-tag `next`): APIs may still change.
+claim full LFCP-WIRE-01 conformance. This is the MVP 0.1 release
+(`0.1.1`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
 
 ## Links
 

package/dist/index.d.ts

@@ -11,5 +11,5 @@ export { createQueuedSnapshot, outboundItem, queueControlRecord, queueKeyEpoch,
 export { type ResourcePhase, type ResourcePhaseEvent, resourcePhaseTransition, } from "./resource-state.js";
 export { type CreatedSnapshot, type CreateSnapshotOptions, createSnapshot } from "./snapshot.js";
 export { adoptStoredDeks, createQueuedDataUnit, dataUnitRow, dekResolver, latestAcceptedOwnUnit, loadControlChain, StoredSeenUnits, saveControlChain, saveControlConflict, } from "./storage.js";
-export { defaultReconnect, type ReconnectPolicy, type ResourceBinding, type SnapshotBinding, SyncClient, type SyncClientOptions, type SyncEvent, startSyncDriver, } from "./sync-client.js";
+export { defaultReconnect, type ReconnectPolicy, type ResourceBinding, type ResourceRefusal, type SnapshotBinding, SyncClient, type SyncClientOptions, type SyncEvent, startSyncDriver, TERMINAL_RESOURCE_CODES, } from "./sync-client.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -11,5 +11,5 @@ export { createQueuedSnapshot, outboundItem, queueControlRecord, queueKeyEpoch,
 export { resourcePhaseTransition, } from "./resource-state.js";
 export { createSnapshot } from "./snapshot.js";
 export { adoptStoredDeks, createQueuedDataUnit, dataUnitRow, dekResolver, latestAcceptedOwnUnit, loadControlChain, StoredSeenUnits, saveControlChain, saveControlConflict, } from "./storage.js";
-export { defaultReconnect, SyncClient, startSyncDriver, } from "./sync-client.js";
+export { defaultReconnect, SyncClient, startSyncDriver, TERMINAL_RESOURCE_CODES, } from "./sync-client.js";
 //# sourceMappingURL=index.js.map

package/dist/sync-client.d.ts

@@ -153,7 +153,46 @@ export type SyncEvent = {
     readonly resourceId?: ResourceId;
     readonly code: string;
     readonly message: string;
+}
+/**
+ * The server refused the Resource for good (see ResourceRefusal): it is
+ * CLOSED and is not opened again until open() is called for it.
+ */
+ | {
+    readonly type: "resource-refused";
+    readonly resourceId: ResourceId;
+    readonly refusal: ResourceRefusal;
 };
+/**
+ * Why a server will not sync a Resource with this session, from a NACK
+ * whose code no retry can change (TERMINAL_RESOURCE_CODES): the server does
+ * not host it (§41: purged, never hosted, a restored server), it was
+ * tombstoned (§24), the session Principal may not read it (§41, §84: never
+ * granted or revoked), or the request itself is not acceptable to it. The
+ * Resource stays CLOSED; open() asks again.
+ */
+export interface ResourceRefusal {
+    /** The §62 name, e.g. RESOURCE_NOT_HOSTED. */
+    readonly code: string;
+    /** The server's diagnostic, if any (never key material, §60). */
+    readonly diagnostic?: string;
+    /** The server that refused (the session URL). */
+    readonly url: string;
+    /** Which request was refused: "open", "control", "keys", "data-get", "data-have" or "snapshot". */
+    readonly request: string;
+}
+/**
+ * §62 codes that end syncing a Resource on this server when they refuse
+ * RESOURCE_OPEN or one of its reads (CONTROL_GET, KEY_PACKAGE_GET, DATA_GET,
+ * DATA_HAVE, SNAPSHOT_GET). Repeating the same request cannot change them:
+ * the server's hosting or the Resource's Control state must change first,
+ * and the application decides when to ask again. Every other code is
+ * transient for these requests (RATE_LIMITED, INTERNAL_ERROR, QUOTA_EXCEEDED,
+ * unknown codes) and is retried with the ReconnectPolicy's backoff, except
+ * where the request has its own fallback: KEY_PACKAGE_GET → KEY_BLOCKED,
+ * SNAPSHOT_GET → replaying the units (§29.2).
+ */
+export declare const TERMINAL_RESOURCE_CODES: ReadonlySet<string>;
 export declare class SyncClient {
     #private;
     constructor(options: SyncClientOptions);
@@ -163,6 +202,8 @@ export declare class SyncClient {
     idle(): Promise<void>;
     get connectionState(): ClientConnectionState;
     resourceState(resource: ResourceId): ResourcePhase;
+    /** Why the server refused the Resource for good, or null (see ResourceRefusal). */
+    resourceRefusal(resource: ResourceId): ResourceRefusal | null;
     /** Connects, and reconnects after losses (per the ReconnectPolicy) until stop(). */
     start(): void;
     /** Closes the connection and stops reconnecting. Local state stays usable. */

package/dist/sync-client.js

@@ -11,6 +11,26 @@ import { resourcePhaseTransition, } from "./resource-state.js";
 import { adoptStoredDeks, dekResolver, loadControlChain, saveControlChain, saveControlConflict, } from "./storage.js";
 /** 1 s, doubling, at most 60 s, forever. */
 export const defaultReconnect = (attempt) => Math.min(60_000, 1000 * 2 ** (attempt - 1));
+/**
+ * §62 codes that end syncing a Resource on this server when they refuse
+ * RESOURCE_OPEN or one of its reads (CONTROL_GET, KEY_PACKAGE_GET, DATA_GET,
+ * DATA_HAVE, SNAPSHOT_GET). Repeating the same request cannot change them:
+ * the server's hosting or the Resource's Control state must change first,
+ * and the application decides when to ask again. Every other code is
+ * transient for these requests (RATE_LIMITED, INTERNAL_ERROR, QUOTA_EXCEEDED,
+ * unknown codes) and is retried with the ReconnectPolicy's backoff, except
+ * where the request has its own fallback: KEY_PACKAGE_GET → KEY_BLOCKED,
+ * SNAPSHOT_GET → replaying the units (§29.2).
+ */
+export const TERMINAL_RESOURCE_CODES = new Set([
+    "RESOURCE_NOT_HOSTED",
+    "RESOURCE_NOT_FOUND",
+    "RESOURCE_TOMBSTONED",
+    "AUTHORIZATION_FAILED",
+    "PROTOCOL_UNSUPPORTED",
+    "MALFORMED_MESSAGE",
+    "PROFILE_UNSUPPORTED",
+]);
 const NACK_NAME = new Map(Object.entries(ERROR_CODE).map(([k, v]) => [v, k]));
 const SUBSCRIBE_DATA_AND_CONTROL = 3n;
 const iso = (ms) => new Date(ms).toISOString();
@@ -103,6 +123,10 @@ export class SyncClient {
     resourceState(resource) {
         return this.#resources.get(toHex(resource))?.state ?? "CLOSED";
     }
+    /** Why the server refused the Resource for good, or null (see ResourceRefusal). */
+    resourceRefusal(resource) {
+        return this.#resources.get(toHex(resource))?.refusal ?? null;
+    }
     /** Connects, and reconnects after losses (per the ReconnectPolicy) until stop(). */
     start() {
         if (this.#trapped)
@@ -144,10 +168,17 @@ export class SyncClient {
                 covered: [],
                 unitsSinceSnapshot: 0,
                 lastRound: "",
+                refusal: null,
+                refusedAttempt: 0,
+                reopenAt: null,
             };
             this.#resources.set(key, ctx);
         }
         ctx.wanted = true;
+        // An explicit open asks the server again after a refusal.
+        ctx.refusal = null;
+        ctx.refusedAttempt = 0;
+        ctx.reopenAt = null;
         if (this.#connection.state === "READY")
             this.#serial(() => this.#sendOpen(ctx));
     }
@@ -202,6 +233,12 @@ export class SyncClient {
             this.#expireRequests(now);
         this.#serial(async () => {
             for (const ctx of this.#resources.values()) {
+                if (ctx.reopenAt !== null &&
+                    now >= ctx.reopenAt &&
+                    ctx.state === "CLOSED" &&
+                    ctx.wanted &&
+                    this.#connection.state === "READY")
+                    await this.#sendOpen(ctx);
                 if (ctx.state === "LIVE" && now - ctx.lastHave >= this.#antiEntropyMs)
                     this.#sendHave(ctx, now);
                 if (ctx.state === "KEY_BLOCKED" && now - ctx.lastKeyRequest >= this.#antiEntropyMs)
@@ -280,6 +317,8 @@ export class SyncClient {
         if (next === undefined)
             return false;
         ctx.state = next;
+        if (next === "LIVE")
+            ctx.refusedAttempt = 0;
         this.#emit({ type: "resource-state", resourceId: ctx.binding.resourceId, state: next });
         if (next === "LIVE" && ctx.controlStale) {
             ctx.controlStale = false;
@@ -338,6 +377,7 @@ export class SyncClient {
         ctx.fetched = [];
         ctx.controlTarget = null;
         ctx.early = [];
+        ctx.reopenAt = null;
         this.#request({ kind: "open", resource: toHex(R) }, createMessage("RESOURCE_OPEN", {
             resourceId: R,
             heads,
@@ -457,15 +497,50 @@ export class SyncClient {
         }
         const ctx = this.#resources.get(request.resource);
         this.#error(code, `${request.kind} refused${m.body.diagnostic ? `: ${m.body.diagnostic}` : ""}`, ctx?.binding.resourceId);
-        if (ctx === undefined)
+        if (ctx === undefined || request.kind === "close")
             return;
-        if (request.kind === "open")
-            this.#move(ctx, "CLOSE");
+        if (TERMINAL_RESOURCE_CODES.has(code)) {
+            this.#refuse(ctx, {
+                code,
+                url: this.#o.url,
+                request: request.kind,
+                ...(m.body.diagnostic === undefined ? {} : { diagnostic: m.body.diagnostic }),
+            });
+            return;
+        }
         if (request.kind === "keys")
             this.#keyBlocked(ctx);
         // A Snapshot is an optimization (§29.2): without it, replay the units.
-        if (request.kind === "snapshot" && ctx.snapshotPending)
-            this.#serial(() => this.#afterSnapshot(ctx));
+        else if (request.kind === "snapshot") {
+            if (ctx.snapshotPending)
+                this.#serial(() => this.#afterSnapshot(ctx));
+        }
+        // A transient refusal of the open or of a sync round: the Resource
+        // would otherwise sit there until the next reconnect. Start over after
+        // a backoff. A refused DATA_HAVE is simply sent again (§69).
+        else if (request.kind !== "data-have")
+            this.#retryLater(ctx);
+    }
+    /** The server refused the Resource for good: CLOSED, not reopened until open() asks again. */
+    #refuse(ctx, refusal) {
+        const subscribed = ctx.state !== "CLOSED" && ctx.state !== "OPENING";
+        ctx.wanted = false;
+        ctx.reopenAt = null;
+        ctx.refusal = Object.freeze(refusal);
+        // Stop any pushes the server may still send for it (§43).
+        if (subscribed && this.#connection.state === "READY")
+            this.#request({ kind: "close", resource: toHex(ctx.binding.resourceId) }, createMessage("RESOURCE_CLOSE", { resourceId: ctx.binding.resourceId }));
+        this.#move(ctx, "CLOSE");
+        this.#emit({ type: "resource-refused", resourceId: ctx.binding.resourceId, refusal });
+    }
+    /** CLOSED now, opened again after the ReconnectPolicy's delay for this Resource's attempt. */
+    #retryLater(ctx) {
+        if (ctx.state !== "CLOSED" && ctx.state !== "OPENING" && this.#connection.state === "READY")
+            this.#request({ kind: "close", resource: toHex(ctx.binding.resourceId) }, createMessage("RESOURCE_CLOSE", { resourceId: ctx.binding.resourceId }));
+        this.#move(ctx, "CLOSE");
+        ctx.refusedAttempt += 1;
+        const delay = (this.#o.reconnect ?? defaultReconnect)(ctx.refusedAttempt);
+        ctx.reopenAt = delay === null ? null : this.#o.now() + delay;
     }
     // -------------------------------------------------------------------------
     // Control (§44-§47, §67)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlfcp/client",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.1",
   "description": "LFCP client: session, Control Plane and Data Plane synchronization.",
   "keywords": [
     "openlfcp",
@@ -39,12 +39,12 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "next"
+    "tag": "latest"
   },
   "dependencies": {
-    "@openlfcp/core": "^0.1.0-rc.1",
-    "@openlfcp/crypto": "^0.1.0-rc.1",
-    "@openlfcp/storage": "^0.1.0-rc.1",
-    "@openlfcp/wire": "^0.1.0-rc.1"
+    "@openlfcp/core": "^0.1.1",
+    "@openlfcp/storage": "^0.1.1",
+    "@openlfcp/crypto": "^0.1.1",
+    "@openlfcp/wire": "^0.1.1"
   }
 }