@serve.zone/interfaces 30.12.0 → 30.13.0

package/ts/data/coremail.ts

@@ -26,6 +26,11 @@ export type TCoreMailSubmissionState =
   | 'deferred'
   | 'failed'
   | 'deadLettered';
+/**
+ * Entry point that produced an outbound submission. `api` is the authenticated
+ * workload TypedRequest surface, `smtp` is the CoreMail submission listener.
+ */
+export type TCoreMailSubmissionSource = 'api' | 'smtp';
 export type TCoreMailInboundDeliveryState = 'pending' | 'fetching' | 'fetched' | 'acknowledged';
 export type TCoreMailInboundAckOutcome = 'processed' | 'discarded';
 export type TCoreMailRecipientAction = 'accept' | 'reject' | 'defer' | 'unhandled';
@@ -149,6 +154,8 @@ export interface ICoreMailSubmission {
   idempotencyKey: string;
   submissionDigest: TCoreMailSha256;
   state: TCoreMailSubmissionState;
+  /** Entry point that produced this submission. Omitted means an API submission. */
+  source?: TCoreMailSubmissionSource;
   parts: ICoreMailPartStatus[];
   transportMessageId?: string;
   attempts: number;
@@ -255,11 +262,38 @@ export interface ICoreMailRuntimeKeyReference {
   acceptUntil?: number;
 }
 
+export interface ICoreMailSmtpTlsDesiredState {
+  /** Keys in CoreMail's resolved runtime secret material holding PEM text, never plaintext values. */
+  certificatePemSecretKey: string;
+  privateKeyPemSecretKey: string;
+}
+
+/**
+ * Desired state for CoreMail's own SMTP submission listener (MSA).
+ *
+ * SMTP AUTH uses the binding identity directly: the username is the
+ * `bindingId` and the password is any current or retiring credential secret of
+ * that binding, so credential rotation windows behave exactly as they do for
+ * the workload TypedRequest surface. The listener stays unavailable until the
+ * referenced PEM material resolves; an enabled listener without resolvable
+ * certificate and private key material never accepts submissions.
+ */
+export interface ICoreMailSmtpDesiredState {
+  enabled: boolean;
+  /** Listener port inside the CoreMail workload. */
+  port: number;
+  /** Advertised EHLO hostname. */
+  hostname: string;
+  tls: ICoreMailSmtpTlsDesiredState;
+}
+
 export interface ICoreMailDesiredState {
   schemaVersion: 2;
   configEpoch: number;
   bindings: ICoreMailBindingDesiredState[];
   gateway: ICoreMailGatewayDesiredState;
+  /** Optional SMTP submission listener. An omitted listener keeps the API-only surface. */
+  smtp?: ICoreMailSmtpDesiredState;
   cursorKeys: ICoreMailRuntimeKeyReference[];
 }
 
@@ -293,6 +327,36 @@ export interface ICoreMailReconciliationStatus {
   errorCode?: TCoreMailErrorCode;
 }
 
+export interface ICoreMailOutboundMailCounters {
+  submittedApi: number;
+  submittedSmtp: number;
+  delivered: number;
+  deferred: number;
+  failed: number;
+  deadLettered: number;
+}
+
+export interface ICoreMailInboundMailCounters {
+  received: number;
+  acknowledgedProcessed: number;
+  acknowledgedDiscarded: number;
+}
+
+/**
+ * Per-service mail counters for one UTC calendar day, reported over the
+ * authenticated CoreMail control session.
+ */
+export interface ICoreMailServiceMailStatistics {
+  tenantId: string;
+  serviceId: string;
+  bindingId: string;
+  /** UTC calendar day, `YYYY-MM-DD`. */
+  dayUtc: string;
+  outbound: ICoreMailOutboundMailCounters;
+  inbound: ICoreMailInboundMailCounters;
+  updatedAt: number;
+}
+
 export interface ICoreMailRecipientResolution {
   recipient: string;
   action: TCoreMailRecipientAction;
@@ -311,6 +375,14 @@ export interface ICoreMailGatewayMessageDescriptor {
   };
 }
 
+/**
+ * dcrouter-reported delivery status for one accepted transport message.
+ *
+ * `updatedAt` must be monotonic per `transportMessageId`. A
+ * `transportMessageId` the gateway can never recognize again must be reported
+ * as a terminal `failed` status instead of an error, because CoreMail retries
+ * errors indefinitely.
+ */
 export interface ICoreMailGatewayOutboundStatus {
   transportMessageId: string;
   state: Extract<

package/ts/data/mail.ts

@@ -2,7 +2,13 @@ export type TMailGatewayClientType = 'onebox' | 'cloudly' | 'custom' | (string &
 
 export type TMailAddressPatternType = 'exactAddress' | 'domainWildcard' | 'localPartPattern';
 
-export type TMailInboundTargetType = 'webhook' | 'smtpForward' | 'typedEndpoint' | 'discard' | 'reject';
+export type TMailInboundTargetType =
+  | 'webhook'
+  | 'smtpForward'
+  | 'typedEndpoint'
+  | 'coreMail'
+  | 'discard'
+  | 'reject';
 
 export type TMailRecipientPolicyMode = 'acceptAll' | 'staticList' | 'cachedResolver' | 'appResolver';
 
@@ -50,9 +56,26 @@ export type TMailDeliveryJournalEventType =
   | 'bounced'
   | 'complaint';
 
+/**
+ * Error codes a mail submission may return. The CoreMail-fronted path maps the
+ * matching `TCoreMailErrorCode` values through unchanged so applications can
+ * branch on them regardless of which transport carried the submission.
+ */
 export type TMailSubmissionErrorCode =
   | 'INVALID_REPLY_TO'
-  | 'REPLY_TO_FIELD_HEADER_CONFLICT';
+  | 'REPLY_TO_FIELD_HEADER_CONFLICT'
+  | 'AUTHENTICATION_FAILED'
+  | 'CAPABILITY_DENIED'
+  | 'INVALID_REQUEST'
+  | 'INVALID_MAILBOX'
+  | 'INVALID_SENDER'
+  | 'INVALID_RECIPIENT'
+  | 'INVALID_HEADER'
+  | 'PAYLOAD_LIMIT_EXCEEDED'
+  | 'QUOTA_EXCEEDED'
+  | 'IDEMPOTENCY_CONFLICT'
+  | 'STATE_CONFLICT'
+  | 'NOT_FOUND';
 
 /**
  * Runtime owner of a mail resource. `appInstanceId` is the deployed WorkApp or service
@@ -94,11 +117,17 @@ export interface IMailTypedEndpointTarget {
   timeoutMs?: number;
 }
 
+export interface IMailCoreMailTarget {
+  /** CoreMail service identity that owns the inbound mailbox. */
+  coreMailServiceId: string;
+}
+
 export interface IMailInboundTarget {
   type: TMailInboundTargetType;
   webhook?: IMailWebhookTarget;
   smtpForward?: IMailSmtpForwardTarget;
   typedEndpoint?: IMailTypedEndpointTarget;
+  coreMail?: IMailCoreMailTarget;
   reject?: {
     smtpCode: number;
     message: string;
@@ -231,8 +260,11 @@ export type TServiceMailSubmissionTlsMode = 'plain' | 'starttls' | 'implicitTls'
 
 export interface IServiceMailInboundConfig {
   enabled?: boolean;
-  /** Platformclient apps use typedEndpoint; third-party apps with their own SMTP server use smtpForward. */
-  targetType?: 'typedEndpoint' | 'smtpForward';
+  /**
+   * Platformclient apps use typedEndpoint; third-party apps with their own SMTP
+   * server use smtpForward; services bound to a CoreMail workload use coreMail.
+   */
+  targetType?: 'typedEndpoint' | 'smtpForward' | 'coreMail';
   /** TypedRequest method exposed by platformclient over TypedSocket for inbound delivery. */
   typedMethod?: string;
   /** Published Docker/Swarm port that dcrouter may SMTP-forward inbound mail to. */

package/ts/requests/coremail.ts

@@ -10,6 +10,7 @@ import type {
   ICoreMailRecipientResolution,
   ICoreMailReconciliationStatus,
   ICoreMailReplicaIdentity,
+  ICoreMailServiceMailStatistics,
   ICoreMailSubmission,
   ICoreMailUploadGrant,
   TCoreMailInboundAckOutcome,
@@ -237,6 +238,33 @@ export interface IReq_CoreMailGetReconciliationStatus extends plugins.typedreque
   };
 }
 
+/**
+ * Control-session read of per-service mail counters. Authority comes from the
+ * authenticated control session; the request carries no tenant or binding
+ * authority of its own.
+ */
+export interface IReq_CoreMailGetServiceMailStatistics extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGetServiceMailStatistics
+> {
+  method: 'coreMailGetServiceMailStatistics';
+  request: {
+    /** Inclusive first UTC calendar day, `YYYY-MM-DD`. */
+    fromDayUtc: string;
+    /** Inclusive last UTC calendar day, `YYYY-MM-DD`. */
+    toDayUtc: string;
+    /** Optional service filter. Omitted means every service known to this CoreMail. */
+    serviceIds?: string[];
+    /** Opaque CoreMail-owned composite cursor. */
+    cursor?: string;
+    limit: number;
+  };
+  response: {
+    statistics: ICoreMailServiceMailStatistics[];
+    nextCursor?: string;
+  };
+}
+
 export interface IReq_CoreMailGatewayAuthenticate extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_CoreMailGatewayAuthenticate
@@ -256,6 +284,13 @@ export interface IReq_CoreMailGatewayAuthenticate extends plugins.typedrequestIn
   };
 }
 
+/**
+ * CoreMail binds every issued routing handle to a digest of the exact
+ * normalized `envelope` and `source` sent here. The following
+ * `coreMailGatewayPrepareInboundHandoff` call must therefore resend
+ * byte-identical values: the full `rcptTo` set in the same order, the same
+ * `mailFrom`, and the same connection source fields.
+ */
 export interface IReq_CoreMailGatewayResolveRecipients extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_CoreMailGatewayResolveRecipients
@@ -271,6 +306,13 @@ export interface IReq_CoreMailGatewayResolveRecipients extends plugins.typedrequ
   };
 }
 
