@serve.zone/interfaces 30.12.0 → 30.14.0

package/ts/data/settings.ts

@@ -1,3 +1,4 @@
+import type { TServiceMailSubmissionTlsMode } from './mail.js';
 import type { ISystemSecretOwner, TSecretManagementScope } from './secret.js';
 
 export interface ICloudlyS3BackupTargetDescriptor {
@@ -42,6 +43,23 @@ export interface ICloudlySettings {
   dcrouterMailSubmissionTlsMode?: 'plain' | 'starttls' | 'implicitTls';
   dcrouterMailForwardTargetHost?: string;
   dcrouterMailForwardTargetHostsByNode?: Record<string, string>;
+  /** Whether this Cloudly reconciles a CoreMail workload at all. */
+  coreMailEnabled?: boolean;
+  coreMailServiceId?: string;
+  /** Canonical CoreMail control socket URL, `https://host/socket`. */
+  coreMailControlEndpointUrl?: string;
+  /** Canonical CoreMail HTTPS transfer origin, an origin without a path. */
+  coreMailTransferOrigin?: string;
+  /** Canonical `wss://` URL of dcrouter's CoreMail gateway socket. */
+  coreMailGatewayEndpointUrl?: string;
+  coreMailControlCredentialId?: string;
+  coreMailControlCredentialVersion?: number;
+  coreMailSmtpHost?: string;
+  coreMailSmtpPort?: number;
+  coreMailSmtpTlsMode?: TServiceMailSubmissionTlsMode;
+  coreMailDefaultMessagesPerMinute?: number;
+  coreMailDefaultMessagesPerDay?: number;
+  coreMailDefaultMaxPendingInbound?: number;
   corebuildWorkerUrl?: string;
   corebuildWorkerUrls?: string[];
 }
@@ -81,4 +99,13 @@ export const cloudlySystemSecretKeys = Object.freeze({
   scalewayAccessKey: 'SCALEWAY_ACCESS_KEY',
   scalewaySecretKey: 'SCALEWAY_SECRET_KEY',
   scalewayOrganizationId: 'SCALEWAY_ORGANIZATION_ID',
+  coreMailControlCredentialSecret: 'COREMAIL_CONTROL_CREDENTIAL_SECRET',
+  coreMailGatewayCredentialSecret: 'COREMAIL_GATEWAY_CREDENTIAL_SECRET',
+  /**
+   * Operator-supplied PEM material for the CoreMail submission listener in v1.
+   * Automatic certificate issuance for the listener is a later workstream; until
+   * it ships, the operator provisions and rotates this material.
+   */
+  coreMailSmtpTlsCertificatePem: 'COREMAIL_SMTP_TLS_CERTIFICATE_PEM',
+  coreMailSmtpTlsPrivateKeyPem: 'COREMAIL_SMTP_TLS_PRIVATE_KEY_PEM',
 } as const);

package/ts/requests/coremail.admin.ts

@@ -0,0 +1,83 @@
+import type * as plugins from '../plugins.js';
+import type {
+  ICoreMailReconciliationStatus,
+  ICoreMailServiceMailStatistics,
+  TCoreMailSha256,
+} from '../data/coremail.js';
+import type { IServiceMailTargetSummary } from '../data/mail.js';
+import type { IIdentity } from '../data/user.js';
+
+/**
+ * Operator-facing CoreMail requests served by Cloudly. Authority comes from the
+ * caller identity, exactly like the other admin mail requests; the CoreMail
+ * control session itself is never exposed to an operator client.
+ */
+export interface IReq_GetCoreMailServiceMailStatistics extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetCoreMailServiceMailStatistics
+> {
+  method: 'getCoreMailServiceMailStatistics';
+  request: {
+    identity: IIdentity;
+    /** Optional service filter. Omitted means every service this identity may read. */
+    serviceId?: string;
+    /** Inclusive first UTC calendar day, `YYYY-MM-DD`. */
+    fromDayUtc: string;
+    /** Inclusive last UTC calendar day, `YYYY-MM-DD`. */
+    toDayUtc: string;
+    /** Opaque Cloudly-owned cursor. */
+    cursor?: string;
+    limit: number;
+  };
+  response: {
+    statistics: ICoreMailServiceMailStatistics[];
+    nextCursor?: string;
+  };
+}
+
+/**
+ * Current CoreMail control-plane state as Cloudly sees it. `enabled` is false
+ * when no CoreMail workload is configured, in which case every other field is
+ * absent rather than defaulted.
+ */
+export interface IReq_GetCoreMailControlStatus extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetCoreMailControlStatus
+> {
+  method: 'getCoreMailControlStatus';
+  request: {
+    identity: IIdentity;
+  };
+  response: {
+    enabled: boolean;
+    coreMailServiceId?: string;
+    appliedConfigEpoch?: number;
+    appliedDesiredStateDigest?: TCoreMailSha256;
+    reconciliation?: ICoreMailReconciliationStatus;
+    lastError?: string;
+    updatedAt?: number;
+  };
+}
+
+/**
+ * Operator inventory of every service mail target: which addresses exist, where
+ * inbound mail is delivered, whether outbound submission is configured, and the
+ * CoreMail binding a service is bound to.
+ */
+export interface IReq_ListServiceMailTargets extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ListServiceMailTargets
+> {
+  method: 'listServiceMailTargets';
+  request: {
+    identity: IIdentity;
+    organizationId?: string;
+    /** Opaque Cloudly-owned cursor. */
+    cursor?: string;
+    limit: number;
+  };
+  response: {
+    services: IServiceMailTargetSummary[];
+    nextCursor?: string;
+  };
+}

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/index.ts

@@ -9,6 +9,7 @@ import * as certificateRequests from './certificate.js';
 import * as clusterRequests from './cluster.js';
 import * as configRequests from './config.js';
 import * as coreMailRequests from './coremail.js';
+import * as coreMailAdminRequests from './coremail.admin.js';
 import * as corestoreRequests from './corestore.js';
 import * as deploymentRequests from './deployment.js';
 import * as dnsRequests from './dns.js';
@@ -47,6 +48,7 @@ export {
   clusterRequests as cluster,
   configRequests as config,
   coreMailRequests as coremail,
+  coreMailAdminRequests as coremailAdmin,
   corestoreRequests as corestore,
   deploymentRequests as deployment,
   dnsRequests as dns,

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