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

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

@@ -0,0 +1,245 @@
+import path from 'node:path';
+import {
+  BACKEND_FEDERATION_EFFECT_EXPOSE as BACKEND_EXPOSE,
+  BACKEND_FEDERATION_MANIFEST_FILE as BACKEND_MANIFEST_FILE,
+  BACKEND_FEDERATION_REMOTE_ENTRY_FILE as BACKEND_REMOTE_ENTRY_FILE,
+  BACKEND_FEDERATION_CONTRACT_VERSION as CONTRACT_VERSION,
+  formatBackendFederationValidationErrors,
+  BACKEND_FEDERATION_NODE_ADAPTER_VERSION as NODE_ADAPTER_VERSION,
+  validateBackendFederationManifest,
+} from '@modern-js/backend-federation-contracts';
+import type { BackendFederationEntryIntegrity } from '@modern-js/server-runtime-extensions/backend-federation-security';
+import { build } from 'esbuild';
+import { type BackendFederationApp, normalizeRelativePath } from './config';
+
+const createRelativeImportSpecifier = (
+  fromDirectory: string,
+  toFile: string,
+) => {
+  const relativePath = normalizeRelativePath(
+    path.relative(fromDirectory, toFile),
+  );
+  return relativePath.startsWith('.') ? relativePath : `./${relativePath}`;
+};
+
+const createPublicPath = (containerEntry: string, fallbackPort: number) => {
+  try {
+    return new URL('.', containerEntry).href;
+  } catch {
+    const slashIndex = containerEntry.lastIndexOf('/');
+    if (slashIndex >= 0) {
+      return containerEntry.slice(0, slashIndex + 1);
+    }
+
+    return `http://localhost:${fallbackPort}/`;
+  }
+};
+
+export const createBackendRemoteEntrySource = async (
+  workspaceRoot: string,
+  app: BackendFederationApp,
+  effectApiPath: string,
+  entryPath: string,
+) => {
+  const effectApiSpecifier = createRelativeImportSpecifier(
+    path.dirname(effectApiPath),
+    effectApiPath,
+  );
+  const containerMetadata = {
+    buildVersion: app.buildVersion,
+    expose: BACKEND_EXPOSE,
+    name: app.backendName,
+    packageName: app.packageName,
+    remoteType: app.remoteType,
+    source: normalizeRelativePath(path.relative(workspaceRoot, effectApiPath)),
+    version: app.version,
+    ...(app.unitId ? { unitId: app.unitId } : {}),
+    ...(app.sourceRevision ? { sourceRevision: app.sourceRevision } : {}),
+  };
+  const compatibility = {
+    build: app.buildVersion,
+    contractVersion: CONTRACT_VERSION,
+    nodeAdapterVersion: NODE_ADAPTER_VERSION,
+    packageName: app.packageName,
+    ...(app.unitId ? { unitId: app.unitId } : {}),
+    ...(app.sourceRevision ? { sourceRevision: app.sourceRevision } : {}),
+  };
+  const source = `// Generated by Modern.js backend federation build.
+import * as exposedNamespace from ${JSON.stringify(effectApiSpecifier)};
+
+const exposedModule = {
+  ...exposedNamespace,
+  backendFederationContract: {
+    ...(exposedNamespace.backendFederationContract ?? {}),
+    compatibility: {
+      ...(exposedNamespace.backendFederationContract?.compatibility ?? {}),
+      ...${JSON.stringify(compatibility)},
+    },
+    name: ${JSON.stringify(app.backendName)},
+    role: 'microvertical-server',
+    runtimeFramework: 'effect',
+    strictEffectApproach: true,
+  },
+};
+const exposedModules = {
+  ${JSON.stringify(BACKEND_EXPOSE)}: () => Promise.resolve(exposedModule),
+};
+const __modernjsBackendFederation = ${JSON.stringify(containerMetadata)};
+
+function init() {}
+
+function get(id) {
+  const load = exposedModules[id];
+  if (!load) {
+    throw new Error(\`Unexpected backend federation expose: \${id}\`);
+  }
+
+  return async () => load();
+}
+
+module.exports = { __modernjsBackendFederation, get, init };
+`;
+  const result = await build({
+    absWorkingDir: path.dirname(effectApiPath),
+    bundle: true,
+    format: 'cjs',
+    logLevel: 'silent',
+    platform: 'node',
+    stdin: {
+      contents: source,
+      loader: 'ts',
+      resolveDir: path.dirname(effectApiPath),
+      sourcefile: path.basename(entryPath),
+    },
+    target: 'node20',
+    write: false,
+  });
+  const output = result.outputFiles[0];
+  if (!output) {
+    throw new Error(
+      '[backend-federation-build] CommonJS backend federation container emitted no output.',
+    );
+  }
+  return output.text;
+};
+
+export const createBackendManifest = (
+  workspaceRoot: string,
+  distDirectory: string,
+  app: BackendFederationApp,
+  entryIntegrity: BackendFederationEntryIntegrity,
+) => {
+  const sourceModule = `${app.directory}/api/effect-api.ts`;
+  const publicPath = createPublicPath(app.containerEntry, app.port);
+
+  const manifest = {
+    schemaVersion: 1,
+    id: app.backendName,
+    name: app.backendName,
+    version: app.version,
+    buildVersion: app.buildVersion,
+    metaData: {
+      name: app.backendName,
+      type: 'backend',
+      buildInfo: {
+        buildVersion: app.buildVersion,
+        buildName: app.packageName,
+      },
+      remoteEntry: {
+        name: BACKEND_REMOTE_ENTRY_FILE,
+        path: '',
+        type: app.remoteType,
+      },
+      globalName: app.backendName,
+      publicPath,
+      ssrRemoteEntry: {
+        name: BACKEND_REMOTE_ENTRY_FILE,
+        path: '',
+        type: app.remoteType,
+      },
+      ssrPublicPath: publicPath,
+    },
+    entry: {
+      ...entryIntegrity,
+      file: BACKEND_REMOTE_ENTRY_FILE,
+      path: normalizeRelativePath(
+        path.relative(
+          workspaceRoot,
+          path.join(distDirectory, BACKEND_REMOTE_ENTRY_FILE),
+        ),
+      ),
+      type: app.remoteType,
+      url: app.containerEntry,
+    },
+    exposes: [
+      {
+        id: `${app.backendName}:${BACKEND_EXPOSE}`,
+        name: BACKEND_EXPOSE,
+        path: '',
+        assets: {
+          js: {
+            async: [],
+            sync: [BACKEND_REMOTE_ENTRY_FILE],
+          },
+          css: {
+            async: [],
+            sync: [],
+          },
+        },
+      },
+    ],
+    shared: [],
+    backendFederation: {
+      role: 'microvertical-server',
+      appId: app.id,
+      name: app.backendName,
+      runtimeFramework: 'effect',
+      strictEffectApproach: true,
+      contractVersion: CONTRACT_VERSION,
+      nodeAdapterVersion: NODE_ADAPTER_VERSION,
+      remoteType: app.remoteType,
+      expose: BACKEND_EXPOSE,
+      manifestUrl: app.manifestUrl,
+      containerEntry: app.containerEntry,
+      source: {
+        module: sourceModule,
+      },
+      readinessPath: `${app.apiPrefix}/${app.apiStem}/readiness`,
+      openapiPath: `${app.apiPrefix}/openapi.json`,
+      ...(app.deliveryUnit ? { deliveryUnit: app.deliveryUnit } : {}),
+      versionBoundary: {
+        invariant: 'web-and-api-same-build',
+        packageName: app.packageName,
+        version: app.version,
+        buildVersion: app.buildVersion,
+        ...(app.uiManifestUrl ? { uiManifestUrl: app.uiManifestUrl } : {}),
+        ...(app.deliveryUnit
+          ? {
+              deliveryUnit: {
+                unitId: app.deliveryUnit.unitId,
+                buildMarker: app.deliveryUnit.buildMarker,
+                sourceRevision: app.deliveryUnit.sourceRevision,
+              },
+            }
+          : {}),
+      },
+    },
+  };
+
+  const validation = validateBackendFederationManifest(manifest, {
+    path: 'backendFederationManifest',
+    requireEffectExpose: true,
+    requireEffectRuntime: true,
+    requireVersionFields: true,
+  });
+
+  if (!validation.ok) {
+    throw new Error(
+      `[backend-federation-build] Invalid backend federation manifest: ${formatBackendFederationValidationErrors(
+        validation.errors,
+      )}.`,
+    );
+  }
+
+  return manifest;
+};

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;
+};