@prisma-next/target-mongo 0.4.0-dev.1 → 0.4.0-dev.3

package/src/core/mongo-planner.ts

@@ -0,0 +1,306 @@
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type {
+  MigrationOperationClass,
+  MigrationOperationPolicy,
+  MigrationPlanner,
+  MigrationPlannerConflict,
+  MigrationPlannerResult,
+} from '@prisma-next/framework-components/control';
+import type { MongoContract } from '@prisma-next/mongo-contract';
+import type {
+  MongoSchemaCollection,
+  MongoSchemaCollectionOptions,
+  MongoSchemaIndex,
+  MongoSchemaIR,
+  MongoSchemaValidator,
+} from '@prisma-next/mongo-schema-ir';
+import { canonicalize, deepEqual } from '@prisma-next/mongo-schema-ir';
+import { contractToMongoSchemaIR } from './contract-to-schema';
+import type { OpFactoryCall } from './op-factory-call';
+import {
+  CollModCall,
+  CreateCollectionCall,
+  CreateIndexCall,
+  DropCollectionCall,
+  DropIndexCall,
+  schemaCollectionToCreateCollectionOptions,
+  schemaIndexToCreateIndexOptions,
+} from './op-factory-call';
+import { renderOps } from './render-ops';
+
+function buildIndexLookupKey(index: MongoSchemaIndex): string {
+  const keys = index.keys.map((k) => `${k.field}:${k.direction}`).join(',');
+  const opts = [
+    index.unique ? 'unique' : '',
+    index.sparse ? 'sparse' : '',
+    index.expireAfterSeconds != null ? `ttl:${index.expireAfterSeconds}` : '',
+    index.partialFilterExpression ? `pfe:${canonicalize(index.partialFilterExpression)}` : '',
+    index.wildcardProjection ? `wp:${canonicalize(index.wildcardProjection)}` : '',
+    index.collation ? `col:${canonicalize(index.collation)}` : '',
+    index.weights ? `wt:${canonicalize(index.weights)}` : '',
+    index.default_language ? `dl:${index.default_language}` : '',
+    index.language_override ? `lo:${index.language_override}` : '',
+  ]
+    .filter(Boolean)
+    .join(';');
+  return opts ? `${keys}|${opts}` : keys;
+}
+
+function validatorsEqual(
+  a: MongoSchemaValidator | undefined,
+  b: MongoSchemaValidator | undefined,
+): boolean {
+  if (!a && !b) return true;
+  if (!a || !b) return false;
+  return (
+    a.validationLevel === b.validationLevel &&
+    a.validationAction === b.validationAction &&
+    canonicalize(a.jsonSchema) === canonicalize(b.jsonSchema)
+  );
+}
+
+function classifyValidatorUpdate(
+  origin: MongoSchemaValidator,
+  dest: MongoSchemaValidator,
+): 'widening' | 'destructive' {
+  let hasDestructive = false;
+
+  if (canonicalize(origin.jsonSchema) !== canonicalize(dest.jsonSchema)) {
+    hasDestructive = true;
+  }
+
+  if (origin.validationAction !== dest.validationAction) {
+    if (dest.validationAction === 'error') hasDestructive = true;
+  }
+
+  if (origin.validationLevel !== dest.validationLevel) {
+    if (dest.validationLevel === 'strict') hasDestructive = true;
+  }
+
+  return hasDestructive ? 'destructive' : 'widening';
+}
+
+function hasImmutableOptionChange(
+  origin: MongoSchemaCollectionOptions | undefined,
+  dest: MongoSchemaCollectionOptions | undefined,
+): string | undefined {
+  if (canonicalize(origin?.capped) !== canonicalize(dest?.capped)) return 'capped';
+  if (canonicalize(origin?.timeseries) !== canonicalize(dest?.timeseries)) return 'timeseries';
+  if (canonicalize(origin?.collation) !== canonicalize(dest?.collation)) return 'collation';
+  if (canonicalize(origin?.clusteredIndex) !== canonicalize(dest?.clusteredIndex))
+    return 'clusteredIndex';
+  return undefined;
+}
+
+function collectionHasOptions(coll: MongoSchemaCollection): boolean {
+  return !!(coll.options || coll.validator);
+}
+
+export type PlanCallsResult =
+  | { readonly kind: 'success'; readonly calls: OpFactoryCall[] }
+  | { readonly kind: 'failure'; readonly conflicts: MigrationPlannerConflict[] };
+
+export class MongoMigrationPlanner implements MigrationPlanner<'mongo', 'mongo'> {
+  planCalls(options: {
+    readonly contract: unknown;
+    readonly schema: unknown;
+    readonly policy: MigrationOperationPolicy;
+    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'mongo', 'mongo'>>;
+  }): PlanCallsResult {
+    const contract = options.contract as MongoContract;
+    const originIR = options.schema as MongoSchemaIR;
+    const destinationIR = contractToMongoSchemaIR(contract);
+
+    const collCreates: OpFactoryCall[] = [];
+    const drops: OpFactoryCall[] = [];
+    const creates: OpFactoryCall[] = [];
+    const validatorOps: OpFactoryCall[] = [];
+    const mutableOptionOps: OpFactoryCall[] = [];
+    const collDrops: OpFactoryCall[] = [];
+    const conflicts: MigrationPlannerConflict[] = [];
+
+    const allCollectionNames = new Set([
+      ...originIR.collectionNames,
+      ...destinationIR.collectionNames,
+    ]);
+
+    for (const collName of [...allCollectionNames].sort()) {
+      const originColl = originIR.collection(collName);
+      const destColl = destinationIR.collection(collName);
+
+      if (!originColl) {
+        if (destColl && collectionHasOptions(destColl)) {
+          const opts = schemaCollectionToCreateCollectionOptions(destColl);
+          collCreates.push(new CreateCollectionCall(collName, opts));
+        }
+      } else if (!destColl) {
+        collDrops.push(new DropCollectionCall(collName));
+      } else {
+        const immutableChange = hasImmutableOptionChange(originColl.options, destColl.options);
+        if (immutableChange) {
+          conflicts.push({
+            kind: 'policy-violation',
+            summary: `Cannot change immutable collection option '${immutableChange}' on ${collName}`,
+            why: `MongoDB does not support modifying the '${immutableChange}' option after collection creation`,
+          });
+        }
+
+        const mutableCall = planMutableOptionsDiffCall(
+          collName,
+          originColl.options,
+          destColl.options,
+        );
+        if (mutableCall) mutableOptionOps.push(mutableCall);
+
+        const validatorCall = planValidatorDiffCall(
+          collName,
+          originColl.validator,
+          destColl.validator,
+        );
+        if (validatorCall) validatorOps.push(validatorCall);
+      }
+
+      const originLookup = new Map<string, MongoSchemaIndex>();
+      if (originColl) {
+        for (const idx of originColl.indexes) {
+          originLookup.set(buildIndexLookupKey(idx), idx);
+        }
+      }
+
+      const destLookup = new Map<string, MongoSchemaIndex>();
+      if (destColl) {
+        for (const idx of destColl.indexes) {
+          destLookup.set(buildIndexLookupKey(idx), idx);
+        }
+      }
+
+      for (const [lookupKey, idx] of originLookup) {
+        if (!destLookup.has(lookupKey)) {
+          drops.push(new DropIndexCall(collName, idx.keys));
+        }
+      }
+
+      for (const [lookupKey, idx] of destLookup) {
+        if (!originLookup.has(lookupKey)) {
+          creates.push(
+            new CreateIndexCall(collName, idx.keys, schemaIndexToCreateIndexOptions(idx)),
+          );
+        }
+      }
+    }
+
+    if (conflicts.length > 0) {
+      return { kind: 'failure', conflicts };
+    }
+
+    const allCalls = [
+      ...collCreates,
+      ...drops,
+      ...creates,
+      ...validatorOps,
+      ...mutableOptionOps,
+      ...collDrops,
+    ];
+
+    for (const call of allCalls) {
+      if (!options.policy.allowedOperationClasses.includes(call.operationClass)) {
+        conflicts.push({
+          kind: 'policy-violation',
+          summary: `${call.operationClass} operation disallowed: ${call.label}`,
+          why: `Policy does not allow '${call.operationClass}' operations`,
+        });
+      }
+    }
+
+    if (conflicts.length > 0) {
+      return { kind: 'failure', conflicts };
+    }
+
+    return { kind: 'success', calls: allCalls };
+  }
+
+  plan(options: {
+    readonly contract: unknown;
+    readonly schema: unknown;
+    readonly policy: MigrationOperationPolicy;
+    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'mongo', 'mongo'>>;
+  }): MigrationPlannerResult {
+    const contract = options.contract as MongoContract;
+    const result = this.planCalls(options);
+    if (result.kind === 'failure') return result;
+    return {
+      kind: 'success',
+      plan: {
+        targetId: 'mongo',
+        destination: {
+          storageHash: contract.storage.storageHash,
+        },
+        operations: renderOps(result.calls),
+      },
+    };
+  }
+}
+
+function planValidatorDiffCall(
+  collName: string,
+  originValidator: MongoSchemaValidator | undefined,
+  destValidator: MongoSchemaValidator | undefined,
+): OpFactoryCall | undefined {
+  if (validatorsEqual(originValidator, destValidator)) return undefined;
+
+  if (destValidator) {
+    const operationClass: MigrationOperationClass = originValidator
+      ? classifyValidatorUpdate(originValidator, destValidator)
+      : 'destructive';
+    return new CollModCall(
+      collName,
+      {
+        validator: { $jsonSchema: destValidator.jsonSchema },
+        validationLevel: destValidator.validationLevel,
+        validationAction: destValidator.validationAction,
+      },
+      {
+        id: `validator.${collName}.${originValidator ? 'update' : 'add'}`,
+        label: `${originValidator ? 'Update' : 'Add'} validator on ${collName}`,
+        operationClass,
+      },
+    );
+  }
+
+  return new CollModCall(
+    collName,
+    {
+      validator: {},
+      validationLevel: 'strict',
+      validationAction: 'error',
+    },
+    {
+      id: `validator.${collName}.remove`,
+      label: `Remove validator on ${collName}`,
+      operationClass: 'widening',
+    },
+  );
+}
+
+function planMutableOptionsDiffCall(
+  collName: string,
+  origin: MongoSchemaCollectionOptions | undefined,
+  dest: MongoSchemaCollectionOptions | undefined,
+): OpFactoryCall | undefined {
+  const originCSPPI = origin?.changeStreamPreAndPostImages;
+  const destCSPPI = dest?.changeStreamPreAndPostImages;
+  if (deepEqual(originCSPPI, destCSPPI)) return undefined;
+
+  const desiredCSPPI = destCSPPI ?? { enabled: false };
+  return new CollModCall(
+    collName,
+    {
+      changeStreamPreAndPostImages: desiredCSPPI,
+    },
+    {
+      id: `options.${collName}.update`,
+      label: `Update mutable options on ${collName}`,
+      operationClass: desiredCSPPI.enabled ? 'widening' : 'destructive',
+    },
+  );
+}

