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

package/src/release-envelope/renderer-output-stamp.ts

@@ -0,0 +1,210 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import {
+  assertUltramodernBuildArtifact,
+  formatBackendFederationValidationErrors,
+  stampUltramodernBuildArtifactIdentity,
+  ULTRAMODERN_BUILD_ARTIFACT_FILE,
+  ULTRAMODERN_BUILD_ARTIFACT_PATH,
+  type UltramodernBuildArtifact,
+  type UltramodernBuildUiSurface,
+  validateRendererIdentity,
+  validateRendererProfile,
+  validateRendererRouterBindings,
+} from '@modern-js/backend-federation-contracts';
+
+export type RendererBuildOutputContext = {
+  appDirectory: string;
+  distDirectory: string;
+  entrypoints: readonly { entryName: string; isMainEntry?: boolean }[];
+};
+
+export type FinalizedRendererBuildOutput = {
+  buildMarker: string;
+  sourceRevision: string;
+  ui: Pick<
+    UltramodernBuildUiSurface,
+    'rendererIdentity' | 'rendererProfile' | 'routerBindings'
+  >;
+};
+
+export type RendererBuildOutputOptions = {
+  resolveRendererBuild: (
+    context: RendererBuildOutputContext,
+  ) => Promise<FinalizedRendererBuildOutput>;
+  /** Exact metadata producer selected by the owning renderer composition. */
+  rendererBuildPlugin: string;
+};
+
+export const validateFinalizedRendererBuild = (
+  output: FinalizedRendererBuildOutput,
+  context: RendererBuildOutputContext,
+  appId: string,
+) => {
+  const entryNames = context.entrypoints.map(entry => entry.entryName);
+  const primary =
+    context.entrypoints.find(entry => entry.isMainEntry) ??
+    context.entrypoints[0];
+  const errors = [
+    ...validateRendererIdentity(output.ui.rendererIdentity).errors,
+    ...validateRendererProfile(output.ui.rendererProfile).errors,
+    ...validateRendererRouterBindings(
+      output.ui.routerBindings,
+      entryNames,
+      'routerBindings',
+    ).errors,
+  ];
+  if (errors.length)
+    throw new Error(formatBackendFederationValidationErrors(errors));
+  if (
+    !primary ||
+    new Set(entryNames).size !== entryNames.length ||
+    context.entrypoints.filter(entry => entry.isMainEntry).length > 1 ||
+    output.ui.rendererIdentity.entryName !== primary.entryName ||
+    output.ui.rendererIdentity.appId !== appId ||
+    output.ui.rendererIdentity.buildId !== output.buildMarker ||
+    output.ui.rendererIdentity.renderer !== output.ui.rendererProfile.renderer
+  )
+    throw new Error(
+      'Finalized renderer output conflicts with the actual application entries and release identity.',
+    );
+};
+
+export const stampFinalizedRendererBuildArtifact = (
+  artifact: UltramodernBuildArtifact,
+  output: FinalizedRendererBuildOutput,
+  context: RendererBuildOutputContext,
+) => {
+  assertUltramodernBuildArtifact(artifact);
+  const ui = artifact.surfaces.ui;
+  if (!ui)
+    throw new Error(
+      'Finalized renderer output requires a declared UI artifact',
+    );
+  validateFinalizedRendererBuild(output, context, artifact.deliveryUnit.appId);
+  const drifted = [
+    !isDeepStrictEqual(
+      { ...ui.rendererIdentity, buildId: output.ui.rendererIdentity.buildId },
+      output.ui.rendererIdentity,
+    ) &&
+      `rendererIdentity (captured entry ${ui.rendererIdentity.entryName}, built entry ${output.ui.rendererIdentity.entryName})`,
+    !isDeepStrictEqual(ui.rendererProfile, output.ui.rendererProfile) &&
+      'rendererProfile',
+    !isDeepStrictEqual(ui.routerBindings, output.ui.routerBindings) &&
+      `routerBindings (captured entries ${Object.keys(ui.routerBindings).join(', ')}, built entries ${Object.keys(output.ui.routerBindings).join(', ')})`,
+  ].filter(Boolean);
+  if (drifted.length)
+    throw new Error(
+      `Finalized renderer output conflicts with the captured application profile or router bindings: ${drifted.join('; ')} differ from ${ULTRAMODERN_BUILD_ARTIFACT_PATH}. After changing modern.config entries, renderer or router, recapture it with \`ultramodern-create ultramodern sync-delivery-unit\`.`,
+    );
+  const identity = {
+    buildMarker: output.buildMarker,
+    sourceRevision: output.sourceRevision,
+  };
+  const stamped = stampUltramodernBuildArtifactIdentity(artifact, identity);
+  return stampUltramodernBuildArtifactIdentity(
+    {
+      ...stamped,
+      surfaces: {
+        ...stamped.surfaces,
+        ui: { ...stamped.surfaces.ui!, ...output.ui },
+      },
+    },
+    identity,
+  );
+};
+
+async function writeOwnedArtifact(file: string, bytes: string) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  let created = false;
+  try {
+    const handle = await fs.open(temporary, 'wx');
+    created = true;
+    try {
+      await handle.writeFile(bytes);
+    } finally {
+      await handle.close();
+    }
+    await fs.rename(temporary, file);
+  } finally {
+    if (created) await fs.rm(temporary, { force: true });
+  }
+}
+
+export async function emitRendererBuildArtifact(
+  context: RendererBuildOutputContext,
+  options: RendererBuildOutputOptions,
+) {
+  const source = path.join(
+    context.appDirectory,
+    ULTRAMODERN_BUILD_ARTIFACT_PATH,
+  );
+  const bytes = await fs.readFile(source).catch(error => {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  });
+  if (!bytes) {
+    const declaration = await fs
+      .stat(source.replace(/\.json$/u, '.ts'))
+      .catch(error => {
+        if (error.code === 'ENOENT') return undefined;
+        throw error;
+      });
+    if (declaration)
+      throw new Error(
+        'Generated UI artifact declaration is missing its build carrier',
+      );
+    return undefined;
+  }
+  const artifact: unknown = JSON.parse(bytes.toString('utf8'));
+  assertUltramodernBuildArtifact(artifact);
+  const finalized = await options.resolveRendererBuild(context);
+  const stamped = stampFinalizedRendererBuildArtifact(
+    artifact,
+    finalized,
+    context,
+  );
+  const serialized = `${JSON.stringify(stamped, null, 2)}\n`;
+  for (const directory of [
+    context.distDirectory,
+    path.join(context.distDirectory, 'public'),
+  ])
+    await writeOwnedArtifact(
+      path.join(directory, ULTRAMODERN_BUILD_ARTIFACT_FILE),
+      serialized,
+    );
+  return stamped;
+}
+
+/** Stamp generated UI carriers after their actual compiler manifest is committed. */
+export function rendererBuildArtifactStampPlugin(
+  options: RendererBuildOutputOptions,
+) {
+  if (
+    typeof options.rendererBuildPlugin !== 'string' ||
+    !options.rendererBuildPlugin ||
+    options.rendererBuildPlugin.trim() !== options.rendererBuildPlugin ||
+    typeof options.resolveRendererBuild !== 'function'
+  )
+    throw new Error(
+      'Renderer artifact stamping requires its owning metadata producer',
+    );
+  return {
+    name: '@modern-js/renderer-build-artifact-stamp',
+    pre: [options.rendererBuildPlugin],
+    required: [options.rendererBuildPlugin],
+    setup(api: {
+      getAppContext(): RendererBuildOutputContext & { apiOnly?: boolean };
+      onAfterBuild(handler: () => Promise<void>): void;
+    }) {
+      api.onAfterBuild(async () => {
+        const context = api.getAppContext();
+        if (context.apiOnly) return;
+        await emitRendererBuildArtifact(context, options);
+      });
+    },
+  };
+}

