Batch-purge changed content by per-page surrogate key (#62454)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 80d768a6-3069-432e-aae6-4d9cbd1e38be
Copilot-Session: 11731c34-4a31-4175-ba46-4970237ba75d

Author: heiskr

.github/workflows/purge-fastly.yml

@@ -1,18 +1,15 @@
 name: Purge Fastly
 
-# **What it does**: Purges Fastly after a deploy and on demand. Soft purge by
-#   default; can hard purge specific languages, or hard purge the ENTIRE cache.
-# **Why we have it**: So that, right after a production deploy, we start afresh,
-#   and so docs engineering can clear a bad cache state without the Fastly UI.
-# **Who does it impact**: Writers and engineers. A full purge impacts all readers,
-#   origin sees a traffic spike while the cache refills, so it's gated below.
+# **What it does**:
+#   On production deploy, hard-purge the changed English content pages by key.
+#   On demand, soft or hard purge language keys, a single key, or entire cache.
+# **Why we have it**: So a just-deployed change is visible right away, and so
+#   docs engineering can clear a bad cache state without the Fastly UI.
+# **Who does it impact**: Writers and engineers. A full purge impacts all readers
+#   and spikes origin traffic while the cache refills, so it's gated below.
 
 on:
   deployment_status:
-  schedule:
-    # Daily soft purge of all languages to catch reusables and AUTOTITLE links.
-    # Intentionally off-peak, around 6-7pm PT.
-    - cron: '20 2 * * *'
   workflow_dispatch:
     inputs:
       languages:
@@ -89,26 +86,22 @@ jobs:
             exit 1
           fi
 
-      - name: Purge Fastly
-        # Auto post-deploy runs wait for the build, purge English only (temporary),
-        # and stay soft. The daily scheduled run waits for nothing, purges all
-        # languages (blank = all), and stays soft. A manual run uses the inputs:
-        # blank languages = all, the `hard` toggle, or a confirmed full-cache purge.
-        #
+      - name: Wait for production to serve this build
+        if: ${{ github.event_name == 'deployment_status' }}
+        run: npm run wait-for-build
+
+      - name: Purge Fastly (manual)
         # Raw inputs are passed through the environment and quoted, never spliced
         # into the command string, so a value like `en' --everything` can't break
         # out of its argument and inject another flag.
+        if: ${{ github.event_name == 'workflow_dispatch' }}
         env:
-          EVENT_NAME: ${{ github.event_name }}
           LANGUAGES_INPUT: ${{ inputs.languages }}
           HARD_INPUT: ${{ inputs.hard }}
           EVERYTHING_INPUT: ${{ inputs.everything }}
         run: |
           args=()
-          if [ "$EVENT_NAME" = "deployment_status" ]; then
-            args+=(--wait-for-build)
-            args+=(--languages en)
-          elif [ -n "$LANGUAGES_INPUT" ]; then
+          if [ -n "$LANGUAGES_INPUT" ]; then
             args+=(--languages "$LANGUAGES_INPUT")
           fi
           if [ "$HARD_INPUT" = "true" ]; then
@@ -119,14 +112,9 @@ jobs:
           fi
           npm run purge-fastly -- "${args[@]}"
 
-      - name: Hard-purge changed English content URLs
-        # Prod deploys only. The soft purge above just marks `language:en` stale,
-        # so stale-while-revalidate can keep serving the pre-deploy copy of a
-        # just-changed page for a while. This evicts the specific English URLs
-        # whose content/ files changed in this deploy, so the next request fetches
-        # fresh. By the time the deploy succeeds the old pods are already gone, so
-        # the refill is deterministically the new content. data/ changes stay
-        # covered by the soft purge above (too many URLs to enumerate cheaply).
+      - name: Hard-purge changed English content pages
+        # On prod deploys, evict the surrogate keys of the English content pages
+        # whose content/ files changed in this deploy.
         if: ${{ github.event_name == 'deployment_status' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package.json

@@ -82,6 +82,7 @@
     "prevent-pushes-to-main": "tsx src/workflows/prevent-pushes-to-main.ts",
     "purge-fastly": "tsx src/workflows/purge-fastly.ts",
     "purge-fastly-changed-content": "tsx src/workflows/purge-fastly-changed-content.ts",
+    "wait-for-build": "tsx src/workflows/wait-for-build.ts",
     "readability-report": "tsx src/workflows/experimental/readability-report.ts",
     "ready-for-docs-review": "tsx src/workflows/ready-for-docs-review.ts",
     "release-banner": "tsx src/ghes-releases/scripts/release-banner.ts",

src/frame/middleware/set-fastly-surrogate-key.ts

@@ -46,6 +46,7 @@ export function setLanguageFastlySurrogateKey(
     langCode: req.language,
     productId: productSurrogateId(context?.page),
     versionKey: versionSurrogateKey(context?.currentVersionObj),
+    relativePath: context?.page?.relativePath,
   })
   res.set(KEY, keys.join(' '))
   return next()
@@ -58,29 +59,26 @@ export function makeLanguageSurrogateKey(langCode?: string) {
   return `language:${langCode}`
 }
 
-// Build the fine-grained surrogate keys for a content response (docs-engineering#6719).
-// A content page is exactly one of each axis, so ~4 keys per page, well under
+// Build the fine-grained surrogate keys for a content response.
+// A content page is exactly one of each axis, so ~5 keys per page, well under
 // Fastly's 16 KB Surrogate-Key header limit:
 //
 //   language:<code>              (also emitted for non-content responses)
 //   product:<top-level dir>      e.g. product:actions      (~36)
 //   version:<short release slug> e.g. version:ghes-3.14     (~7-8)
 //   product:<x>,language:<y>     compound, for targeted translation purges
+//   language:<code>,path:<path>  compound, one key per source page, all versions
 //
-// These keys are inert: nothing purges the new keys yet. docs-engineering#6720
-// will use them to target the tightest key that covers a deploy instead of
-// soft-purging a whole language. Space is the Fastly delimiter; colons and
-// commas are fine (we already ship `language:en` and `api-search:en`). The
-// language key stays first so anything that only reads the first token (e.g.
-// the caching-headers test helper) keeps working.
 export function makeContentSurrogateKeys({
   langCode,
   productId,
   versionKey,
+  relativePath,
 }: {
   langCode?: string
   productId?: string
   versionKey?: string
+  relativePath?: string
 }): string[] {
   const keys = [makeLanguageSurrogateKey(langCode)]
   if (productId) {
@@ -92,9 +90,23 @@ export function makeContentSurrogateKeys({
   if (versionKey) {
     keys.push(`version:${versionKey}`)
   }
+  const pageKey = makePageSurrogateKey(langCode, relativePath)
+  if (pageKey) {
+    keys.push(pageKey)
+  }
   return keys
 }
 
+// One surrogate key per source page, e.g. `language:en,path:actions/foo.md`,
+// covering every version-URL of the page. A pure function of language and
+// relativePath so the purge job can rebuild the same key from a changed file's
+// path. Language-scoped so an English deploy doesn't evict translations. Returns
+// undefined for non-content responses.
+export function makePageSurrogateKey(langCode?: string, relativePath?: string): string | undefined {
+  if (!langCode || !relativePath) return undefined
+  return `language:${langCode},path:${relativePath}`
+}
+
 // Derive the product id for the `product:` surrogate key from a content page's
 // path. The top-level content directory is the product id (mirrors
 // Page.parentProductId), e.g. `actions`. Returns undefined for non-content

src/frame/tests/server.ts

@@ -9,6 +9,7 @@ import { loadPages } from '@/frame/lib/page-data'
 import {
   SURROGATE_ENUMS,
   makeLanguageSurrogateKey,
+  makePageSurrogateKey,
 } from '@/frame/middleware/set-fastly-surrogate-key'
 
 interface Category {
@@ -97,12 +98,14 @@ describe('server', () => {
     const res = await get('/en/get-started')
     expect(res.statusCode).toBe(200)
     const keys = res.headers['surrogate-key'].split(/\s/g)
-    // Language key stays first for anything that only reads the first token.
     expect(keys[0]).toBe(makeLanguageSurrogateKey('en'))
     expect(keys).toContain('product:get-started')
     expect(keys).toContain('product:get-started,language:en')
     expect(keys.some((key: string) => /^version:.+/.test(key))).toBe(true)
-    // Stays well under Fastly's limits: about 4 keys per page.
+    // Exact key, not just a pattern, to lock the render side byte-for-byte to what
+    // the purge job rebuilds from a changed file path (content/get-started/index.md).
+    expect(keys).toContain('language:en,path:get-started/index.md')
+    expect(keys).toContain(makePageSurrogateKey('en', 'get-started/index.md'))
     expect(keys.length).toBeLessThanOrEqual(6)
   })