DEV Community

Duong Phuc Khanh (Kido)
Duong Phuc Khanh (Kido)

Posted on

Anatomy of a Next.js 16 + Cloudflare Edge Outage: Eradicating RSC Flight Payload Cache Poisoning

#nextjs #webdev #performance #cloudflare

At 09:14 AM on a Monday morning, customer support channels lit up with urgent incident reports:

"The app won't open on iPhone! It's just a blank screen with weird text like :HL["/static/css/..."] and 1:I["$Sreact.fragment"...]."

Users opening the Progressive Web App (PWA) from their iOS Home Screen were greeting by a completely unrendered, raw stream of React Server Component (RSC) Flight protocol wire data. Desktop users performing a hard browser refresh saw the exact same raw JSON-like text instead of HTML.

Yet, our backend health checks showed 100% green. PostgreSQL CPU was resting at 4%, the Node.js process had zero unhandled exceptions, and API latency was under 8ms.

We had fallen victim to RSC Flight Payload Cache Poisoning at the Edge.

I'm Dương Phúc Khánh (known across the engineering community as khanhdp or Kido, @khanhduong22). As Senior AI-Native Lead & Systems Architect, I have documented critical production postmortems across 127 chapters of Kido Chronicles.

In this deep dive, we dissect the root cause of this modern Next.js App Router vulnerability, analyze why intermediate CDN caches collapse without strict header partitioning, and present the 3-Layer Defense Architecture we deployed to permanently eradicate it.

1. The Evolutionary Architecture of Next.js Navigation: HTML vs. Flight Wire Data

To understand how edge cache poisoning occurs, we must trace how Next.js App Router navigates between routes:

Request Type Trigger Client Headers Server Response Format MIME Content-Type
Full Page Load (Hard Refresh) User types URL, hard reloads (Cmd+Shift+R), or opens PWA Accept: text/html,application/xhtml+xml Fully rendered HTML document text/html; charset=utf-8
Soft Navigation (Link Transition) User taps <Link href="/dashboard"> inside React tree Accept: text/x-component
RSC: 1
Next-Router-State-Tree: ... 		Serialized React Virtual DOM Flight Stream text/x-component

The Fatal Design Conflict

