@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.4 → 3.9.0-ultramodern.6

package/src/backend-federation-build/config.ts

@@ -0,0 +1,356 @@
+import { existsSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { resolveUltramodernSourceRevision } from '@modern-js/app-tools-extensions/release-identity';
+import {
+  BACKEND_FEDERATION_MANIFEST_FILE as BACKEND_MANIFEST_FILE,
+  BACKEND_FEDERATION_REMOTE_ENTRY_FILE as BACKEND_REMOTE_ENTRY_FILE,
+  DELIVERY_UNIT_DEPLOY_PROFILE,
+  DELIVERY_UNIT_KIND,
+  DELIVERY_UNIT_SCHEMA_VERSION,
+  type DeliveryUnitContractBlock,
+  type DeliveryUnitRecord,
+  deliveryUnitContractBlock,
+  isUltramodernBuildArtifact,
+  ULTRAMODERN_BUILD_ARTIFACT_PATH,
+  type UltramodernBuildArtifact,
+  validateDeliveryUnitRecord,
+  validateUltramodernBuildArtifact,
+} from '@modern-js/backend-federation-contracts';
+
+export const COMPACT_CONFIG_PATH = '.modernjs/ultramodern.json';
+
+export type CompactApp = {
+  id?: unknown;
+  kind?: unknown;
+  path?: unknown;
+  package?: unknown;
+  port?: unknown;
+  api?: {
+    prefix?: unknown;
+    stem?: unknown;
+  };
+  moduleFederation?: {
+    name?: unknown;
+    manifestUrl?: unknown;
+  };
+  backendFederation?: {
+    name?: unknown;
+    versionBoundary?: {
+      ui?: {
+        manifestUrl?: unknown;
+      };
+    };
+    executionSurfaces?: {
+      node?: {
+        remoteName?: unknown;
+        manifestUrl?: unknown;
+        containerEntry?: unknown;
+        remoteType?: unknown;
+      };
+    };
+  };
+  deliveryUnit?: {
+    unitId?: unknown;
+    buildMarker?: unknown;
+    sourceRevision?: unknown;
+    packageName?: unknown;
+    version?: unknown;
+  };
+  serverExecution?: {
+    node?: {
+      remoteName?: unknown;
+      manifestUrl?: unknown;
+      containerEntry?: unknown;
+      remoteType?: unknown;
+    };
+  };
+};
+
+export type CompactConfig = {
+  topology?: {
+    apps?: CompactApp[];
+  };
+};
+
+export type BackendFederationApp = {
+  id: string;
+  directory: string;
+  packageName?: string;
+  version?: string;
+  buildVersion?: string;
+  unitId?: string;
+  sourceRevision?: string;
+  deliveryUnit?: DeliveryUnitContractBlock;
+  port: number;
+  apiPrefix: string;
+  apiStem: string;
+  backendName: string;
+  manifestUrl: string;
+  containerEntry: string;
+  remoteType: string;
+  uiManifestUrl?: string;
+  compactDeliveryUnit?: {
+    unitId?: string;
+    buildMarker?: string;
+    sourceRevision?: string;
+    packageName?: string;
+    version?: string;
+  };
+};
+
+export type BackendFederationBuildIdentity = {
+  appId?: string;
+  packageName?: string;
+  version?: string;
+  buildVersion?: string;
+  unitId?: string;
+  sourceRevision?: string;
+  artifact?: UltramodernBuildArtifact;
+};
+
+export const normalizeRelativePath = (value: string) =>
+  value.replace(/\\/gu, '/').replace(/^\.\/+/u, '');
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const readJsonFile = async <T>(filePath: string): Promise<T> =>
+  JSON.parse(await fs.readFile(filePath, 'utf8')) as T;
+
+export const buildArtifactPathFor = (appDirectory: string) =>
+  path.join(appDirectory, ULTRAMODERN_BUILD_ARTIFACT_PATH);
+
+export const readBuildIdentity = async (
+  appDirectory: string,
+): Promise<BackendFederationBuildIdentity> => {
+  const buildArtifactPath = buildArtifactPathFor(appDirectory);
+  if (existsSync(buildArtifactPath)) {
+    const artifact = await readJsonFile<unknown>(buildArtifactPath);
+    const artifactValidation = validateUltramodernBuildArtifact(
+      artifact,
+      buildArtifactPath,
+    );
+    if (!artifactValidation.ok) {
+      throw new Error(
+        `[backend-federation-build] Invalid delivery-unit build artifact at ${buildArtifactPath}.`,
+      );
+    }
+    if (!isUltramodernBuildArtifact(artifact)) {
+      throw new Error(
+        `[backend-federation-build] Invalid delivery-unit build artifact at ${buildArtifactPath}.`,
+      );
+    }
+
+    const deliveryUnit = artifact.deliveryUnit;
+    return {
+      artifact,
+      appId: deliveryUnit.appId,
+      buildVersion: deliveryUnit.buildMarker,
+      packageName: deliveryUnit.packageName,
+      version: deliveryUnit.version,
+      unitId: deliveryUnit.unitId,
+      sourceRevision: deliveryUnit.sourceRevision,
+    };
+  }
+
+  throw new Error(
+    `[backend-federation-build] Missing delivery-unit build artifact at ${buildArtifactPath}.`,
+  );
+};
+
+const toPascalCase = (value: string) =>
+  value
+    .split(/[^a-zA-Z0-9]+/u)
+    .filter(Boolean)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+
+const stringValue = (value: unknown) =>
+  typeof value === 'string' && value.length > 0 ? value : undefined;
+
+const createBackendName = (app: CompactApp, id: string) => {
+  const configuredName =
+    stringValue(app.backendFederation?.name) ??
+    stringValue(app.backendFederation?.executionSurfaces?.node?.remoteName) ??
+    stringValue(app.serverExecution?.node?.remoteName);
+
+  if (configuredName) {
+    return configuredName;
+  }
+
+  const mfName = stringValue(app.moduleFederation?.name);
+  return mfName ? `${mfName}Backend` : `vertical${toPascalCase(id)}Backend`;
+};
+
+export const findWorkspaceRoot = (appDirectory: string) => {
+  let current = appDirectory;
+
+  while (true) {
+    if (existsSync(path.join(current, COMPACT_CONFIG_PATH))) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return undefined;
+    }
+    current = parent;
+  }
+};
+
+export const resolveWorkspaceSourceRevision = async (workspaceRoot: string) => {
+  return resolveUltramodernSourceRevision(workspaceRoot);
+};
+
+export const createStampedDeliveryUnit = (input: {
+  appId: string;
+  unitId?: string;
+  buildMarker?: string;
+  packageName?: string;
+  version?: string;
+  sourceRevision: string;
+}): DeliveryUnitContractBlock | undefined => {
+  if (
+    !input.unitId ||
+    !input.buildMarker ||
+    !input.packageName ||
+    !input.version
+  ) {
+    return undefined;
+  }
+
+  const record = {
+    schemaVersion: DELIVERY_UNIT_SCHEMA_VERSION,
+    kind: DELIVERY_UNIT_KIND,
+    appId: input.appId,
+    unitId: input.unitId,
+    packageName: input.packageName,
+    version: input.version,
+    buildMarker: input.buildMarker,
+    sourceRevision: input.sourceRevision,
+    deployProfile: DELIVERY_UNIT_DEPLOY_PROFILE,
+  };
+  const validation = validateDeliveryUnitRecord(record);
+
+  if (!validation.ok) {
+    return undefined;
+  }
+
+  return deliveryUnitContractBlock(record as DeliveryUnitRecord);
+};
+
+export const createAppFromCompactMetadata = (
+  workspaceRoot: string,
+  appDirectory: string,
+  compactApp: CompactApp,
+): BackendFederationApp | undefined => {
+  const id = stringValue(compactApp.id);
+  const appPath = stringValue(compactApp.path);
+
+  if (!id || compactApp.kind !== 'vertical' || !isRecord(compactApp.api)) {
+    return undefined;
+  }
+
+  const directory = appPath
+    ? normalizeRelativePath(appPath)
+    : `verticals/${id}`;
+  if (path.resolve(workspaceRoot, directory) !== path.resolve(appDirectory)) {
+    return undefined;
+  }
+
+  const port =
+    typeof compactApp.port === 'number' ? compactApp.port : undefined;
+  if (port === undefined) {
+    return undefined;
+  }
+
+  const apiPrefix = stringValue(compactApp.api.prefix) ?? `/${id}-api`;
+  const apiStem = stringValue(compactApp.api.stem) ?? id;
+  const backendName = createBackendName(compactApp, id);
+  const manifestUrl =
+    stringValue(
+      compactApp.backendFederation?.executionSurfaces?.node?.manifestUrl,
+    ) ??
+    stringValue(compactApp.serverExecution?.node?.manifestUrl) ??
+    `http://localhost:${port}/${BACKEND_MANIFEST_FILE}`;
+  const containerEntry =
+    stringValue(
+      compactApp.backendFederation?.executionSurfaces?.node?.containerEntry,
+    ) ??
+    stringValue(compactApp.serverExecution?.node?.containerEntry) ??
+    `http://localhost:${port}/${BACKEND_REMOTE_ENTRY_FILE}`;
+  const configuredRemoteType =
+    stringValue(
+      compactApp.backendFederation?.executionSurfaces?.node?.remoteType,
+    ) ?? stringValue(compactApp.serverExecution?.node?.remoteType);
+  if (
+    configuredRemoteType !== undefined &&
+    configuredRemoteType !== 'commonjs-module'
+  ) {
+    throw new Error(
+      `[backend-federation-build] Node backend federation remoteType must be "commonjs-module"; received "${configuredRemoteType}" for ${id}.`,
+    );
+  }
+  if (
+    !new URL(containerEntry).pathname.endsWith(`/${BACKEND_REMOTE_ENTRY_FILE}`)
+  ) {
+    throw new Error(
+      `[backend-federation-build] Node backend federation containerEntry must end with "/${BACKEND_REMOTE_ENTRY_FILE}"; received "${containerEntry}" for ${id}.`,
+    );
+  }
+  const remoteType = 'commonjs-module';
+  const packageName = stringValue(compactApp.package);
+  const uiManifestUrl =
+    stringValue(
+      compactApp.backendFederation?.versionBoundary?.ui?.manifestUrl,
+    ) ?? stringValue(compactApp.moduleFederation?.manifestUrl);
+  const compactDeliveryUnit = isRecord(compactApp.deliveryUnit)
+    ? {
+        unitId: stringValue(compactApp.deliveryUnit.unitId),
+        buildMarker: stringValue(compactApp.deliveryUnit.buildMarker),
+        sourceRevision: stringValue(compactApp.deliveryUnit.sourceRevision),
+        packageName: stringValue(compactApp.deliveryUnit.packageName),
+        version: stringValue(compactApp.deliveryUnit.version),
+      }
+    : undefined;
+
+  return {
+    id,
+    directory,
+    packageName,
+    port,
+    apiPrefix,
+    apiStem,
+    backendName,
+    manifestUrl,
+    containerEntry,
+    remoteType,
+    uiManifestUrl,
+    compactDeliveryUnit,
+  };
+};
+
+export const findBackendFederationApp = async (
+  workspaceRoot: string,
+  appDirectory: string,
+) => {
+  const compactConfigPath = path.join(workspaceRoot, COMPACT_CONFIG_PATH);
+  const compactConfig = await readJsonFile<CompactConfig>(compactConfigPath);
+  const apps = Array.isArray(compactConfig.topology?.apps)
+    ? compactConfig.topology.apps
+    : [];
+
+  for (const app of apps) {
+    const resolved = createAppFromCompactMetadata(
+      workspaceRoot,
+      appDirectory,
+      app,
+    );
+    if (resolved) {
+      return resolved;
+    }
+  }
+
+  return undefined;
+};

