@mdbase-dev/connect 0.1.0-beta.59 → 0.1.0-beta.60

package/dist/browser/mdbase-connect.min.js.sha384

@@ -1 +1 @@
-sha384-69NPRMI4u0984KosSyXFlbNrbhqiCITqyXNmYsN/zEQtLEztYB+0g+zi9QKz97ij
+sha384-8q/ad0vEZFISbJVmcgiwghE8Zi5/u4kBtZPskPy+cHhXMEwZoHGTiGdujLx57o8/

package/dist/connection-transport.d.ts

@@ -32,11 +32,7 @@ export declare class ConnectionTransport {
     requestDirectAccess(options?: ConnectRequestOptions): Promise<DirectAccessStatus>;
     private requestDirectAccessWithinBudget;
     disableDirectAccess(): void;
-    /**
-     * Return one offline-replication transport regardless of whether the
-     * authority is remote, directly connected, or relay connected.
-     * Authority credentials and routing stay private inside the SDK.
-     */
+    /** Return pending writes without exposing authority transport credentials. */
     pendingMutations(): readonly PendingMutationSummary[];
     pendingMutation(requestId: string): PendingMutationSummary | null;
     recoverPendingMutation<Result>(requestId: string, options?: ConnectRequestOptions): Promise<Result>;

package/dist/connection-transport.js

@@ -10,6 +10,8 @@ import { readStoredToken } from "./stored-token.js";
 import { withCooperativeRequestBudget, withRequestBudget } from "./request-budget.js";
 import { sendAuthoritySyncRequest } from "./authority-sync-request.js";
 import { freshEncryptedRequest } from "./fresh-encrypted-request.js";
+import { isExplicitConnectorBusyResponse, retryExplicitConnectorBusy } from "./transient-retry.js";
+import { probeLoopbackAccess, tokenSupportsDirectAccess } from "./direct-access.js";
 export class ConnectionTransport {
     serverUrl;
     storage;
@@ -63,9 +65,7 @@ export class ConnectionTransport {
     get route() {
         return this.currentToken()?.authority ? "remote" : this.currentRoute;
     }
-    notifyStorageChanged() {
-        this.emitConnection();
-    }
+    notifyStorageChanged() { this.emitConnection(); }
     async checkDirectAccess(options = {}) {
         return withRequestBudget(options, this.timeouts.watchStartMs, (budget) => this.checkDirectAccessWithinBudget(budget.signal));
     }
@@ -99,11 +99,7 @@ export class ConnectionTransport {
         this.setDirectStatus("disabled");
         this.setRoute("relay");
     }
-    /**
-     * Return one offline-replication transport regardless of whether the
-     * authority is remote, directly connected, or relay connected.
-     * Authority credentials and routing stay private inside the SDK.
-     */
+    /** Return pending writes without exposing authority transport credentials. */
     pendingMutations() {
         return this.storedPendingMutations().map((pending) => ({
             requestId: pending.requestId,
@@ -136,7 +132,7 @@ export class ConnectionTransport {
             signal: budget.signal
         }));
     }
-    async performOperationWithinBudget(operation, input, options, storedPending, freshReadRetried = false) {
+    async performOperationWithinBudget(operation, input, options, storedPending, freshReadRetried = false, connectorBusyRetries = 0, knownRejectedMutationRetry = false) {
         throwIfCancelled(options.signal);
         let token = this.currentToken();
         if (!token)
@@ -160,7 +156,7 @@ export class ConnectionTransport {
             ?? (isMutation(operation, input) ? crypto.randomUUID() : undefined);
         let attempt;
         try {
-            attempt = await this.sendOperation(token, operation, input, tryDirect, options, pendingRequestId);
+            attempt = await this.sendOperation(token, operation, input, tryDirect, options, pendingRequestId, knownRejectedMutationRetry);
         }
         catch (error) {
             throw operationTransportError(error, options.signal, pendingRequestId !== undefined && this.storedPendingMutation(pendingRequestId) !== null
@@ -181,7 +177,7 @@ export class ConnectionTransport {
             token = await this.refreshAuthorization(options.signal);
             tryDirect = await this.shouldAttemptDirect(token);
             try {
-                attempt = await this.sendOperation(token, operation, input, tryDirect, options, pendingRequestId);
+                attempt = await this.sendOperation(token, operation, input, tryDirect, options, pendingRequestId, knownRejectedMutationRetry);
             }
             catch (error) {
                 throw operationTransportError(error, options.signal, pendingRequestId !== undefined && this.storedPendingMutation(pendingRequestId) !== null
@@ -190,6 +186,15 @@ export class ConnectionTransport {
             }
             response = attempt.response;
         }
+        const retryBusy = (error) => retryExplicitConnectorBusy({
+            error,
+            attempt,
+            completedRetries: connectorBusyRetries,
+            signal: options.signal,
+            knownRejectedMutationRetry,
+            clearPending: (requestId) => this.clearPendingMutation(requestId),
+            retry: (pending, knownRejected) => this.performOperationWithinBudget(operation, input, options, pending, freshReadRetried, connectorBusyRetries + 1, knownRejected)
+        });
         let body;
         try {
             body = await decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned a response that is not valid JSON.");
@@ -201,6 +206,9 @@ export class ConnectionTransport {
         }
         if (!response.ok) {
             const error = apiError(body, "operation_failed", "Collection operation failed.", response.status);
+            const recovery = await retryBusy(error);
+            if (recovery.retried)
+                return recovery.result;
             if (error.code === "fresh_request_required"
                 && !attempt.pendingMutation
                 && !freshReadRetried) {
@@ -280,9 +288,13 @@ export class ConnectionTransport {
                     throw unknownMutationOutcome(attempt.requestId, new Error("Operation rejection did not contain a canonical problem."));
                 throw connectError("invalid_operation_response", "The collection authority returned an invalid operation problem.");
             }
+            const error = new MdbaseConnectError(body.problem);
+            const recovery = await retryBusy(error);
+            if (recovery.retried)
+                return recovery.result;
             if (attempt.pendingMutation)
                 this.clearPendingMutation(attempt.requestId);
-            throw new MdbaseConnectError(body.problem);
+            throw error;
         }
         if (body.ok !== true || !("result" in body)) {
             if (attempt.pendingMutation)
@@ -328,7 +340,7 @@ export class ConnectionTransport {
             }
         });
     }
-    async sendOperation(token, operation, input, tryDirect, options = {}, pendingRequestId) {
+    async sendOperation(token, operation, input, tryDirect, options = {}, pendingRequestId, knownRejectedMutationRetry = false) {
         let body = input ?? {};
         let encryptedRequest;
         let pendingMutation = false;
@@ -347,7 +359,7 @@ export class ConnectionTransport {
                     throw connectError("pending_mutation_unresolved", "A previous write still has an unknown outcome. Retry that exact write before making another change.");
                 }
                 requestId = pending.requestId;
-                resumingMutation = true;
+                resumingMutation = !knownRejectedMutationRetry;
             }
             pendingMutation = true;
         }
@@ -429,7 +441,8 @@ export class ConnectionTransport {
                     body: JSON.stringify(encryptedRequest),
                     signal: options.signal
                 }));
-                if (!directFallbackStatus(response.status)) {
+                if (!directFallbackStatus(response.status)
+                    || await isExplicitConnectorBusyResponse(response)) {
                     if (response.ok) {
                         this.markDirectAvailable();
                         this.setRoute("direct");
@@ -528,20 +541,9 @@ export class ConnectionTransport {
         };
     }
     directCapable(token) {
-        if (!token || token.authority || !token.encryption || !token.grantId || !token.keyHandle)
-            return false;
-        if (this.directAccessMode === "disabled")
-            return false;
-        if (typeof location !== "undefined"
-            && token.applicationOrigin
-            && token.applicationOrigin !== location.origin)
-            return false;
-        return true;
-    }
-    hasResumableMutationTransport() {
-        const token = this.currentToken();
-        return Boolean(token);
+        return tokenSupportsDirectAccess(token, this.directAccessMode);
     }
+    hasResumableMutationTransport() { return this.currentToken() !== null; }
     directEligible(token) {
         return token !== null
             && this.directCapable(token)
@@ -569,23 +571,9 @@ export class ConnectionTransport {
     }
     async probeDirectAccess(signal) {
         this.setDirectStatus("checking");
-        try {
-            const response = await fetch(`${this.loopbackUrl}/v1/ready`, loopbackRequest({
-                method: "GET",
-                cache: "no-store",
-                signal
-            }));
-            const body = await decodeJsonResponse(response, "invalid_operation_response", "The connector returned an invalid readiness response.").catch(() => null);
-            if (response.ok
-                && body?.service === "mdbase-connect"
-                && body?.loopback_protocol_version === 1
-                && body?.operation_transport_protocol_version === OPERATION_TRANSPORT_PROTOCOL_VERSION) {
-                this.markDirectAvailable();
-                return "available";
-            }
-        }
-        catch {
-            // Permission denial, unsupported mixed content, and an absent connector all reject fetch.
+        if (await probeLoopbackAccess(this.loopbackUrl, OPERATION_TRANSPORT_PROTOCOL_VERSION, signal)) {
+            this.markDirectAvailable();
+            return "available";
         }
         if ((await localNetworkPermission()) === "denied")
             return this.setDirectStatus("denied");
@@ -615,9 +603,7 @@ export class ConnectionTransport {
             this.emitConnection();
         }
     }
-    emitConnection() {
-        this.onChange();
-    }
+    emitConnection() { this.onChange(); }
     invalidateRejectedAuthorization(rejected) {
         const current = parseStored(this.storage.getItem(this.internals.tokenKey(this.collectionId)));
         if (!current || !sameAuthorization(current, rejected))

package/dist/direct-access.d.ts

@@ -0,0 +1,3 @@
+import type { StoredToken } from "./internal-types.js";
+export declare function tokenSupportsDirectAccess(token: StoredToken | null, mode: "auto" | "disabled"): boolean;
+export declare function probeLoopbackAccess(loopbackUrl: string, expectedOperationProtocol: number, signal?: AbortSignal): Promise<boolean>;

package/dist/direct-access.js

@@ -0,0 +1,29 @@
+import { loopbackRequest } from "./operation-helpers.js";
+import { decodeJsonResponse } from "./runtime-utils.js";
+export function tokenSupportsDirectAccess(token, mode) {
+    if (!token || token.authority || !token.encryption || !token.grantId || !token.keyHandle) {
+        return false;
+    }
+    if (mode === "disabled")
+        return false;
+    return typeof location === "undefined"
+        || !token.applicationOrigin
+        || token.applicationOrigin === location.origin;
+}
+export async function probeLoopbackAccess(loopbackUrl, expectedOperationProtocol, signal) {
+    try {
+        const response = await fetch(`${loopbackUrl}/v1/ready`, loopbackRequest({
+            method: "GET",
+            cache: "no-store",
+            signal
+        }));
+        const body = await decodeJsonResponse(response, "invalid_operation_response", "The connector returned an invalid readiness response.").catch(() => null);
+        return response.ok
+            && body?.service === "mdbase-connect"
+            && body?.loopback_protocol_version === 1
+            && body?.operation_transport_protocol_version === expectedOperationProtocol;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/file-transfer-internals.js

@@ -1,5 +1,6 @@
 import { MdbaseConnectError, connectError } from "./errors.js";
 import { IncrementalSha256 } from "./file-sha256.js";
+import { MAX_TRANSIENT_CHUNK_ATTEMPTS, waitForTransientChunkRetry } from "./transient-retry.js";
 const HASH_CHUNK_BYTES = 1024 * 1024;
 const DEFAULT_CONCURRENCY = 4;
 const MAX_CONCURRENCY = 8;
@@ -144,14 +145,17 @@ export function chunkLength(totalSize, partSize, index) {
     return Math.min(partSize, Math.max(0, totalSize - index * partSize));
 }
 export async function retryChunk(work, signal) {
-    for (let attempt = 1; attempt <= MAX_OBJECT_ATTEMPTS; attempt += 1) {
+    for (let attempt = 1; attempt <= MAX_TRANSIENT_CHUNK_ATTEMPTS; attempt += 1) {
         throwIfAborted(signal);
         try {
             return await work();
         }
         catch (error) {
-            if (signal?.aborted || attempt === MAX_OBJECT_ATTEMPTS)
+            if (signal?.aborted
+                || attempt === MAX_TRANSIENT_CHUNK_ATTEMPTS
+                || (error instanceof MdbaseConnectError && !error.retryable))
                 throw error;
+            await waitForTransientChunkRetry(attempt, signal);
         }
     }
     throw new Error("Unreachable file chunk retry state.");

package/dist/local-file-transport.js

@@ -4,6 +4,7 @@ import { MdbaseConnectError, connectError, serverConnectError } from "./errors.j
 import { GrantFileTransferCipher } from "./file-crypto.js";
 import { directFallbackStatus, loopbackRequest } from "./operation-helpers.js";
 import { apiError, decodeJsonResponse } from "./runtime-utils.js";
+import { isConnectorBusy, isExplicitConnectorBusyResponse, MAX_CONNECTOR_BUSY_RETRIES, waitForConnectorAvailability } from "./transient-retry.js";
 /** Keeps grant-bound file crypto and loopback framing out of the operation transport. */
 export class LocalFileTransport {
     options;
@@ -11,9 +12,9 @@ export class LocalFileTransport {
         this.options = options;
     }
     async control(token, method, path, input, signal) {
-        return this.controlAttempt(token, method, path, input, signal, false);
+        return this.controlAttempt(token, method, path, input, signal, false, 0);
     }
-    async controlAttempt(token, method, path, input, signal, freshReadRetried) {
+    async controlAttempt(token, method, path, input, signal, freshReadRetried, connectorBusyRetries) {
         requireEncryption(token);
         const controlInput = localFileControlInput(method, path, input);
         let encryptedRequest = await this.encryptControl(token, controlInput);
@@ -33,10 +34,11 @@ export class LocalFileTransport {
                     throw error;
                 this.options.onDirectUnavailable();
             }
-            if (response && !directFallbackStatus(response.status)) {
+            if (response && (!directFallbackStatus(response.status)
+                || await isExplicitConnectorBusyResponse(response))) {
                 if (response.ok)
                     this.options.onDirectAvailable();
-                return this.decryptControlResponse(token, method, path, input, signal, encryptedRequest, response, freshReadRetried);
+                return this.decryptControlResponse(token, method, path, input, signal, encryptedRequest, response, freshReadRetried, connectorBusyRetries);
             }
             if (response)
                 this.options.onDirectUnavailable();
@@ -57,16 +59,21 @@ export class LocalFileTransport {
         }
         if (response.ok)
             this.options.onRelayAvailable();
-        return this.decryptControlResponse(token, method, path, input, signal, encryptedRequest, response, freshReadRetried);
+        return this.decryptControlResponse(token, method, path, input, signal, encryptedRequest, response, freshReadRetried, connectorBusyRetries);
     }
-    async decryptControlResponse(token, method, path, input, signal, encryptedRequest, response, freshReadRetried) {
+    async decryptControlResponse(token, method, path, input, signal, encryptedRequest, response, freshReadRetried, connectorBusyRetries) {
         const body = await decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned an invalid file control response.");
         if (!response.ok) {
             const error = apiError(body, "operation_failed", "Collection file request failed.", response.status);
+            if (isConnectorBusy(error)
+                && connectorBusyRetries < MAX_CONNECTOR_BUSY_RETRIES) {
+                await waitForConnectorAvailability(connectorBusyRetries, signal);
+                return this.controlAttempt(token, method, path, input, signal, freshReadRetried, connectorBusyRetries + 1);
+            }
             if (error.code === "fresh_request_required"
                 && method === "GET"
                 && !freshReadRetried) {
-                return this.controlAttempt(token, method, path, input, signal, true);
+                return this.controlAttempt(token, method, path, input, signal, true, connectorBusyRetries);
             }
             throw error;
         }
@@ -79,10 +86,17 @@ export class LocalFileTransport {
             && decrypted.problem.code === "fresh_request_required"
             && method === "GET"
             && !freshReadRetried) {
-            return this.controlAttempt(token, method, path, input, signal, true);
+            return this.controlAttempt(token, method, path, input, signal, true, connectorBusyRetries);
+        }
+        if (!decrypted.ok) {
+            const error = encryptedProblem(decrypted.problem);
+            if (isConnectorBusy(error)
+                && connectorBusyRetries < MAX_CONNECTOR_BUSY_RETRIES) {
+                await waitForConnectorAvailability(connectorBusyRetries, signal);
+                return this.controlAttempt(token, method, path, input, signal, freshReadRetried, connectorBusyRetries + 1);
+            }
+            throw error;
         }
-        if (!decrypted.ok)
-            throwEncryptedProblem(decrypted.problem);
         return decrypted.result;
     }
     async uploadChunk(session, chunkIndex, bytes, signal) {
@@ -99,7 +113,8 @@ export class LocalFileTransport {
                     throw error;
                 this.options.onDirectUnavailable();
             }
-            if (response && !directFallbackStatus(response.status)) {
+            if (response && (!directFallbackStatus(response.status)
+                || await isExplicitConnectorBusyResponse(response))) {
                 if (response.ok)
                     this.options.onDirectAvailable();
                 return requireSuccessfulChunkResponse(response, "Encrypted file chunk upload failed.");
@@ -132,7 +147,8 @@ export class LocalFileTransport {
                     throw error;
                 this.options.onDirectUnavailable();
             }
-            if (response && !directFallbackStatus(response.status)) {
+            if (response && (!directFallbackStatus(response.status)
+                || await isExplicitConnectorBusyResponse(response))) {
                 if (response.ok)
                     this.options.onDirectAvailable();
                 return this.decryptDownloadResponse(token, session, chunkIndex, response);
@@ -313,8 +329,8 @@ function validateDownloadFrame(session, chunkIndex, encoded) {
         throw connectError("invalid_operation_response", "The connector returned a file frame for a different chunk.");
     }
 }
-function throwEncryptedProblem(problem) {
-    throw serverConnectError(problem.code === "unknown" ? problem.server_code : problem.code, problem.message, {
+function encryptedProblem(problem) {
+    return serverConnectError(problem.code === "unknown" ? problem.server_code : problem.code, problem.message, {
         details: problem.details,
         operationOutcome: problem.operation_outcome ?? "rejected",
         traceId: problem.trace_id

package/dist/transient-retry.d.ts

@@ -0,0 +1,22 @@
+import { MdbaseConnectError } from "./errors.js";
+import type { OperationAttempt, PendingMutation } from "./internal-types.js";
+export declare const MAX_CONNECTOR_BUSY_RETRIES = 8;
+export declare const MAX_TRANSIENT_CHUNK_ATTEMPTS = 10;
+export declare function isConnectorBusy(error: unknown): error is MdbaseConnectError;
+export declare function retryExplicitConnectorBusy<Result>(options: {
+    error: unknown;
+    attempt: OperationAttempt;
+    completedRetries: number;
+    signal?: AbortSignal;
+    knownRejectedMutationRetry: boolean;
+    clearPending(requestId: string): void;
+    retry(pending: PendingMutation | undefined, knownRejected: boolean): Promise<Result>;
+}): Promise<{
+    retried: false;
+} | {
+    retried: true;
+    result: Result;
+}>;
+export declare function isExplicitConnectorBusyResponse(response: Response): Promise<boolean>;
+export declare function waitForConnectorAvailability(retryIndex: number, signal?: AbortSignal): Promise<void>;
+export declare function waitForTransientChunkRetry(completedAttempt: number, signal?: AbortSignal): Promise<void>;

package/dist/transient-retry.js

@@ -0,0 +1,59 @@
+import { abortableDelay } from "./async.js";
+import { MdbaseConnectError, connectError } from "./errors.js";
+export const MAX_CONNECTOR_BUSY_RETRIES = 8;
+export const MAX_TRANSIENT_CHUNK_ATTEMPTS = 10;
+export function isConnectorBusy(error) {
+    return error instanceof MdbaseConnectError && error.code === "connector_busy";
+}
+export async function retryExplicitConnectorBusy(options) {
+    if (!isConnectorBusy(options.error)
+        || options.completedRetries >= MAX_CONNECTOR_BUSY_RETRIES) {
+        return { retried: false };
+    }
+    try {
+        await waitForConnectorAvailability(options.completedRetries, options.signal);
+    }
+    catch (error) {
+        if (options.attempt.pendingMutation
+            && (options.knownRejectedMutationRetry || !options.attempt.resumingMutation)) {
+            options.clearPending(options.attempt.requestId);
+        }
+        throw error;
+    }
+    return {
+        retried: true,
+        result: await options.retry(options.attempt.pendingMutationRecord, options.knownRejectedMutationRetry
+            || (options.attempt.pendingMutation === true && !options.attempt.resumingMutation))
+    };
+}
+export async function isExplicitConnectorBusyResponse(response) {
+    if (response.status !== 502 && response.status !== 503)
+        return false;
+    const body = await response.clone().json().catch(() => null);
+    return body?.error === "connector_busy"
+        || (typeof body?.error === "object"
+            && body.error?.code === "connector_busy");
+}
+export function waitForConnectorAvailability(retryIndex, signal) {
+    return retryDelay(jitteredBackoff(50, 800, retryIndex), signal);
+}
+export function waitForTransientChunkRetry(completedAttempt, signal) {
+    return retryDelay(jitteredBackoff(100, 1_000, completedAttempt - 1), signal);
+}
+async function retryDelay(milliseconds, signal) {
+    try {
+        await abortableDelay(milliseconds, signal);
+    }
+    catch (cause) {
+        if (signal?.aborted) {
+            if (signal.reason instanceof MdbaseConnectError)
+                throw signal.reason;
+            throw connectError("operation_cancelled", "The operation was cancelled while waiting for connector capacity.", { operationOutcome: "not_sent", cause });
+        }
+        throw cause;
+    }
+}
+function jitteredBackoff(base, cap, exponent) {
+    const bounded = Math.min(cap, base * (2 ** Math.max(0, exponent)));
+    return Math.max(1, Math.round(bounded * (0.75 + Math.random() * 0.5)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdbase-dev/connect",
-  "version": "0.1.0-beta.59",
+  "version": "0.1.0-beta.60",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mdbase-dev/connect-protocol": "0.1.0-beta.59"
+    "@mdbase-dev/connect-protocol": "0.1.0-beta.60"
   },
   "devDependencies": {
     "esbuild": "^0.28.1",