POC of "fake" PPR for data

.changeset/ppr-cache-tag-prefix.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Prefix all cache tags with `ppr:` when rendering under the PPR route, so PPR cache entries are partitioned from the static ones.

.changeset/ppr-request-signature.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Require a GitBook-secret signature on the `x-gbo-*` PPR headers, so a client can't opt itself into the PPR route.

.changeset/ppr-token-exchange.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Exchange the PPR revalidation token for a content API token scoped to each PPR component, so the API receives claims it understands and the header and table of contents can be cached across pages.

.github/composite/deploy-cloudflare/action.yaml

@@ -48,6 +48,7 @@ runs:
               GITBOOK_ICONS_TOKEN: ${{ inputs.opItem }}/GITBOOK_ICONS_TOKEN
               NEXT_SERVER_ACTIONS_ENCRYPTION_KEY: ${{ inputs.opItem }}/NEXT_SERVER_ACTIONS_ENCRYPTION_KEY
               GITBOOK_SECRET: ${{ inputs.opItem }}/GITBOOK_SECRET
+              GITBOOK_EXCHANGE_TOKEN_URL: ${{ inputs.opItem }}/GITBOOK_EXCHANGE_TOKEN_URL
               GITBOOK_APP_URL: ${{ inputs.opItem }}/GITBOOK_APP_URL
               GITBOOK_API_URL: ${{ inputs.opItem }}/GITBOOK_API_URL
               GITBOOK_API_PUBLIC_URL: ${{ inputs.opItem }}/GITBOOK_API_PUBLIC_URL

.github/composite/deploy-vercel/action.yaml

@@ -50,6 +50,7 @@ runs:
               GITBOOK_ICONS_URL: ${{ inputs.opItem }}/GITBOOK_ICONS_URL
               GITBOOK_ICONS_TOKEN: ${{ inputs.opItem }}/GITBOOK_ICONS_TOKEN
               GITBOOK_SECRET: ${{ inputs.opItem }}/GITBOOK_SECRET
+              GITBOOK_EXCHANGE_TOKEN_URL: ${{ inputs.opItem }}/GITBOOK_EXCHANGE_TOKEN_URL
               GITBOOK_APP_URL: ${{ inputs.opItem }}/GITBOOK_APP_URL
               GITBOOK_API_URL: ${{ inputs.opItem }}/GITBOOK_API_URL
               GITBOOK_API_PUBLIC_URL: ${{ inputs.opItem }}/GITBOOK_API_PUBLIC_URL

AGENTS.md

@@ -24,6 +24,35 @@ Examples:
 - `http://localhost:3000/url/gitbook.com/docs`
 - `http://localhost:3000/url/open-source.gitbook.io/midjourney`
 
