Add urlLookup parameter to restrict URL lookup alternatives

packages/gitbook/src/lib/data/lookup.ts

@@ -12,6 +12,11 @@ interface LookupPublishedContentByUrlInput {
     redirectOnError: boolean;
     apiToken: string | null;
     visitorPayload: SiteVisitorPayload;
+    /**
+     * When provided and matching one of the URL lookup alternatives, restrict the lookup
+     * to that single alternative instead of racing all of them.
+     */
+    urlLookup?: string;
 }
 
 /**
@@ -25,6 +30,16 @@ export async function lookupPublishedContentByUrl(
     const url = stripURLSearch(lookupURL);
     const lookup = getURLLookupAlternatives(url);
 
+    if (input.urlLookup) {
+        // We verify first that it matches one of the alternatives, otherwise we ignore it and race all alternatives.
+        const matched = lookup.urls.find((alternative) => alternative.url === input.urlLookup);
+        if (matched) {
+            // Restrict to the requested alternative, forced as primary so errors and
+            // incomplete results still surface instead of being swallowed as null.
+            lookup.urls = [{ ...matched, primary: true }];
+        }
+    }
+
     const result = await race(lookup.urls, async (alternative, { signal }) => {
         const api = apiClient({ apiToken: input.apiToken });
         const callResult = await trace(

packages/gitbook/src/middleware.ts

@@ -204,10 +204,14 @@ async function serveSiteRoutes(requestURL: URL, request: NextRequest) {
     //
     request.headers.delete('x-gitbook-disable-tracking');
 
+    // header that allow to bypass the race in lookupPublishedContentByUrl when we know in advance the correct lookup to use
+    const urlLookup = request.headers.get('x-gitbook-lookup-url') ?? undefined;
+
     const withAPIToken = async (apiToken: string | null) => {
         const siteURLData = await throwIfDataError(
             lookupPublishedContentByUrl({
                 url: siteRequestURL.toString(),
+                urlLookup,
                 visitorPayload: {
                     jwtToken: visitorToken?.token ?? undefined,
                     unsignedClaims,