@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.9 → 3.9.3-ultramodern.1

package/src/cloudflare/native-renderer.ts

@@ -0,0 +1,117 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { WORKER_BUNDLE_DIRECTORY } from './constants';
+import type { WorkerRendererBuild } from './renderer-identity';
+import { isRecord } from './utils';
+
+/**
+ * Build-validated native document inputs for each worker route. The Node host
+ * reads these from `dist`; a module worker has no filesystem, so the native
+ * build writes them beside its worker bundles and deploy inlines them.
+ */
+export const NATIVE_RENDERER_WORKER_RESOURCES_FILE = `${WORKER_BUNDLE_DIRECTORY}/native-renderer.json`;
+
+export interface NativeRendererWorkerEntry {
+  readonly assets: readonly unknown[];
+  readonly nativeManifest?: unknown;
+  readonly hydrationBuildId?: string;
+  readonly serverConfig: {
+    readonly ssr: boolean | 'stream';
+    readonly ssrByRouteIds?: readonly string[];
+  };
+  readonly csrFallbackHeader?: string;
+  readonly nonce?: string;
+}
+
+export interface NativeRendererWorkerResources {
+  readonly schema: 'ultramodern-native-worker-resources';
+  readonly version: 1;
+  /** The built renderer, whose adapter serves native documents. */
+  readonly renderer: string;
+  readonly entries: Readonly<Record<string, NativeRendererWorkerEntry>>;
+}
+
+const invalid = (detail: string) =>
+  new Error(
+    `Invalid native renderer worker resources (${NATIVE_RENDERER_WORKER_RESOURCES_FILE}): ${detail}. Rebuild the application with deploy.worker.ssr before deploying.`,
+  );
+
+function validateEntry(entryName: string, value: unknown) {
+  if (!isRecord(value)) throw invalid(`entry ${entryName} is not an object`);
+  const { assets, hydrationBuildId, serverConfig, csrFallbackHeader, nonce } =
+    value;
+  if (!Array.isArray(assets) || !assets.length)
+    throw invalid(`entry ${entryName} has no document assets`);
+  if (
+    hydrationBuildId !== undefined &&
+    (typeof hydrationBuildId !== 'string' || !hydrationBuildId.trim())
+  )
+    throw invalid(`entry ${entryName} has an empty hydration build ID`);
+  if (
+    !isRecord(serverConfig) ||
+    ![true, false, 'stream'].includes(serverConfig.ssr as never) ||
+    (serverConfig.ssrByRouteIds !== undefined &&
+      (!Array.isArray(serverConfig.ssrByRouteIds) ||
+        serverConfig.ssrByRouteIds.some(id => typeof id !== 'string')))
+  )
+    throw invalid(`entry ${entryName} has an invalid server config`);
+  for (const [field, text] of [
+    ['csrFallbackHeader', csrFallbackHeader],
+    ['nonce', nonce],
+  ] as const)
+    if (text !== undefined && (typeof text !== 'string' || !text))
+      throw invalid(`entry ${entryName} has an invalid ${field}`);
+}
+
+/**
+ * Read the native worker resources for a built application. Every built entry
+ * of the resources' renderer must have validated document inputs.
+ */
+export async function readNativeRendererWorkerResources(
+  distDirectory: string,
+  build: WorkerRendererBuild | undefined,
+): Promise<NativeRendererWorkerResources | undefined> {
+  let bytes: string;
+  try {
+    bytes = await fs.readFile(
+      path.join(distDirectory, NATIVE_RENDERER_WORKER_RESOURCES_FILE),
+      'utf8',
+    );
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+      return undefined;
+    throw error;
+  }
+  const value: unknown = JSON.parse(bytes);
+  if (
+    !isRecord(value) ||
+    value.schema !== 'ultramodern-native-worker-resources' ||
+    value.version !== 1 ||
+    typeof value.renderer !== 'string' ||
+    !value.renderer ||
+    !isRecord(value.entries)
+  )
+    throw invalid('unknown schema');
+  if (
+    value.renderer !== build?.renderer.name ||
+    !build.renderer.nativeDocuments
+  )
+    throw invalid(
+      `renderer ${value.renderer} is not the built native-document renderer`,
+    );
+  const entries = value.entries;
+  const nativeEntries = Object.entries(build.identities).filter(
+    ([, identity]) => identity.renderer === value.renderer,
+  );
+  for (const [entryName] of nativeEntries)
+    if (!Object.hasOwn(entries, entryName))
+      throw invalid(`entry ${entryName} is missing`);
+  for (const [entryName, entry] of Object.entries(entries)) {
+    if (!nativeEntries.some(([name]) => name === entryName))
+      throw invalid(
+        `entry ${entryName} has no built ${value.renderer} renderer identity`,
+      );
+    validateEntry(entryName, entry);
+  }
+  return value as unknown as NativeRendererWorkerResources;
+}

