@wular/pnext 0.0.1

package/src/compat/actions/instances.ts

@@ -0,0 +1,144 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Runtime registry for INLINE server actions: functions with a 'use server' body directive that cross
+ * the server->client boundary as live closures - inline functions in server components, `.bind()`
+ * results, and HOC-wrapped actions. These cannot be resolved to a stable module export, so pnext (which
+ * has no compiler pass to hoist them) registers the live function instance at render time.
+ *
+ * Id scheme: `i:<routeId>:<hash>:<n>` where `hash` fingerprints the function source and `n`
+ * disambiguates same-source occurrences in tree order within one render. The id is deterministic for a
+ * deterministic render, so ids baked into static HTML can be re-materialized at runtime: on a registry
+ * miss the server re-renders the route, which re-registers the same ids, then retries the lookup.
+ *
+ * DIVERGENCE from Next: Next serializes the closure's captured variables into the page (encrypted) and
+ * re-hydrates them per request. pnext instead holds the live closure from the most recent render of the
+ * route in this process. Captured constants behave identically; closures over per-request state see the
+ * values of the most recent render rather than the exact render the user saw. Multi-process deployments
+ * only work because of the re-render path.
+ */
+
+const instances = new Map<string, (...args: unknown[]) => unknown>();
+
+/** Per-render dedup state; create one per page render and thread it through. */
+export interface InstanceScope {
+  routeId: string;
+  counts: Map<string, number>;
+}
+
+export function createInstanceScope(routeId: string): InstanceScope {
+  return { routeId, counts: new Map() };
+}
+
+/**
+ * Register a live action function for the scope's route. Returns the wire id.
+ * Calling again with the same scope position (same source hash, same
+ * occurrence index) overwrites the previous render's instance.
+ */
+export function registerActionInstance(scope: InstanceScope, fn: unknown): string {
+  const callable = fn as (...args: unknown[]) => unknown;
+  const hash = sourceHash(callable);
+  const index = scope.counts.get(hash) ?? 0;
+  scope.counts.set(hash, index + 1);
+  const id = `i:${scope.routeId}:${hash}:${index}`;
+  instances.set(id, callable);
+  return id;
+}
+
+/** Live instance for an id, if this process has rendered it. */
+export function lookupActionInstance(id: string) {
+  return instances.get(id);
+}
+
+export function isInstanceActionId(id: string) {
+  return id.startsWith('i:');
+}
+
+/** Route id encoded in an instance action id, for the re-render fallback. */
+export function instanceActionRouteId(id: string): string | undefined {
+  if (!isInstanceActionId(id)) return undefined;
+  // i:<routeId>:<hash>:<n> — routeId may itself contain ':'? Route ids are
+  // path-derived and never contain ':', so a simple split is safe; hash and n
+  // are the last two segments.
+  const parts = id.split(':');
+  if (parts.length < 4) return undefined;
+  return parts.slice(1, -2).join(':');
+}
+
+export function clearActionInstances() {
+  instances.clear();
+}
+
+/**
+ * Compile-time-injected registration for MODULE-SCOPE inline actions (a `'use server'` body directive
+ * on a top-level function that is not part of a module-level 'use server' file). The server compile
+ * pipeline appends a tagging call after each such declaration, which registers the live function under
+ * a stable id and mirrors React's registerServerReference metadata by defining `$$id` - real-world code
+ * introspects and even overrides it to simulate version skew. A caller-overridden `$$id` wins as the
+ * wire id, so skewed ids produce the failed-to-find flow exactly like Next.
+ */
+export interface TaggedActionFunction {
+  (...args: unknown[]): unknown;
+  $$id?: string;
+  $$pnextAssignedId?: string;
+  $$pnextInlineAction?: true;
+}
+
+declare global {
+  var __pnextTagInlineAction: ((fn: unknown, id: string) => void) | undefined;
+  var __pnextMarkInlineAction: (<T>(fn: T) => T) | undefined;
+}
+
+/**
+ * Compile-time-injected mark for ANONYMOUS inline server actions - a function expression whose body
+ * opens with `'use server'` and that is passed straight to a prop/argument. Such a function has no name
+ * to hang a stable id on, and the runtime cannot recover the directive from String(fn): the loader that
+ * evaluates the compiled module strips directive prologues. The mark is the only thing left that
+ * separates it from a plain client handler at serialization time.
+ */
+globalThis.__pnextMarkInlineAction = <T>(fn: T): T => {
+  if (typeof fn === 'function') (fn as TaggedActionFunction).$$pnextInlineAction = true;
+  return fn;
+};
+
+/** True for a compile-marked anonymous inline 'use server' function. */
+export function isMarkedInlineAction(fn: unknown): boolean {
+  return typeof fn === 'function' && (fn as TaggedActionFunction).$$pnextInlineAction === true;
+}
+
+globalThis.__pnextTagInlineAction = (fn: unknown, id: string) => {
+  if (typeof fn !== 'function') return;
+  const tagged = fn as TaggedActionFunction;
+  instances.set(id, tagged);
+  tagged.$$pnextAssignedId = id;
+  if (!('$$id' in tagged)) {
+    Object.defineProperty(tagged, '$$id', { value: id, configurable: true, writable: true });
+  }
+};
+
+/** Caller-overridden $$id (version-skew simulation) wins as the wire id. */
+export function overriddenActionId(fn: unknown): string | undefined {
+  if (typeof fn !== 'function') return undefined;
+  const tagged = fn as TaggedActionFunction;
+  if (typeof tagged.$$id === 'string' && tagged.$$id !== tagged.$$pnextAssignedId) {
+    return tagged.$$id;
+  }
+  return undefined;
+}
+
+/** Stable assigned id for a compile-tagged module-scope inline action. */
+export function assignedInlineActionId(fn: unknown): string | undefined {
+  if (typeof fn !== 'function') return undefined;
+  const tagged = fn as TaggedActionFunction;
+  return typeof tagged.$$pnextAssignedId === 'string' ? tagged.$$pnextAssignedId : undefined;
+}
+
+function sourceHash(fn: (...args: unknown[]) => unknown) {
+  let source = '';
+  try {
+    source = String(fn);
+  } catch {
+    source = 'opaque';
+  }
+  return createHash('sha256').update(source).digest('hex').slice(0, 10);
+}

