@bleedingdev/modern-js-ultramodern-create 3.9.0-ultramodern.2 → 3.9.0-ultramodern.21

package/templates/workspace-scripts/proof-node-backend-federation.mjs

@@ -9,7 +9,8 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const workspaceRoot = path.resolve(process.env.ULTRAMODERN_WORKSPACE_ROOT ?? process.cwd());
 const workspaceRequire = createRequire(path.join(workspaceRoot, 'package.json'));
-const compactConfigPath = path.join(workspaceRoot, '.modernjs/ultramodern.json');
+const topologyPath = path.join(workspaceRoot, 'topology/reference-topology.json');
+const localOverlayPath = path.join(workspaceRoot, 'topology/local-overlays/development.json');
 const defaultOut = path.join(
   workspaceRoot,
   '.codex/reports/node-backend-federation-proof/proof.json',
@@ -19,13 +20,9 @@ const defaultOut = path.join(
 // @modern-js/utils/universal backend-federation-contract. Generated workspace
 // scripts do not currently import @modern-js/utils directly.
 const contractVersion = 'microvertical-server-effect-v1';
-const nodeAdapterVersion = 'backend-mf-effect-v1';
+const nodeAdapterVersion = 'backend-mf-effect-v2';
 const backendExpose = './effect-api';
 const releaseEnvelopePath = 'release/microvertical-release-envelope.json';
-const localRuntimeRelativePaths = [
-  'packages/cli/plugin-bff/dist/esm-node/runtime/effect/index.mjs',
-  'cli/plugin-bff/dist/esm-node/runtime/effect/index.mjs',
-];
 
 function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, 'utf8'));
@@ -55,60 +52,30 @@ function hasBackendFederationManifestAdapter(runtime) {
   return typeof runtime?.loadBackendFederatedEffectApiFromManifest === 'function';
 }
 
