@bleedingdev/modern-js-backend-federation-contracts 0.0.0 → 3.9.0-ultramodern.11

package/src/backend-federation-contract/build-artifact.ts

@@ -0,0 +1,224 @@
+import {
+  DELIVERY_UNIT_IDENTITY_FIELDS,
+  DELIVERY_UNIT_SCHEMA_VERSION,
+} from './constants';
+import {
+  deliveryUnitIdentityFieldValue,
+  validateDeliveryUnitRecord,
+} from './delivery-unit';
+import type {
+  BackendFederationContractValidationError,
+  BackendFederationContractValidationResult,
+  DeliveryUnitRecord,
+  UltramodernBuildArtifact,
+} from './types';
+import {
+  addError,
+  isRecord,
+  nonEmptyString,
+  recordField,
+  validationResult,
+} from './validation-core';
+
+export const createUltramodernBuildArtifact = (
+  record: DeliveryUnitRecord,
+): UltramodernBuildArtifact => {
+  const deliveryUnit = {
+    appId: record.appId,
+    build: record.buildMarker,
+    buildMarker: record.buildMarker,
+    deployProfile: record.deployProfile,
+    kind: record.kind,
+    packageName: record.packageName,
+    schemaVersion: record.schemaVersion,
+    sourceRevision: record.sourceRevision,
+    unitId: record.unitId,
+    version: record.version,
+  };
+  const api = {
+    appId: deliveryUnit.appId,
+    build: deliveryUnit.build,
+    buildMarker: deliveryUnit.buildMarker,
+    deployProfile: deliveryUnit.deployProfile,
+    kind: deliveryUnit.kind,
+    packageName: deliveryUnit.packageName,
+    schemaVersion: deliveryUnit.schemaVersion,
+    sourceRevision: deliveryUnit.sourceRevision,
+    surface: 'api' as const,
+    unitId: deliveryUnit.unitId,
+    version: deliveryUnit.version,
+  };
+  const ui = {
+    appId: deliveryUnit.appId,
+    build: deliveryUnit.build,
+    buildMarker: deliveryUnit.buildMarker,
+    deployProfile: deliveryUnit.deployProfile,
+    kind: deliveryUnit.kind,
+    packageName: deliveryUnit.packageName,
+    schemaVersion: deliveryUnit.schemaVersion,
+    sourceRevision: deliveryUnit.sourceRevision,
+    surface: 'ui' as const,
+    unitId: deliveryUnit.unitId,
+    version: deliveryUnit.version,
+  };
+
+  return {
+    deliveryUnit,
+    kind: 'ultramodern-build-artifact',
+    schemaVersion: DELIVERY_UNIT_SCHEMA_VERSION,
+    surfaces: {
+      api,
+      ui,
+    },
+  };
+};
+
+export const validateUltramodernBuildArtifact = (
+  value: unknown,
+  path = 'artifact',
+): BackendFederationContractValidationResult => {
+  const errors: BackendFederationContractValidationError[] = [];
+
+  if (!isRecord(value)) {
+    addError(errors, path, 'must be an object.');
+    return validationResult(errors);
+  }
+
+  if (value.schemaVersion !== DELIVERY_UNIT_SCHEMA_VERSION) {
+    addError(
+      errors,
+      `${path}.schemaVersion`,
+      `must be ${DELIVERY_UNIT_SCHEMA_VERSION}.`,
+    );
+  }
+  if (value.kind !== 'ultramodern-build-artifact') {
+    addError(errors, `${path}.kind`, 'must be "ultramodern-build-artifact".');
+  }
+
+  const deliveryUnit = value.deliveryUnit;
+  errors.push(
+    ...validateDeliveryUnitRecord(deliveryUnit, {
+      path: `${path}.deliveryUnit`,
+      allowBuildAlias: true,
+    }).errors,
+  );
+
+  if (isRecord(deliveryUnit)) {
+    const build = nonEmptyString(deliveryUnit.build);
+    const buildMarker = nonEmptyString(deliveryUnit.buildMarker);
+    if (!build) {
+      addError(
+        errors,
+        `${path}.deliveryUnit.build`,
+        'must be a non-empty string.',
+      );
+    } else if (buildMarker && build !== buildMarker) {
+      addError(
+        errors,
+        `${path}.deliveryUnit.build`,
+        'must match deliveryUnit.buildMarker.',
+      );
+    }
+  }
+
+  const surfaces = recordField(value, 'surfaces');
+  if (!surfaces) {
+    addError(errors, `${path}.surfaces`, 'must be an object.');
+    return validationResult(errors);
+  }
+
+  for (const surface of ['ui', 'api'] as const) {
+    const marker = surfaces[surface];
+    const markerPath = `${path}.surfaces.${surface}`;
+    errors.push(
+      ...validateDeliveryUnitRecord(marker, {
+        path: markerPath,
+        allowBuildAlias: true,
+      }).errors,
+    );
+
+    if (!isRecord(marker)) {
+      continue;
+    }
+
+    const markerBuild = nonEmptyString(marker.build);
+    const markerBuildMarker = nonEmptyString(marker.buildMarker);
+    if (!markerBuild) {
+      addError(errors, `${markerPath}.build`, 'must be non-empty string.');
+    } else if (markerBuildMarker && markerBuild !== markerBuildMarker) {
+      addError(errors, `${markerPath}.build`, 'must match buildMarker.');
+    }
+
+    if (marker.surface !== surface) {
+      addError(errors, `${markerPath}.surface`, `must be "${surface}".`);
+    }
+
+    for (const field of DELIVERY_UNIT_IDENTITY_FIELDS) {
+      const deliveryUnitValue = deliveryUnitIdentityFieldValue(
+        deliveryUnit,
+        field,
+        { allowBuildAlias: true },
+      );
+      const markerValue = deliveryUnitIdentityFieldValue(marker, field, {
+        allowBuildAlias: true,
+      });
+      if (
+        deliveryUnitValue !== undefined &&
+        markerValue !== undefined &&
+        deliveryUnitValue !== markerValue
+      ) {
+        addError(
+          errors,
+          `${markerPath}.${field}`,
+          `must match ${path}.deliveryUnit.${field}.`,
+        );
+      }
+    }
+  }
+
+  return validationResult(errors);
+};
+
+export const isUltramodernBuildArtifact = (
+  value: unknown,
+): value is UltramodernBuildArtifact =>
+  validateUltramodernBuildArtifact(value).ok;
+
+export const stampUltramodernBuildArtifactIdentity = (
+  artifact: UltramodernBuildArtifact,
+  identity: {
+    buildMarker: string;
+    sourceRevision: string;
+  },
+): UltramodernBuildArtifact => ({
+  ...artifact,
+  deliveryUnit: {
+    ...artifact.deliveryUnit,
+    build: identity.buildMarker,
+    buildMarker: identity.buildMarker,
+    sourceRevision: identity.sourceRevision,
+  },
+  surfaces: {
+    ui: {
+      ...artifact.surfaces.ui,
+      build: identity.buildMarker,
+      buildMarker: identity.buildMarker,
+      sourceRevision: identity.sourceRevision,
+    },
+    api: {
+      ...artifact.surfaces.api,
+      build: identity.buildMarker,
+      buildMarker: identity.buildMarker,
+      sourceRevision: identity.sourceRevision,
+    },
+  },
+});
+
+export const stampUltramodernBuildArtifactSourceRevision = (
+  artifact: UltramodernBuildArtifact,
+  sourceRevision: string,
+): UltramodernBuildArtifact =>
+  stampUltramodernBuildArtifactIdentity(artifact, {
+    buildMarker: artifact.deliveryUnit.buildMarker,
+    sourceRevision,
+  });