package/src/compat/actions/origin.ts

@@ -0,0 +1,109 @@
+// Server Actions CSRF origin validation (COMPAT).
+//
+// Mirrors Next's action-handler origin check: an action POST carrying an
+// `origin` header whose host does not match the request host (`x-forwarded-host`
+// preferred, else `host`) is rejected unless the origin is whitelisted via
+// `experimental.serverActions.allowedOrigins`. Opaque origins ('null', e.g. a
+// sandboxed iframe) are treated as the literal host 'null'. A missing origin is
+// allowed (handcrafted request; can't carry unwilling credentials).
+
+import { getNextConfig } from '../next/config-loader';
+
+export const INVALID_ORIGIN_MESSAGE = 'Invalid Server Actions request.';
+
+/** Read experimental.serverActions.allowedOrigins (also the top-level key). */
+export function allowedOrigins(): string[] {
+  const config = getNextConfig();
+  const top = (config.serverActions as { allowedOrigins?: unknown } | undefined)?.allowedOrigins;
+  const experimental = config.experimental as
+    | { serverActions?: { allowedOrigins?: unknown } | boolean }
+    | undefined;
+  const exp =
+    experimental && typeof experimental.serverActions === 'object'
+      ? experimental.serverActions.allowedOrigins
+      : undefined;
+  const list = top ?? exp;
+  return Array.isArray(list) ? list.filter((v): v is string => typeof v === 'string') : [];
+}
+
+function firstHeaderValue(value: string | null): string | undefined {
+  if (value === null) return undefined;
+  return value.split(',')[0]?.trim() || undefined;
+}
+
+/** Request host used to compare against the origin (x-forwarded-host > host). */
+function requestHost(headers: Headers): string | undefined {
+  return firstHeaderValue(headers.get('x-forwarded-host')) ?? headers.get('host') ?? undefined;
+}
+
+function originHost(headers: Headers): string | undefined {
+  const origin = headers.get('origin');
+  if (origin === null) return undefined;
+  if (origin === 'null') return 'null';
+  try {
+    return new URL(origin).host;
+  } catch {
+    return undefined;
+  }
+}
+
+function matchWildcardDomain(domain: string, pattern: string): boolean {
+  const normalizedDomain = domain.replace(/[A-Z]/g, c => c.toLowerCase());
+  const normalizedPattern = pattern.replace(/[A-Z]/g, c => c.toLowerCase());
+  const domainParts = normalizedDomain.split('.');
+  const patternParts = normalizedPattern.split('.');
+  if (patternParts.length < 1) return false;
+  if (domainParts.length < patternParts.length) return false;
+  if (patternParts.length === 1 && (patternParts[0] === '*' || patternParts[0] === '**')) {
+    return false;
+  }
+  while (patternParts.length) {
+    const patternPart = patternParts.pop();
+    const domainPart = domainParts.pop();
+    if (patternPart === '') return false;
+    if (patternPart === '*') {
+      if (domainPart) continue;
+      return false;
+    }
+    if (patternPart === '**') {
+      if (patternParts.length > 0) return false;
+      return domainPart !== undefined;
+    }
+    if (domainPart !== patternPart) return false;
+  }
+  return domainParts.length === 0;
+}
+
+function isCsrfOriginAllowed(originDomain: string, origins: string[]): boolean {
+  const normalizedOrigin = originDomain.replace(/[A-Z]/g, c => c.toLowerCase());
+  return origins.some(allowed => {
+    if (!allowed) return false;
+    const normalizedAllowed = allowed.replace(/[A-Z]/g, c => c.toLowerCase());
+    return normalizedAllowed === normalizedOrigin || matchWildcardDomain(originDomain, allowed);
+  });
+}
+
+/**
+ * Returns true when the request passes the CSRF origin check (or has no origin
+ * to check). Returns false when the action must be aborted; the caller responds
+ * with the "Invalid Server Actions request." error. Logs the mismatch like Next.
+ */
+export function isActionOriginAllowed(request: Request): boolean {
+  const headers = request.headers;
+  const oHost = originHost(headers);
+  if (oHost === undefined) return true;
+  const host = requestHost(headers);
+  if (host !== undefined && oHost === host) return true;
+  if (isCsrfOriginAllowed(oHost, allowedOrigins())) return true;
+  if (host) {
+    const hostType = headers.has('x-forwarded-host') ? 'x-forwarded-host' : 'host';
+    console.error(
+      `\`${hostType}\` header with value \`${host}\` does not match \`origin\` header with value \`${oHost}\` from a forwarded Server Actions request. Aborting the action.`,
+    );
+  } else {
+    console.error(
+      '`x-forwarded-host` or `host` headers are not provided. One of these is needed to compare the `origin` header from a forwarded Server Actions request. Aborting the action.',
+    );
+  }
+  return false;
+}

