feat: eager HTML cache regeneration on updateTag/refresh

When updateTag() or refresh() is called in a server action, this change ensures:
1. User A (action caller) sees fresh data immediately (read-your-own-writes)
2. User B (cold visitor) gets the same cached data from HTML cache
3. Both users see identical data from a single render

Implementation uses client-side stream splitting:
- Server concatenates action result stream and page stream with a boundary
- Client splits on boundary, processes each stream independently
- Results combined at JS object level

Files changed:
- lib/constants.ts: Added FLIGHT_STREAM_BOUNDARY constant
- node-web-streams-helper.ts: Added concatenateFlightStreams()
- action-handler.ts: Trigger logic for updateTag/refresh
- fetch-server-response.ts: Added splitFlightStreams()
- server-action-reducer.ts: Handle split streams on client
- render-result.ts: Added toReadableStream() method

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: feedthejim

packages/next/src/client/components/app-router-headers.ts

@@ -37,3 +37,6 @@ export const NEXT_HTML_REQUEST_ID_HEADER = 'x-nextjs-html-request-id' as const
 
 // TODO: Should this include nextjs in the name, like the others?
 export const NEXT_ACTION_REVALIDATED_HEADER = 'x-action-revalidated' as const
+
+// Header to indicate split flight response (action result + page data with boundary)
+export const NEXT_SPLIT_FLIGHT_HEADER = 'x-next-split-flight' as const

packages/next/src/client/components/router-reducer/fetch-server-response.ts

@@ -503,3 +503,77 @@ function createUnclosingPrefetchStream(
     },
   })
 }
+
+/**
+ * Splits a Flight stream that contains two concatenated streams separated by a boundary.
+ * Used for split flight responses where action result and page data are sent together.
+ *
+ * @param body - The response body containing [action stream][boundary][page stream]
+ * @param boundary - The boundary string that separates the two streams
+ * @returns Two separate streams that can be processed independently
+ */
+export async function splitFlightStreams(
+  body: ReadableStream<Uint8Array>,
+  boundary: string
+): Promise<{
+  actionStream: ReadableStream<Uint8Array>
+  pageStream: ReadableStream<Uint8Array>
+}> {
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  const encoder = new TextEncoder()
+  const boundaryBytes = encoder.encode(boundary)
+
+  let buffer = new Uint8Array(0)
+  let boundaryIndex = -1
+
+  // Read until we find the boundary
+  while (boundaryIndex === -1) {
+    const { done, value } = await reader.read()
+    if (done) {
+      throw new Error('Split flight boundary not found in response')
+    }
+
+    // Append to buffer
+    const newBuffer = new Uint8Array(buffer.length + value.length)
+    newBuffer.set(buffer)
+    newBuffer.set(value, buffer.length)
+    buffer = newBuffer
+
+    // Search for boundary in the accumulated buffer
+    const text = decoder.decode(buffer)
+    boundaryIndex = text.indexOf(boundary)
+  }
+
+  // Split buffer at boundary
+  const actionBytes = buffer.slice(0, boundaryIndex)
+  const pageStartBytes = buffer.slice(boundaryIndex + boundaryBytes.length)
+
+  // Create action stream from the buffered action bytes
+  const actionStream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(actionBytes)
+      controller.close()
+    },
+  })
+
+  // Create page stream: starts with buffered remainder, then pipes rest of original stream
+  const pageStream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      // First enqueue the buffered bytes after the boundary
+      if (pageStartBytes.length > 0) {
+        controller.enqueue(pageStartBytes)
+      }
+
+      // Then pipe through the rest of the original stream
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        controller.enqueue(value)
+      }
+      controller.close()
+    },
+  })
+
+  return { actionStream, pageStream }
+}

packages/next/src/client/components/router-reducer/reducers/server-action-reducer.ts

@@ -13,7 +13,13 @@ import {
   NEXT_URL,
   RSC_CONTENT_TYPE_HEADER,
   NEXT_REQUEST_ID_HEADER,
+  NEXT_SPLIT_FLIGHT_HEADER,
 } from '../../app-router-headers'
