@bleedingdev/modern-js-runtime-extensions 3.9.0-ultramodern.4 → 3.9.0-ultramodern.6

package/src/routerState.ts

@@ -0,0 +1,208 @@
+// @effect-diagnostics asyncFunction:off strictBooleanExpressions:off
+import { createRuntimeContextExtension } from './contextExtensions';
+import type {
+  InternalRouterRuntimeState,
+  InternalRouterServerSnapshot,
+  RouterRouteMatchSnapshot,
+  RouterServerPrepareResult,
+} from './routerStateTypes';
+
+export type {
+  BuiltInRouterFramework,
+  InternalRouterRuntimeState,
+  InternalRouterServerSnapshot,
+  RouterFramework,
+  RouterLifecyclePhase,
+  RouterRouteMatchSnapshot,
+  RouterServerPrepareResult,
+} from './routerStateTypes';
+
+/**
+ * Router runtime state is shared by every router provider (react-router,
+ * @modern-js/plugin-tanstack, ...) and consumed by the SSR pipeline. It lives
+ * in the runtime-context extension slot instead of ad-hoc fields on
+ * `TInternalRuntimeContext`.
+ */
+const routerRuntimeStateExtension =
+  createRuntimeContextExtension<InternalRouterRuntimeState>(
+    '@modern-js/runtime:router-runtime-state',
+  );
+
+/**
+ * The server snapshot is tracked separately: a later
+ * `applyRouterRuntimeState` call without a snapshot must not clear a
+ * previously captured one.
+ */
+const routerServerSnapshotExtension =
+  createRuntimeContextExtension<InternalRouterServerSnapshot>(
+    '@modern-js/runtime:router-server-snapshot',
+  );
+
+export function getRouterRuntimeState(
+  runtimeContext: object,
+): InternalRouterRuntimeState | undefined {
+  return routerRuntimeStateExtension.get(runtimeContext);
+}
+
+export function getRouterServerSnapshot(
+  runtimeContext: object,
+): InternalRouterServerSnapshot | undefined {
+  return routerServerSnapshotExtension.get(runtimeContext);
+}
+
+type RouterSnapshotLike = Partial<InternalRouterServerSnapshot>;
+
+function toHydrationScripts(state: {
+  hydrationScript?: string;
+  hydrationScripts?: string[];
+}) {
+  if (state.hydrationScripts?.length) {
+    return state.hydrationScripts;
+  }
+
+  return state.hydrationScript ? [state.hydrationScript] : undefined;
+}
+
+function getMatchedRouteIdsFromMatches(matches?: RouterRouteMatchSnapshot[]) {
+  const routeIds = matches
+    ?.map(match => match.assetRouteId ?? match.routeId)
+    .filter((routeId): routeId is string => typeof routeId === 'string');
+
+  return routeIds?.length ? routeIds : undefined;
+}
+
+export function createRouterServerSnapshot(
+  state: RouterSnapshotLike,
+): InternalRouterServerSnapshot {
+  const hydrationScripts = toHydrationScripts(state);
+  const matchedRouteIds =
+    state.matchedRouteIds ?? getMatchedRouteIdsFromMatches(state.matches);
+
+  return {
+    ...state,
+    ...(hydrationScripts?.length
+      ? {
+          hydrationScript: state.hydrationScript ?? hydrationScripts[0],
+          hydrationScripts,
+        }
+      : {}),
+    ...(matchedRouteIds ? { matchedRouteIds } : {}),
+  };
+}
+
+export function createRouterRuntimeState(
+  state: InternalRouterRuntimeState,
+): InternalRouterRuntimeState {
+  const hasSnapshotState =
+    Boolean(state.serverSnapshot) ||
+    Boolean(state.hydrationScript) ||
+    Boolean(state.hydrationScripts?.length) ||
+    Boolean(state.matchedRouteIds?.length) ||
+    Boolean(state.matches?.length);
+  const serverSnapshot = state.serverSnapshot
+    ? createRouterServerSnapshot({
+        ...state.serverSnapshot,
+        framework: state.serverSnapshot.framework ?? state.framework,
+        basename: state.serverSnapshot.basename ?? state.basename,
+        hydrationScript:
+          state.serverSnapshot.hydrationScript ?? state.hydrationScript,
+        hydrationScripts:
+          state.serverSnapshot.hydrationScripts ?? state.hydrationScripts,
+        matchedRouteIds:
+          state.serverSnapshot.matchedRouteIds ?? state.matchedRouteIds,
+        matches: state.serverSnapshot.matches ?? state.matches,
+      })
+    : hasSnapshotState
+      ? createRouterServerSnapshot({
+          framework: state.framework,
+          basename: state.basename,
+          hydrationScript: state.hydrationScript,
+          hydrationScripts: state.hydrationScripts,
+          matchedRouteIds: state.matchedRouteIds,
+          matches: state.matches,
+        })
+      : undefined;
+  const hydrationScripts = toHydrationScripts({
+    hydrationScript: state.hydrationScript ?? serverSnapshot?.hydrationScript,
+    hydrationScripts:
+      state.hydrationScripts ?? serverSnapshot?.hydrationScripts,
+  });
+  const matchedRouteIds =
+    state.matchedRouteIds ??
+    serverSnapshot?.matchedRouteIds ??
+    getMatchedRouteIdsFromMatches(state.matches);
+
+  return {
+    ...state,
+    ...(hydrationScripts?.length
+      ? {
+          hydrationScript: state.hydrationScript ?? hydrationScripts[0],
+          hydrationScripts,
+        }
+      : {}),
+    ...(matchedRouteIds ? { matchedRouteIds } : {}),
+    ...(serverSnapshot ? { serverSnapshot } : {}),
+  };
+}
+
+export function applyRouterRuntimeState<Context extends object>(
+  runtimeContext: Context,
+  state: InternalRouterRuntimeState,
+) {
+  const normalized = createRouterRuntimeState(state);
+  routerRuntimeStateExtension.set(runtimeContext, normalized);
+  if (normalized.serverSnapshot) {
+    routerServerSnapshotExtension.set(
+      runtimeContext,
+      normalized.serverSnapshot,
+    );
+  }
+
+  return runtimeContext;
+}
+
+export function applyRouterServerPrepareResult<Context extends object>(
+  runtimeContext: Context,
+  result: RouterServerPrepareResult,
+) {
+  const state = createRouterRuntimeState({
+    ...result.state,
+    cleanup: result.cleanup ?? result.state.cleanup,
+    serverSnapshot: result.snapshot ?? result.state.serverSnapshot,
+  });
+  applyRouterRuntimeState(runtimeContext, state);
+  return runtimeContext;
+}
+
+export function getRouterHydrationScripts(runtimeContext: object) {
+  const serverSnapshot = getRouterServerSnapshot(runtimeContext);
+  const runtimeState = getRouterRuntimeState(runtimeContext);
+  return (
+    serverSnapshot?.hydrationScripts ??
+    toHydrationScripts({
+      hydrationScript: serverSnapshot?.hydrationScript,
+    }) ??
+    runtimeState?.hydrationScripts ??
+    toHydrationScripts({
+      hydrationScript: runtimeState?.hydrationScript,
+    }) ??
+    []
+  );
+}
+
+export function getRouterMatchedRouteIds(runtimeContext: object) {
+  const serverSnapshot = getRouterServerSnapshot(runtimeContext);
+  const runtimeState = getRouterRuntimeState(runtimeContext);
+  return (
+    serverSnapshot?.matchedRouteIds ??
+    getMatchedRouteIdsFromMatches(serverSnapshot?.matches) ??
+    runtimeState?.matchedRouteIds ??
+    getMatchedRouteIdsFromMatches(runtimeState?.matches)
+  );
+}
+
+export async function cleanupRouterRuntimeState(runtimeContext: object) {
+  try {
+    await getRouterRuntimeState(runtimeContext)?.cleanup?.();
+  } catch {}
+}