-function findLocalRuntimePath(createBin) {
-  let current = path.dirname(fileURLToPath(pathToFileURL(createBin)));
-  for (let depth = 0; depth < 8; depth += 1) {
-    for (const relativePath of localRuntimeRelativePaths) {
-      const candidate = path.join(current, relativePath);
-      if (fs.existsSync(candidate)) {
-        return candidate;
-      }
-    }
-
-    const parent = path.dirname(current);
-    if (parent === current) {
-      break;
-    }
-    current = parent;
-  }
-
-  return undefined;
-}
-
-async function importBackendFederationRuntime() {
-  let importError;
-  try {
-    const runtimePath = workspaceRequire.resolve('@modern-js/plugin-bff/effect');
-    const runtime = await import(pathToFileURL(runtimePath).href);
-    if (hasBackendFederationManifestAdapter(runtime)) {
-      return runtime;
-    }
-
-    importError = new Error(
+export async function importBackendFederationRuntime() {
+  const runtimePath = workspaceRequire.resolve(
+    '@modern-js/plugin-bff-extensions/backend-federation-manifest/node',
+  );
+  const effectPath = workspaceRequire.resolve('@modern-js/bff-effect/effect');
+  const [runtime, effect] = await Promise.all([
+    import(pathToFileURL(runtimePath).href),
+    import(pathToFileURL(effectPath).href),
+  ]);
+  if (!hasBackendFederationManifestAdapter(runtime)) {
+    throw new Error(
       `${runtimePath} does not export loadBackendFederatedEffectApiFromManifest`,
     );
-  } catch (error) {
-    importError = error;
   }
-
-  const createBin = process.env.ULTRAMODERN_CREATE_BIN;
-  if (!createBin) {
-    throw importError;
-  }
-
-  const localRuntimePath = findLocalRuntimePath(createBin);
-  if (!localRuntimePath) {
-    throw importError;
-  }
-
-  const localRuntime = await import(pathToFileURL(localRuntimePath).href);
-  if (!hasBackendFederationManifestAdapter(localRuntime)) {
+  if (typeof effect.createEffectBffTestHandler !== 'function') {
     throw new Error(
-      `${localRuntimePath} does not export loadBackendFederatedEffectApiFromManifest`,
+      `${effectPath} does not export createEffectBffTestHandler`,
     );
   }
-
-  return localRuntime;
+  return {
+    loadBackendFederatedEffectApiFromManifest:
+      runtime.loadBackendFederatedEffectApiFromManifest,
+    createEffectBffTestHandler: effect.createEffectBffTestHandler,
+  };
 }
 
 function normalizeRelativePath(value) {
@@ -129,7 +96,6 @@ function createBackendName(app) {
   return (
     app.backendFederation?.name ??
     app.backendFederation?.executionSurfaces?.node?.remoteName ??
-    app.serverExecution?.node?.remoteName ??
     (typeof app.moduleFederation?.name === 'string'
       ? `${app.moduleFederation.name}Backend`
       : `vertical${toPascalCase(app.id)}Backend`)
@@ -138,7 +104,6 @@ function createBackendName(app) {
 
 function createBackendManifestUrl(app) {
   return (
-    app.backendFederation?.executionSurfaces?.node?.manifestUrl ??
     app.serverExecution?.node?.manifestUrl ??
     `http://localhost:${app.port}/backend-mf-manifest.json`
   );
@@ -146,7 +111,6 @@ function createBackendManifestUrl(app) {
 
 function createBackendContainerEntry(app) {
   return (
-    app.backendFederation?.executionSurfaces?.node?.containerEntry ??
     app.serverExecution?.node?.containerEntry ??
     `http://localhost:${app.port}/backendRemoteEntry.cjs`
   );
@@ -154,8 +118,8 @@ function createBackendContainerEntry(app) {
 
 function resolveRemoteType(app) {
   return (
-    app.backendFederation?.executionSurfaces?.node?.remoteType ??
     app.serverExecution?.node?.remoteType ??
+    app.backendFederation?.executionSurfaces?.node?.remoteType ??
     'commonjs-module'
   );
 }
@@ -173,8 +137,8 @@ function collectJsonSmokeChecks(apps, targetApp) {
 
   const configuredChecks = apps
     .flatMap((app) =>
-      Array.isArray(app?.deploy?.cloudflare?.jsonSmokeChecks)
-        ? app.deploy.cloudflare.jsonSmokeChecks
+      Array.isArray(app?.cloudflare?.jsonSmokeChecks)
+        ? app.cloudflare.jsonSmokeChecks
         : [],
     )
     .filter((check) => {
@@ -211,27 +175,70 @@ function collectJsonSmokeChecks(apps, targetApp) {
   ];
 }
 
-function compactApps(config, appFilter) {
-  const apps = Array.isArray(config.topology?.apps) ? config.topology.apps : [];
+export function topologyApps(topology, localOverlay, appFilter, env = process.env) {
+  if (!Array.isArray(topology?.verticals) || !localOverlay?.ports || !localOverlay?.serverExecution) {
+    throw new Error('Node proof requires declared reference topology and development overlay.');
+  }
+  const apps = topology.verticals;
   const filteredApps = apps
     .filter((app) => app?.kind === 'vertical' && app.api)
     .filter((app) => !appFilter || app.id === appFilter)
-    .map((app) => ({
+    .map((app) => {
+      const overlayPort = localOverlay.ports[app.id];
+      const domain = app.domain ?? app.id;
+      const portEnv = app.portEnv ??
+        `VERTICAL_${String(domain).replace(/[^a-zA-Z0-9]/gu, '_').toUpperCase()}_PORT`;
+      const configuredPort = env[portEnv];
+      const port = configuredPort === undefined ? overlayPort : Number(configuredPort);
+      const serverExecution = localOverlay.serverExecution[app.id];
+      if (!app.path || !Number.isInteger(overlayPort) || !Number.isInteger(port) || port < 1 || port > 65535 || !serverExecution?.node) {
+        throw new Error(`${app.id} is missing its declared path, port or Node server execution.`);
+      }
+      const appManifest = readJson(path.join(workspaceRoot, app.path, 'package.json'));
+      if (app.package !== appManifest.name || typeof appManifest.version !== 'string') {
+        throw new Error(`${app.id} topology package identity must match package.json`);
+      }
+      const api = { ...app.api, prefix: app.api.bff?.prefix };
+      const declared = { ...app, api, serverExecution };
+      const publicUrlEnv = app.cloudflare?.publicUrlEnv;
+      const configuredPublicUrl = publicUrlEnv ? env[publicUrlEnv] : undefined;
+      const publicOrigin = configuredPublicUrl
+        ? new URL(configuredPublicUrl).origin
+        : `http://localhost:${port}`;
+      if (!/^https?:\/\//u.test(publicOrigin)) {
+        throw new Error(`${app.id} has an invalid declared public URL.`);
+      }
+      const nodeUrl = (declaredUrl) => {
+        const url = new URL(declaredUrl);
+        return url.origin === new URL(`http://localhost:${overlayPort}`).origin &&
+          url.username === '' &&
+          url.password === ''
+          ? `${publicOrigin}${url.pathname}${url.search}${url.hash}`
+          : declaredUrl;
+      };
+      return {
       id: app.id,
-      directory:
-        typeof app.path === 'string' ? normalizeRelativePath(app.path) : `verticals/${app.id}`,
-      backendName: createBackendName(app),
-      manifestUrl: createBackendManifestUrl(app),
-      containerEntry: createBackendContainerEntry(app),
-      port: app.port,
-      portEnv: app.portEnv,
-      remoteType: resolveRemoteType(app),
-      smokeChecks: collectJsonSmokeChecks(apps, app),
-      compactDeliveryUnit:
+      directory: normalizeRelativePath(app.path),
+      backendName: createBackendName(declared),
+      manifestUrl: nodeUrl(createBackendManifestUrl(declared)),
+      containerEntry: nodeUrl(createBackendContainerEntry(declared)),
+      port,
+      portEnv,
+      remoteType: resolveRemoteType(declared),
+      apiProtocol: app.api.protocol ?? 'rest',
+      apiPrefix: app.api.bff?.prefix,
+      rpcPath: app.api.rpcPath,
+      rpcSerialization: app.api.rpcSerialization,
+      apiOnly: app.surfaceProfile === 'api-only',
+      smokeChecks: collectJsonSmokeChecks(apps, declared),
+      topologyDeliveryUnit:
         app.deliveryUnit && typeof app.deliveryUnit === 'object'
           ? app.deliveryUnit
           : undefined,
-    }));
+      packageName: appManifest.name,
+      version: appManifest.version,
+    };
+    });
 
   if (appFilter && filteredApps.length === 0) {
     throw new Error(`No vertical API app matched --app ${appFilter}`);
@@ -473,7 +480,7 @@ function sha256(bytes) {
   return createHash('sha256').update(bytes).digest('hex');
 }
 
-function readBoundReleaseEnvelope(app, target) {
+export function readBoundReleaseEnvelope(app, target) {
   const targetDirectory = path.join(workspaceRoot, app.directory, target);
   const envelopePath = path.join(targetDirectory, releaseEnvelopePath);
   assertFile(envelopePath, app.id, 'Node release envelope');
@@ -484,6 +491,18 @@ function readBoundReleaseEnvelope(app, target) {
     `${app.id} release-envelope schema`,
   );
   assertEqual(envelope.target, 'node', `${app.id} release-envelope target`);
+  assertEqual(
+    envelope.kind,
+    'ultramodern-target-microvertical-release-envelope',
+    `${app.id} release-envelope kind`,
+  );
+  if (app.apiOnly) {
+    if (envelope.surfaces?.uiClient?.length !== 0 || envelope.surfaces?.ssr?.length !== 0) {
+      throw new Error(`${app.id} API-only release envelope must declare empty UI/client and SSR surfaces`);
+    }
+  } else if (!envelope.surfaces?.uiClient?.length || !envelope.surfaces?.ssr?.length) {
+    throw new Error(`${app.id} full-stack release envelope must bind UI/client and SSR surfaces`);
+  }
 
   const manifestLogicalPath = envelope.surfaces?.backendFederation?.manifest;
   const containerLogicalPath = envelope.surfaces?.backendFederation?.container;
@@ -729,6 +748,98 @@ async function proveLiveApi(app, manifest, releaseBinding) {
   };
 }
 
+export async function proveLiveRpcApi(app, loaded, manifest, releaseBinding) {
+  const contract = loaded.contract;
+  if (contract?.protocol !== 'rpc' || typeof contract.group !== 'string' ||
+      typeof contract.path !== 'string' || contract.serialization !== 'json') {
+    throw new Error(`${app.id} backend expose missing native RPC contract`);
+  }
+  assertEqual(contract.path, app.rpcPath, `${app.id} RPC contract/topology path`);
+  assertEqual(contract.path, manifest.backendFederation?.rpcPath, `${app.id} RPC contract/manifest path`);
+  assertEqual(contract.serialization, app.rpcSerialization, `${app.id} RPC contract/topology serialization`);
+  assertEqual(contract.serialization, manifest.backendFederation?.rpcSerialization, `${app.id} RPC contract/manifest serialization`);
+  const check = app.smokeChecks.find((entry) => entry?.body?.method === 'list' && entry.route === contract.path);
+  if (!check || !Number.isInteger(check.body?.params?.limit) || check.body.params.limit < 1) {
+    throw new Error(`${app.id} has no declared RPC list smoke check`);
+  }
+  const route = normalizeRoutePath(contract.path);
+  const url = new URL(route, app.manifestUrl).href;
+  const clientModule = createRequire(
+    path.join(workspaceRoot, app.directory, 'package.json'),
+  )(`${app.packageName}/api/rpc-client`);
+  const clientName = toPascalCase(contract.group);
+  const localContract = clientModule[`${clientName}RpcContract`];
+  if (localContract?.path !== contract.path ||
+      localContract?.group !== contract.group ||
+      localContract?.serialization !== contract.serialization ||
+      localContract?.protocol !== contract.protocol) {
+    throw new Error(`${app.id} public RPC client contract does not match the verified backend expose`);
+  }
+  const makeClient = clientModule[`make${clientName}RpcClient`];
+  if (typeof makeClient !== 'function' ||
+      typeof clientModule.Effect?.runPromise !== 'function') {
+    throw new Error(`${app.id} has no native public RPC client`);
+  }
+  const client = await clientModule.Effect.runPromise(makeClient({ url }));
+  try {
+    const listed = await clientModule.Effect.runPromise(client.list({ limit: check.body.params.limit }));
+    const item = listed?.items?.[0];
+    if (typeof item?.id !== 'string' || item.id.length === 0) {
+      throw new Error(`${app.id} native RPC list returned no item id`);
+    }
+    for (const expectation of normalizeJsonExpectations(check)) {
+      if (expectation.path === 'id') {
+        assertJsonEqual(check.body.id, expectation.value, `${app.id} declared RPC request id`);
+      } else if (expectation.path.startsWith('result.')) {
+        assertJsonEqual(
+          jsonPathValue(listed, expectation.path.slice('result.'.length)),
+          expectation.value,
+          `${app.id} native RPC ${expectation.path}`,
+        );
+      } else {
+        throw new Error(`${app.id} RPC smoke check has unsupported expectation ${expectation.path}`);
+      }
+    }
+    const fetched = await clientModule.Effect.runPromise(client.get({ id: item.id }));
+    assertEqual(fetched?.id, item.id, `${app.id} native RPC get item id`);
+    const missingId = `__ultramodern-proof-missing-${item.id}__`;
+    const missing = await clientModule.Effect.runPromise(
+      clientModule.Effect.match(client.get({ id: missingId }), {
+        onFailure: (error) => ({ error }),
+        onSuccess: (value) => ({ value }),
+      }),
+    );
+    const expectedErrorTag = `${toPascalCase(contract.group)}NotFoundRpc`;
+    if (missing?.error?._tag !== expectedErrorTag ||
+        missing.error?.id !== missingId) {
+      throw new Error(`${app.id} native RPC get did not return ${expectedErrorTag} for a missing item`);
+    }
+    return {
+      method: 'RPC',
+      route,
+      url,
+      protocol: contract.protocol,
+      serialization: contract.serialization,
+      group: contract.group,
+      operations: [
+        { method: 'list', itemId: item.id, status: 'pass' },
+        { method: 'get', itemId: fetched.id, status: 'pass' },
+        { method: 'get', errorTag: missing.error._tag, missingId, status: 'pass' },
+      ],
+      envelopeDigest: releaseBinding.envelope.envelopeDigest,
+      apiBackendArtifacts: releaseBinding.apiBackendArtifacts.map((artifact) => ({
+        logicalPath: artifact.logicalPath,
+        runtime: artifact.runtime,
+        byteLength: artifact.byteLength,
+        sha256: artifact.sha256,
+      })),
+      status: 'pass',
+    };
+  } finally {
+    await client.dispose();
+  }
+}
+
 function jsonPathValue(value, path) {
   const segments = String(path ?? '')
     .split('.')
@@ -781,12 +892,17 @@ async function runSmokeChecks(app, loaded, createEffectBffTestHandler) {
     throw new Error(`${app.id} backend runtime cannot create Effect test handler`);
   }
 
-  const servicePrefix = loaded.contract?.servicePrefix ?? loaded.contract?.apiPrefix;
+  const servicePrefix = loaded.contract?.protocol === 'rpc'
+    ? app.apiPrefix
+    : loaded.contract?.servicePrefix ?? loaded.contract?.apiPrefix;
   if (typeof servicePrefix !== 'string' || servicePrefix.length === 0) {
     throw new Error(
-      `${app.id} backend expose missing contract.servicePrefix/apiPrefix`,
+      `${app.id} backend expose missing declared API prefix`,
     );
   }
+  if (loaded.contract?.protocol === 'rpc') {
+    assertEqual(loaded.contract.path, app.rpcPath, `${app.id} RPC smoke route`);
+  }
 
   const edge = await createEffectBffTestHandler({
     module: loaded.runtime,
@@ -995,10 +1111,10 @@ function validateManifest(app, manifest, buildIdentity) {
   }
 }
 
-function assertCompactStableIdentityMatchesBuild(app, buildIdentity) {
-  const compactDeliveryUnit = app.compactDeliveryUnit;
-  if (!compactDeliveryUnit) {
-    return;
+function assertTopologyStableIdentityMatchesBuild(app, buildIdentity) {
+  const topologyDeliveryUnit = app.topologyDeliveryUnit;
+  if (!topologyDeliveryUnit) {
+    throw new Error(`${app.id} is missing its declared topology delivery-unit identity`);
   }
 
   const mismatches = [];
@@ -1007,20 +1123,22 @@ function assertCompactStableIdentityMatchesBuild(app, buildIdentity) {
       mismatches.push(`${label}: deliveryUnit=${a} vs ultramodern-build=${b}`);
     }
   };
-  compare('unitId', compactDeliveryUnit.unitId, buildIdentity.unitId);
+  compare('unitId', topologyDeliveryUnit.unitId, buildIdentity.unitId);
   compare(
     'packageName',
-    compactDeliveryUnit.packageName,
+    topologyDeliveryUnit.packageName,
     buildIdentity.packageName,
   );
-  compare('version', compactDeliveryUnit.version, buildIdentity.version);
+  compare('version', topologyDeliveryUnit.version, buildIdentity.version);
+  compare('packageName', app.packageName, buildIdentity.packageName);
+  compare('version', app.version, buildIdentity.version);
 
   if (mismatches.length > 0) {
     throw new Error(
       `${app.id} delivery-unit identity drift between ${path.relative(
         workspaceRoot,
-        compactConfigPath,
-      )} (generation metadata) and ${path.relative(
+        topologyPath,
+      )} (reference topology) and ${path.relative(
         workspaceRoot,
         buildIdentity.artifactPath,
       )} (stamped target identity): ${mismatches.join('; ')}`,
@@ -1039,7 +1157,7 @@ async function proveBackend(app, backendRuntime, target) {
   assertFile(entryPath, app.id, 'backend remote entry');
 
   const buildIdentity = readBuildIdentity(app, target);
-  assertCompactStableIdentityMatchesBuild(app, buildIdentity);
+  assertTopologyStableIdentityMatchesBuild(app, buildIdentity);
   const manifest = readJson(manifestPath);
   validateManifest(app, manifest, buildIdentity);
   const releaseBinding = readBoundReleaseEnvelope(app, target);
@@ -1141,7 +1259,9 @@ async function proveBackend(app, backendRuntime, target) {
   }
 
   const smokeChecks = await runSmokeChecks(app, loaded, createEffectBffTestHandler);
-  const liveApi = await proveLiveApi(app, manifest, releaseBinding);
+  const liveApi = loaded.contract?.protocol === 'rpc'
+    ? await proveLiveRpcApi(app, loaded, manifest, releaseBinding)
+    : await proveLiveApi(app, manifest, releaseBinding);
 
   return {
     appId: app.id,
@@ -1218,9 +1338,10 @@ async function main(argv = process.argv.slice(2)) {
     return 0;
   }
 
-  const config = readJson(compactConfigPath);
-  const runtimeApps = compactApps(config);
-  const apps = args.app ? compactApps(config, args.app) : runtimeApps;
+  const topology = readJson(topologyPath);
+  const localOverlay = readJson(localOverlayPath);
+  const runtimeApps = topologyApps(topology, localOverlay);
+  const apps = args.app ? topologyApps(topology, localOverlay, args.app) : runtimeApps;
   const results = [];
   const backendRuntime =
     apps.length > 0 ? await importBackendFederationRuntime() : undefined;