package/src/release-envelope/types.ts

@@ -1,7 +1,24 @@
-export const MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION = 3 as const;
+import type {
+  RendererIdentity,
+  RendererProfile,
+  RendererRouterBindings,
+} from '@modern-js/backend-federation-contracts';
 
-export const MICROVERTICAL_RELEASE_ENVELOPE_KIND =
-  'ultramodern-target-microvertical-release-envelope' as const;
+import {
+  MICROVERTICAL_RELEASE_ENVELOPE_KIND,
+  MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION,
+  SHELL_RELEASE_ENVELOPE_KIND,
+} from './contract.mjs';
+
+export {
+  MICROVERTICAL_RELEASE_ENVELOPE_KIND,
+  MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION,
+  SHELL_RELEASE_ENVELOPE_KIND,
+};
+
+export type ReleaseEnvelopeKind =
+  | typeof MICROVERTICAL_RELEASE_ENVELOPE_KIND
+  | typeof SHELL_RELEASE_ENVELOPE_KIND;
 
 export const MICROVERTICAL_RELEASE_TARGETS = ['node', 'cloudflare'] as const;
 
@@ -48,17 +65,35 @@ export type MicroVerticalReleaseSurfaces = {
   uiClient: string[];
   ssr: string[];
   apiBackend: string[];
-  backendFederation: {
+  backendFederation?: {
     manifest: string;
     container: string;
   };
 };
 
+export type MicroVerticalReleaseUi = {
+  rendererIdentity: RendererIdentity;
+  rendererProfile: RendererProfile;
+  routerBindings: RendererRouterBindings;
+};
+
+/** A Shell consumes remotes; it never publishes a backend federation pair. */
+export type ShellReleaseSurfaces = {
+  uiClient: string[];
+  ssr: string[];
+  apiBackend: string[];
+};
+
+export type ReleaseSurfaces =
+  | MicroVerticalReleaseSurfaces
+  | ShellReleaseSurfaces;
+
 export type MicroVerticalReleaseEnvelopePayload = {
   schemaVersion: typeof MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION;
   kind: typeof MICROVERTICAL_RELEASE_ENVELOPE_KIND;
   target: MicroVerticalReleaseTarget;
   identity: MicroVerticalReleaseIdentity;
+  ui?: MicroVerticalReleaseUi;
   artifacts: MicroVerticalReleaseArtifact[];
   surfaces: MicroVerticalReleaseSurfaces;
 };
@@ -68,16 +103,50 @@ export type MicroVerticalReleaseEnvelope =
     envelopeDigest: string;
   };
 