package/src/backend-federation-contract/constants.ts

@@ -0,0 +1,33 @@
+export const BACKEND_FEDERATION_EFFECT_EXPOSE = './effect-api';
+
+export const BACKEND_FEDERATION_MANIFEST_FILE = 'backend-mf-manifest.json';
+
+export const BACKEND_FEDERATION_REMOTE_ENTRY_FILE = 'backendRemoteEntry.cjs';
+
+export const BACKEND_FEDERATION_CONTRACT_VERSION =
+  'microvertical-server-effect-v1';
+
+export const BACKEND_FEDERATION_NODE_ADAPTER_VERSION = 'backend-mf-effect-v1';
+
+export const DELIVERY_UNIT_SCHEMA_VERSION = 1;
+
+export const DELIVERY_UNIT_KIND = 'microvertical-delivery-unit';
+
+export const DELIVERY_UNIT_DEPLOY_PROFILE = 'cloudflare-ssr-mf-effect-v1';
+
+export const DELIVERY_UNIT_IDENTITY_FIELDS = [
+  'unitId',
+  'buildMarker',
+  'sourceRevision',
+] as const;
+
+export type DeliveryUnitIdentityField =
+  (typeof DELIVERY_UNIT_IDENTITY_FIELDS)[number];
+
+export const ULTRAMODERN_BUILD_ARTIFACT_FILE = 'ultramodern-build.json';
+
+export const ULTRAMODERN_BUILD_ARTIFACT_PATH = `shared/${ULTRAMODERN_BUILD_ARTIFACT_FILE}`;
+
+export const ULTRAMODERN_BUILD_MODULE_FILE = 'ultramodern-build.ts';
+
+export const ULTRAMODERN_BUILD_MODULE_PATH = `shared/${ULTRAMODERN_BUILD_MODULE_FILE}`;

