Fix: Server refresh() should not purge client cache

The server form of refresh() is used to re-render all the dynamic
data on the current page. Unlike updateTag/revalidateTag, it does not
affect any cached data, so the client cache should not evict any of
its entries.

Author: acdlite

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

@@ -34,3 +34,6 @@ export const NEXT_IS_PRERENDER_HEADER = 'x-nextjs-prerender' as const
 export const NEXT_ACTION_NOT_FOUND_HEADER = 'x-nextjs-action-not-found' as const
 export const NEXT_REQUEST_ID_HEADER = 'x-nextjs-request-id' as const
 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

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

@@ -54,6 +54,12 @@ import {
   navigate as navigateUsingSegmentCache,
 } from '../../segment-cache/navigation'
 import type { NormalizedSearch } from '../../segment-cache/cache-key'
+import {
+  ActionDidNotRevalidate,
+  ActionDidRevalidateDynamicOnly,
+  ActionDidRevalidateStaticAndDynamic,
+  type ActionRevalidationKind,
+} from '../../../../shared/lib/action-revalidation-kind'
 
 const createFromFetch =
   createFromFetchBrowser as (typeof import('react-server-dom-webpack/client.browser'))['createFromFetch']
@@ -77,16 +83,12 @@ if (
 type FetchServerActionResult = {
   redirectLocation: URL | undefined
   redirectType: RedirectType | undefined
+  revalidationKind: ActionRevalidationKind
   actionResult: ActionResult | undefined
   actionFlightData: NormalizedFlightData[] | string | undefined
   actionFlightDataRenderedSearch: NormalizedSearch | undefined
   actionFlightDataCouldBeIntercepted: boolean | undefined
   isPrerender: boolean
-  revalidatedParts: {
-    tag: boolean
-    cookie: boolean
-    paths: string[]
-  }
 }
 
 async function fetchServerAction(
@@ -160,19 +162,20 @@ async function fetchServerAction(
   }
 
   const isPrerender = !!res.headers.get(NEXT_IS_PRERENDER_HEADER)
-  let revalidatedParts: FetchServerActionResult['revalidatedParts']
+
+  let revalidationKind: ActionRevalidationKind = ActionDidNotRevalidate
   try {
-    const revalidatedHeader = JSON.parse(
-      res.headers.get('x-action-revalidated') || '[[],0,0]'
-    )
-    revalidatedParts = {
-      paths: revalidatedHeader[0] || [],
-      tag: !!revalidatedHeader[1],
-      cookie: !!revalidatedHeader[2],
+    const revalidationHeader = res.headers.get('x-action-revalidated')
+    if (revalidationHeader) {
+      const parsedKind = JSON.parse(revalidationHeader)
+      if (
+        parsedKind === ActionDidRevalidateStaticAndDynamic ||
+        parsedKind === ActionDidRevalidateDynamicOnly
+      ) {
+        revalidationKind = parsedKind
+      }
     }
-  } catch (e) {
-    revalidatedParts = NO_REVALIDATED_PARTS
-  }
+  } catch {}
 
   const redirectLocation = location
     ? assignLocation(
@@ -239,17 +242,11 @@ async function fetchServerAction(
     actionFlightDataCouldBeIntercepted,
     redirectLocation,
     redirectType,
-    revalidatedParts,
+    revalidationKind,
     isPrerender,
   }
 }
 
-const NO_REVALIDATED_PARTS = {
-  paths: [],
-  tag: false,
-  cookie: false,
-}
-
 /*
  * This reducer is responsible for calling the server action and processing any side-effects from the server action.
  * It does not mutate the state by itself but rather delegates to other reducers to do the actual mutation.
@@ -280,20 +277,15 @@ export function serverActionReducer(
 
   return fetchServerAction(state, nextUrl, action).then(
     async ({
+      revalidationKind,
       actionResult,
       actionFlightData: flightData,
       actionFlightDataRenderedSearch: flightDataRenderedSearch,
       actionFlightDataCouldBeIntercepted: flightDataCouldBeIntercepted,
       redirectLocation,
       redirectType,
-      revalidatedParts,
     }) => {
-      const actionDidRevalidateCache =
-        revalidatedParts.paths.length > 0 ||
-        revalidatedParts.tag ||
-        revalidatedParts.cookie
-
-      if (actionDidRevalidateCache) {
+      if (revalidationKind !== ActionDidNotRevalidate) {
         // Store whether this action triggered any revalidation
         // The action queue will use this information to potentially
         // trigger a refresh action if the action was discarded
@@ -302,7 +294,9 @@ export function serverActionReducer(
 
         // If there was a revalidation, evict the entire prefetch cache.
         // TODO: Evict only segments with matching tags and/or paths.
-        revalidateEntireCache(state.nextUrl, state.tree)
+        if (revalidationKind === ActionDidRevalidateStaticAndDynamic) {
+          revalidateEntireCache(state.nextUrl, state.tree)
+        }
       }
 
       if (redirectLocation !== undefined) {
@@ -341,7 +335,7 @@ export function serverActionReducer(
         // Did the action trigger a redirect?
         redirectLocation === undefined &&
         // Did the action revalidate any data?
-        !actionDidRevalidateCache &&
+        revalidationKind === ActionDidNotRevalidate &&
         // Did the server render new data?
         flightData === undefined
       ) {
@@ -382,7 +376,8 @@ export function serverActionReducer(
 
       // If the action triggered a revalidation of the cache, we should also
       // refresh all the dynamic data.
-      const shouldRefreshDynamicData = actionDidRevalidateCache
+      const shouldRefreshDynamicData =
+        revalidationKind !== ActionDidNotRevalidate
 
       // The server may have sent back new data. If so, we will perform a
       // "seeded" navigation that uses the data from the response.

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

@@ -14,6 +14,7 @@ import {
   NEXT_ROUTER_PREFETCH_HEADER,
   NEXT_ROUTER_SEGMENT_PREFETCH_HEADER,
   NEXT_URL,
+  NEXT_ACTION_REVALIDATED_HEADER,
 } from '../../client/components/app-router-headers'
 import {
   getAccessFallbackHTTPStatus,
@@ -63,6 +64,10 @@ import { executeRevalidates } from '../revalidation-utils'
 import { getRequestMeta } from '../request-meta'
 import { setCacheBustingSearchParam } from '../../client/components/router-reducer/set-cache-busting-search-param'
 import { getServerModuleMap } from './manifests-singleton'
+import {
+  ActionDidNotRevalidate,
+  ActionDidRevalidateStaticAndDynamic,
+} from '../../shared/lib/action-revalidation-kind'
 
 function formDataFromSearchQueryString(query: string) {
   const searchParams = new URLSearchParams(query)
@@ -141,9 +146,10 @@ function addRevalidationHeader(
   // client router cache as they may be stale. And if a path was revalidated, the
   // client needs to invalidate all subtrees below that path.
 
-  // To keep the header size small, we use a tuple of
-  // [[revalidatedPaths], isTagRevalidated ? 1 : 0, isCookieRevalidated ? 1 : 0]
-  // instead of a JSON object.
+  // TODO: Currently we don't send the specific tags or paths to the client,
+  // we just send a flag indicating that all the static data on the client
+  // should be invalidated. In the future, this will likely be a Bloom filter
+  // or bitmask of some kind.
 
   // TODO-APP: Currently the prefetch cache doesn't have subtree information,
   // so we need to invalidate the entire cache if a path was revalidated.
@@ -157,10 +163,22 @@ function addRevalidationHeader(
     ? 1
     : 0
 
-  res.setHeader(
-    'x-action-revalidated',
-    JSON.stringify([[], isTagRevalidated, isCookieRevalidated])
-  )
+  // First check if a tag, cookie, or path was revalidated.
+  if (isTagRevalidated || isCookieRevalidated) {
+    res.setHeader(
+      NEXT_ACTION_REVALIDATED_HEADER,
+      JSON.stringify(ActionDidRevalidateStaticAndDynamic)
+    )
+  } else if (
+    // Check for refresh() actions. This will invalidate only the dynamic data.
+    workStore.pathWasRevalidated !== undefined &&
+    workStore.pathWasRevalidated !== ActionDidNotRevalidate
+  ) {
+    res.setHeader(
+      NEXT_ACTION_REVALIDATED_HEADER,
+      JSON.stringify(workStore.pathWasRevalidated)
+    )
+  }
 }
 
 /**
@@ -1137,7 +1155,9 @@ export async function handleAction({
           // If the page was not revalidated, or if the action was forwarded
           // from another worker, we can skip rendering the page.
           skipPageRendering:
-            !workStore.pathWasRevalidated || actionWasForwarded,
+            workStore.pathWasRevalidated === undefined ||
+            workStore.pathWasRevalidated === ActionDidNotRevalidate ||
+            actionWasForwarded,
           temporaryReferences,
         }),
       }
@@ -1170,7 +1190,9 @@ async function executeActionAndPrepareForRender<
 
     // If the page was not revalidated, or if the action was forwarded from
     // another worker, we can skip rendering the page.
-    skipPageRendering ||= !workStore.pathWasRevalidated
+    skipPageRendering ||=
+      workStore.pathWasRevalidated === undefined ||
+      workStore.pathWasRevalidated === ActionDidNotRevalidate
 
     return { actionResult, skipPageRendering }
   } finally {

packages/next/src/server/app-render/work-async-storage.external.ts

@@ -10,6 +10,7 @@ import type { CacheLife } from '../use-cache/cache-life'
 import { workAsyncStorageInstance } from './work-async-storage-instance' with { 'turbopack-transition': 'next-shared' }
 import type { LazyResult } from '../lib/lazy-result'
 import type { DigestedError } from './create-error-handler'
+import type { ActionRevalidationKind } from '../../shared/lib/action-revalidation-kind'
 
 export interface WorkStore {
   readonly isStaticGeneration: boolean
@@ -61,7 +62,7 @@ export interface WorkStore {
   invalidDynamicUsageError?: Error
 
   nextFetchId?: number
-  pathWasRevalidated?: boolean
+  pathWasRevalidated?: ActionRevalidationKind
 
   /**
    * Tags that were revalidated during the current request. They need to be sent

packages/next/src/server/web/spec-extension/adapters/request-cookies.ts

@@ -4,6 +4,7 @@ import { ResponseCookies } from '../cookies'
 import { ReflectAdapter } from './reflect'
 import { workAsyncStorage } from '../../../app-render/work-async-storage.external'
 import type { RequestStore } from '../../../app-render/work-unit-async-storage.external'
+import { ActionDidRevalidateStaticAndDynamic } from '../../../../shared/lib/action-revalidation-kind'
 
 /**
  * @internal
@@ -116,7 +117,7 @@ export class MutableRequestCookiesAdapter {
       // TODO-APP: change method of getting workStore
       const workStore = workAsyncStorage.getStore()
       if (workStore) {
-        workStore.pathWasRevalidated = true
+        workStore.pathWasRevalidated = ActionDidRevalidateStaticAndDynamic
       }
 
       const allCookies = responseCookies.getAll()

packages/next/src/server/web/spec-extension/revalidate.ts

@@ -11,6 +11,10 @@ import { workAsyncStorage } from '../../app-render/work-async-storage.external'
 import { workUnitAsyncStorage } from '../../app-render/work-unit-async-storage.external'
 import { DynamicServerError } from '../../../client/components/hooks-server-context'
 import { InvariantError } from '../../../shared/lib/invariant-error'
+import {
+  ActionDidRevalidateDynamicOnly,
+  ActionDidRevalidateStaticAndDynamic as ActionDidRevalidate,
+} from '../../../shared/lib/action-revalidation-kind'
 
 type CacheLifeConfig = {
   expire?: number
@@ -73,8 +77,9 @@ export function refresh() {
   }
 
   if (workStore) {
-    // TODO: break this to it's own field
-    workStore.pathWasRevalidated = true
+    // The Server Action version of refresh() only revalidates the dynamic data
+    // on the client. It doesn't affect cached data.
+    workStore.pathWasRevalidated = ActionDidRevalidateDynamicOnly
   }
 }
 
@@ -226,6 +231,6 @@ function revalidate(
 
   if (!profile || cacheLife?.expire === 0) {
     // TODO: only revalidate if the path matches
-    store.pathWasRevalidated = true
+    store.pathWasRevalidated = ActionDidRevalidate
   }
 }

packages/next/src/shared/lib/action-revalidation-kind.ts

@@ -0,0 +1,5 @@
+export type ActionRevalidationKind = 0 | 1 | 2
+
+export const ActionDidNotRevalidate = 0
+export const ActionDidRevalidateStaticAndDynamic = 1
+export const ActionDidRevalidateDynamicOnly = 2

test/e2e/app-dir/segment-cache/refresh/app/dashboard/client.tsx

@@ -11,7 +11,7 @@ export function ClientRefreshButton() {
         router.refresh()
       }}
     >
-      Refresh
+      Client refresh
     </button>
   )
 }

test/e2e/app-dir/segment-cache/refresh/app/dashboard/layout.tsx

@@ -1,5 +1,19 @@
 import { LinkAccordion } from '../../components/link-accordion'
 import { ClientRefreshButton } from './client'
+import { refresh } from 'next/cache'
+
+function ServerRefreshButton() {
+  return (
+    <form
+      action={async () => {
+        'use server'
+        refresh()
+      }}
+    >
+      <button id="server-refresh-button">Server refresh</button>
+    </form>
+  )
+}
 
 export default function DashboardLayout({
   navbar,
@@ -14,6 +28,7 @@ export default function DashboardLayout({
         {navbar}
         <div>
           <ClientRefreshButton />
+          <ServerRefreshButton />
         </div>
         <ul>
           <li>
@@ -22,6 +37,9 @@ export default function DashboardLayout({
           <li>
             <LinkAccordion href="/dashboard/analytics">Analytics</LinkAccordion>
           </li>
+          <li>
+            <LinkAccordion href="/docs">Docs</LinkAccordion>
+          </li>
         </ul>
       </div>
       <div>{main}</div>

test/e2e/app-dir/segment-cache/refresh/app/docs/page.tsx

@@ -0,0 +1,3 @@
+export default function DocsPage() {
+  return <div id="docs-page">Static docs page</div>
+}