@cortexkit/claustrum-client 0.12.0 → 0.13.0

package/README.md

@@ -23,6 +23,21 @@ credential caching, refresh, account scheduling, and retry policy.
   as a version older than every real one.
 • Unknown server error classes are bounded to `transient`; callers must retry them
   rather than treating a forward-compatible class as permanent.
+• **Changed in 0.13.0:** a transport `Error` frame whose answer no retry or reconnect
+  can change is reported as `permanent` with action `gone`, and the client no longer
+  reconnects for it: `unknown_method`, `invalid_params`, `invalid_request`,
+  `flow_scopes_unsupported`, `invalid_control_body`, `unknown_module`, and the SDK's
+  pre-send `missing_identity`. These are not verdicts about a credential: do not mark
+  anything gone or needing re-authentication on them; stop retrying and surface the
+  code. `unknown_method` from a vault means the vault predates that operation (for
+  example an enrollment op against a vault older than the enrollment ceremony):
+  update the vault. `watchScoped` is the exception: there `unknown_method` resolves
+  `closed` as `unsupported`, the signal to fall back to polling `listScoped`. Before 0.13.0 these were `transient`/`retry`. Every other
+  transport failure is still `transient`/`retry`.
+• Since 0.13.0, when a terminal transport failure makes the client reconnect and the
+  reconnect or the retried call then fails, the error carries the ORIGINAL call's code
+  and class. Earlier versions threw the reconnect's error instead, usually
+  `transport_error`, hiding the original call's code.
 • `listScoped` rows always carry `providerIds` (a required field since 0.6.0, so code
   that builds rows by hand, such as test fixtures, must set it). An empty array means
   no provider ids are set. Since 0.6.2 a daemon too old to send the field decodes the

package/dist/wire.js

@@ -5,6 +5,37 @@ import { storeIdentity } from './identity.js';
 import { openScopedWatch } from './watch.js';
 const CLAUSTRUM_MODULE_ID = 'claustrum';
 const RECONNECT_BACKOFF_MS = 60_000;
+/**
+ * Transport `Error` frame codes whose answer neither a retry nor a fresh connection can
+ * change. A call failing with one of these is reported as `permanent`/`gone` and is never
+ * reconnected; every other transport failure stays `transient`/`retry`.
+ *
+ * This is the ONLY list of such codes: the error classification and the reconnect
+ * decision both read it, so the two cannot disagree about a code.
+ *
+ * - `unknown_method`: the vault does not implement the operation. From a released vault
+ *   this means the vault predates the operation, and the remedy is to update the vault.
+ * - `invalid_params`, `invalid_request`: the vault could not decode the request body or
+ *   its params. The same bytes are refused the same way on any connection.
+ * - `flow_scopes_unsupported`: the vault refuses routes opened under a flow scope.
+ * - `invalid_control_body`: the vault build cannot decode the daemon's route bind.
+ * - `unknown_module`: the daemon has no module with this id registered or supervised at
+ *   all. A vault that is restarting or warming up is reported as `module_warming` or
+ *   `target_unavailable` instead, which the SDK already retries in place. A fresh
+ *   connection to the same daemon gets the same answer, and the wasted reconnect would
+ *   also start the reconnect backoff, leaving a genuinely wedged connection unable to
+ *   recover for a minute.
+ * - `missing_identity`: the SDK refused before sending because no bind identity was set.
+ */
+const DEFINITIVE_TRANSPORT_CODES = new Set([
+    'unknown_method',
+    'invalid_params',
+    'invalid_request',
+    'flow_scopes_unsupported',
+    'invalid_control_body',
+    'unknown_module',
+    'missing_identity',
+]);
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -284,46 +315,45 @@ export class ClaustrumClient {
             });
         }
         catch (error) {
-            if (this.#shouldReconnect(error)) {
-                try {
-                    if (this.#client === sentClient)
-                        await this.#reconnect();
-                }
-                catch (reconnectError) {
-                    throw this.#asTransportError(reconnectError);
-                }
-                try {
-                    return await this.#client.call(CLAUSTRUM_MODULE_ID, method, params, {
-                        identity: this.#identity,
-                        consumerIdentity: null,
-                    });
-                }
-                catch (retryError) {
-                    throw this.#asTransportError(retryError);
-                }
+            if (!this.#shouldReconnect(error))
+                throw this.#asTransportError(error);
+            try {
+                if (this.#client === sentClient)
+                    await this.#reconnect();
+                return await this.#client.call(CLAUSTRUM_MODULE_ID, method, params, {
+                    identity: this.#identity,
+                    consumerIdentity: null,
+                });
+            }
+            catch (recoveryError) {
+                // Report the call's own failure, not the recovery's. A failed reconnect would
+                // otherwise replace the original call's code with `transport_error`, so
+                // the one actionable code would appear once and every later diagnostic would
+                // name a transport failure that never happened. Only a failure that carried no
+                // code at all has nothing to preserve.
+                throw this.#transportErrorCode(error) === undefined
+                    ? this.#asTransportError(recoveryError)
+                    : this.#asTransportError(error);
             }
-            throw this.#asTransportError(error);
         }
     }
+    #transportErrorCode(error) {
+        return error instanceof SubcCallError && error.code ? error.code : undefined;
+    }
     #asTransportError(error) {
         if (error instanceof ClaustrumCredentialError)
             return error;
-        const code = error instanceof SubcCallError && error.code ? error.code : 'transport_error';
-        return new ClaustrumCredentialError(code, 'transient', 'retry');
+        const code = this.#transportErrorCode(error);
+        if (code !== undefined && DEFINITIVE_TRANSPORT_CODES.has(code)) {
+            return new ClaustrumCredentialError(code, 'permanent', 'gone');
+        }
+        return new ClaustrumCredentialError(code ?? 'transport_error', 'transient', 'retry');
     }
     #shouldReconnect(error) {
         return (!this.#closed &&
             error instanceof SubcCallError &&
             error.kind === 'terminal' &&
-            error.code !== 'missing_identity' &&
-            error.code !== 'invalid_control_body' &&
-            // The daemon answers unknown_module only when no module with this id is
-            // registered or supervised at all; a vault that is restarting or warming up
-            // is reported as module_warming or target_unavailable, which the SDK already
-            // retries in place. A fresh connection to the same daemon gets the same
-            // answer, and the wasted reconnect would also start the reconnect backoff,
-            // leaving a genuinely wedged connection unable to recover for a minute.
-            error.code !== 'unknown_module');
+            !DEFINITIVE_TRANSPORT_CODES.has(error.code ?? ''));
     }
     async #reconnect() {
         if (this.#closed)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/claustrum-client",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "license": "MIT",
   "repository": {
     "type": "git",