mirror of
https://github.com/GitbookIO/gitbook.git
synced 2026-11-16 21:12:58 +00:00
Compare commits
7 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 262749a0b1 | |||
| b145bfcdff | |||
| 1c718491bd | |||
| 8dd308bd90 | |||
| c09da2ec1a | |||
| 9fcde5f487 | |||
| c85d84fc1d |
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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:
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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"
|
||||
},
|
||||
|
||||
+1
@@ -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,
|
||||
}
|
||||
);
|
||||
|
||||
@@ -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',
|
||||
|
||||
|
||||
@@ -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();
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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 (
|
||||
|
||||
@@ -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', () => {
|
||||
|
||||
@@ -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',
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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>');
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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';
|
||||
|
||||
|
||||
@@ -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 });
|
||||
}
|
||||
|
||||
@@ -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')
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -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' });
|
||||
}
|
||||
@@ -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
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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';
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
@@ -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 ? (
|
||||
|
||||
Reference in New Issue
Block a user