@rsc-kit/core 0.30.27 → 0.30.29

package/dist/edgeShells.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The url patterns of the pages an edge may serve from a cached shell, for
+ * `.output/ppr.json` - the marker of the PPR contract, which an edge reads the
+ * same way for every framework that implements it.
+ *
+ * An edge in front of the app asks one question of each request - is this a
+ * PPR page? - and answers it from a list it was handed at deploy time. Reading
+ * `rsc-static/` for it does not work: a guarded page has a shell on disk too,
+ * served from a cache it skips its guard; `_team_` cannot say whether it was a
+ * parameter or a folder of that name; and the layout is ours to change.
+ *
+ * So the list is the build's, by the same rule the shell endpoint applies: a
+ * page with a shell, on a route with no middleware - neither a `middleware.ts`
+ * above it nor the host's `export const middleware`. The endpoint refuses
+ * exactly those, so the list and the origin cannot disagree.
+ */
+import type { RouteSegment } from './manifest.js';
+/** What an edge is promised, and what it can hold. */
+export declare const MAX_SHELLS = 200;
+export declare const MAX_SHELL_BYTES = 200;
+/**
+ * The marker. `bypass` names this framework's own requests on a page's path
+ * that are not a visitor's document: every payload fetch - a navigation, a
+ * prefetch, a refresh - carries X-RSC, and an action is a POST, which an edge
+ * never answers from a shell anyway.
+ */
+export declare function pprMarker(build: string, shells: string[]): {
+    v: number;
+    build: string;
+    shells: string[];
+    bypass: {
+        headers: string[];
+    };
+};
+export interface ShellRoute {
+    component: string;
+    segments: RouteSegment[];
+    middleware?: readonly string[];
+    hostMiddleware?: readonly string[];
+}
+/**
+ * The patterns, `/` for the index, `[name]` for one segment and a final
+ * `[...name]` for one or more - and what was left out of the list, and why,
+ * for the build to say.
+ */
+export declare function edgeShells(results: readonly {
+    type: string;
+    component: string;
+}[], routes: readonly ShellRoute[]): {
+    shells: string[];
+    left: string[];
+};

package/dist/edgeShells.js

