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

package/src/entry-client.ts

@@ -0,0 +1,90 @@
+import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions/paths';
+import {
+  type NativeClientEntryOptions,
+  type NativeI18nInstance,
+  startNativeClientEntry,
+} from '@modern-js/renderer-core/entry-client';
+import { createNativeRouter } from '@modern-js/renderer-core/router';
+import type { ComponentBody } from 'octane';
+import {
+  hydrateOctaneApplication,
+  mountOctaneApplication,
+  type OctaneApplicationModule,
+  readOctaneDocumentBootstrap,
+} from './client';
+import {
+  componentView,
+  localizedRouterRoot,
+  octaneRouterFactory,
+} from './entry-application';
+import {
+  OctaneRouterRoot,
+  prepareOctaneRouterHydration,
+} from './router-client';
+import type {
+  OctaneWorkerFederationFactory,
+  OctaneWorkerFederationScope,
+} from './worker-federation-context';
+
+export interface OctaneClientEntryOptions
+  extends NativeClientEntryOptions<NativeI18nInstance, LocalisedUrlsOption> {
+  /** The native client compilation hash, `__webpack_hash__`. */
+  readonly nativeHydrationBuildId: string;
+  readonly workerFederation?:
+    | OctaneWorkerFederationScope
+    | OctaneWorkerFederationFactory;
+}
+
+const LocalizedRouterRoot = localizedRouterRoot(OctaneRouterRoot);
+
+/** Start a generated Octane browser entry: mount, or hydrate the server document. */
+export function startNativeClient(options: OctaneClientEntryOptions): void {
+  const { nativeHydrationBuildId } = options;
+  startNativeClientEntry(options, {
+    readBootstrap: (document, identity) =>
+      readOctaneDocumentBootstrap(document, identity, nativeHydrationBuildId),
+    createRouter: (application, routerOptions) =>
+      createNativeRouter(application, routerOptions, octaneRouterFactory),
+    disposeRouter: router => router.history.destroy(),
+    async prepareRouter(router, hydrating, signal) {
+      // Hydration adopts the server's matches; a fresh mount loads its own.
+      if (hydrating) await prepareOctaneRouterHydration(router, { signal });
+      else await router.load();
+    },
+    async start({ root, identity, bootstrap, signal, load }) {
+      const application = {
+        container: root,
+        identity,
+        nativeHydrationBuildId,
+        federation: options.federation,
+        workerFederation: options.workerFederation,
+        documentId: bootstrap?.documentId,
+        signal,
+        // Hydration installs the native signal bridge before this importer runs.
+        load: async (): Promise<OctaneApplicationModule> => {
+          const view = await load();
+          if (view.kind === 'component')
+            return { default: componentView(view.component, view.i18n) };
+          return view.i18n
+            ? {
+                default: LocalizedRouterRoot as ComponentBody,
+                props: { router: view.router, i18n: view.i18n },
+              }
+            : {
+                default: OctaneRouterRoot as ComponentBody,
+                props: { router: view.router },
+              };
+        },
+      };
+      const handle = bootstrap?.hydrating
+        ? await hydrateOctaneApplication({
+            ...application,
+            documentIdentity: bootstrap.identity,
+            documentId: bootstrap.documentId,
+            documentNativeHydrationBuildId: bootstrap.nativeHydrationBuildId,
+          })
+        : await mountOctaneApplication(application);
+      return () => handle.dispose();
+    },
+  });
+}

package/src/entry-server.ts

