@real-router/rsc-server-plugin 0.1.0

package/src/actionFactory.ts

@@ -0,0 +1,148 @@
+import { getPluginApi } from "@real-router/core/api";
+
+import { ERROR_PREFIX } from "./constants";
+
+import type { RscActionResult } from "./types";
+import type {
+  DefaultDependencies,
+  Plugin,
+  PluginFactory,
+} from "@real-router/types";
+
+/**
+ * Per-start runtime validator for `getResult()` return values.
+ *
+ * Returns `null` when the value is acceptable (typed `RscActionResult`,
+ * non-thenable, non-array, non-null object). Otherwise returns a short
+ * descriptor used in the thrown `TypeError` message — keeps the error
+ * actionable by pointing at the exact failure mode (`"null"`, `"array"`,
+ * `"Promise/thenable — wire your action result synchronously"`, or the
+ * raw `typeof` for primitives).
+ *
+ * Single source of truth for the two-decision pattern: "throw or
+ * accept" + "what to say in the error". Previously the same checks
+ * lived inline at the call site AND in `describeBadResult` — a typo in
+ * one would silently break the symmetry. Unifying as one classifier
+ * eliminates that drift class.
+ */
+function classifyRscActionResult(value: unknown): string | null {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  if (typeof value !== "object") {
+    return typeof value;
+  }
+  if (typeof (value as { then?: unknown }).then === "function") {
+    return "Promise/thenable — wire your action result synchronously";
+  }
+
+  return null;
+}
+
+/**
+ * Plugin factory that publishes a Server Action result to
+ * `state.context.rscAction`. Pair with `rscServerPluginFactory` —
+ * the `"rsc"` and `"rscAction"` namespaces are independent and the
+ * two plugins coexist on the same router.
+ *
+ * The factory takes a `getResult` resolver evaluated at start-time
+ * (inside the `start` interceptor, after the route resolves but
+ * before the caller reads `state`). The caller has the action result
+ * in scope (e.g. computed by `decodeAction` + `loadServerAction` in
+ * their fetch handler) and returns it from the closure:
+ *
+ * @example
+ * ```ts
+ * let actionResult: RscActionResult | undefined;
+ *
+ * if (request.method === "POST") {
+ *   const decoded = await decodeAction(formData);
+ *   actionResult = { returnValue: { ok: true, data: await decoded() } };
+ * }
+ *
+ * router.usePlugin(
+ *   rscServerPluginFactory(loaders),
+ *   rscActionPluginFactory(() => actionResult),
+ * );
+ *
+ * const state = await router.start(pathname);
+ * // state.context.rscAction === actionResult (or undefined)
+ * ```
+ *
+ * When `getResult()` returns `undefined`, the interceptor skips the
+ * write — `state.context.rscAction` stays `undefined`. Useful for
+ * GET requests where there's no action to surface.
+ *
+ * The result is JSON-friendly (no ReactNode), so it serializes via
+ * `serializeRouterState(state)` without needing `excludeContext`.
+ * If you want to keep it server-side only (e.g. action result
+ * contains secrets), pass `excludeContext: ["rsc", "rscAction"]`.
+ */
+export function rscActionPluginFactory<
+  TReturn = unknown,
+  TFormState = unknown,
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  getResult: () => RscActionResult<TReturn, TFormState> | undefined,
+): PluginFactory<Dependencies> {
+  // Mirror the factory-time validation that `rscServerPluginFactory` and
+  // `ssrDataPluginFactory` already perform on their loaders map: a TS-cast
+  // bypass or a JS consumer can smuggle a non-function through, and the
+  // failure would otherwise surface much later inside the start interceptor
+  // as `TypeError: getResult is not a function`, after the `"rscAction"`
+  // namespace has already been claimed and the start interceptor has been
+  // registered. Failing eagerly with a typed, prefixed error keeps the API
+  // consistent across all factories in this package.
+  if (typeof getResult !== "function") {
+    throw new TypeError(`${ERROR_PREFIX} getResult must be a function`);
+  }
+
+  return (router): Plugin => {
+    const api = getPluginApi(router);
+    const claim = api.claimContextNamespace("rscAction");
+
+    const removeStartInterceptor = api.addInterceptor(
+      "start",
+      async (next, path) => {
+        const state = await next(path);
+        // Read as `unknown`: the TS contract pins it to RscActionResult, but
+        // we run a defensive shape guard below for cast-bypassed garbage.
+        const result: unknown = getResult();
+
+        if (result === undefined) {
+          return state;
+        }
+
+        // Symmetry-with-loaders runtime guard. The TS contract is
+        // `() => RscActionResult | undefined`, but the most common consumer
+        // mistake is wiring an `async` getResult — TS allows it via cast,
+        // and the resulting Promise would land in `state.context.rscAction`
+        // and break every downstream `result.returnValue` access. Single
+        // classifier — `classifyRscActionResult` is the source of truth for
+        // BOTH the accept/reject decision AND the error description, so a
+        // change to one cannot drift from the other.
+        const badShape = classifyRscActionResult(result);
+
+        if (badShape !== null) {
+          throw new TypeError(
+            `${ERROR_PREFIX} getResult must return an RscActionResult object or undefined (got ${badShape})`,
+          );
+        }
+
+        claim.write(state, result as RscActionResult<TReturn, TFormState>);
+
+        return state;
+      },
+    );
+
+    return {
+      teardown() {
+        removeStartInterceptor();
+        claim.release();
+      },
+    };
+  };
+}