+### PPR routes
+
+PPR requests are normally resolved upstream and arrive with a large set of `x-gbo-*` headers, so they
+can't be reproduced by hitting the dev server directly. `bun run dev:ppr` (from `packages/gitbook`)
+starts a dev-only proxy on port 3001 that resolves the URL, injects those headers and signs them.
+The app rejects an unsigned set, so `GITBOOK_SECRET` must be set in `.env.local` (any value works
+locally, as long as both processes read the same one).
+
+The app also exchanges the PPR token for one scoped to each component, against
+`GITBOOK_EXCHANGE_TOKEN_URL`. That endpoint only accepts a revalidation token, which the
+published-URLs lookup never returns, so the proxy mints one with `PPR_DEV_API_TOKEN_SECRET` — a
+local-only stand-in for the API token secret the cache worker holds in production. It must match the
+secret the target `/token` endpoint verifies with, so local PPR needs a local gitbook-x sites stack.
+The secret is read only by the proxy script: never add it to `src/lib/env`, `next.config.mjs` or a
+deploy workflow.
+
+```
+GITBOOK_SECRET=<any value>
+GITBOOK_EXCHANGE_TOKEN_URL=http://localhost:8788/token
+PPR_DEV_API_TOKEN_SECRET=<local gitbook-x functionsConfig.api.tokenSecret>
+```
+
+```
+http://localhost:3001/url/<published-gitbook-url>
+```
+
+Responses carry `x-gitbook-route-type: ppr` when the PPR route was used. Hot reload doesn't work
+through the proxy (its websocket can't be forwarded), so keep using port 3000 while iterating.
+
 ## Architecture
 
 ```

packages/gitbook/e2e/internal.spec.ts

@@ -1,4 +1,4 @@
-import { type Page, expect } from '@playwright/test';
+import { type Page, expect, test } from '@playwright/test';
 import jwt from 'jsonwebtoken';
 
 import {
@@ -15,6 +15,7 @@ import {
 } from '@gitbook/api';
 import type { GitBookStandalone } from '@gitbook/embed';
 
+import { signPPRRequestHeaders } from '../src/lib/ppr';
 import { getGitBookPreviewURL, getSiteAPIToken } from '../tests/utils';
 import {
     type Test,
@@ -315,6 +316,49 @@ const searchTestCases: Test[] = [
     },
 ];
 
+const PPR_TEST_SITE_URL = 'https://gitbook-open-e2e-sites.gitbook.io/gitbook-doc/';
+
+/**
+ * The `x-gbo-*` set GBO resolves upstream. `sign` mirrors what GBO does with `GITBOOK_SECRET`;
+ * without it the app must fall back to resolving the URL itself.
+ */
+async function getPPRHeaders(options: { sign: string | undefined }) {
+    const data = await getSiteAPIToken(PPR_TEST_SITE_URL);
+
+    if (!data.revision) {
+        throw new Error('PPR test site did not resolve to content with a revision');
+    }
+
+    const headers = new Headers({
+        'x-gbo-site': data.site,
+        'x-gbo-site-section': data.siteSection ?? '',
+        'x-gbo-site-space': data.siteSpace,
+        'x-gbo-space': data.space,
+        'x-gbo-site-base-path': data.siteBasePath,
+        'x-gbo-base-path': data.basePath,
+        'x-gbo-pathname': data.pathname || '/',
+        'x-gbo-organization': data.organization,
+        'x-gbo-share-key': data.shareKey ?? '',
+        'x-gbo-complete': String(data.complete),
+        'x-gbo-context-id': data.contextId ?? '',
+        'x-gbo-canonical-url': data.canonicalUrl,
+        'x-gbo-preview': data.preview === undefined ? '' : String(data.preview),
+        'x-gbo-revision': data.revision ?? '',
+        'x-gbo-change-request': data.changeRequest ?? '',
+        'x-gbo-api-token': data.apiToken,
+        'x-gbo-revalidation-id': 'ppr-e2e-revalidation',
+        'x-gbo-default-site-section': data.siteSection ?? '',
+        'x-gbo-default-site-space': data.siteSpace,
+        'x-gbo-default-space': data.space,
+    });
+
+    if (options.sign) {
+        await signPPRRequestHeaders(headers, options.sign);
+    }
+
+    return Object.fromEntries(headers.entries());
+}
+
 const testCases: TestsCase[] = [
     {
         name: 'GitBook Site (Single Variant)',
@@ -325,6 +369,37 @@ const testCases: TestsCase[] = [
                 url: '',
                 run: waitForCookiesDialog,
             },
+            {
+                name: 'PPR route renders the site shell',
+                url: '',
+                headers: () => getPPRHeaders({ sign: process.env.GITBOOK_SECRET }),
+                screenshot: false,
+                run: async (page, response) => {
+                    // The deployment signs with its own `GITBOOK_SECRET`; without it here the
+                    // headers can only be tested for rejection (see the test below).
+                    test.skip(
+                        !process.env.GITBOOK_SECRET,
+                        'GITBOOK_SECRET is required to sign PPR headers'
+                    );
+                    expect(response?.headers()['x-gitbook-route-type']).toBe('ppr');
+                    await expect(page.locator('header[data-gb-site-header]')).toBeVisible();
+                    await expect(page.getByTestId('table-of-contents')).toBeVisible();
+                    await expect(page.locator('main')).toBeVisible();
+                },
+            },
+            {
+                name: 'PPR route ignores an unsigned header set',
+                url: '',
+                headers: () => getPPRHeaders({ sign: undefined }),
+                screenshot: false,
+                run: async (page, response) => {
+                    // Anyone can send these headers, so an unsigned set must never take the PPR
+                    // path: it skips URL resolution and visitor-auth, and picks the cache key.
+                    expect(response?.headers()['x-gitbook-route-type']).not.toBe('ppr');
+                    await expect(page.locator('header[data-gb-site-header]')).toBeVisible();
+                    await expect(page.locator('main')).toBeVisible();
+                },
+            },
             {
                 name: 'No variants dropdown',
                 url: '',

packages/gitbook/e2e/util.ts

@@ -44,6 +44,10 @@ export interface Test {
      */
     url: string | (() => string | Promise<string>);
     cookies?: Parameters<BrowserContext['addCookies']>[0];
+    /** Headers to send with the main document request. */
+    headers?:
+        | Record<string, string>
+        | (() => Record<string, string> | Promise<Record<string, string>>);
     /**
      * Test to run
      */
@@ -279,6 +283,11 @@ export function runTestCases(testCases: TestsCase[]) {
                         } catch {}
                     });
 
+                    const headers =
+                        typeof testEntry.headers === 'function'
+                            ? await testEntry.headers()
+                            : testEntry.headers;
+
                     // Set the header to disable the Vercel toolbar
                     // But only on the main document as it'd cause CORS issues on other resources
                     await page.route('**/*', async (route, request) => {
@@ -287,6 +296,7 @@ export function runTestCases(testCases: TestsCase[]) {
                                 headers: {
                                     ...request.headers(),
                                     'x-vercel-skip-toolbar': '1',
+                                    ...headers,
                                 },
                             });
                         } else {

packages/gitbook/next.config.mjs

@@ -88,6 +88,7 @@ const nextConfig = {
         GITBOOK_API_TOKEN: process.env.GITBOOK_API_TOKEN,
         GITBOOK_ASSETS_PREFIX: process.env.GITBOOK_ASSETS_PREFIX,
         GITBOOK_SECRET: process.env.GITBOOK_SECRET,
+        GITBOOK_EXCHANGE_TOKEN_URL: process.env.GITBOOK_EXCHANGE_TOKEN_URL,
         GITBOOK_IMAGE_RESIZE_SIGNING_KEY: process.env.GITBOOK_IMAGE_RESIZE_SIGNING_KEY,
         GITBOOK_IMAGE_RESIZE_MODE: process.env.GITBOOK_IMAGE_RESIZE_MODE,
         GITBOOK_FONTS_URL: process.env.GITBOOK_FONTS_URL,

packages/gitbook/package.json

@@ -122,6 +122,7 @@
         "generate:fonts": "bun ./scripts/generate-font-faces.ts",
         "clean": "rm -rf ./.next && rm -rf ./public/~gitbook/static/icons && rm -rf ./public/~gitbook/static/math && rm -rf ./public/~gitbook/static/mermaid && rm -rf ./public/~gitbook/static/scalar && rm -rf ./public/~gitbook/static/fonts",
         "dev": "bun run generate:assets && env-cmd --silent -f ../../.env.local next --webpack",
+        "dev:ppr": "env-cmd --silent -f ../../.env.local bun scripts/ppr-dev-proxy.ts",
         "build": "bun run generate:assets && next build --webpack",
         "build:local": "bun run generate:assets && GITBOOK_URL=http://localhost:3000 next build --webpack",
         "check:css-browser-compatibility": "bun scripts/check-css-browser-compatibility.ts",