@bleedingdev/modern-js-renderer-core 0.0.0-bootstrap → 3.9.3-ultramodern.1

package/src/entry-server.ts

@@ -0,0 +1,393 @@
+import { untilAborted } from './abort';
+import {
+  type DataOutcome,
+  handleDataRequest,
+  invokeRouteData,
+  normalizeDataResult,
+} from './data';
+import type { DocumentAsset, DocumentInlineData } from './document';
+import type { NativeFederationBinding } from './federation';
+import { assertRendererIdentity, type RendererIdentity } from './identity';
+import {
+  type NativeEntryI18n,
+  type NativeI18nInstance,
+  type NativeI18nView,
+  type NativeRequestLanguage,
+  nativeI18nView,
+} from './localization';
+import {
+  isRoutedApplication,
+  matchApplicationRouteIds,
+  type NativeApplicationModule,
+  type NativeRoutedApplication,
+  type NativeRouteMatch,
+  type NativeRouteMatcher,
+  type NativeRouterOptions,
+  selectApplicationDataRoute,
+} from './router';
+import type { NativeRequestContext, NativeServerManifest } from './server';
+import type { RequestSession } from './session';
+
+export type * from './localization';
+export type {
+  NativeApplicationModule,
+  NativeRoutedApplication,
+  NativeRouterOptions,
+} from './router';
+
+/** What a generated server entry passes to its renderer. */
+export interface NativeServerEntryOptions<
+  Instance extends NativeI18nInstance = NativeI18nInstance,
+  LocalisedUrls = unknown,
+> {
+  readonly identity: RendererIdentity;
+  readonly federation?: NativeFederationBinding;
+  /** The generated application module, imported per request. */
+  readonly app: () => Promise<NativeApplicationModule>;
+  readonly i18n?: NativeEntryI18n<Instance, LocalisedUrls>;
+  /** The document mount element id; the client entry must use the same. */
+  readonly rootId?: string;
+}
+
+/** The renderer-neutral part of one response document. */
+export interface NativeServerDocument {
+  readonly documentId: string;
+  readonly rootId: string;
+  readonly nonce?: string;
+  readonly assets?: readonly DocumentAsset[];
+  readonly lang?: string;
+  readonly inlineData?: readonly DocumentInlineData[];
+}
+
+export interface NativeServerRoutesInput<
+  Router,
+  Document,
+  Instance,
+  LocalisedUrls,
+> {
+  /** The request bound to the session signal; data loaders observe it. */
+  readonly request: Request;
+  readonly context: NativeRequestContext;
+  readonly router: Router;
+  /** Blocking data outcomes, recorded while the router loads. */
+  readonly outcomes: readonly DataOutcome[];
+  readonly document: Document;
+  /** Request-private values the router must never serialize. */
+  readonly forbiddenValues: readonly object[];
+  readonly i18n?: NativeI18nView<Instance, LocalisedUrls>;
+}
+
+/** The renderer's own request scope, manifest, router and document. */
+export interface NativeServerAdapter<
+  Router extends NativeRouteMatcher<unknown, NativeRouteMatch>,
+  Document extends NativeServerDocument,
+  Instance extends NativeI18nInstance,
+  LocalisedUrls,
+> {
+  /** Validate the compiler manifest and complete the document. */
+  document(
+    base: NativeServerDocument,
+    nativeManifest: unknown,
+    identity: Readonly<RendererIdentity>,
+  ): Document;
+  /** Run one request inside the renderer's native request scope. */
+  run<Result>(
+    session: RequestSession,
+    callback: () => Promise<Result>,
+  ): Promise<Result>;
+  /** Commit a terminal data or redirect response. */
+  respond(session: RequestSession, response: Response): Response;
+  createRouter(
+    application: NativeRoutedApplication,
+    options: NativeRouterOptions,
+  ): Router;
+  renderCSR(
+    context: NativeRequestContext,
+    document: Document,
+  ): Response | Promise<Response>;
+  renderComponent(
+    context: NativeRequestContext,
+    component: unknown,
+    document: Document,
+    i18n?: NativeI18nView<Instance, LocalisedUrls>,
+  ): Promise<Response>;
+  /** Load the router, resolve its HTTP outcome and render the document. */
+  renderRoutes(
+    input: NativeServerRoutesInput<Router, Document, Instance, LocalisedUrls>,
+  ): Promise<Response>;
+}
+
+export type NativeServerEntry = Required<NativeServerManifest>;
+
+function serverRouteLoader(
+  application: NativeRoutedApplication,
+): NativeRouterOptions['loadRoute'] {
+  return async (route, input) => {
+    const loader = application.dataModules[route.id]?.loader;
+    if (!loader) return { kind: 'success', value: undefined, status: 200 };
+    return invokeRouteData(loader, input, {
+      production: process.env.NODE_ENV !== 'development',
+    });
+  };
+}
+
+/** `vary` names the request headers a detected document language came from. */
+function resolveDocumentPolicy(
+  session: RequestSession,
+  vary?: readonly string[],
+): void {
+  if (!session.responsePolicy)
+    session.resolveResponse({
+      kind: 'document',
+      status: 200,
+      headers: [
+        ['content-type', 'text/html; charset=utf-8'],
+        ...(vary?.length ? [['vary', vary.join(', ')] as const] : []),
+      ],
+      cache: { mode: 'no-store' },
+    });
+}
+
+const detectedVary = (language: NativeRequestLanguage | undefined) =>
+  language?.kind === 'language' ? language.vary : undefined;
+
+/**
+ * Create the native transport handlers of a generated server entry: identity
+ * and session ownership, CSR and SSR documents, localized redirects, route
+ * matching and the data endpoint. The renderer adapter owns its request
+ * scope, router and document.
+ */
+export function createNativeServerEntry<
+  Router extends NativeRouteMatcher<unknown, NativeRouteMatch>,
+  Document extends NativeServerDocument,
+  Instance extends NativeI18nInstance,
+  LocalisedUrls,
+>(
+  options: NativeServerEntryOptions<Instance, LocalisedUrls>,
+  adapter: NativeServerAdapter<Router, Document, Instance, LocalisedUrls>,
+): NativeServerEntry {
+  const rendererIdentity = Object.freeze({ ...options.identity });
+  const { i18n } = options;
+
+  const own = (request: Request, context: NativeRequestContext) => {
+    assertRendererIdentity(context.entry, rendererIdentity);
+    assertRendererIdentity(context.session.identity, rendererIdentity);
+    if (request !== context.session.request)
+      throw new Error('Native request/session ownership mismatch');
+  };
+
+  const prepare = (request: Request, context: NativeRequestContext) => {
+    own(request, context);
+    return adapter.document(
+      {
+        documentId: crypto.randomUUID(),
+        rootId: options.rootId ?? 'root',
+        ...(context.nonce === undefined ? {} : { nonce: context.nonce }),
+        ...(context.assets === undefined ? {} : { assets: context.assets }),
+      },
+      context.nativeManifest,
+      rendererIdentity,
+    );
+  };
+
+  // Application and translation loads race the session signal: a stalled
+  // load, such as a development compilation, must not hold an aborted
+  // request, its context and its session.
+  const routedApplication = async (
+    signal: AbortSignal,
+  ): Promise<NativeRoutedApplication> => {
+    const application = await untilAborted(options.app(), signal);
+    if (!isRoutedApplication(application))
+      throw new Error(
+        'unsupported-renderer-capability: ssrByRouteIds requires native route matching.',
+      );
+    return application;
+  };
+
+  const nativeCSRRequestHandler = (
+    request: Request,
+    context: NativeRequestContext,
+  ) =>
+    adapter.run(context.session, async () => {
+      const document = prepare(request, context);
+      if (!i18n) {
+        resolveDocumentPolicy(context.session);
+        return adapter.renderCSR(context, document);
+      }
+      const language = i18n.resolveRequest(request);
+      if (language.kind === 'redirect')
+        return adapter.respond(
+          context.session,
+          i18n.redirect(language.location),
+        );
+      resolveDocumentPolicy(context.session, detectedVary(language));
+      return adapter.renderCSR(context, {
+        ...document,
+        lang: language.language,
+        inlineData: [i18n.handoff(language.language)],
+      });
+    });
+
+  const nativeMatchRouteIds = (
+    request: Request,
+    context: NativeRequestContext,
+  ) =>
+    adapter.run(context.session, async () => {
+      own(request, context);
+      const application = await routedApplication(context.session.signal);
+      const router = adapter.createRouter(application, {
+        identity: rendererIdentity,
+        loadRoute: serverRouteLoader(application),
+        request,
+        context: context.session.platform.bindings,
+        session: context.session,
+        ...(i18n
+          ? {
+              rewrite: i18n.rewrite(
+                () => i18n.resolveRequest(request).language,
+              ),
+            }
+          : {}),
+      });
+      return matchApplicationRouteIds(router, new URL(request.url));
+    });
+
+  const nativeRequestHandler = (
+    request: Request,
+    context: NativeRequestContext,
+  ) =>
+    adapter.run(context.session, async () => {
+      const document = prepare(request, context);
+      const { session } = context;
+      const application = await untilAborted(options.app(), session.signal);
+      const routed = isRoutedApplication(application);
+      const nativeRequest = routed
+        ? new Request(request, { signal: session.signal })
+        : request;
+      // One isolated instance per request; the URL decides its language.
+      const language = i18n?.resolveRequest(nativeRequest);
+      if (!routed && i18n && language?.kind === 'redirect')
+        return adapter.respond(session, i18n.redirect(language.location));
+      // Data requests and redirects never read translations, so the instance
+      // is created only once a document is about to render.
+      const localize = async (
+        inlineData: readonly DocumentInlineData[] = [],
+      ) => {
+        if (!i18n || !language) return { document, localization: undefined };
+        const instance = await untilAborted(
+          i18n.create(language.language),
+          session.signal,
+        );
+        return {
+          document: {
+            ...document,
+            lang: instance.language,
+            inlineData: [
+              ...inlineData,
+              i18n.handoff(instance.language, instance),
+            ],
+          },
+          localization: nativeI18nView(i18n, instance),
+        };
+      };
+      if (!routed) {
+        const localized = await localize(document.inlineData);
+        resolveDocumentPolicy(session, detectedVary(language));
+        return adapter.renderComponent(
+          context,
+          application.default,
+          localized.document,
+          localized.localization,
+        );
+      }
+      const bindings = session.platform.bindings;
+      const outcomes: DataOutcome[] = [];
+      // Loaders settle in any order, but later metadata wins singleton
+      // fields, so outcomes stay in matched parent-to-leaf route order.
+      const outcomeRanks: number[] = [];
+      let routeOrder: readonly string[] | undefined;
+      const addOutcome = (rank: number, outcome: DataOutcome) => {
+        const at = outcomeRanks.findIndex(other => other > rank);
+        const index = at < 0 ? outcomes.length : at;
+        outcomes.splice(index, 0, outcome);
+        outcomeRanks.splice(index, 0, rank);
+      };
+      const router = adapter.createRouter(application, {
+        identity: rendererIdentity,
+        loadRoute: serverRouteLoader(application),
+        request: nativeRequest,
+        context: bindings,
+        onOutcome: (routeId, outcome) => {
+          if ('response' in outcome) {
+            routeOrder ??= matchApplicationRouteIds(
+              router,
+              new URL(nativeRequest.url),
+            );
+            const rank = routeOrder.indexOf(routeId);
+            addOutcome(rank < 0 ? Number.POSITIVE_INFINITY : rank, outcome);
+          } else if (outcome.completion) {
+            const completion = outcome.completion;
+            void completion.catch(error => session.fail(error));
+            session.registerCleanup(() => completion);
+          }
+        },
+        session,
+        ...(context.nonce === undefined ? {} : { nonce: context.nonce }),
+        ...(i18n && language
+          ? { rewrite: i18n.rewrite(() => language.language) }
+          : {}),
+      });
+      const dataResponse = await handleDataRequest({
+        request: nativeRequest,
+        identity: rendererIdentity,
+        context: bindings,
+        privateValues: [context, session, session.platform, bindings],
+        // Only development keeps loader errors' messages; an unset mode stays private.
+        production: process.env.NODE_ENV !== 'development',
+        selectRoute: (dataRequest, routeId, operation) =>
+          selectApplicationDataRoute(
+            router,
+            dataRequest,
+            routeId,
+            operation,
+            application.dataModules,
+          ),
+      });
+      if (dataResponse) return adapter.respond(session, dataResponse);
+      if (i18n && language?.kind === 'redirect')
+        return adapter.respond(session, i18n.redirect(language.location));
+      // A header-detected language makes the document depend on those headers:
+      // the header-only outcome adds `Vary` and keeps it out of public caches.
+      const vary = detectedVary(language);
+      if (vary?.length)
+        addOutcome(
+          Number.POSITIVE_INFINITY,
+          await normalizeDataResult(
+            new Response(null, { headers: { vary: vary.join(', ') } }),
+          ),
+        );
+      const localized = await localize();
+      return adapter.renderRoutes({
+        request: nativeRequest,
+        context,
+        router,
+        outcomes,
+        document: localized.document,
+        forbiddenValues: [
+          context,
+          session,
+          session.platform,
+          bindings,
+          nativeRequest,
+        ],
+        ...(localized.localization ? { i18n: localized.localization } : {}),
+      });
+    });
+
+  return {
+    rendererIdentity,
+    nativeRequestHandler,
+    nativeCSRRequestHandler,
+    nativeMatchRouteIds,
+  };
+}