package/src/buildRscPayload.ts

@@ -0,0 +1,64 @@
+import type { RscActionResult, RscPayload } from "./types";
+import type { State } from "@real-router/types";
+import type { ReactNode } from "react";
+
+/**
+ * Build a canonical Flight payload from `state.context.rsc` (+ optional
+ * Server Component override) and `state.context.rscAction`.
+ *
+ * Removes the repeated `{ root, returnValue, formState }` boilerplate at
+ * the call site:
+ *
+ * ```ts
+ * import { renderToReadableStream } from "@vitejs/plugin-rsc/rsc";
+ * const flight = renderToReadableStream(buildRscPayload(state));
+ * ```
+ *
+ * Pass `rootOverride` to wrap the per-route Server Component tree (e.g.
+ * with cross-cutting layout chrome) without rebuilding the payload by
+ * hand:
+ *
+ * ```ts
+ * const wrapped = (
+ *   <>
+ *     <NotificationBanner action={state.context.rscAction} />
+ *     {state.context.rsc}
+ *   </>
+ * );
+ * const payload = buildRscPayload<MyData, ReactFormState>(state, wrapped);
+ * ```
+ *
+ * `rootOverride === undefined` means "use the default" (`state.context.rsc`).
+ * Pass `null` to explicitly render nothing — `null` is a valid `ReactNode`
+ * and is preserved as-is, **not** treated as "fall back to default".
+ *
+ * `returnValue` and `formState` are **omitted** (not set to `undefined`)
+ * when their source is missing, so the result type-checks under
+ * `exactOptionalPropertyTypes: true` consumers without ceremony.
+ */
+export function buildRscPayload<TReturn = unknown, TFormState = unknown>(
+  state: State,
+  rootOverride?: ReactNode,
+): RscPayload<TReturn, TFormState> {
+  const ctx = state.context as {
+    rsc?: ReactNode;
+    rscAction?: RscActionResult<TReturn, TFormState>;
+  };
+
+  // `??` would collapse an explicit `null` override to the default — use a
+  // strict `=== undefined` check so callers can render nothing on purpose.
+  const root = rootOverride === undefined ? ctx.rsc : rootOverride;
+
+  const payload: RscPayload<TReturn, TFormState> = { root };
+  const action = ctx.rscAction;
+
+  if (action?.returnValue !== undefined) {
+    payload.returnValue = action.returnValue;
+  }
+
+  if (action?.formState !== undefined) {
+    payload.formState = action.formState;
+  }
+
+  return payload;
+}

package/src/constants.ts

@@ -0,0 +1,16 @@
+import type { RscSsrMode } from "./types";
+
+const LOGGER_CONTEXT = "rsc-server-plugin";
+
+export const ERROR_PREFIX = `[@real-router/${LOGGER_CONTEXT}]`;
+
+/**
+ * The strict subset of `SsrMode` that `rsc-server-plugin` accepts.
+ * `"data-only"` is intentionally excluded — RSC has no semantically meaningful
+ * "data without component" (the Flight payload IS the data + component).
+ *
+ * Single source of truth for `factory.ts` (`createSsrLoaderPlugin` allowedModes),
+ * `validation.ts` (factory-time loader-map validator), and `getSsrRscMode.ts`
+ * (runtime read-side guard against TS-cast-bypassed garbage in `state.context`).
+ */
+export const ALLOWED_RSC_MODES: readonly RscSsrMode[] = ["full", "client-only"];