package/src/backend-federation-contract/delivery-unit.ts

@@ -0,0 +1,170 @@
+import type { DeliveryUnitIdentityField } from './constants';
+import {
+  DELIVERY_UNIT_DEPLOY_PROFILE,
+  DELIVERY_UNIT_IDENTITY_FIELDS,
+  DELIVERY_UNIT_KIND,
+  DELIVERY_UNIT_SCHEMA_VERSION,
+} from './constants';
+import type {
+  BackendFederationContractValidationError,
+  BackendFederationContractValidationResult,
+  DeliveryUnitContractBlock,
+  DeliveryUnitIdentity,
+  DeliveryUnitRecord,
+  ValidateDeliveryUnitIdentityOptions,
+} from './types';
+import {
+  addError,
+  isRecord,
+  nonEmptyString,
+  validationResult,
+} from './validation-core';
+
+export const deliveryUnitIdentityFieldValue = (
+  value: unknown,
+  field: DeliveryUnitIdentityField,
+  options: Pick<ValidateDeliveryUnitIdentityOptions, 'allowBuildAlias'> = {},
+): string | undefined => {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  if (field === 'buildMarker' && options.allowBuildAlias) {
+    return nonEmptyString(value.buildMarker) ?? nonEmptyString(value.build);
+  }
+
+  return nonEmptyString(value[field]);
+};
+
+export const validateDeliveryUnitIdentity = (
+  value: unknown,
+  options: ValidateDeliveryUnitIdentityOptions = {},
+): BackendFederationContractValidationResult => {
+  const path = options.path ?? 'deliveryUnit';
+  const errors: BackendFederationContractValidationError[] = [];
+
+  if (!isRecord(value)) {
+    addError(errors, path, 'must be an object.');
+    return validationResult(errors);
+  }
+
+  for (const field of DELIVERY_UNIT_IDENTITY_FIELDS) {
+    if (!deliveryUnitIdentityFieldValue(value, field, options)) {
+      addError(errors, `${path}.${field}`, 'must be a non-empty string.');
+    }
+  }
+
+  return validationResult(errors);
+};
+
+export const validateDeliveryUnitContractBlock = (
+  value: unknown,
+  options: ValidateDeliveryUnitIdentityOptions = {},
+): BackendFederationContractValidationResult => {
+  const path = options.path ?? 'deliveryUnit';
+  const errors = [...validateDeliveryUnitIdentity(value, options).errors];
+
+  if (!isRecord(value)) {
+    return validationResult(errors);
+  }
+
+  if (value.schemaVersion !== DELIVERY_UNIT_SCHEMA_VERSION) {
+    addError(
+      errors,
+      `${path}.schemaVersion`,
+      `must be ${DELIVERY_UNIT_SCHEMA_VERSION}.`,
+    );
+  }
+  if (value.kind !== DELIVERY_UNIT_KIND) {
+    addError(errors, `${path}.kind`, `must be "${DELIVERY_UNIT_KIND}".`);
+  }
+  if (!nonEmptyString(value.packageName)) {
+    addError(errors, `${path}.packageName`, 'must be a non-empty string.');
+  }
+  if (!nonEmptyString(value.version)) {
+    addError(errors, `${path}.version`, 'must be a non-empty string.');
+  }
+
+  return validationResult(errors);
+};
+
+export const validateDeliveryUnitRecord = (
+  value: unknown,
+  options: ValidateDeliveryUnitIdentityOptions = {},
+): BackendFederationContractValidationResult => {
+  const path = options.path ?? 'deliveryUnit';
+  const errors = [
+    ...validateDeliveryUnitContractBlock(value, {
+      ...options,
+      path,
+    }).errors,
+  ];
+
+  if (!isRecord(value)) {
+    return validationResult(errors);
+  }
+
+  if (!nonEmptyString(value.appId)) {
+    addError(errors, `${path}.appId`, 'must be a non-empty string.');
+  }
+  if (value.deployProfile !== DELIVERY_UNIT_DEPLOY_PROFILE) {
+    addError(
+      errors,
+      `${path}.deployProfile`,
+      `must be "${DELIVERY_UNIT_DEPLOY_PROFILE}".`,
+    );
+  }
+
+  return validationResult(errors);
+};
+
+export const validateDeliveryUnitBoundaryIdentity = (
+  value: unknown,
+  path: string,
+): BackendFederationContractValidationError[] => {
+  const errors: BackendFederationContractValidationError[] = [];
+
+  if (!isRecord(value)) {
+    addError(errors, path, 'must be an object.');
+    return errors;
+  }
+
+  for (const field of DELIVERY_UNIT_IDENTITY_FIELDS) {
+    if (!deliveryUnitIdentityFieldValue(value, field)) {
+      addError(errors, `${path}.${field}`, 'must be a non-empty string.');
+    }
+  }
+
+  return errors;
+};
+
+export const deliveryUnitContractBlock = (
+  record: DeliveryUnitRecord,
+): DeliveryUnitContractBlock => ({
+  schemaVersion: record.schemaVersion,
+  kind: record.kind,
+  unitId: record.unitId,
+  packageName: record.packageName,
+  version: record.version,
+  buildMarker: record.buildMarker,
+  sourceRevision: record.sourceRevision,
+});
+
+export const toDeliveryUnitIdentity = (
+  value: unknown,
+): DeliveryUnitIdentity | undefined => {
+  const unitId = deliveryUnitIdentityFieldValue(value, 'unitId');
+  const buildMarker = deliveryUnitIdentityFieldValue(value, 'buildMarker', {
+    allowBuildAlias: true,
+  });
+  const sourceRevision = deliveryUnitIdentityFieldValue(
+    value,
+    'sourceRevision',
+  );
+
+  if (!unitId || !buildMarker || !sourceRevision) {
+    return undefined;
+  }
+
+  return { unitId, buildMarker, sourceRevision };
+};

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

