@bleedingdev/modern-js-renderer-octane 0.0.0-stage → 3.9.3-ultramodern.10

package/src/routes.ts

@@ -0,0 +1,274 @@
+import type {
+  DataOutcome,
+  FileSystemRouteIR,
+  PublicDataOutcome,
+} from '@modern-js/renderer-core/data';
+import {
+  type FileSystemRouteOptions,
+  loadFileSystemRoute,
+  type NativeLoaderMatch,
+  nativeRoutePath,
+  resolveRouteData as resolveNativeRouteData,
+  splitFileSystemRoutes,
+} from '@modern-js/renderer-core/router';
+import {
+  type AnyRoute,
+  type AnyRouteMatch,
+  type AnyRouter,
+  createRootRoute,
+  createRoute,
+  ErrorComponent,
+  type ErrorRouteComponent,
+  HeadContent,
+  type NotFoundRouteComponent,
+  notFound,
+  Outlet,
+  type RouteComponent,
+  redirect,
+  Scripts,
+} from '@octanejs/tanstack-router';
+import { createElement, Fragment } from 'octane';
+
+const fileRouteHeads = new WeakMap<AnyRoute, AnyRoute['options']['head']>();
+
+/** Head callbacks execute on the host; only the factory's original binding is admitted. */
+export function hasUnchangedOctaneFileRouteHead(route: AnyRoute): boolean {
+  return fileRouteHeads.get(route) === route.options.head;
+}
+
+export type {
+  FileSystemDataModule,
+  FileSystemRouteOptions,
+} from '@modern-js/renderer-core/router';
+export {
+  matchApplicationRouteIds,
+  matchApplicationRoutes,
+  RouteDataError,
+  selectApplicationDataRoute,
+} from '@modern-js/renderer-core/router';
+
+/** Generated imports contain native view bindings, keyed by the structural id. */
+export interface FileSystemRouteModule {
+  component?: RouteComponent;
+  pendingComponent?: RouteComponent;
+  errorComponent?: ErrorRouteComponent;
+  notFoundComponent?: NotFoundRouteComponent;
+  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>;
+  head?: AnyRoute['options']['head'];
+}
+
+/** Native route boundaries decide how redirects, missing data and errors render. */
+export function resolveRouteData(
+  routeId: string,
+  outcome: DataOutcome | PublicDataOutcome,
+): unknown {
+  return resolveNativeRouteData({ redirect, notFound }, routeId, outcome);
+}
+
+interface ReactiveNativeMatch {
+  get(): AnyRouteMatch | undefined;
+  subscribe(callback: () => void): { unsubscribe(): void };
+}
+
+function isReactiveNativeMatch(value: unknown): value is ReactiveNativeMatch {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof Reflect.get(value, 'get') === 'function' &&
+    typeof Reflect.get(value, 'subscribe') === 'function'
+  );
+}
+
+/** A transport failure belongs to the native generation that fetched it. */
+function observeRouteCompletion(
+  router: AnyRouter,
+  routeId: string,
+  controller: AbortController,
+  signal: AbortSignal,
+  completion: Promise<void>,
+) {
+  void completion.catch(error => {
+    if (signal.aborted) return;
+    const route = Object.values(router.routesById).find(
+      candidate => candidate.options.staticData?.ultramodernRouteId === routeId,
+    );
+    if (!route) return;
+    const store = router.stores.getMatchStore(route.id);
+    let subscription: { unsubscribe(): void } | undefined;
+    let settled = false;
+    const cleanup = () => {
+      subscription?.unsubscribe();
+      signal.removeEventListener('abort', onAbort);
+    };
+    const onAbort = () => {
+      settled = true;
+      cleanup();
+    };
+    const publish = async () => {
+      if (settled) return;
+      const current = store.get();
+      if (!current) return;
+      if (
+        current.abortController !== controller ||
+        signal.aborted ||
+        (current.status !== 'pending' && current.status !== 'success')
+      ) {
+        onAbort();
+        return;
+      }
+      // The initial loader can still be pending after its critical value returns.
+      if (current.status !== 'success' || current.isFetching) return;
+      settled = true;
+      cleanup();
+      const route = router.routesById[current.routeId];
+      let failure = error;
+      try {
+        await route?.options.errorComponent?.preload?.();
+        if (signal.aborted || store.get()?.abortController !== controller)
+          return;
+        route?.options.onError?.(failure);
+      } catch (onErrorFailure) {
+        failure = onErrorFailure;
+      }
+      // The error component is ready before publishing a late transport failure.
+      if (signal.aborted) return;
+      router.stores.setMatches(
+        router.stores.matches.get().map(previous =>
+          previous.routeId === route.id &&
+          previous.abortController === controller &&
+          previous.status === 'success' &&
+          !previous.isFetching
+            ? {
+                ...previous,
+                error: failure,
+                status: 'error',
+                isFetching: false,
+              }
+            : previous,
+        ),
+      );
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    if (isReactiveNativeMatch(store)) subscription = store.subscribe(publish);
+    if (settled) subscription?.unsubscribe();
+    else publish();
+  });
+}
+
+/** Pass filesystem structure to native factories without matching any URL. */
+export function createFileSystemRouteTree<Context = unknown>(
+  routes: readonly FileSystemRouteIR[],
+  modules: Readonly<Record<string, FileSystemRouteModule>>,
+  options: FileSystemRouteOptions<Context, AnyRouter> = {},
+): AnyRoute {
+  const { root: rootDescriptor, children } = splitFileSystemRoutes(routes);
+
+  function bindings(
+    route: FileSystemRouteIR,
+    errorComponent?: ErrorRouteComponent,
+  ) {
+    const needsData = Boolean(route.modules?.data || route.modules?.clientData);
+    if (needsData && !options.loadRoute) {
+      throw new Error(`An Octane data route requires its loader: ${route.id}`);
+    }
+    const loadRoute = options.loadRoute;
+    const { head, ...module } = modules[route.id] ?? {};
+    return {
+      ...module,
+      ...(head !== undefined ? { head } : {}),
+      // Octane's server renders an uncaught match error through the root
+      // outlet's Suspense, which defers it to a client retry that then
+      // replaces the whole layout. Give every child match the nearest
+      // error.tsx (or the native default) so the error renders in place.
+      ...(errorComponent ? { errorComponent } : {}),
+      component: module.component ?? Outlet,
+      staticData: { ultramodernRouteId: route.id },
+      ...(needsData && loadRoute
+        ? {
+            loader: async (match: NativeLoaderMatch) => {
+              const { outcome, signal } = await loadFileSystemRoute(
+                route,
+                loadRoute,
+                options,
+                match,
+              );
+              if ('completion' in outcome && outcome.completion) {
+                const router = options.getRouter?.();
+                if (!router) {
+                  throw new Error(
+                    'An Octane streamed data route requires its native router',
+                  );
+                }
+                let failed = false;
+                let failure: unknown;
+                void outcome.completion.catch(error => {
+                  failed = true;
+                  failure = error;
+                });
+                // Detect a terminal failure already received with the first frame.
+                await Promise.resolve();
+                signal.throwIfAborted();
+                if (failed) throw failure;
+                observeRouteCompletion(
+                  router,
+                  route.id,
+                  match.abortController,
+                  signal,
+                  outcome.completion,
+                );
+              }
+              options.onOutcome?.(route.id, outcome);
+              return resolveRouteData(route.id, outcome);
+            },
+          }
+        : {}),
+    };
+  }
+
+  const rootBindings = rootDescriptor
+    ? bindings(rootDescriptor)
+    : { component: Outlet };
+  const authoredRoot: RouteComponent = rootBindings.component;
+  function OctaneDocumentRoot(props: Parameters<RouteComponent>[0]) {
+    return createElement(
+      Fragment,
+      null,
+      createElement(HeadContent),
+      createElement(authoredRoot, props),
+      createElement(Scripts),
+    );
+  }
+  if (authoredRoot.preload !== undefined) {
+    OctaneDocumentRoot.preload = authoredRoot.preload;
+  }
+  const rootErrorComponent =
+    (rootDescriptor && modules[rootDescriptor.id]?.errorComponent) ||
+    ErrorComponent;
+  const root = createRootRoute({
+    ...rootBindings,
+    component: OctaneDocumentRoot,
+  });
+  fileRouteHeads.set(root, root.options.head);
+
+  function bind(
+    route: FileSystemRouteIR,
+    parent: AnyRoute,
+    inheritedErrorComponent: ErrorRouteComponent,
+  ): AnyRoute {
+    const errorComponent =
+      modules[route.id]?.errorComponent ?? inheritedErrorComponent;
+    const native = createRoute({
+      getParentRoute: () => parent,
+      ...nativeRoutePath(route),
+      ...bindings(route, errorComponent),
+    });
+    fileRouteHeads.set(native, native.options.head);
+    return native.addChildren(
+      route.children.map(child => bind(child, native, errorComponent)),
+    );
+  }
+
+  return root.addChildren(
+    children.map(route => bind(route, root, rootErrorComponent)),
+  );
+}

package/src/server.ts

@@ -0,0 +1,340 @@
+import {
+  type DocumentAsset,
+  type DocumentInlineData,
+  prepareDocument,
+} from '@modern-js/renderer-core/document';
+import type { NativeFederationBinding } from '@modern-js/renderer-core/federation';
+import {
+  type RequestSession,
+  type ResponsePolicy,
+  untilAborted,
+} from '@modern-js/renderer-core/session';
+import type { WorkerFederationTransport } from '@modern-js/renderer-core/worker-federation';
+import type { AnyRouter } from '@octanejs/tanstack-router';
+import { transformReadableStreamWithRouter } from '@octanejs/tanstack-router/ssr/server';
+import {
+  createElement,
+  earlySignalBootstrapScript,
+  renderToReadableStream,
+  type ServerRenderNode,
+  type StreamOptions,
+} from 'octane/server';
+import {
+  assertNativeHydrationBuildId,
+  assertOctaneIdentity,
+} from './bootstrap';
+import { createFederationScope, FederationRoot } from './federation-context';
+import { WorkerFederationRoot } from './worker-federation-context';
+
+export interface OctaneDocumentOptions {
+  /** One identity for this response, shared with the client's signal receiver. */
+  readonly documentId: string;
+  /** Actual native client compilation hash, separate from application identity. */
+  readonly nativeHydrationBuildId: string;
+  readonly rootId?: string;
+  readonly lang?: string;
+  readonly nonce?: string;
+  readonly assets?: readonly DocumentAsset[];
+  /** Placed after the renderer bootstrap and before the entry scripts. */
+  readonly inlineData?: readonly DocumentInlineData[];
+}
+
+export type { DocumentInlineData as OctaneDocumentInlineData };
+
+export interface OctaneDocumentResponseOptions<
+  Bindings extends object = object,
+> {
+  readonly session: RequestSession<Bindings>;
+  readonly document: OctaneDocumentOptions;
+  readonly responsePolicy?: ResponsePolicy;
+  /** Native route loading finishes its blocking HTTP work before rendering. */
+  readonly resolveResponse?: (
+    session: RequestSession<Bindings>,
+  ) => ResponsePolicy | Promise<ResponsePolicy>;
+}
+
+export interface RenderOctaneApplicationOptions<
+  Bindings extends object = object,
+> extends OctaneDocumentResponseOptions<Bindings> {
+  readonly App: ServerRenderNode;
+  readonly props?: unknown;
+  /** Native router serialization, owned by this request's router SSR context. */
+  readonly injection?: StreamOptions['injection'];
+  readonly router?: AnyRouter;
+  readonly routerSerializationTimeoutMs?: number;
+  /** This server compilation's native Module Federation runtime. */
+  readonly federation?: NativeFederationBinding;
+  readonly workerFederation?: WorkerFederationTransport;
+  readonly workerFederationLocale?: string;
+}
+
+function prepareOctaneDocument<Bindings extends object>(
+  session: RequestSession<Bindings>,
+  document: OctaneDocumentOptions,
+  hydrating: boolean,
+) {
+  assertOctaneIdentity(session.identity);
+  if (session.platform.kind !== 'node' && session.platform.kind !== 'worker') {
+    throw new Error(
+      'An Octane document requires a Node or worker request platform.',
+    );
+  }
+  assertNativeHydrationBuildId(document.nativeHydrationBuildId);
+  const nonce = document.nonce;
+  return prepareDocument(
+    {
+      identity: session.identity,
+      documentId: document.documentId,
+      hydrating,
+      nativeHydrationBuildId: document.nativeHydrationBuildId,
+    },
+    {
+      rootId: document.rootId,
+      lang: document.lang,
+      nonce: { script: nonce, style: nonce },
+      assets: document.assets,
+      inlineData: document.inlineData,
+    },
+  );
+}
+
+async function resolveDocumentResponse<Bindings extends object>(
+  input: OctaneDocumentResponseOptions<Bindings>,
+): Promise<void> {
+  const { session } = input;
+  if (input.responsePolicy && input.resolveResponse) {
+    throw new Error('Choose one blocking Octane response policy resolver.');
+  }
+  if (input.resolveResponse) {
+    // A resolver that ignores cancellation must not hold the request.
+    session.resolveResponse(
+      await untilAborted(input.resolveResponse(session), session.signal),
+    );
+  } else if (input.responsePolicy) {
+    session.resolveResponse(input.responsePolicy);
+  } else if (!session.responsePolicy) {
+    session.resolveResponse({
+      kind: 'document',
+      status: 200,
+      headers: [['content-type', 'text/html; charset=utf-8']],
+      cache: { mode: 'no-store' },
+    });
+  }
+}
+
+/** Deliver the CSR document; native browser mounting owns the empty root. */
+export async function renderOctaneCSRDocument<Bindings extends object>(
+  input: OctaneDocumentResponseOptions<Bindings>,
+): Promise<Response> {
+  const { session } = input;
+  try {
+    const { rootId, lang, bootstrap, headAssets, entryScripts } =
+      prepareOctaneDocument(session, input.document, false);
+    await resolveDocumentResponse(input);
+    if (session.responsePolicy?.kind === 'terminal')
+      return session.respond(null);
+    session.startRendering();
+    const bytes = new TextEncoder().encode(
+      `<!doctype html><html lang="${lang}"><head>${headAssets}</head><body><div id="${rootId}"></div>${bootstrap}${entryScripts}</body></html>`,
+    );
+    return session.respond(
+      new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(bytes);
+          controller.close();
+        },
+      }),
+    );
+  } catch (error) {
+    await session.fail(error);
+    throw error;
+  }
+}
+
+/**
+ * Render a native Octane application into one request-owned HTML document.
+ * The dispatcher owns the session; this adapter owns native stream consumption
+ * and document placement. A late native error fails the body without changing
+ * the status and headers already sent to the client.
+ */
+export async function renderOctaneApplication<Bindings extends object>(
+  input: RenderOctaneApplicationOptions<Bindings>,
+): Promise<Response> {
+  const { session, document } = input;
+  try {
+    const { rootId, lang, bootstrap, headAssets, entryScripts } =
+      prepareOctaneDocument(session, document, true);
+    const earlyBootstrap = earlySignalBootstrapScript(
+      document.nonce === undefined ? {} : { nonce: document.nonce },
+    );
+
+    await resolveDocumentResponse(input);
+    if (session.responsePolicy?.kind === 'terminal')
+      return session.respond(null);
+    session.startRendering();
+
+    let head = '';
+    // Worker SSR and browser activation must own the same provider ranges,
+    // even when only the browser needs a Module Federation loader.
+    const federation =
+      input.federation || input.workerFederation
+        ? createFederationScope(input.federation, true, document.nonce)
+        : undefined;
+    const App = federation
+      ? () =>
+          createElement(FederationRoot, {
+            scope: federation,
+            children:
+              typeof input.App === 'function'
+                ? createElement(input.App, input.props)
+                : input.App,
+          })
+      : input.App;
+    // Native SSR retries the application while lazy boundaries settle. Keep
+    // their request-owned context identity stable across those render passes.
+    const workerFederation = input.workerFederation
+      ? {
+          transport: input.workerFederation,
+          locale: input.workerFederationLocale ?? 'default',
+          signal: session.signal,
+        }
+      : undefined;
+    const NativeApp = workerFederation
+      ? () =>
+          createElement(WorkerFederationRoot, {
+            scope: workerFederation,
+            children:
+              typeof App === 'function' ? createElement(App, input.props) : App,
+          })
+      : App;
+    const nativeStream = await renderToReadableStream(NativeApp, input.props, {
+      signal: session.signal,
+      ...(document.nonce === undefined ? {} : { nonce: document.nonce }),
+      earlySignalBootstrap: 'external',
+      ...(input.injection === undefined ? {} : { injection: input.injection }),
+      streamedSignals: {
+        buildId: document.nativeHydrationBuildId,
+        documentId: document.documentId,
+      },
+      externalSnapshots: { documentId: document.documentId },
+      headChannel: 'separate',
+      onHeadReady(value) {
+        head = value;
+      },
+      onError(error) {
+        // Octane reports recoverable Suspense-boundary errors here as well as
+        // fatal ones. A recoverable error streams the boundary's client
+        // fallback into an otherwise valid document, so it must not terminate
+        // the request. Fatal errors reject the shell or allReady instead.
+        if (session.signal.aborted) return;
+        // A document carrying an errored boundary must not enter a shared cache.
+        session.markFallback();
+        console.error('Octane render error:', error);
+      },
+    });
+    // Observe rejection immediately, but consume concurrently: native allReady
+    // requires downstream demand and cannot be awaited before reading the body.
+    const ready = nativeStream.allReady.then(
+      () => ({ ok: true as const }),
+      error => ({ ok: false as const, error }),
+    );
+    const reader = nativeStream.getReader();
+    const encoder = new TextEncoder();
+    const prefix = encoder.encode(
+      `<!doctype html><html lang="${lang}"><head>${head}${headAssets}</head><body>${earlyBootstrap}<div id="${rootId}">`,
+    );
+    const shellBootstrap = encoder.encode(`</div>${bootstrap}${entryScripts}`);
+    const suffix = encoder.encode('</body></html>');
+    let phase: 'prefix' | 'shell' | 'bootstrap' | 'native' | 'done' = 'prefix';
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      reader.releaseLock();
+    };
+    let cancellation: Promise<void> | undefined;
+    const cancelNative = (reason: unknown): Promise<void> => {
+      if (cancellation) return cancellation;
+      if (released) return Promise.resolve();
+      cancellation = reader.cancel(reason).finally(release);
+      return cancellation;
+    };
+    // Cleanup starts native cancellation without waiting for it: a native
+    // stream that never finishes cancelling must not hold the session.
+    const releaseNative = (reason: unknown) => {
+      void cancelNative(reason).catch(() => {});
+    };
+    try {
+      session.registerCleanup(() => releaseNative(session.signal.reason));
+    } catch (error) {
+      // The request can abort between native shell readiness and registration.
+      releaseNative(error);
+      throw error;
+    }
+    const body = new ReadableStream<Uint8Array>(
+      {
+        async pull(controller) {
+          try {
+            if (phase === 'prefix') {
+              phase = 'shell';
+              controller.enqueue(prefix);
+              return;
+            }
+            if (phase === 'bootstrap') {
+              phase = 'native';
+              controller.enqueue(shellBootstrap);
+              return;
+            }
+            const next = await reader.read();
+            if (!next.done) {
+              // Octane 0.7.1 writes its complete initial shell as the first
+              // chunk, including initial signal selections. Close only our
+              // root after it, then start the browser before deferred segments.
+              // Later native carriers find their targets in the whole document.
+              if (phase === 'shell') phase = 'bootstrap';
+              controller.enqueue(next.value);
+              return;
+            }
+            if (phase === 'shell') {
+              throw new Error(
+                'Octane ended before publishing its initial shell.',
+              );
+            }
+            const completion = await ready;
+            release();
+            if (!completion.ok) throw completion.error;
+            phase = 'done';
+            controller.enqueue(suffix);
+            controller.close();
+          } catch (error) {
+            phase = 'done';
+            // An errored ReadableStream does not invoke its cancel callback.
+            // Release the native owner here as well as on consumer cancellation.
+            releaseNative(error);
+            controller.error(error);
+          }
+        },
+        cancel(reason) {
+          phase = 'done';
+          releaseNative(reason);
+        },
+      },
+      { highWaterMark: 0 },
+    );
+    return session.respond(
+      input.router
+        ? transformReadableStreamWithRouter(input.router, body, {
+            signal: session.signal,
+            rendererSafePoint: 'script-close',
+            timeoutMs: input.routerSerializationTimeoutMs,
+            onAbort: reason => {
+              void session.fail(reason);
+            },
+          })
+        : body,
+    );
+  } catch (error) {
+    await session.fail(error);
+    throw error;
+  }
+}