package/src/compat/actions/protocol.ts

@@ -0,0 +1,125 @@
+/**
+ * Wire contract shared by the client runtime and the server endpoint. Keeping
+ * the constants in one place guarantees the two sides never drift.
+ *
+ * The wire shape mirrors Next.js where tests can observe it:
+ * - Actions POST to the CURRENT PAGE URL (not a bespoke endpoint) with the
+ *   action id in the `next-action` header.
+ * - JSON-args bodies use content-type text/plain; form submissions send
+ *   multipart/form-data (or urlencoded for no-JS submits).
+ * - Server errors come back as text/plain; the client treats any non-ok
+ *   response with a different content-type as "unexpected response".
+ */
+
+/** Header carrying the action id from client -> server. Mirrors Next's name. */
+export const ACTION_ID_HEADER = 'next-action';
+
+/**
+ * Response header set on a redirect result so the client can distinguish a
+ * framework redirect (soft-navigable) from an arbitrary 303 it should follow.
+ */
+export const ACTION_REDIRECT_HEADER = 'x-action-redirect';
+
+/**
+ * Response header telling the client to soft-refresh the current route after a
+ * successful action: set when the action revalidated data (revalidatePath/
+ * revalidateTag) or mutated cookies, mirroring when Next invalidates its
+ * client router cache.
+ */
+export const ACTION_REFRESH_HEADER = 'x-pnext-action-refresh';
+
+/** Next's public action revalidation header. `1` means static+dynamic invalidated. */
+export const NEXT_ACTION_REVALIDATED_HEADER = 'x-action-revalidated';
+
+/** Response header marking a notFound() result (body is the 404 page HTML). */
+export const ACTION_NOT_FOUND_HEADER = 'x-pnext-action-not-found';
+
+/**
+ * Next's own action-not-found marker (`x-nextjs-action-not-found`). Set on the
+ * 404 response for an unknown/unrecognized action id so tooling and the
+ * no-server-actions suite observe it; distinct from ACTION_NOT_FOUND_HEADER,
+ * which drives the client's 404-page swap for a notFound() result.
+ */
+export const NEXT_ACTION_NOT_FOUND_HEADER = 'x-nextjs-action-not-found';
+
+/** Response header carrying redirect(location, RedirectType.replace) intent. */
+export const REDIRECT_TYPE_HEADER = 'x-pnext-redirect-type';
+
+/**
+ * Response header carrying the boundary digest of a masked action error. Next
+ * transports the digest to the client so a caught action error exposes
+ * `error.digest`; the redacted 500 body hides the message, so the digest rides
+ * this header and the client stamps it onto the thrown Error. Computed with the
+ * same deterministic scheme as the render boundary digest (error-serialize.ts),
+ * so it matches the `digest: '<digest>'` line printed to the server log.
+ */
+export const ACTION_ERROR_DIGEST_HEADER = 'x-pnext-action-error-digest';
+
+/** Argument marker for a server-action function reference passed as an arg. */
+export const ARG_ACTION_MARKER = '$$pnext_action_ref';
+
+/**
+ * Hidden form field carrying the action id for no-JS progressive enhancement, emitted in
+ * <form action={serverAction}> so a plain HTML submit - which cannot set the next-action header -
+ * still identifies the form's action. A per-button `formAction` override uses SUBMIT_ACTION_ID_FIELD
+ * instead so it is unambiguous regardless of DOM order: the form-level field renders LAST inside
+ * client-island forms, so a shared field name could not tell the two apart.
+ */
+export const ACTION_ID_FIELD = '$pnext_action_id';
+
+/**
+ * Field name a `<button formAction>` submitter carries its action id under, submitted only when it is
+ * the submitter. Distinct from ACTION_ID_FIELD so the server can prefer a submitter override over the
+ * surrounding form's default without relying on field order - a no-JS submit has no `event.submitter`
+ * to disambiguate them.
+ */
+export const SUBMIT_ACTION_ID_FIELD = '$pnext_submit_action_id';
+
+/**
+ * Multipart field name carrying the JSON-encoded argument list when a call
+ * mixes JSON args with FormData/File values (e.g. bound args ahead of a form
+ * submission). Slots reference the other multipart parts.
+ */
+export const ACTION_ARGS_FIELD = '$pnext_args';
+
+/**
+ * Hidden form field carrying a useActionState form's CURRENT state (JSON) for
+ * no-JS progressive submissions. The server runs `action(state, formData)` and
+ * re-renders the page with the result as the form's new state.
+ */
+export const FORM_STATE_FIELD = '$pnext_form_state';
+
+/** Marker key for a FormData argument slot inside ACTION_ARGS_FIELD JSON. */
+export const ARG_FORMDATA_MARKER = '$$pnext_fd';
+
+/** Marker key for a File argument slot inside ACTION_ARGS_FIELD JSON. */
+export const ARG_FILE_MARKER = '$$pnext_file';
+
+/** Prefix for multipart parts belonging to a FormData argument slot. */
+export const ARG_FORMDATA_PREFIX = '$pnext_fd_';
+
+/** Prefix for multipart parts holding a File argument slot. */
+export const ARG_FILE_PREFIX = '$pnext_file_';
+
+/** Serialized-prop marker for a server-action function passed to an island. */
+export const PROP_ACTION_MARKER = '$$pnextAction';
+
+/** Maximum action argument list length, mirroring Next's guard. */
+export const MAX_ACTION_ARGS = 1000;
+
+export function tooManyArgsMessage(count: number) {
+  return `Server Action arguments list is too long (${count}). Maximum allowed is ${MAX_ACTION_ARGS}.`;
+}
+
+/**
+ * The exact text a masked production action error renders as on the client (React's minified
+ * flight-client error). Next's e2e tests assert this string verbatim via their error boundaries, so
+ * prod builds send it as the text/plain error body and the client throws it as the Error message.
+ */
+export const MASKED_ACTION_ERROR =
+  'Minified React error #441; visit https://react.dev/errors/441 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.';
+
+/** JSON success envelope: { data } (application/json, status 200). */
+export interface ActionSuccessBody {
+  data: unknown;
+}