package/src/cloudflare/renderer-identity.ts

@@ -0,0 +1,171 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import {
+  formatBackendFederationValidationErrors,
+  type RendererIdentity,
+  validateRendererIdentity,
+  validateRendererProfile,
+} from '@modern-js/backend-federation-contracts';
+import type { DeliveryUnitStamp } from './delivery-unit';
+import { isRecord } from './utils';
+
+export type WorkerRendererIdentities = Readonly<
+  Record<string, RendererIdentity>
+>;
+
+/** The built renderer and how its adapter serves worker documents. */
+export interface WorkerRenderer {
+  readonly name: string;
+  /** Documents come only from the renderer's native server handler. */
+  readonly nativeDocuments: boolean;
+  readonly rsc: boolean;
+}
+
+export interface WorkerRendererBuild {
+  readonly renderer: WorkerRenderer;
+  readonly identities: WorkerRendererIdentities;
+}
+
+/** Bind response metadata to the finalized build and its generated entries. */
+export async function readWorkerRendererBuild(
+  distDirectory: string,
+  routes: readonly {
+    entryName?: unknown;
+    entryPath?: unknown;
+    isApi?: unknown;
+    isSSR?: unknown;
+    worker?: unknown;
+    bundle?: unknown;
+    isRSC?: unknown;
+    isStream?: unknown;
+  }[],
+  deliveryUnit?: DeliveryUnitStamp,
+): Promise<WorkerRendererBuild | undefined> {
+  let bytes: string;
+  try {
+    bytes = await fs.readFile(
+      path.join(distDirectory, 'renderer-build.json'),
+      'utf8',
+    );
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+      return undefined;
+    throw error;
+  }
+  const build: unknown = JSON.parse(bytes);
+  if (
+    !isRecord(build) ||
+    build.schema !== 'ultramodern-renderer-build' ||
+    build.version !== 2 ||
+    typeof build.buildId !== 'string' ||
+    !/^[a-f0-9]{64}$/u.test(build.buildId) ||
+    !isRecord(build.profile) ||
+    build.renderer !== build.profile.renderer ||
+    !isRecord(build.worker) ||
+    typeof build.worker.nativeDocuments !== 'boolean' ||
+    typeof build.worker.rsc !== 'boolean' ||
+    !isRecord(build.entries) ||
+    !Object.keys(build.entries).length
+  )
+    throw new Error(
+      'Invalid or outdated renderer-build.json for the Cloudflare worker; rebuild the application.',
+    );
+
+  // The SDK profile also carries compiler configuration. Only the neutral
+  // renderer protocol fields belong to the worker response binding.
+  const { renderer, protocolVersion, compiler, hydration, router } =
+    build.profile;
+  const validation = validateRendererProfile({
+    renderer,
+    protocolVersion,
+    compiler,
+    hydration,
+    router,
+  });
+  if (!validation.ok)
+    throw new Error(formatBackendFederationValidationErrors(validation.errors));
+
+  const identities: Record<string, RendererIdentity> = {};
+  let appId: string | undefined;
+  for (const [entryName, value] of Object.entries(build.entries)) {
+    const validation = validateRendererIdentity(value);
+    if (!validation.ok)
+      throw new Error(
+        formatBackendFederationValidationErrors(validation.errors),
+      );
+    const identity = value as RendererIdentity;
+    if (
+      entryName === '__proto__' ||
+      identity.entryName !== entryName ||
+      identity.renderer !== renderer ||
+      identity.protocolVersion !== protocolVersion ||
+      identity.buildId !== build.buildId ||
+      (appId !== undefined && identity.appId !== appId)
+    )
+      throw new Error(
+        'Cloudflare renderer entry identity conflicts with its built manifest',
+      );
+    appId = identity.appId;
+    identities[entryName] = Object.freeze({ ...identity });
+  }
+  for (const route of routes) {
+    // Native public routes name a copied file rather than a renderer entry.
+    // Classify the original route shape so application dispatch markers cannot
+    // be erased by the worker manifest's normalization.
+    if (
+      route.isSSR === false &&
+      route.entryName === undefined &&
+      route.worker === undefined &&
+      route.bundle === undefined &&
+      (route.isRSC === undefined || route.isRSC === false) &&
+      (route.isStream === undefined || route.isStream === false) &&
+      typeof route.entryPath === 'string' &&
+      route.entryPath.startsWith('public/') &&
+      !route.entryPath.includes('\\') &&
+      path.posix.normalize(route.entryPath) === route.entryPath
+    ) {
+      const asset = await fs.stat(path.join(distDirectory, route.entryPath));
+      if (asset.isFile()) continue;
+    }
+    // The BFF prefix route is served by the API worker, never a renderer
+    // entry; it carries no document, bundle or dispatch marker.
+    if (
+      route.isApi === true &&
+      route.isSSR === false &&
+      route.entryName === undefined &&
+      route.entryPath === '' &&
+      route.worker === undefined &&
+      route.bundle === undefined &&
+      (route.isRSC === undefined || route.isRSC === false) &&
+      (route.isStream === undefined || route.isStream === false)
+    )
+      continue;
+    if (
+      typeof route.entryName !== 'string' ||
+      !Object.hasOwn(identities, route.entryName)
+    )
+      throw new Error(
+        `Cloudflare generated route has no built renderer identity for ${String(route.entryName)}`,
+      );
+  }
+  const ui = deliveryUnit?.surfaces.ui;
+  if (
+    ui &&
+    !isDeepStrictEqual(
+      identities[ui.rendererIdentity.entryName],
+      ui.rendererIdentity,
+    )
+  )
+    throw new Error(
+      'Cloudflare built renderer identity conflicts with its finalized delivery unit',
+    );
+  return Object.freeze({
+    renderer: Object.freeze({
+      name: renderer as string,
+      nativeDocuments: build.worker.nativeDocuments,
+      rsc: build.worker.rsc,
+    }),
+    identities: Object.freeze(identities),
+  });
+}