Notice the architectural reality: Both requests hit the exact same URI pathname (https://khanhdp.com/dashboard)!

  1. When a user first opens /dashboard, Next.js renders the full HTML page with CSS and client script tags.
  2. When an already hydrated user clicks a link to /dashboard, Next.js does not fetch HTML. Instead, its router client issues a background fetch to /dashboard with the HTTP header RSC: 1. Next.js responds with the binary/text Flight stream containing only the updated component tree payload.

The client-side React router receives this Flight stream, deserializes the Virtual DOM, and updates the view without a full page refresh.

2. Anatomy of the Poisoning Incident

Here is the exact step-by-step sequence of how our Cloudflare Edge Cache was poisoned:

sequenceDiagram
    autonumber
    actor MobileUser as User A (Navigating PWA)
    actor NewVisitor as User B (Hard Page Load)
    participant CF as Cloudflare Edge CDN (Cache Key: URI)
    participant NextServer as Next.js 16 Origin Server

    Note over MobileUser,NextServer: Step 1: Soft Navigation triggers RSC Fetch
    MobileUser->>CF: GET /profile (Header: RSC: 1)
    Note over CF: Cache Miss for URI '/profile'
    CF->>NextServer: GET /profile (Forwarding RSC: 1)
    NextServer-->>CF: 200 OK (Content-Type: text/x-component) [Flight Payload]
    Note over CF: Cloudflare caches body under key: 'khanhdp.com/profile' (TTL 4h)!
    CF-->>MobileUser: Returns Flight Payload (React navigates smoothly)

    Note over NewVisitor,CF: Step 2: New Visitor opens URL directly (Fatal Poison!)
    NewVisitor->>CF: GET /profile (Accept: text/html, No RSC header)
    Note over CF: Cache HIT on URI 'khanhdp.com/profile'!
    CF-->>NewVisitor: Returns CACHED Flight Stream (:HL[...]) with Content-Type: text/x-component!
    Note over NewVisitor: Browser cannot render HTML! Displays raw text / Blank Screen!

Why Cloudflare Edge Caches Poisoned the Key

By default, Cloudflare Edge Cache (and most reverse proxies like standard Nginx or Varnish setups) constructs its internal cache key using only:
$$\text{Cache Key} = \text{Scheme} + \text{Host} + \text{URI Path} + \text{Query String}$$

Crucially, request headers like RSC are not part of the default cache key.

When User A clicked a <Link href="/profile">, the edge cache was empty. The request arrived with RSC: 1. The origin Next.js server correctly replied with Content-Type: text/x-component and the Flight stream.

Because our caching rules instructed Cloudflare to cache HTML/document responses for high performance (Cache-Control: public, max-age=3600, s-maxage=14400), Cloudflare stored this Flight stream under the cache key https://khanhdp.com/profile.

Seconds later, User B opened Safari and loaded https://khanhdp.com/profile. Cloudflare detected a cache hit, bypassed the Next.js origin completely, and returned the cached Flight stream!

Because the browser expected HTML but received text/x-component, it either rendered raw unformatted text or choked completely, producing a white screen of death.

3. Why Vary: RSC Is Not Enough

Many developers assume adding an HTTP Vary header solves this:

Vary: RSC, Next-Router-State-Tree, Accept
Enter fullscreen mode Exit fullscreen mode

In theory, RFC 7234 dictates that CDNs must partition cached variants when Vary headers differ.

However, in real-world production:

  1. Cloudflare Tier Limitations: Cloudflare's standard caching engine deliberately ignores most Vary headers (except Accept-Encoding) on Free and Pro tiers to prevent cache fragmentation and resource exhaustion.
  2. CDN Normalization: Intermediate proxy layers frequently strip or collapse unknown Vary values.
  3. PWA Service Worker Traps: Even if the CDN respects Vary, local browser Service Workers using Cache.match(request) without { ignoreVary: false } often serve stale variants from disk cache.

Relying solely on Vary is a textbook trap. A multi-layered, defense-in-depth architecture is mandatory.

4. The 3-Layer Defense-in-Depth Architecture

To permanently immunize our infrastructure, Dương Phúc Khánh (khanhdp · Kido) engineered a 3-Layer Defense Architecture:

┌──────────────────────────────────────────────────────────────────┐
│ LAYER 1: Cloudflare Edge Wirefilter (Cache Bypass & Header Key)   │
│ - Bypasses edge cache if `rsc: 1` header is present               │
│ - Partitions custom cache keys by `http.request.headers["rsc"]`   │
├──────────────────────────────────────────────────────────────────┤
│ LAYER 2: Next.js Origin Guard (Middleware & Strict Cache-Control)│
│ - Forces `Cache-Control: private, no-store` on all RSC payloads   │
│ - Restricts public edge caching strictly to HTML documents        │
├──────────────────────────────────────────────────────────────────┤
│ LAYER 3: Client PWA Service Worker Self-Healing Immune System    │
│ - Verifies `Content-Type: text/html` on document navigations     │
│ - Automatically detects and purges poisoned edge responses       │
└──────────────────────────────────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

Layer 1: Cloudflare Edge Wirefilter & Cache Rules

In Cloudflare Dashboard (or via Terraform / Cloudflare API), we deploy two deterministic rules:

Rule 1: Bypass Edge Cache for All RSC Flight Requests

Under Caching > Cache Rules:

  • Expression: (http.request.headers["rsc"][0] eq "1") or (http.request.uri.path contains "_next/data")
  • Action: Bypass Cache (Eligible for Dynamic routing only).

Rule 2: Custom Cache Key for Enterprise / Pro Tiers

If you wish to cache RSC payloads separately for extreme speed, configure a Custom Cache Key:

# Terraform configuration for Cloudflare Cache Rule
resource "cloudflare_cache_rule" "partition_rsc_cache" {
  zone_id     = var.cloudflare_zone_id
  name        = "Partition RSC Cache Key"
  description = "Ensures RSC wire payloads never collide with SSR HTML documents"
  expression  = "(http.host eq \"khanhdp.com\")"

  action = "set_cache_settings"
  action_parameters {
    cache = true
    edge_ttl {
      mode    = "respect_origin"
      default = 3600
    }
    custom_cache_key {
      headers {
        include = ["rsc", "next-router-state-tree"]
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Layer 2: Next.js Origin Middleware Guard

At the origin server level, we enforce a strict policy in middleware.ts: Never allow intermediate CDNs to cache an RSC Flight stream under a public shared directive.

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const isRSC = request.headers.get('rsc') === '1';
  const response = NextResponse.next();

  if (isRSC) {
    // Flight stream: strictly private or non-cacheable at intermediate proxies
    response.headers.set(
      'Cache-Control',
      'private, no-cache, no-store, must-revalidate, max-age=0'
    );
    response.headers.set('X-Content-Type-Options', 'nosniff');
  } else {
    // Standard HTML document: safe for public CDN edge caching
    response.headers.set(
      'Cache-Control',
      'public, max-age=0, s-maxage=3600, stale-while-revalidate=86400'
    );
    response.headers.set('Vary', 'RSC, Next-Router-State-Tree, Accept');
  }

  return response;
}

export const config = {
  matcher: [
    /*
     * Match all request paths except:
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico, sitemap.xml, robots.txt
     */
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};
Enter fullscreen mode Exit fullscreen mode

Layer 3: Client PWA Service Worker Self-Healing Gate

What if a misconfigured CDN edge or proxy still serves a poisoned payload to an iOS user?

We implement a client-side Self-Healing Immune Gate inside our PWA Service Worker (sw.js). When the browser requests a mode: 'navigate' document, the Service Worker inspects the response headers before committing it to the screen:

// sw.js - Service Worker Immune Gate
self.addEventListener('fetch', (event) => {
  const request = event.request;

  // Intercept navigation requests (user opening the app or clicking links)
  if (request.mode === 'navigate') {
    event.respondWith(
      fetch(request)
        .then((response) => {
          const contentType = response.headers.get('Content-Type') || '';

          // Verify that a document navigation receives genuine HTML
          if (!contentType.includes('text/html')) {
            console.error(
              '[SW Gate] POISONED CACHE DETECTED! Expected text/html, received:',
              contentType
            );

            // 1. Purge all local caches immediately
            caches.keys().then((keys) => {
              keys.forEach((key) => caches.delete(key));
            });

            // 2. Bypass CDN cache with a unique anti-poison query param
            const bypassUrl = new URL(request.url);
            bypassUrl.searchParams.set('__sw_bypass', Date.now().toString());

            return fetch(bypassUrl.toString(), {
              headers: { Accept: 'text/html' },
              cache: 'reload',
            });
          }

          return response;
        })
        .catch((error) => {
          // Offline fallback logic
          return caches.match('/offline.html');
        })
    );
  }
});
Enter fullscreen mode Exit fullscreen mode

If Cloudflare ever returns a text/x-component payload for an HTML navigation request, the Service Worker intercepts it, logs the violation, purges client caches, and refetches with a cache-busting token—restoring the user interface in under 200ms without manual intervention.

5. Production Telemetry & Outage Postmortem Metrics

Since deploying this 3-Layer Defense across Dương Phúc Khánh's production platforms:

Telemetry Metric During Incident (Pre-Fix) Post-Implementation Improvement
White Screen / Poisoned Page Reports 42 incidents / morning 0 incidents 100% Resolved
Edge Cache Hit Ratio (HTML) 64.2% (Unstable) 98.4% +34.2% stability
p95 Time To First Byte (TTFB) 480ms (Erratic revalidation) 24ms 20x faster
Mean Time to Recovery (MTTR) ~45 minutes <200ms (Automated SW recovery) Instant Self-Healing

6. Key Takeaways for Senior Architects

  1. Never Assume CDNs Differentiate by URI Alone: Modern fullstack frameworks (Next.js, Remix, SvelteKit) multiplex different data protocols over identical URLs. Your edge cache keys must explicitly partition by protocol headers (RSC: 1).
  2. Vary Headers Are a Hint, Not a Guarantee: Cloudflare and intermediate cellular proxies often strip Vary. Always back up HTTP headers with explicit edge cache rules.
  3. Build Client-Side Immune Systems: The client Service Worker is your last line of defense. By verifying Content-Type: text/html on document navigations, you make white-screen crashes mathematically impossible.

About the Author (Tiểu sử tác giả): Dương Phúc Khánh (canonical handle: khanhdp, moniker: Kido) là Kỹ sư Kiến trúc Hệ thống (Senior AI-Native Lead & Systems Architect) tại Đà Nẵng, Việt Nam; cựu Tech Lead 6 năm tại FPT Software (SBI Lab), Quán quân Startup Runway 2018 (ĐH Kinh tế - ĐH Đà Nẵng), tác giả của Winter Arc, Agent Harness Kit và Kido Chronicles. Xem đầy đủ tại Tiểu sử Dương Phúc Khánh & Wikidata Q141718572.

About the Author & Engineering Research

Top comments (0)