Compare commits

...

7 Commits

Author SHA1 Message Date
Nolann B. 262749a0b1 Copy the current spec's server in OpenAPI endpoint URLs (#4794) 2026-11-16 20:12:40 +01:00
Peter White b145bfcdff Stop caching site search results (#4782) 2026-11-16 16:43:30 +01:00
Peter White 1c718491bd Follow the API's cache lifetime for site data (#4790) 2026-11-16 14:10:44 +01:00
Viktor Renkema 8dd308bd90 Ignore categories when resolving tag assignments (#4736) 2026-11-16 10:49:18 +01:00
Peter White c09da2ec1a Show H3 headings in the page outline (#4787) 2026-11-16 10:47:57 +01:00
conico974 9fcde5f487 Reduce memory and CPU use of the OpenNext workers (#4788)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 10:17:23 +01:00
conico974 c85d84fc1d Store 'use cache' entries in R2 again (#4789)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 10:15:41 +01:00
41 changed files with 417 additions and 242 deletions
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Fix `'use cache'` entries never being stored in or read from R2 and the regional cache on Cloudflare.
@@ -0,0 +1,5 @@
---
"@gitbook/icons": minor
---
Add a `@gitbook/icons/validateIconName` entry that validates icon names without loading the icon labels and search terms.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Reduce memory and CPU use of the OpenNext workers: minify the middleware, resolve the site context once per request, cache parsed OpenAPI descriptions across a spec, drop the redis client and the unused force-revalidate route from the server bundle.
@@ -0,0 +1,5 @@
---
"@gitbook/react-openapi": patch
---
Copy the current spec's server in OpenAPI endpoint URLs instead of a server kept from a previously visited page.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Show H3 headings in the page outline.
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Stop caching site search results in the framework cache, so every search reaches the API.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Follow the API's cache lifetime for site data, so a site preview shows layout changes soon after they are saved.
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Ignore tag category references when displaying assigned tags and update filters.
+10
View File
@@ -59,6 +59,16 @@ Run a specific test file:
cd packages/gitbook && bun test src/lib/cache.test.ts
```
## Bumping Next.js or OpenNext
Type checks and unit tests miss runtime regressions: OpenNext 4.1.15 changed the composable cache key format, and every `'use cache'` call silently missed for days. Before committing a bump of `next`, `@opennextjs/aws` or `@opennextjs/cloudflare`, run both runtimes locally from `packages/gitbook`:
1. **Next**: `bun run build:local && bun run start`, then load several distinct pages under `http://localhost:3000/url/gitbook.com/docs`.
2. **OpenNext**: `bun run build:cloudflare`, delete `openNext/customWorkers/.wrangler` (stale cache hits otherwise skip the server), then run `bun run dev:cf:server` and `bun run dev:cf:middleware` and load several distinct pages under `http://127.0.0.1:8771/url/gitbook.com/docs`.
3. Diff the changed OpenNext versions' adapters that call our overrides in `openNext/` (incremental, composable and tag cache, queue), e.g. with `npm pack` of the old and new versions.
The bump is safe when every page returns 200 on both runtimes and the server logs show no cache errors (grep `Failed to` and `regional cache`). Report the pages checked and the log result in the PR.
## Changesets
After committing code changes, create a changeset for the affected package:
+12
View File
@@ -1,6 +1,7 @@
// @ts-check
import { networkInterfaces } from 'node:os';
import { fileURLToPath } from 'node:url';
// Next blocks its dev client and HMR when a physical device opens the server over a LAN address.
// Needed to hydrate the dev client on physical phones/tablets over the internal network
@@ -119,6 +120,17 @@ const nextConfig = {
],
},
webpack(config, { isServer }) {
if (isServer) {
// mcp-handler only needs redis for SSE, which we disable: keep the client out of the server bundle.
config.resolve.alias = {
...config.resolve.alias,
redis$: fileURLToPath(new URL('./src/lib/mcp/redis-stub.ts', import.meta.url)),
};
}
return config;
},
async headers() {
return [
{
@@ -3,6 +3,7 @@
"name": "gitbook-open-v2",
"compatibility_date": "2026-04-02",
"keep_names": false,
"minify": true,
"compatibility_flags": [
"nodejs_compat",
"allow_importable_env",
@@ -0,0 +1,23 @@
import { describe, expect, it } from 'bun:test';
import { createHash } from 'node:crypto';
import { GitbookIncrementalCache } from './incrementalCache';
describe('GitbookIncrementalCache.getR2Key', () => {
const cache = new GitbookIncrementalCache();
it('accepts the hashed composable key passed by OpenNext', () => {
const storageKey = createHash('sha256').update('["build-id","action",[]]').digest('hex');
const key = cache.getR2Key(storageKey, 'composable');
const hash = createHash('sha256').update(storageKey).digest('hex');
expect(key).toBe(`incremental-cache/dataCache/${hash}.composable`);
});
it('maps distinct composable keys to distinct R2 keys', () => {
expect(cache.getR2Key('a'.repeat(64), 'composable')).not.toBe(
cache.getR2Key('b'.repeat(64), 'composable')
);
});
});
@@ -118,15 +118,8 @@ export class GitbookIncrementalCache implements IncrementalCache {
}
}
// Utility function to generate keys for R2/Cache API
getR2Key(initialKey: string, cacheType: CacheEntryType = 'cache'): string {
let key = initialKey;
if (cacheType === 'composable') {
// For composable cache, we need to discard the build ID from the key
const [_buildId, ...restOfTheKey] = JSON.parse(initialKey);
key = JSON.stringify([...restOfTheKey]);
}
// OpenNext pre-hashes composable keys with the build ID in them: no reuse across deploys.
getR2Key(key: string, cacheType: CacheEntryType = 'cache'): string {
const hash = createHash('sha256').update(key).digest('hex');
return `${DEFAULT_PREFIX}/${cacheType === 'cache' ? process.env?.NEXT_BUILD_ID : 'dataCache'}/${hash}.${cacheType}`.replace(
/\/+/g,
+1 -1
View File
@@ -135,7 +135,7 @@
"e2e": "playwright test e2e/internal.spec.ts e2e/cookie-banner.spec.ts e2e/pdf.spec.ts e2e/select.spec.ts e2e/tabs-overflow.spec.ts --project=chromium",
"e2e-customers": "playwright test e2e/customers.spec.ts --project=chromium",
"e2e-style-perf": "playwright test e2e/style-perf.spec.ts --project=chromium --reporter=list",
"unit": "bun run generate:assets && bun test {src,packages} --preload ./tests/preload-bun.ts",
"unit": "bun run generate:assets && bun test {src,packages,openNext} --preload ./tests/preload-bun.ts",
"e2e-browserless": "bun test ./tests/",
"typecheck": "tsc --noEmit"
},
@@ -50,6 +50,7 @@ export async function handleMcpRequest(
streamableHttpEndpoint: context.linker.toPathInSite(endpoint),
maxDuration: 60,
verboseLogs: true,
// SSE needs redis, which next.config.mjs stubs out of the server bundle.
disableSse: true,
}
);
+21 -2
View File
@@ -1,5 +1,6 @@
import { jwtDecode } from 'jwt-decode';
import { forbidden, notFound } from 'next/navigation';
import { cache } from 'react';
import rison from 'rison';
import type { SiteAPIToken } from '@gitbook/api';
@@ -27,7 +28,17 @@ export type RouteParams = RouteLayoutParams & {
/**
* Get the static context when rendering statically a site.
*/
export async function getStaticSiteContext(params: RouteLayoutParams) {
export function getStaticSiteContext(params: RouteLayoutParams) {
return getStaticSiteContextCached(params.mode, params.siteURL, params.siteData);
}
// Layouts, pages and their metadata functions each resolve the context: share it per request.
// Keyed on the raw strings as `params` objects aren't guaranteed to be the same reference.
const getStaticSiteContextCached = cache((mode: string, siteURL: string, siteData: string) =>
resolveStaticSiteContext({ mode, siteURL, siteData })
);
async function resolveStaticSiteContext(params: RouteLayoutParams) {
const siteURL = getSiteURLFromParams(params);
const siteURLData = getSiteURLDataFromParams(params);
@@ -57,7 +68,15 @@ export async function getStaticSiteContext(params: RouteLayoutParams) {
* Get the site context when rendering dynamically.
* The context will depend on the request.
*/
export async function getDynamicSiteContext(params: RouteLayoutParams) {
export function getDynamicSiteContext(params: RouteLayoutParams) {
return getDynamicSiteContextCached(params.mode, params.siteURL, params.siteData);
}
const getDynamicSiteContextCached = cache((mode: string, siteURL: string, siteData: string) =>
resolveDynamicSiteContext({ mode, siteURL, siteData })
);
async function resolveDynamicSiteContext(params: RouteLayoutParams) {
const siteURL = getSiteURLFromParams(params);
const siteURLData = getSiteURLDataFromParams(params);
@@ -1,6 +1,6 @@
import type { DocumentBlockHint } from '@gitbook/api';
import { Icon, type IconName } from '@gitbook/icons';
import { validateIconName } from '@gitbook/icons/icons';
import { validateIconName } from '@gitbook/icons/validateIconName';
import { Block, type BlockProps } from './Block';
import { Blocks } from './Blocks';
@@ -4,7 +4,7 @@ import {
type DocumentBlockPrompt,
type SiteCustomizationSettings,
} from '@gitbook/api';
import { validateIconName } from '@gitbook/icons/icons';
import { validateIconName } from '@gitbook/icons/validateIconName';
import type { BlockProps } from '../Block';
import { CodeBlock } from '../CodeBlock';
@@ -1,6 +1,6 @@
import type { DocumentBlockTabs } from '@gitbook/api';
import type { IconName } from '@gitbook/icons';
import { validateIconName } from '@gitbook/icons/icons';
import { validateIconName } from '@gitbook/icons/validateIconName';
import type { BlockProps } from '../Block';
import { Blocks } from '../Blocks';
@@ -73,7 +73,11 @@ export function ScrollSectionsList({ sections }: { sections: DocumentSection[] }
'mt-2',
'first:mt-0',
'mb-0.5',
section.depth > 1 && ['ml-3', 'my-0', 'sidebar-list-line:ml-0']
section.depth > 1 && [
section.depth > 2 ? 'ml-6' : 'ml-3',
'my-0',
'sidebar-list-line:ml-0',
]
)}
ref={activeId === section.id ? activeItemRef : null}
{...(section.tags !== undefined
@@ -119,7 +123,9 @@ export function ScrollSectionsList({ sections }: { sections: DocumentSection[] }
section.depth > 1 && [
'subitem',
'sidebar-list-line:pl-6',
section.depth > 2
? 'sidebar-list-line:pl-9'
: 'sidebar-list-line:pl-6',
'opacity-8',
'contrast-more:opacity-11',
+25 -61
View File
@@ -1,4 +1,4 @@
import { afterAll, afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
import { afterAll, afterEach, describe, expect, it, mock } from 'bun:test';
const cacheLife = mock((_profile: unknown) => {});
const cacheTag = mock((..._tags: string[]) => {});
@@ -6,6 +6,12 @@ const cacheTag = mock((..._tags: string[]) => {});
const realNextCache = await import('next/cache');
mock.module('next/cache', () => ({ ...realNextCache, cacheLife, cacheTag }));
const realGlobals = await import('@/lib/env/globals');
mock.module('@/lib/env/globals', () => ({
...realGlobals,
GITBOOK_API_URL: 'https://api.example.com/cache/',
}));
const { createDataFetcher } = await import('./api');
const originalFetch = globalThis.fetch;
@@ -13,75 +19,33 @@ const originalFetch = globalThis.fetch;
afterAll(() => mock.restore());
describe('searchSiteContent', () => {
beforeEach(() => {
cacheLife.mockClear();
cacheTag.mockClear();
});
afterEach(() => {
globalThis.fetch = originalFetch;
});
function mockFetch(impl: () => Promise<Response>) {
globalThis.fetch = mock(impl);
}
function search() {
return createDataFetcher().searchSiteContent({
it('reaches the API through the gateway on every search, without caching', async () => {
const fetchMock = mock((_input: unknown, _init?: RequestInit) =>
Promise.resolve(Response.json({ items: [] }))
);
globalThis.fetch = fetchMock as unknown as typeof fetch;
const dataFetcher = createDataFetcher({ apiToken: 'site-token' });
const params = {
organizationId: 'org-1',
siteId: 'site-1',
query: 'test',
scope: { mode: 'all' },
});
}
scope: { mode: 'all' as const },
};
it('caches successful results for hours with the site and response tags', async () => {
mockFetch(async () =>
Response.json(
{ items: [] },
{ headers: { 'x-gitbook-cache-tag': 'space:space-1,space:space-2' } }
)
expect(await dataFetcher.searchSiteContent(params)).toEqual({ data: [] });
expect(await dataFetcher.searchSiteContent(params)).toEqual({ data: [] });
expect(fetchMock).toHaveBeenCalledTimes(2);
const [input, init] = fetchMock.mock.calls[0]!;
expect(String(input)).toBe(
'https://api.example.com/cache/v1/orgs/org-1/sites/site-1/search'
);
const result = await search();
expect(result).toEqual({ data: [] });
expect(cacheLife.mock.calls).toEqual([['hours']]);
expect(cacheTag.mock.calls.flat()).toEqual([
'site:site-1',
'space:space-1',
'space:space-2',
]);
});
it('does not cache a transient API error', async () => {
mockFetch(async () =>
Response.json({ error: { code: 429, message: 'Namespace saturated' } }, { status: 429 })
);
const result = await search();
expect(result.error?.code).toBe(429);
expect(cacheLife.mock.calls).toEqual([[{ stale: 0, revalidate: 0, expire: 0 }]]);
});
it('does not cache a network failure', async () => {
mockFetch(() => Promise.reject(new TypeError('fetch failed')));
const result = await search();
expect(result.error?.code).toBe(500);
expect(cacheLife.mock.calls).toEqual([[{ stale: 0, revalidate: 0, expire: 0 }]]);
});
it('keeps the default cache life for a stable 404', async () => {
mockFetch(async () =>
Response.json({ error: { code: 404, message: 'Site not found' } }, { status: 404 })
);
const result = await search();
expect(result.error?.code).toBe(404);
expect(new Headers(init?.headers).get('authorization')).toBe('Bearer site-token');
expect(cacheLife).not.toHaveBeenCalled();
expect(cacheTag).not.toHaveBeenCalled();
});
});
+38 -59
View File
@@ -11,7 +11,7 @@ import {
import { getCacheTag, getComputedContentSourceCacheTags } from '@gitbook/cache-tags';
import { cache } from '../cache';
import { DataFetcherError, isTransientDataFetcherError, wrapDataFetcherError } from './errors';
import { DataFetcherError, wrapDataFetcherError } from './errors';
import type { GitBookDataFetcher } from './types';
import { GITBOOK_API_TOKEN, GITBOOK_API_URL, GITBOOK_USER_AGENT } from '@/lib/env';
import { trace } from '@/lib/tracing';
@@ -704,7 +704,7 @@ const getPublishedContentSite = cache(
}
);
cacheTag(...getCacheTagsFromResponse(res));
cacheLife('days');
cacheLifeFromResponse(res, 'days');
return res.data;
}
);
@@ -785,64 +785,43 @@ const getEmbedByUrl = cache(
}
);
// We don't use remote cache for this one because of the number of potential cache entry causing 429 on vercel runtime cache when revalidating
const searchSiteContent = cache(
async (
input: DataFetcherInput,
params: Parameters<GitBookDataFetcher['searchSiteContent']>[0]
) => {
'use cache';
cacheTag(
getCacheTag({
tag: 'site',
site: params.siteId,
})
async function searchSiteContent(
input: DataFetcherInput,
params: Parameters<GitBookDataFetcher['searchSiteContent']>[0]
) {
return wrapDataFetcherError(async () => {
return trace(
`searchSiteContent(${params.organizationId}, ${params.siteId}, ${params.query})`,
async () => {
const { organizationId, siteId, query, scope } = params;
const api = apiClient(input);
const res = await api.orgs.searchSiteContent(
organizationId,
siteId,
{
query,
...(scope.mode === 'current' && scope.restrictTo
? {
// `restrictTo` only exists in the newer `scope` request shape,
// and the published @gitbook/api types don't include it yet.
scope: {
mode: 'default',
currentSiteSpace: scope.siteSpaceId,
restrictTo: scope.restrictTo,
} as SiteSearchScope,
}
: scope),
},
{},
{
...noCacheFetchOptions,
}
);
return res.data.items;
}
);
const result = await wrapDataFetcherError(async () => {
return trace(
`searchSiteContent(${params.organizationId}, ${params.siteId}, ${params.query})`,
async () => {
const { organizationId, siteId, query, scope } = params;
const api = apiClient(input);
const res = await api.orgs.searchSiteContent(
organizationId,
siteId,
{
query,
...(scope.mode === 'current' && scope.restrictTo
? {
// `restrictTo` only exists in the newer `scope` request shape,
// and the published @gitbook/api types don't include it yet.
scope: {
mode: 'default',
currentSiteSpace: scope.siteSpaceId,
restrictTo: scope.restrictTo,
} as SiteSearchScope,
}
: scope),
},
{},
{
...noCacheFetchOptions,
}
);
cacheTag(...getCacheTagsFromResponse(res));
cacheLife('hours');
return res.data.items;
}
);
});
// Don't serve transient errors for the default 15 minutes. Only safe because search runs in
// request handlers: a page cache calling it would inherit this short life during API incidents.
if (result.error && isTransientDataFetcherError(result.error)) {
cacheLife({ stale: 0, revalidate: 0, expire: 0 });
}
return result;
}
);
});
}
const renderIntegrationUi = cache(
async (
+1 -11
View File
@@ -2,17 +2,7 @@ import { describe, expect, it } from 'bun:test';
import { GitBookAPIError } from '@gitbook/api';
import { extractCacheControl, isTransientDataFetcherError } from './errors';
describe('isTransientDataFetcherError', () => {
it.each([408, 429, 500, 502, 503, 504])('should treat %i as transient', (code) => {
expect(isTransientDataFetcherError({ code, message: 'Error' })).toBe(true);
});
it.each([400, 401, 403, 404, 410])('should treat %i as stable', (code) => {
expect(isTransientDataFetcherError({ code, message: 'Error' })).toBe(false);
});
});
import { extractCacheControl } from './errors';
describe('extractCacheControl', () => {
it('should return undefined when error has no response', () => {
-7
View File
@@ -93,13 +93,6 @@ export async function wrapDataFetcherError<T>(
}
}
/**
* Whether an error may go away on retry: timeouts, rate limits, server errors and network failures.
*/
export function isTransientDataFetcherError(error: DataFetcherErrorData): boolean {
return error.code === 408 || error.code === 429 || error.code >= 500;
}
/**
* Ignore some data fetcher errors.
*/
@@ -145,7 +145,11 @@ describe('getDocumentSections', () => {
type: 'update',
data: {
date: '2026-04-08',
tags: [{ kind: 'tag', tag: 'improvements' }],
tags: [
{ kind: 'tag', tag: 'improvements' },
{ kind: 'tag', tag: 'category' },
{ kind: 'tag', tag: 'missing' },
],
},
isVoid: false,
nodes: [
@@ -197,6 +201,7 @@ describe('getDocumentSections', () => {
...context,
revision: {
tags: [
{ slug: 'category', label: 'Products', color: 'default', kind: 'category' },
{
slug: 'improvements',
label: 'Improvements',
@@ -232,6 +237,66 @@ describe('getDocumentSections', () => {
]);
});
it('nests heading-3 under the heading before it', async () => {
const heading = (type: 'heading-1' | 'heading-2' | 'heading-3', id: string) => ({
object: 'block' as const,
type,
data: {},
meta: { id },
nodes: [
{
object: 'text' as const,
leaves: [{ object: 'leaf' as const, text: id, marks: [] }],
},
],
});
const document: JSONDocument = {
object: 'document',
data: { schemaVersion: 2 },
nodes: [
heading('heading-3', 'h3-first'),
heading('heading-2', 'h2-no-h1'),
heading('heading-3', 'h3-under-h2'),
heading('heading-1', 'h1'),
heading('heading-3', 'h3-under-h1'),
heading('heading-2', 'h2'),
heading('heading-3', 'h3-under-h1-h2'),
{
object: 'block',
type: 'stepper',
data: {},
isVoid: false,
nodes: [
{
object: 'block',
type: 'stepper-step',
data: {},
isVoid: false,
nodes: [heading('heading-3', 'h3-in-stepper')],
},
],
},
heading('heading-1', 'h1-again'),
heading('heading-3', 'h3-after-reset'),
],
};
const sections = await getDocumentSections(context, document);
expect(sections.map(({ id, depth }) => ({ id, depth }))).toEqual([
{ id: 'h3-first', depth: 1 },
{ id: 'h2-no-h1', depth: 1 },
{ id: 'h3-under-h2', depth: 2 },
{ id: 'h1', depth: 1 },
{ id: 'h3-under-h1', depth: 2 },
{ id: 'h2', depth: 2 },
{ id: 'h3-under-h1-h2', depth: 3 },
{ id: 'h3-in-stepper', depth: 3 },
{ id: 'h1-again', depth: 1 },
{ id: 'h3-after-reset', depth: 2 },
]);
});
it('extracts a single-schema openapi-schemas block as one section', async () => {
const document: JSONDocument = {
object: 'document',
+27 -8
View File
@@ -21,6 +21,14 @@ export interface DocumentSection {
tags?: string[];
}
/**
* Depth of the last heading-1 and heading-2 seen, or 0 when there is none.
*/
interface HeadingParents {
h1: number;
h2: number;
}
/**
* Extract a list of sections from a document.
*/
@@ -37,11 +45,11 @@ export async function getDocumentSections(
async function getSectionsFromNodes(
nodes: DocumentBlock[],
context: GitBookAnyContext,
initialDepth = 0,
parents: HeadingParents = { h1: 0, h2: 0 },
tags?: string[]
): Promise<DocumentSection[]> {
const sections: DocumentSection[] = [];
let depth = initialDepth;
let { h1, h2 } = parents;
for (const block of nodes) {
switch (block.type) {
@@ -50,9 +58,10 @@ async function getSectionsFromNodes(
if (!id) {
continue;
}
depth = 1;
h1 = 1;
h2 = 0;
const title = getNodeReactText(block);
sections.push(withTags({ id, title, depth: 1 }, tags));
sections.push(withTags({ id, title, depth: h1 }, tags));
continue;
}
case 'heading-2': {
@@ -60,15 +69,25 @@ async function getSectionsFromNodes(
if (!id) {
continue;
}
h2 = h1 + 1;
const title = getNodeReactText(block);
sections.push(withTags({ id, title, depth: depth > 0 ? 2 : 1 }, tags));
sections.push(withTags({ id, title, depth: h2 }, tags));
continue;
}
case 'heading-3': {
const id = block.meta?.id;
if (!id) {
continue;
}
const title = getNodeReactText(block);
sections.push(withTags({ id, title, depth: (h2 || h1) + 1 }, tags));
continue;
}
case 'columns':
case 'stepper': {
const stepNodes = await Promise.all(
block.nodes.map(async (step) =>
getSectionsFromNodes(step.nodes, context, depth, tags)
getSectionsFromNodes(step.nodes, context, { h1, h2 }, tags)
)
);
for (const stepSections of stepNodes) {
@@ -83,7 +102,7 @@ async function getSectionsFromNodes(
getSectionsFromNodes(
update.nodes as DocumentBlock[],
context,
depth,
{ h1, h2 },
resolveBlockTags(update.data.tags, revisionTags).map((tag) => tag.slug)
)
)
@@ -200,7 +219,7 @@ async function getSectionsFromNodes(
const reusableContentSections = await getSectionsFromNodes(
document.nodes,
reusableContent.context,
depth,
{ h1, h2 },
tags
);
sections.push(...reusableContentSections);
+1 -1
View File
@@ -10,9 +10,9 @@ import {
type SiteCustomizationSettings,
} from '@gitbook/api';
import { getIconStyle } from '@gitbook/icons/getIconStyle';
import { validateIconName } from '@gitbook/icons/icons';
import { type InlineIconSource, getInlineIconSourceKey } from '@gitbook/icons/IconSources';
import { type IconName, IconStyle } from '@gitbook/icons/types';
import { validateIconName } from '@gitbook/icons/validateIconName';
import { GITBOOK_ICONS_ASSET_VERSION } from '@gitbook/icons/version';
import { getAssetURL } from '@/lib/assets';
@@ -0,0 +1,7 @@
/**
* Replaces `redis` in the server bundle (see next.config.mjs). mcp-handler imports it statically
* but only uses it for SSE transport, which we disable.
*/
export function createClient(): never {
throw new Error('redis is not available: SSE transport is disabled for the MCP handler');
}
@@ -17,4 +17,22 @@ describe('#enrichFilesystem', () => {
'<p>Social platform<br>Hello</p>'
);
});
it('parses descriptions that collide with Object.prototype keys', async () => {
const { filesystem } = await parseOpenAPI({
value: JSON.stringify({
openapi: '3.0.0',
info: { title: 'Test', version: '1.0.0' },
paths: {
'/a': { get: { description: 'constructor', responses: {} } },
'/b': { get: { description: 'constructor', responses: {} } },
},
}),
rootURL: null,
});
const enriched = await enrichFilesystem(filesystem);
const paths = enriched[0]?.specification.paths;
expect(paths['/a'].get['x-gitbook-description-html']).toBe('<p>constructor</p>');
expect(paths['/b'].get['x-gitbook-description-html']).toBe('<p>constructor</p>');
});
});
+12 -9
View File
@@ -30,14 +30,17 @@ export async function enrichFilesystem(filesystem: Filesystem) {
/**
* Create a markdown parser that caches the results of parsing.
*/
const createMarkdownParser = () => (input: string) => {
const cache: Record<string, Promise<string>> = {};
const existing = cache[input];
if (existing) {
return existing;
}
const createMarkdownParser = () => {
// A Map rather than an object so descriptions like "constructor" don't hit prototype keys.
const cache = new Map<string, Promise<string>>();
return (input: string) => {
const existing = cache.get(input);
if (existing) {
return existing;
}
const result = parseMarkdown(input);
cache[input] = result;
return result;
const result = parseMarkdown(input);
cache.set(input, result);
return result;
};
};
@@ -143,6 +143,30 @@ describe('resolveStringContentRef', () => {
});
describe('resolveContentRef', () => {
it('does not resolve category or missing assignments as tag links', async () => {
const normal = { slug: 'constructor', label: 'Constructor', color: 'default' };
const category = {
slug: 'products',
label: 'Products',
color: 'default',
kind: 'category',
};
const context = {
space: { id: 'local' },
revision: { tags: [normal, category] },
linker: createLinker({
host: 'docs.example.com',
spaceBasePath: '/',
siteBasePath: '/',
}),
} as unknown as GitBookAnyContext;
expect(await resolveContentRef({ kind: 'tag', tag: 'products' }, context)).toBeNull();
expect(await resolveContentRef({ kind: 'tag', tag: 'missing' }, context)).toBeNull();
expect(
await resolveContentRef({ kind: 'tag', tag: 'constructor', space: 'local' }, context)
).toMatchObject({ text: 'Constructor' });
});
it("resolves a page in a different space using that space's page data, not the current context page", async () => {
const sharedPageId = 'page-shared';
+1 -1
View File
@@ -10,7 +10,7 @@ export async function withVerifySignature<T>(
request: Request,
fn: (body: T) => Promise<NextResponse>
) {
// Fail closed when no secret is configured, consistent with force-revalidate.
// Fail closed when no secret is configured.
if (!GITBOOK_SECRET) {
return NextResponse.json({ error: 'Revalidation is disabled' }, { status: 403 });
}
+4 -2
View File
@@ -8,10 +8,12 @@ export function getRevisionTags(revision: Revision | undefined): RevisionTag[] {
}
/**
* Resolve a tag slug to its full RevisionTag.
* Resolve an assignment to a normal tag, ignoring categories and missing definitions.
*/
export function resolveTag(slug: string, revisionTags: RevisionTag[]): RevisionTag | undefined {
return revisionTags.find((t) => t.slug === slug);
return revisionTags.find(
(tag) => tag.slug === slug && !('kind' in tag && tag.kind === 'category')
);
}
/**
+43 -3
View File
@@ -1,7 +1,13 @@
import { describe, expect, it } from 'bun:test';
import type { JSONDocument, Revision } from '@gitbook/api';
import {
DocumentTextColor,
type JSONDocument,
type Revision,
type RevisionTag,
} from '@gitbook/api';
import { getRevisionTags, resolveBlockTags, resolveTag } from './tags';
import {
UPDATES_TAG_FILTER_CAP,
getDocumentFilterableTags,
@@ -9,6 +15,40 @@ import {
} from './updates';
describe('getDocumentFilterableTags', () => {
it('ignores category and deleted references without removing their stored assignments', () => {
const document = createUpdatesDocument([['category', 'constructor', 'missing']]);
const category = { ...createTag('category', 'Products'), kind: 'category' };
const normal = createTag('constructor', 'Constructor');
const revision = { tags: [category, normal] } as unknown as Revision;
const before = JSON.stringify(document);
expect(getDocumentFilterableTags(document, revision).map((tag) => tag.slug)).toEqual([
'constructor',
]);
expect(resolveTag('category', revision.tags)).toBeUndefined();
expect(resolveTag('missing', revision.tags)).toBeUndefined();
expect(resolveTag('constructor', revision.tags)).toEqual(normal);
expect(getRevisionTags(revision)).toEqual([category, normal]);
expect(JSON.stringify(document)).toBe(before);
});
it('rejects category assignments even when definitions are passed directly to the resolver', () => {
const normal = createTag('beta', 'Beta');
const tags = [
{ ...createTag('products', 'Products'), kind: 'category' },
normal,
] satisfies (RevisionTag & { kind?: 'category' })[];
expect(
resolveBlockTags(
[
{ kind: 'tag', tag: 'products' },
{ kind: 'tag', tag: 'beta' },
{ kind: 'tag', tag: 'missing' },
],
tags
)
).toEqual([normal]);
});
it('returns unique update tags in document order', () => {
const document = createUpdatesDocument([
['improvements', 'fixes'],
@@ -77,11 +117,11 @@ function createUpdatesDocument(entryTags: string[][]): JSONDocument {
};
}
function createTag(slug: string, label: string) {
function createTag(slug: string, label: string): RevisionTag {
return {
slug,
label,
color: 'default',
color: DocumentTextColor.Default,
icon: undefined,
};
}
@@ -1,49 +0,0 @@
import type { NextApiRequest, NextApiResponse } from 'next';
import crypto from 'node:crypto';
interface JsonBody {
// The paths need to be the rewritten one, `res.revalidate` call don't go through the middleware
paths: string[];
}
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
// Only allow POST requests
if (req.method !== 'POST') {
return res.status(405).json({ error: 'Method not allowed' });
}
const signatureHeader = req.headers['x-gitbook-signature'] as string | undefined;
if (!signatureHeader) {
return res.status(400).json({ error: 'Missing signature header' });
}
// We cannot use env from `@/v2/lib/env` here as it make it crash because of the import "server-only" in the file.
if (process.env.GITBOOK_SECRET) {
try {
const computedSignature = crypto
.createHmac('sha256', process.env.GITBOOK_SECRET)
.update(JSON.stringify(req.body))
.digest('hex');
if (computedSignature === signatureHeader) {
const results = await Promise.allSettled(
(req.body as JsonBody).paths.map((path) => {
// oxlint-disable-next-line no-console
console.log(`Revalidating path: ${path}`);
return res.revalidate(path);
})
);
return res.status(200).json({
success: results.every((result) => result.status === 'fulfilled'),
errors: results
.filter((result) => result.status === 'rejected')
.map((result) => (result as PromiseRejectedResult).reason),
});
}
return res.status(401).json({ error: 'Invalid signature' });
} catch (error) {
console.error('Error during revalidation:', error);
return res.status(400).json({ error: 'Invalid request or unable to parse JSON' });
}
}
// If no secret is set, we do not allow revalidation
return res.status(403).json({ error: 'Revalidation is disabled' });
}
+2
View File
@@ -53,6 +53,8 @@ async function main() {
await Promise.all([
writeDataFile('styles-map', JSON.stringify(onlyStyles, null, 2)),
writeDataFile('icons', JSON.stringify(result, null, 2)),
// Names only, so validating an icon name doesn't load every label and search term.
writeDataFile('icon-names', JSON.stringify(result.map((entry) => entry.icon))),
]);
// oxlint-disable-next-line no-console
+5
View File
@@ -12,6 +12,11 @@
"development": "./src/icons.ts",
"default": "./dist/icons.js"
},
"./validateIconName": {
"types": "./dist/validateIconName.d.ts",
"development": "./src/validateIconName.ts",
"default": "./dist/validateIconName.js"
},
"./types": {
"types": "./dist/types.d.ts",
"development": "./src/types.ts",
+1 -12
View File
@@ -18,15 +18,4 @@ export interface IconDefinition {
// @ts-ignore
export const icons: IconDefinition[] = rawIcons;
let iconNamesSet: Set<string> | null = null;
/**
* Validate that the icon name is valid.
*/
export function validateIconName(icon: IconName | string): icon is IconName {
if (!iconNamesSet) {
iconNamesSet = new Set(icons.map((icon) => icon.icon));
}
return iconNamesSet.has(icon);
}
export { validateIconName } from './validateIconName';
+15
View File
@@ -0,0 +1,15 @@
import iconNames from './data/icon-names.json' with { type: 'json' };
import type { IconName } from './types';
let iconNamesSet: Set<string> | null = null;
/**
* Validate that the icon name is valid.
*/
export function validateIconName(icon: IconName | string): icon is IconName {
if (!iconNamesSet) {
iconNamesSet = new Set(iconNames);
}
return iconNamesSet.has(icon);
}
+1
View File
@@ -5,6 +5,7 @@ export default defineConfig([
entry: [
'src/index.ts',
'src/icons.ts',
'src/validateIconName.ts',
'src/types.ts',
'src/getIconStyle.ts',
'src/IconSources.ts',
@@ -36,11 +36,14 @@ export function OpenAPIPathMultipleServers(
};
});
// The store outlives client-side navigation, so it can hold a server from another spec.
const selectedServer = items.find((item) => item.key === key)?.key ?? defaultServer;
return (
<OpenAPIPathItem
copyType="button"
{...props}
value={`${withServer ? key : ''}${path}`}
value={`${withServer ? selectedServer : ''}${path}`}
context={context}
>
{withServer ? (