+/**
+ * The handoff is validated against the routing handles issued by
+ * `coreMailGatewayResolveRecipients`. `message.envelope` and `source` must be
+ * byte-identical to the resolve-time values, including the full `rcptTo` set in
+ * the same order, because CoreMail recomputes the envelope digest the handles
+ * are bound to.
+ */
 export interface IReq_CoreMailGatewayPrepareInboundHandoff extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_CoreMailGatewayPrepareInboundHandoff
@@ -343,6 +385,12 @@ export interface IReq_CoreMailGatewayCompleteOutboundHandoff extends plugins.typ
   };
 }
 
+/**
+ * Status polling for one accepted transport message. `status.updatedAt` must be
+ * monotonic per `transportMessageId`. A `transportMessageId` that is
+ * permanently unknown to the gateway must be answered with a terminal `failed`
+ * status rather than an error, because CoreMail retries errors indefinitely.
+ */
 export interface IReq_CoreMailGatewayGetOutboundStatus extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_CoreMailGatewayGetOutboundStatus

package/ts/requests/mail.ts

@@ -1,4 +1,5 @@
 import * as plugins from '../plugins.js';
+import type { ICoreMailGatewayPeerDesiredState } from '../data/coremail.js';
 import type { IIdentity } from '../data/user.js';
 import type {
   IMailAddressBinding,
@@ -144,6 +145,67 @@ export interface IReq_DeleteMailAddressBinding extends plugins.typedrequestInter
   };
 }
 