package/src/federation.ts

@@ -0,0 +1,111 @@
+/** The application compiler's native Module Federation runtime. */
+export interface FederationInstance {
+  /** The application's federation name, unique among this realm's instances. */
+  readonly name?: string;
+  loadRemote<T>(id: string): Promise<T | null>;
+  readonly remoteHandler?: {
+    readonly idToRemoteMap?: Record<string, { name: string; expose: string }>;
+  };
+  readonly moduleCache?: Map<string, { readonly remoteInfo: unknown }>;
+  readonly snapshotHandler?: {
+    getGlobalRemoteInfo(info: unknown): { remoteSnapshot?: RemoteSnapshot };
+  };
+}
+
+interface RemoteSnapshot {
+  readonly publicPath?: unknown;
+  readonly remoteEntry?: unknown;
+  readonly modules?: readonly {
+    readonly modulePath?: unknown;
+    readonly assets?: {
+      readonly js?: { readonly sync?: readonly string[] };
+      readonly css?: {
+        readonly sync?: readonly string[];
+        readonly async?: readonly string[];
+      };
+    };
+  }[];
+}
+
+/** Generated entries retain their own compiler's host, including on the server. */
+export interface NativeFederationBinding {
+  readonly instance: () => FederationInstance;
+  /**
+   * Server bindings: the client module, relative to the client asset base,
+   * that loads a server-rendered remote through this host before hydration.
+   */
+  readonly hydrationModule?: string;
+}
+
+export interface FederatedAssets {
+  readonly js: readonly string[];
+  readonly css: readonly string[];
+}
+
+/** Capture the host before importing application modules or remote containers. */
+export function getFederationHost(
+  binding: NativeFederationBinding | undefined,
+): FederationInstance | undefined {
+  if (binding === undefined) return undefined;
+  if (typeof binding?.instance !== 'function')
+    throw new TypeError('The native federation host binding is invalid.');
+  const instance = binding.instance();
+  if (!instance || typeof instance.loadRemote !== 'function')
+    throw new TypeError('The application federation runtime has not started.');
+  return instance;
+}
+
+/** Load through the selected application's runtime, never another app's host. */
+export async function loadFederatedModule<T>(
+  instance: FederationInstance | undefined,
+  id: string,
+): Promise<T> {
+  if (!instance)
+    throw new Error(
+      `Cannot load ${id}: this application has no Module Federation runtime. Add module-federation.config.ts with its remotes.`,
+    );
+  const module = await instance.loadRemote<T>(id);
+  if (!module) throw new Error(`Remote module ${id} is unavailable`);
+  return module;
+}
+
+/** Browser assets from the native snapshot that admitted and loaded this remote. */
+export function remoteBrowserAssets(
+  instance: FederationInstance,
+  id: string,
+): FederatedAssets | undefined {
+  const target = instance.remoteHandler?.idToRemoteMap?.[id];
+  const loaded = target && instance.moduleCache?.get(target.name);
+  const snapshot =
+    loaded &&
+    instance.snapshotHandler?.getGlobalRemoteInfo(loaded.remoteInfo)
+      .remoteSnapshot;
+  if (
+    !snapshot ||
+    typeof snapshot.publicPath !== 'string' ||
+    !snapshot.publicPath ||
+    typeof snapshot.remoteEntry !== 'string' ||
+    !snapshot.remoteEntry
+  )
+    return undefined;
+  const expose = snapshot.modules?.find(
+    module => module.modulePath === target.expose,
+  );
+  if (!expose?.assets) return undefined;
+  const publicPath = snapshot.publicPath;
+  const url = (file: string) =>
+    /^(?:https?:)?\/\//iu.test(file)
+      ? file
+      : `${publicPath.replace(/\/$/u, '')}/${file.replace(/^\//u, '')}`;
+  return {
+    js: [url(snapshot.remoteEntry), ...(expose.assets.js?.sync ?? []).map(url)],
+    css: [
+      ...new Set(
+        [
+          ...(expose.assets.css?.sync ?? []),
+          ...(expose.assets.css?.async ?? []),
+        ].map(url),
+      ),
+    ],
+  };
+}

