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

package/src/plugin/profile.ts

@@ -0,0 +1,46 @@
+import type { RendererBuildProfile } from '@modern-js/renderer-core/adapter';
+
+export const octaneProfile: RendererBuildProfile<'octane'> = {
+  renderer: 'octane',
+  status: 'preview',
+  protocolVersion: 1,
+  minimumNode: '26.10.0',
+  hmr: {
+    editedBoundary: 'may-reset',
+    unaffectedComponents: 'preserved',
+    document: 'preserved',
+    roots: 'single',
+    cleanup: 'exactly-once',
+  },
+  compiler: { name: '@octanejs/rspack-plugin', version: '0.1.55' },
+  hydration: {
+    name: 'octane',
+    version: '0.7.1+ultramodern.1331985ea3b0',
+  },
+  router: {
+    name: '@octanejs/tanstack-router',
+    version: '0.1.60+ultramodern.0b9f76ee3003',
+    coreName: '@tanstack/router-core',
+    coreVersion: '1.171.15',
+  },
+  sourceExtensions: ['.tsx', '.tsrx', '.ts', '.js'],
+  jsxImportSource: 'octane',
+  dependencies: {
+    octane:
+      'https://github.com/bleedingdev/octane/releases/download/octane%400.7.1%2Bultramodern.1331985ea3b0/octane-0.7.1%2Bultramodern.1331985ea3b0.tgz',
+    '@octanejs/tanstack-router':
+      'https://github.com/bleedingdev/octane/releases/download/%40octanejs%2Ftanstack-router%400.1.60%2Bultramodern.0b9f76ee3003/octanejs-tanstack-router-0.1.60%2Bultramodern.0b9f76ee3003.tgz',
+    '@octanejs/rspack-plugin': '0.1.55',
+    '@modern-js/renderer-octane': '3.8.3',
+    seroval: '1.6.8',
+    'seroval-plugins': '1.6.8',
+  },
+  capabilities: {
+    worker: true,
+    moduleFederation: true,
+    rsc: false,
+    ssg: true,
+    i18n: true,
+    svgComponent: true,
+  },
+};

package/src/plugin/source.ts

@@ -0,0 +1,16 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { octaneProfile } from './profile';
+
+export async function assertOctaneEntrySource(
+  source: string | false | undefined,
+): Promise<void> {
+  if (
+    source &&
+    path.extname(source).toLowerCase() === '.jsx' &&
+    (await fs.stat(source)).isFile()
+  )
+    throw new Error(
+      `unsupported-renderer-capability: Octane does not support .jsx source: ${source}. Supported source extensions: ${octaneProfile.sourceExtensions.join(', ')}.`,
+    );
+}

package/src/plugin/svg-component-template.cjs

@@ -0,0 +1,17 @@
+// Octane follows React host semantics: refs are props and inner markup is
+// trusted HTML. Native attribute names and `class` pass through unchanged.
+module.exports = ({
+  attributes,
+  markup,
+  origin,
+}) => `/** @jsxImportSource octane */
+// Generated by UltraModern from ${origin}. Do not edit.
+import { trustHTML } from 'octane';
+
+const attributes: { readonly [name: string]: string } = ${attributes};
+const markup = trustHTML(${markup});
+
+export default function SvgComponent(props: { readonly [name: string]: unknown }) {
+  return <svg {...attributes} {...props} dangerouslySetInnerHTML={markup} />;
+}
+`;

package/src/router-client.ts