+/**
+ * dcrouter-owned CoreMail gateway peer state.
+ *
+ * `peer.transferOrigin` must equal the `gateway.coreMailTransferOrigin` carried
+ * in that CoreMail service's own desired state. The producer (Cloudly or
+ * Onebox) is the single owner of that string: dcrouter never infers it from a
+ * socket, Host header, TypedSocket tag, or peer input.
+ */
+export interface IReq_ListCoreMailGatewayPeers extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ListCoreMailGatewayPeers
+> {
+  method: 'listCoreMailGatewayPeers';
+  request: {
+    auth: IMailControlRequestAuth;
+    owner: IMailResourceOwner;
+  };
+  response: {
+    peers: ICoreMailGatewayPeerDesiredState[];
+  };
+}
+
+/**
+ * Creates or replaces one CoreMail gateway peer. On success the accepted peer is
+ * returned in its stored form so the producer can compare the exact applied
+ * state. `owner` is required (not partial) because a peer is producer-owned
+ * provisioning state, never a filtered listing.
+ */
+export interface IReq_SyncCoreMailGatewayPeer extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SyncCoreMailGatewayPeer
+> {
+  method: 'syncCoreMailGatewayPeer';
+  request: {
+    auth: IMailControlRequestAuth;
+    owner: IMailResourceOwner;
+    peer: ICoreMailGatewayPeerDesiredState;
+  };
+  response: {
+    success: boolean;
+    peer?: ICoreMailGatewayPeerDesiredState;
+    message?: string;
+  };
+}
+
+export interface IReq_DeleteCoreMailGatewayPeer extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_DeleteCoreMailGatewayPeer
+> {
+  method: 'deleteCoreMailGatewayPeer';
+  request: {
+    auth: IMailControlRequestAuth;
+    owner: IMailResourceOwner;
+    coreMailServiceId: string;
+  };
+  response: {
+    success: boolean;
+    message?: string;
+  };
+}
+
 export interface IReq_ListWorkAppMailBindings extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_ListWorkAppMailBindings