package/src/routerStatePlugin.ts

@@ -0,0 +1,86 @@
+import { createRouterPrefetchPolicy } from './routerPrefetchPolicy';
+import {
+  applyRouterRuntimeState,
+  createRouterServerSnapshot,
+} from './routerState';
+
+type ReactRouterServerContext = {
+  statusCode: number;
+  errors?: Record<string, unknown> | null;
+  loaderData: Record<string, unknown>;
+  matches: { route: { id?: string } }[];
+};
+
+type RouterLifecycleEvent = {
+  framework: string;
+  phase: string;
+  runtimeContext: object;
+  basename?: string;
+  router?: unknown;
+};
+
+/** Install fork policy through lifecycle hooks supplied by the native owner. */
+export function createRouterStatePlugin<Hooks extends Record<string, unknown>>({
+  registryHooks,
+}: {
+  registryHooks: Hooks;
+}) {
+  return {
+    name: '@modern-js/router-runtime-policy',
+    registryHooks,
+    setup(api: {
+      onBeforeRender: (callback: (context: object) => void) => unknown;
+      onAfterCreateRouter: (
+        callback: (event: RouterLifecycleEvent) => void,
+      ) => unknown;
+    }) {
+      api.onBeforeRender(context => {
+        const runtimeContext = context as {
+          linkPrefetchPolicy?: ReturnType<typeof createRouterPrefetchPolicy>;
+        };
+        runtimeContext.linkPrefetchPolicy ??= createRouterPrefetchPolicy();
+      });
+      api.onAfterCreateRouter(event => {
+        if (event.framework !== 'react-router') {
+          return;
+        }
+        if (event.phase === 'ssr-prepare') {
+          const { routerContext } = event.runtimeContext as {
+            routerContext?: ReactRouterServerContext;
+          };
+          if (!routerContext) {
+            return;
+          }
+          const serverSnapshot = createRouterServerSnapshot({
+            framework: event.framework,
+            basename: event.basename,
+            statusCode: routerContext.statusCode,
+            errors: routerContext.errors ?? undefined,
+            routerData: {
+              loaderData: routerContext.loaderData,
+              errors: routerContext.errors ?? undefined,
+            },
+            matches: routerContext.matches.flatMap(match =>
+              typeof match.route.id === 'string'
+                ? [{ routeId: match.route.id }]
+                : [],
+            ),
+          });
+          applyRouterRuntimeState(event.runtimeContext, {
+            framework: event.framework,
+            basename: event.basename,
+            instance: event.router,
+            matchedRouteIds: serverSnapshot.matchedRouteIds,
+            serverSnapshot,
+          });
+        } else if (event.phase === 'client-create') {
+          applyRouterRuntimeState(event.runtimeContext, {
+            framework: event.framework,
+            basename: event.basename,
+            instance: event.router,
+          });
+        }
+      });
+    },
+  };
+}