@@ -0,0 +1,144 @@
+import { type AnyRouter, RouterProvider } from '@octanejs/tanstack-router';
+import { hydrate } from '@octanejs/tanstack-router/ssr/client';
+import {
+  createElement,
+  hookSlots,
+  initializeHydrationEventCapture,
+  useEffect,
+} from 'octane';
+import { octaneRouterSnapshotAdapter } from './router-snapshot';
+
+export interface OctaneRouterHydrationOptions {
+  signal?: AbortSignal;
+}
+
+const hydration = new WeakMap<AnyRouter, Promise<void>>();
+
+function abortReason(signal: AbortSignal): unknown {
+  return signal.reason === undefined
+    ? new DOMException('Octane router hydration aborted', 'AbortError')
+    : signal.reason;
+}
+
+function awaitHydration(
+  promise: Promise<void>,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (!signal) return promise;
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (success: boolean, error?: unknown) => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener('abort', onAbort);
+      if (success) resolve();
+      else reject(error);
+    };
+    const onAbort = () => finish(false, abortReason(signal));
+    signal.addEventListener('abort', onAbort, { once: true });
+    promise.then(
+      () => finish(true),
+      error => finish(false, error),
+    );
+    if (signal.aborted) onAbort();
+  });
+}
+
+interface ReactiveMatchIds {
+  get(): readonly string[];
+  subscribe(callback: () => void): { unsubscribe(): void };
+}
+
+function isReactiveMatchIds(value: unknown): value is ReactiveMatchIds {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof Reflect.get(value, 'get') === 'function' &&
+    typeof Reflect.get(value, 'subscribe') === 'function'
+  );
+}
+
+function waitForCommittedMatches(
+  router: AnyRouter,
+  signal?: AbortSignal,
+): Promise<void> {
+  signal?.throwIfAborted();
+  const matchesId = router.stores.matchesId;
+  if (matchesId.get().length > 0) return Promise.resolve();
+  if (!isReactiveMatchIds(matchesId)) {
+    throw new Error(
+      'Octane router hydration requires its native reactive match store',
+    );
+  }
+  return new Promise((resolve, reject) => {
+    let subscription: ReturnType<typeof matchesId.subscribe> | undefined;
+    let settled = false;
+    const cleanup = () => {
+      subscription?.unsubscribe();
+      signal?.removeEventListener('abort', onAbort);
+    };
+    const finish = () => {
+      if (settled || matchesId.get().length === 0) return;
+      settled = true;
+      cleanup();
+      resolve();
+    };
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (signal) reject(abortReason(signal));
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    subscription = matchesId.subscribe(finish);
+    // Native stores can notify synchronously while a subscription is installed.
+    if (settled) subscription.unsubscribe();
+    else finish();
+  });
+}
+
+/** Restore native SSR matches before Octane adopts the server's route ranges. */
+export async function prepareOctaneRouterHydration(
+  router: AnyRouter,
+  options: OctaneRouterHydrationOptions = {},
+): Promise<void> {
+  initializeHydrationEventCapture();
+  options.signal?.throwIfAborted();
+  const adapters = router.options.serializationAdapters ?? [];
+  if (!adapters.includes(octaneRouterSnapshotAdapter)) {
+    const nativeOptions = {
+      ...router.options,
+      serializationAdapters: [octaneRouterSnapshotAdapter, ...adapters],
+    };
+    router.update(nativeOptions);
+  }
+  let pending = hydration.get(router);
+  if (!pending) {
+    pending = Promise.resolve(hydrate(router)).then(() => {});
+    // Native hydration can finish after this startup owner has been cancelled.
+    void pending.catch(() => {});
+    hydration.set(router, pending);
+  }
+  await awaitHydration(pending, options.signal);
+  await waitForCommittedMatches(router, options.signal);
+  options.signal?.throwIfAborted();
+}
+
+const routerHydrationEffectSlot = Symbol(hookSlots(1));
+
+/** Adopt the native provider's ranges inside the admitted fragment host. */
+export function OctaneRouterRoot({ router }: { router: AnyRouter }) {
+  useEffect(
+    () => {
+      window.$_TSR?.h();
+    },
+    [],
+    routerHydrationEffectSlot,
+  );
+  return createElement(RouterProvider, { router });
+}

package/src/router-handler.ts

