@rsc-kit/core 0.1.0

package/dist/headers.js

@@ -0,0 +1,96 @@
+// The wire protocol, as names rather than string literals.
+//
+// A host writing these out by hand is how they drift. Two of them are not
+// negotiable at all — the client sends them or asks for them at fixed
+// addresses, and a host that spells one differently fails silently: the
+// request falls through, the decoder never runs, and a button does nothing
+// with no error on either side.
+//
+// PROTOCOL.md describes what each one means. This is the same list, importable.
+export const HEADER = {
+    /**
+     * Present on a request for a Flight payload rather than the document. One
+     * url serves both, which is why every answer must Vary on it.
+     */
+    rsc: 'X-RSC',
+    /** The layout chain the client has mounted, outermost first, comma-separated. */
+    segments: 'X-RSC-Segments',
+    /** The boundary the answer replaces. 0 means a whole document. */
+    segmentDepth: 'X-RSC-Segment-Depth',
+    /** The chain to send back next time. */
+    layouts: 'X-RSC-Layouts',
+    /** Identifies the build, so a client can notice it is talking to an old one. */
+    version: 'X-RSC-Version',
+    /** The slot an intercepted navigation is targeting. */
+    intercept: 'X-RSC-Intercept',
+    /** Where the navigation or action came from. */
+    referer: 'X-RSC-Referer',
+    /** One named region of the current page to render and return alone. */
+    revalidate: 'X-RSC-Revalidate',
+    /** The server reference being invoked. */
+    action: 'X-RSC-Action',
+    /**
+     * Go here instead.
+     *
+     * Used for a redirect the client has to perform itself: a failed action, and
+     * a navigation whose render redirected. Never a 3xx for those — `fetch`
+     * follows one transparently, so the client would get the destination's HTML
+     * where it expected a Flight payload and decode it as one.
+     */
+    redirect: 'X-RSC-Redirect',
+    /**
+     * The body's real type.
+     *
+     * The body itself goes out as application/octet-stream so a host that parses
+     * multipart cannot consume it before the action does — reading Content-Type
+     * instead leaves an upload undecodable.
+     */
+    contentType: 'X-RSC-Content-Type',
+    /**
+     * Where the browser posts server actions.
+     *
+     * Not a convention this can choose: the client runtime posts here
+     * unconditionally.
+     */
+    actionPath: '/_rsc/action',
+};
+/** Flight payload. */
+export const FLIGHT_TYPE = 'text/x-component; charset=utf-8';
+/** A rendered document. */
+export const HTML_TYPE = 'text/html; charset=utf-8';
+/**
+ * Every request header that changes what a response body contains.
+ *
+ * One url answers with a whole document, a partial payload, a named region or
+ * an interceptor depending on these — so a cache keyed on the url alone, or on
+ * `X-RSC` alone, will hand one client another's answer. They are materially
+ * different bodies, not variations in presentation.
+ */
+export const VARY_ON_RSC = [
+    HEADER.rsc,
+    HEADER.segments,
+    HEADER.revalidate,
+    HEADER.intercept,
+    HEADER.referer,
+].join(', ');
+/**
+ * What a response says about being stored, when it must not be.
+ *
+ * `Vary` alone is not enough on the platform this targets. Cloudflare ignores
+ * `Vary` for everything except `Accept-Encoding`, and this package ships a
+ * Workers story as a headline feature — so one url answering with a document,
+ * a Flight payload, a segment and an interceptor, keyed only on the url, hands
+ * one visitor another's body. Anything narrowed by a request header, and
+ * anything behind a guard, says outright that it is not to be stored.
+ */
+export const PER_CLIENT = 'private, no-store';
+/**
+ * And what a frozen, unguarded page says.
+ *
+ * Explicit rather than absent: with no directive at all, whether an
+ * intermediary stores it comes down to that intermediary's heuristics, which
+ * is not a decision this package should be leaving to chance in either
+ * direction.
+ */
+export const REVALIDATE = 'public, max-age=0, must-revalidate';
+//# sourceMappingURL=headers.js.map

package/dist/headers.js.map

@@ -0,0 +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,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;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"}

