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

package/src/router-external-snapshot.ts

@@ -0,0 +1,363 @@
+import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions/paths';
+import {
+  type AnyRoute,
+  type AnyRouter,
+  associateRouterRenderProfile,
+  captureRouterRenderSnapshot,
+  createRouterRenderRouteTree,
+  defaultParseSearch,
+  defaultStringifySearch,
+  disposeRouterRenderSnapshot,
+  getRouterRenderProfile,
+  matchContext,
+  type RouterRenderJsonRecord,
+  type RouterRenderSnapshot,
+  registerRouterRenderProfile,
+  restoreRouterRenderSnapshot,
+  routerContext,
+} from '@octanejs/tanstack-router';
+import { hasUnchangedOctaneFileRouteHead } from './routes';
+import {
+  getOctaneWorkerRouterRewrite,
+  OCTANE_WORKER_CONTEXT_KEYS,
+  registerOctaneWorkerContext,
+} from './worker-federation-contexts';
+
+export const OCTANE_FILE_ROUTE_SNAPSHOT_PROFILE = Object.freeze({
+  key: 'ultramodern.file-routes',
+  version: '1',
+});
+
+interface GeneratedRouterOrigin {
+  readonly publicContext: RouterRenderJsonRecord;
+  readonly rewrite: AnyRouter['options']['rewrite'];
+}
+const origins = new WeakMap<AnyRouter, GeneratedRouterOrigin>();
+let profileRegistered = false;
+
+function plainRecord(value: unknown): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    [Object.prototype, null].includes(Object.getPrototypeOf(value))
+  );
+}
+
+function record(
+  value: unknown,
+  fields?: readonly string[],
+): Record<string, unknown> {
+  if (!plainRecord(value))
+    throw new TypeError('Worker router context requires a plain record');
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (
+      typeof key !== 'string' ||
+      (fields && !fields.includes(key)) ||
+      !descriptor ||
+      !descriptor.enumerable ||
+      !('value' in descriptor)
+    )
+      throw new TypeError('Unknown Worker router context field or accessor');
+  }
+  return value;
+}
+
+function nonempty(value: unknown): string {
+  if (typeof value !== 'string' || !value.trim() || value.length > 1024)
+    throw new TypeError('Invalid Worker router identity');
+  return value;
+}
+
+/** Only the host entry's public logical identity crosses the Worker boundary. */
+function publicContext(value: unknown): RouterRenderJsonRecord {
+  const context = record(value, ['ultramodern']);
+  const metadata = record(context.ultramodern, ['rendererIdentity']);
+  const identity = record(metadata.rendererIdentity, [
+    'renderer',
+    'appId',
+    'entryName',
+    'protocolVersion',
+    'buildId',
+  ]);
+  if (identity.renderer !== 'octane' || identity.protocolVersion !== 1)
+    throw new TypeError('Unsupported Worker router identity');
+  return Object.freeze({
+    ultramodern: Object.freeze({
+      rendererIdentity: Object.freeze({
+        renderer: 'octane',
+        appId: nonempty(identity.appId),
+        entryName: nonempty(identity.entryName),
+        protocolVersion: 1,
+        buildId: nonempty(identity.buildId),
+      }),
+    }),
+  });
+}
+
+function localizedUrls(value: unknown): LocalisedUrlsOption | undefined {
+  if (value === undefined || typeof value === 'boolean') return value;
+  const input = record(value);
+  const result: Exclude<LocalisedUrlsOption, boolean> = {};
+  for (const [path, translations] of Object.entries(input)) {
+    const names: Record<string, string> = {};
+    for (const [language, target] of Object.entries(record(translations)))
+      names[nonempty(language)] = nonempty(target);
+    result[path] = names;
+  }
+  return result;
+}
+
+function rewriteDescriptor(value: unknown):
+  | {
+      readonly language: string;
+      readonly languages: readonly string[];
+      readonly localisedUrls?: LocalisedUrlsOption;
+    }
+  | undefined {
+  if (value === undefined) return undefined;
+  const input = record(value, ['language', 'languages', 'localisedUrls']);
+  if (
+    !Array.isArray(input.languages) ||
+    !input.languages.length ||
+    input.languages.length > 64
+  )
+    throw new TypeError('Invalid Worker router i18n languages');
+  const languages = input.languages.map(nonempty);
+  const language = nonempty(input.language);
+  if (
+    new Set(languages).size !== languages.length ||
+    !languages.includes(language)
+  )
+    throw new TypeError('Invalid Worker router i18n language');
+  const urls = localizedUrls(input.localisedUrls);
+  return {
+    language,
+    languages,
+    ...(urls === undefined ? {} : { localisedUrls: urls }),
+  };
+}
+
+function nativeRewriteDescriptor(
+  router: AnyRouter,
+): RouterRenderJsonRecord | undefined {
+  if (!router.options.rewrite) return undefined;
+  const known = getOctaneWorkerRouterRewrite()?.capture(router.options.rewrite);
+  if (!known)
+    throw new TypeError(
+      'Custom router rewrite requires an exact Worker profile',
+    );
+  const descriptor = rewriteDescriptor(known);
+  if (!descriptor)
+    throw new TypeError('Missing native router rewrite provenance');
+  return {
+    language: descriptor.language,
+    languages: [...descriptor.languages],
+    ...(descriptor.localisedUrls === undefined
+      ? {}
+      : { localisedUrls: descriptor.localisedUrls }),
+  };
+}
+
+function validateDefaultSnapshot(snapshot: RouterRenderSnapshot): void {
+  publicContext(snapshot.publicContext);
+  rewriteDescriptor(snapshot.i18n);
+}
+
+/** File-route heads are host presentation work, like the already settled loaders. */
+function assertFileRouteRenderHost(
+  router: AnyRouter,
+  allowRewrite: boolean,
+): void {
+  if (
+    router.options.parseSearch !== defaultParseSearch ||
+    router.options.stringifySearch !== defaultStringifySearch ||
+    (!allowRewrite && router.options.rewrite) ||
+    router.options.routeMasks?.length
+  )
+    throw new TypeError(
+      'Router render snapshot: authored router behavior requires an exact local profile',
+    );
+  const authoredRouting = [
+    'caseSensitive',
+    'validateSearch',
+    'loaderDeps',
+    'beforeLoad',
+    'context',
+    'onEnter',
+    'onStay',
+    'onLeave',
+    'lazyFn',
+    'scripts',
+    'headers',
+    'onError',
+    'parseParams',
+    'stringifyParams',
+  ];
+  const seen = new Set<AnyRoute>();
+  const visit = (route: AnyRoute, depth: number) => {
+    if (seen.has(route) || seen.size >= 4096 || depth > 64)
+      throw new TypeError(
+        'Router render snapshot: route geometry must be bounded and acyclic',
+      );
+    seen.add(route);
+    if (
+      authoredRouting.some(
+        key => Reflect.get(route.options, key) !== undefined,
+      ) ||
+      route.options.params?.parse ||
+      route.options.params?.stringify ||
+      route.options.search?.middlewares?.length ||
+      route.lazyFn ||
+      ('path' in route.options && 'id' in route.options) ||
+      !hasUnchangedOctaneFileRouteHead(route)
+    )
+      throw new TypeError(
+        'Router render snapshot: authored route behavior requires an exact local profile',
+      );
+    for (const child of route.children ?? []) visit(child, depth + 1);
+  };
+  visit(router.options.routeTree, 0);
+}
+
+function ensureDefaultProfile(): void {
+  if (profileRegistered) return;
+  registerRouterRenderProfile({
+    id: OCTANE_FILE_ROUTE_SNAPSHOT_PROFILE,
+    assertHost: (router, snapshot) => {
+      const origin = origins.get(router);
+      if (
+        !origin ||
+        origin.rewrite !== router.options.rewrite ||
+        JSON.stringify(publicContext(router.options.context)) !==
+          JSON.stringify(origin.publicContext)
+      )
+        throw new TypeError('Generated Worker router origin changed');
+      assertFileRouteRenderHost(router, snapshot.i18n !== undefined);
+      validateDefaultSnapshot(snapshot);
+      if (
+        JSON.stringify(nativeRewriteDescriptor(router)) !==
+        JSON.stringify(snapshot.i18n)
+      )
+        throw new TypeError(
+          'Worker router rewrite differs from its native provenance',
+        );
+    },
+    createRoutingTree: snapshot => {
+      validateDefaultSnapshot(snapshot);
+      return createRouterRenderRouteTree(snapshot.routes);
+    },
+    routingOptions: snapshot => {
+      const defaults = {
+        parseSearch: defaultParseSearch,
+        stringifySearch: defaultStringifySearch,
+      };
+      const i18n = rewriteDescriptor(snapshot.i18n);
+      if (!i18n) return defaults;
+      const codec = getOctaneWorkerRouterRewrite();
+      if (!codec)
+        throw new TypeError('Missing owning Worker router i18n codec');
+      return { ...defaults, rewrite: codec.restore(i18n) };
+    },
+  });
+  profileRegistered = true;
+}
+
+/** Associate the genuine router produced by the generated file-route factory. */
+export function associateOctaneFileRouteSnapshot(router: AnyRouter): void {
+  ensureDefaultProfile();
+  const context = publicContext(router.options.context);
+  origins.set(router, {
+    publicContext: context,
+    rewrite: router.options.rewrite,
+  });
+  associateRouterRenderProfile(router, {
+    id: OCTANE_FILE_ROUTE_SNAPSHOT_PROFILE,
+    publicContext: context,
+  });
+}
+
+export function captureOctaneRouterSnapshot(
+  router: AnyRouter,
+): RouterRenderSnapshot {
+  const origin = origins.get(router);
+  const declared = getRouterRenderProfile(router);
+  if (
+    origin &&
+    declared?.key === OCTANE_FILE_ROUTE_SNAPSHOT_PROFILE.key &&
+    declared.version === OCTANE_FILE_ROUTE_SNAPSHOT_PROFILE.version
+  ) {
+    const i18n = nativeRewriteDescriptor(router);
+    associateRouterRenderProfile(router, {
+      id: OCTANE_FILE_ROUTE_SNAPSHOT_PROFILE,
+      publicContext: origin.publicContext,
+      ...(i18n === undefined ? {} : { i18n }),
+    });
+  }
+  return captureRouterRenderSnapshot(router);
+}
+
+let registrations = 0;
+let releaseContexts: (() => void) | undefined;
+
+/** Startup registration uses the actual physical native router/match Contexts. */
+export function registerOctaneRouterWorkerContexts(): () => void {
+  ensureDefaultProfile();
+  if (!releaseContexts) {
+    const releaseRouter = registerOctaneWorkerContext(routerContext, {
+      key: OCTANE_WORKER_CONTEXT_KEYS.router,
+      encode: value => {
+        if (!value) throw new TypeError('Missing native router provider');
+        return captureOctaneRouterSnapshot(value);
+      },
+      decode: (value, signal) => restoreRouterRenderSnapshot(value, { signal }),
+      dispose: value => {
+        if (value) disposeRouterRenderSnapshot(value);
+      },
+      isProvided: value => value !== undefined,
+    });
+    try {
+      const releaseMatch = registerOctaneWorkerContext(matchContext, {
+        key: OCTANE_WORKER_CONTEXT_KEYS.match,
+        encode: nonempty,
+        decode: nonempty,
+        validate: (value, readContext) => {
+          const selected = readContext(routerContext);
+          const router = selected.present ? selected.value : undefined;
+          // Native Match and useMatch share the active route store key, not
+          // the location-specific match identity (which includes parameters).
+          const current = router?.state.matches.find(
+            match => match.routeId === value,
+          );
+          if (
+            !router ||
+            !current ||
+            typeof value !== 'string' ||
+            router.stores.getMatchStore(value).get() !== current
+          )
+            throw new TypeError(
+              'Worker match context requires its selected native router and a current match',
+            );
+        },
+        isProvided: value => value !== undefined,
+      });
+      releaseContexts = () => {
+        releaseMatch();
+        releaseRouter();
+      };
+    } catch (error) {
+      releaseRouter();
+      throw error;
+    }
+  }
+  registrations++;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    if (--registrations === 0) {
+      releaseContexts?.();
+      releaseContexts = undefined;
+    }
+  };
+}

package/src/router-handler.ts

@@ -0,0 +1,185 @@
+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 result = router._serverResult;
+  if (result?.type === 'redirect')
+    appendHeaders(headers, result.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 ?? [])],
+      });
+
+      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({ _signal: session.signal }), 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 loadResult = router._serverResult;
+      if (loadResult?.type === 'redirect') {
+        const resolved = loadResult.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({ signal: session.signal }),
+        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-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();
+}