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

package/src/index.ts

@@ -0,0 +1,10 @@
+export type { RendererIdentity } from '@modern-js/renderer-core/identity';
+export type { OctaneDocumentBootstrap } from './bootstrap';
+
+export const OCTANE_RUNTIME_PROFILE = Object.freeze({
+  renderer: 'octane',
+  runtime: '0.13.8',
+  router: '0.2.10',
+  routerCore: '1.171.34',
+  history: '1.162.4',
+});

package/src/manifest.ts

@@ -0,0 +1,253 @@
+import type { NativeCompilerArtifacts } from '@modern-js/renderer-core/adapter';
+import {
+  nativeModuleManifestFilename,
+  type RendererIdentity,
+  readRendererIdentity,
+} from '@modern-js/renderer-core/identity';
+import {
+  assertNativeHydrationBuildId,
+  assertOctaneIdentity,
+} from './bootstrap';
+
+export const OCTANE_RUNTIME_VERSION = '0.13.8';
+export const OCTANE_COMPILER_VERSION = '0.2.4';
+
+export interface OctaneCompiledSource {
+  readonly resource: string;
+  readonly canonicalId: string;
+  readonly moduleId: string | number;
+  readonly transformKind: 'compile' | 'slots' | 'client-only-stub';
+  readonly emittedSourceSha256: string;
+  readonly assets: readonly string[];
+}
+
+export interface OctaneModuleManifest {
+  readonly schemaVersion: 1;
+  readonly renderer: 'octane';
+  readonly runtimeVersion: typeof OCTANE_RUNTIME_VERSION;
+  readonly compilerVersion: typeof OCTANE_COMPILER_VERSION;
+  readonly rendererIdentity: Readonly<RendererIdentity>;
+  readonly nativeHydrationBuildId: string;
+  readonly sourceModules: readonly OctaneCompiledSource[];
+  readonly assets: readonly {
+    readonly file: string;
+    readonly sha256: string;
+  }[];
+}
+
+export function octaneModuleManifestFileName(entryName: string): string {
+  return nativeModuleManifestFilename('octane', entryName);
+}
+
+function record(
+  value: unknown,
+  fields: readonly string[],
+): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Malformed Octane compiler manifest object.');
+  }
+  if (Object.keys(value).some(key => !fields.includes(key))) {
+    throw new Error('Octane compiler manifest contains an unknown field.');
+  }
+  return value as Record<string, unknown>;
+}
+
+function digest(value: unknown): value is string {
+  return typeof value === 'string' && /^[a-f\d]{64}$/u.test(value);
+}
+
+function nonempty(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    value.trim().length > 0 &&
+    !value.includes('\0')
+  );
+}
+
+function assetPath(value: unknown): value is string {
+  return (
+    nonempty(value) &&
+    value.endsWith('.js') &&
+    !value.startsWith('/') &&
+    !value.includes('\\') &&
+    !value.split('/').some(part => part === '..' || part === '.' || !part)
+  );
+}
+
+/** A build's manifest is an immutable artifact: its shape is checked once. */
+const validatedManifests = new WeakMap<object, OctaneModuleManifest>();
+
+/** Validates completed native bytes separately from the source/profile build. */
+export function validateOctaneModuleManifest(
+  value: unknown,
+  expectedIdentity: RendererIdentity,
+  expectedNativeHydrationBuildId?: string,
+): OctaneModuleManifest {
+  assertOctaneIdentity(expectedIdentity);
+  const cached =
+    value && typeof value === 'object'
+      ? validatedManifests.get(value)
+      : undefined;
+  const manifest = cached ?? readOctaneModuleManifest(value);
+  readRendererIdentity(manifest.rendererIdentity, expectedIdentity);
+  if (expectedNativeHydrationBuildId !== undefined) {
+    assertNativeHydrationBuildId(expectedNativeHydrationBuildId);
+    if (manifest.nativeHydrationBuildId !== expectedNativeHydrationBuildId) {
+      throw new Error(
+        'Octane native hydration build differs from the compiled client.',
+      );
+    }
+  }
+  if (!cached) {
+    validatedManifests.set(value as object, manifest);
+    validatedManifests.set(manifest, manifest);
+  }
+  return manifest;
+}
+
+function readOctaneModuleManifest(value: unknown): OctaneModuleManifest {
+  const manifest = record(value, [
+    'schemaVersion',
+    'renderer',
+    'runtimeVersion',
+    'compilerVersion',
+    'rendererIdentity',
+    'nativeHydrationBuildId',
+    'sourceModules',
+    'assets',
+  ]);
+  if (
+    manifest.schemaVersion !== 1 ||
+    manifest.renderer !== 'octane' ||
+    manifest.runtimeVersion !== OCTANE_RUNTIME_VERSION ||
+    manifest.compilerVersion !== OCTANE_COMPILER_VERSION
+  ) {
+    throw new Error(
+      'Octane compiler manifest ABI conflicts with the application.',
+    );
+  }
+  // The caller compares this well-formed record with its expected identity.
+  const rendererIdentity = readRendererIdentity(
+    manifest.rendererIdentity,
+    manifest.rendererIdentity as RendererIdentity,
+  );
+  const nativeHydrationBuildId = manifest.nativeHydrationBuildId;
+  assertNativeHydrationBuildId(nativeHydrationBuildId);
+  if (!Array.isArray(manifest.assets) || !manifest.assets.length) {
+    throw new Error(
+      'Octane compiler manifest has no emitted JavaScript closure.',
+    );
+  }
+  const assetNames = new Set<string>();
+  const assets = manifest.assets.map(value => {
+    const asset = record(value, ['file', 'sha256']);
+    if (
+      !assetPath(asset.file) ||
+      !digest(asset.sha256) ||
+      assetNames.has(asset.file)
+    ) {
+      throw new Error('Invalid Octane emitted asset digest.');
+    }
+    assetNames.add(asset.file);
+    return Object.freeze({ file: asset.file, sha256: asset.sha256 });
+  });
+  if (
+    !Array.isArray(manifest.sourceModules) ||
+    !manifest.sourceModules.length
+  ) {
+    throw new Error(
+      'Octane compiler manifest has no authenticated native sources.',
+    );
+  }
+  const resources = new Set<string>();
+  const sourceModules = manifest.sourceModules.map(value => {
+    const source = record(value, [
+      'resource',
+      'canonicalId',
+      'moduleId',
+      'transformKind',
+      'emittedSourceSha256',
+      'assets',
+    ]);
+    if (
+      !nonempty(source.resource) ||
+      source.resource.startsWith('/') ||
+      source.resource.includes('\\') ||
+      !nonempty(source.canonicalId) ||
+      !(
+        (typeof source.moduleId === 'string' && nonempty(source.moduleId)) ||
+        (typeof source.moduleId === 'number' &&
+          Number.isFinite(source.moduleId))
+      ) ||
+      !(
+        source.transformKind === 'compile' ||
+        source.transformKind === 'slots' ||
+        source.transformKind === 'client-only-stub'
+      ) ||
+      !digest(source.emittedSourceSha256) ||
+      !Array.isArray(source.assets) ||
+      !source.assets.length ||
+      source.assets.some(
+        file => typeof file !== 'string' || !assetNames.has(file),
+      ) ||
+      new Set(source.assets).size !== source.assets.length ||
+      resources.has(source.resource)
+    ) {
+      throw new Error('Invalid Octane native source-to-asset provenance.');
+    }
+    resources.add(source.resource);
+    return Object.freeze({
+      resource: source.resource,
+      canonicalId: source.canonicalId,
+      moduleId: source.moduleId,
+      transformKind: source.transformKind,
+      emittedSourceSha256: source.emittedSourceSha256,
+      assets: Object.freeze([...source.assets] as string[]),
+    });
+  });
+  return Object.freeze({
+    schemaVersion: 1,
+    renderer: 'octane',
+    runtimeVersion: OCTANE_RUNTIME_VERSION,
+    compilerVersion: OCTANE_COMPILER_VERSION,
+    rendererIdentity,
+    nativeHydrationBuildId,
+    sourceModules: Object.freeze(sourceModules),
+    assets: Object.freeze(assets),
+  });
+}
+
+/**
+ * The compiler artifact ABI. It lives in this runtime module, not in the
+ * build-only `./plugin`, because the production server validates manifests
+ * with it and deployments trace it from there.
+ */
+export const compilerArtifacts: NativeCompilerArtifacts = {
+  clientManifestFile: octaneModuleManifestFileName,
+  async validateClientManifest(value, identity, context) {
+    const hydrationBuildId =
+      context.compilationHash ?? context.hydrationBuildId;
+    if (
+      context.development &&
+      (typeof hydrationBuildId !== 'string' || !hydrationBuildId.trim())
+    )
+      throw new Error(
+        'Octane development snapshot has no native hydration build.',
+      );
+    const nativeManifest = validateOctaneModuleManifest(
+      value,
+      identity,
+      hydrationBuildId,
+    );
+    return {
+      nativeManifest,
+      hydrationBuildId: nativeManifest.nativeHydrationBuildId,
+    };
+  },
+  isMutableDevelopmentAsset(filename, entryNames) {
+    return (
+      filename === 'octane-client-build.json' ||
+      entryNames.some(entry => filename === octaneModuleManifestFileName(entry))
+    );
+  },
+};