+import { FLIGHT_STREAM_BOUNDARY } from '../../../../lib/constants'
+import {
+  splitFlightStreams,
+  createFromNextReadableStream,
+} from '../fetch-server-response'
 import { UnrecognizedActionError } from '../../unrecognized-action-error'
 
 // TODO: Explicitly import from client.browser
@@ -211,23 +217,55 @@ async function fetchServerAction(
   let actionFlightDataCouldBeIntercepted: FetchServerActionResult['actionFlightDataCouldBeIntercepted']
 
   if (isRscResponse) {
-    const response: ActionFlightResponse = await createFromFetch(
-      Promise.resolve(res),
-      {
-        callServer,
-        findSourceMapURL,
-        temporaryReferences,
-        debugChannel: createDebugChannel && createDebugChannel(headers),
+    // Check if this is a split flight response (action result + page data separated by boundary)
+    const isSplitFlight = res.headers.get(NEXT_SPLIT_FLIGHT_HEADER) === '1'
+
+    if (isSplitFlight && res.body) {
+      // Split the response body on boundary and process each stream independently
+      const { actionStream, pageStream } = await splitFlightStreams(
+        res.body,
+        FLIGHT_STREAM_BOUNDARY
+      )
+
+      // Process each stream independently using createFromNextReadableStream
+      // We cast to RequestHeaders since headers is a Record<string, string>
+      const requestHeaders =
+        headers as import('../fetch-server-response').RequestHeaders
+      const actionResponse: ActionFlightResponse =
+        await createFromNextReadableStream(actionStream, requestHeaders)
+      const pageResponse: ActionFlightResponse =
+        await createFromNextReadableStream(pageStream, requestHeaders)
+
+      // Combine at JS object level
+      // Action result comes from the action stream
+      actionResult = redirectLocation ? undefined : actionResponse.a
+      // Flight data comes from the page stream (internal request result)
+      const maybeFlightData = normalizeFlightData(pageResponse.f)
+      if (maybeFlightData !== '') {
+        actionFlightData = maybeFlightData
+        actionFlightDataRenderedSearch = pageResponse.q as NormalizedSearch
+        actionFlightDataCouldBeIntercepted = pageResponse.i
       }
-    )
+    } else {
+      // Standard single-stream response
+      const response: ActionFlightResponse = await createFromFetch(
+        Promise.resolve(res),
+        {
+          callServer,
+          findSourceMapURL,
+          temporaryReferences,
+          debugChannel: createDebugChannel && createDebugChannel(headers),
+        }
+      )
 
-    // An internal redirect can send an RSC response, but does not have a useful `actionResult`.
-    actionResult = redirectLocation ? undefined : response.a
-    const maybeFlightData = normalizeFlightData(response.f)
-    if (maybeFlightData !== '') {
-      actionFlightData = maybeFlightData
-      actionFlightDataRenderedSearch = response.q as NormalizedSearch
-      actionFlightDataCouldBeIntercepted = response.i
+      // An internal redirect can send an RSC response, but does not have a useful `actionResult`.
+      actionResult = redirectLocation ? undefined : response.a
+      const maybeFlightData = normalizeFlightData(response.f)
+      if (maybeFlightData !== '') {
+        actionFlightData = maybeFlightData
+        actionFlightDataRenderedSearch = response.q as NormalizedSearch
+        actionFlightDataCouldBeIntercepted = response.i
+      }
     }
   } else {
     // An external redirect doesn't contain RSC data.

packages/next/src/lib/constants.ts

@@ -26,6 +26,12 @@ export const NEXT_CACHE_REVALIDATE_TAG_TOKEN_HEADER =
 
 export const NEXT_RESUME_HEADER = 'next-resume'
 
+// Header to indicate split flight streams (action result + page data)
+export const NEXT_SPLIT_FLIGHT_HEADER = 'x-next-split-flight'
+
+// Boundary to separate action result stream from page stream in split flight responses
+export const FLIGHT_STREAM_BOUNDARY = '__NEXT_FLIGHT_BOUNDARY__\n'
+
 // if these change make sure we update the related
 // documentation as well
 export const NEXT_CACHE_TAG_MAX_ITEMS = 128

packages/next/src/server/app-render/action-handler.ts

@@ -43,7 +43,11 @@ import {
   JSON_CONTENT_TYPE_HEADER,
   NEXT_CACHE_REVALIDATED_TAGS_HEADER,
   NEXT_CACHE_REVALIDATE_TAG_TOKEN_HEADER,
+  NEXT_SPLIT_FLIGHT_HEADER,
+  FLIGHT_STREAM_BOUNDARY,
 } from '../../lib/constants'
+import { concatenateFlightStreams } from '../stream-utils/node-web-streams-helper'
+import { getClientReferenceManifest } from './manifests-singleton'
 import { getServerActionRequestMetadata } from '../lib/server-action-request-meta'
 import { isCsrfOriginAllowed } from './csrf-protection'
 import { warn } from '../../build/output/log'
@@ -70,6 +74,13 @@ import {
   ActionDidRevalidateStaticAndDynamic,
 } from '../../shared/lib/action-revalidation-kind'
 
+// Used for filtering stack frames in renderToReadableStream
+const filterStackFrame =
+  process.env.NODE_ENV !== 'production'
+    ? (require('../lib/source-maps') as typeof import('../lib/source-maps'))
+        .filterStackFrameDEV
+    : undefined
+
 /**
  * Checks if the app has any server actions defined in any runtime.
  */
@@ -444,6 +455,100 @@ async function createRedirectRenderResult(
   return RenderResult.EMPTY
 }
 
+/**
+ * Creates a render result by making an internal request to the current page.
+ * This is used for updateTag/refresh to ensure the HTML cache gets populated
+ * with the same data that the action caller sees (read-your-own-writes consistency).
+ *
+ * Similar to createRedirectRenderResult but for the current page instead of a redirect URL.
+ */
+async function createInternalRequestRenderResult(
+  req: BaseNextRequest,
+  res: BaseNextResponse,
+  originalHost: Host,
+  pagePath: string,
+  basePath: string,
+  workStore: WorkStore
+): Promise<RenderResult | null> {
+  if (!originalHost) {
+    return null
+  }
+
+  const forwardedHeaders = getForwardedHeaders(req, res)
+  forwardedHeaders.set(RSC_HEADER, '1')
+
+  const proto =
+    getRequestMeta(req, 'initProtocol')?.replace(/:+$/, '') || 'https'
+
+  // For standalone or the serverful mode, use the internal origin directly
+  // other than the host headers from the request.
+  const origin =
+    process.env.__NEXT_PRIVATE_ORIGIN || `${proto}://${originalHost.value}`
+
+  const fetchUrl = new URL(`${origin}${basePath}${pagePath}`)
+
+  if (workStore.pendingRevalidatedTags?.length) {
+    forwardedHeaders.set(
+      NEXT_CACHE_REVALIDATED_TAGS_HEADER,
+      workStore.pendingRevalidatedTags.map((item) => item.tag).join(',')
+    )
+    forwardedHeaders.set(
+      NEXT_CACHE_REVALIDATE_TAG_TOKEN_HEADER,
+      workStore.incrementalCache?.prerenderManifest?.preview?.previewModeId ||
+        ''
+    )
+  }
+
+  // Keep the router state tree header for partial rendering - Next.js's
+  // group revalidation will handle writing the full HTML cache
+  // Remove action header since this is now a page render request
+  forwardedHeaders.delete(ACTION_HEADER)
+
+  try {
+    setCacheBustingSearchParam(fetchUrl, {
+      [NEXT_ROUTER_PREFETCH_HEADER]: forwardedHeaders.get(
+        NEXT_ROUTER_PREFETCH_HEADER
+      )
+        ? ('1' as const)
+        : undefined,
+      [NEXT_ROUTER_SEGMENT_PREFETCH_HEADER]:
+        forwardedHeaders.get(NEXT_ROUTER_SEGMENT_PREFETCH_HEADER) ?? undefined,
+      [NEXT_ROUTER_STATE_TREE_HEADER]:
+        forwardedHeaders.get(NEXT_ROUTER_STATE_TREE_HEADER) ?? undefined,
+      [NEXT_URL]: forwardedHeaders.get(NEXT_URL) ?? undefined,
+    })
+
+    const response = await fetch(fetchUrl, {
+      method: 'GET',
+      headers: forwardedHeaders,
+      next: {
+        // @ts-ignore
+        internal: 1,
+      },
+    })
+
+    if (
+      response.headers.get('content-type')?.startsWith(RSC_CONTENT_TYPE_HEADER)
+    ) {
+      // Copy headers from the response
+      for (const [key, value] of response.headers) {
+        if (!actionsForbiddenHeaders.includes(key)) {
+          res.setHeader(key, value)
+        }
+      }
+
+      return new FlightRenderResult(response.body!)
+    } else {
+      // Since we aren't consuming the response body, we cancel it to avoid memory leaks
+      response.body?.cancel()
+    }
+  } catch (err) {
+    console.error('Failed to get internal request response for updateTag:', err)
+  }
+
+  return null
+}
+
 // Used to compare Host header and Origin header.
 const enum HostType {
   XForwardedHost = 'x-forwarded-host',
@@ -1084,6 +1189,64 @@ export async function handleAction({
             addRevalidationHeader(res, { workStore, requestStore })
           })
 
+        // For updateTag() or refresh() calls, use internal request to ensure
+        // the HTML cache gets populated with the same data the action caller sees.
+        // This provides read-your-own-writes consistency between User A (action caller)
+        // and User B (subsequent cold visitor).
+        const hasUpdateTagCalls = workStore.pendingRevalidatedTags?.some(
+          (item) => item.profile === undefined
+        )
+        const hasRefreshCall =
+          workStore.pathWasRevalidated !== undefined &&
+          workStore.pathWasRevalidated !== ActionDidNotRevalidate
+
+        const shouldUseSplitFlightResponse = hasUpdateTagCalls || hasRefreshCall
+
+        if (
+          isFetchAction &&
+          shouldUseSplitFlightResponse &&
+          !actionWasForwarded
+        ) {
+          // Make an internal request to get the page render stream.
+          // This ensures the same data is used for both action response and HTML cache.
+          const pageResult = await createInternalRequestRenderResult(
+            req,
+            res,
+            host,
+            workStore.route,
+            ctx.renderOpts.basePath,
+            workStore
+          )
+
+          if (pageResult) {
+            // Encode the action result as a separate Flight stream
+            const { clientModules } = getClientReferenceManifest()
+            const actionResultPayload = { a: Promise.resolve(actionResult) }
+            const actionResultStream = ComponentMod.renderToReadableStream(
+              actionResultPayload,
+              clientModules,
+              { temporaryReferences, filterStackFrame }
+            )
+
+            // Set header to indicate split flight response
+            res.setHeader(NEXT_SPLIT_FLIGHT_HEADER, '1')
+
+            // Concatenate: [action result stream][BOUNDARY][page stream]
+            // Client will split on boundary and process each stream independently
+            const combinedStream = concatenateFlightStreams(
+              actionResultStream,
+              pageResult.toReadableStream(),
+              FLIGHT_STREAM_BOUNDARY
+            )
+
+            return {
+              type: 'done',
+              result: new FlightRenderResult(combinedStream),
+            }
+          }
+          // If internal request failed, fall through to regular generateFlight
+        }
+
         // For form actions, we need to continue rendering the page.
         if (isFetchAction) {
           return {

packages/next/src/server/render-result.ts

@@ -195,6 +195,13 @@ export default class RenderResult<
     return this.response
   }
 
+  /**
+   * Returns a readable stream of the response.
+   */
+  public toReadableStream(): ReadableStream<Uint8Array> {
+    return this.readable
+  }
+
   /**
    * Returns a readable stream of the response.
    */