+export type ShellReleaseEnvelopePayload = {
+  schemaVersion: typeof MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION;
+  kind: typeof SHELL_RELEASE_ENVELOPE_KIND;
+  target: MicroVerticalReleaseTarget;
+  identity: MicroVerticalReleaseIdentity;
+  ui?: MicroVerticalReleaseUi;
+  artifacts: MicroVerticalReleaseArtifact[];
+  surfaces: ShellReleaseSurfaces;
+};
+
+export type ShellReleaseEnvelope = ShellReleaseEnvelopePayload & {
+  envelopeDigest: string;
+};
+
+export type ReleaseEnvelopePayload =
+  | MicroVerticalReleaseEnvelopePayload
+  | ShellReleaseEnvelopePayload;
+
+export type ReleaseEnvelope =
+  | MicroVerticalReleaseEnvelope
+  | ShellReleaseEnvelope;
+
 export type CreateMicroVerticalReleaseEnvelopeInput = {
   artifactRoot: string;
   target: MicroVerticalReleaseTarget;
   identity: MicroVerticalReleaseIdentity;
+  ui?: MicroVerticalReleaseUi;
   artifacts: MicroVerticalReleaseArtifactInput[];
-  surfaces: MicroVerticalReleaseSurfaces;
-};
+} & (
+  | {
+      kind?: typeof MICROVERTICAL_RELEASE_ENVELOPE_KIND;
+      surfaces: MicroVerticalReleaseSurfaces;
+    }
+  | {
+      kind: typeof SHELL_RELEASE_ENVELOPE_KIND;
+      surfaces: ShellReleaseSurfaces;
+    }
+);
 
 export type VerifyMicroVerticalReleaseEnvelopeOptions = {
   artifactRoot: string;
   logicalPathForArtifact?: (artifact: MicroVerticalReleaseArtifact) => string;
   expectedTarget?: MicroVerticalReleaseTarget;
+  expectedKind?: ReleaseEnvelopeKind;
+  expectedRendererIdentity?: RendererIdentity;
+  expectedRendererProfile?: RendererProfile;
 };

