fix(dispatch): harden static asset storage failures (#243)

* fix(dispatch): harden static asset storage failures

* fix(dispatch): address asset fallback review

* fix(dispatch): preserve pre-stub timeout attribution

Author: Brooooooklyn

README.md

@@ -250,7 +250,7 @@ The edge router.
 
 - Reads slug/domain routing from KV.
 - Sends worker projects to Workers for Platforms.
-- Serves static/SPA deployments directly from `STATIC_ASSETS` KV with R2 overflow for large files.
+- Serves current static/SPA deployments directly from R2, while retaining KV reads for small assets carried forward from legacy deploys.
 - Handles ISR, edge caching, redirect/rewrite rules, header rules, and request metering.
 - Relays Cloudflare Queue batches to user workers.
 

packages/api/README.md

@@ -152,7 +152,7 @@ Dashboard auth uses the same JWT model, stored in the `void_token` cookie.
 ### Static/SPA deploys
 
 1. content-address assets by hash
-2. store small assets in `STATIC_ASSETS` KV and large assets in `STATIC_ASSETS_R2`
+2. issue presigned uploads that store every new asset directly in `STATIC_ASSETS_R2` (`STATIC_ASSETS` KV is retained for carry-forward assets from legacy multipart deploys)
 3. write a manifest to `ROUTING`
 4. point routing at `staticDeploymentId` instead of a worker
 

packages/api/src/usage-counter.ts

@@ -27,6 +27,10 @@ export type UsageEvent = Readonly<{
   requests: number;
   responseBytes: number;
   status?: number;
+  failureKind?:
+    | 'platform-static-asset-timeout'
+    | 'platform-static-asset-error'
+    | 'platform-static-asset-missing';
   sandboxRuntimeSeconds?: number;
   sandboxInstanceId?: string;
 }>;

packages/api/src/usage-queue.ts

@@ -3,6 +3,10 @@ import type { ApiEnv } from './env.ts';
 import { getPlanLimits } from './tiers.ts';
 import type { UsageEvent } from './usage-counter.ts';
 
+const PLATFORM_STATIC_ASSET_FAILURES: ReadonlySet<NonNullable<UsageEvent['failureKind']>> = new Set(
+  ['platform-static-asset-timeout', 'platform-static-asset-error', 'platform-static-asset-missing'],
+);
+
 export function groupEventsByUser(
   events: ReadonlyArray<UsageEvent>,
 ): Map<string, ReadonlyArray<UsageEvent>> {
@@ -72,9 +76,15 @@ export async function processUsageEventBatch(
   if (failures.length > 0) {
     batch.retryAll();
   } else {
-    // Best-effort: route 5xx events to ErrorAlertMonitor (failures don't block ack)
+    // Best-effort: route project 5xx events to ErrorAlertMonitor (failures
+    // don't block ack). Platform-owned static storage failures remain billed
+    // and visible in request analytics, but do not tell users that their
+    // application returned an error.
     const errorRecords = records.filter(
-      ({ event }) => event.status !== undefined && event.status >= 500,
+      ({ event }) =>
+        event.status !== undefined &&
+        event.status >= 500 &&
+        !(event.failureKind !== undefined && PLATFORM_STATIC_ASSET_FAILURES.has(event.failureKind)),
     );
     if (errorRecords.length > 0) {
       const errorsByProject = new Map<

packages/api/test/unit/usage-queue.test.ts

@@ -192,4 +192,50 @@ describe('processUsageEventBatch — 5xx alert window', () => {
     expect(p1).toMatchObject({ firstAt: early, lastAt: early });
     expect(p2).toMatchObject({ firstAt: late, lastAt: late });
   });
+
+  it('bills platform static-asset failures without sending user error alerts', async () => {
+    const stubFetch = vi.fn(async () => new Response(null, { status: 200 }));
+    const errorStubFetch = vi.fn(async () => new Response(null, { status: 200 }));
+    getUserMock.mockResolvedValue({ id: 'u1', plan: 'solo' });
+
+    const platformFailures: Array<UsageEvent> = [
+      { ...error5xx('docs'), failureKind: 'platform-static-asset-timeout' },
+      { ...error5xx('docs'), failureKind: 'platform-static-asset-error' },
+      { ...error5xx('docs'), failureKind: 'platform-static-asset-missing' },
+    ];
+    const batch = makeBatch(platformFailures);
+
+    await processUsageEventBatch(batch as never, makeEnv(stubFetch, errorStubFetch) as never);
+
+    expect(stubFetch).toHaveBeenCalledOnce();
+    const counterBody = (await fetchCalls(stubFetch)[0][0].json()) as {
+      events: Array<UsageEvent>;
+    };
+    expect(counterBody.events).toEqual(platformFailures);
+    expect(errorStubFetch).not.toHaveBeenCalled();
+    expect(batch.calls.ackAll).toBe(1);
+  });
+
+  it('still alerts for application 5xx events mixed with a platform timeout', async () => {
+    const stubFetch = vi.fn(async () => new Response(null, { status: 200 }));
+    const errorStubFetch = vi.fn(async () => new Response(null, { status: 200 }));
+    getUserMock.mockResolvedValue({ id: 'u1', plan: 'solo' });
+
+    const platformTimeout: UsageEvent = {
+      ...error5xx('docs'),
+      failureKind: 'platform-static-asset-timeout',
+    };
+    const appFailure = error5xx('repl');
+    const batch = makeBatch([platformTimeout, appFailure]);
+
+    await processUsageEventBatch(batch as never, makeEnv(stubFetch, errorStubFetch) as never);
+
+    expect(errorStubFetch).toHaveBeenCalledOnce();
+    const alertBody = (await fetchCalls(errorStubFetch)[0][0].json()) as {
+      projectId: string;
+      count: number;
+    };
+    expect(alertBody).toMatchObject({ projectId: 'repl', count: 1 });
+    expect(batch.calls.ackAll).toBe(1);
+  });
 });

packages/dispatch/README.md

@@ -9,12 +9,12 @@ Edge router for deployed Void apps. It routes requests to user workers, serves s
 3. Reject suspended projects with `429`.
 4. Apply `redirectRules` (pre-asset) before any worker invocation. Redirects short-circuit with a `Location` header; status-200 entries are "force" rewrites that mutate `url.pathname` and continue.
 5. Serve hashed assets from edge cache when possible.
-6. For static/SPA projects, serve files from `STATIC_ASSETS` KV with `STATIC_ASSETS_R2` overflow for large assets, using `assetConfig` path resolution.
+6. For static/SPA projects, serve current direct-upload assets from `STATIC_ASSETS_R2`; preserve `STATIC_ASSETS` KV reads for assets carried forward from legacy deploys. Storage reads get one delayed hedge within the existing 10-second request budget, then use `assetConfig` path resolution.
 7. Apply `fallbackRules` (post-asset) only when static asset resolution misses — instead of returning 404, match the pathname against fallback rules (status=200 only) and rewrite. Intended for SPA shells (`/* → /index.html`) and default-locale catch-alls. On static deployments, a matched fallback serves the resolved asset directly without dispatching to a user worker, so `X-Void-Original-URL` is never set, `c.originalUrl()` is unavailable, and the response is not ISR-cached (see `packages/dispatch/test/unit/fallback-rules.test.ts`).
 8. For `/api/*`, forward to the user worker in the dispatch namespace with plan-specific CPU/subrequest limits.
 9. For SSR with ISR enabled, use `caches.default` plus `ISR_CACHE` KV for stale-while-revalidate behavior.
-10. For WfP deploys, inspect the worker response for the Cloudflare asset-dedupe-poisoning stub (`Assets have not yet been deployed to this script.`). On detection, if the routing entry has `assetManifestId`, re-serve from the platform-owned mirror (`STATIC_ASSETS`/`STATIC_ASSETS_R2`). See `meta/design-docs/0066` and `meta/design-docs/0065`.
-11. Apply header rules and record usage in Analytics Engine. If `userId` is present on the routing entry, enqueue usage events as well.
+10. For WfP deploys, inspect worker and cache responses for the Cloudflare asset-dedupe-poisoning stub (`Assets have not yet been deployed to this script.`). On detection, purge any poisoned cache entry and re-serve from the platform-owned mirror (`STATIC_ASSETS`/`STATIC_ASSETS_R2`). If the mirror is unavailable or incomplete, return an attributed `503` instead of passing through and caching the known-bad `200` stub. See `meta/design-docs/0066` and `meta/design-docs/0065`.
+11. Apply header rules and record usage in Analytics Engine. If `userId` is present on the routing entry, enqueue usage events as well. Platform-owned static storage failures carry a `failureKind`: they remain metered and queryable but are excluded from customer application-error emails.
 
 Two rule lists exist so dispatch never has to reason about per-rule phase flags at the edge:
 
@@ -23,8 +23,8 @@ Two rule lists exist so dispatch never has to reason about per-rule phase flags
 
 ## Static and ISR Storage
 
-- **Static/SPA deploys**: manifest in `ROUTING`, assets in `STATIC_ASSETS` KV, overflow in `STATIC_ASSETS_R2`
-- **WfP deploys with asset mirror**: same stores as static (manifest at `manifest:{deploymentId}`, assets at `assets/{projectId}/{hash}`). `RoutingEntry.assetManifestId` points at the manifest. CF's `ASSETS` binding remains primary — this mirror is only consulted when the CF stub is detected.
+- **Static/SPA deploys**: manifest in `ROUTING`; current direct-upload assets in `STATIC_ASSETS_R2`. `STATIC_ASSETS` KV remains readable for small assets carried forward from legacy multipart deploys.
+- **WfP deploys with asset mirror**: same project-scoped storage and manifest format as static (manifest at `manifest:{deploymentId}`, assets at `assets/{projectId}/{hash}`). `RoutingEntry.assetManifestId` points at the manifest. CF's `ASSETS` binding remains primary — this mirror is only consulted when the CF stub is detected.
 - **ISR cache**: packed HTML/headers stored in `ISR_CACHE` KV, with edge-cache copies in `caches.default`. Keys are (project, deployment, pathname, optional rewrite-variant token) so a direct hit to `/en/docs` and a request rewritten from `/docs → /en/docs` live in distinct slots — user code can branch on `c.isRewritten()` / `c.originalUrl()` and the cache honors that. The variant suffix is derived from `X-Void-Original-URL` via the shared helpers in [`packages/isr-shared`](../isr-shared/README.md); direct hits (no rewrite, no header) use the unsuffixed key.
 - **ISR TTL resolution**: a request's TTL resolves route-aware — dispatch first-matches the path against the manifest's ordered `pages` table (`{ pattern, revalidate }`, in the framework's route order, **not** re-sorted) so a specific page shadows a broad catch-all, then falls back to the flat `revalidate` pattern→TTL map for deploys that predate `pages`. Only a positive-TTL, non-catch-all match is ISR-eligible; API routes and asset-extension paths that merely match a catch-all render live (`resolvePageTtl` / `isIsrEligiblePath` in `isr.ts`).
 - **Hashed assets**: immutable edge-cache entries keyed by URL path