@ai-matrx/data 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.16.0
+
+- `MatrxFilesClient.healLoadError(ref, {src, attempts})` — the heal ladder
+  behind `@ai-matrx/media` 0.6's `MediaClient.healLoadError`: bearer byte
+  fetch on the primary files host, then on every other session base
+  (`FilesSession.bases()`), every attempt timed and recorded, root cause
+  named by `diagnoseHeal` (`files/heal.ts`). Never throws.
+- `FilesHealLane` / `FilesHealAttempt` / `FilesHealDiagnosis` /
+  `FilesHealResult` — structural twins of the media types.
+- `FilesSession.bases()` — the hosts the session lane mints on.
+
 ## 0.15.1
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/dist/files.cjs

@@ -347,12 +347,165 @@ function createFilesSession(options) {
       }
       return { secretSource, status };
     },
+    bases() {
+      return [...new Set(options.resolveBases())];
+    },
     reset() {
       stateByBase.clear();
     }
   };
 }
 
+// src/files/heal.ts
+function originOf(base) {
+  try {
+    return new URL(base).origin;
+  } catch {
+    return base;
+  }
+}
+async function runByteLane(lane, base, input) {
+  const now = input.now ?? Date.now;
+  const started = now();
+  const host = originOf(base);
+  if (!input.fileId) {
+    return {
+      attempt: {
+        lane,
+        outcome: "skipped",
+        ms: 0,
+        host,
+        detail: "no file id \u2014 the source is not one of our durable file URLs"
+      },
+      src: null
+    };
+  }
+  let response;
+  try {
+    response = await input.fetchBytes(base, input.fileId);
+  } catch (err) {
+    return {
+      attempt: {
+        lane,
+        outcome: "network-error",
+        ms: now() - started,
+        host,
+        detail: err instanceof Error ? err.message : String(err ?? "fetch failed")
+      },
+      src: null
+    };
+  }
+  if (!response.ok) {
+    return {
+      attempt: {
+        lane,
+        outcome: "http-error",
+        status: response.status,
+        ms: now() - started,
+        host,
+        detail: `GET /files/{id}/download \u2192 HTTP ${response.status}`
+      },
+      src: null
+    };
+  }
+  try {
+    const blob = await response.blob();
+    const src = input.cacheBlob(input.fileId, blob);
+    return {
+      attempt: {
+        lane,
+        outcome: "ok",
+        status: response.status,
+        ms: now() - started,
+        host,
+        detail: `${blob.size} bytes via bearer token \u2192 object URL`
+      },
+      src
+    };
+  } catch (err) {
+    return {
+      attempt: {
+        lane,
+        outcome: "network-error",
+        ms: now() - started,
+        host,
+        detail: `body read failed: ${err instanceof Error ? err.message : String(err)}`
+      },
+      src: null
+    };
+  }
+}
+function diagnoseHeal(attempts, mintStatus) {
+  const lane1 = attempts.find((a) => a.lane === "session-refresh-retry");
+  const bearer = attempts.find((a) => a.lane === "bearer-blob");
+  const alternate = attempts.find((a) => a.lane === "bearer-blob-alternate-host");
+  const healedBy = attempts.find((a) => a.outcome === "ok");
+  if (healedBy?.lane === "bearer-blob") {
+    if (lane1 && mintStatus === void 0) return "cookie-not-sent-by-browser";
+    if (mintStatus !== void 0) return "cookie-mint-failed";
+    return "unknown";
+  }
+  if (healedBy?.lane === "bearer-blob-alternate-host") {
+    if (bearer && (bearer.outcome === "network-error" || (bearer.status ?? 0) >= 500)) {
+      return "primary-host-down-alternate-served";
+    }
+    return "unknown";
+  }
+  const byteLanes = [bearer, alternate].filter(Boolean);
+  if (byteLanes.some((a) => a.status === 401)) return "bearer-rejected";
+  if (byteLanes.some((a) => a.status === 403)) return "access-denied";
+  if (byteLanes.some((a) => a.status === 404)) return "file-missing";
+  if (byteLanes.some((a) => (a.status ?? 0) >= 500)) return "files-host-error";
+  if (byteLanes.length > 0 && byteLanes.every((a) => a.outcome === "network-error")) {
+    return "files-host-unreachable";
+  }
+  if (mintStatus !== void 0) return "cookie-mint-failed";
+  return "unknown";
+}
+var SUMMARY = {
+  "cookie-not-sent-by-browser": "the files-session cookie was minted (200) but the browser did not send it back on the media element request \u2014 third-party cookies are blocked in this browser (Chrome setting / Incognito, Safari, Brave)",
+  "cookie-mint-failed": "the files-session cookie mint itself failed",
+  "bearer-rejected": "the bearer token was refused (401): the sign-in on this tab is stale",
+  "access-denied": "this identity may not read this file (403)",
+  "file-missing": "the file is gone (404)",
+  "files-host-error": "the files host answered with a server error (5xx)",
+  "files-host-unreachable": "no files host answered (network/DNS/CORS)",
+  "primary-host-down-alternate-served": "the primary files host did not serve the bytes; the alternate host did",
+  unknown: "the attempt pattern matches no known cause"
+};
+async function healLoadErrorLadder(input) {
+  const attempts = [...input.priorAttempts];
+  let src = null;
+  let healedBy;
+  const primary = await runByteLane("bearer-blob", input.primaryBase, input);
+  attempts.push(primary.attempt);
+  if (primary.src) {
+    src = primary.src;
+    healedBy = "bearer-blob";
+  } else {
+    for (const base of input.alternateBases) {
+      const alt = await runByteLane("bearer-blob-alternate-host", base, input);
+      attempts.push(alt.attempt);
+      if (alt.src) {
+        src = alt.src;
+        healedBy = "bearer-blob-alternate-host";
+        break;
+      }
+    }
+  }
+  const diagnosis = diagnoseHeal(attempts, input.mintStatus);
+  const cause = SUMMARY[diagnosis];
+  const served = healedBy ? `served via ${healedBy} in ${attempts.find((a) => a.outcome === "ok")?.ms ?? 0}ms` : `every lane died (${attempts.map((a) => `${a.lane}:${a.outcome}${a.status ? ` ${a.status}` : ""}`).join(", ")})`;
+  const ifMint = input.mintStatus !== void 0 ? ` (last cookie mint status ${input.mintStatus})` : "";
+  return {
+    src,
+    healedBy,
+    attempts,
+    diagnosis,
+    summary: `${cause}${ifMint}; ${served}`
+  };
+}
+
 // src/files/client.ts
 var TUS_TRANSPORT_THRESHOLD_BYTES = 80 * 1024 * 1024;
 function resolveUploadTransport(fileSizeBytes, override) {
@@ -904,6 +1057,28 @@ function createMatrxFilesClient(config) {
       await session.ensure({ force: true });
       return finish("retry");
     },
+    async healLoadError(ref, context) {
+      const norm = normalizeRef(ref);
+      const fileId = norm?.kind === "file_id" ? norm.fileId : norm?.kind === "url" ? recognizer.fileIdFromFileEndpointUrl(norm.url) : null;
+      const primary = filesBase();
+      return healLoadErrorLadder({
+        fileId,
+        priorAttempts: context.attempts,
+        primaryBase: primary,
+        alternateBases: session.bases().filter((b) => b !== primary),
+        mintStatus: session.snapshot().status,
+        fetchBytes: async (base, id) => {
+          const headers = await authHeaders();
+          return fetchImpl(fileUrls(base, id).download, { headers });
+        },
+        cacheBlob: (id, blob) => {
+          const already = blobCache.get(id);
+          const objectUrl = already?.url ?? URL.createObjectURL(blob);
+          if (!already) blobCache.set(id, blob, objectUrl, { mimeType: blob.type });
+          return objectUrl;
+        }
+      });
+    },
     async recoverBlobLoadError(ref, attempt) {
       if (attempt > 1) return "terminal";
       const norm = normalizeRef(ref);