package/src/core/mongo-runner.ts

@@ -0,0 +1,275 @@
+import type { ContractMarkerRecord } from '@prisma-next/contract/types';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type {
+  MigrationOperationPolicy,
+  MigrationPlan,
+  MigrationPlanOperation,
+  MigrationRunnerExecutionChecks,
+  MigrationRunnerFailure,
+  MigrationRunnerResult,
+} from '@prisma-next/framework-components/control';
+import type {
+  MongoDdlCommandVisitor,
+  MongoInspectionCommandVisitor,
+  MongoMigrationCheck,
+  MongoMigrationPlanOperation,
+} from '@prisma-next/mongo-query-ast/control';
+import { notOk, ok } from '@prisma-next/utils/result';
+import { FilterEvaluator } from './filter-evaluator';
+import { deserializeMongoOps } from './mongo-ops-serializer';
+
+export interface MarkerOperations {
+  readMarker(): Promise<ContractMarkerRecord | null>;
+  initMarker(destination: {
+    readonly storageHash: string;
+    readonly profileHash: string;
+  }): Promise<void>;
+  updateMarker(
+    expectedFrom: string,
+    destination: { readonly storageHash: string; readonly profileHash: string },
+  ): Promise<boolean>;
+  writeLedgerEntry(entry: {
+    readonly edgeId: string;
+    readonly from: string;
+    readonly to: string;
+  }): Promise<void>;
+}
+
+export interface MongoRunnerDependencies {
+  readonly commandExecutor: MongoDdlCommandVisitor<Promise<void>>;
+  readonly inspectionExecutor: MongoInspectionCommandVisitor<Promise<Record<string, unknown>[]>>;
+  readonly markerOps: MarkerOperations;
+}
+
+function runnerFailure(
+  code: string,
+  summary: string,
+  opts?: { why?: string; meta?: Record<string, unknown> },
+): MigrationRunnerResult {
+  return notOk<MigrationRunnerFailure>({
+    code,
+    summary,
+    ...opts,
+  });
+}
+
+export class MongoMigrationRunner {
+  constructor(private readonly deps: MongoRunnerDependencies) {}
+
+  async execute(options: {
+    readonly plan: MigrationPlan;
+    readonly destinationContract: unknown;
+    readonly policy: MigrationOperationPolicy;
+    readonly callbacks?: {
+      onOperationStart?(op: MigrationPlanOperation): void;
+      onOperationComplete?(op: MigrationPlanOperation): void;
+    };
+    readonly executionChecks?: MigrationRunnerExecutionChecks;
+    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'mongo', 'mongo'>>;
+  }): Promise<MigrationRunnerResult> {
+    const { commandExecutor, inspectionExecutor, markerOps } = this.deps;
+    const operations = deserializeMongoOps(options.plan.operations as readonly unknown[]);
+
+    const policyCheck = this.enforcePolicyCompatibility(options.policy, operations);
+    if (policyCheck) return policyCheck;
+
+    const existingMarker = await markerOps.readMarker();
+
+    const markerCheck = this.ensureMarkerCompatibility(existingMarker, options.plan);
+    if (markerCheck) return markerCheck;
+
+    const checks = options.executionChecks;
+    const runPrechecks = checks?.prechecks !== false;
+    const runPostchecks = checks?.postchecks !== false;
+    const runIdempotency = checks?.idempotencyChecks !== false;
+
+    const filterEvaluator = new FilterEvaluator();
+
+    let operationsExecuted = 0;
+
+    for (const operation of operations) {
+      options.callbacks?.onOperationStart?.(operation);
+      try {
+        if (runPostchecks && runIdempotency) {
+          const allSatisfied = await this.allChecksSatisfied(
+            operation.postcheck,
+            inspectionExecutor,
+            filterEvaluator,
+          );
+          if (allSatisfied) continue;
+        }
+
+        if (runPrechecks) {
+          const precheckResult = await this.evaluateChecks(
+            operation.precheck,
+            inspectionExecutor,
+            filterEvaluator,
+          );
+          if (!precheckResult) {
+            return runnerFailure(
+              'PRECHECK_FAILED',
+              `Operation ${operation.id} failed during precheck`,
+              { meta: { operationId: operation.id } },
+            );
+          }
+        }
+
+        for (const step of operation.execute) {
+          await step.command.accept(commandExecutor);
+        }
+
+        if (runPostchecks) {
+          const postcheckResult = await this.evaluateChecks(
+            operation.postcheck,
+            inspectionExecutor,
+            filterEvaluator,
+          );
+          if (!postcheckResult) {
+            return runnerFailure(
+              'POSTCHECK_FAILED',
+              `Operation ${operation.id} failed during postcheck`,
+              { meta: { operationId: operation.id } },
+            );
+          }
+        }
+
+        operationsExecuted += 1;
+      } finally {
+        options.callbacks?.onOperationComplete?.(operation);
+      }
+    }
+
+    const destination = options.plan.destination;
+    const contract = options.destinationContract as { profileHash?: string };
+    const profileHash = contract.profileHash ?? destination.storageHash;
+
+    if (
+      operationsExecuted === 0 &&
+      existingMarker?.storageHash === destination.storageHash &&
+      existingMarker.profileHash === profileHash
+    ) {
+      return ok({ operationsPlanned: operations.length, operationsExecuted });
+    }
+
+    if (existingMarker) {
+      const updated = await markerOps.updateMarker(existingMarker.storageHash, {
+        storageHash: destination.storageHash,
+        profileHash,
+      });
+      if (!updated) {
+        return runnerFailure(
+          'MARKER_CAS_FAILURE',
+          'Marker was modified by another process during migration execution.',
+          {
+            meta: {
+              expectedStorageHash: existingMarker.storageHash,
+              destinationStorageHash: destination.storageHash,
+            },
+          },
+        );
+      }
+    } else {
+      await markerOps.initMarker({
+        storageHash: destination.storageHash,
+        profileHash,
+      });
+    }
+
+    const originHash = existingMarker?.storageHash ?? '';
+    await markerOps.writeLedgerEntry({
+      edgeId: `${originHash}->${destination.storageHash}`,
+      from: originHash,
+      to: destination.storageHash,
+    });
+
+    return ok({ operationsPlanned: operations.length, operationsExecuted });
+  }
+
+  private async evaluateChecks(
+    checks: readonly MongoMigrationCheck[],
+    inspectionExecutor: MongoInspectionCommandVisitor<Promise<Record<string, unknown>[]>>,
+    filterEvaluator: FilterEvaluator,
+  ): Promise<boolean> {
+    for (const check of checks) {
+      const documents = await check.source.accept(inspectionExecutor);
+      const matchFound = documents.some((doc) =>
+        filterEvaluator.evaluate(check.filter, doc as Record<string, unknown>),
+      );
+      const passed = check.expect === 'exists' ? matchFound : !matchFound;
+      if (!passed) return false;
+    }
+    return true;
+  }
+
+  private async allChecksSatisfied(
+    checks: readonly MongoMigrationCheck[],
+    inspectionExecutor: MongoInspectionCommandVisitor<Promise<Record<string, unknown>[]>>,
+    filterEvaluator: FilterEvaluator,
+  ): Promise<boolean> {
+    if (checks.length === 0) return false;
+    return this.evaluateChecks(checks, inspectionExecutor, filterEvaluator);
+  }
+
+  private enforcePolicyCompatibility(
+    policy: MigrationOperationPolicy,
+    operations: readonly MongoMigrationPlanOperation[],
+  ): MigrationRunnerResult | undefined {
+    const allowedClasses = new Set(policy.allowedOperationClasses);
+    for (const operation of operations) {
+      if (!allowedClasses.has(operation.operationClass)) {
+        return runnerFailure(
+          'POLICY_VIOLATION',
+          `Operation ${operation.id} has class "${operation.operationClass}" which is not allowed by policy.`,
+          {
+            why: `Policy only allows: ${[...allowedClasses].join(', ')}.`,
+            meta: {
+              operationId: operation.id,
+              operationClass: operation.operationClass,
+            },
+          },
+        );
+      }
+    }
+    return undefined;
+  }
+
+  private ensureMarkerCompatibility(
+    marker: ContractMarkerRecord | null,
+    plan: MigrationPlan,
+  ): MigrationRunnerResult | undefined {
+    const origin = plan.origin ?? null;
+    if (!origin) {
+      if (marker) {
+        return runnerFailure(
+          'MARKER_ORIGIN_MISMATCH',
+          'Database already has a contract marker but the plan has no origin. This would silently overwrite the existing marker.',
+          { meta: { markerStorageHash: marker.storageHash } },
+        );
+      }
+      return undefined;
+    }
+
+    if (!marker) {
+      return runnerFailure(
+        'MARKER_ORIGIN_MISMATCH',
+        `Missing contract marker: expected origin storage hash ${origin.storageHash}.`,
+        { meta: { expectedOriginStorageHash: origin.storageHash } },
+      );
+    }
+
+    if (marker.storageHash !== origin.storageHash) {
+      return runnerFailure(
+        'MARKER_ORIGIN_MISMATCH',
+        `Existing contract marker (${marker.storageHash}) does not match plan origin (${origin.storageHash}).`,
+        {
+          meta: {
+            markerStorageHash: marker.storageHash,
+            expectedOriginStorageHash: origin.storageHash,
+          },
+        },
+      );
+    }
+
+    return undefined;
+  }
+}