@@ -0,0 +1,98 @@
+/**
+ * The url patterns of the pages an edge may serve from a cached shell, for
+ * `.output/ppr.json` - the marker of the PPR contract, which an edge reads the
+ * same way for every framework that implements it.
+ *
+ * An edge in front of the app asks one question of each request - is this a
+ * PPR page? - and answers it from a list it was handed at deploy time. Reading
+ * `rsc-static/` for it does not work: a guarded page has a shell on disk too,
+ * served from a cache it skips its guard; `_team_` cannot say whether it was a
+ * parameter or a folder of that name; and the layout is ours to change.
+ *
+ * So the list is the build's, by the same rule the shell endpoint applies: a
+ * page with a shell, on a route with no middleware - neither a `middleware.ts`
+ * above it nor the host's `export const middleware`. The endpoint refuses
+ * exactly those, so the list and the origin cannot disagree.
+ */
+/** What an edge is promised, and what it can hold. */
+export const MAX_SHELLS = 200;
+export const MAX_SHELL_BYTES = 200;
+/**
+ * The marker. `bypass` names this framework's own requests on a page's path
+ * that are not a visitor's document: every payload fetch - a navigation, a
+ * prefetch, a refresh - carries X-RSC, and an action is a POST, which an edge
+ * never answers from a shell anyway.
+ */
+export function pprMarker(build, shells) {
+    return { v: 1, build, shells, bypass: { headers: ['X-RSC'] } };
+}
+/**
+ * The patterns, `/` for the index, `[name]` for one segment and a final
+ * `[...name]` for one or more - and what was left out of the list, and why,
+ * for the build to say.
+ */
+export function edgeShells(results, routes) {
+    const byComponent = new Map(routes.map((route) => [route.component, route]));
+    const shells = [];
+    const left = [];
+    for (const component of new Set(results.filter((r) => r.type === 'shell').map((r) => r.component))) {
+        const route = byComponent.get(component);
+        if (!route)
+            continue;
+        if (route.middleware?.length || route.hostMiddleware?.length)
+            continue;
+        // Bound from the request's host, which a path pattern cannot say: the
+        // same pattern would match every tenant's page on every domain.
+        if (route.segments.some((segment) => segment.type === 'host'))
+            continue;
+        const pattern = patternOf(route.segments);
+        if (pattern === null)
+            continue;
+        if (new TextEncoder().encode(pattern).length > MAX_SHELL_BYTES) {
+            left.push(`${pattern.slice(0, 60)}… is over ${MAX_SHELL_BYTES} bytes`);
+            continue;
+        }
+        if (!shells.includes(pattern))
+            shells.push(pattern);
+    }
+    // Over the cap, the deepest are the ones not listed: an edge that does not
+    // know a page is a PPR page sends it to the origin, which answers it
+    // correctly, and the shallow pages are the ones most visited.
+    if (shells.length > MAX_SHELLS) {
+        shells.sort((a, b) => depth(a) - depth(b) || (a < b ? -1 : 1));
+        left.push(`${shells.length - MAX_SHELLS} past the shallowest ${MAX_SHELLS}`);
+        shells.length = MAX_SHELLS;
+    }
+    shells.sort();
+    return { shells, left };
+}
+/**
+ * A route's segments as the edge matches them, or null when it cannot: a
+ * catch-all anywhere but last, or a name that is itself bracketed - an
+ * optional catch-all, `[[...name]]`, matches no url at all.
+ */
+function patternOf(segments) {
+    const parts = [];
+    for (const [index, segment] of segments.entries()) {
+        // Not a path an edge can match: the contract has no empty, `.` or `..`
+        // segment, and a name with a slash would be two.
+        if (['', '.', '..'].includes(segment.value) || segment.value.includes('/'))
+            return null;
+        if (segment.type === 'static')
+            parts.push(segment.value);
+        else if (segment.value.includes('[') || segment.value.includes(']'))
+            return null;
+        else if (segment.type === 'catchAll') {
+            if (index !== segments.length - 1)
+                return null;
+            parts.push(`[...${segment.value}]`);
+        }
+        else
+            parts.push(`[${segment.value}]`);
+    }
+    return '/' + parts.join('/');
+}
+function depth(pattern) {
+    return pattern === '/' ? 0 : pattern.split('/').length - 1;
+}
+//# sourceMappingURL=edgeShells.js.map