package/src/identity.ts

@@ -0,0 +1,128 @@
+export type Renderer = string;
+
+/** Immutable identity for one application entry and its hydration bytes. */
+export interface RendererIdentity {
+  renderer: Renderer;
+  appId: string;
+  entryName: string;
+  protocolVersion: 1;
+  buildId: string;
+}
+
+export function resolveRenderer(value: unknown = 'react'): Renderer {
+  if (
+    typeof value === 'string' &&
+    value.trim() === value &&
+    /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(value)
+  )
+    return value;
+  throw new Error(`Unsupported UltraModern renderer: ${String(value)}`);
+}
+
+export function identityCacheKey(identity: RendererIdentity): string {
+  resolveRenderer(identity.renderer);
+  for (const key of ['appId', 'entryName', 'buildId'] as const) {
+    if (
+      typeof identity[key] !== 'string' ||
+      identity[key].trim().length === 0
+    ) {
+      throw new Error(`Renderer identity requires a nonempty ${key}`);
+    }
+  }
+  if (identity.protocolVersion !== 1) {
+    throw new Error('Unsupported renderer data protocol version');
+  }
+  return JSON.stringify([
+    identity.renderer,
+    identity.appId,
+    identity.entryName,
+    identity.protocolVersion,
+    identity.buildId,
+  ]);
+}
+
+export function assertRendererIdentity(
+  actual: RendererIdentity,
+  expected: RendererIdentity,
+): void {
+  if (identityCacheKey(actual) !== identityCacheKey(expected)) {
+    throw new Error('Renderer identity conflicts with the application build');
+  }
+}
+
+const IDENTITY_FIELDS = [
+  'renderer',
+  'appId',
+  'entryName',
+  'protocolVersion',
+  'buildId',
+] as const;
+
+/**
+ * Read an identity from untrusted JSON (a document bootstrap or a build
+ * manifest). It must be a plain record with exactly the identity fields and
+ * equal the identity this application was built with.
+ */
+export function readRendererIdentity(
+  value: unknown,
+  expected: RendererIdentity,
+): Readonly<RendererIdentity> {
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value)) ||
+    Object.keys(value).some(
+      key => !(IDENTITY_FIELDS as readonly string[]).includes(key),
+    )
+  ) {
+    throw new Error('A renderer identity must contain only identity fields.');
+  }
+  const identity = value as RendererIdentity;
+  assertRendererIdentity(identity, expected);
+  return Object.freeze({
+    renderer: identity.renderer,
+    appId: identity.appId,
+    entryName: identity.entryName,
+    protocolVersion: identity.protocolVersion,
+    buildId: identity.buildId,
+  });
+}
+
+/** The emitted client compiler manifest for one native renderer entry. */
+export function nativeModuleManifestFilename(
+  renderer: Renderer,
+  entryName: string,
+): string {
+  if (typeof entryName !== 'string' || !entryName.trim()) {
+    throw new Error(
+      'Native module manifests require an application entry name.',
+    );
+  }
+  return `${resolveRenderer(renderer)}-module-manifest.${encodeURIComponent(entryName)}.json`;
+}
+
+/** Response header naming the built entry identity that rendered a document. */
+export const RENDERER_IDENTITY_HEADER = 'x-ultramodern-renderer-identity';
+
+/**
+ * Serialize an entry identity as an ASCII-only header value (JSON with
+ * non-ASCII code units escaped), so every host emits the same bytes.
+ */
+export function serializeRendererIdentityHeader(
+  identity: RendererIdentity,
+): string {
+  identityCacheKey(identity);
+  return JSON.stringify({
+    renderer: identity.renderer,
+    appId: identity.appId,
+    entryName: identity.entryName,
+    protocolVersion: identity.protocolVersion,
+    buildId: identity.buildId,
+  }).replace(/[\u007f-\u{10ffff}]/gu, character =>
+    Array.from(
+      { length: character.length },
+      (_, index) =>
+        `\\u${character.charCodeAt(index).toString(16).padStart(4, '0')}`,
+    ).join(''),
+  );
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export {
+  assertRendererIdentity,
+  identityCacheKey,
+  type Renderer,
+  type RendererIdentity,
+  resolveRenderer,
+} from './identity';