@@ -0,0 +1,153 @@
+import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions/paths';
+import {
+  collectDataHeaders,
+  dataMetadataToDocumentPolicy,
+  mergeDataResponseIntoResponse,
+  mergeDataResponseMetadata,
+  mergeHeaderFields,
+} from '@modern-js/renderer-core/data';
+import {
+  createNativeServerEntry as createServerEntry,
+  type NativeI18nInstance,
+  type NativeServerEntry,
+  type NativeServerEntryOptions,
+} from '@modern-js/renderer-core/entry-server';
+import { createNativeRouter } from '@modern-js/renderer-core/router';
+import type { ResponsePolicy } from '@modern-js/renderer-core/session';
+import type { ServerRenderNode } from 'octane/server';
+import {
+  componentView,
+  localizedRouterRoot,
+  octaneRouterFactory,
+} from './entry-application';
+import { validateOctaneModuleManifest } from './manifest';
+import {
+  createOctaneRequestHandler,
+  createSsrStreamResponse,
+  getSsrStatus,
+  OctaneRouterServer,
+} from './router-server';
+import { renderOctaneApplication, renderOctaneCSRDocument } from './server';
+
+/** Document-describing fields an Octane route's `headers()` may set. */
+const OCTANE_DOCUMENT_FIELDS = new Set([
+  'content-language',
+  'content-location',
+  'content-disposition',
+]);
+
+/**
+ * The loader projection strips representation fields; the ones an Octane route
+ * declares for the document itself are kept, as Solid document headers are.
+ */
+export function withOctaneDocumentFields(
+  policy: ResponsePolicy,
+  responseHeaders: Headers,
+): ResponsePolicy {
+  const fields = collectDataHeaders(responseHeaders).filter(([name]) =>
+    OCTANE_DOCUMENT_FIELDS.has(name.toLowerCase()),
+  );
+  return fields.length
+    ? { ...policy, headers: [...policy.headers, ...fields] }
+    : policy;
+}
+
+export { createNativeWorkerFederationRuntime } from './worker-federation';
+
+export interface OctaneServerEntryOptions
+  extends NativeServerEntryOptions<NativeI18nInstance, LocalisedUrlsOption> {
+  readonly workerFederationLocale?: string;
+}
+
+const LocalizedRouterServer = localizedRouterRoot(OctaneRouterServer);
+
+/** The native transport handlers of a generated Octane server entry. */
+export function createNativeServerEntry(
+  options: OctaneServerEntryOptions,
+): NativeServerEntry {
+  return createServerEntry(options, {
+    document: (document, nativeManifest, identity) => ({
+      ...document,
+      nativeHydrationBuildId: validateOctaneModuleManifest(
+        nativeManifest,
+        identity,
+      ).nativeHydrationBuildId,
+    }),
+    run: (_session, callback) => callback(),
+    respond: (_session, response) => response,
+    createRouter: (application, routerOptions) =>
+      createNativeRouter(application, routerOptions, octaneRouterFactory),
+    renderCSR: ({ session }, document) =>
+      renderOctaneCSRDocument({ session, document }),
+    renderComponent: (
+      { session, workerFederation },
+      component,
+      document,
+      i18n,
+    ) =>
+      renderOctaneApplication({
+        session,
+        App: componentView(component, i18n) as ServerRenderNode,
+        document,
+        federation: options.federation,
+        workerFederation,
+        workerFederationLocale: options.workerFederationLocale,
+      }),
+    async renderRoutes({
+      request,
+      context: { session, workerFederation },
+      router,
+      outcomes,
+      document,
+      forbiddenValues,
+      i18n,
+    }) {
+      const response = await createOctaneRequestHandler({
+        request,
+        session,
+        createRouter: () => router,
+        serialization: { forbiddenValues },
+      })(async ({ router, responseHeaders }) => {
+        const metadata = mergeDataResponseMetadata(outcomes, {
+          status: getSsrStatus(router),
+        });
+        // Route headers() take precedence over loader singleton fields; list
+        // fields keep both.
+        const policy = dataMetadataToDocumentPolicy({
+          ...metadata,
+          headers: mergeHeaderFields(
+            collectDataHeaders(responseHeaders),
+            metadata.headers,
+          ),
+        });
+        session.resolveResponse(
+          withOctaneDocumentFields(policy, responseHeaders),
+        );
+        const rendered = await renderOctaneApplication({
+          session,
+          ...(i18n
+            ? {
+                App: LocalizedRouterServer as ServerRenderNode,
+                props: { router, i18n },
+              }
+            : {
+                App: OctaneRouterServer as ServerRenderNode,
+                props: { router },
+              }),
+          document,
+          federation: options.federation,
+          workerFederation,
+          workerFederationLocale: options.workerFederationLocale,
+          router,
+        });
+        return createSsrStreamResponse(router, rendered);
+      });
+      return session.committedPolicy
+        ? response
+        : mergeDataResponseIntoResponse(
+            response,
+            mergeDataResponseMetadata(outcomes, { status: response.status }),
+          );
+    },
+  });
+}

package/src/federation-context.ts