package/src/release-identity.ts

@@ -1,6 +1,9 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 
+// The framework initializes this fixed reader before authored config observation.
+// Its commands remain private; authored subprocess APIs keep their own guards.
+const invokeGit = execFileSync;
 const BUILD_MARKER_NAMESPACE =
   'ultramodern-delivery-unit-release-build-marker:v1';
 const PROMOTABLE_SOURCE_REVISION_PATTERN = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
@@ -10,14 +13,24 @@ export type UltramodernReleaseIdentity = {
   sourceRevision: string;
 };
 
+// Inherited GIT_* variables (git hooks export GIT_DIR and GIT_INDEX_FILE)
+// would make git describe some other repository than `workspaceRoot`.
+const workspaceGitEnv = (): NodeJS.ProcessEnv =>
+  Object.fromEntries(
+    Object.entries(process.env).filter(
+      ([name]) => !name.toUpperCase().startsWith('GIT_'),
+    ),
+  );
+
 const gitOutput = (
   workspaceRoot: string,
   args: string[],
 ): string | undefined => {
   try {
-    return execFileSync('git', args, {
+    return invokeGit('git', args, {
       cwd: workspaceRoot,
       encoding: 'utf8',
+      env: workspaceGitEnv(),
       stdio: ['ignore', 'pipe', 'ignore'],
     }).trim();
   } catch {
@@ -44,10 +57,11 @@ export const createUltramodernReleaseBuildMarker = ({
 export const resolveUltramodernSourceRevision = (
   workspaceRoot = process.cwd(),
   configuredSourceRevision?: string,
+  environment: Readonly<NodeJS.ProcessEnv> = process.env,
 ): string => {
   const configuredArgumentValue = configuredSourceRevision?.trim();
   const configuredEnvironmentValue =
-    process.env.ULTRAMODERN_SOURCE_REVISION?.trim();
+    environment.ULTRAMODERN_SOURCE_REVISION?.trim();
   const configuredArgument =
     configuredArgumentValue && configuredArgumentValue !== 'workspace'
       ? configuredArgumentValue
@@ -110,16 +124,19 @@ export const resolveUltramodernReleaseIdentity = ({
   sourceRevision: configuredSourceRevision,
   unitId,
   workspaceRoot,
+  environment,
 }: {
   generationBuildMarker: string;
   sourceRevision?: string;
   unitId: string;
   workspaceRoot?: string;
+  environment?: Readonly<NodeJS.ProcessEnv>;
 }): UltramodernReleaseIdentity => {
   const explicitSourceRevision = configuredSourceRevision?.trim();
   const sourceRevision = resolveUltramodernSourceRevision(
     workspaceRoot,
     explicitSourceRevision,
+    environment,
   );
   return {
     buildMarker:

package/src/renderer-build-identity.ts

@@ -0,0 +1,168 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  immutableRendererRouterBindings,
+  type RendererIdentity,
+  type RendererName,
+  type RendererProfile,
+  type RendererRouterBindings,
+  type RouterFramework,
+  validateRendererProfile,
+  validateRendererRouterBindings,
+} from '@modern-js/backend-federation-contracts';
+import { resolveUltramodernSourceRevision } from './release-identity';
+
+export type RendererProfileKeyInput = RendererProfile & {
+  readonly dependencies?: Readonly<Record<string, string>>;
+};
+
+export interface RendererBuildIdentityOptions {
+  projectRoot: string;
+  renderer: RendererName;
+  profile: RendererProfileKeyInput;
+  entryNames: readonly string[];
+  mode: 'development' | 'production';
+  /** Delivery-unit app id; defaults to the application package name. */
+  appId?: string;
+  /** Externally authenticated source revision (delivery unit or CI). */
+  sourceRevision?: string;
+  /** Actual final entry ownership, supplied by the selected renderer composition. */
+  routerBindings: RendererRouterBindings;
+  /** Admitted router frameworks, supplied by the selected renderer owner. */
+  routerFrameworks?: readonly RouterFramework[];
+}
+
+export interface RendererBuildIdentities {
+  readonly identities: Readonly<Record<string, RendererIdentity>>;
+  readonly buildId: string;
+  readonly profileKey: string;
+  readonly sourceRevision: string;
+  readonly routerBindings: RendererRouterBindings;
+}
+
+const LOCKFILES = [
+  'pnpm-lock.yaml',
+  'package-lock.json',
+  'yarn.lock',
+  'bun.lock',
+  'bun.lockb',
+];
+
+/** Stable per process: one dev session or dirty build keeps one buildId. */
+const processNonce = randomUUID();
+
+const sha256 = (value: string | Uint8Array) =>
+  createHash('sha256').update(value).digest('hex');
+
+/** Renderer, protocol and installed renderer/framework/compiler versions. */
+export function rendererProfileKey(profile: RendererProfileKeyInput): string {
+  return sha256(
+    JSON.stringify([
+      profile.renderer,
+      profile.protocolVersion,
+      profile.compiler,
+      profile.hydration,
+      profile.router,
+      Object.entries(profile.dependencies ?? {}).sort(([left], [right]) =>
+        left < right ? -1 : left > right ? 1 : 0,
+      ),
+    ]),
+  );
+}
+
+/** Hash of the nearest lockfile, or an empty marker when there is none. */
+function lockfileHash(projectRoot: string): string {
+  let directory = path.resolve(projectRoot);
+  for (;;) {
+    for (const name of LOCKFILES) {
+      try {
+        return sha256(fs.readFileSync(path.join(directory, name)));
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      }
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return '';
+    directory = parent;
+  }
+}
+
+/** Resolve once per build before emitting entries; never rehashes sources. */
+export function resolveRendererBuildIdentities(
+  options: RendererBuildIdentityOptions,
+): RendererBuildIdentities {
+  const profile: RendererProfile = {
+    renderer: options.profile.renderer,
+    protocolVersion: options.profile.protocolVersion,
+    compiler: options.profile.compiler,
+    hydration: options.profile.hydration,
+    router: options.profile.router,
+  };
+  const validation = validateRendererProfile(profile);
+  if (!validation.ok || options.renderer !== profile.renderer)
+    throw new Error(
+      `Renderer/profile identity mismatch: ${JSON.stringify(validation.errors)}.`,
+    );
+  const entries = [...options.entryNames].sort();
+  if (
+    entries.length === 0 ||
+    new Set(entries).size !== entries.length ||
+    entries.some(value => !value || value === '__proto__')
+  )
+    throw new Error(
+      'Renderer build identity requires unique nonempty entry names.',
+    );
+  const routerValidation = validateRendererRouterBindings(
+    options.routerBindings,
+    entries,
+    'routerBindings',
+    options.routerFrameworks,
+  );
+  if (!routerValidation.ok)
+    throw new Error(
+      `Invalid renderer router bindings: ${JSON.stringify(routerValidation.errors)}.`,
+    );
+  const projectRoot = path.resolve(options.projectRoot);
+  const appId =
+    options.appId ??
+    JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'))
+      .name;
+  if (typeof appId !== 'string' || !appId || appId.trim() !== appId)
+    throw new Error(
+      'Renderer application identity requires a delivery artifact appId or a package name.',
+    );
+  const profileKey = rendererProfileKey(options.profile);
+  const sourceRevision = resolveUltramodernSourceRevision(
+    projectRoot,
+    options.sourceRevision,
+  );
+  const buildId = sha256(
+    JSON.stringify([
+      profileKey,
+      lockfileHash(projectRoot),
+      options.mode === 'development' || sourceRevision === 'workspace'
+        ? processNonce
+        : sourceRevision,
+    ]),
+  );
+  const identities = Object.fromEntries(
+    entries.map(entryName => [
+      entryName,
+      Object.freeze({
+        renderer: options.renderer,
+        appId,
+        entryName,
+        protocolVersion: 1 as const,
+        buildId,
+      }),
+    ]),
+  );
+  return Object.freeze({
+    identities: Object.freeze(identities),
+    buildId,
+    profileKey,
+    sourceRevision,
+    routerBindings: immutableRendererRouterBindings(options.routerBindings),
+  });
+}

package/src/templates/cloudflare-entry.001-bootstrap-security.mjs

@@ -3,8 +3,12 @@ const MODERN_WORKER_MANIFEST = p_workerManifest;
 export const modernWorkerManifest = MODERN_WORKER_MANIFEST;
 const WORKER_MODULE_LOADERS = p_workerModuleLoaders;
 const workerModulePromises = new Map();
-const effectBffDispatcherPromises = new Map();
-const remoteJsonPromises = new Map();
+// workerd forbids awaiting I/O (a `fetch()` Promise) that was started by a
+// different request's execution context. This worker isolate outlives any
+// single request, so this map may only ever hold settled, plain JSON values
+// — never a live fetch Promise shared across requests. In-flight dedupe is
+// instead scoped per request; see `createRemoteJsonFetchScope`.
+const remoteJsonCache = new Map();
 const CORS_POLICY = MODERN_WORKER_MANIFEST.security?.cors || {};
 const ASSET_CORS_ENABLED = CORS_POLICY.assets !== false;
 const APP_CORS_ALLOWED_ORIGINS = (CORS_POLICY.allowedOrigins || []).map(
@@ -24,9 +28,6 @@ const ASSET_CORS_HEADERS = {
   'access-control-allow-origin': '*',
 };
 
-globalThis.__dirname ??= '/';
-globalThis.__filename ??= '/index.js';
-
 function getAllowedAppCorsOrigin(request) {
   if (APP_CORS_ALLOWED_ORIGINS.length === 0) {
     return null;
@@ -226,7 +227,11 @@ function withCloudflareSecurityHeaders(response, request) {
 }
 
 function createRenderableRequest(request) {
-  if (request.method !== 'HEAD') {
+  if (
+    request.method !== 'HEAD' ||
+    request.headers.get('x-rsc-action') ||
+    request.headers.get('x-rsc-tree')
+  ) {
     return request;
   }
 
@@ -242,6 +247,9 @@ function finalizeResponseForRequest(response, request) {
 
   const headers = new Headers(securedResponse.headers);
   headers.delete('content-length');
+  // A HEAD response sends no body, so release the producer's stream instead of abandoning it:
+  // a stream nobody reads never finishes, and whatever waits for its end never runs.
+  securedResponse.body?.cancel().catch(() => undefined);
 
   return new Response(null, {
     headers,

package/src/templates/cloudflare-entry.002-assets-routes.mjs

@@ -20,7 +20,7 @@ function withAssetHeaders(response, request) {
   });
 }
 
-async function createCorsPreflightResponse(request, env) {
+async function createCorsPreflightResponse(request, _env) {
   if (request.method !== 'OPTIONS') {
     return null;
   }
@@ -71,7 +71,15 @@ async function fetchAssetByPath(pathname, request, env) {
   const url = new URL(request.url);
   url.pathname = `/${pathname.replace(/^\/+/u, '')}`;
 
-  return fetchAsset(new Request(url, request), env);
+  return fetchAsset(
+    new Request(url, {
+      method: 'GET',
+      headers: request.headers,
+      redirect: request.redirect,
+      signal: request.signal,
+    }),
+    env,
+  );
 }
 
 async function fetchAssetByPathFollowingRedirects(