@relayfile/sdk 0.10.50 → 0.10.52

package/dist/client.d.ts

@@ -178,6 +178,13 @@ export declare class RelayFileClient {
     private shouldRetryStatus;
     private shouldRetryError;
     private computeRetryDelayMs;
+    /**
+     * Extract a server-advertised retry delay from a parsed 429 error body.
+     * Relayfile advertises backpressure delays as `details.retryAfterSeconds`
+     * (in seconds) on `workspace_busy` / `queue_full` responses. Returns
+     * milliseconds, or null when absent/malformed.
+     */
+    private parseRetryAfterSecondsFromBody;
     private parseRetryAfterMs;
     private sleep;
     private readPayload;

package/dist/client.js

@@ -8,6 +8,15 @@ const DEFAULT_RETRY_OPTIONS = {
     maxDelayMs: 2000,
     jitterRatio: 0.2
 };
+/**
+ * Hard ceiling for a *server-advertised* retry delay (a 429 body's
+ * `details.retryAfterSeconds`). `maxDelayMs` bounds our OWN exponential
+ * backoff; an explicit server instruction ("retry after N seconds") is honored
+ * above that cap — truncating it just retries into the same overloaded resource
+ * and burns the retry budget — but is still bounded here so a pathological or
+ * hostile value cannot stall the client indefinitely.
+ */
+const RETRY_AFTER_MAX_MS = 30_000;
 const DEFAULT_CHANGE_COALESCE_MS = 200;
 const DEFAULT_CHANGE_LOG_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 const DEFAULT_CHANGE_LOG_MAX_ENTRIES = 10_000;
@@ -75,6 +84,25 @@ function getFileReadCache(client) {
         return cached;
     return false;
 }
+async function withFileReadCacheInvalidated(client, workspaceId, paths, attempt) {
+    const cache = getFileReadCache(client);
+    if (cache === false)
+        return attempt();
+    const evict = () => {
+        for (const path of paths) {
+            cache.evict(workspaceId, path);
+        }
+    };
+    // The attempt itself invalidates our knowledge, before its outcome is known.
+    evict();
+    try {
+        return await attempt();
+    }
+    finally {
+        // A concurrent read can repopulate while the request is in flight.
+        evict();
+    }
+}
 function initFileReadCache(client, options) {
     if (options.readCache === false) {
         fileReadCaches.set(client, false);
@@ -236,7 +264,9 @@ class RelayFileWebSocketConnection {
             }
         });
         socket.addEventListener("error", (event) => {
-            const errorEvent = event instanceof ErrorEvent && event.error instanceof Error ? event.error : event;
+            const errorEvent = typeof ErrorEvent !== "undefined" && event instanceof ErrorEvent && event.error instanceof Error
+                ? event.error
+                : event;
             for (const handler of this.handlers.error) {
                 handler(errorEvent);
             }
@@ -758,7 +788,14 @@ function getWorkspaceIdFromToken(token) {
     }
     try {
         const parsed = JSON.parse(decodeBase64Url(parts[1] ?? ""));
-        return typeof parsed.workspace_id === "string" && parsed.workspace_id.length > 0 ? parsed.workspace_id : undefined;
+        // Prefer the canonical `workspace_id` claim; fall back to the `wks` claim
+        // minted delegated tokens (relay_pa_*) actually carry, then `workspace`.
+        for (const candidate of [parsed.workspace_id, parsed.wks, parsed.workspace]) {
+            if (typeof candidate === "string" && candidate.length > 0) {
+                return candidate;
+            }
+        }
+        return undefined;
     }
     catch {
         return undefined;
@@ -771,7 +808,15 @@ function getAgentIdFromToken(token) {
     }
     try {
         const parsed = JSON.parse(decodeBase64Url(parts[1] ?? ""));
-        return typeof parsed.agent_name === "string" && parsed.agent_name.length > 0 ? parsed.agent_name : undefined;
+        if (typeof parsed.agent_name === "string" && parsed.agent_name.length > 0) {
+            return parsed.agent_name;
+        }
+        // Minted delegated tokens omit `agent_name` and carry the agent as the JWT
+        // subject, e.g. sub: "agent_gil-ramp-bookkeeper".
+        if (typeof parsed.sub === "string" && parsed.sub.startsWith("agent_") && parsed.sub.length > "agent_".length) {
+            return parsed.sub.slice("agent_".length);
+        }
+        return undefined;
     }
     catch {
         return undefined;
@@ -1248,7 +1293,7 @@ export class RelayFileClient {
     async writeFile(input) {
         const { workspaceId, path, correlationId, baseRevision, content, contentType, encoding, contentIdentity, signal } = input;
         const query = buildQuery({ path, forkId: input.forkId });
-        const result = await this.request({
+        return withFileReadCacheInvalidated(this, workspaceId, [path], () => this.request({
             method: "PUT",
             path: `/v1/workspaces/${encodeURIComponent(workspaceId)}/fs/file${query}`,
             correlationId,
@@ -1264,15 +1309,11 @@ export class RelayFileClient {
                 ...(contentIdentity ? { contentIdentity } : {})
             },
             signal
-        });
-        const cache = getFileReadCache(this);
-        if (cache !== false)
-            cache.evict(workspaceId, path);
-        return result;
+        }));
     }
     async mergeFile(input) {
         const query = buildQuery({ path: input.path });
-        const result = await this.request({
+        return withFileReadCacheInvalidated(this, input.workspaceId, [input.path], () => this.request({
             method: "POST",
             path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/fs/merge${query}`,
             correlationId: input.correlationId,
@@ -1291,31 +1332,22 @@ export class RelayFileClient {
                 contentIdentity: input.contentIdentity
             },
             signal: input.signal
-        });
-        const cache = getFileReadCache(this);
-        if (cache !== false)
-            cache.evict(input.workspaceId, input.path);
-        return result;
+        }));
     }
     async bulkWrite(input) {
         const query = buildQuery({ forkId: input.forkId });
-        const response = await this.performRequest({
-            method: "POST",
-            path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/fs/bulk${query}`,
-            correlationId: input.correlationId,
-            body: {
-                files: input.files
-            },
-            signal: input.signal
+        return withFileReadCacheInvalidated(this, input.workspaceId, input.files.map((file) => file.path), async () => {
+            const response = await this.performRequest({
+                method: "POST",
+                path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/fs/bulk${query}`,
+                correlationId: input.correlationId,
+                body: {
+                    files: input.files
+                },
+                signal: input.signal
+            });
+            return await this.readPayload(response);
         });
-        const result = await this.readPayload(response);
-        const cache = getFileReadCache(this);
-        if (cache !== false) {
-            for (const file of input.files) {
-                cache.evict(input.workspaceId, file.path);
-            }
-        }
-        return result;
     }
     async issueCheckpointSeal(input) {
         return this.request({
@@ -1420,7 +1452,7 @@ export class RelayFileClient {
     }
     async deleteFile(input) {
         const query = buildQuery({ path: input.path, forkId: input.forkId });
-        const result = await this.request({
+        return withFileReadCacheInvalidated(this, input.workspaceId, [input.path], () => this.request({
             method: "DELETE",
             path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/fs/file${query}`,
             correlationId: input.correlationId,
@@ -1428,11 +1460,7 @@ export class RelayFileClient {
                 "If-Match": input.baseRevision
             },
             signal: input.signal
-        });
-        const cache = getFileReadCache(this);
-        if (cache !== false)
-            cache.evict(input.workspaceId, input.path);
-        return result;
+        }));
     }
     async createFork(input) {
         const body = {
@@ -2175,7 +2203,11 @@ export class RelayFileClient {
             const payload = await this.readPayload(response);
             if (this.shouldRetryStatus(response.status, retries, params.signal)) {
                 retries += 1;
-                await this.sleep(this.computeRetryDelayMs(retries, response.headers.get("retry-after")), params.signal);
+                await this.sleep(this.computeRetryDelayMs(retries, response.headers.get("retry-after"), 
+                // `details.retryAfterSeconds` is a 429-only backpressure signal
+                // (`workspace_busy` / `queue_full`). Only consult the body on a 429
+                // so a 5xx body can never bypass `maxDelayMs` via this path.
+                response.status === 429 ? payload : undefined), params.signal);
                 continue;
             }
             this.throwForError(response.status, payload, response.headers);
@@ -2199,17 +2231,53 @@ export class RelayFileClient {
         }
         return retries < this.retryOptions.maxRetries;
     }
-    computeRetryDelayMs(retryAttempt, retryAfterHeader) {
+    computeRetryDelayMs(retryAttempt, retryAfterHeader, payload) {
+        // A server-advertised `Retry-After` HEADER is the standard, explicit
+        // signal and takes precedence: parse it first and leave its handling
+        // unchanged (bounded by our own `maxDelayMs`). Only when the header is
+        // absent or unparseable do we consult the body below, so a body hint never
+        // silently overrides a shorter, explicit header the server already sent.
         const retryAfterMs = this.parseRetryAfterMs(retryAfterHeader);
         if (retryAfterMs !== null) {
             return Math.min(this.retryOptions.maxDelayMs, retryAfterMs);
         }
+        // With no usable header, a 429 body can still advertise an explicit
+        // backpressure delay as `details.retryAfterSeconds` (e.g. `workspace_busy`
+        // when the workspace durable object is overloaded, or `queue_full`). Honor
+        // it as an instruction, bounded only by RETRY_AFTER_MAX_MS — NOT truncated
+        // to `maxDelayMs`, which governs our own exponential backoff. Truncating it
+        // (maxDelayMs defaults to 2s vs. a typical 5s advertised delay) retries
+        // into the still-busy resource and exhausts the retry budget.
+        const advertisedMs = this.parseRetryAfterSecondsFromBody(payload);
+        if (advertisedMs !== null) {
+            return Math.max(0, Math.min(RETRY_AFTER_MAX_MS, advertisedMs));
+        }
         const backoff = this.retryOptions.baseDelayMs * Math.pow(2, Math.max(0, retryAttempt - 1));
         const capped = Math.min(this.retryOptions.maxDelayMs, backoff);
         const jitter = this.retryOptions.jitterRatio;
         const factor = 1 + (Math.random() * 2 - 1) * jitter;
         return Math.max(0, Math.round(capped * factor));
     }
+    /**
+     * Extract a server-advertised retry delay from a parsed 429 error body.
+     * Relayfile advertises backpressure delays as `details.retryAfterSeconds`
+     * (in seconds) on `workspace_busy` / `queue_full` responses. Returns
+     * milliseconds, or null when absent/malformed.
+     */
+    parseRetryAfterSecondsFromBody(payload) {
+        if (!payload || typeof payload !== "object") {
+            return null;
+        }
+        const details = payload.details;
+        if (!details || typeof details !== "object") {
+            return null;
+        }
+        const seconds = details.retryAfterSeconds;
+        if (typeof seconds === "number" && Number.isFinite(seconds) && seconds >= 0) {
+            return seconds * 1000;
+        }
+        return null;
+    }
     parseRetryAfterMs(retryAfterHeader) {
         if (!retryAfterHeader) {
             return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.10.50",
+  "version": "0.10.52",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -59,15 +59,15 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.10.50",
+    "@relayfile/core": "0.10.52",
     "ignore": "^7.0.5",
     "tar": "^7.5.10"
   },
   "optionalDependencies": {
-    "@relayfile/mount-darwin-arm64": "0.10.50",
-    "@relayfile/mount-darwin-x64": "0.10.50",
-    "@relayfile/mount-linux-arm64": "0.10.50",
-    "@relayfile/mount-linux-x64": "0.10.50"
+    "@relayfile/mount-darwin-arm64": "0.10.52",
+    "@relayfile/mount-darwin-x64": "0.10.52",
+    "@relayfile/mount-linux-arm64": "0.10.52",
+    "@relayfile/mount-linux-x64": "0.10.52"
   },
   "devDependencies": {
     "typescript": "^5.7.3",