package/src/cloudflare/worker-manifest.ts

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import type {} from '@modern-js/server-runtime-extensions/server-config';
 import { fs as fse } from '@modern-js/utils';
+import { getCloudflareWorkerRouteDataEntryName } from '../cloudflare-output-contract';
 import { readRouteSpec } from './artifacts';
 import {
   ASSETS_BINDING,
@@ -21,12 +22,16 @@ import {
 } from './constants';
 import type { DeliveryUnitStamp } from './delivery-unit';
 import { createI18nWorkerManifest } from './i18n-worker';
+import { readNativeRendererWorkerResources } from './native-renderer';
+import { readWorkerRendererBuild } from './renderer-identity';
 import { createCloudflareWorkerSecurityPolicy } from './security-policies';
 import type { CloudflareAppContext, CloudflareModernConfig } from './types';
 import { isRecord, normalizeRelativePath } from './utils';
 import {
   createWorkerManifestServiceBindings,
   createWorkerServiceBindings,
+  createWorkerVpcServiceBindings,
+  getWorkerEffectBffPrefix,
 } from './wrangler-config';
 
 const createMissingEffectBffWorkerError = (
@@ -118,7 +123,38 @@ const createModuleFederationWorkerManifest = async (
     ];
   });
 
-  return name && exposes.length > 0 ? { name, exposes } : undefined;
+  if (!name || exposes.length === 0) return undefined;
+
+  // A fragment is rendered by this app's own route, so it depends on the
+  // route stylesheets too (for example a global Tailwind sheet no exposed
+  // component imports). Bundle them so the worker reports them to the
+  // composing shell without reading assets at request time.
+  const routeManifestPath = path.join(
+    outputDirectory,
+    PUBLIC_ASSETS_DIRECTORY,
+    ROUTE_MANIFEST_FILE,
+  );
+  const routeManifest = (await fse.pathExists(routeManifestPath))
+    ? ((await fse.readJson(routeManifestPath)) as unknown)
+    : undefined;
+  const routeAssets =
+    isRecord(routeManifest) && isRecord(routeManifest.routeAssets)
+      ? Object.values(routeManifest.routeAssets).filter(isRecord)
+      : [];
+  const routeCss = [
+    ...new Set(
+      routeAssets.flatMap(routeAsset =>
+        [routeAsset.referenceCssAssets, routeAsset.assets]
+          .flatMap(value => (Array.isArray(value) ? value : []))
+          .filter(
+            (asset): asset is string =>
+              typeof asset === 'string' && asset.endsWith('.css'),
+          ),
+      ),
+    ),
+  ];
+
+  return { name, exposes, routeCss };
 };
 
 export const createWorkerManifest = async (
@@ -132,6 +168,15 @@ export const createWorkerManifest = async (
     routeSpec.routes.map(async (route: Record<string, any>) => {
       const worker =
         typeof route.worker === 'string' ? route.worker : undefined;
+      const routeDataWorker =
+        route.isSSR && typeof route.entryName === 'string'
+          ? `${WORKER_BUNDLE_DIRECTORY}/${getCloudflareWorkerRouteDataEntryName(
+              route.entryName,
+            )}.js`
+          : undefined;
+      const hasRouteDataWorker = routeDataWorker
+        ? await fse.pathExists(path.join(outputDirectory, routeDataWorker))
+        : false;
 
       return {
         urlPath: route.urlPath,
@@ -142,24 +187,68 @@ export const createWorkerManifest = async (
         workerExists: worker
           ? await fse.pathExists(path.join(outputDirectory, worker))
           : false,
+        ...(hasRouteDataWorker ? { routeDataWorker } : {}),
+        // Native workers apply configured route headers as the Node host does.
+        ...(route.responseHeaders && typeof route.responseHeaders === 'object'
+          ? { responseHeaders: route.responseHeaders }
+          : {}),
       };
     }),
   );
+  const rendererBuild = await readWorkerRendererBuild(
+    appContext.distDirectory,
+    routeSpec.routes,
+    deliveryUnitStamp,
+  );
+  const rendererIdentities = rendererBuild?.identities;
+  const nativeRenderer = await readNativeRendererWorkerResources(
+    appContext.distDirectory,
+    rendererBuild,
+  );
+  // Native-document renderers serve pages only through their native server
+  // handler. Fail deploy before emitting an entry that could only reject.
+  for (const route of routes) {
+    const renderer =
+      typeof route.entryName === 'string' &&
+      rendererIdentities &&
+      Object.hasOwn(rendererIdentities, route.entryName)
+        ? rendererIdentities[route.entryName].renderer
+        : undefined;
+    if (
+      renderer !== undefined &&
+      rendererBuild?.renderer.nativeDocuments &&
+      (nativeRenderer?.renderer !== renderer || !route.workerExists)
+    )
+      throw new Error(
+        `Cloudflare worker deploy of the ${renderer} renderer requires its native worker build for entry ${route.entryName}. Set deploy.worker.ssr: true and rebuild with the Cloudflare deploy target.`,
+      );
+  }
 
-  const bffPrefix = modernConfig.bff?.prefix;
-  const primaryBffPrefix = Array.isArray(bffPrefix) ? bffPrefix[0] : bffPrefix;
   const isEffectApi =
     Boolean(modernConfig.bff) && modernConfig.bff?.runtimeFramework !== 'hono';
+  const effectBffPrefix = getWorkerEffectBffPrefix(modernConfig);
   const effectApiWorkerExists = await fse.pathExists(
     path.join(outputDirectory, BFF_EFFECT_WORKER_ENTRY),
   );
+  const typedServiceBindings = createWorkerServiceBindings(
+    modernConfig,
+    undefined,
+  );
   const serviceBindings = createWorkerManifestServiceBindings(
-    createWorkerServiceBindings(modernConfig, undefined),
+    typedServiceBindings,
+    // The wrangler config checks VPC names against every Worker binding; the
+    // manifest only needs the framework-owned assets binding reserved.
+    createWorkerVpcServiceBindings(
+      modernConfig,
+      undefined,
+      typedServiceBindings,
+      new Set([ASSETS_BINDING]),
+    ),
   );
   const moduleFederation =
     await createModuleFederationWorkerManifest(outputDirectory);
 
-  if (isEffectApi && primaryBffPrefix && !effectApiWorkerExists) {
+  if (effectBffPrefix !== undefined && !effectApiWorkerExists) {
     throw createMissingEffectBffWorkerError(
       outputDirectory,
       BFF_EFFECT_WORKER_ENTRY,
@@ -199,13 +288,17 @@ export const createWorkerManifest = async (
     security: createCloudflareWorkerSecurityPolicy(modernConfig),
     ...(moduleFederation === undefined ? {} : { moduleFederation }),
     ...(deliveryUnitStamp ? { deliveryUnit: deliveryUnitStamp } : {}),
+    ...(rendererBuild
+      ? { renderer: rendererBuild.renderer, rendererIdentities }
+      : {}),
+    ...(nativeRenderer ? { nativeRenderer } : {}),
     i18n: createI18nWorkerManifest(routeSpec, appContext),
     bff:
-      isEffectApi && primaryBffPrefix && effectApiWorkerExists
+      effectBffPrefix !== undefined && effectApiWorkerExists
         ? {
             dispatcherExport: BFF_EFFECT_WORKER_DISPATCHER_EXPORT,
             runtimeFramework: 'effect',
-            prefix: primaryBffPrefix,
+            prefix: effectBffPrefix,
             worker: BFF_EFFECT_WORKER_ENTRY,
             effect: effectBffManifest,
           }
@@ -218,9 +311,14 @@ export const createWorkerModuleLoaders = (manifest: any) => {
   const imports = new Map<string, string>();
 
   for (const route of manifest.routeSpec.routes) {
-    if (route.worker && route.workerExists) {
-      const importPath = `../${String(route.worker).replace(/^\/+/u, '')}`;
-      imports.set(route.worker, `() => import(${JSON.stringify(importPath)})`);
+    for (const worker of [
+      route.workerExists ? route.worker : undefined,
+      route.routeDataWorker,
+    ]) {
+      if (worker) {
+        const importPath = `../${String(worker).replace(/^\/+/u, '')}`;
+        imports.set(worker, `() => import(${JSON.stringify(importPath)})`);
+      }
     }
   }
 

package/src/cloudflare/worker-options.ts

@@ -0,0 +1,60 @@
+import type { RequestHandlerOptions } from '@modern-js/server-core';
+
+/** The native context supplied to a Cloudflare module worker's fetch method. */
+export interface CloudflareExecutionContext {
+  waitUntil(promise: Promise<unknown>): void;
+  passThroughOnException(): void;
+}
+
+/** Worker request bindings follow the shared RequestPlatform kind/bindings shape. */
+export interface CloudflareWorkerPlatform<Bindings extends object = object> {
+  readonly kind: 'worker';
+  /** The original env object. Direct worker invocations may omit it. */
+  readonly bindings: Bindings | undefined;
+}
+
+/** Request-owned options for manifest HTML and Flight worker handlers. */
+export interface CloudflareWorkerRequestHandlerOptions<
+  Bindings extends object = object,
+> extends RequestHandlerOptions {
+  readonly platform: CloudflareWorkerPlatform<Bindings>;
+  /** The original context, including its native method receivers. */
+  readonly executionContext: CloudflareExecutionContext | undefined;
+}
+
+/** Narrow native handler options without replacing their worker references. */
+export function isCloudflareWorkerRequestHandlerOptions(
+  options: RequestHandlerOptions,
+): options is CloudflareWorkerRequestHandlerOptions {
+  if (!('platform' in options) || !('executionContext' in options))
+    return false;
+  const platform = options.platform;
+  if (
+    platform === null ||
+    typeof platform !== 'object' ||
+    !('kind' in platform) ||
+    platform.kind !== 'worker' ||
+    !('bindings' in platform)
+  ) {
+    return false;
+  }
+  const bindings = platform.bindings;
+  if (
+    bindings !== undefined &&
+    (bindings === null ||
+      typeof bindings !== 'object' ||
+      Array.isArray(bindings))
+  ) {
+    return false;
+  }
+  const context = options.executionContext;
+  return (
+    context === undefined ||
+    (context !== null &&
+      typeof context === 'object' &&
+      'waitUntil' in context &&
+      typeof context.waitUntil === 'function' &&
+      'passThroughOnException' in context &&
+      typeof context.passThroughOnException === 'function')
+  );
+}