package/dist/host.d.ts

@@ -0,0 +1,86 @@
+export { revalidate } from './revalidate.js';
+export { redirect } from './redirect.js';
+export { matchIntercept, matchRoute, sharedDepth } from './routing.js';
+export type { MatchedRoute } from './routing.js';
+import type { MatchedRoute } from './routing.js';
+import type { RouteManifest } from './manifest.js';
+/** The built server bundle. Only the parts a host calls. */
+export interface RscEngine {
+    /** The route table this bundle was built from. */
+    manifest?(): RouteManifest;
+    installHostFn(fn: (name: string, ...args: unknown[]) => unknown): void;
+    handleRscStream(component: string, props?: Record<string, unknown>, layouts?: {
+        component: string;
+        props: Record<string, unknown>;
+    }[], loadings?: string[], parallelSlots?: Record<string, string>, slotOverrides?: Record<string, unknown>, from?: number, pageKey?: string): Promise<{
+        stream: ReadableStream;
+        segmentDepth: number;
+    }>;
+    handleRscHtmlStream(component: string, props?: Record<string, unknown>, layouts?: {
+        component: string;
+        props: Record<string, unknown>;
+    }[], loadings?: string[], parallelSlots?: Record<string, string>, slotOverrides?: Record<string, unknown>, nonce?: string, pageKey?: string, bootstrap?: boolean): Promise<{
+        htmlStream: ReadableStream;
+    }>;
+    handleRscRevalidate?(target: string, page: unknown): Promise<{
+        rscPayload: string;
+    }>;
+    /**
+     * Run a route's middleware without rendering anything.
+     *
+     * For a frozen page: the host reads it from disk and the engine never sees
+     * the request, so the check has to be asked for separately.
+     */
+    runRouteMiddleware?(component: string, props: Record<string, unknown>): Promise<void>;
+    handleAction(actionId: string, body: Uint8Array | string | FormData, contentType?: string, page?: unknown, takeRevalidated?: () => string[]): Promise<{
+        stream: ReadableStream;
+    }>;
+}
+export interface RscHostOptions {
+    /** The built server bundle — `import * as engine from './build/rsc/index.js'`. */
+    engine: RscEngine;
+    /**
+     * The route table. Defaults to the one the bundle was built with, which is
+     * almost always what you want — a manifest passed separately can go stale
+     * against the bundle it is describing.
+     */
+    manifest?: RouteManifest;
+    /**
+     * Functions the app's server components call as `await rpc('name', ...args)`.
+     *
+     * In the Laravel host this crosses a socket into PHP. Here they are just
+     * functions, which is the whole reason a JS host is smaller.
+     */
+    rpc?: Record<string, (...args: unknown[]) => unknown>;
+    /**
+     * Props for a page, given whatever its url bound.
+     *
+     * Defaults to the url params alone. A host that loads a user, reads a
+     * session or resolves a tenant does it here — this is the one place the
+     * engine cannot supply anything for.
+     */
+    props?: (match: MatchedRoute, request: Request) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * Reads what the prerenderer wrote, if this build has any.
+     *
+     * A function rather than a directory, because not every host has a
+     * filesystem: on an edge runtime these live in a KV store or a static-asset
+     * binding. `prerenderedFrom` in `@rsc-kit/core/files` is the one for a disk.
+     *
+     * Checked before rendering, and anything it cannot find falls through to
+     * being rendered now — so a partial prerender is a valid state, not a
+     * broken one.
+     */
+    prerendered?: (name: string) => Promise<string | null> | string | null;
+    /** Serve a built browser asset. Return null for anything not found. */
+    assets?: (pathname: string, request: Request) => Promise<Response | null> | Response | null;
+    /**
+     * Identifies this build to the client, which compares it on every
+     * navigation and falls back to a full load when it changes. Without one a
+     * client keeps talking to a deployment that no longer exists — worst behind
+     * a CDN, where the shell it holds may already be from an older build.
+     */
+    version?: string;
+}
+export declare function createRscHandler(options: RscHostOptions): (request: Request) => Promise<Response | null>;
+//# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"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"}