@@ -0,0 +1,182 @@
+import type { RequestSession } from '@modern-js/renderer-core/session';
+import { type AnyRouter, createMemoryHistory } from '@octanejs/tanstack-router';
+import {
+  attachRouterServerSsrUtils,
+  getNormalizedURL,
+  getOrigin,
+  normalizeSsrResponse,
+  type RequestHandler,
+} from '@octanejs/tanstack-router/ssr/server';
+import { cleanupOctaneRouterSSR } from './router-server-cleanup';
+import {
+  type OctaneRouterSerializationOptions,
+  prepareOctaneRouterSerialization,
+} from './router-server-snapshot';
+
+export interface OctaneRequestHandlerOptions<TRouter extends AnyRouter> {
+  createRouter(): TRouter;
+  request: Request;
+  session: RequestSession;
+  getRouterManifest?: () =>
+    | Parameters<typeof attachRouterServerSsrUtils>[0]['manifest']
+    | Promise<Parameters<typeof attachRouterServerSsrUtils>[0]['manifest']>;
+  serialization?: OctaneRouterSerializationOptions;
+}
+
+function withAbort<T>(pending: Promise<T>, signal: AbortSignal): Promise<T> {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (success: boolean, value: unknown) => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener('abort', onAbort);
+      if (success) resolve(value as T);
+      else reject(value);
+    };
+    const onAbort = () => finish(false, signal.reason);
+    signal.addEventListener('abort', onAbort, { once: true });
+    pending.then(
+      value => finish(true, value),
+      error => finish(false, error),
+    );
+    if (signal.aborted) onAbort();
+  });
+}
+
+/** List fields that nested matches add to: CSP policies, links and timing. */
+const CSP_HEADERS = new Set([
+  'content-security-policy',
+  'content-security-policy-report-only',
+  'link',
+  'server-timing',
+]);
+
+/**
+ * Match headers are server HTTP policy, never part of the public router
+ * snapshot. Nested matches union `Vary` and append CSP fields; other
+ * singleton fields stay last-writer-wins.
+ */
+function appendHeaders(destination: Headers, value: unknown): void {
+  if (value == null) return;
+  const source =
+    value instanceof Headers ? value : new Headers(value as HeadersInit);
+  for (const [key, item] of Headers.prototype.entries.call(source)) {
+    if (key === 'set-cookie') continue;
+    if (CSP_HEADERS.has(key)) destination.append(key, item);
+    else if (key === 'vary') {
+      const fields = new Map<string, string>();
+      for (const field of `${destination.get('vary') ?? ''},${item}`.split(
+        ',',
+      )) {
+        const name = field.trim();
+        if (name && !fields.has(name.toLowerCase()))
+          fields.set(name.toLowerCase(), name);
+      }
+      destination.set('vary', [...fields.values()].join(', '));
+    } else destination.set(key, item);
+  }
+  for (const cookie of Headers.prototype.getSetCookie.call(source)) {
+    destination.append('set-cookie', cookie);
+  }
+}
+
+function requestHeaders(router: AnyRouter): Headers {
+  const headers = new Headers({ 'content-type': 'text/html; charset=utf-8' });
+  for (const match of router.stores.matches.get()) {
+    const field = Object.getOwnPropertyDescriptor(match, 'headers');
+    if (field?.get || field?.set)
+      throw new TypeError(
+        'Native Octane response headers must be owned values',
+      );
+    appendHeaders(headers, field?.value);
+  }
+  const redirect = router.stores.redirect.get();
+  if (redirect) appendHeaders(headers, redirect.headers);
+  return headers;
+}
+
+/** Resolve native routes and HTTP disposition before the native document serializer. */
+export function createOctaneRequestHandler<TRouter extends AnyRouter>({
+  createRouter,
+  request,
+  session,
+  getRouterManifest,
+  serialization,
+}: OctaneRequestHandlerOptions<TRouter>): RequestHandler<TRouter> {
+  return async callback => {
+    session.signal.throwIfAborted();
+    const router = createRouter();
+    let responseOwnsCleanup = false;
+    try {
+      const manifest = getRouterManifest
+        ? await withAbort(Promise.resolve(getRouterManifest()), session.signal)
+        : undefined;
+      attachRouterServerSsrUtils({ router, manifest });
+      const guard = prepareOctaneRouterSerialization(router, session, {
+        ...serialization,
+        forbiddenValues: [request, ...(serialization?.forbiddenValues ?? [])],
+      });
+      session.registerCleanup(() => router.cancelMatches());
+
+      const { url } = getNormalizedURL(request.url, 'http://localhost');
+      const href = url.href.replace(url.origin, '');
+      router.update({
+        ...router.options,
+        history: createMemoryHistory({ initialEntries: [href] }),
+        origin: router.options.origin ?? getOrigin(request),
+      });
+      await withAbort(router.load(), session.signal);
+      guard.assertActive();
+
+      // A native redirect is a terminal HTTP Response. It must never enter
+      // the public serializer as a match error or document payload.
+      const redirect = router.stores.redirect.get();
+      if (redirect) {
+        const resolved = router.resolveRedirect(redirect);
+        const headers = requestHeaders(router);
+        return new Response(null, {
+          status: resolved.status,
+          statusText: resolved.statusText,
+          headers,
+        });
+      }
+
+      guard.assertMatches();
+      const serverSsr = router.serverSsr;
+      if (!serverSsr)
+        throw new Error('Native Octane router SSR state is required');
+      await withAbort(serverSsr.dehydrate(), session.signal);
+      guard.assertActive();
+      const responseHeaders = requestHeaders(router);
+      // A callback that ignores cancellation must not hold the router SSR
+      // state; a result arriving after abort only has its body released.
+      const rendered = Promise.resolve(
+        callback({ request, router, responseHeaders }),
+      );
+      const result = normalizeSsrResponse(
+        await withAbort(rendered, session.signal).catch(error => {
+          if (session.signal.aborted)
+            void rendered.then(
+              late => {
+                try {
+                  void normalizeSsrResponse(late)
+                    .response.body?.cancel()
+                    .catch(() => {});
+                } catch {}
+              },
+              () => {},
+            );
+          throw error;
+        }),
+      );
+      responseOwnsCleanup = result.serverSsrCleanup === 'stream';
+      return result.response;
+    } catch (error) {
+      session.fail(error);
+      throw error;
+    } finally {
+      if (!responseOwnsCleanup) cleanupOctaneRouterSSR(router);
+    }
+  };
+}

