Compare commits

..

6 Commits

Author SHA1 Message Date
Peter White ebf893e0b4 Keep query params on redirects within the preview domain 2026-11-19 14:45:48 +00:00
Peter White 683f089bdc Resolve change request and revision URLs in full so the API can redirect them
Sites that turn off public change request previews get a redirect to the site preview from the
URL lookup. Part of RND-14276.
2026-11-19 14:27:58 +00:00
Peter White 3ddab40f8d Build the preview redirect from the site space preview URL 2026-11-19 13:51:05 +00:00
Peter White e194363ccf Read the published preview setting from the site instead of the URL lookup 2026-11-19 13:28:40 +00:00
Peter White 2ce7c5a98d changeset 2026-11-19 12:59:48 +00:00
Peter White 120781d2c7 Redirect change request and revision links to the site preview when public previews are off
Members sign in on the preview domain and land on the same content. Fixes RND-14276.
2026-11-19 12:59:48 +00:00
6 changed files with 65 additions and 333 deletions
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Send change request and revision links to the site preview, where GitBook members can sign in, when a site turns off public change request previews.
+23 -50
View File
@@ -1,7 +1,5 @@
import { afterEach, describe, expect, it, spyOn } from 'bun:test';
import type { PublishedSiteContentLookup } from '@gitbook/api';
import { GITBOOK_PREVIEW_BASE_URL } from '../env';
import * as api from './api';
import { DataFetcherError } from './errors';
@@ -50,64 +48,39 @@ describe('preview auth redirects', () => {
expect(redirect.origin + redirect.pathname).toBe(authURL.toString());
expect(redirect.searchParams.get('redirect')).toBe(requestURL.toString());
});
});
it.each([
{
name: 'non-preview application redirects',
requestURL: 'https://docs.example.com/~/changes/66',
target: 'application',
redirect: 'https://app.gitbook.com/o/org_foo/sites/site_foo',
expectedRedirect: 'https://app.gitbook.com/o/org_foo/sites/site_foo',
},
{
name: 'preview content redirects with a remaining page path',
requestURL: new URL(
'site_foo/~/changes/66/hello%20world',
GITBOOK_PREVIEW_BASE_URL
).toString(),
target: 'content',
redirect: 'https://docs.example.com/section?theme=dark',
expectedRedirect: 'https://docs.example.com/section/hello%20world?theme=dark',
},
{
name: 'preview external redirects with a remaining page path',
requestURL: new URL(
'site_foo/~/revisions/revision_123/hello%20world',
GITBOOK_PREVIEW_BASE_URL
).toString(),
target: 'external',
redirect: 'https://auth.example.com/login?location=%2Fsection&state=keep',
expectedRedirect:
'https://auth.example.com/login?location=%2Fsection%2Fhello%2520world&state=keep',
},
] as const)(
'preserves handling of $name',
async ({ requestURL, target, redirect, expectedRedirect }) => {
const data: PublishedSiteContentLookup =
target === 'external'
? { target, redirect, site: 'site_foo' }
: { target, redirect };
apiClientSpy = spyOn(api, 'apiClient').mockReturnValue({
urls: {
async resolvePublishedContentByUrl() {
return { data };
},
describe('lookup URL', () => {
it('sends change request URLs in full and keeps the redirect of the API', async () => {
const urls: string[] = [];
const redirect = new URL(
'site_foo/section/~/changes/66/hello%20world',
GITBOOK_PREVIEW_BASE_URL
).toString();
const apiClientSpy = spyOn(api, 'apiClient').mockReturnValue({
urls: {
async resolvePublishedContentByUrl({ url }: { url: string }) {
urls.push(url);
return { data: { target: 'content', redirect } };
},
} as unknown as ReturnType<typeof api.apiClient>);
},
} as unknown as ReturnType<typeof api.apiClient>);
try {
const result = await lookupPublishedContentByUrl({
url: requestURL,
url: 'https://docs.example.com/section/~/changes/66/hello%20world?jwt_token=abc',
apiToken: null,
redirectOnError: false,
visitorPayload: {},
});
expect(result).toEqual({ data: { ...data, redirect: expectedRedirect } });
expect(result).toEqual({ data: { target: 'content', redirect } });
} finally {
apiClientSpy.mockRestore();
}
);
});
describe('lookup URL', () => {
expect(urls).toEqual(['https://docs.example.com/section/~/changes/66/hello%20world']);
});
it('resolves the full URL without search params in a single call', async () => {
const urls: string[] = [];
const apiClientSpy = spyOn(api, 'apiClient').mockReturnValue({
+9 -45
View File
@@ -3,9 +3,8 @@ import type { GitBookAPI, PublishedSiteContentLookup, SiteVisitorPayload } from
import { apiClient } from './api';
import { getExposableError } from './errors';
import type { DataFetcherResponse } from './types';
import { getURLLookup, getURLLookupPathname, stripURLSearch } from './urls';
import { getURLLookup, stripURLSearch } from './urls';
import { tryCatch } from '@/lib/async';
import { joinPath, joinPathWithBaseURL } from '@/lib/paths';
import { isPreviewRequest } from '@/lib/preview';
import { trace } from '@/lib/tracing';
@@ -40,12 +39,12 @@ export async function lookupPublishedContentByUrl(
const callResult = await trace(
{
operation: 'resolvePublishedContentByUrl',
name: lookup.url,
name: lookup,
},
() =>
tryCatch(
api.urls.resolvePublishedContentByUrl({
url: lookup.url,
url: lookup,
...(input.visitorPayload ? { visitor: input.visitorPayload } : {}),
redirectOnError: input.redirectOnError,
} as ResolveBody) //TODO: remove cast when we are sure that everything is good
@@ -62,47 +61,12 @@ export async function lookupPublishedContentByUrl(
data: { data },
} = callResult;
if ('redirect' in data) {
if (data.target === 'application' && isPreviewRequest(lookupURL)) {
// The cached lookup omits content selectors and query params needed after login.
const redirect = new URL(data.redirect);
redirect.searchParams.set('redirect', lookupURL.toString());
return { data: { ...data, redirect: redirect.toString() } };
}
// Append the path to the redirect URL
// because we resolved a shorter path and the redirect is relative to it
if (lookup.extraPath) {
if (data.target === 'content') {
const redirect = new URL(data.redirect);
redirect.pathname = joinPath(redirect.pathname, lookup.extraPath);
data.redirect = redirect.toString();
} else {
const redirect = new URL(data.redirect);
if (redirect.searchParams.has('location')) {
redirect.searchParams.set(
'location',
joinPath(redirect.searchParams.get('location') ?? '', lookup.extraPath)
);
data.redirect = redirect.toString();
}
}
}
return { data };
if ('redirect' in data && data.target === 'application' && isPreviewRequest(lookupURL)) {
// The cached lookup omits the query params needed after login.
const redirect = new URL(data.redirect);
redirect.searchParams.set('redirect', lookupURL.toString());
return { data: { ...data, redirect: redirect.toString() } };
}
const changeRequest = data.changeRequest ?? lookup.changeRequest;
const revision = data.revision ?? lookup.revision;
return {
data: {
...data,
canonicalUrl: joinPathWithBaseURL(data.canonicalUrl, lookup.extraPath),
basePath: joinPath(data.basePath, lookup.basePath ?? ''),
pathname: getURLLookupPathname(lookup, data),
...(changeRequest ? { changeRequest } : {}),
...(revision ? { revision } : {}),
},
};
return { data };
}
+15 -139
View File
@@ -1,88 +1,6 @@
import { describe, expect, it } from 'bun:test';
import { getURLLookup, getURLLookupPathname, normalizeRequestURL, normalizeURL } from './urls';
describe('getURLLookupPathname', () => {
const previewRoot = 'https://sites.gitbook.com/preview/site_example/section';
const pagePath = 'guides/access/setup';
const homepagePath = '/welcome/overview';
it.each(['revisions', 'changes'])(
'resolves a page in a %s preview from the site-space root',
(kind) => {
const lookup = getURLLookup(
new URL(`${previewRoot}/~/${kind}/revision-id/${pagePath}`)
)!;
expect(
getURLLookupPathname(lookup, {
basePath: '/preview/site_example/section/',
pathname: homepagePath,
})
).toBe(`/${pagePath}`);
}
);
it.each(['revisions', 'changes'])(
'preserves the custom homepage at a %s preview root',
(kind) => {
const lookup = getURLLookup(new URL(`${previewRoot}/~/${kind}/revision-id/`))!;
expect(
getURLLookupPathname(lookup, {
basePath: '/preview/site_example/section/',
pathname: homepagePath,
})
).toBe(`${homepagePath}/`);
}
);
it('uses the resolved pathname for a full URL lookup', () => {
const lookup = getURLLookup(new URL(`https://docs.example.com/section/${pagePath}`))!;
expect(
getURLLookupPathname(lookup, {
basePath: '/section/',
pathname: `/${pagePath}`,
})
).toBe(`/${pagePath}/`);
});
it('preserves page resolution without a custom homepage', () => {
const lookup = getURLLookup(new URL(`${previewRoot}/~/revisions/revision-id/${pagePath}`))!;
expect(
getURLLookupPathname(lookup, {
basePath: '/preview/site_example/section/',
pathname: '/',
})
).toBe(`/${pagePath}`);
});
it.each(['/section/variant', '/section/variant/'])(
'recognizes a root lookup with base path %s',
(basePath) => {
expect(
getURLLookupPathname(
{
url: 'https://docs.example.com/section/variant/',
extraPath: 'guide/page',
},
{ basePath, pathname: homepagePath }
)
).toBe('/guide/page');
}
);
it('preserves a legitimate page prefix for a non-root lookup', () => {
expect(
getURLLookupPathname(
{ url: 'https://docs.example.com/section/guide', extraPath: 'page' },
{ basePath: '/section/', pathname: '/guide' }
)
).toBe('/guide/page');
});
});
import { getURLLookup, normalizeRequestURL, normalizeURL } from './urls';
describe('getURLLookup', () => {
it.each([
@@ -98,68 +16,26 @@ describe('getURLLookup', () => {
'https://docs.mycompany.com/section/blog/rss.xml',
'https://docs.mycompany.com/a/b/intro.md',
'https://proxy.gitbook.site/sites/site_foo/hello/world',
'https://docs.mycompany.com/~/revisions/id/a/b/c',
'https://docs.mycompany.com/~/changes/id/hello',
'https://test.gitbook.io/sharelink/v/variant/~/revisions/id/a/b/c',
'https://docs.mycompany.com/~/revisions/id/a/~gitbook/ogimage/pageId',
])('looks up the full URL %s', (url) => {
expect(getURLLookup(new URL(url))).toEqual({ url, extraPath: '' });
expect(getURLLookup(new URL(url))).toBe(url);
});
it('looks up the normalized URL', () => {
expect(getURLLookup(new URL('https://docs.mycompany.com//hello/'))).toEqual({
url: 'https://docs.mycompany.com/hello',
extraPath: '',
});
expect(getURLLookup(new URL('https://docs.mycompany.com//hello/'))).toBe(
'https://docs.mycompany.com/hello'
);
});
it('should not match before a revision ID', () => {
expect(getURLLookup(new URL('https://docs.mycompany.com/~/revisions/id/a/b/c'))).toEqual({
url: 'https://docs.mycompany.com/',
extraPath: 'a/b/c',
basePath: '~/revisions/id',
revision: 'id',
});
});
it('should not match before a change request ID', () => {
expect(getURLLookup(new URL('https://docs.mycompany.com/~/changes/id/hello'))).toEqual({
url: 'https://docs.mycompany.com/',
extraPath: 'hello',
basePath: '~/changes/id',
changeRequest: 'id',
});
});
it('should match a revision in a variant in a share-link', () => {
expect(
getURLLookup(
new URL('https://test.gitbook.io/sharelink/v/variant/~/revisions/id/a/b/c')
)
).toEqual({
url: 'https://test.gitbook.io/sharelink/v/variant',
extraPath: 'a/b/c',
basePath: '~/revisions/id',
revision: 'id',
});
});
it('should keep the revision base path for an internal path', () => {
expect(
getURLLookup(
new URL('https://docs.mycompany.com/~/revisions/id/a/~gitbook/ogimage/pageId')
)
).toEqual({
url: 'https://docs.mycompany.com/',
extraPath: 'a/~gitbook/ogimage/pageId',
basePath: '~/revisions/id',
revision: 'id',
});
});
it.each([
'https://proxy.gitbook.site/',
'https://proxy.gitbook.site/sites',
'https://proxy.gitbook.site/sites/~/changes/id/hello',
])('should skip the proxy root URL %s', (url) => {
expect(getURLLookup(new URL(url))).toBeNull();
});
it.each(['https://proxy.gitbook.site/', 'https://proxy.gitbook.site/sites'])(
'should skip the proxy root URL %s',
(url) => {
expect(getURLLookup(new URL(url))).toBeNull();
}
);
});
describe('normalizeRequestURL', () => {
+2 -96
View File
@@ -1,107 +1,13 @@
import { joinPath, removeTrailingSlash } from '../paths';
import { isProxyRequest, isProxyRootRequest } from '../proxy';
import { DataFetcherError, getExposableError } from './errors';
/**
* Paths served by our own routes rather than by site content. They can never be part of a
* site URL, so a revision or change marker is never searched for inside them.
* Kept in sync with the site route handlers and `encodePathInSiteContent` in the middleware.
*/
const INTERNAL_PATHS = [
// Simple `~gitbook` endpoints. `image`, `__evt` and `visitor` are served by the middleware
// before the lookup, but are listed so this stays a complete registry.
/^~gitbook\/(pdf|search|search-prewarm|icon|site-index|image|__evt|visitor)$/,
/^~gitbook\/ogimage\/[^/]+$/,
/^~gitbook\/auth\/(login|logout)$/,
/^~gitbook\/oauth2\/v1\/[^/]+\/authorize$/,
/^~gitbook\/embed(\/(assistant|search|demo|script\.js|page(\/.*)?))?$/,
/^~gitbook\/markdown\/.+$/,
/^~gitbook\/markdown-ask\/[^/]+(\/[^/]+)?$/,
/^~gitbook\/rss\/.+$/,
// Site root files, including the `llms.txt` aliases from `PATH_ALIASES`.
/^llms\.txt$/,
/^llms-full\.txt(\/\d+)?$/,
/^(\.well-known\/)?sitemap\.md$/,
/^robots\.txt$/,
/^sitemap(-pages)?\.xml$/,
/^rss\.xml$/,
];
/**
* Return the leading segments that can be part of the site URL, dropping the internal path
* (if any) that follows them.
*/
function getContentPathSegments(pathSegments: string[]): string[] {
for (let index = 0; index < pathSegments.length; index++) {
const remaining = pathSegments.slice(index).join('/');
if (INTERNAL_PATHS.some((regex) => regex.test(remaining))) {
return pathSegments.slice(0, index);
}
}
return pathSegments;
}
/**
* For a given GitBook URL, return the URL to resolve with the API.
*
* The full URL is resolved as-is, except for revisions and changes in the path
* (`~/revisions/<id>/` or `~/changes/<id>/`): these are resolved up to the tilde,
* and the rest of the path goes in the extraPath.
*
* Returns `null` for the root proxy URLs, which can never resolve to a site.
*/
export function getURLLookup(input: URL): {
url: string;
extraPath: string;
basePath?: string;
changeRequest?: string;
revision?: string;
} | null {
export function getURLLookup(input: URL): string | null {
const url = normalizeURL(input);
const pathSegments = url.pathname.slice(1).split('/');
// A `~` in an internal path (like `~gitbook/...`) is not a revision or change marker.
const contentSegments = getContentPathSegments(pathSegments);
const tildeIndex = contentSegments.indexOf('~');
const kind = tildeIndex >= 0 ? contentSegments[tildeIndex + 1] : undefined;
if (kind !== 'revisions' && kind !== 'changes') {
return isProxyRootRequest(url) ? null : { url: url.toString(), extraPath: '' };
}
const idIndex = tildeIndex + 2;
const id = contentSegments[idIndex];
const contentURL = new URL(url);
contentURL.pathname = contentSegments.slice(0, tildeIndex).join('/');
if (isProxyRootRequest(contentURL)) {
return null;
}
return {
url: contentURL.toString(),
extraPath: pathSegments.slice(idIndex + 1).join('/'),
basePath: contentSegments.slice(tildeIndex, idIndex + 1).join('/'),
...(kind === 'revisions' ? { revision: id } : { changeRequest: id }),
};
}
/** Combine a resolved lookup with the remaining requested page path. */
export function getURLLookupPathname(
alternative: { url: string; extraPath: string },
resolved: { basePath: string; pathname: string }
) {
if (
alternative.extraPath &&
removeTrailingSlash(new URL(alternative.url).pathname) ===
removeTrailingSlash(resolved.basePath)
) {
// A root lookup can resolve to a custom homepage, which is not a prefix for other pages.
return joinPath('/', alternative.extraPath);
}
return joinPath(resolved.pathname, alternative.extraPath);
return isProxyRootRequest(url) ? null : url.toString();
}
/**
+11 -3
View File
@@ -40,6 +40,7 @@ import {
import { GITBOOK_DISABLE_INSIGHTS, isGitBookAssetsHostURL, isGitBookHostURL } from '@/lib/env';
import { getImageResizingContextId } from '@/lib/images';
import { isAITrainingOrIndexingRequest } from '@/lib/indexing-crawlers';
import { getLogger } from '@/lib/logger';
import { MCP_SERVER_CARD_PATH, MCP_SERVER_CARD_WELL_KNOWN_PATH } from '@/lib/mcp/paths';
import { MiddlewareHeaders } from '@/lib/middleware';
import {
@@ -328,9 +329,16 @@ async function serveSiteRoutes(requestURL: URL, request: NextRequest) {
);
}
// Keep the same search params as the original request
// as it might contain a VA token
contentRedirect.search = request.nextUrl.search;
if (
!isPreviewRequest(siteRequestURL) &&
isPreviewRequest(new URL(siteURLData.redirect))
) {
getLogger().info('Redirected disabled published preview to the preview domain');
} else {
// Keep the same search params as the original request
// as it might contain a VA token
contentRedirect.search = request.nextUrl.search;
}
return createRedirectResponse(contentRedirect.toString());
}