package/src/errors.ts

@@ -0,0 +1,6 @@
+export {
+  LoaderRedirect,
+  LoaderNotFound,
+  LoaderTimeout,
+  withTimeout,
+} from "./shared-ssr/errors";

package/src/factory.ts

@@ -0,0 +1,56 @@
+import { ALLOWED_RSC_MODES, ERROR_PREFIX } from "./constants";
+import { createLoadersValidator, createSsrLoaderPlugin } from "./shared-ssr";
+
+import type { RscLoaderFactoryMap } from "./types";
+import type { DefaultDependencies, PluginFactory } from "@real-router/types";
+import type { ReactNode } from "react";
+
+// Inlined from the deleted validation.ts — single 7-line consumer was
+// here, no other importer in src/ or tests/, so the indirection was
+// pure ceremony.
+const validateLoaders = createLoadersValidator(ERROR_PREFIX, ALLOWED_RSC_MODES);
+
+/**
+ * Plugin factory that loads per-route `ReactNode` (RSC payload) by intercepting
+ * `router.start()`. Variant B from the RSC integration RFC: the plugin stores a
+ * `ReactNode` on `state.context.rsc` — it does NOT render Flight bytes itself.
+ *
+ * The caller is responsible for piping the published `ReactNode` through the
+ * appropriate bundler-specific renderer (e.g.
+ * `@vitejs/plugin-rsc/rsc.renderToReadableStream`,
+ * `react-server-dom-webpack/server.edge`, etc.) — keeping this plugin fully
+ * bundler-agnostic.
+ *
+ * Sibling plugin `@real-router/ssr-data-plugin` follows the same factory
+ * pattern via `createSsrLoaderPlugin` from `shared/ssr/`.
+ *
+ * @example
+ * ```ts
+ * const router = cloneRouter(baseRouter);
+ *
+ * router.usePlugin(rscServerPluginFactory({
+ *   "users.profile": () => async (params) => {
+ *     const user = await db.users.findById(params.id);
+ *     return <UserProfile user={user} />;
+ *   },
+ * }));
+ *
+ * const state = await router.start(req.url);
+ * if (state.context.rsc) {
+ *   const flight = renderToReadableStream(state.context.rsc);
+ *   // pipe flight to HTTP response
+ * }
+ * ```
+ */
+export function rscServerPluginFactory<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(loaders: RscLoaderFactoryMap<Dependencies>): PluginFactory<Dependencies> {
+  validateLoaders(loaders);
+
+  return createSsrLoaderPlugin<ReactNode, Dependencies>(loaders, {
+    namespace: "rsc",
+    modeNamespace: "ssrRscMode",
+    errorPrefix: ERROR_PREFIX,
+    allowedModes: ALLOWED_RSC_MODES,
+  });
+}

package/src/getSsrRscMode.ts

