@serve.zone/coremail 1.0.0

package/ts/classes.desiredstate.ts

@@ -0,0 +1,508 @@
+import * as plugins from './plugins.js';
+import { type ICoreMailModels } from './classes.models.js';
+import { CoreMailStorage, createSha256 } from './classes.storage.js';
+import { CoreMailTransferService } from './classes.transfer.js';
+import type { ICoreMailReplicaRuntime, ITransferAuthority } from './interfaces.js';
+import { logCoreMailFailure } from './coremail.log.js';
+import { withCoreMailTransaction } from './coremail.quota.js';
+import type {
+  ICoreMailDesiredSnapshotRecord,
+  ICoreMailStateRecord,
+} from './coremail.persistence.js';
+import {
+  requireCoreMailSafeInteger,
+  requireCoreMailUuid,
+} from './coremail.selectors.js';
+
+type TCoreMailSha256 = plugins.serveZoneInterfaces.data.TCoreMailSha256;
+type TCoreMailDesiredState = plugins.serveZoneInterfaces.data.ICoreMailDesiredState;
+type TCoreMailStatus = plugins.serveZoneInterfaces.data.ICoreMailReconciliationStatus;
+type TStoredState = plugins.smartdata.TStoredDocument<ICoreMailStateRecord>;
+type TStoredDesiredSnapshot =
+  plugins.smartdata.TStoredDocument<ICoreMailDesiredSnapshotRecord>;
+
+const emptyStateDigest = createSha256('');
+
+export class CoreMailDesiredStateService {
+  private activeDesiredState: TCoreMailDesiredState | null = null;
+  private activeStatePointer!: TStoredState;
+  private refreshTask: Promise<void> | null = null;
+
+  public constructor(
+    private readonly database: plugins.smartdata.SmartdataDb,
+    private readonly models: ICoreMailModels,
+    private readonly storage: CoreMailStorage,
+    private readonly transfers: CoreMailTransferService,
+    private readonly replica: ICoreMailReplicaRuntime,
+    private readonly activeSessionCounts: (
+      bindingArg: plugins.serveZoneInterfaces.data.ICoreMailBindingDesiredState,
+      configEpochArg: number,
+    ) => Array<{ credentialId: string; version: number; count: number }>,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  private controlAuthority(): ITransferAuthority {
+    return {
+      kind: 'control',
+      tenantId: '-',
+      serviceId: this.replica.serviceId,
+      bindingId: '-',
+    };
+  }
+
+  public async start(): Promise<void> {
+    const initialized = await this.models.State.exact.insert({
+      stateId: 'active',
+      appliedConfigEpoch: 0,
+      appliedDesiredStateDigest: emptyStateDigest,
+      snapshotId: '-',
+      updatedAt: this.now(),
+    });
+    const state = initialized.document;
+    if (!state) {
+      throw new Error('CoreMail could not initialize its desired-state pointer.');
+    }
+    this.activeStatePointer = state;
+    await this.refreshFromPointer(state);
+  }
+
+  public getActiveDesiredState = async (): Promise<TCoreMailDesiredState | null> => {
+    await this.refresh();
+    return this.activeDesiredState;
+  };
+
+  private async refresh(): Promise<void> {
+    if (this.refreshTask) {
+      await this.refreshTask;
+      return;
+    }
+    const task = (async () => {
+      const pointer = await this.models.State.exact.findStoredOne({
+        stateId: 'active',
+      });
+      if (!pointer) {
+        throw new Error('CoreMail desired-state pointer is unavailable.');
+      }
+      await this.refreshFromPointer(pointer);
+    })();
+    this.refreshTask = task;
+    try {
+      await task;
+    } finally {
+      if (this.refreshTask === task) {
+        this.refreshTask = null;
+      }
+    }
+  }
+
+  private async refreshFromPointer(pointerArg: TStoredState): Promise<void> {
+    if (pointerArg.appliedConfigEpoch === 0) {
+      this.activeStatePointer = pointerArg;
+      this.activeDesiredState = null;
+      return;
+    }
+    if (
+      this.activeDesiredState?.configEpoch === pointerArg.appliedConfigEpoch
+      && this.activeStatePointer?.snapshotId === pointerArg.snapshotId
+      && this.activeStatePointer.appliedDesiredStateDigest
+        === pointerArg.appliedDesiredStateDigest
+    ) {
+      this.activeStatePointer = pointerArg;
+      return;
+    }
+    const desiredState = await this.loadDesiredState(pointerArg);
+    this.activeStatePointer = pointerArg;
+    this.activeDesiredState = desiredState;
+  }
+
+  private async loadDesiredState(stateArg: TStoredState): Promise<TCoreMailDesiredState> {
+    const snapshot = await this.models.DesiredSnapshot.exact.findStoredOne({
+      snapshotId: stateArg.snapshotId,
+      configEpoch: stateArg.appliedConfigEpoch,
+      desiredStateDigest: stateArg.appliedDesiredStateDigest,
+    });
+    if (
+      !snapshot
+      || (snapshot.state !== 'staged' && snapshot.state !== 'active')
+    ) {
+      throw new Error('CoreMail active desired-state snapshot is unavailable.');
+    }
+    const bytes = await this.storage.getVerifiedBytes(
+      snapshot.objectKey,
+      snapshot.lengthBytes,
+      snapshot.desiredStateDigest,
+      plugins.serveZoneInterfaces.data.coreMailLimits.desiredStateBytes,
+    );
+    const desiredState = await this.parseDesiredState(
+      bytes,
+      snapshot.configEpoch,
+      snapshot.desiredStateDigest,
+    );
+    if (snapshot.state === 'staged') {
+      await this.models.DesiredSnapshot.exact.transition({
+        current: snapshot,
+        change: (modelArg) => {
+          modelArg.state = 'active';
+          modelArg.activatedAt = stateArg.updatedAt;
+        },
+      }).catch(async () => {
+        await logCoreMailFailure('desired-state', 'SNAPSHOT_REPAIR_FAILED')
+          .catch(() => undefined);
+      });
+    }
+    return desiredState;
+  }
+
+  private async parseDesiredState(
+    bytesArg: Uint8Array,
+    configEpochArg: number,
+    digestArg: TCoreMailSha256,
+  ): Promise<TCoreMailDesiredState> {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytesArg));
+    } catch {
+      throw new Error('CoreMail desired state is not canonical UTF-8 JSON.');
+    }
+    const desiredState =
+      plugins.serveZoneInterfaces.data.normalizeCoreMailDesiredState(parsed);
+    if (
+      desiredState.configEpoch !== configEpochArg
+      || !await plugins.serveZoneInterfaces.data.verifyCoreMailDesiredStateDigest(
+        desiredState,
+        digestArg,
+      )
+    ) {
+      throw new Error('CoreMail desired-state digest or epoch does not match.');
+    }
+    const canonical = plugins.serveZoneInterfaces.data.canonicalizeCoreMailDesiredState(
+      desiredState,
+    );
+    if (!Buffer.from(bytesArg).equals(Buffer.from(canonical, 'utf8'))) {
+      throw new Error('CoreMail desired-state bytes are not canonical.');
+    }
+    return desiredState;
+  }
+
+  public async prepare(
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailPrepareDesiredStateUpload['request'],
+  ): Promise<{
+    reconciliationId: string;
+    grant: plugins.serveZoneInterfaces.data.ICoreMailUploadGrant;
+    replayed: boolean;
+  }> {
+    await this.refresh();
+    const desiredStateDigest =
+      plugins.serveZoneInterfaces.data.normalizeCoreMailSha256(
+        requestArg.desiredStateDigest,
+      );
+    const expectedAppliedConfigEpoch = requireCoreMailSafeInteger(
+      requestArg.expectedAppliedConfigEpoch,
+      'expectedAppliedConfigEpoch',
+    );
+    const configEpoch = requireCoreMailSafeInteger(
+      requestArg.configEpoch,
+      'configEpoch',
+      1,
+    );
+    if (
+      configEpoch <= expectedAppliedConfigEpoch
+      || !Number.isSafeInteger(requestArg.lengthBytes)
+      || requestArg.lengthBytes < 2
+      || requestArg.lengthBytes >
+        plugins.serveZoneInterfaces.data.coreMailLimits.desiredStateBytes
+    ) {
+      throw new Error('CoreMail desired-state preparation is invalid.');
+    }
+    const current = await this.models.State.exact.findStoredOne({
+      stateId: 'active',
+      appliedConfigEpoch: expectedAppliedConfigEpoch,
+    });
+    if (!current || current.appliedConfigEpoch !== this.activeStatePointer.appliedConfigEpoch) {
+      throw new Error('CoreMail desired-state compare-and-set fence changed.');
+    }
+    let snapshot = await this.models.DesiredSnapshot.exact.findStoredOne({
+      configEpoch,
+      desiredStateDigest,
+    });
+    let replayed = Boolean(snapshot);
+    if (snapshot) {
+      if (
+        snapshot.expectedAppliedConfigEpoch !== expectedAppliedConfigEpoch
+        || snapshot.lengthBytes !== requestArg.lengthBytes
+        || (snapshot.state !== 'staged' && snapshot.state !== 'active')
+      ) {
+        throw new Error('CoreMail desired-state replay conflicts with persisted intent.');
+      }
+    } else {
+      const snapshotId = plugins.nodeCrypto.randomUUID();
+      const createdAt = this.now();
+      const candidate: ICoreMailDesiredSnapshotRecord = {
+        snapshotId,
+        reconciliationId: plugins.nodeCrypto.randomUUID(),
+        expectedAppliedConfigEpoch,
+        configEpoch,
+        desiredStateDigest,
+        lengthBytes: requestArg.lengthBytes,
+        objectKey: `desired-state/${snapshotId}.json`,
+        state: 'staged',
+        createdAt,
+        updatedAt: createdAt,
+      };
+      try {
+        const inserted = await this.models.DesiredSnapshot.exact.insert(candidate);
+        if (inserted.status === 'conflict') {
+          throw new Error(
+            'CoreMail desired-state preparation conflicts with persisted intent.',
+          );
+        }
+        snapshot = inserted.document;
+      } catch (error) {
+        if (
+          !(error instanceof plugins.smartdata.SmartdataExactPersistenceError)
+          || error.code !== 'unique_conflict'
+        ) {
+          throw error;
+        }
+        const concurrent =
+          await this.models.DesiredSnapshot.exact.findStoredOne({
+          configEpoch,
+          desiredStateDigest,
+        });
+        if (
+          !concurrent
+          || concurrent.expectedAppliedConfigEpoch
+            !== expectedAppliedConfigEpoch
+          || concurrent.lengthBytes !== requestArg.lengthBytes
+          || (concurrent.state !== 'staged' && concurrent.state !== 'active')
+        ) {
+          throw new Error(
+            'CoreMail desired-state preparation conflicts with persisted intent.',
+          );
+        }
+        snapshot = concurrent;
+        replayed = true;
+      }
+    }
+    if (snapshot.state === 'staged') {
+      const touchedAt = this.now();
+      const touch = await this.models.DesiredSnapshot.exact.transition({
+        current: snapshot,
+        change: (modelArg) => {
+          modelArg.updatedAt = touchedAt;
+        },
+      });
+      if (touch.status !== 'transitioned') {
+        throw new Error('CoreMail desired-state preparation fence changed.');
+      }
+      snapshot = touch.document;
+    }
+    const grant = await this.transfers.issueGrant({
+      authority: this.controlAuthority(),
+      purpose: 'desired-state-upload',
+      method: 'PUT',
+      expectedSha256: snapshot.desiredStateDigest,
+      lengthBytes: snapshot.lengthBytes,
+      contentType: 'application/json',
+      objectKey: snapshot.objectKey,
+    });
+    return {
+      reconciliationId: snapshot.reconciliationId,
+      grant: grant as plugins.serveZoneInterfaces.data.ICoreMailUploadGrant,
+      replayed,
+    };
+  }
+
+  public async apply(
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailApplyDesiredState['request'],
+  ): Promise<TCoreMailStatus> {
+    await this.refresh();
+    const desiredStateDigest =
+      plugins.serveZoneInterfaces.data.normalizeCoreMailSha256(
+        requestArg.desiredStateDigest,
+      );
+    const reconciliationId = requireCoreMailUuid(
+      requestArg.reconciliationId,
+      'reconciliationId',
+    );
+    const grantId = requireCoreMailUuid(requestArg.grantId, 'grantId');
+    const lengthBytes = requireCoreMailSafeInteger(
+      requestArg.lengthBytes,
+      'lengthBytes',
+      2,
+    );
+    const snapshot = await this.models.DesiredSnapshot.exact.findStoredOne({
+      reconciliationId,
+      desiredStateDigest,
+      lengthBytes,
+    });
+    if (!snapshot || (snapshot.state !== 'staged' && snapshot.state !== 'active')) {
+      throw new Error('CoreMail desired-state reconciliation is unavailable.');
+    }
+    await this.transfers.assertConsumed({
+      grantId,
+      authority: this.controlAuthority(),
+      purpose: 'desired-state-upload',
+      expectedSha256: desiredStateDigest,
+      lengthBytes,
+      objectKey: snapshot.objectKey,
+    });
+    const bytes = await this.storage.getVerifiedBytes(
+      snapshot.objectKey,
+      snapshot.lengthBytes,
+      snapshot.desiredStateDigest,
+      plugins.serveZoneInterfaces.data.coreMailLimits.desiredStateBytes,
+    );
+    const desiredState = await this.parseDesiredState(
+      bytes,
+      snapshot.configEpoch,
+      snapshot.desiredStateDigest,
+    );
+    if (
+      snapshot.state === 'active'
+      && this.activeStatePointer.snapshotId === snapshot.snapshotId
+    ) {
+      return await this.createStatus('ready', desiredState);
+    }
+    const activatedAt = this.now();
+    const activation = await withCoreMailTransaction(
+      this.database,
+      async (transactionArg) => {
+        const transactionSnapshot =
+          await this.models.DesiredSnapshot.exact.findStoredOne({
+            snapshotId: snapshot.snapshotId,
+            reconciliationId: snapshot.reconciliationId,
+            state: 'staged',
+          }, { session: transactionArg });
+        const current = await this.models.State.exact.findStoredOne({
+          stateId: 'active',
+          appliedConfigEpoch: snapshot.expectedAppliedConfigEpoch,
+        }, { session: transactionArg });
+        if (
+          !transactionSnapshot
+          || !current
+          || snapshot.configEpoch <= current.appliedConfigEpoch
+          || current.snapshotId !== this.activeStatePointer.snapshotId
+          || current.appliedDesiredStateDigest
+            !== this.activeStatePointer.appliedDesiredStateDigest
+        ) {
+          throw new Error('CoreMail desired-state anti-rollback fence changed.');
+        }
+        const snapshotActivation =
+          await this.models.DesiredSnapshot.exact.transition({
+            current: transactionSnapshot,
+            change: (modelArg) => {
+              modelArg.state = 'active';
+              modelArg.activatedAt = activatedAt;
+              modelArg.updatedAt = activatedAt;
+            },
+          }, { session: transactionArg });
+        if (snapshotActivation.status !== 'transitioned') {
+          throw new Error('CoreMail desired-state snapshot activation was contended.');
+        }
+        if (current.snapshotId !== '-') {
+          const prior = await this.models.DesiredSnapshot.exact.findStoredOne({
+            snapshotId: current.snapshotId,
+          }, { session: transactionArg });
+          if (!prior) {
+            throw new Error('CoreMail prior desired-state snapshot is unavailable.');
+          }
+          const superseded = await this.models.DesiredSnapshot.exact.transition({
+            current: prior,
+            change: (modelArg) => {
+              modelArg.state = 'superseded';
+              modelArg.activatedAt ??= current.updatedAt;
+              modelArg.updatedAt = activatedAt;
+            },
+          }, { session: transactionArg });
+          if (superseded.status !== 'transitioned') {
+            throw new Error('CoreMail prior desired-state snapshot was contended.');
+          }
+        }
+        const pointerActivation = await this.models.State.exact.transition({
+          current,
+          change: (modelArg) => {
+            modelArg.appliedConfigEpoch = snapshot.configEpoch;
+            modelArg.appliedDesiredStateDigest = snapshot.desiredStateDigest;
+            modelArg.snapshotId = snapshot.snapshotId;
+            modelArg.updatedAt = activatedAt;
+          },
+        }, { session: transactionArg });
+        if (pointerActivation.status !== 'transitioned') {
+          throw new Error('CoreMail desired-state activation was contended.');
+        }
+        return pointerActivation.document;
+      },
+    );
+    this.activeStatePointer = activation;
+    this.activeDesiredState = desiredState;
+    return await this.createStatus('ready', desiredState);
+  }
+
+  public async getStatus(
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailGetReconciliationStatus['request'],
+  ): Promise<TCoreMailStatus> {
+    await this.refresh();
+    if (this.activeStatePointer.appliedConfigEpoch === 0) {
+      throw new Error('CoreMail has no applied desired state.');
+    }
+    const digest = plugins.serveZoneInterfaces.data.normalizeCoreMailSha256(
+      requestArg.desiredStateDigest,
+    );
+    if (
+      this.activeDesiredState?.configEpoch === requestArg.configEpoch
+      && this.activeStatePointer.appliedDesiredStateDigest === digest
+    ) {
+      return await this.createStatus('ready', this.activeDesiredState);
+    }
+    const snapshot = await this.models.DesiredSnapshot.exact.findStoredOne({
+      configEpoch: requestArg.configEpoch,
+      desiredStateDigest: digest,
+    });
+    return await this.createStatus(
+      snapshot?.state === 'staged' ? 'applying' : 'failed',
+      this.activeDesiredState,
+      snapshot?.errorCode ?? 'RECONCILIATION_FENCE_MISMATCH',
+    );
+  }
+
+  private async createStatus(
+    stateArg: plugins.serveZoneInterfaces.data.TCoreMailReconciliationState,
+    desiredStateArg: TCoreMailDesiredState | null,
+    errorCodeArg?: plugins.serveZoneInterfaces.data.TCoreMailErrorCode,
+  ): Promise<TCoreMailStatus> {
+    const bindings = await Promise.all(
+      (desiredStateArg?.bindings ?? []).map(async (bindingArg) => ({
+        bindingId: bindingArg.bindingId,
+        revision: bindingArg.revision,
+        state: bindingArg.state,
+        pendingInboundCount: await this.models.InboundDelivery.exact.count({
+          tenantId: bindingArg.tenantId,
+          serviceId: bindingArg.serviceId,
+          bindingId: bindingArg.bindingId,
+          bindingRevision: bindingArg.revision,
+          state: {
+            $in: [...plugins.serveZoneInterfaces.data.coreMailQuotaPolicy
+              .pendingInboundStates],
+          },
+        }),
+        activeSessionsByCredential: this.activeSessionCounts(
+          bindingArg,
+          desiredStateArg!.configEpoch,
+        ),
+      })),
+    );
+    return {
+      replica: { ...this.replica },
+      state: stateArg,
+      appliedConfigEpoch: this.activeStatePointer.appliedConfigEpoch,
+      appliedDesiredStateDigest: this.activeStatePointer.appliedDesiredStateDigest,
+      bindings,
+      updatedAt: this.now(),
+      ...(errorCodeArg ? { errorCode: errorCodeArg } : {}),
+    };
+  }
+}