@zackbart/connecta 0.41.0 → 0.42.0

package/dist/catalog-cache.js

@@ -238,6 +238,21 @@ export function observeCatalogExpiry(ctx, method, ttlMs, expiresAt, staleFallbac
 // failure for five minutes. Resources never use stale inventories. A fallback
 // carries its original expired deadline and cannot authorize auth recovery.
 const STALE_FALLBACK_MS = 300_000;
+/**
+ * How long past its expiry a complete tool catalog stays listable when its
+ * connector does not answer discovery in time. The listing only: a call always
+ * resolves through STALE_FALLBACK_MS at most. One day matches the longest TTL a
+ * deployment can configure, so this retains nothing it could not already hold.
+ * A refusal retires it sooner, for that credential: see `fenceTools`.
+ */
+const STALE_DISCOVERY_MS = 86_400_000;
+/** A fence outlives every entry it could be keeping from reuse. */
+const CATALOG_FENCE_TTL_SECONDS = (MAX_CACHE_TTL_MS + STALE_DISCOVERY_MS) / 1000;
+/** What a refusal's fence is keyed by, beside the catalog: one credential's slot within one generation. */
+const catalogFenceFingerprint = (sharing, partition, authPartition, credentialIdentity) => authCall(fingerprintSerializedCatalog, [
+    // A shared credential gets one answer whoever asks, so one fence covers all its callers.
+    JSON.stringify(["fence", sharing === "shared" ? authPartition : partition, credentialIdentity ?? null]),
+]);
 /** Catalog chunks one storage read fetches together. */
 const CHUNKS_PER_READ = 8;
 export function attachCatalogCache(ctx, value) {
@@ -475,7 +490,9 @@ const catalogLocation = authMethod((ctx, config, authPartition) => authFlow(func
 export const prefetchCatalog = authMethod((ctx, connectorId, config, authPartition, sharing, credentialIdentity, negotiationKey) => authFlow(function* () {
     const { partition, sharedPartition, configHash } = yield authCall(catalogLocation, [ctx, config, authPartition]);
     const slots = sharing === "shared" ? [partition, sharedPartition] : [partition];
-    const suffixes = [];
+    const suffixes = [
+        (yield catalogFenceFingerprint(sharing, partition, authPartition, credentialIdentity)).fingerprint,
+    ];
     for (const slot of slots)
         suffixes.push((yield authCall(fingerprintSerializedCatalog, [
             JSON.stringify(["tools/list", slot, credentialIdentity ?? null]),
@@ -624,6 +641,58 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
         ])).fingerprint;
         return stopped() ? undefined : responseCacheKeys.entry(prefix, digest);
     }));
+    const fenceKey = cacheMethod((operation, generation) => authFlow(function* () {
+        const { fingerprint } = (yield catalogFenceFingerprint(sharing, partition, authPartition, operation.credentialIdentity));
+        return responseCacheKeys.entry(responseCacheKeys.namespace(connectorId, configHash, generation), fingerprint);
+    }));
+    // Whether an expired catalog may stand in now. Read past this request's
+    // memo: a refusal or invalidation in another isolate retires it at once.
+    const staleAllowed = cacheMethod((operation) => authFlow(function* () {
+        if (operation.stopped() || !(yield authCall(namespace, [operation])))
+            return false;
+        const key = (yield authCall(fenceKey, [operation, operation.generation.value]));
+        const fence = (yield authCall(operation.io, [
+            cacheMethod(() => reads.read(storage, key, authStorage(storage, "get", [key]), true)),
+        ]));
+        return fence === null && !operation.stopped();
+    }));
+    // Read before the listing dispatches: a refusal after this point writes a
+    // value this listing never saw. An older memoized read only lifts less.
+    const readListingFence = cacheMethod((operation) => authFlow(function* () {
+        const { listing, stopped, io } = operation;
+        if (!listing || listing.fence !== undefined || stopped())
+            return;
+        // A generation claimed later holds no fence this listing could know of.
+        if (!listing.generationStored) {
+            listing.fence = null;
+            return;
+        }
+        const key = (yield authCall(fenceKey, [operation, listing.generation.value]));
+        listing.fence = (yield authCall(io, [
+            cacheMethod(() => reads.read(storage, key, authStorage(storage, "get", [key]))),
+        ]));
+    }));
+    // A complete listing's answer lifts the fence captured before it was
+    // asked, and only that one: a refusal that landed while it ran wrote
+    // another, which stays. With nothing captured it lifts nothing, so the
+    // next listing that reads the fence first does it instead.
+    const liftFence = cacheMethod((operation) => authFlow(function* () {
+        const { listing, stopped, io } = operation;
+        if (!listing?.fence || stopped())
+            return;
+        try {
+            const key = (yield authCall(fenceKey, [operation, operation.generation.value]));
+            const lifted = (yield authCall(io, [
+                cacheMethod(() => authStorage(storage, "compareAndSet", [key, listing.fence, null])),
+            ]));
+            if (lifted)
+                listing.fence = null;
+        }
+        catch (error) {
+            if (!stopped())
+                logFailure(ctx.logger, "catalog fence failed", failureRecord({ connector: connectorId }, error));
+        }
+    }));
     const manifest = (raw) => {
         if (!raw)
             return undefined;
@@ -721,13 +790,18 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                     ]));
                     roots.push(responseCacheKeys.entry(responseCacheKeys.namespace(connectorId, configHash, operation.generation.value), fingerprint));
                 }
-                yield reads.prefetch(roots.map((key) => ({ storage, key })), (storage, keys) => authStorageMany(storage, keys));
+                const fence = (yield authCall(fenceKey, [operation, operation.generation.value]));
+                yield reads.prefetch([...roots, fence].map((key) => ({ storage, key })), (storage, keys) => authStorageMany(storage, keys));
+                (yield authCall(readListingFence, [operation]));
                 const values = [];
                 for (const root of roots)
                     values.push(yield reads.read(storage, root, authStorage(storage, "get", [root])));
                 listing.manifests ??= new Map();
                 roots.forEach((root, i) => listing.manifests.set(root, values[i] ?? null));
             }
+            // A refused credential is listed anew, whatever its catalog's age.
+            if (listing?.fence && key.method === "tools/list")
+                return undefined;
             const m = manifest(listing?.manifests?.has(root)
                 ? listing.manifests.get(root)
                 : (yield authCall(io, [
@@ -736,7 +810,7 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             if (stopped() ||
                 !m ||
                 (m.expiresAt <= Date.now() &&
-                    (key.method !== "tools/list" || m.expiresAt + STALE_FALLBACK_MS <= Date.now())))
+                    (key.method !== "tools/list" || m.expiresAt + STALE_DISCOVERY_MS <= Date.now())))
                 return undefined;
             // Up to CHUNKS_PER_READ chunks per round trip, so one answer stays a
             // few megabytes; the generation fence below still decides whether
@@ -814,6 +888,8 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                     (yield authCall(io, [
                         cacheMethod(() => authStorage(storage, "delete", [root])),
                     ]));
+                if (method === "tools/list")
+                    (yield authCall(liftFence, [operation]));
                 return 0;
             }
             if (!Array.isArray(catalogItems(method, result)) ||
@@ -833,7 +909,7 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
             let offset = 0;
             let chunkCount = 0;
-            const ttlSeconds = () => Math.max(0.001, (expiresAt + (method === "tools/list" ? STALE_FALLBACK_MS : 0) - Date.now()) / 1000);
+            const ttlSeconds = () => Math.max(0.001, (expiresAt + (method === "tools/list" ? STALE_DISCOVERY_MS : 0) - Date.now()) / 1000);
             while (offset < bytes.length) {
                 if (stopped() || expiresAt <= Date.now())
                     return 0;
@@ -885,6 +961,27 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                     return 0;
                 if (published) {
                     lastStamp = stamp;
+                    // Tool chunks outlive their manifest by the stale limit, so a
+                    // superseded revision is removed now rather than retained for
+                    // a day. A reader holding it misses and lists again; a failed
+                    // removal leaves the chunks to their TTL.
+                    const superseded = manifest(previous);
+                    if (superseded && superseded.revision !== revision) {
+                        try {
+                            for (let index = 0; index < superseded.chunkCount && !stopped(); index++)
+                                (yield authCall(io, [
+                                    cacheMethod(() => authStorage(storage, "delete", [
+                                        responseCacheKeys.chunk(root, superseded.revision, index),
+                                    ])),
+                                ]));
+                        }
+                        catch (error) {
+                            if (!stopped())
+                                logFailure(ctx.logger, "catalog chunk cleanup failed", failureRecord({ connector: connectorId }, error));
+                        }
+                    }
+                    if (method === "tools/list")
+                        (yield authCall(liftFence, [operation]));
                     return stamp;
                 }
             }
@@ -930,7 +1027,7 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
     // The queue retains only a Promise turn. Awaiting it in this caller's
     // request preserves workerd I/O ownership; the listing program stays native.
     let tail = Promise.resolve();
-    const withListing = cacheMethod((listingCtx, read) => authFlow(function* () {
+    const withListing = cacheMethod((listingCtx, read, bound) => authFlow(function* () {
         const previous = tail;
         let release;
         tail = new Promise((resolve) => {
@@ -951,9 +1048,17 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             staleTools = undefined;
             const operation = capture();
             try {
-                if (resolveCredentialIdentity)
+                if (bound && "credentialIdentity" in bound)
+                    listing.credentialIdentity = bound.credentialIdentity;
+                else if (resolveCredentialIdentity)
                     listing.credentialIdentity = yield authInvoke(operation, "io", [resolveCredentialIdentity]);
-                if (!operation.stopped()) {
+                if (bound?.fence !== undefined)
+                    listing.fence = bound.fence;
+                if (bound?.generationStored !== undefined) {
+                    listing.generationStored = bound.generationStored;
+                    listing.generation.value = bound.generation;
+                }
+                else if (!operation.stopped()) {
                     try {
                         // Memoized: it locates the listing's entries, which the
                         // fresh fence in get accepts or refuses.
@@ -989,6 +1094,24 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                 void previous.then(release);
         }
     }));
+    // Capture what an attempt is about to run under. `pinned` names a
+    // credential the caller has already read for it.
+    const bindListing = cacheMethod((listingCtx, pinned, readFence = false) => authCall(withListing, [
+        listingCtx,
+        cacheMethod(() => authFlow(function* () {
+            const operation = capture();
+            if (readFence)
+                (yield authCall(readListingFence, [operation]));
+            const listing = operation.listing;
+            return {
+                credentialIdentity: listing.credentialIdentity,
+                generation: listing.generation.value,
+                generationStored: listing.generationStored ?? false,
+                fence: listing.fence,
+            };
+        })),
+        pinned,
+    ]));
     // A complete, unexpired tools/list entry, read before any connection
     // exists. This is the SDK's own two-probe read: the private slot
     // `[serverIdentity, cachePartition]`, then a shared connector's public
@@ -1017,12 +1140,101 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             return Array.isArray(result.tools) ? result : undefined;
         })),
     ]));
+    // The newest complete tools/list entry this caller could be served, fresh
+    // or within STALE_DISCOVERY_MS of expiry, with its original times. Reads
+    // only, through the same address, fingerprint, generation and credential
+    // fences as a listing, so another owner's entry, an invalidated generation
+    // or a rotated credential is a miss. Never a source for call resolution.
+    const peekTools = cacheMethod((listingCtx, serverIdentity = "") => authCall(withListing, [
+        listingCtx,
+        cacheMethod(() => authFlow(function* () {
+            if (!active?.generationStored)
+                return undefined;
+            const read = (slot) => authInvoke(store, "get", [
+                { method: "tools/list", params: "", partition: JSON.stringify([serverIdentity, slot]) },
+            ]);
+            let entry = (yield read(partition));
+            let stale = staleTools;
+            if (entry === undefined && sharing === "shared") {
+                staleTools = undefined;
+                const shared = (yield read(""));
+                entry = shared?.scope === "public" ? shared : undefined;
+                // Set by the read above, which control flow analysis cannot see.
+                const sharedStale = staleTools;
+                if (sharedStale?.manifest.scope === "public" &&
+                    (!stale || stale.manifest.fetchedAt < sharedStale.manifest.fetchedAt))
+                    stale = sharedStale;
+            }
+            if (entry?.expiresAt !== undefined && entry.expiresAt > Date.now()) {
+                const result = JSON.parse(entry.value);
+                if (!Array.isArray(result.tools))
+                    return undefined;
+                return {
+                    result,
+                    fetchedAt: catalogFetchedAt(listingCtx) ?? Date.now(),
+                    expiresAt: entry.expiresAt,
+                };
+            }
+            const operation = capture();
+            if (!stale ||
+                !(yield authCall(staleAllowed, [operation])) ||
+                stale.manifest.expiresAt + STALE_DISCOVERY_MS <= Date.now())
+                return undefined;
+            return { result: stale.result, fetchedAt: stale.manifest.fetchedAt, expiresAt: stale.manifest.expiresAt };
+        })),
+    ]));
+    // The downstream refused this credential, which says more than a TTL can:
+    // nothing cached for it may stand in again until a listing succeeds. One
+    // key beside the catalog, durable across requests and isolates, in the
+    // namespace of the generation the refused attempt ran under, so a change
+    // of credential or a disconnect discards it with the entries it guards. An
+    // attempt that found no generation fences the one claimed since, if any:
+    // that is where a listing beside it published. Nothing is stored while no
+    // generation is, since then nothing is cached to retire. A failed write is
+    // logged and never masks the refusal.
+    const writeFence = cacheMethod((operation) => authFlow(function* () {
+        const { listing, stopped, io } = operation;
+        if (!listing || stopped())
+            return;
+        try {
+            const generation = listing.generationStored
+                ? listing.generation.value
+                : (yield authCall(io, [cacheMethod(() => generationRead(false))]));
+            if (!generation || stopped())
+                return;
+            const key = (yield authCall(fenceKey, [operation, generation]));
+            (yield authCall(io, [
+                cacheMethod(() => authStorage(storage, "set", [
+                    key,
+                    crypto.randomUUID(),
+                    { ttlSeconds: CATALOG_FENCE_TTL_SECONDS },
+                ])),
+            ]));
+        }
+        catch (error) {
+            if (!stopped())
+                logFailure(ctx.logger, "catalog fence failed", failureRecord({ connector: connectorId }, error));
+        }
+    }));
+    // The refusal of the listing now running, as that listing was bound.
+    const fenceListing = cacheMethod(() => authCall(writeFence, [capture()]));
+    // The refusal of an attempt bound earlier, outside any listing.
+    const fenceTools = cacheMethod((listingCtx, bound) => authCall(withListing, [listingCtx, cacheMethod(() => authCall(writeFence, [capture()])), bound]));
+    // For a listing that never reads the cache before it dispatches.
+    const captureFence = cacheMethod(() => authFlow(function* () {
+        const operation = capture();
+        try {
+            (yield authCall(readListingFence, [operation]));
+        }
+        catch (error) {
+            if (!operation.stopped())
+                logFailure(ctx.logger, "catalog fence failed", failureRecord({ connector: connectorId }, error));
+        }
+    }));
     const fallbackTools = cacheMethod(() => authFlow(function* () {
         const operation = capture();
         if (!staleTools ||
-            operation.stopped() ||
-            !(yield authCall(namespace, [operation])) ||
-            operation.stopped() ||
+            !(yield authCall(staleAllowed, [operation])) ||
             staleTools.manifest.expiresAt + STALE_FALLBACK_MS <= Date.now())
             return;
         const { result, manifest } = staleTools;
@@ -1035,6 +1247,11 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
         completeCatalogRefresh,
         fallbackTools,
         cachedTools,
+        peekTools,
+        bindListing,
+        captureFence,
+        fenceListing,
+        fenceTools,
         responseCacheStore: store,
         cachePartition: partition,
         defaultCacheTtlMs: policy?.defaultTtlMs ?? CONFIG_DEFAULTS.discovery.catalogTtlSeconds * 1000,
@@ -1046,36 +1263,54 @@ function isCatalogMethod(method) {
     return method === "tools/list" || method === "resources/list" || method === "resources/templates/list";
 }
 function customCatalogCache(ctx, connectorId) {
-    return runEdge(authProgram(customCatalogCacheNative, [
-        ctx,
-        connectorId,
-    ]));
+    return runEdge(authProgram(customCatalogCacheNative, [ctx, connectorId]));
 }
-const customCatalogCacheNative = /* @__PURE__ */ registerAuth(customCatalogCache, (ctx, connectorId) => authFlow(function* () {
+const customCatalogAuth = authMethod((ctx) => authFlow(function* () {
     const credential = (yield authValue(() => ctx.credential?.getAll()));
     // Credential values enter the stored partition only through a keyed digest.
-    const auth = credential == null
+    return credential == null
         ? (yield authCall(fingerprintSerializedCatalog, ["null"])).fingerprint
         : (yield authCall(secretDigest, [ctx, JSON.stringify(credential)]));
+}));
+const customCatalogCacheNative = /* @__PURE__ */ registerAuth(customCatalogCache, (ctx, connectorId) => authFlow(function* () {
+    const auth = (yield authCall(customCatalogAuth, [ctx]));
     const cache = (yield authCall(catalogClientOptions, [ctx, connectorId, "custom-connector", auth]));
     const key = {
         method: "tools/list",
         partition: JSON.stringify(["custom-connector", cache.cachePartition]),
     };
-    return { cache, key };
+    return { cache, key, auth };
+}));
+/**
+ * Before a custom listing dispatches: only an authenticated owner may retain a
+ * complete private fallback, and unscoped/operator reads start no cache I/O.
+ * Its answer is recorded against this ticket, never a later read of the store.
+ */
+export function bindCustomCatalogListing(ctx, connectorId) {
+    return runEdge(authProgram(bindCustomCatalogListingNative, [ctx, connectorId]));
+}
+const bindCustomCatalogListingNative = /* @__PURE__ */ registerAuth(bindCustomCatalogListing, (ctx, connectorId) => authFlow(function* () {
+    if (!catalogTtlMs(ctx, undefined) || !callerOf(ctx)?.authenticated)
+        return;
+    const custom = (yield authCall(customCatalogCache, [ctx, connectorId]));
+    const bound = (yield authInvoke(custom.cache, "bindListing", [ctx, undefined, true]));
+    return { ...custom, bound };
 }));
-/** Custom listings always fetch. Only an authenticated owner may retain a
- * complete private fallback; unscoped/operator reads start no cache I/O. */
-export function storeCustomCatalogFallback(ctx, connectorId, tools) {
-    return runEdge(authProgram(storeCustomCatalogFallbackNative, [ctx, connectorId, tools]));
+/** Custom listings always fetch; the ticket says whether and where one is retained. */
+export function storeCustomCatalogFallback(ctx, tools, listing) {
+    return runEdge(authProgram(storeCustomCatalogFallbackNative, [ctx, tools, listing]));
 }
-const storeCustomCatalogFallbackNative = /* @__PURE__ */ registerAuth(storeCustomCatalogFallback, (ctx, connectorId, tools) => authFlow(function* () {
+const storeCustomCatalogFallbackNative = /* @__PURE__ */ registerAuth(storeCustomCatalogFallback, (ctx, tools, listing) => authFlow(function* () {
     const ttlMs = catalogTtlMs(ctx, undefined);
     observeCatalogFetch(ctx, Date.now());
     observeCatalogExpiry(ctx, "tools/list", ttlMs);
-    if (!ttlMs || !callerOf(ctx)?.authenticated)
+    if (!ttlMs || !listing)
         return;
-    const { cache, key } = (yield authCall(customCatalogCache, [ctx, connectorId]));
+    // The connector read its own credential, so a change while it ran leaves
+    // this answer belonging to neither: it is retained for neither.
+    if ((yield authCall(customCatalogAuth, [ctx])) !== listing.auth)
+        return;
+    const { cache, key, bound } = listing;
     (yield authInvoke(cache, "withListing", [
         ctx,
         authMethod(() => authFlow(function* () {
@@ -1096,8 +1331,41 @@ const storeCustomCatalogFallbackNative = /* @__PURE__ */ registerAuth(storeCusto
                 },
             ]));
         })),
+        bound,
     ]));
 }));
+/** A custom connector's retained catalog, for discovery only. Same owner rule as its fallback. */
+export function customCatalogPeek(ctx, connectorId) {
+    return runEdge(authProgram(customCatalogPeekNative, [ctx, connectorId]));
+}
+const customCatalogPeekNative = /* @__PURE__ */ registerAuth(customCatalogPeek, (ctx, connectorId) => authFlow(function* () {
+    if (!callerOf(ctx)?.authenticated)
+        return;
+    const { cache } = (yield authCall(customCatalogCache, [ctx, connectorId]));
+    const entry = (yield authInvoke(cache, "peekTools", [ctx, "custom-connector"]));
+    return entry
+        ? { tools: entry.result.tools, fetchedAt: entry.fetchedAt, expiresAt: entry.expiresAt }
+        : undefined;
+}));
+/**
+ * A custom connector's refusal. It reads its own credential, by any route, so
+ * only one unchanged since the ticket identifies what was refused: that
+ * catalog stands in for nothing until a listing succeeds. A change, or a failed
+ * read, leaves it unknown, so every catalog retained for this connector goes.
+ */
+export function fenceCustomCatalog(ctx, connectorId, listing) {
+    return runEdge(authProgram(fenceCustomCatalogNative, [ctx, connectorId, listing]));
+}
+const fenceCustomCatalogNative = /* @__PURE__ */ registerAuth(fenceCustomCatalog, (ctx, connectorId, listing) => authFlow(function* () {
+    const current = (yield authCall(customCatalogAuth, [ctx]).pipe(Effect.catch(() => Effect.succeed(undefined))));
+    if (current === listing.auth)
+        (yield authInvoke(listing.cache, "fenceTools", [ctx, listing.bound]));
+    else
+        (yield authCall(invalidateCatalogCache, [
+            serviceFor(ctx, CatalogPolicy)?.storage ?? ctx.storage,
+            connectorId,
+        ]));
+}));
 export function customCatalogFallback(ctx, connectorId) {
     return runEdge(authProgram(customCatalogFallbackNative, [ctx, connectorId]));
 }

package/dist/catalog-freshness.js

@@ -6,8 +6,20 @@ export function markCatalogFreshness(tools, freshUntil) {
     return tools;
 }
 export function carryCatalogFreshness(source, copy) {
+    const stale = staleCatalogs.get(source);
+    if (stale)
+        staleCatalogs.set(copy, stale);
     return markCatalogFreshness(copy, deadlines.get(source) ?? 0);
 }
+const staleCatalogs = new WeakMap();
+/** Host-only, beside freshness: a stale listing is never fresh and never grants anything. */
+export function markCatalogStale(tools, staleness) {
+    staleCatalogs.set(tools, staleness);
+    return tools;
+}
+export function catalogStaleness(tools) {
+    return staleCatalogs.get(tools);
+}
 export function catalogIsFresh(tools) {
     return (deadlines.get(tools) ?? 0) > Date.now();
 }