package/src/plugin/compiler-manifest.cjs

@@ -0,0 +1,204 @@
+const { createHash } = require('node:crypto');
+const path = require('node:path');
+const { getOctaneRspackBuildInfo } = require('@octanejs/rspack-plugin');
+
+const name = 'ultramodern:octane:compiler-manifest';
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+
+/** The released native compiler remains responsible for every transformation. */
+class OctaneCompilerManifestPlugin {
+  constructor(options) {
+    this.options = options;
+  }
+
+  apply(compiler) {
+    compiler.hooks.normalModuleFactory.tap(name, factory => {
+      factory.hooks.beforeResolve.tap(name, result => {
+        if (/\.svg\?(?:[^#]*&)?react(?:[=&]|$)/u.test(result.request)) {
+          throw new Error(
+            'unsupported-renderer-capability: `?react` SVG imports are React components; import Octane SVG components with `?component`.',
+          );
+        }
+      });
+      factory.hooks.afterResolve.tap(name, result => {
+        const resource = result.createData?.resource?.split('?')[0];
+        if (resource && path.extname(resource).toLowerCase() === '.jsx') {
+          throw new Error(
+            `unsupported-renderer-capability: Octane does not support .jsx source: ${resource}. Supported source extensions: .tsx, .tsrx, .ts, .js.`,
+          );
+        }
+      });
+    });
+    if (!this.options.emitClientManifest) return;
+    compiler.hooks.thisCompilation.tap(name, compilation => {
+      compilation.hooks.processAssets.tap(
+        {
+          name,
+          stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_REPORT + 1,
+        },
+        () => {
+          // Preserve the owning resolver/compiler diagnostic on an invalid graph.
+          if (compilation.errors.length) return;
+          const buildAsset = compilation.getAsset('octane-client-build.json');
+          if (!buildAsset)
+            throw new Error(
+              'The native Octane client build manifest is missing.',
+            );
+          const nativeBuild = JSON.parse(buildAsset.source.source().toString());
+          if (
+            nativeBuild.version !== 1 ||
+            nativeBuild.buildId !== compilation.hash
+          ) {
+            throw new Error(
+              'The native Octane client manifest does not match the completed compilation.',
+            );
+          }
+          const sourcesByModule = new Map();
+          const moduleAssets = new Map();
+          const visit = (module, inheritedAssets = []) => {
+            const chunks = [
+              ...compilation.chunkGraph.getModuleChunksIterable(module),
+            ];
+            const previousAssets = moduleAssets.get(module);
+            const assets = [
+              ...new Set([
+                ...(previousAssets ?? []),
+                ...inheritedAssets,
+                ...chunks.flatMap(chunk => [...chunk.files]),
+              ]),
+            ]
+              .filter(file => file.endsWith('.js'))
+              .sort();
+            // Rspack also lists concatenated children as standalone modules.
+            // A later parent visit can supply their first emitted chunk.
+            if (
+              previousAssets &&
+              assets.every(file => previousAssets.has(file))
+            )
+              return;
+            moduleAssets.set(module, new Set(assets));
+            const info = getOctaneRspackBuildInfo(module);
+            if (info && assets.length) {
+              const resource = module.resource?.split('?')[0];
+              const emitted = module.originalSource();
+              if (!resource || !emitted) {
+                throw new Error(
+                  `Octane compiled module has no source: ${module.identifier()}.`,
+                );
+              }
+              const relative = path.relative(this.options.root, resource);
+              sourcesByModule.set(module, {
+                resource:
+                  relative.split(path.sep).join('/') +
+                  (info.resourceQuery ?? ''),
+                canonicalId: info.canonicalId,
+                moduleId:
+                  compilation.chunkGraph.getModuleId(module) ??
+                  module.identifier(),
+                transformKind: info.transformKind,
+                emittedSourceSha256: digest(emitted.buffer()),
+                assets,
+              });
+            }
+            for (const nested of module.modules ?? []) visit(nested, assets);
+          };
+          for (const module of compilation.modules) visit(module);
+          const sources = [...sourcesByModule.values()];
+          sources.sort((left, right) =>
+            left.resource.localeCompare(right.resource),
+          );
+          // Module Federation publishes exposed native modules through a
+          // separate container entry in this same compilation. Its browser
+          // closure belongs to this application's publication, even when the
+          // document itself never imports an exposed component.
+          const containerChunks = new Set();
+          for (const [entryName, entry] of compilation.entries) {
+            if (
+              !entry.dependencies.some(
+                dependency => dependency.type === 'container entry',
+              )
+            )
+              continue;
+            const container = compilation.entrypoints.get(entryName);
+            if (!container)
+              throw new Error(
+                `Octane compiler has no federation container entry for ${entryName}.`,
+              );
+            for (const chunk of container.chunks) {
+              containerChunks.add(chunk);
+              for (const referenced of chunk.getAllReferencedChunks())
+                containerChunks.add(referenced);
+            }
+          }
+          const identities = this.options.rendererIdentities();
+          if (!identities || !Object.keys(identities).length) {
+            throw new Error(
+              'Octane compiler requires immutable application entry identities.',
+            );
+          }
+          for (const [entryName, rendererIdentity] of Object.entries(
+            identities,
+          )) {
+            if (
+              rendererIdentity?.renderer !== 'octane' ||
+              rendererIdentity.entryName !== entryName
+            ) {
+              throw new Error(
+                `Octane compiler identity conflicts with entry ${entryName}.`,
+              );
+            }
+            const entrypoint = compilation.entrypoints.get(entryName);
+            if (!entrypoint)
+              throw new Error(
+                `Octane compiler has no client entry for ${entryName}.`,
+              );
+            const entryChunks = new Set([
+              ...entrypoint.chunks,
+              ...containerChunks,
+            ]);
+            for (const chunk of entrypoint.chunks) {
+              for (const referenced of chunk.getAllReferencedChunks())
+                entryChunks.add(referenced);
+            }
+            const files = [
+              ...new Set(
+                [...entryChunks]
+                  .flatMap(chunk => [...chunk.files])
+                  .filter(file => file.endsWith('.js')),
+              ),
+            ].sort();
+            const fileSet = new Set(files);
+            const manifest = {
+              schemaVersion: 1,
+              renderer: 'octane',
+              runtimeVersion: this.options.runtimeVersion,
+              compilerVersion: this.options.compilerVersion,
+              rendererIdentity,
+              nativeHydrationBuildId: nativeBuild.buildId,
+              sourceModules: sources.flatMap(source => {
+                const assets = source.assets.filter(file => fileSet.has(file));
+                return assets.length ? [{ ...source, assets }] : [];
+              }),
+              assets: files.map(file => ({
+                file,
+                sha256: digest(compilation.getAsset(file).source.buffer()),
+              })),
+            };
+            this.options.validateManifest(
+              manifest,
+              rendererIdentity,
+              compilation.hash,
+            );
+            compilation.emitAsset(
+              this.options.manifestFilename(entryName),
+              new compiler.webpack.sources.RawSource(
+                `${JSON.stringify(manifest, null, 2)}\n`,
+              ),
+            );
+          }
+        },
+      );
+    });
+  }
+}
+module.exports = { OctaneCompilerManifestPlugin };

package/src/plugin/compiler.ts

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { NativeRendererCompilerOptions } from '@modern-js/renderer-core/adapter';
+import type { RsbuildPlugin } from '@rsbuild/core';
+import {
+  OCTANE_COMPILER_VERSION,
+  OCTANE_RUNTIME_VERSION,
+  octaneModuleManifestFileName,
+  validateOctaneModuleManifest,
+} from '../manifest';
+
+export function pluginSourceDirectory(): string {
+  let directory = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const compiler = path.join(directory, 'src/plugin');
+    if (
+      fs.existsSync(path.join(directory, 'package.json')) &&
+      fs.existsSync(path.join(compiler, 'compiler-manifest.cjs'))
+    )
+      return compiler;
+    const parent = path.dirname(directory);
+    if (parent === directory)
+      throw new Error('Cannot locate the UltraModern Octane compiler package.');
+    directory = parent;
+  }
+}
+
+/** Octane owns native compilation; UltraModern retains the application host. */
+export function createOctaneCompilerPlugin(
+  options: NativeRendererCompilerOptions,
+): RsbuildPlugin {
+  return {
+    name: 'ultramodern:octane:compiler',
+    setup(api) {
+      const directory = pluginSourceDirectory();
+      const require = createRequire(path.join(directory, 'index.cjs'));
+      const {
+        OctaneCompilerManifestPlugin,
+      } = require('./compiler-manifest.cjs');
+      // The application installs the Octane compiler; resolve it lazily so
+      // descriptor readers never load it.
+      const appRequire = createRequire(
+        path.join(api.context.rootPath, 'package.json'),
+      );
+      const {
+        inferRspackEnvironment,
+        OctaneRspackPlugin,
+      }: typeof import('@octanejs/rspack-plugin') = appRequire(
+        '@octanejs/rspack-plugin',
+      );
+      api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) =>
+        mergeRsbuildConfig(config, {
+          source: {
+            // Released native bindings export raw TypeScript and TSRX.
+            include: [/[/\\]@octanejs[/\\]/u],
+          },
+        }),
+      );
+      api.modifyRspackConfig((config, { environment: rsbuildEnvironment }) => {
+        // The Cloudflare SSR worker targets `webworker`; it still renders
+        // the server document rather than a client hydration bundle.
+        const environment =
+          rsbuildEnvironment.name === options.workerEnvironmentName
+            ? 'server'
+            : inferRspackEnvironment(config.target);
+        config.plugins ??= [];
+        config.plugins.push(
+          new OctaneRspackPlugin({
+            root: api.context.rootPath,
+            environment,
+            transpile: false,
+          }),
+        );
+        config.plugins.push(
+          new OctaneCompilerManifestPlugin({
+            emitClientManifest: environment === 'client',
+            root: api.context.rootPath,
+            runtimeVersion: OCTANE_RUNTIME_VERSION,
+            compilerVersion: OCTANE_COMPILER_VERSION,
+            rendererIdentities: options.rendererIdentities,
+            manifestFilename: octaneModuleManifestFileName,
+            validateManifest: validateOctaneModuleManifest,
+          }),
+        );
+        config.module ??= {};
+        config.module.rules ??= [];
+        // Rsbuild's existing SWC rule handles ordinary .ts/.tsx sources.
+        // TSRX needs the same stripping stage after Octane's pre-loader.
+        config.module.rules.push({
+          test: /\.tsrx$/u,
+          type: 'javascript/auto',
+          use: [
+            {
+              loader: 'builtin:swc-loader',
+              options: { detectSyntax: 'auto' },
+            },
+          ],
+        });
+      });
+    },
+  };
+}