package/src/compat/actions/registry.ts

@@ -0,0 +1,74 @@
+import { actionId } from './ids';
+
+/**
+ * In-process registry mapping a stable actionId -> the module + export that
+ * implements it. Populated at build/startup by the wiring agent from the route
+ * manifest; read by the runtime endpoint to resolve an incoming action id.
+ *
+ * The id is computed with the same `actionId` scheme the client stub uses, so a
+ * registration and its client stub always agree on the wire id.
+ */
+
+export interface ActionEntry {
+  /** actionId(filePath, exportName, root) — the wire id. */
+  id: string;
+  /** Module path the wiring agent will hand to importModule(). */
+  modulePath: string;
+  /** Named export within the module implementing the action. */
+  exportName: string;
+  /**
+   * The SOURCE file the id was computed from (workspace-relative when the registration passed `root`,
+   * otherwise as given). Used to decide whether a POSTed route's module graph contains the action -
+   * Next's "forwarded action" discrimination, see serve.ts isForwardedAction.
+   */
+  filePath: string;
+}
+
+const registry = new Map<string, ActionEntry>();
+
+/**
+ * Register every action export of a module. `filePath` identifies the module for
+ * id computation (workspace-relative when `root` is given); `modulePath` is what
+ * gets stored for the endpoint's importModule() (may differ, e.g. a compiled
+ * output path). When `modulePath` is omitted it defaults to `filePath`.
+ *
+ * Returns the entries that were registered (with their ids), so callers can emit
+ * matching client stubs.
+ */
+export function registerActionModule(
+  filePath: string,
+  exportNames: readonly string[],
+  options: { root?: string; modulePath?: string } = {},
+): ActionEntry[] {
+  const modulePath = options.modulePath ?? filePath;
+  const entries: ActionEntry[] = [];
+  for (const exportName of exportNames) {
+    const id = actionId(filePath, exportName, options.root);
+    const entry: ActionEntry = { id, modulePath, exportName, filePath };
+    registry.set(id, entry);
+    entries.push(entry);
+  }
+  return entries;
+}
+
+/** Resolve an action id to its module + export, or undefined if unknown. */
+export function lookupAction(id: string): { modulePath: string; exportName: string } | undefined {
+  const entry = registry.get(id);
+  if (!entry) return undefined;
+  return { modulePath: entry.modulePath, exportName: entry.exportName };
+}
+
+/** The source file a registered action id was computed from, or undefined. */
+export function lookupActionSource(id: string): string | undefined {
+  return registry.get(id)?.filePath;
+}
+
+/** Snapshot of all registered actions. */
+export function allActions(): ActionEntry[] {
+  return [...registry.values()];
+}
+
+/** Clear the registry (test/rebuild support). */
+export function clearActions(): void {
+  registry.clear();
+}