@@ -0,0 +1,41 @@
+import { ALLOWED_RSC_MODES } from "./constants";
+
+import type { RscSsrMode } from "./types";
+import type { State } from "@real-router/types";
+
+/**
+ * Returns the SSR mode resolved by `rsc-server-plugin` for the current state.
+ * Falls back to `"full"` when the route has no plugin entry.
+ *
+ * Read this from `entry-server.tsx` to branch on full vs client-only:
+ * - `"full"` — render the Server Component tree, pipe Flight stream.
+ * - `"client-only"` — ship shell HTML and let the client fetch via its own mechanism.
+ *
+ * The mode is written to `state.context.ssrRscMode` by the plugin's `start`
+ * interceptor for every route registered in the loaders map.
+ *
+ * Defensive read: if `state.context.ssrRscMode` was set to something outside
+ * `ALLOWED_RSC_MODES` by a TS-cast bypass or a foreign writer, the function
+ * collapses it to `"full"` rather than returning the bad value. Without this
+ * guard, a downstream `mode === "full"` branch would silently misbehave for
+ * `0`, `false`, `""`, `null`, or any unknown string.
+ *
+ * The read itself is wrapped in `try/catch` — a foreign writer that installs
+ * a throwing getter (`Object.defineProperty(ctx, "ssrRscMode", { get() { throw … } })`)
+ * cannot break the contract. The function NEVER throws, no matter how
+ * adversarial the context shape. `"full"` is the safe default for any error.
+ */
+export function getSsrRscMode(state: State): RscSsrMode {
+  let raw: unknown;
+
+  try {
+    raw = (state.context as { ssrRscMode?: unknown }).ssrRscMode;
+  } catch {
+    return "full";
+  }
+
+  return typeof raw === "string" &&
+    ALLOWED_RSC_MODES.includes(raw as RscSsrMode)
+    ? (raw as RscSsrMode)
+    : "full";
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+export type {
+  RscActionResult,
+  RscLoaderFn,
+  RscLoaderFactoryMap,
+  RscLoaderFnFactory,
+  RscPayload,
+  RscRouteEntry,
+  RscSsrMode,
+  SsrLoaderContext,
+} from "./types";
+
+export { rscServerPluginFactory } from "./factory";
+
+export { rscActionPluginFactory } from "./actionFactory";
+
+export { buildRscPayload } from "./buildRscPayload";
+
+export { getSsrRscMode } from "./getSsrRscMode";
+
+export { invalidate } from "./invalidate";
+
+declare module "@real-router/types" {
+  interface StateContext {
+    rsc?: import("react").ReactNode;
+    rscAction?: import("./types").RscActionResult;
+    ssrRscMode?: import("./types").RscSsrMode;
+  }
+}

package/src/invalidate.ts

@@ -0,0 +1,36 @@
+import { markStale } from "./shared-ssr";
+
+import type { Router } from "@real-router/types";
+
+/**
+ * Mark the `"rsc"` namespace as stale on the given router. The next
+ * navigation (including a same-route reload) re-runs the RSC loader for the
+ * destination route and overwrites `state.context.rsc` (and the mode marker)
+ * via the plugin's `subscribeLeave` listener.
+ *
+ * Honest fire-and-forget semantics — returns `void`. The flag is consumed in
+ * the awaited LEAVE_APPROVE phase of the next navigation, so subscribers see
+ * a fresh `ReactNode` when the navigation completes. Behaviour during an
+ * in-flight transition: the current transition completes unchanged; the flag
+ * is read by the *following* navigation. This keeps the invariant
+ * "one transition = one `state.context` snapshot" intact.
+ *
+ * Composability through the existing core API:
+ *
+ * ```ts
+ * // Fire-and-forget: stale until the user navigates somewhere
+ * invalidate(router, "rsc");
+ *
+ * // Explicit await — pair with a same-route reload
+ * invalidate(router, "rsc");
+ * await router.navigate(state.name, state.params, { reload: true });
+ * ```
+ *
+ * Surgical alternative to `router.navigate({ reload: true })` for multi-
+ * namespace routes: only the `"rsc"` namespace re-runs; a side-by-side
+ * `ssr-data-plugin` keeps its cached `state.context.data` on this transition
+ * unless its own `invalidate()` was also called.
+ */
+export function invalidate(router: Router, namespace: "rsc"): void {
+  markStale(router, namespace);
+}

package/src/types.ts

@@ -0,0 +1,122 @@
+import type {
+  SsrLoaderFn,
+  SsrLoaderFnFactory,
+  SsrMode,
+  SsrRouteEntry,
+} from "./shared-ssr";
+import type { DefaultDependencies } from "@real-router/types";
+import type { ReactNode } from "react";
+
+export { type SsrLoaderContext } from "./shared-ssr";
+
+/**
+ * SSR mode subset supported by `rsc-server-plugin`.
+ *
+ * `"data-only"` is intentionally excluded — RSC has no concept of "data
+ * without component" (the Flight payload IS the data + component). Using
+ * `"data-only"` with `rscServerPluginFactory` is a configuration error and
+ * is rejected at factory time.
+ */
+export type RscSsrMode = Exclude<SsrMode, "data-only">;
+
+/**
+ * Compiled RSC loader signature.
+ *
+ * Receives the resolved route's `params` and returns a `ReactNode` (a Server
+ * Component element, sync or async). Synchronous return is permitted because
+ * many Server Components are synchronous — wrapping them in `Promise.resolve`
+ * would be ceremonial.
+ */
+export type RscLoaderFn = SsrLoaderFn<ReactNode>;
+
+/**
+ * Factory function for creating RSC loaders.
+ *
+ * Receives the router instance and a dependency getter (same pattern as
+ * `DataLoaderFnFactory`/`GuardFnFactory`). Factory runs once at
+ * `usePlugin()` time; the returned loader is cached.
+ *
+ * @template Dependencies - Router dependency map for typed `getDependency()`.
+ *   Defaults to `DefaultDependencies`. Pass your app's dependency interface
+ *   for type-safe DI: `RscLoaderFnFactory<AppDependencies>`.
+ */
+export type RscLoaderFnFactory<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> = SsrLoaderFnFactory<ReactNode, Dependencies>;
+
+/**
+ * Per-route entry: either a loader factory (short form) or
+ * `{ ssr?, loader? }` object form. Mode defaults to `"full"`.
+ *
+ * Allowed `ssr` values for RSC: `"full"` | `"client-only"` (and the
+ * `true` / `false` aliases). `"data-only"` is rejected at factory time.
+ *
+ * Function form `(state) => RscSsrMode` is resolved per-navigation,
+ * **before** the mode is written to context.
+ */
+export type RscRouteEntry<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> = SsrRouteEntry<ReactNode, RscSsrMode, Dependencies>;
+
+/**
+ * Map of route name → entry (factory or `{ ssr?, loader? }`).
+ *
+ * Pass to `rscServerPluginFactory()`. Keys are route names (e.g. `"users.profile"`);
+ * values are factory or object-form route entries.
+ */
+export type RscLoaderFactoryMap<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> = Record<string, RscRouteEntry<Dependencies>>;
+
+/**
+ * Server Action result published by `rscActionPluginFactory` to
+ * `state.context.rscAction`. Consumers read either field at render
+ * time. Both are optional — typical flows write one or the other:
+ *
+ * - `returnValue` — set when the action was invoked via the hydrated
+ *   client path (`setServerCallback` → `loadServerAction` →
+ *   `decodeReply` in the RSC entry). Threaded back into
+ *   `useActionState` on the client.
+ * - `formState` — set when the action was invoked via progressive
+ *   enhancement (`<form action={fn}>` POST without JS) and decoded
+ *   via `decodeAction(formData)` + `decodeFormState(result, formData)`.
+ *
+ * Both type parameters default to `unknown` to keep the plugin
+ * runtime-only — consumers narrow them at the call site.
+ */
+export interface RscActionResult<TReturn = unknown, TFormState = unknown> {
+  returnValue?: { ok: boolean; data: TReturn };
+  formState?: TFormState;
+}
+
+/**
+ * Canonical Flight payload shape for RSC apps that ship Server Actions.
+ *
+ * The pipeline serializes this object via the bundler's RSC stream
+ * renderer (e.g. `@vitejs/plugin-rsc/rsc.renderToReadableStream`); the
+ * SSR + browser entries deserialize the same shape and thread
+ * `returnValue`/`formState` into `useActionState`.
+ *
+ * Apps without Server Actions can use `RscPayload` with all generics
+ * defaulted, or just type their payload as `{ root: ReactNode }`.
+ *
+ * Type parameters:
+ * - `TReturn` — narrowed shape of `returnValue.data` (e.g. mutation
+ *   confirmation). Defaults to `unknown`.
+ * - `TFormState` — narrowed shape of `formState`. Defaults to
+ *   `unknown` so the plugin stays free of `react-dom/client` import
+ *   (which carries the canonical `ReactFormState` type). Consumers
+ *   narrow at call site:
+ *
+ *   ```ts
+ *   import type { ReactFormState } from "react-dom/client";
+ *   type AppPayload = RscPayload<{ id: string }, ReactFormState>;
+ *   ```
+ */
+export interface RscPayload<
+  TReturn = unknown,
+  TFormState = unknown,
+> extends RscActionResult<TReturn, TFormState> {
+  /** Server Component tree to render. */
+  root: ReactNode;
+}