package/src/routerStateTypes.ts

@@ -0,0 +1,46 @@
+export type BuiltInRouterFramework = 'react-router' | 'tanstack';
+
+export type RouterFramework = BuiltInRouterFramework | (string & {});
+
+export interface RouterRouteMatchSnapshot {
+  routeId: string;
+  assetRouteId?: string;
+  pathname?: string;
+  params?: Record<string, string>;
+}
+
+export interface InternalRouterServerSnapshot {
+  framework?: RouterFramework;
+  basename?: string;
+  statusCode?: number;
+  errors?: Record<string, unknown>;
+  routerData?: {
+    loaderData?: Record<string, unknown>;
+    errors?: Record<string, unknown>;
+  };
+  hydrationScript?: string;
+  hydrationScripts?: string[];
+  matchedRouteIds?: string[];
+  matches?: RouterRouteMatchSnapshot[];
+}
+
+export interface InternalRouterRuntimeState {
+  framework: RouterFramework;
+  basename?: string;
+  instance?: unknown;
+  hydrationScript?: string;
+  hydrationScripts?: string[];
+  matchedRouteIds?: string[];
+  matches?: RouterRouteMatchSnapshot[];
+  serverSnapshot?: InternalRouterServerSnapshot;
+  cleanup?: () => void | Promise<void>;
+}
+
+export interface RouterServerPrepareResult {
+  state: InternalRouterRuntimeState;
+  snapshot?: InternalRouterServerSnapshot;
+  redirect?: Response;
+  cleanup?: () => void | Promise<void>;
+}
+
+export type RouterLifecyclePhase = 'ssr-prepare' | 'client-create' | 'hydrate';