@@ -0,0 +1,56 @@
+export {
+  createUltramodernBuildArtifact,
+  isUltramodernBuildArtifact,
+  stampUltramodernBuildArtifactIdentity,
+  stampUltramodernBuildArtifactSourceRevision,
+  validateUltramodernBuildArtifact,
+} from './build-artifact';
+export type { DeliveryUnitIdentityField } from './constants';
+export {
+  BACKEND_FEDERATION_CONTRACT_VERSION,
+  BACKEND_FEDERATION_EFFECT_EXPOSE,
+  BACKEND_FEDERATION_MANIFEST_FILE,
+  BACKEND_FEDERATION_NODE_ADAPTER_VERSION,
+  BACKEND_FEDERATION_REMOTE_ENTRY_FILE,
+  DELIVERY_UNIT_DEPLOY_PROFILE,
+  DELIVERY_UNIT_IDENTITY_FIELDS,
+  DELIVERY_UNIT_KIND,
+  DELIVERY_UNIT_SCHEMA_VERSION,
+  ULTRAMODERN_BUILD_ARTIFACT_FILE,
+  ULTRAMODERN_BUILD_ARTIFACT_PATH,
+  ULTRAMODERN_BUILD_MODULE_FILE,
+  ULTRAMODERN_BUILD_MODULE_PATH,
+} from './constants';
+export {
+  deliveryUnitContractBlock,
+  deliveryUnitIdentityFieldValue,
+  toDeliveryUnitIdentity,
+  validateDeliveryUnitContractBlock,
+  validateDeliveryUnitIdentity,
+  validateDeliveryUnitRecord,
+} from './delivery-unit';
+export {
+  backendFederationExposeNames,
+  backendFederationMetadata,
+  backendFederationVersionBoundary,
+  toBackendFederationExposeNames,
+  validateBackendFederationManifest,
+  validateBackendFederationMetadata,
+} from './metadata';
+export type {
+  BackendFederationContractValidationError,
+  BackendFederationContractValidationResult,
+  DeliveryUnitContractBlock,
+  DeliveryUnitIdentity,
+  DeliveryUnitRecord,
+  UltramodernBuildArtifact,
+  UltramodernBuildDeliveryUnit,
+  UltramodernBuildSurface,
+  ValidateBackendFederationManifestOptions,
+  ValidateBackendFederationMetadataOptions,
+  ValidateDeliveryUnitIdentityOptions,
+} from './types';
+export {
+  formatBackendFederationValidationErrors,
+  nonEmptyString,
+} from './validation-core';