package/src/backend-federation-build/emit.ts

@@ -0,0 +1,202 @@
+import { existsSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { resolveUltramodernReleaseIdentity } from '@modern-js/app-tools-extensions/release-identity';
+import {
+  BACKEND_FEDERATION_MANIFEST_FILE as BACKEND_MANIFEST_FILE,
+  BACKEND_FEDERATION_REMOTE_ENTRY_FILE as BACKEND_REMOTE_ENTRY_FILE,
+  stampUltramodernBuildArtifactIdentity,
+  ULTRAMODERN_BUILD_ARTIFACT_FILE,
+} from '@modern-js/backend-federation-contracts';
+import { createBackendFederationEntryIntegrity } from '@modern-js/server-runtime-extensions/backend-federation-security/node';
+import {
+  createBackendManifest,
+  createBackendRemoteEntrySource,
+} from './codegen';
+import {
+  type BackendFederationApp,
+  buildArtifactPathFor,
+  COMPACT_CONFIG_PATH,
+  createStampedDeliveryUnit,
+  findBackendFederationApp,
+  findWorkspaceRoot,
+  readBuildIdentity,
+  resolveWorkspaceSourceRevision,
+} from './config';
+
+export type { BackendFederationBuildIdentity } from './config';
+
+export type BackendFederationArtifactResult = {
+  appId: string;
+  manifestPath: string;
+  containerPath: string;
+  deliveryUnitArtifactPath?: string;
+  remoteName: string;
+  remoteType: string;
+};
+
+export const emitBackendFederationArtifacts = async (
+  appDirectory: string,
+  distDirectory: string,
+): Promise<BackendFederationArtifactResult | undefined> => {
+  const workspaceRoot = findWorkspaceRoot(appDirectory);
+  if (!workspaceRoot) {
+    return undefined;
+  }
+
+  const effectApiPath = path.join(appDirectory, 'api/effect-api.ts');
+  const backendFederationConfigPath = path.join(
+    appDirectory,
+    'backend-federation.config.ts',
+  );
+  if (!existsSync(effectApiPath) || !existsSync(backendFederationConfigPath)) {
+    return undefined;
+  }
+
+  const app = await findBackendFederationApp(workspaceRoot, appDirectory);
+  if (!app) {
+    return undefined;
+  }
+  const buildIdentity = await readBuildIdentity(appDirectory);
+  const compactDeliveryUnit = app.compactDeliveryUnit;
+  const hasCompactDeliveryUnit =
+    compactDeliveryUnit !== undefined &&
+    (compactDeliveryUnit.unitId !== undefined ||
+      compactDeliveryUnit.buildMarker !== undefined ||
+      compactDeliveryUnit.packageName !== undefined ||
+      compactDeliveryUnit.version !== undefined);
+  const hasBuildIdentity =
+    buildIdentity.unitId !== undefined ||
+    buildIdentity.buildVersion !== undefined ||
+    buildIdentity.packageName !== undefined ||
+    buildIdentity.version !== undefined;
+
+  if (hasBuildIdentity) {
+    const compactConfigPath = path.join(workspaceRoot, COMPACT_CONFIG_PATH);
+    const buildIdentityPath = buildArtifactPathFor(appDirectory);
+    const mismatches: string[] = [];
+    const compare = (
+      label: string,
+      a?: string,
+      b?: string,
+      leftLabel = 'deliveryUnit',
+    ) => {
+      if (a !== undefined && b !== undefined && a !== b) {
+        mismatches.push(
+          `${label}: ${leftLabel}=${a} vs ultramodern-build=${b}`,
+        );
+      }
+    };
+    compare('appId', app.id, buildIdentity.appId, 'topology');
+
+    if (hasCompactDeliveryUnit) {
+      compare('unitId', compactDeliveryUnit?.unitId, buildIdentity.unitId);
+      compare(
+        'buildMarker/build',
+        compactDeliveryUnit?.buildMarker,
+        buildIdentity.buildVersion,
+      );
+      compare(
+        'packageName',
+        compactDeliveryUnit?.packageName,
+        buildIdentity.packageName,
+      );
+      compare('version', compactDeliveryUnit?.version, buildIdentity.version);
+    }
+
+    if (mismatches.length > 0) {
+      throw new Error(
+        `[backend-federation-build] Delivery-unit identity drift between ${compactConfigPath} (topology) and ${buildIdentityPath}: ${mismatches.join('; ')}`,
+      );
+    }
+  }
+
+  const unitId = compactDeliveryUnit?.unitId ?? buildIdentity.unitId;
+  const generationBuildMarker =
+    compactDeliveryUnit?.buildMarker ?? buildIdentity.buildVersion;
+  const sourceRevision = await resolveWorkspaceSourceRevision(workspaceRoot);
+  const buildVersion =
+    generationBuildMarker && unitId
+      ? resolveUltramodernReleaseIdentity({
+          generationBuildMarker,
+          unitId,
+          workspaceRoot,
+        }).buildMarker
+      : undefined;
+  const packageName =
+    compactDeliveryUnit?.packageName ??
+    buildIdentity.packageName ??
+    app.packageName;
+  const version = compactDeliveryUnit?.version ?? buildIdentity.version;
+  const deliveryUnit = createStampedDeliveryUnit({
+    appId: app.id,
+    unitId,
+    buildMarker: buildVersion,
+    packageName,
+    version,
+    sourceRevision,
+  });
+  const stampedBuildArtifact = buildIdentity.artifact
+    ? stampUltramodernBuildArtifactIdentity(buildIdentity.artifact, {
+        buildMarker:
+          buildVersion ?? buildIdentity.artifact.deliveryUnit.buildMarker,
+        sourceRevision,
+      })
+    : undefined;
+
+  const resolvedApp: BackendFederationApp = {
+    ...app,
+    packageName,
+    version,
+    buildVersion,
+    unitId,
+    sourceRevision,
+    deliveryUnit,
+  };
+
+  const manifestPath = path.join(distDirectory, BACKEND_MANIFEST_FILE);
+  const entryPath = path.join(distDirectory, BACKEND_REMOTE_ENTRY_FILE);
+  const deliveryUnitArtifactPath = stampedBuildArtifact
+    ? path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE)
+    : undefined;
+  const entrySource = await createBackendRemoteEntrySource(
+    workspaceRoot,
+    resolvedApp,
+    effectApiPath,
+    entryPath,
+  );
+  await fs.mkdir(distDirectory, { recursive: true });
+  await fs.writeFile(entryPath, entrySource);
+  await fs.writeFile(
+    manifestPath,
+    `${JSON.stringify(createBackendManifest(workspaceRoot, distDirectory, resolvedApp, createBackendFederationEntryIntegrity(entrySource)), null, 2)}\n`,
+  );
+  if (stampedBuildArtifact && deliveryUnitArtifactPath) {
+    await fs.writeFile(
+      deliveryUnitArtifactPath,
+      `${JSON.stringify(stampedBuildArtifact, null, 2)}\n`,
+    );
+  }
+
+  return {
+    appId: resolvedApp.id,
+    manifestPath,
+    containerPath: entryPath,
+    ...(deliveryUnitArtifactPath ? { deliveryUnitArtifactPath } : {}),
+    remoteName: resolvedApp.backendName,
+    remoteType: resolvedApp.remoteType,
+  };
+};
+
+export default () => ({
+  name: '@modern-js/backend-federation-build',
+  setup(api: {
+    getAppContext(): { appDirectory: string; distDirectory: string };
+    onAfterBuild(handler: () => Promise<void>): void;
+  }) {
+    api.onAfterBuild(async () => {
+      const { appDirectory, distDirectory } = api.getAppContext();
+      await emitBackendFederationArtifacts(appDirectory, distDirectory);
+    });
+  },
+});

package/src/backend-federation-build/index.ts

@@ -0,0 +1,2 @@
+export type { BackendFederationArtifactResult } from './emit';
+export { default, emitBackendFederationArtifacts } from './emit';