package/src/runtimeContextProjection.ts

@@ -0,0 +1,105 @@
+import { stripRuntimeContextExtensions } from './contextExtensions';
+
+// Only the transport fields consumed by this projection are required. This
+// policy module does not depend on the native runtime or plugin API types.
+interface ProjectionContext {
+  isBrowser?: boolean;
+  ssrContext?: {
+    request: {
+      url?: unknown;
+      userAgent?: unknown;
+      cookie?: unknown;
+      pathname?: unknown;
+      query?: object;
+      params?: object;
+      headers?: object;
+      host?: unknown;
+      referer?: unknown;
+    };
+    response: { locals?: unknown };
+  };
+}
+
+function createRscSafeRequestContext(
+  ssrContext: ProjectionContext['ssrContext'],
+) {
+  const requestContext = {
+    request: {
+      params: {},
+      pathname: '',
+      query: {},
+      headers: {},
+      host: '',
+      url: '',
+    },
+    response: {
+      setHeader() {},
+      status() {},
+      locals: {} as unknown,
+    },
+  };
+  Object.defineProperty(requestContext.response, 'setHeader', {
+    enumerable: false,
+  });
+  Object.defineProperty(requestContext.response, 'status', {
+    enumerable: false,
+  });
+
+  if (ssrContext === undefined) {
+    return requestContext;
+  }
+
+  const { request, response } = ssrContext;
+  return {
+    request: {
+      url: request.url,
+      userAgent: request.userAgent,
+      cookie: request.cookie,
+      pathname: request.pathname,
+      query: { ...request.query },
+      params: { ...request.params },
+      headers: { ...request.headers },
+      host: request.host,
+      referer: request.referer,
+    },
+    response: Object.assign(requestContext.response, {
+      locals: response.locals ?? {},
+    }),
+  };
+}
+
+export function projectRuntimeContext<
+  InternalContext extends ProjectionContext,
+  PublicContext extends ProjectionContext,
+>(
+  projection: {
+    internalContext: InternalContext;
+    publicContext: PublicContext;
+  },
+  options: { context: InternalContext; isRsc: boolean },
+) {
+  let internalContext = projection.internalContext;
+  let publicContext = { ...projection.publicContext };
+  // Enumerable symbol slots deliberately survive internal SSR copies. Remove
+  // them only from the public projection, never from the original request.
+  stripRuntimeContextExtensions(publicContext);
+
+  if (options.isRsc && options.context.isBrowser === false) {
+    const requestContext = createRscSafeRequestContext(
+      options.context.ssrContext,
+    );
+    internalContext = {
+      ...internalContext,
+      context: requestContext,
+      requestContext,
+    };
+    delete internalContext.ssrContext;
+    publicContext = {
+      ...publicContext,
+      context: requestContext,
+      requestContext,
+    };
+  }
+
+  return { internalContext, publicContext };
+}

package/src/server-config/bffRuntime.ts

