@usearete/sdk 0.22.4 → 0.23.1

package/dist/index.cjs

@@ -10,6 +10,10 @@ const DEFAULT_CONFIG = {
     maxReconnectAttempts: 5,
     maxEntriesPerView: DEFAULT_MAX_ENTRIES_PER_VIEW,
 };
+/** True for the session refusals that no retry or reconnect can resolve. */
+function isStackVersionRefusalCode(code) {
+    return code === 'STACK_VERSION_RETIRED' || code === 'STACK_VERSION_UNKNOWN';
+}
 const REPLAY_ERROR_CODES = {
     'cursor-expired': true,
     'cursor-epoch-changed': true,
@@ -48,41 +52,66 @@ class AreteError extends Error {
  * collapsing them into a generic failure would destroy the only distinction.
  */
 function parseErrorCode(errorCode) {
-    const codeMap = {
-        'token-missing': 'TOKEN_MISSING',
-        'token-expired': 'TOKEN_EXPIRED',
-        'token-invalid-signature': 'TOKEN_INVALID_SIGNATURE',
-        'token-invalid-format': 'TOKEN_INVALID_FORMAT',
-        'token-invalid-issuer': 'TOKEN_INVALID_ISSUER',
-        'token-invalid-audience': 'TOKEN_INVALID_AUDIENCE',
-        'token-missing-claim': 'TOKEN_MISSING_CLAIM',
-        'token-key-not-found': 'TOKEN_KEY_NOT_FOUND',
-        'origin-mismatch': 'ORIGIN_MISMATCH',
-        'origin-required': 'ORIGIN_REQUIRED',
-        'origin-not-allowed': 'ORIGIN_NOT_ALLOWED',
-        'rate-limit-exceeded': 'RATE_LIMIT_EXCEEDED',
-        'websocket-session-rate-limit-exceeded': 'WEBSOCKET_SESSION_RATE_LIMIT_EXCEEDED',
-        'connection-limit-exceeded': 'CONNECTION_LIMIT_EXCEEDED',
-        'subscription-limit-exceeded': 'SUBSCRIPTION_LIMIT_EXCEEDED',
-        'snapshot-limit-exceeded': 'SNAPSHOT_LIMIT_EXCEEDED',
-        'egress-limit-exceeded': 'EGRESS_LIMIT_EXCEEDED',
-        'invalid-static-token': 'INVALID_STATIC_TOKEN',
-        'internal-error': 'INTERNAL_ERROR',
-        'auth-required': 'AUTH_REQUIRED',
-        'missing-authorization-header': 'MISSING_AUTHORIZATION_HEADER',
-        'invalid-authorization-format': 'INVALID_AUTHORIZATION_FORMAT',
-        'invalid-api-key': 'INVALID_API_KEY',
-        'expired-api-key': 'EXPIRED_API_KEY',
-        'user-not-found': 'USER_NOT_FOUND',
-        'secret-key-required': 'SECRET_KEY_REQUIRED',
-        'deployment-access-denied': 'DEPLOYMENT_ACCESS_DENIED',
-        'quota-exceeded': 'QUOTA_EXCEEDED',
-    };
     const normalized = errorCode.toLowerCase();
     if (isReplayErrorCode(normalized))
         return normalized;
-    return codeMap[normalized] || 'INTERNAL_ERROR';
+    return authErrorCodeFromWire(normalized) ?? 'INTERNAL_ERROR';
 }
+/**
+ * Resolve a wire error code the way {@link parseErrorCode} does, except that a
+ * code this SDK does not know is returned as sent instead of being collapsed
+ * into `INTERNAL_ERROR`. A newer server's refusal then still reaches the
+ * consumer under its own name.
+ */
+/** Whether `code` is a wire error code this SDK knows. */
+function isKnownWireErrorCode(code) {
+    const normalized = code.trim().toLowerCase();
+    return isReplayErrorCode(normalized) || authErrorCodeFromWire(normalized) !== undefined;
+}
+function parseWireErrorCode(errorCode) {
+    const trimmed = errorCode.trim();
+    const normalized = trimmed.toLowerCase();
+    if (isReplayErrorCode(normalized))
+        return normalized;
+    return authErrorCodeFromWire(normalized) ?? trimmed;
+}
+function authErrorCodeFromWire(normalized) {
+    return Object.prototype.hasOwnProperty.call(AUTH_ERROR_CODES_BY_WIRE, normalized)
+        ? AUTH_ERROR_CODES_BY_WIRE[normalized]
+        : undefined;
+}
+const AUTH_ERROR_CODES_BY_WIRE = {
+    'token-missing': 'TOKEN_MISSING',
+    'token-expired': 'TOKEN_EXPIRED',
+    'token-invalid-signature': 'TOKEN_INVALID_SIGNATURE',
+    'token-invalid-format': 'TOKEN_INVALID_FORMAT',
+    'token-invalid-issuer': 'TOKEN_INVALID_ISSUER',
+    'token-invalid-audience': 'TOKEN_INVALID_AUDIENCE',
+    'token-missing-claim': 'TOKEN_MISSING_CLAIM',
+    'token-key-not-found': 'TOKEN_KEY_NOT_FOUND',
+    'origin-mismatch': 'ORIGIN_MISMATCH',
+    'origin-required': 'ORIGIN_REQUIRED',
+    'origin-not-allowed': 'ORIGIN_NOT_ALLOWED',
+    'rate-limit-exceeded': 'RATE_LIMIT_EXCEEDED',
+    'websocket-session-rate-limit-exceeded': 'WEBSOCKET_SESSION_RATE_LIMIT_EXCEEDED',
+    'connection-limit-exceeded': 'CONNECTION_LIMIT_EXCEEDED',
+    'subscription-limit-exceeded': 'SUBSCRIPTION_LIMIT_EXCEEDED',
+    'snapshot-limit-exceeded': 'SNAPSHOT_LIMIT_EXCEEDED',
+    'egress-limit-exceeded': 'EGRESS_LIMIT_EXCEEDED',
+    'invalid-static-token': 'INVALID_STATIC_TOKEN',
+    'internal-error': 'INTERNAL_ERROR',
+    'auth-required': 'AUTH_REQUIRED',
+    'missing-authorization-header': 'MISSING_AUTHORIZATION_HEADER',
+    'invalid-authorization-format': 'INVALID_AUTHORIZATION_FORMAT',
+    'invalid-api-key': 'INVALID_API_KEY',
+    'expired-api-key': 'EXPIRED_API_KEY',
+    'user-not-found': 'USER_NOT_FOUND',
+    'secret-key-required': 'SECRET_KEY_REQUIRED',
+    'deployment-access-denied': 'DEPLOYMENT_ACCESS_DENIED',
+    'quota-exceeded': 'QUOTA_EXCEEDED',
+    'stack-version-retired': 'STACK_VERSION_RETIRED',
+    'stack-version-unknown': 'STACK_VERSION_UNKNOWN',
+};
 
 const GZIP_MAGIC_0 = 0x1f;
 const GZIP_MAGIC_1 = 0x8b;
@@ -625,6 +654,73 @@ function hostedWebsocketSuffixes() {
     return [HOSTED_WEBSOCKET_SUFFIX, ...extraHostedSuffixes];
 }
 const MAX_HTTP_AUTH_TOKEN_STATES = 32;
+function optionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** The structured fields of a stack version refusal, dropping malformed ones. */
+function parseStackVersionRefusal(body) {
+    const replacementBody = typeof body?.replacement === 'object' && body.replacement !== null
+        ? body.replacement
+        : undefined;
+    const version = optionalString(replacementBody?.['version']);
+    const stackManifestHash = optionalString(replacementBody?.['stackManifestHash']);
+    const upgradeCommand = optionalString(body?.upgradeCommand);
+    const retiredAt = optionalString(body?.retiredAt);
+    return {
+        ...(version !== undefined || stackManifestHash !== undefined
+            ? {
+                replacement: {
+                    ...(version !== undefined ? { version } : {}),
+                    ...(stackManifestHash !== undefined ? { stackManifestHash } : {}),
+                },
+            }
+            : {}),
+        ...(upgradeCommand !== undefined ? { upgradeCommand } : {}),
+        ...(retiredAt !== undefined ? { retiredAt } : {}),
+    };
+}
+/** The server's message, followed by the replacement and how to install it. */
+function describeStackVersionRefusal(message, refusal) {
+    const guidance = [];
+    const replacement = refusal.replacement?.version ?? refusal.replacement?.stackManifestHash;
+    if (replacement !== undefined)
+        guidance.push(`Replacement: ${replacement}.`);
+    if (refusal.upgradeCommand !== undefined)
+        guidance.push(`Upgrade with: ${refusal.upgradeCommand}`);
+    if (guidance.length === 0)
+        return message;
+    const trimmed = message.trimEnd();
+    return `${trimmed}${/[.!?]$/.test(trimmed) ? '' : '.'} ${guidance.join(' ')}`;
+}
+/**
+ * The wire code a close reason carries: the `code` of `code: message`, or the
+ * whole reason when it is exactly a known wire code. A free-form reason
+ * carries none.
+ */
+function closeReasonWireCode(reason) {
+    if (!reason)
+        return undefined;
+    const prefixed = reason.match(/^([\w-]+):/)?.[1];
+    if (prefixed !== undefined)
+        return prefixed;
+    const bare = reason.trim();
+    return isKnownWireErrorCode(bare) ? bare : undefined;
+}
+/** A stack version refusal ends the connection: no retry or reconnect can fix it. */
+function isTerminalRefusal(error) {
+    return error instanceof AreteError && isStackVersionRefusalCode(error.code);
+}
+function normalizeStackRelease(release) {
+    if (release === undefined)
+        return undefined;
+    if (typeof release.stackManifestHash !== 'string'
+        || release.stackManifestHash.length === 0
+        || typeof release.liveAlias !== 'string'
+        || release.liveAlias.length === 0) {
+        throw new AreteError('Stack release requires a non-empty stackManifestHash and liveAlias', 'INVALID_CONFIG');
+    }
+    return { stackManifestHash: release.stackManifestHash, liveAlias: release.liveAlias };
+}
 function normalizeTokenResult(result) {
     if (typeof result === 'string') {
         return { token: result };
@@ -801,6 +897,7 @@ class ConnectionManager {
         this.maxReconnectAttempts =
             config.maxReconnectAttempts ?? DEFAULT_CONFIG.maxReconnectAttempts;
         this.authConfig = config.auth;
+        this.release = normalizeStackRelease(config.release);
         this.authFetch = config.fetch ?? ((input, init) => {
             if (typeof globalThis.fetch !== 'function') {
                 throw new AreteError('A fetch implementation is required for authentication token requests', 'INVALID_CONFIG');
@@ -903,7 +1000,15 @@ class ConnectionManager {
         }
     }
     async fetchAuthToken(scopes, isCurrent) {
-        const request = { scopes: normalizeScopes(scopes) };
+        const request = {
+            scopes: normalizeScopes(scopes),
+            ...(this.release
+                ? {
+                    stackManifestHash: this.release.stackManifestHash,
+                    liveAlias: this.release.liveAlias,
+                }
+                : {}),
+        };
         const result = await this.requestAuthToken(request, isCurrent);
         return result === undefined ? undefined : this.updateTokenState(result, request.scopes);
     }
@@ -1032,9 +1137,14 @@ class ConnectionManager {
                 ? { ...target, programReleaseHash: request.programReleaseHash }
                 : target;
         }
+        // Session requests from a stack definition without a release stay
+        // byte-for-byte what older clients send.
         return {
             websocket_url: this.websocketUrl ?? '',
             scopes: request.scopes,
+            ...(request.stackManifestHash !== undefined && request.liveAlias !== undefined
+                ? { stackManifestHash: request.stackManifestHash, liveAlias: request.liveAlias }
+                : {}),
         };
     }
     async fetchTokenFromEndpoint(tokenEndpoint, request) {
@@ -1071,6 +1181,15 @@ class ConnectionManager {
             const errorMessage = typeof parsedError?.error === 'string' && parsedError.error.length > 0
                 ? parsedError.error
                 : rawError || response.statusText || 'Authentication request failed';
+            if (isStackVersionRefusalCode(errorCode)) {
+                const refusal = parseStackVersionRefusal(parsedError);
+                throw new AreteError(describeStackVersionRefusal(`Token endpoint returned ${response.status}: ${errorMessage}`, refusal), errorCode, {
+                    status: response.status,
+                    wireErrorCode,
+                    responseBody: rawError || null,
+                    ...refusal,
+                });
+            }
             throw new AreteError(`Token endpoint returned ${response.status}: ${errorMessage}`, errorCode, {
                 status: response.status,
                 wireErrorCode,
@@ -1136,8 +1255,10 @@ class ConnectionManager {
                     this.scheduleTokenRefresh();
                 }
             }
-            catch {
-                if (this.tokenRefreshInFlight === refresh) {
+            catch (error) {
+                // A stack version refusal will not change on retry. Stop refreshing;
+                // the next connect after this session ends reports it.
+                if (this.tokenRefreshInFlight === refresh && !isTerminalRefusal(error)) {
                     this.scheduleTokenRefresh();
                 }
             }
@@ -1330,11 +1451,11 @@ class ConnectionManager {
         const issue = {
             error: message.error ?? message.code,
             message: message.message ?? message.error ?? message.code,
-            code: parseErrorCode(message.code),
+            code: parseWireErrorCode(message.code),
             retryable: message.retryable ?? false,
-            retryAfter: message.retry_after,
-            suggestedAction: message.suggested_action,
-            docsUrl: message.docs_url,
+            retryAfter: message.retryAfter ?? message.retry_after,
+            suggestedAction: message.suggestedAction ?? message.suggested_action,
+            docsUrl: message.docsUrl ?? message.docs_url,
             fatal: message.fatal,
             subscriptionId: message.subscriptionId,
         };
@@ -1370,7 +1491,7 @@ class ConnectionManager {
                 this.pendingConnect = null;
             }
             if (generation === this.socketGeneration) {
-                this.updateState(recovering ? 'reconnecting' : 'error', error instanceof Error ? error.message : 'Failed to get token');
+                this.updateState(recovering && !isTerminalRefusal(error) ? 'reconnecting' : 'error', error instanceof Error ? error.message : 'Failed to get token');
             }
             throw error;
         }
@@ -1398,6 +1519,7 @@ class ConnectionManager {
                     if (!isCurrentSocket())
                         return;
                     this.reconnectAttempts = 0;
+                    this.lastDisconnectReason = undefined;
                     this.updateState('connected');
                     this.startPingInterval();
                     this.scheduleTokenRefresh();
@@ -1471,8 +1593,19 @@ class ConnectionManager {
                             ? `${event.code}: ${event.reason}`
                             : `code ${event.code}`;
                         const errorMessage = `WebSocket closed before open (${detail})`;
-                        this.updateState(recovering ? 'reconnecting' : 'error', errorMessage);
-                        finish(() => reject(new AreteError(errorMessage, 'CONNECTION_ERROR')));
+                        const reasonCode = closeReasonWireCode(event.reason);
+                        const wireErrorCode = reasonCode === undefined
+                            ? undefined
+                            : parseWireErrorCode(reasonCode);
+                        // A stack version refusal is terminal even mid-reconnect: carry it
+                        // as the error code, so recovery stops instead of retrying.
+                        const refused = wireErrorCode !== undefined && isStackVersionRefusalCode(wireErrorCode);
+                        this.updateState(recovering && !refused ? 'reconnecting' : 'error', errorMessage);
+                        finish(() => reject(new AreteError(errorMessage, refused ? wireErrorCode : 'CONNECTION_ERROR', {
+                            closeCode: event.code,
+                            closeReason: event.reason || undefined,
+                            wireErrorCode,
+                        })));
                         return;
                     }
                     if (this.reconnectForTokenRefresh) {
@@ -1481,15 +1614,19 @@ class ConnectionManager {
                             this.updateState('error', 'WebSocket closed for token refresh and automatic reconnection is disabled');
                             return;
                         }
-                        void this.connect(true).catch(() => {
-                            this.handleReconnect();
+                        void this.connect(true).catch((error) => {
+                            this.recoverFromFailedConnect(error);
                         });
                         return;
                     }
                     // Parse close reason for error codes (e.g., "token-expired: Token has expired")
                     const closeReason = event.reason || '';
-                    const errorCodeMatch = closeReason.match(/^([\w-]+):/);
-                    const errorCode = errorCodeMatch ? parseErrorCode(errorCodeMatch[1]) : null;
+                    const reasonCode = closeReasonWireCode(closeReason);
+                    const errorCode = reasonCode === undefined ? null : parseWireErrorCode(reasonCode);
+                    if (errorCode !== null && isStackVersionRefusalCode(errorCode)) {
+                        this.updateState('error', `WebSocket closed (${event.code}: ${closeReason})`);
+                        return;
+                    }
                     // Check for auth errors that require token refresh
                     if (event.code === 1008 || errorCode) {
                         const isAuthError = errorCode
@@ -1502,8 +1639,8 @@ class ConnectionManager {
                                 return;
                             }
                             // Try to reconnect immediately with a fresh token
-                            void this.connect(true).catch(() => {
-                                this.handleReconnect();
+                            void this.connect(true).catch((error) => {
+                                this.recoverFromFailedConnect(error);
                             });
                             return;
                         }
@@ -1518,13 +1655,13 @@ class ConnectionManager {
                         }
                     }
                     if (this.currentState !== 'disconnected') {
+                        const detail = event.reason
+                            ? `${event.code}: ${event.reason}`
+                            : `code ${event.code}`;
                         if (this.autoReconnect) {
-                            this.handleReconnect();
+                            this.handleReconnect(`WebSocket closed (${detail})`);
                         }
                         else {
-                            const detail = event.reason
-                                ? `${event.code}: ${event.reason}`
-                                : `code ${event.code}`;
                             this.updateState('error', `WebSocket closed (${detail}) and automatic reconnection is disabled`);
                         }
                     }
@@ -1543,6 +1680,7 @@ class ConnectionManager {
         this.stopPingInterval();
         this.clearTokenRefreshTimeout();
         this.reconnectForTokenRefresh = false;
+        this.lastDisconnectReason = undefined;
         const pendingConnect = this.pendingConnect;
         this.pendingConnect = null;
         this.tokenRequestInFlight = null;
@@ -1672,29 +1810,47 @@ class ConnectionManager {
             handler(frame);
         }
     }
-    handleReconnect() {
+    /**
+     * @param reason Why the connection was lost, when known. It is reported
+     * with the `reconnecting` state and kept for the terminal error if the
+     * attempts run out, so a server's close reason is never dropped.
+     */
+    handleReconnect(reason) {
+        if (reason !== undefined) {
+            this.lastDisconnectReason = reason;
+        }
         if (!this.autoReconnect) {
             this.updateState('error', 'Automatic reconnection is disabled');
             return;
         }
         if (this.reconnectAttempts >= this.maxReconnectAttempts) {
-            this.updateState('error', `Max reconnection attempts (${this.reconnectAttempts}) reached`);
+            const lastReason = this.lastDisconnectReason;
+            this.updateState('error', `Max reconnection attempts (${this.reconnectAttempts}) reached`
+                + (lastReason ? `; last disconnect: ${lastReason}` : ''));
             return;
         }
-        this.updateState('reconnecting');
+        this.updateState('reconnecting', this.lastDisconnectReason);
         const attemptIndex = Math.min(this.reconnectAttempts, this.reconnectIntervals.length - 1);
         const delay = this.reconnectIntervals[attemptIndex] ?? 1000;
         this.reconnectAttempts++;
         this.reconnectTimeout = setTimeout(() => {
-            this.connect(true).catch(() => {
+            this.connect(true).catch((error) => {
                 // Once a socket exists, its close event owns the next retry. Token
                 // acquisition and socket construction can fail before that point.
                 if (this.ws === null && this.currentState !== 'disconnected') {
-                    this.handleReconnect();
+                    this.recoverFromFailedConnect(error);
                 }
             });
         }, delay);
     }
+    /** Schedule the next attempt after a failed reconnect, unless nothing can succeed. */
+    recoverFromFailedConnect(error) {
+        if (isTerminalRefusal(error)) {
+            // connect() already reported the refusal as the terminal error state.
+            return;
+        }
+        this.handleReconnect(error instanceof Error ? error.message : undefined);
+    }
     clearReconnectTimeout() {
         if (this.reconnectTimeout) {
             clearTimeout(this.reconnectTimeout);
@@ -7032,6 +7188,9 @@ let Arete$1 = class Arete {
             maxReconnectAttempts: options.maxReconnectAttempts,
             auth: options.auth,
             fetch: this.fetchImpl,
+            // The release names the version served at the generated endpoint. A
+            // different `url` points somewhere the generator knew nothing about.
+            release: url !== null && url === this.stack.endpoints.ws ? this.stack.release : undefined,
         });
         this.processor.useCursorTracker(this.connection.cursors);
         this.subscriptionRegistry = new SubscriptionRegistry(this.connection, this.queryStore);
@@ -8013,6 +8172,7 @@ exports.isErrorFrame = isErrorFrame;
 exports.isHostedAreteEndpoint = isHostedAreteEndpoint;
 exports.isReplayErrorCode = isReplayErrorCode;
 exports.isSnapshotFrame = isSnapshotFrame;
+exports.isStackVersionRefusalCode = isStackVersionRefusalCode;
 exports.isSubscribedFrame = isSubscribedFrame;
 exports.isUnsubscribedFrame = isUnsubscribedFrame;
 exports.isValidFrame = isValidFrame;