@rsc-kit/core 0.30.26 → 0.30.28

package/dist/host.js

@@ -68,7 +68,7 @@ import { inlineFlight, inlineFlightStart } from "./inlineFlight.js";
 import { currentNotFound, withRedirect } from "./redirect.js";
 import { compressed } from "./compress.js";
 import { withCache } from "./cache.js";
-import { takeAfterWork, withRequest, withResponseDraft } from "./request.js";
+import { takeAfterWork, withRequest, withResponseDraft, withUrl } from "./request.js";
 import { criticalAssetsOf, linkHeader, mergeAssets } from "./earlyHints.js";
 /**
  * @internal For a host adapter that embeds the engine. An app imports this
@@ -81,7 +81,7 @@ export { redirect } from "./redirect.js";
 // public surface so a host imports from one place.
 /** @internal For a host adapter. An app never matches its own routes. */
 export { matchIntercept, matchRoute, sharedDepth } from "./routing.js";
-import { FLIGHT_TYPE, HEADER, HTML_TYPE, PER_CLIENT, PER_REQUEST, REVALIDATE, VARY_ON_RSC, } from "./headers.js";
+import { FLIGHT_TYPE, HEADER, HTML_TYPE, PER_CLIENT, PER_REQUEST, REVALIDATE, PPR, VARY_ON_RSC, } from "./headers.js";
 import { ServerAuthenticationError, ServerAuthorizationError, } from "./js/errors.js";
 import { assertSigningSecret, serveChanges } from "./changed.js";
 /**
@@ -681,7 +681,12 @@ export function createRscHandler(options) {
             // Last, over the finished answer, headers and all. A stored answer
             // is the same bytes for everyone and is compressed once, keyed by
             // the build and the url it was stored for.
-            if (compress) {
+            //
+            // Never the contract's resume: the edge appends it to the shell's
+            // plain bytes and compresses the page once, so gzip here would be
+            // garbage in the middle of a document. The edge drops
+            // Accept-Encoding, but this does not rely on it.
+            if (compress && !new URL(request.url).pathname.startsWith(PPR.prefix)) {
                 const answer = await compressed(request, response, servedFrom.get(response) === "stored" ? storedKey(request, response) : undefined);
                 const from = servedFrom.get(response);
                 if (answer !== response && from)
@@ -800,15 +805,10 @@ export function createRscHandler(options) {
         if (url.pathname === HEADER.changesPath) {
             return await serveChanges(request);
         }
-        // The two halves an edge cache needs: hand it a shell it may keep, and
-        // finish that shell for a visitor it cannot answer for itself.
-        if (options.prerendered && url.pathname === HEADER.pprShellPath) {
-            return await servePprShell(request, url, options.prerendered);
-        }
-        if (request.method === "POST" &&
-            options.prerendered &&
-            url.pathname === HEADER.pprResumePath) {
-            return await servePprResume(request, url, options.prerendered);
+        // The PPR contract, for a platform's edge. The whole prefix is reserved,
+        // and is a 404 to anyone without the release's token.
+        if (url.pathname.startsWith(PPR.prefix)) {
+            return await servePprContract(request, url);
         }
         // A form submitted before the page had a runtime: the browser posts it
         // to the page's own url, as React wrote it, with the action's id among
@@ -1117,8 +1117,12 @@ export function createRscHandler(options) {
     }
     /** Whether a health probe sent this deployment's host-call secret, compared in constant time. */
     function probeHoldsSecret(request) {
-        const expected = (typeof process === "undefined" ? undefined : process.env.RSC_HOST_CALL_SECRET) ?? "";
-        const given = request.headers.get("x-rsc-host-secret") ?? "";
+        return holdsSecret(request, "x-rsc-host-secret", "RSC_HOST_CALL_SECRET");
+    }
+    /** Whether the request's header holds the secret in the environment's variable, compared in constant time. */
+    function holdsSecret(request, header, variable) {
+        const expected = (typeof process === "undefined" ? undefined : process.env[variable]) ?? "";
+        const given = request.headers.get(header) ?? "";
         // An unset secret matches nothing, the empty string included.
         if (expected === "" || given.length !== expected.length)
             return false;
@@ -1173,44 +1177,26 @@ export function createRscHandler(options) {
         storedAs.set(answer, storedName);
         return answer;
     }
-    async function servePprShell(request, url, read) {
-        if (request.method !== "GET" && request.method !== "HEAD")
-            return null;
-        const target = url.searchParams.get("url");
-        if (!target || !target.startsWith("/")) {
-            return new Response("A url is required", { status: 400 });
-        }
+    /**
+     * A page's shell, by the rule both shell endpoints apply: a PPR page, on a
+     * route with no guard, whose shell the build wrote for this url or for its
+     * pattern. Anything else is a 404 - the same pages edgeShells leaves out of
+     * the marker, so the list and the origin cannot disagree.
+     */
+    async function shellAt(pathname, read) {
         // Matched from the url asked for, never from anything else the caller sent.
-        const route = matchRoute(routes, new URL(target, url.origin).pathname);
+        const route = matchRoute(routes, pathname);
         if (!route)
             return new Response("No such page", { status: 404 });
         if (isGuarded(route)) {
             return new Response("This route is not edge-cacheable", { status: 404 });
         }
-        const key = storedKeyFor(new URL(target, url.origin).pathname, route);
+        const key = storedKeyFor(pathname, route);
         if (key === null)
             return new Response("No such page", { status: 404 });
         const shell = (await read(`${key}.ppr.html`)) ??
             (await read(`${patternKey(route.route)}.ppr.html`));
-        if (shell === null)
-            return new Response("No shell for this page", { status: 404 });
-        return new Response(JSON.stringify({ shell, version: version ?? null }), {
-            headers: withVersion({
-                "Content-Type": "application/json",
-                // Deliberately NOT the REVALIDATE the rest of the host sends. That is
-                // `max-age=0, must-revalidate`, which a cache honours by treating the
-                // entry as stale the moment it arrives — an edge would store this and
-                // never once serve it, so the whole thing would quietly do nothing
-                // while looking like it worked, because the miss path serves correct
-                // pages.
-                //
-                // This is build output with nothing of the caller in it, and a guarded
-                // route never reaches here at all, so it is genuinely cacheable. An
-                // hour bounds how long a deploy can be served against a stale shell;
-                // the version below catches it sooner than that.
-                "Cache-Control": "public, max-age=3600",
-            }),
-        });
+        return shell ?? new Response("No shell for this page", { status: 404 });
     }
     /**
      * Finish a shell for the visitor this request belongs to.
@@ -1225,53 +1211,130 @@ export function createRscHandler(options) {
      * of its own. A resume asked for with no cookies is an anonymous visitor and
      * gets an anonymous answer.
      */
-    async function servePprResume(request, url, read) {
-        const target = url.searchParams.get("url");
-        if (!target || !target.startsWith("/")) {
-            return new Response("A url is required", { status: 400 });
-        }
-        const pathname = new URL(target, url.origin).pathname;
+    async function resumeAt(request, target, read) {
+        const pathname = target.pathname;
         const route = matchRoute(routes, pathname);
         if (!route)
             return new Response("No such page", { status: 404 });
-        // The same refusal the document would get, before a byte of the holes is
-        // rendered. Nothing below runs for a caller this turns away.
-        const refusal = await refuseUnlessAllowed(request, route);
-        if (refusal === RENDER_NOT_FOUND)
-            return new Response("Not found", { status: 404 });
-        if (refusal)
-            return refusal;
-        if (!engine.handleRscResume) {
-            return new Response("This engine cannot resume", { status: 500 });
-        }
-        const key = storedKeyFor(pathname, route);
-        if (key === null)
-            return new Response("No such page", { status: 404 });
-        const pattern = patternKey(route.route);
-        let shellKey = null;
-        if ((await read(`${key}.ppr.html`)) !== null)
-            shellKey = key;
-        else if ((await read(`${pattern}.ppr.html`)) !== null)
-            shellKey = pattern;
-        // Read from our own artifacts. Never from the request body — that is the
-        // difference between this and the protocol it is modelled on.
-        const state = shellKey === null ? null : await read(`${shellKey}.postponed.json`);
-        if (state === null)
-            return new Response("Nothing to resume", { status: 404 });
-        const { htmlStream } = await engine.handleRscResume(route.route.component, route.params, route.route.layouts.map((component) => ({ component, props: {} })), route.route.loadings, route.route.slots, {}, JSON.parse(state), undefined, shellKey === key ? pathname : "", pathname);
-        // Carries the build version so a caller holding a cached shell can tell
-        // that it no longer belongs to this origin. A shell from an older build
-        // does not make the resume fail — it replays against slots that have moved
-        // and React falls back to client rendering, silently and for good. Nothing
-        // else would ever report it.
-        return new Response(htmlStream, {
-            headers: withVersion({
-                "Content-Type": HTML_TYPE,
-                // Rendered for whoever asked. Never cacheable.
-                "Cache-Control": PER_CLIENT,
-            }),
+        // The holes render for the visitor's url, not for this endpoint's: a
+        // component reading the search params would otherwise find `?url=…`.
+        // Absolute, as the request's own url is: searchParams() parses it whole.
+        return await withUrl(target.href, async () => {
+            // The same refusal the document would get, before a byte of the holes
+            // is rendered. Nothing below runs for a caller this turns away.
+            const refusal = await refuseUnlessAllowed(request, route);
+            if (refusal === RENDER_NOT_FOUND)
+                return new Response("Not found", { status: 404 });
+            if (refusal)
+                return refusal;
+            if (!engine.handleRscResume) {
+                return new Response("This engine cannot resume", { status: 500 });
+            }
+            const key = storedKeyFor(pathname, route);
+            if (key === null)
+                return new Response("No such page", { status: 404 });
+            const pattern = patternKey(route.route);
+            let shellKey = null;
+            if ((await read(`${key}.ppr.html`)) !== null)
+                shellKey = key;
+            else if ((await read(`${pattern}.ppr.html`)) !== null)
+                shellKey = pattern;
+            // Read from our own artifacts. Never from the request body — that is
+            // the difference between this and the protocol it is modelled on.
+            const state = shellKey === null ? null : await read(`${shellKey}.postponed.json`);
+            if (state === null)
+                return new Response("Nothing to resume", { status: 404 });
+            const { htmlStream } = await engine.handleRscResume(route.route.component, route.params, route.route.layouts.map((component) => ({ component, props: {} })), route.route.loadings, route.route.slots, {}, JSON.parse(state), undefined, shellKey === key ? pathname : "", pathname);
+            // Carries the build version so a caller holding a cached shell can tell
+            // that it no longer belongs to this origin. A shell from an older build
+            // does not make the resume fail — it replays against slots that have
+            // moved and React falls back to client rendering, silently and for
+            // good. Nothing else would ever report it.
+            return new Response(htmlStream, {
+                headers: withVersion({
+                    "Content-Type": HTML_TYPE,
+                    // Rendered for whoever asked. Never cacheable.
+                    "Cache-Control": PER_CLIENT,
+                    ...(version ? { [PPR.build]: version } : {}),
+                }),
+            });
         });
     }
+    /**
+     * The PPR contract's two endpoints, for a platform's edge. They exist only
+     * for a caller holding the release's PPR_TOKEN: unset, missing or wrong,
+     * everything under /_ppr/ is a 404, as if there were nothing here - so an
+     * app is safe wherever it runs, and only the platform can ask.
+     *
+     * The shell goes as JSON with an empty `state`: the resume reads its own
+     * from the build and ignores the body. Both answers name the build in
+     * PPR-Build.
+     */
+    async function servePprContract(request, url) {
+        const answer = await pprContractAnswer(request, url);
+        // Every answer here depends on the token, a 404 included: stored by a
+        // cache in between, one would be served to callers with the wrong token
+        // or none - and a stored 404 would hide a real shell from the edge.
+        try {
+            answer.headers.set("Cache-Control", "private, no-store");
+            return answer;
+        }
+        catch {
+            return new Response(answer.body, {
+                status: answer.status,
+                headers: { ...Object.fromEntries(answer.headers), "Cache-Control": "private, no-store" },
+            });
+        }
+    }
+    async function pprContractAnswer(request, url) {
+        const missing = new Response("Not found", { status: 404 });
+        const read = options.prerendered;
+        if (!read || !version || !holdsSecret(request, PPR.token, PPR.tokenEnv))
+            return missing;
+        if (url.pathname === PPR.shellPath && (request.method === "GET" || request.method === "HEAD")) {
+            const pathname = contractPathname(url.searchParams.get("path"), url);
+            if (pathname === null)
+                return missing;
+            const shell = await shellAt(pathname, read);
+            if (shell instanceof Response)
+                return shell;
+            return new Response(request.method === "HEAD" ? null : JSON.stringify({ v: 1, build: version, html: shell, state: "" }), {
+                headers: {
+                    "Content-Type": "application/json",
+                    // Fixed for the build, so no ETag. And never stored on the way:
+                    // it was answered only for the token, and a cache between the
+                    // edge and here would hand it to callers without one.
+                    "Cache-Control": "private, no-store",
+                    [PPR.build]: version,
+                },
+            });
+        }
+        if (url.pathname === PPR.resumePath && request.method === "POST") {
+            const raw = url.searchParams.get("url");
+            const at = raw === null ? -1 : raw.indexOf("?");
+            const pathname = contractPathname(at === -1 ? raw : raw.slice(0, at), url);
+            if (pathname === null)
+                return missing;
+            return await resumeAt(request, new URL(pathname + (at === -1 ? "" : raw.slice(at)), url.origin), read);
+        }
+        return missing;
+    }
+    /**
+     * A contract path - absolute and decoded once - as the pathname this host
+     * matches, or null for one that would not survive the trip unchanged: a
+     * dot segment, a query or fragment inside it, an encoded slash.
+     */
+    function contractPathname(path, base) {
+        if (!path || !path.startsWith("/"))
+            return null;
+        const pathname = new URL(path, base.origin).pathname;
+        try {
+            return decodeURIComponent(pathname) === path ? pathname : null;
+        }
+        catch {
+            return null;
+        }
+    }
     async function servePrerendered(request, url, route, source) {
         const key = storedKeyFor(url.pathname, route);
         if (key === null)