package/src/backend-federation-contract/metadata.ts

@@ -0,0 +1,225 @@
+import {
+  BACKEND_FEDERATION_CONTRACT_VERSION,
+  BACKEND_FEDERATION_EFFECT_EXPOSE,
+  BACKEND_FEDERATION_NODE_ADAPTER_VERSION,
+  DELIVERY_UNIT_IDENTITY_FIELDS,
+  DELIVERY_UNIT_SCHEMA_VERSION,
+} from './constants';
+import {
+  deliveryUnitIdentityFieldValue,
+  validateDeliveryUnitBoundaryIdentity,
+  validateDeliveryUnitContractBlock,
+} from './delivery-unit';
+import type {
+  BackendFederationContractValidationError,
+  BackendFederationContractValidationResult,
+  ValidateBackendFederationManifestOptions,
+  ValidateBackendFederationMetadataOptions,
+} from './types';
+import {
+  addError,
+  isRecord,
+  nonEmptyString,
+  recordField,
+  validateVersionField,
+  validationResult,
+} from './validation-core';
+
+export const toBackendFederationExposeNames = (value: unknown): string[] => {
+  const names: string[] = [];
+
+  if (Array.isArray(value)) {
+    for (const expose of value) {
+      const name =
+        nonEmptyString(expose) ??
+        (isRecord(expose) ? nonEmptyString(expose.name) : undefined);
+      if (name) {
+        names.push(name);
+      }
+    }
+  } else if (isRecord(value)) {
+    names.push(...Object.keys(value).filter(name => name.length > 0));
+  }
+
+  return Array.from(new Set(names));
+};
+
+export const backendFederationExposeNames = (value: unknown): string[] => {
+  if (!isRecord(value)) {
+    return [];
+  }
+
+  const exposes = toBackendFederationExposeNames(value.exposes);
+  const expose = nonEmptyString(value.expose);
+  return Array.from(new Set([...exposes, ...(expose ? [expose] : [])]));
+};
+
+export const backendFederationMetadata = (
+  value: unknown,
+): Record<string, unknown> | undefined =>
+  isRecord(value) ? recordField(value, 'backendFederation') : undefined;
+
+export const backendFederationVersionBoundary = (
+  value: unknown,
+): Record<string, unknown> | undefined =>
+  recordField(backendFederationMetadata(value), 'versionBoundary');
+
+export const validateBackendFederationMetadata = (
+  value: unknown,
+  options: ValidateBackendFederationMetadataOptions = {},
+): BackendFederationContractValidationResult => {
+  const path = options.path ?? 'backendFederation';
+  const errors: BackendFederationContractValidationError[] = [];
+
+  if (!isRecord(value)) {
+    addError(errors, path, 'must be an object.');
+    return validationResult(errors);
+  }
+
+  if (options.requireEffectRuntime && value.runtimeFramework !== 'effect') {
+    addError(errors, `${path}.runtimeFramework`, 'must be "effect".');
+  }
+  if (options.requireEffectRuntime && value.strictEffectApproach !== true) {
+    addError(errors, `${path}.strictEffectApproach`, 'must be true.');
+  }
+
+  validateVersionField(
+    errors,
+    value,
+    'contractVersion',
+    options.expectedContractVersion ?? BACKEND_FEDERATION_CONTRACT_VERSION,
+    path,
+    options.requireVersionFields ?? false,
+  );
+  validateVersionField(
+    errors,
+    value,
+    'nodeAdapterVersion',
+    options.expectedNodeAdapterVersion ??
+      BACKEND_FEDERATION_NODE_ADAPTER_VERSION,
+    path,
+    options.requireVersionFields ?? false,
+  );
+
+  if (
+    options.requireEffectExpose &&
+    !backendFederationExposeNames(value).includes(
+      BACKEND_FEDERATION_EFFECT_EXPOSE,
+    )
+  ) {
+    addError(
+      errors,
+      `${path}.expose`,
+      `must include "${BACKEND_FEDERATION_EFFECT_EXPOSE}".`,
+    );
+  }
+
+  if (options.validateDeliveryUnit ?? true) {
+    const deliveryUnit = recordField(value, 'deliveryUnit');
+    if (deliveryUnit) {
+      errors.push(
+        ...validateDeliveryUnitContractBlock(deliveryUnit, {
+          path: `${path}.deliveryUnit`,
+        }).errors,
+      );
+    }
+
+    const versionBoundary = recordField(value, 'versionBoundary');
+    const versionBoundaryDeliveryUnit = recordField(
+      versionBoundary,
+      'deliveryUnit',
+    );
+    if (versionBoundaryDeliveryUnit) {
+      errors.push(
+        ...validateDeliveryUnitBoundaryIdentity(
+          versionBoundaryDeliveryUnit,
+          `${path}.versionBoundary.deliveryUnit`,
+        ),
+      );
+    }
+
+    if (deliveryUnit && versionBoundaryDeliveryUnit) {
+      for (const field of DELIVERY_UNIT_IDENTITY_FIELDS) {
+        const deliveryUnitValue = deliveryUnitIdentityFieldValue(
+          deliveryUnit,
+          field,
+        );
+        const versionBoundaryDeliveryUnitValue = deliveryUnitIdentityFieldValue(
+          versionBoundaryDeliveryUnit,
+          field,
+        );
+
+        if (
+          deliveryUnitValue &&
+          versionBoundaryDeliveryUnitValue &&
+          deliveryUnitValue !== versionBoundaryDeliveryUnitValue
+        ) {
+          addError(
+            errors,
+            `${path}.versionBoundary.deliveryUnit.${field}`,
+            `must match ${path}.deliveryUnit.${field}.`,
+          );
+        }
+      }
+    }
+  }
+
+  return validationResult(errors);
+};
+
+export const validateBackendFederationManifest = (
+  value: unknown,
+  options: ValidateBackendFederationManifestOptions = {},
+): BackendFederationContractValidationResult => {
+  const path = options.path ?? 'manifest';
+  const errors: BackendFederationContractValidationError[] = [];
+
+  if (!isRecord(value)) {
+    addError(errors, path, 'must be an object.');
+    return validationResult(errors);
+  }
+
+  if (
+    value.schemaVersion !== undefined &&
+    value.schemaVersion !== DELIVERY_UNIT_SCHEMA_VERSION
+  ) {
+    addError(
+      errors,
+      `${path}.schemaVersion`,
+      `must be ${DELIVERY_UNIT_SCHEMA_VERSION}.`,
+    );
+  }
+
+  const metadata = backendFederationMetadata(value);
+  if (!metadata) {
+    if (options.requireBackendFederation ?? true) {
+      addError(errors, `${path}.backendFederation`, 'must be an object.');
+    }
+  } else {
+    errors.push(
+      ...validateBackendFederationMetadata(metadata, {
+        ...options,
+        path: `${path}.backendFederation`,
+        requireEffectExpose: false,
+      }).errors,
+    );
+  }
+
+  if (options.requireEffectExpose) {
+    const topLevelExposeNames = toBackendFederationExposeNames(value.exposes);
+    const metadataExposeNames = backendFederationExposeNames(metadata);
+    const exposeNames = new Set([
+      ...topLevelExposeNames,
+      ...metadataExposeNames,
+    ]);
+    if (!exposeNames.has(BACKEND_FEDERATION_EFFECT_EXPOSE)) {
+      addError(
+        errors,
+        `${path}.exposes`,
+        `must include "${BACKEND_FEDERATION_EFFECT_EXPOSE}".`,
+      );
+    }
+  }
+
+  return validationResult(errors);
+};