@serve.zone/coremail 1.0.0

package/ts/classes.submissions.ts

@@ -0,0 +1,554 @@
+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 {
+  createCoreMailSubmissionDigest,
+  normalizeCoreMailOutboundMessage,
+} from './coremail.validation.js';
+import { createCoreMailMime } from './coremail.mime.js';
+import {
+  createCoreMailOutboundQuotaDescriptors,
+  ensureCoreMailQuotaCounter,
+  incrementCoreMailQuotaCounter,
+  withCoreMailTransaction,
+} from './coremail.quota.js';
+import {
+  requireCoreMailIdentifier,
+  requireCoreMailUuid,
+} from './coremail.selectors.js';
+import type { ICoreMailSubmissionRecord } from './coremail.persistence.js';
+import type {
+  ICoreMailWorkloadSession,
+  ISubmissionPartRecord,
+  ITransferAuthority,
+} from './interfaces.js';
+
+type TBinding = plugins.serveZoneInterfaces.data.ICoreMailBindingDesiredState;
+type TSubmission = plugins.serveZoneInterfaces.data.ICoreMailSubmission;
+type TStoredSubmission =
+  plugins.smartdata.TStoredDocument<ICoreMailSubmissionRecord>;
+
+const maximumPartBytes = plugins.serveZoneInterfaces.data.coreMailLimits.attachmentBytes;
+
+const authorityFilter = (
+  sessionArg: ICoreMailWorkloadSession,
+  submissionIdArg: string | undefined,
+) => ({
+  tenantId: requireCoreMailIdentifier(sessionArg.tenantId, 'session.tenantId'),
+  serviceId: requireCoreMailIdentifier(sessionArg.serviceId, 'session.serviceId'),
+  bindingId: requireCoreMailIdentifier(sessionArg.bindingId, 'session.bindingId'),
+  bindingRevision: sessionArg.bindingRevision,
+  ...(submissionIdArg === undefined
+    ? {}
+    : { submissionId: requireCoreMailUuid(submissionIdArg, 'submissionId') }),
+});
+
+const workloadAuthority = (
+  sessionArg: ICoreMailWorkloadSession,
+): ITransferAuthority => ({
+  kind: 'workload',
+  tenantId: sessionArg.tenantId,
+  serviceId: sessionArg.serviceId,
+  bindingId: sessionArg.bindingId,
+});
+
+const toPublicSubmission = (
+  submissionArg: ICoreMailSubmissionRecord,
+): TSubmission => plugins.serveZoneInterfaces.data.normalizeCoreMailSubmission({
+    submissionId: submissionArg.submissionId,
+    idempotencyKey: submissionArg.idempotencyKey,
+    submissionDigest: submissionArg.submissionDigest,
+    state: submissionArg.state,
+    parts: submissionArg.parts.map((partArg) => ({
+      partId: partArg.partId,
+      state: partArg.state,
+      sha256: partArg.sha256,
+      lengthBytes: partArg.lengthBytes,
+    })),
+    ...(submissionArg.transportMessageId
+      ? { transportMessageId: submissionArg.transportMessageId }
+      : {}),
+    attempts: submissionArg.attempts,
+    ...(submissionArg.nextAttemptAt === undefined
+      || submissionArg.state !== 'deferred'
+      ? {}
+      : { nextAttemptAt: submissionArg.nextAttemptAt }),
+    ...(submissionArg.error === undefined ? {} : { error: submissionArg.error }),
+    ...(submissionArg.acceptedAt === undefined
+      ? {}
+      : { acceptedAt: submissionArg.acceptedAt }),
+    ...(submissionArg.deliveredAt === undefined
+      ? {}
+      : { deliveredAt: submissionArg.deliveredAt }),
+    ...(submissionArg.terminalAt === undefined
+      ? {}
+      : { terminalAt: submissionArg.terminalAt }),
+    createdAt: submissionArg.createdAt,
+    updatedAt: submissionArg.updatedAt,
+  });
+
+const isUniqueConflict = (errorArg: unknown): boolean =>
+  errorArg instanceof plugins.smartdata.SmartdataExactPersistenceError
+  && errorArg.code === 'unique_conflict';
+
+export class CoreMailSubmissionService {
+  public constructor(
+    private readonly database: plugins.smartdata.SmartdataDb,
+    private readonly models: ICoreMailModels,
+    private readonly storage: CoreMailStorage,
+    private readonly transfers: CoreMailTransferService,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  public async prepare(
+    sessionArg: ICoreMailWorkloadSession,
+    bindingArg: TBinding,
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailPrepareOutboundSubmission['request'],
+  ): Promise<{ submission: TSubmission; replayed: boolean }> {
+    const message = normalizeCoreMailOutboundMessage(requestArg.message, bindingArg);
+    const submissionDigest = createCoreMailSubmissionDigest(
+      requestArg.idempotencyKey,
+      message,
+    );
+    const replay = await this.models.Submission.exact.findStoredOne({
+      ...authorityFilter(sessionArg, undefined),
+      idempotencyKey: requestArg.idempotencyKey,
+    });
+    if (replay) {
+      if (replay.submissionDigest !== submissionDigest) {
+        throw new Error('CoreMail idempotency key conflicts with persisted intent.');
+      }
+      return { submission: toPublicSubmission(replay), replayed: true };
+    }
+
+    const submissionId = plugins.nodeCrypto.randomUUID();
+    const createdAt = this.now();
+    const parts: ISubmissionPartRecord[] = message.parts.map((partArg) => ({
+      ...partArg,
+      objectKey: `outbound-parts/${submissionId}/${plugins.nodeCrypto.randomUUID()}`,
+      state: 'missing',
+    }));
+    const submission: ICoreMailSubmissionRecord = {
+      submissionId,
+      tenantId: sessionArg.tenantId,
+      serviceId: sessionArg.serviceId,
+      bindingId: sessionArg.bindingId,
+      bindingRevision: sessionArg.bindingRevision,
+      revision: 0,
+      idempotencyKey: requestArg.idempotencyKey,
+      submissionDigest,
+      state: 'preparing',
+      message,
+      parts,
+      attempts: 0,
+      createdAt,
+      updatedAt: createdAt,
+    };
+    const quotaNow = this.now();
+    const quota = createCoreMailOutboundQuotaDescriptors({
+      tenantId: sessionArg.tenantId,
+      serviceId: sessionArg.serviceId,
+      bindingId: sessionArg.bindingId,
+      bindingRevision: sessionArg.bindingRevision,
+    }, quotaNow);
+    await ensureCoreMailQuotaCounter(this.models, quota.minute);
+    await ensureCoreMailQuotaCounter(this.models, quota.day);
+    try {
+      const transactionResult = await withCoreMailTransaction(
+        this.database,
+        async (transactionArg) => {
+          const transactionReplay = await this.models.Submission.exact.findStoredOne(
+            {
+              ...authorityFilter(sessionArg, undefined),
+              idempotencyKey: requestArg.idempotencyKey,
+            },
+            { session: transactionArg },
+          );
+          if (transactionReplay) {
+            if (transactionReplay.submissionDigest !== submissionDigest) {
+              throw new Error('CoreMail idempotency key conflicts with persisted intent.');
+            }
+            return { submissionId: transactionReplay.submissionId, replayed: true };
+          }
+          await incrementCoreMailQuotaCounter(
+            this.models,
+            quota.day,
+            bindingArg.limits.messagesPerDay,
+            quotaNow,
+            transactionArg,
+            quota.dayRetryAfterMs,
+          );
+          await incrementCoreMailQuotaCounter(
+            this.models,
+            quota.minute,
+            bindingArg.limits.messagesPerMinute,
+            quotaNow,
+            transactionArg,
+            quota.minuteRetryAfterMs,
+          );
+          const inserted = await this.models.Submission.exact.insert(
+            submission,
+            { session: transactionArg },
+          );
+          if (inserted.status === 'conflict') {
+            throw new Error('CoreMail submission identity conflicts with persisted intent.');
+          }
+          return { submissionId, replayed: inserted.status === 'already_committed' };
+        },
+      );
+      const committed = await this.models.Submission.exact.findStoredOne({
+        ...authorityFilter(sessionArg, transactionResult.submissionId),
+      });
+      if (!committed || committed.submissionDigest !== submissionDigest) {
+        throw new Error('CoreMail committed submission is unavailable.');
+      }
+      return {
+        submission: toPublicSubmission(committed),
+        replayed: transactionResult.replayed,
+      };
+    } catch (error) {
+      if (!isUniqueConflict(error)) {
+        throw error;
+      }
+      const concurrent = await this.models.Submission.exact.findStoredOne({
+        ...authorityFilter(sessionArg, undefined),
+        idempotencyKey: requestArg.idempotencyKey,
+      });
+      if (!concurrent || concurrent.submissionDigest !== submissionDigest) {
+        throw new Error('CoreMail idempotency key conflicts with persisted intent.');
+      }
+      return { submission: toPublicSubmission(concurrent), replayed: true };
+    }
+  }
+
+  public async preparePartUpload(
+    sessionArg: ICoreMailWorkloadSession,
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailPrepareOutboundPartUpload['request'],
+  ): Promise<{ grant: plugins.serveZoneInterfaces.data.ICoreMailUploadGrant }> {
+    const submission = await this.requireSubmission(
+      sessionArg,
+      requestArg.submissionId,
+    );
+    if (
+      submission.state !== 'preparing'
+      && submission.state !== 'uploading'
+      && submission.state !== 'ready'
+    ) {
+      throw new Error('CoreMail submission no longer accepts part uploads.');
+    }
+    const partIndex = submission.parts.findIndex(
+      (partArg) => partArg.partId === requireCoreMailIdentifier(
+        requestArg.partId,
+        'partId',
+      ),
+    );
+    if (partIndex < 0) {
+      throw new Error('CoreMail submission part is unavailable.');
+    }
+    const part = submission.parts[partIndex];
+    if (part.state === 'complete') {
+      throw new Error('CoreMail submission part is already complete.');
+    }
+    const grant = await this.transfers.issueGrant({
+      authority: workloadAuthority(sessionArg),
+      purpose: 'outbound-part-upload',
+      method: 'PUT',
+      expectedSha256: part.sha256,
+      lengthBytes: part.lengthBytes,
+      contentType: part.contentType,
+      objectKey: part.objectKey,
+    });
+    const parts = submission.parts.map((partArg, indexArg) =>
+      indexArg === partIndex
+        ? { ...partArg, state: 'uploading' as const, grantId: grant.grantId }
+        : partArg
+    );
+    const updatedAt = this.now();
+    const update = await this.models.Submission.exact.transition({
+      current: submission,
+      change: (modelArg) => {
+        modelArg.parts = parts;
+        modelArg.state = 'uploading';
+        modelArg.updatedAt = updatedAt;
+        modelArg.revision += 1;
+      },
+    });
+    if (update.status !== 'transitioned') {
+      throw new Error('CoreMail submission part upload fence changed.');
+    }
+    return {
+      grant: grant as plugins.serveZoneInterfaces.data.ICoreMailUploadGrant,
+    };
+  }
+
+  public async completePartUpload(
+    sessionArg: ICoreMailWorkloadSession,
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailCompleteOutboundPartUpload['request'],
+  ): Promise<{ submission: TSubmission }> {
+    const submission = await this.requireSubmission(
+      sessionArg,
+      requestArg.submissionId,
+    );
+    const partIndex = submission.parts.findIndex(
+      (partArg) => partArg.partId === requireCoreMailIdentifier(
+        requestArg.partId,
+        'partId',
+      ),
+    );
+    if (partIndex < 0) {
+      throw new Error('CoreMail submission part is unavailable.');
+    }
+    const part = submission.parts[partIndex];
+    const sha256 = plugins.serveZoneInterfaces.data.normalizeCoreMailSha256(
+      requestArg.sha256,
+    );
+    if (
+      (part.state !== 'uploading' && part.state !== 'complete')
+      || part.sha256 !== sha256
+      || part.lengthBytes !== requestArg.lengthBytes
+    ) {
+      throw new Error('CoreMail submission part completion is invalid.');
+    }
+    await this.transfers.assertConsumed({
+      grantId: requestArg.grantId,
+      authority: workloadAuthority(sessionArg),
+      purpose: 'outbound-part-upload',
+      expectedSha256: part.sha256,
+      lengthBytes: part.lengthBytes,
+      objectKey: part.objectKey,
+    });
+    if (part.state === 'complete') {
+      return { submission: toPublicSubmission(submission) };
+    }
+    const parts = submission.parts.map((partArg, indexArg) =>
+      indexArg === partIndex
+        ? {
+            ...partArg,
+            state: 'complete' as const,
+            grantId: requestArg.grantId,
+          }
+        : partArg
+    );
+    const allComplete = parts.every((partArg) => partArg.state === 'complete');
+    const updatedAt = this.now();
+    const update = await this.models.Submission.exact.transition({
+      current: submission,
+      change: (modelArg) => {
+        modelArg.parts = parts;
+        modelArg.state = allComplete ? 'ready' : 'uploading';
+        modelArg.updatedAt = updatedAt;
+        modelArg.revision += 1;
+      },
+    });
+    if (update.status !== 'transitioned') {
+      throw new Error('CoreMail submission part completion fence changed.');
+    }
+    return {
+      submission: toPublicSubmission(update.document),
+    };
+  }
+
+  public async finalize(
+    sessionArg: ICoreMailWorkloadSession,
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailFinalizeOutboundSubmission['request'],
+  ): Promise<{ submission: TSubmission }> {
+    const submission = await this.requireSubmission(
+      sessionArg,
+      requestArg.submissionId,
+    );
+    if (
+      submission.state === 'accepted'
+      || submission.state === 'queued'
+      || submission.state === 'delivering'
+      || submission.state === 'delivered'
+      || submission.state === 'deferred'
+      || submission.state === 'failed'
+      || submission.state === 'deadLettered'
+    ) {
+      return { submission: toPublicSubmission(submission) };
+    }
+    if (
+      submission.state !== 'ready'
+      || !submission.parts.every((partArg) => partArg.state === 'complete')
+    ) {
+      throw new Error('CoreMail submission is not ready for finalization.');
+    }
+    if (
+      submission.mimeObjectKey
+      && submission.mimeSha256
+      && submission.mimeLengthBytes !== undefined
+      && submission.mimePublishedAt !== undefined
+      && (
+        submission.workerRetryAt !== undefined
+        || (
+          submission.leaseOwnerTaskId !== undefined
+          && submission.leaseOwnerTaskId !== 'submission-finalizer'
+          && submission.leaseExpiresAt !== undefined
+          && submission.leaseExpiresAt > this.now()
+        )
+      )
+    ) {
+      return { submission: toPublicSubmission(submission) };
+    }
+    const content = await Promise.all(
+      submission.parts.map(async (partArg) => ({
+        descriptor: partArg,
+        bytes: await this.storage.getVerifiedBytes(
+          partArg.objectKey,
+          partArg.lengthBytes,
+          partArg.sha256,
+          maximumPartBytes,
+        ),
+      })),
+    );
+    const mimeBytes = createCoreMailMime(
+      submission.submissionId,
+      submission.submissionDigest,
+      submission.createdAt,
+      submission.message,
+      content,
+    );
+    const mimeObjectKey =
+      `outbound-mime/${submission.submissionId}/${submission.submissionDigest.slice(7)}`;
+    const mimeSha256 = createSha256(mimeBytes);
+    const mimeLengthBytes = mimeBytes.byteLength;
+    if (mimeLengthBytes > plugins.serveZoneInterfaces.data.coreMailLimits.serializedMimeBytes) {
+      throw new Error('CoreMail serialized MIME exceeds its byte budget.');
+    }
+    if (
+      submission.mimeObjectKey !== undefined
+      && (
+        submission.mimeObjectKey !== mimeObjectKey
+        || submission.mimeSha256 !== mimeSha256
+        || submission.mimeLengthBytes !== mimeLengthBytes
+      )
+    ) {
+      throw new Error('CoreMail submission MIME ownership conflicts.');
+    }
+    if (
+      submission.mimeObjectKey === mimeObjectKey
+      && submission.leaseExpiresAt !== undefined
+      && submission.leaseExpiresAt > this.now()
+    ) {
+      if (submission.leaseOwnerTaskId !== 'submission-finalizer') {
+        return { submission: toPublicSubmission(submission) };
+      }
+      throw new Error('CoreMail submission finalization is already in progress.');
+    }
+    const leaseToken = plugins.nodeCrypto.randomUUID();
+    const claimAt = this.now();
+    const claim = await this.models.Submission.exact.transition({
+      current: submission,
+      change: (modelArg) => {
+        modelArg.mimeObjectKey = mimeObjectKey;
+        modelArg.mimeSha256 = mimeSha256;
+        modelArg.mimeLengthBytes = mimeLengthBytes;
+        modelArg.leaseOwnerTaskId = 'submission-finalizer';
+        modelArg.leaseToken = leaseToken;
+        modelArg.leaseExpiresAt = claimAt
+          + plugins.serveZoneInterfaces.data.coreMailLimits.transferOverallTimeoutMs
+          + 2 * 60_000;
+        modelArg.updatedAt = claimAt;
+        modelArg.revision += 1;
+        delete modelArg.mimePublishedAt;
+        delete modelArg.workerRetryAt;
+      },
+    });
+    if (claim.status !== 'transitioned') {
+      const replay = await this.requireSubmission(
+        sessionArg,
+        submission.submissionId,
+      );
+      if (
+        replay.submissionDigest === submission.submissionDigest
+        && replay.mimeObjectKey === mimeObjectKey
+        && replay.mimeSha256 === mimeSha256
+        && replay.mimeLengthBytes === mimeLengthBytes
+        && (
+          replay.workerRetryAt !== undefined
+          || replay.leaseOwnerTaskId !== 'submission-finalizer'
+        )
+      ) {
+        return { submission: toPublicSubmission(replay) };
+      }
+      throw new Error('CoreMail submission finalization fence changed.');
+    }
+    const mime = await this.storage.putBytesExact(
+      mimeObjectKey,
+      mimeBytes,
+      'message/rfc822',
+      plugins.serveZoneInterfaces.data.coreMailLimits.serializedMimeBytes,
+      AbortSignal.timeout(
+        plugins.serveZoneInterfaces.data.coreMailLimits.transferOverallTimeoutMs,
+      ),
+    );
+    if (mime.sha256 !== mimeSha256 || mime.lengthBytes !== mimeLengthBytes) {
+      throw new Error('CoreMail published MIME integrity conflicts.');
+    }
+    const queuedAt = this.now();
+    const update = await this.models.Submission.exact.transition({
+      current: claim.document,
+      change: (modelArg) => {
+        modelArg.mimePublishedAt = queuedAt;
+        modelArg.workerRetryAt = queuedAt;
+        modelArg.updatedAt = queuedAt;
+        modelArg.revision += 1;
+        delete modelArg.leaseOwnerTaskId;
+        delete modelArg.leaseToken;
+        delete modelArg.leaseExpiresAt;
+      },
+    });
+    if (update.status !== 'transitioned') {
+      const replay = await this.requireSubmission(
+        sessionArg,
+        submission.submissionId,
+      ).catch(() => undefined);
+      if (
+        replay?.submissionDigest === submission.submissionDigest
+        && replay.mimeObjectKey === mimeObjectKey
+        && replay.mimeSha256 === mime.sha256
+        && replay.mimeLengthBytes === mime.lengthBytes
+        && (
+          replay.workerRetryAt !== undefined
+          || replay.leaseOwnerTaskId !== 'submission-finalizer'
+        )
+      ) {
+        return { submission: toPublicSubmission(replay) };
+      }
+      throw new Error('CoreMail submission finalization fence changed.');
+    }
+    return {
+      submission: toPublicSubmission(update.document),
+    };
+  }
+
+  public async get(
+    sessionArg: ICoreMailWorkloadSession,
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailGetOutboundSubmission['request'],
+  ): Promise<{ submission: TSubmission }> {
+    return {
+      submission: toPublicSubmission(
+        await this.requireSubmission(sessionArg, requestArg.submissionId),
+      ),
+    };
+  }
+
+  private async requireSubmission(
+    sessionArg: ICoreMailWorkloadSession,
+    submissionIdArg: string,
+  ): Promise<TStoredSubmission> {
+    const submission = await this.models.Submission.exact.findStoredOne({
+      ...authorityFilter(sessionArg, submissionIdArg),
+    });
+    if (!submission) {
+      throw new Error('CoreMail submission is unavailable.');
+    }
+    return submission;
+  }
+}