Function createCachedRemoteJWKSet

apps/cloud/src/auth/jwks-cache.ts:259–413

(
  url: URL,
  options: CachedRemoteJWKSetOptions = {},
)

 * auth paths — see module header for why we don't just use jose's built-in.
 */
export const createCachedRemoteJWKSet = (
  url: URL,
  options: CachedRemoteJWKSetOptions = {},
): CachedRemoteJWKSet => {
  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
  const staleMaxMs = Math.max(options.staleMaxMs ?? DEFAULT_STALE_MAX_MS, ttlMs);
  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
  const store = options.store === undefined ? workersCacheStore(staleMaxMs) : options.store;
  // Capture the fetch impl lazily so consumers can swap globalThis.fetch
  // (tests do this) without us snapshotting a stale reference.
  const fetchImpl = (): typeof globalThis.fetch =>
    options.fetch ?? globalThis.fetch.bind(globalThis);

  let entry: CacheEntry | null = null;
  let inflight: Promise<CacheEntry> | null = null;
  let fetchCount = 0;
  let fetchFailureCount = 0;
  let blockingFetchCount = 0;
  let storeHitCount = 0;
  let lastFetchDurationMs: number | null = null;
  let lastStoreReadMs: number | null = null;
  let lastResolveMs: number | null = null;

  const isFresh = (candidate: CacheEntry): boolean => Date.now() - candidate.fetchedAt < ttlMs;
  const isUsable = (candidate: CacheEntry): boolean =>
    Date.now() - candidate.fetchedAt < staleMaxMs;

  const refresh = (): Promise<CacheEntry> => {
    if (inflight) return inflight;
    const startedAt = Date.now();
    fetchCount += 1;
    inflight = (async () => {
      const jwks = await fetchJwksOnce(url, fetchImpl(), timeoutMs);
      const next = entryFrom({ jwks, fetchedAt: Date.now() });
      entry = next;
      if (store) {
        await ignoreFailure(store.put(url, { jwks: next.jwks, fetchedAt: next.fetchedAt }));
      }
      return next;
    })()
      .then(
        (next) => next,
        (error: unknown) => {
          fetchFailureCount += 1;
          // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: counting a fetch failure must preserve the original rejection for jose
          throw error;
        },
      )
      .finally(() => {
        lastFetchDurationMs = Date.now() - startedAt;
        inflight = null;
      });
    return inflight;
  };

  /** Fire-and-forget revalidation behind a stale hit. */
  const refreshInBackground = (): void => {
    void ignoreFailure(refresh());