@@ -0,0 +1,53 @@
+import {
+  type FederationInstance,
+  getFederationHost,
+  type NativeFederationBinding,
+} from '@modern-js/renderer-core/federation';
+import { type ComponentBody, createContext, createElement } from 'octane';
+
+/** One application owns its host runtime; each response owns its render scope. */
+export interface OctaneFederationScope {
+  readonly instance: FederationInstance | undefined;
+  readonly server: boolean;
+  readonly nonce?: string;
+}
+
+export const FederationContext = createContext<OctaneFederationScope | null>(
+  null,
+);
+
+export function createFederationScope(
+  binding: NativeFederationBinding | undefined,
+  server: boolean,
+  nonce?: string,
+): OctaneFederationScope {
+  return {
+    instance: getFederationHost(binding),
+    server,
+    ...(nonce === undefined ? {} : { nonce }),
+  };
+}
+
+export function FederationRoot(props: {
+  readonly scope: OctaneFederationScope;
+  readonly children?: unknown;
+}) {
+  return createElement(FederationContext, {
+    value: props.scope,
+    children: props.children,
+  });
+}
+
+/** A stable root component retains native state when its application updates. */
+export function FederationApplication(props: {
+  readonly scope: OctaneFederationScope;
+  readonly application: {
+    readonly default: ComponentBody;
+    readonly props?: unknown;
+  };
+}) {
+  return createElement(FederationRoot, {
+    scope: props.scope,
+    children: createElement(props.application.default, props.application.props),
+  });
+}

package/src/federation.ts