@@ -0,0 +1,136 @@
+export type BffRuntimeFramework = 'hono' | 'effect';
+
+/** Fork BFF options, independent of any native server config interface. */
+export interface BffRuntimeUserConfig {
+  runtimeFramework?: BffRuntimeFramework;
+  effect?: BffEffectUserConfig;
+  crossProjectPolicy?: BffCrossProjectPolicyUserConfig;
+}
+
+export interface BffCrossProjectPolicyUserConfig {
+  /**
+   * Enable cross-project envelope and operation-context policy checks.
+   *
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * Require cross-project envelope header when policy is enabled.
+   *
+   * @default true
+   */
+  requireEnvelope?: boolean;
+  /**
+   * Require operation-context header when policy is enabled.
+   *
+   * @default true
+   */
+  requireOperationContext?: boolean;
+  /**
+   * Require operation-context detail header carrying schema/version metadata.
+   *
+   * @default true
+   */
+  requireOperationContextDetails?: boolean;
+  /**
+   * Require operation schema hash in operation-context details.
+   *
+   * @default true
+   */
+  requireOperationSchemaHash?: boolean;
+  /**
+   * Require operation version in operation-context details.
+   *
+   * @default true
+   */
+  requireOperationVersion?: boolean;
+  /**
+   * Optional allowlist of producer namespaces derived from requestId.
+   */
+  allowedNamespaces?: string[];
+  /**
+   * Optional hook deriving a verified producer identity (namespace) from
+   * request headers, e.g. an mTLS subject or gateway-verified JWT claim.
+   * When provided, namespace checks bind to this verified value instead of
+   * the client-asserted requestId namespace; returning `undefined` denies
+   * the request. Without it the namespace checks are advisory only.
+   */
+  verifyProducerIdentity?: (
+    headers: Record<string, unknown>,
+  ) => string | undefined;
+  /**
+   * Optional operation-contract map keyed by:
+   * - `${METHOD}:${routePath}`
+   * - `operation:${requestId}:${operationId}`
+   */
+  expectedOperationContracts?: Record<
+    string,
+    {
+      schemaHash?: string;
+      operationVersion?: number;
+    }
+  >;
+  /**
+   * Allow operations missing from expectedOperationContracts.
+   *
+   * @default false
+   */
+  allowUnknownOperations?: boolean;
+  /**
+   * HTTP status code used for denied requests.
+   *
+   * @default 403
+   */
+  denyStatus?: number;
+}
+
+export type BffEffectOpenApiUserConfig =
+  | boolean
+  | {
+      path?: string;
+    };
+
+export interface BffEffectDataPlatformSelectionUserConfig {
+  maxDepth?: number;
+  maxFields?: number;
+  allowedLeafPaths?: string[];
+}
+
+export interface BffEffectDataPlatformBatchUserConfig {
+  enabled?: boolean;
+  endpoint?: `/${string}`;
+  maxBatchSize?: number;
+  maxBatchBytes?: number;
+  flushIntervalMs?: number;
+  maxConcurrency?: number;
+  requestTimeoutMs?: number;
+  allowedMethods?: string[];
+}
+
+export interface BffEffectDataPlatformUserConfig {
+  enabled?: boolean;
+  requireEnvelope?: boolean;
+  envelopeHeader?: string;
+  expectedNamespace?: string;
+  validateOrigin?: boolean;
+  requireTraceContext?: boolean;
+  selection?: BffEffectDataPlatformSelectionUserConfig;
+  batch?: BffEffectDataPlatformBatchUserConfig;
+}
+
+export interface BffEffectUserConfig {
+  entry?: string;
+  /**
+   * Enforce Effect-native API/runtime modules instead of raw request handlers.
+   *
+   * Effect API entries must export a `defineEffectBff(...)`
+   * definition or a `{ api, layer }` HttpApi module. Raw `handler` exports,
+   * default request handlers, and unbranded custom `createHandler` factories
+   * are rejected.
+   *
+   * @default true
+   */
+  strictEffectApproach?: true;
+  openapi?: BffEffectOpenApiUserConfig;
+  dataPlatform?: BffEffectDataPlatformUserConfig;
+}

package/src/server-config/index.ts

@@ -0,0 +1,2 @@
+export type * from './bffRuntime';
+export type * from './serverTelemetry';