package/dist/edgeShells.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edgeShells.js","sourceRoot":"","sources":["../src/edgeShells.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The url patterns of the pages an edge may serve from a cached shell, for\n * `.output/ppr.json` - the marker of the PPR contract, which an edge reads the\n * same way for every framework that implements it.\n *\n * An edge in front of the app asks one question of each request - is this a\n * PPR page? - and answers it from a list it was handed at deploy time. Reading\n * `rsc-static/` for it does not work: a guarded page has a shell on disk too,\n * served from a cache it skips its guard; `_team_` cannot say whether it was a\n * parameter or a folder of that name; and the layout is ours to change.\n *\n * So the list is the build's, by the same rule the shell endpoint applies: a\n * page with a shell, on a route with no middleware - neither a `middleware.ts`\n * above it nor the host's `export const middleware`. The endpoint refuses\n * exactly those, so the list and the origin cannot disagree.\n */\n\nimport type { RouteSegment } from './manifest.js'\n\n/** What an edge is promised, and what it can hold. */\nexport const MAX_SHELLS = 200\nexport const MAX_SHELL_BYTES = 200\n\n/**\n * The marker. `bypass` names this framework's own requests on a page's path\n * that are not a visitor's document: every payload fetch - a navigation, a\n * prefetch, a refresh - carries X-RSC, and an action is a POST, which an edge\n * never answers from a shell anyway.\n */\nexport function pprMarker(build: string, shells: string[]) {\n  return { v: 1, build, shells, bypass: { headers: ['X-RSC'] } }\n}\n\nexport interface ShellRoute {\n  component: string\n  segments: RouteSegment[]\n  middleware?: readonly string[]\n  hostMiddleware?: readonly string[]\n}\n\n/**\n * The patterns, `/` for the index, `[name]` for one segment and a final\n * `[...name]` for one or more - and what was left out of the list, and why,\n * for the build to say.\n */\nexport function edgeShells(\n  results: readonly { type: string; component: string }[],\n  routes: readonly ShellRoute[],\n): { shells: string[]; left: string[] } {\n  const byComponent = new Map(routes.map((route) => [route.component, route]))\n  const shells: string[] = []\n  const left: string[] = []\n\n  for (const component of new Set(results.filter((r) => r.type === 'shell').map((r) => r.component))) {\n    const route = byComponent.get(component)\n\n    if (!route) continue\n    if (route.middleware?.length || route.hostMiddleware?.length) continue\n\n    // Bound from the request's host, which a path pattern cannot say: the\n    // same pattern would match every tenant's page on every domain.\n    if (route.segments.some((segment) => segment.type === 'host')) continue\n\n    const pattern = patternOf(route.segments)\n\n    if (pattern === null) continue\n\n    if (new TextEncoder().encode(pattern).length > MAX_SHELL_BYTES) {\n      left.push(`${pattern.slice(0, 60)}… is over ${MAX_SHELL_BYTES} bytes`)\n      continue\n    }\n\n    if (!shells.includes(pattern)) shells.push(pattern)\n  }\n\n  // Over the cap, the deepest are the ones not listed: an edge that does not\n  // know a page is a PPR page sends it to the origin, which answers it\n  // correctly, and the shallow pages are the ones most visited.\n  if (shells.length > MAX_SHELLS) {\n    shells.sort((a, b) => depth(a) - depth(b) || (a < b ? -1 : 1))\n    left.push(`${shells.length - MAX_SHELLS} past the shallowest ${MAX_SHELLS}`)\n    shells.length = MAX_SHELLS\n  }\n\n  shells.sort()\n\n  return { shells, left }\n}\n\n/**\n * A route's segments as the edge matches them, or null when it cannot: a\n * catch-all anywhere but last, or a name that is itself bracketed - an\n * optional catch-all, `[[...name]]`, matches no url at all.\n */\nfunction patternOf(segments: readonly RouteSegment[]): string | null {\n  const parts: string[] = []\n\n  for (const [index, segment] of segments.entries()) {\n    // Not a path an edge can match: the contract has no empty, `.` or `..`\n    // segment, and a name with a slash would be two.\n    if (['', '.', '..'].includes(segment.value) || segment.value.includes('/')) return null\n    if (segment.type === 'static') parts.push(segment.value)\n    else if (segment.value.includes('[') || segment.value.includes(']')) return null\n    else if (segment.type === 'catchAll') {\n      if (index !== segments.length - 1) return null\n      parts.push(`[...${segment.value}]`)\n    } else parts.push(`[${segment.value}]`)\n  }\n\n  return '/' + parts.join('/')\n}\n\nfunction depth(pattern: string): number {\n  return pattern === '/' ? 0 : pattern.split('/').length - 1\n}\n"]}

package/dist/headers.d.ts

@@ -70,10 +70,6 @@ export declare const HEADER: {
      */
     readonly query: 'X-RSC-Query';
     readonly queryPath: '/_rsc/query';
-    /** Build-time shell for a PPR route, for an edge cache to hold. */
-    readonly pprShellPath: '/_rsc/ppr-shell';
-    /** Finish a shell an edge cache is already serving. */
-    readonly pprResumePath: '/_rsc/ppr-resume';
     /**
      * On a refresh a change triggered: which names moved, to which versions
      * (`stock@5,orders@2`). A shared section renders once per such change, and
@@ -126,3 +122,20 @@ export declare const REVALIDATE = "public, max-age=0, must-revalidate";
  * cache may not keep it; the visitor's own browser may, and must ask again.
  */
 export declare const PER_REQUEST = "private, max-age=0, must-revalidate";
+/**
+ * The PPR contract: one marker, one shell endpoint, one resume, for any edge
+ * and any framework that implements it. Vendor-neutral names on purpose: an
+ * edge speaks the contract, and there is no second way in that is rsc-kit's
+ * own. docs/hosts/deployment.mdx has the whole of it.
+ */
+export declare const PPR: {
+    /** Reserved: nothing under it is the app's. */
+    readonly prefix: '/_ppr/';
+    readonly shellPath: '/_ppr/shell';
+    readonly resumePath: '/_ppr/resume';
+    /** The platform's per-release token. Unset, both endpoints are a 404. */
+    readonly tokenEnv: 'PPR_TOKEN';
+    readonly token: 'PPR-Token';
+    /** The build a shell or holes belong to - the marker's `build`. */
+    readonly build: 'PPR-Build';
+};

package/dist/headers.js

@@ -79,10 +79,6 @@ export const HEADER = {
      */
     query: 'X-RSC-Query',
     queryPath: '/_rsc/query',
-    /** Build-time shell for a PPR route, for an edge cache to hold. */
-    pprShellPath: '/_rsc/ppr-shell',
-    /** Finish a shell an edge cache is already serving. */
-    pprResumePath: '/_rsc/ppr-resume',
     /**
      * On a refresh a change triggered: which names moved, to which versions
      * (`stock@5,orders@2`). A shared section renders once per such change, and
@@ -141,4 +137,21 @@ export const REVALIDATE = 'public, max-age=0, must-revalidate';
  * cache may not keep it; the visitor's own browser may, and must ask again.
  */
 export const PER_REQUEST = 'private, max-age=0, must-revalidate';
+/**
+ * The PPR contract: one marker, one shell endpoint, one resume, for any edge
+ * and any framework that implements it. Vendor-neutral names on purpose: an
+ * edge speaks the contract, and there is no second way in that is rsc-kit's
+ * own. docs/hosts/deployment.mdx has the whole of it.
+ */
+export const PPR = {
+    /** Reserved: nothing under it is the app's. */
+    prefix: '/_ppr/',
+    shellPath: '/_ppr/shell',
+    resumePath: '/_ppr/resume',
+    /** The platform's per-release token. Unset, both endpoints are a 404. */
+    tokenEnv: 'PPR_TOKEN',
+    token: 'PPR-Token',
+    /** The build a shell or holes belong to - the marker's `build`. */
+    build: 'PPR-Build',
+};
 //# sourceMappingURL=headers.js.map

package/dist/headers.js.map

@@ -1 +1 @@
-{"version":3,"file":"headers.js","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,0EAA0E;AAC1E,sEAAsE;AACtE,wEAAwE;AACxE,2EAA2E;AAC3E,gCAAgC;AAChC,EAAE;AACF,gFAAgF;AAEhF,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB;;;OAGG;IACH,GAAG,EAAE,OAAO;IAEZ,iFAAiF;IACjF,QAAQ,EAAE,gBAAgB;IAE1B,kEAAkE;IAClE,YAAY,EAAE,qBAAqB;IAEnC,wCAAwC;IACxC,OAAO,EAAE,eAAe;IAExB;;;;OAIG;IACH,QAAQ,EAAE,iBAAiB;IAE3B,gFAAgF;IAChF,OAAO,EAAE,eAAe;IAExB,uDAAuD;IACvD,SAAS,EAAE,iBAAiB;IAE5B,gDAAgD;IAChD,OAAO,EAAE,eAAe;IAExB,uEAAuE;IACvE,UAAU,EAAE,kBAAkB;IAE9B,0CAA0C;IAC1C,MAAM,EAAE,cAAc;IAEtB;;;;;;;OAOG;IACH,QAAQ,EAAE,gBAAgB;IAE1B;;;;;;OAMG;IACH,WAAW,EAAE,oBAAoB;IAEjC;;;;;OAKG;IACH,UAAU,EAAE,cAAc;IAC1B;;;;;;;;;OASG;IACH;;;;;;;OAOG;IACH,KAAK,EAAE,aAAa;IAEpB,SAAS,EAAE,aAAa;IACxB,mEAAmE;IACnE,YAAY,EAAE,iBAAiB;IAC/B,uDAAuD;IACvD,aAAa,EAAE,kBAAkB;IACjC;;;;OAIG;IACH,SAAS,EAAE,eAAe;IAC1B,+EAA+E;IAC/E,WAAW,EAAE,eAAe;IAC5B,8FAA8F;IAC9F,UAAU,EAAE,cAAc;CAClB,CAAA;AAEV,sBAAsB;AACtB,MAAM,CAAC,MAAM,WAAW,GAAG,iCAAiC,CAAA;AAE5D,2BAA2B;AAC3B,MAAM,CAAC,MAAM,SAAS,GAAG,0BAA0B,CAAA;AAEnD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,MAAM,CAAC,GAAG;IACV,MAAM,CAAC,QAAQ;IACf,MAAM,CAAC,UAAU;IACjB,MAAM,CAAC,SAAS;IAChB,MAAM,CAAC,OAAO;CACf,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,mBAAmB,CAAA;AAE7C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,oCAAoC,CAAA;AAE9D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,qCAAqC,CAAA","sourcesContent":["// The wire protocol, as names rather than string literals.\n//\n// A host writing these out by hand is how they drift. Two of them are not\n// negotiable at all — the client sends them or asks for them at fixed\n// addresses, and a host that spells one differently fails silently: the\n// request falls through, the decoder never runs, and a button does nothing\n// with no error on either side.\n//\n// PROTOCOL.md describes what each one means. This is the same list, importable.\n\nexport const HEADER = {\n  /**\n   * Present on a request for a Flight payload rather than the document. One\n   * url serves both, which is why every answer must Vary on it.\n   */\n  rsc: 'X-RSC',\n\n  /** The layout chain the client has mounted, outermost first, comma-separated. */\n  segments: 'X-RSC-Segments',\n\n  /** The boundary the answer replaces. 0 means a whole document. */\n  segmentDepth: 'X-RSC-Segment-Depth',\n\n  /** The chain to send back next time. */\n  layouts: 'X-RSC-Layouts',\n\n  /**\n   * On a payload request: this url's page said it does not exist, after the\n   * shell went out, and the client is asking for the not-found page to put\n   * where it was. RedirectBoundary sends it.\n   */\n  notFound: 'X-RSC-Not-Found',\n\n  /** Identifies the build, so a client can notice it is talking to an old one. */\n  version: 'X-RSC-Version',\n\n  /** The slot an intercepted navigation is targeting. */\n  intercept: 'X-RSC-Intercept',\n\n  /** Where the navigation or action came from. */\n  referer: 'X-RSC-Referer',\n\n  /** One named region of the current page to render and return alone. */\n  revalidate: 'X-RSC-Revalidate',\n\n  /** The server reference being invoked. */\n  action: 'X-RSC-Action',\n\n  /**\n   * Go here instead.\n   *\n   * Used for a redirect the client has to perform itself: a failed action, and\n   * a navigation whose render redirected. Never a 3xx for those — `fetch`\n   * follows one transparently, so the client would get the destination's HTML\n   * where it expected a Flight payload and decode it as one.\n   */\n  redirect: 'X-RSC-Redirect',\n\n  /**\n   * The body's real type.\n   *\n   * The body itself goes out as application/octet-stream so a host that parses\n   * multipart cannot consume it before the action does — reading Content-Type\n   * instead leaves an upload undecodable.\n   */\n  contentType: 'X-RSC-Content-Type',\n\n  /**\n   * Where the browser posts server actions.\n   *\n   * Not a convention this can choose: the client runtime posts here\n   * unconditionally.\n   */\n  actionPath: '/_rsc/action',\n  /**\n   * Where the browser reads queries.\n   *\n   * A GET, and that is the whole point of it being a separate address: a POST\n   * is cacheable by nothing, so a read routed through the action endpoint can\n   * never be kept by an HTTP cache, a CDN or a service worker. Only functions\n   * declared with `query()` are reachable here — the endpoint checks the mark\n   * before invoking anything, because otherwise this address would run any\n   * registered action over GET.\n   */\n  /**\n   * Sent on every read, and required by the query endpoint.\n   *\n   * A GET with no unusual header is a simple request, so any page could\n   * trigger one with an <img> and the visitor's cookies would ride along.\n   * This header is not CORS-safelisted, so the browser preflights it — the\n   * same thing that makes a POST carrying X-RSC-Action safe.\n   */\n  query: 'X-RSC-Query',\n\n  queryPath: '/_rsc/query',\n  /** Build-time shell for a PPR route, for an edge cache to hold. */\n  pprShellPath: '/_rsc/ppr-shell',\n  /** Finish a shell an edge cache is already serving. */\n  pprResumePath: '/_rsc/ppr-resume',\n  /**\n   * On a refresh a change triggered: which names moved, to which versions\n   * (`stock@5,orders@2`). A shared section renders once per such change, and\n   * every tab asking with the same one gets that render.\n   */\n  changedBy: 'X-RSC-Changed',\n  /** The stream a tab hears on when a name its page refreshes on has changed. */\n  changesPath: '/_rsc/changes',\n  /** Whether this renderer can serve: up, and its backend answering. GET only, never cached. */\n  healthPath: '/_rsc/health',\n} as const\n\n/** Flight payload. */\nexport const FLIGHT_TYPE = 'text/x-component; charset=utf-8'\n\n/** A rendered document. */\nexport const HTML_TYPE = 'text/html; charset=utf-8'\n\n/**\n * Every request header that changes what a response body contains.\n *\n * One url answers with a whole document, a partial payload, a named region or\n * an interceptor depending on these — so a cache keyed on the url alone, or on\n * `X-RSC` alone, will hand one client another's answer. They are materially\n * different bodies, not variations in presentation.\n */\nexport const VARY_ON_RSC = [\n  HEADER.rsc,\n  HEADER.segments,\n  HEADER.revalidate,\n  HEADER.intercept,\n  HEADER.referer,\n].join(', ')\n\n/**\n * What a response says about being stored, when it must not be.\n *\n * `Vary` alone is not enough on the platform this targets. Cloudflare ignores\n * `Vary` for everything except `Accept-Encoding`, and this package ships a\n * Workers story as a headline feature — so one url answering with a document,\n * a Flight payload, a segment and an interceptor, keyed only on the url, hands\n * one visitor another's body. Anything narrowed by a request header, and\n * anything behind a guard, says outright that it is not to be stored.\n */\nexport const PER_CLIENT = 'private, no-store'\n\n/**\n * And what a frozen, unguarded page says.\n *\n * Explicit rather than absent: with no directive at all, whether an\n * intermediary stores it comes down to that intermediary's heuristics, which\n * is not a decision this package should be leaving to chance in either\n * direction.\n */\nexport const REVALIDATE = 'public, max-age=0, must-revalidate'\n\n/**\n * And what a page rendered for one request says.\n *\n * It may have read the visitor's cookies, and nothing in the headers - which\n * leave before the render has finished - can know whether it did. So a shared\n * cache may not keep it; the visitor's own browser may, and must ask again.\n */\nexport const PER_REQUEST = 'private, max-age=0, must-revalidate'\n"]}
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,0EAA0E;AAC1E,sEAAsE;AACtE,wEAAwE;AACxE,2EAA2E;AAC3E,gCAAgC;AAChC,EAAE;AACF,gFAAgF;AAEhF,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB;;;OAGG;IACH,GAAG,EAAE,OAAO;IAEZ,iFAAiF;IACjF,QAAQ,EAAE,gBAAgB;IAE1B,kEAAkE;IAClE,YAAY,EAAE,qBAAqB;IAEnC,wCAAwC;IACxC,OAAO,EAAE,eAAe;IAExB;;;;OAIG;IACH,QAAQ,EAAE,iBAAiB;IAE3B,gFAAgF;IAChF,OAAO,EAAE,eAAe;IAExB,uDAAuD;IACvD,SAAS,EAAE,iBAAiB;IAE5B,gDAAgD;IAChD,OAAO,EAAE,eAAe;IAExB,uEAAuE;IACvE,UAAU,EAAE,kBAAkB;IAE9B,0CAA0C;IAC1C,MAAM,EAAE,cAAc;IAEtB;;;;;;;OAOG;IACH,QAAQ,EAAE,gBAAgB;IAE1B;;;;;;OAMG;IACH,WAAW,EAAE,oBAAoB;IAEjC;;;;;OAKG;IACH,UAAU,EAAE,cAAc;IAC1B;;;;;;;;;OASG;IACH;;;;;;;OAOG;IACH,KAAK,EAAE,aAAa;IAEpB,SAAS,EAAE,aAAa;IACxB;;;;OAIG;IACH,SAAS,EAAE,eAAe;IAC1B,+EAA+E;IAC/E,WAAW,EAAE,eAAe;IAC5B,8FAA8F;IAC9F,UAAU,EAAE,cAAc;CAClB,CAAA;AAEV,sBAAsB;AACtB,MAAM,CAAC,MAAM,WAAW,GAAG,iCAAiC,CAAA;AAE5D,2BAA2B;AAC3B,MAAM,CAAC,MAAM,SAAS,GAAG,0BAA0B,CAAA;AAEnD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,MAAM,CAAC,GAAG;IACV,MAAM,CAAC,QAAQ;IACf,MAAM,CAAC,UAAU;IACjB,MAAM,CAAC,SAAS;IAChB,MAAM,CAAC,OAAO;CACf,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,mBAAmB,CAAA;AAE7C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,oCAAoC,CAAA;AAE9D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,qCAAqC,CAAA;AAEhE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,+CAA+C;IAC/C,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,aAAa;IACxB,UAAU,EAAE,cAAc;IAC1B,yEAAyE;IACzE,QAAQ,EAAE,WAAW;IACrB,KAAK,EAAE,WAAW;IAClB,mEAAmE;IACnE,KAAK,EAAE,WAAW;CACV,CAAA","sourcesContent":["// The wire protocol, as names rather than string literals.\n//\n// A host writing these out by hand is how they drift. Two of them are not\n// negotiable at all — the client sends them or asks for them at fixed\n// addresses, and a host that spells one differently fails silently: the\n// request falls through, the decoder never runs, and a button does nothing\n// with no error on either side.\n//\n// PROTOCOL.md describes what each one means. This is the same list, importable.\n\nexport const HEADER = {\n  /**\n   * Present on a request for a Flight payload rather than the document. One\n   * url serves both, which is why every answer must Vary on it.\n   */\n  rsc: 'X-RSC',\n\n  /** The layout chain the client has mounted, outermost first, comma-separated. */\n  segments: 'X-RSC-Segments',\n\n  /** The boundary the answer replaces. 0 means a whole document. */\n  segmentDepth: 'X-RSC-Segment-Depth',\n\n  /** The chain to send back next time. */\n  layouts: 'X-RSC-Layouts',\n\n  /**\n   * On a payload request: this url's page said it does not exist, after the\n   * shell went out, and the client is asking for the not-found page to put\n   * where it was. RedirectBoundary sends it.\n   */\n  notFound: 'X-RSC-Not-Found',\n\n  /** Identifies the build, so a client can notice it is talking to an old one. */\n  version: 'X-RSC-Version',\n\n  /** The slot an intercepted navigation is targeting. */\n  intercept: 'X-RSC-Intercept',\n\n  /** Where the navigation or action came from. */\n  referer: 'X-RSC-Referer',\n\n  /** One named region of the current page to render and return alone. */\n  revalidate: 'X-RSC-Revalidate',\n\n  /** The server reference being invoked. */\n  action: 'X-RSC-Action',\n\n  /**\n   * Go here instead.\n   *\n   * Used for a redirect the client has to perform itself: a failed action, and\n   * a navigation whose render redirected. Never a 3xx for those — `fetch`\n   * follows one transparently, so the client would get the destination's HTML\n   * where it expected a Flight payload and decode it as one.\n   */\n  redirect: 'X-RSC-Redirect',\n\n  /**\n   * The body's real type.\n   *\n   * The body itself goes out as application/octet-stream so a host that parses\n   * multipart cannot consume it before the action does — reading Content-Type\n   * instead leaves an upload undecodable.\n   */\n  contentType: 'X-RSC-Content-Type',\n\n  /**\n   * Where the browser posts server actions.\n   *\n   * Not a convention this can choose: the client runtime posts here\n   * unconditionally.\n   */\n  actionPath: '/_rsc/action',\n  /**\n   * Where the browser reads queries.\n   *\n   * A GET, and that is the whole point of it being a separate address: a POST\n   * is cacheable by nothing, so a read routed through the action endpoint can\n   * never be kept by an HTTP cache, a CDN or a service worker. Only functions\n   * declared with `query()` are reachable here — the endpoint checks the mark\n   * before invoking anything, because otherwise this address would run any\n   * registered action over GET.\n   */\n  /**\n   * Sent on every read, and required by the query endpoint.\n   *\n   * A GET with no unusual header is a simple request, so any page could\n   * trigger one with an <img> and the visitor's cookies would ride along.\n   * This header is not CORS-safelisted, so the browser preflights it — the\n   * same thing that makes a POST carrying X-RSC-Action safe.\n   */\n  query: 'X-RSC-Query',\n\n  queryPath: '/_rsc/query',\n  /**\n   * On a refresh a change triggered: which names moved, to which versions\n   * (`stock@5,orders@2`). A shared section renders once per such change, and\n   * every tab asking with the same one gets that render.\n   */\n  changedBy: 'X-RSC-Changed',\n  /** The stream a tab hears on when a name its page refreshes on has changed. */\n  changesPath: '/_rsc/changes',\n  /** Whether this renderer can serve: up, and its backend answering. GET only, never cached. */\n  healthPath: '/_rsc/health',\n} as const\n\n/** Flight payload. */\nexport const FLIGHT_TYPE = 'text/x-component; charset=utf-8'\n\n/** A rendered document. */\nexport const HTML_TYPE = 'text/html; charset=utf-8'\n\n/**\n * Every request header that changes what a response body contains.\n *\n * One url answers with a whole document, a partial payload, a named region or\n * an interceptor depending on these — so a cache keyed on the url alone, or on\n * `X-RSC` alone, will hand one client another's answer. They are materially\n * different bodies, not variations in presentation.\n */\nexport const VARY_ON_RSC = [\n  HEADER.rsc,\n  HEADER.segments,\n  HEADER.revalidate,\n  HEADER.intercept,\n  HEADER.referer,\n].join(', ')\n\n/**\n * What a response says about being stored, when it must not be.\n *\n * `Vary` alone is not enough on the platform this targets. Cloudflare ignores\n * `Vary` for everything except `Accept-Encoding`, and this package ships a\n * Workers story as a headline feature — so one url answering with a document,\n * a Flight payload, a segment and an interceptor, keyed only on the url, hands\n * one visitor another's body. Anything narrowed by a request header, and\n * anything behind a guard, says outright that it is not to be stored.\n */\nexport const PER_CLIENT = 'private, no-store'\n\n/**\n * And what a frozen, unguarded page says.\n *\n * Explicit rather than absent: with no directive at all, whether an\n * intermediary stores it comes down to that intermediary's heuristics, which\n * is not a decision this package should be leaving to chance in either\n * direction.\n */\nexport const REVALIDATE = 'public, max-age=0, must-revalidate'\n\n/**\n * And what a page rendered for one request says.\n *\n * It may have read the visitor's cookies, and nothing in the headers - which\n * leave before the render has finished - can know whether it did. So a shared\n * cache may not keep it; the visitor's own browser may, and must ask again.\n */\nexport const PER_REQUEST = 'private, max-age=0, must-revalidate'\n\n/**\n * The PPR contract: one marker, one shell endpoint, one resume, for any edge\n * and any framework that implements it. Vendor-neutral names on purpose: an\n * edge speaks the contract, and there is no second way in that is rsc-kit's\n * own. docs/hosts/deployment.mdx has the whole of it.\n */\nexport const PPR = {\n  /** Reserved: nothing under it is the app's. */\n  prefix: '/_ppr/',\n  shellPath: '/_ppr/shell',\n  resumePath: '/_ppr/resume',\n  /** The platform's per-release token. Unset, both endpoints are a 404. */\n  tokenEnv: 'PPR_TOKEN',\n  token: 'PPR-Token',\n  /** The build a shell or holes belong to - the marker's `build`. */\n  build: 'PPR-Build',\n} as const\n"]}

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";
 /**
@@ -433,6 +433,8 @@ export function createRscHandler(options) {
     // own. Resolved on the first request: the engine reads it from a build
     // product it only has at runtime.
     let version = engine.buildId ? undefined : options.version;
+    // The PPR contract's build, read once - see pprBuild.
+    let pprBuildRead = null;
     const maxActionBody = options.maxActionBody ?? DEFAULT_MAX_ACTION_BODY;
     const compress = options.compress ?? true;
     // Annotated rather than inferred: the narrowing below is lost inside the
@@ -681,7 +683,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 +807,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 +1119,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 +1179,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 +1213,142 @@ 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,
+                    ...(pprBuildRead ? { [PPR.build]: pprBuildRead } : {}),
+                }),
+            });
         });
     }
+    /**
+     * The PPR contract's two endpoints, for a platform's edge. They exist only
+     * for a caller holding the PPR_TOKEN the platform set: 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 || !holdsSecret(request, PPR.token, PPR.tokenEnv))
+            return missing;
+        const build = await pprBuild(read);
+        if (!build)
+            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, 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]: build,
+                },
+            });
+        }
+        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;
+    }
+    /**
+     * The build the marker names, which the build wrote beside the shells - not
+     * the client's id this host sends a browser, which a server-only change
+     * keeps. See pprBuildId.
+     */
+    async function pprBuild(read) {
+        pprBuildRead ??= (await read("_ppr.build"))?.trim() || null;
+        return pprBuildRead;
+    }
+    /**
+     * 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)