@@ -0,0 +1,307 @@
+import { loadFederatedModule } from '@modern-js/renderer-core/federation';
+import {
+  type ComponentBody,
+  createElement,
+  decodeExternalSnapshot,
+  externalSnapshotBoundary,
+  hookSlots,
+  lazy,
+  type OctaneNode,
+  preinit,
+  publisherBoundary,
+  Suspense,
+  serializeExternalSnapshotRequest,
+  useContext,
+  useEffect,
+} from 'octane';
+import {
+  FederationContext,
+  type OctaneFederationScope,
+} from './federation-context';
+
+import { I18nContext } from './i18n/context';
+import {
+  type OctaneWorkerFederationScope,
+  WorkerFederationContext,
+} from './worker-federation-context';
+import { useOctaneWorkerContextKeys } from './worker-federation-contexts';
+
+/** The native component shape exposed by a same-renderer Octane remote. */
+export interface FederatedModule<P extends object> {
+  readonly default: ComponentBody<P>;
+}
+
+export interface FederatedComponentOptions {
+  /** Native content shown while loading, or after a failed server load. */
+  readonly fallback?: () => OctaneNode;
+  /** A positive load limit; the server defaults to 3000ms. */
+  readonly timeout?: number;
+  /** Explicit registered server projections required by an application remote. */
+  readonly contextKeys?: readonly string[];
+}
+
+function withTimeout<T>(
+  promise: Promise<T>,
+  timeout: number | undefined,
+  label: string,
+): Promise<T> {
+  if (timeout === undefined) return promise;
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(
+      () =>
+        reject(
+          new Error(`Remote module ${label} did not load within ${timeout}ms`),
+        ),
+      timeout,
+    );
+    (timer as { unref?: () => void }).unref?.();
+    promise.then(
+      value => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      error => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+// This library wrapper is published as plain JavaScript, outside app compilation.
+const publisherRegistrationEffectSlot = Symbol(hookSlots(1));
+
+/**
+ * Render a native Octane remote by its `remote/Expose` id or a browser loader.
+ * Native Suspense owns server fallbacks, streamed styles and hydration adoption;
+ * browser failures reach the nearest native ErrorBoundary. A loader function is
+ * browser-only; use an id to render through the host's server federation runtime.
+ */
+export function federatedComponent<P extends object = Record<string, never>>(
+  remote: string | (() => Promise<FederatedModule<P>>),
+  options: FederatedComponentOptions = {},
+): ComponentBody<P> {
+  if (
+    typeof remote === 'string'
+      ? !/^[^/]+\/.+/u.test(remote)
+      : typeof remote !== 'function'
+  ) {
+    throw new TypeError(
+      "federatedComponent requires a remote id such as 'remote/Widget' or a loader",
+    );
+  }
+  if (
+    options.timeout !== undefined &&
+    (!Number.isFinite(options.timeout) || options.timeout <= 0)
+  ) {
+    throw new TypeError(
+      'federatedComponent timeout must be a positive number of milliseconds',
+    );
+  }
+  const id = typeof remote === 'string' ? remote : undefined;
+  const standalone: OctaneFederationScope = {
+    instance: undefined,
+    server: typeof document === 'undefined',
+  };
+  // Native lazy caches its module. Scope the cache to one application/response,
+  // so two hosts using the same component definition cannot share a remote.
+  const components = new WeakMap<object, ComponentBody<P>>();
+  const workerOwners = new WeakMap<
+    OctaneFederationScope,
+    WeakMap<OctaneWorkerFederationScope, Map<string, object>>
+  >();
+
+  return props => {
+    const context = useContext(FederationContext) ?? standalone;
+    const worker = useContext(WorkerFederationContext);
+    const language = worker
+      ? (useContext(I18nContext)?.language ?? worker.locale)
+      : undefined;
+    const contextKeys = worker
+      ? useOctaneWorkerContextKeys(options.contextKeys)
+      : undefined;
+    let owner: object = context;
+    if (worker) {
+      let scopes = workerOwners.get(context);
+      if (!scopes) workerOwners.set(context, (scopes = new WeakMap()));
+      let variants = scopes.get(worker);
+      if (!variants) scopes.set(worker, (variants = new Map()));
+      // Server snapshots are locale-specific. The hydrated browser publisher
+      // keeps its native owner and receives language changes through context.
+      const key = JSON.stringify([
+        context.server ? language : undefined,
+        contextKeys,
+      ]);
+      let variant = variants.get(key);
+      if (!variant) variants.set(key, (variant = {}));
+      owner = variant;
+    }
+    let Remote = components.get(owner);
+    if (!Remote) {
+      Remote = lazy(async () => {
+        try {
+          if (context.server && !id) {
+            throw new Error(
+              'A federatedComponent loader renders in the browser only; use a remote id to server-render it',
+            );
+          }
+          if (worker) {
+            if (!id || !language) {
+              throw new Error(
+                'Worker federation requires a remote id and the owning entry locale',
+              );
+            }
+            const separator = id.indexOf('/');
+            const remoteName = id.slice(0, separator);
+            const expose = `./${id.slice(separator + 1)}`;
+            const controller = new AbortController();
+            const signal = worker.signal
+              ? AbortSignal.any([worker.signal, controller.signal])
+              : controller.signal;
+            const timeout =
+              options.timeout ?? (context.server ? 3000 : undefined);
+            let admitted;
+            try {
+              admitted = await withTimeout(
+                worker.transport.admit({
+                  remote: remoteName,
+                  expose,
+                  locale: language,
+                  signal,
+                }),
+                timeout,
+                id,
+              );
+            } finally {
+              // Release this admission waiter, including after its own deadline.
+              controller.abort();
+            }
+            const BrowserRemote = lazy(async () => {
+              const { module, assets } = await loadFederatedModule<
+                FederatedModule<P>
+              >(context.instance, id);
+              if (typeof module?.default !== 'function') {
+                throw new TypeError(
+                  'A federated Octane module must default-export a native component',
+                );
+              }
+              const component = module.default;
+              const Loaded: ComponentBody<P> = (props, scope, extra) => {
+                for (const href of assets?.css ?? []) {
+                  preinit(href, {
+                    as: 'style',
+                    precedence: 'federated',
+                    ...(context.nonce === undefined
+                      ? {}
+                      : { nonce: context.nonce }),
+                  });
+                }
+                return component(props, scope, extra);
+              };
+              return { default: Loaded };
+            });
+            const boundary = externalSnapshotBoundary({
+              authority: admitted.coordinate.native,
+              component: BrowserRemote,
+              contextKeys,
+              timeoutMs: timeout,
+              async snapshot(request, signal) {
+                const response = await worker.transport.request({
+                  remote: remoteName,
+                  expose,
+                  locale: language,
+                  payload: serializeExternalSnapshotRequest(request),
+                  signal,
+                });
+                return decodeExternalSnapshot(response.payload);
+              },
+            });
+            const Loaded: ComponentBody<P> = props => {
+              // A Worker server does not execute BrowserRemote. Register the
+              // exact admitted expose's extracted CSS in this active native
+              // render; nested snapshots carry these hints through native head.
+              for (const href of admitted.styles) {
+                preinit(href, {
+                  as: 'style',
+                  precedence: 'federated',
+                  ...(context.nonce === undefined
+                    ? {}
+                    : { nonce: context.nonce }),
+                });
+              }
+              return createElement(boundary, props);
+            };
+            return { default: Loaded };
+          }
+          const { module, assets } = await withTimeout(
+            Promise.resolve().then(() =>
+              id
+                ? loadFederatedModule<FederatedModule<P>>(context.instance, id)
+                : (remote as () => Promise<FederatedModule<P>>)().then(
+                    module => ({ module, assets: undefined }),
+                  ),
+            ),
+            options.timeout ?? (context.server ? 3000 : undefined),
+            id ?? 'loader',
+          );
+          if (typeof module?.default !== 'function') {
+            throw new TypeError(
+              'A federated Octane module must default-export a native component',
+            );
+          }
+          if (context.server && !assets) {
+            throw new Error(
+              `Cannot server-render ${id}: the host has no browser assets for this remote`,
+            );
+          }
+          // Native publisher ownership admits this exact compiled component's
+          // signal generations. Keep the boundary in the context-scoped lazy
+          // cache so props and compatible hot updates retain its live owner.
+          const component = publisherBoundary(module.default, {
+            publisherKey: id ?? 'ultramodern:browser-loader',
+          });
+          const Loaded: ComponentBody<P> = props => {
+            // A development runtime installs this hook on the actual owning
+            // host. Registration follows the native mounted lifetime; routing
+            // alone grants no replacement authority to a remote name.
+            useEffect(
+              () => {
+                if (context.server || !id || !context.instance) return;
+                const register = Reflect.get(
+                  context.instance,
+                  Symbol.for('ultramodern.federation.browser-dev-boundary.v1'),
+                );
+                if (typeof register !== 'function') return;
+                return register(id, module.default, component);
+              },
+              [],
+              publisherRegistrationEffectSlot,
+            );
+            // Resource APIs require an active native render. Late styles travel
+            // in Octane's resource carrier ahead of the remote's HTML segment.
+            for (const href of assets?.css ?? []) {
+              preinit(href, {
+                as: 'style',
+                precedence: 'federated',
+                ...(context.nonce === undefined
+                  ? {}
+                  : { nonce: context.nonce }),
+              });
+            }
+            return createElement(component, props);
+          };
+          return { default: Loaded };
+        } catch (error) {
+          // A later mount or ErrorBoundary reset may retry a failed load.
+          if (!context.server) components.delete(owner);
+          throw error;
+        }
+      });
+      components.set(owner, Remote);
+    }
+    return createElement(Suspense, {
+      fallback: options.fallback,
+      children: createElement(Remote, props),
+    });
+  };
+}

package/src/i18n/I18nProvider.ts

@@ -0,0 +1,47 @@
+import { createElement, hookSlots, useSyncExternalStore } from 'octane';
+import { I18nContext } from './context';
+import type { I18nContextValue } from './types';
+
+export interface I18nProviderProps extends Omit<I18nContextValue, 'language'> {
+  children?: unknown;
+}
+
+/**
+ * Provides a per-request i18next-shaped instance to the Octane tree. The
+ * instance must come from the caller (created with `cloneInstance` per
+ * request on the server, and the same instance reused on hydration) — this
+ * provider holds no module-level state of its own beyond the one reactive
+ * `language` state it derives from `instance` and shares with every
+ * consumer through context, matching `@modern-js/plugin-i18n`'s React
+ * `ModernI18nProvider` shape (one subscription, pushed through context,
+ * rather than every consumer subscribing to `languageChanged` itself).
+ *
+ * No JSX: built with `createElement`, matching this package's existing
+ * style (see `src/routes.ts`), and avoiding any dependency on Octane's
+ * JSX/compiler toolchain for a file that needs none of its features.
+ */
+// Plain TypeScript is not rewritten by the Octane compiler, so each hook call
+// site carries its own stable slot, like `OctaneRouterRoot`.
+const languageStoreSlot = Symbol(hookSlots(1));
+
+export function I18nProvider(props: I18nProviderProps) {
+  const instance = props.instance;
+  const language = useSyncExternalStore(
+    notify => {
+      instance.on?.('languageChanged', notify);
+      return () => instance.off?.('languageChanged', notify);
+    },
+    () => instance.language,
+    () => instance.language,
+    languageStoreSlot,
+  );
+
+  const value: I18nContextValue = {
+    instance: props.instance,
+    languages: props.languages,
+    localisedUrls: props.localisedUrls,
+    language,
+  };
+
+  return createElement(I18nContext, { value, children: props.children });
+}