package/src/router-injection.ts

@@ -0,0 +1,145 @@
+import type { RequestSession } from '@modern-js/renderer-core/session';
+import type { AnyRouter } from '@octanejs/tanstack-router';
+import type { StreamInjectionSource } from 'octane/server';
+import { cleanupOctaneRouterSSR } from './router-server-cleanup';
+
+const SERIALIZATION_TIMEOUT_MS = 60_000;
+
+export interface OctaneRouterInjectionOptions {
+  serializationTimeoutMs?: number;
+}
+
+/** Couple native router serialization to the response's single stream owner. */
+export function createOctaneRouterInjection(
+  router: AnyRouter,
+  session: RequestSession,
+  options: OctaneRouterInjectionOptions = {},
+): StreamInjectionSource {
+  const serverSsr = router.serverSsr;
+  if (!serverSsr) {
+    throw new Error('Native Octane router.serverSsr is required for streaming');
+  }
+  const timeoutMs = options.serializationTimeoutMs ?? SERIALIZATION_TIMEOUT_MS;
+  if (
+    !Number.isInteger(timeoutMs) ||
+    timeoutMs <= 0 ||
+    timeoutMs > SERIALIZATION_TIMEOUT_MS
+  ) {
+    throw new TypeError(
+      'Octane router serialization timeout must be 1 to 60000 ms',
+    );
+  }
+  session.signal.throwIfAborted();
+  let settled = false;
+  let released = false;
+  let renderFinished = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let stopSerialization: (() => void) | undefined;
+  const subscriptions = new Set<() => void>();
+  let resolveDone!: () => void;
+  let rejectDone!: (error: unknown) => void;
+  const done = new Promise<void>((resolve, reject) => {
+    resolveDone = resolve;
+    rejectDone = reject;
+  });
+  // The caller may fail before attaching the injection to its native renderer.
+  void done.catch(() => {});
+
+  const settle = (error?: unknown) => {
+    if (settled) return;
+    settled = true;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+    stopSerialization?.();
+    stopSerialization = undefined;
+    if (error === undefined) resolveDone();
+    else rejectDone(error);
+  };
+  const release = () => {
+    if (released) return;
+    released = true;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+    stopSerialization?.();
+    stopSerialization = undefined;
+    for (const unsubscribe of subscriptions) unsubscribe();
+    subscriptions.clear();
+    session.signal.removeEventListener('abort', onAbort);
+    if (!settled) {
+      settle(
+        session.signal.reason ??
+          new Error('Octane router serialization was interrupted'),
+      );
+    }
+  };
+  function onAbort() {
+    settle(
+      session.signal.reason ??
+        new DOMException('Octane request aborted', 'AbortError'),
+    );
+    release();
+  }
+
+  if (serverSsr.isSerializationFinished()) settle();
+  else stopSerialization = serverSsr.onSerializationFinished(() => settle());
+  serverSsr.onCleanup(release);
+  session.signal.addEventListener('abort', onAbort, { once: true });
+  try {
+    session.registerCleanup(() => {
+      release();
+      cleanupOctaneRouterSSR(router);
+    });
+  } catch (error) {
+    release();
+    cleanupOctaneRouterSSR(router);
+    throw error;
+  }
+
+  return {
+    take() {
+      if (released) return '';
+      // Octane takes injected HTML only once the shell is rendered, so the
+      // router's Scripts has already moved the $_TSR bootstrap into its
+      // barrier script. Lift the barrier here, not on subscribe: streamed
+      // signals subscribe before rendering. Deferred $_TSR chunks then stream
+      // as they settle instead of waiting for setRenderFinished.
+      serverSsr.liftScriptBarrier();
+      return serverSsr.takeBufferedHtml() ?? '';
+    },
+    subscribe(notify) {
+      if (released) return () => {};
+      const stop = serverSsr.onInjectedHtml(notify);
+      let subscribed = true;
+      const unsubscribe = () => {
+        if (!subscribed) return;
+        subscribed = false;
+        subscriptions.delete(unsubscribe);
+        stop();
+      };
+      subscriptions.add(unsubscribe);
+      return unsubscribe;
+    },
+    done,
+    cancel(reason) {
+      settle(
+        reason ?? new DOMException('Octane rendering cancelled', 'AbortError'),
+      );
+      release();
+      void session.abort(reason);
+    },
+    renderComplete() {
+      if (released || renderFinished) return;
+      renderFinished = true;
+      serverSsr.setRenderFinished();
+      if (!serverSsr.isSerializationFinished() && !settled) {
+        timer = setTimeout(() => {
+          const error = new Error(
+            'Octane router serialization timed out after app rendering',
+          );
+          settle(error);
+          void session.fail(error);
+        }, timeoutMs);
+      }
+    },
+  };
+}

package/src/router-server-cleanup.ts

@@ -0,0 +1,11 @@
+import type { AnyRouter } from '@octanejs/tanstack-router';
+
+const released = new WeakSet<NonNullable<AnyRouter['serverSsr']>>();
+
+/** The request handler, serializer and renderer share one native SSR owner. */
+export function cleanupOctaneRouterSSR(router: AnyRouter): void {
+  const serverSsr = router.serverSsr;
+  if (!serverSsr || released.has(serverSsr)) return;
+  released.add(serverSsr);
+  serverSsr.cleanup();
+}