@toapi/worker: offline stale-fallback is unreachable — serveFromNetwork is not awaited

[mismosmi]

Summary

@toapi/worker@1.1.0 documents, as one of its three headline benefits:

Offline resilience — if the network is unavailable, an expired-but-present cache entry is served rather than failing.

That fallback cannot run. In packages/2-toapi-worker/src/handle-toapi-request.ts the expired-entry branch returns the promise instead of awaiting it, so the catch is dead code:

} else {
  // cached response is expired
  try {
    // try to serve from network
    return serveFromNetwork(req);   // <- not awaited
  } catch (error) {
    // probably network not available, serve old response
    errorLog(error);
    return cachedResponse;          // <- unreachable
  }
}

serveFromNetwork starts with await fetch(req), which rejects when there is no network. Because the promise is returned rather than awaited, that rejection escapes handleToapiRequest, reaches event.respondWith(), and the browser reports a network error — instead of serving the cached copy that is sitting right there.

return await serveFromNetwork(req) fixes it.

Why this is the common path, not an edge case

listenForInvalidations calls expireAll() every time the stream opens, which stamps expiresAt = Date.now() on every entry, including ones cached without a TTL (their expiresAt was null). That is documented and intended — "when the service worker connects to the invalidation stream, it automatically marks every cached entry as expired so the next access revalidates it".

The consequence is that after any service-worker restart, every cached entry takes the broken branch. So the practical behaviour is:

• entries re-fetched since the worker last started → served from cache offline (they take the expiresAt === null path, which returns cachedResponse directly);
• everything else → hard network error offline.

Since a service worker is killed after ~30s idle and restarted on the next event, "everything else" is most of the cache most of the time.

Reproduction

1. Set up a worker with setupToapiWorker() and load a page that reads a tagged /api route.
2. Confirm the response is in the tapi-cache Cache Storage bucket.
3. Let the service worker be terminated (DevTools → Application → Service Workers → Stop, or just idle), so the next start re-opens the invalidation stream and runs expireAll().
4. Go offline and reload.

Expected: the cached response is served (per the docs above).
Actual: the request fails with a network error; event.respondWith() received a rejected promise.

Version

@toapi/worker@1.1.0 — verified both in the published dist/handle-toapi-request.js and in the TypeScript source at main.

[farbenmeer-code]

🤖 Open this thread in ColorCode

[mismosmi]

Correcting my own repro steps — I have now tested this in a browser rather than reasoning from the source, and step 3 above (stop the worker, then go offline) does not reliably reproduce it. The bug is real, but reaching the expired branch is harder than I implied.

The defect reproduces deterministically. Chromium, @toapi/worker@1.1.0, setupToapiWorker() + Workbox precaching, server killed outright (see the caveat below):

entry state	offline read of /api/auth/me
expiresAt: null	200, served from cache — app renders fully offline
expiresAt in the past	TypeError: Failed to fetch, app renders "Failed to fetch"

So the second row is exactly the case the docs promise to serve from cache, and it errors instead. return await serveFromNetwork(req) is still the fix.

Why "stop the worker, then reload" is not enough. When the restarted worker reconnects the stream, expireAll() marks every entry expired and posts the tags to every client. @toapi/client reacts by revalidating those tags, which refetches the entries the open page is querying — and serveFromNetwork re-stores them with expiresAt: null again. Within a second or two of the restart, everything the current page is actually looking at is back in the healthy first row. I watched CDP runningStatus go activated/stopped → activated/starting → activated/running and the meta records stayed null throughout.

The entries that stay expired are the ones no mounted query owns — anything cached by a page you are no longer on. Those sit expired until something asks for them again, and if that request happens offline it errors instead of serving the copy that is right there. That is the realistic user-facing shape of this bug: "the view I had open still works offline, the one I visited yesterday does not."

Caveat for anyone verifying this. Playwright's context.setOffline(true) (and DevTools' Offline checkbox, in some versions) does not apply to the service worker's own target, so the worker keeps fetching successfully while the page looks offline — which makes the bug appear absent. I only got truthful results after killing the server process.

---

Generated by Claude Code

[farbenmeer-code]

✅ Ready to implement

Problem

In packages/2-toapi-worker/src/handle-toapi-request.ts, the expired-cache branch at line 31 calls return serveFromNetwork(req) without await. Since serveFromNetwork is async and can reject (e.g. offline), the promise rejection escapes past the catch block on line 32 to event.respondWith(), causing a network error instead of serving the stale cached entry.

Acceptance criteria

1. return serveFromNetwork(req) on line 31 becomes return await serveFromNetwork(req) so the catch on line 32 can handle the rejection.
2. When offline, an expired-but-cached entry is served from cache (the catch branch returns cachedResponse), matching the documented offline-resilience behavior.
3. The network path (online) still works — the awaited promise resolves normally and the fresh response is returned.

---

▶ Plan the implementation in ColorCode

[farbenmeer-code]

The issue is triaged and ready. The "ready to implement" comment has been posted — its link will trigger planning and implementation when clicked.

[farbenmeer-code]

📋 Implementation plan

Plan: Fix missing await in handleToapiRequest stale-fallback branch

The fix

In packages/2-toapi-worker/src/handle-toapi-request.ts, line 31:

-        return serveFromNetwork(req);
+        return await serveFromNetwork(req);

This ensures the catch block on line 32 can actually catch a rejection from serveFromNetwork (e.g. when offline), so cachedResponse is returned as the stale fallback instead of the rejection escaping to event.respondWith().

Changeset

Add a .changeset/*.md file with a patch bump for @toapi/worker (the fixed group will bump all @toapi/* packages together, but the semantic intent is a patch-level bugfix). Changelog entry: "Fix offline stale-fallback in the worker: serveFromNetwork is now awaited so the expired-cache catch block can serve the cached response when the network is unavailable."

Verification

• TypeScript compilation: pnpm --filter @toapi/worker build must pass.
• No existing tests in this package (--passWithNoTests), so manual verification of the acceptance criteria:
  1. Online path: a request with an expired cache entry returns the fresh network response (the awaited promise resolves normally).
  2. Offline path: a request with an expired cache entry returns the cached response (the rejection is caught by the catch block).

What is NOT in scope

• Adding tests for handleToapiRequest (the package has no test infrastructure; setting that up is a separate effort).
• Changing expireAll() behavior (expiresAt stamping of null-TTL entries is documented/intended).

---

✅ Accepted — watch it being implemented in ColorCode

[farbenmeer-code]

Done. Here's the summary:

What	Detail
Fix	packages/2-toapi-worker/src/handle-toapi-request.ts:35 — added await before serveFromNetwork(req)
Changeset	.changeset/await-stale-fallback.md — patch bump for @toapi/worker
PR	#424 (draft)
CI	Build couldn't run in this sandbox (network bottleneck on pnpm install), but CI will catch it on push

The fix is a single keyword — await — in a function that was already async. The catch block is now reachable when serveFromNetwork rejects (e.g. offline), returning the stale cachedResponse as documented.

[farbenmeer-code]

Everything is in order:

• Branch: up to date with main (1 commit ahead, no merge needed)
• Reviews: none yet
• CI: in progress — Unit Tests running

No action needed at this point. CI results will come back as a new message.