@serve.zone/interfaces 32.61.0 → 32.62.0

package/ts/data/settings.ts

@@ -52,6 +52,15 @@ export interface ICloudlySettings {
   dcrouterMailSubmissionHost?: string;
   dcrouterMailSubmissionPort?: number;
   dcrouterMailSubmissionTlsMode?: 'plain' | 'starttls' | 'implicitTls';
+  /**
+   * The canonical HTTPS URL of dcrouter's tenant mail listener, the endpoint a service's typed
+   * dcrouter-direct mail binding connects to. Cloudly writes it, and only it, into the binding's
+   * `MAIL_TYPED_URL` and `MAIL_<TOKEN>_TYPED_URL` (`serviceMailEnvironmentNames`); never
+   * `dcrouterGatewayUrl` and never a CoreMail endpoint. Absent: Cloudly refuses to provision a
+   * typed dcrouter-direct mail binding and names this key, with no fallback. A value is accepted
+   * only when `validateDcrouterMailEndpointUrl` answers no error.
+   */
+  dcrouterMailEndpointUrl?: string;
   dcrouterMailForwardTargetHost?: string;
   dcrouterMailForwardTargetHostsByNode?: Record<string, string>;
   /** Whether this Cloudly reconciles a CoreMail workload at all. */
@@ -81,6 +90,43 @@ export interface ICloudlySettings {
   appStoreCatalogRegistries?: string[];
 }
 
+/** The longest `dcrouterMailEndpointUrl` Cloudly accepts, in characters. */
+export const dcrouterMailEndpointUrlMaximumLength = 2_048;
+
+/**
+ * Every reason a value is not a `dcrouterMailEndpointUrl`; empty when it is one.
+ *
+ * An `https:` URL without credentials, query or fragment, at most
+ * `dcrouterMailEndpointUrlMaximumLength` characters, written exactly as `new URL(value).href`
+ * spells it (`https://mail.example.com/`), so two spellings of one endpoint never compare unequal.
+ * Plain `http:` and `wss:` are refused: the binding's credential travels to this endpoint. No
+ * reason quotes the value.
+ */
+export const validateDcrouterMailEndpointUrl = (valueArg: unknown): string[] => {
+  if (typeof valueArg !== 'string' || valueArg.length === 0
+    || valueArg.length > dcrouterMailEndpointUrlMaximumLength) {
+    return [`dcrouterMailEndpointUrl must be a URL of 1 to ${dcrouterMailEndpointUrlMaximumLength} characters`];
+  }
+  let url: URL;
+  try {
+    url = new URL(valueArg);
+  } catch {
+    return ['dcrouterMailEndpointUrl must be an absolute URL'];
+  }
+  const errors: string[] = [];
+  if (url.protocol !== 'https:') errors.push('dcrouterMailEndpointUrl must use https');
+  if (url.username !== '' || url.password !== '') {
+    errors.push('dcrouterMailEndpointUrl must not carry credentials');
+  }
+  if (valueArg.includes('?') || valueArg.includes('#')) {
+    errors.push('dcrouterMailEndpointUrl must not carry a query or fragment');
+  }
+  if (errors.length === 0 && url.href !== valueArg) {
+    errors.push('dcrouterMailEndpointUrl must be written in its canonical URL form');
+  }
+  return errors;
+};
+
 export const cloudlySystemSecretOwner = Object.freeze({
   kind: 'system',
   systemId: 'cloudly-settings',

package/ts/data/workloadreplicaidentity.ts

@@ -0,0 +1,219 @@
+import type { TSha256Digest } from './immutableimage.js';
+import { isSha256Digest } from './immutableimage.js';
+import type { IRuntimeAssignment } from './runtimeassignment.js';
+import { isRuntimeReplicaId, snapshotRuntimeAssignment } from './runtimeassignment.js';
+import { runtimeConfigContract } from './runtimeconfig.js';
+import type { TServiceRuntimeRefusal } from './serviceruntime.js';
+import { hasExactKeys, readDataProperties } from '../private/dataproperties.js';
+
+/**
+ * Which replica of which workload a process is, as its runtime states it.
+ *
+ * Every member is the runtime assignment's own (`buildWorkloadReplicaIdentity`), so a workload, its
+ * runtime and its controller name a replica with the same four values. `attemptId` is the one
+ * execution attempt: a rollout, a replacement or a restart onto another attempt is a new attempt,
+ * so the attempt is what a workload reports to correlate itself with the controller's roster.
+ */
+export interface IWorkloadReplicaIdentity {
+  /** The service the replica runs (`IRuntimeAssignment.serviceId`). */
+  serviceId: string;
+  /** The stable logical replica (`IRuntimeAssignment.replicaId`), a `isRuntimeReplicaId` name. */
+  replicaId: string;
+  /** The one execution attempt (`IRuntimeAssignment.attemptId`). */
+  attemptId: string;
+  /** The root descriptor digest the replica runs (`IRuntimeAssignment.workload.imageDigest`). */
+  imageDigest: TSha256Digest;
+}
+
+/**
+ * The environment variable names every runtime injects into every workload it runs, one per
+ * identity member. The one spelling Pallet, Onebox, Cloudly's composition refusal and every
+ * workload that reads its identity share.
+ */
+export const workloadReplicaIdentityEnvironmentNames = Object.freeze({
+  serviceId: 'SERVEZONE_WORKLOAD_SERVICE_ID',
+  replicaId: 'SERVEZONE_WORKLOAD_REPLICA_ID',
+  attemptId: 'SERVEZONE_WORKLOAD_ATTEMPT_ID',
+  imageDigest: 'SERVEZONE_WORKLOAD_IMAGE_DIGEST',
+} as const satisfies Readonly<Record<keyof IWorkloadReplicaIdentity, string>>);
+
+export type TWorkloadReplicaIdentityEnvironmentName =
+  typeof workloadReplicaIdentityEnvironmentNames[keyof IWorkloadReplicaIdentity];
+
+const identityKeys = Object.freeze(
+  Object.keys(workloadReplicaIdentityEnvironmentNames) as (keyof IWorkloadReplicaIdentity)[],
+);
+const identityEnvironmentNames: readonly string[] = Object.freeze(
+  Object.values(workloadReplicaIdentityEnvironmentNames),
+);
+
+/**
+ * The bounds the injection adds to a runtime config's own.
+ *
+ * `IRuntimeConfig.environment` keeps its own bound (`runtimeConfigContract.maximumEnvironmentEntries`),
+ * so a service states at most that many entries. A runtime's executor admits the config's entries
+ * plus the injected identity, `maximumExecutorEnvironmentEntries`, computed from both, never a
+ * literal of its own.
+ */
+export const workloadReplicaIdentityContract = Object.freeze({
+  injectedEnvironmentEntries: identityKeys.length,
+  maximumExecutorEnvironmentEntries: runtimeConfigContract.maximumEnvironmentEntries + identityKeys.length,
+});
+
+const isIdentifier = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(valueArg);
+
+/** What each member must hold, in the runtime assignment's own vocabulary. */
+const memberRules: Readonly<Record<keyof IWorkloadReplicaIdentity, {
+  accepts: (valueArg: unknown) => boolean;
+  requirement: string;
+}>> = Object.freeze({
+  serviceId: { accepts: isIdentifier, requirement: 'a canonical identifier' },
+  replicaId: { accepts: isRuntimeReplicaId, requirement: 'a replica id' },
+  attemptId: { accepts: isIdentifier, requirement: 'a canonical identifier' },
+  imageDigest: {
+    accepts: (valueArg: unknown) => typeof valueArg === 'string' && isSha256Digest(valueArg),
+    requirement: 'a sha256 digest',
+  },
+});
+
+const judgeIdentity = (valueArg: unknown): { record: Record<string, unknown> | null; errors: string[] } => {
+  const record = readDataProperties(valueArg);
+  if (record === null) {
+    return { record, errors: ['workload replica identity must be a plain record of data properties'] };
+  }
+  const errors: string[] = [];
+  if (!hasExactKeys(record, identityKeys)) {
+    errors.push(`workload replica identity must state exactly ${identityKeys.join(', ')}`);
+  }
+  for (const key of identityKeys) {
+    if (Object.hasOwn(record, key) && !memberRules[key].accepts(record[key])) {
+      errors.push(`${key} must be ${memberRules[key].requirement}`);
+    }
+  }
+  return { record, errors };
+};
+
+/** Every reason a value is not exactly a workload replica identity; empty when it is one. */
+export const validateWorkloadReplicaIdentity = (valueArg: unknown): string[] => judgeIdentity(valueArg).errors;
+
+/** A detached, frozen copy of exactly a workload replica identity; throws naming every violation. */
+export const snapshotWorkloadReplicaIdentity = (valueArg: unknown): IWorkloadReplicaIdentity => {
+  const { record, errors } = judgeIdentity(valueArg);
+  if (record === null || errors.length > 0) {
+    throw new Error(`workload replica identity refused: ${errors.join('; ')}`);
+  }
+  return Object.freeze({
+    serviceId: record.serviceId as string,
+    replicaId: record.replicaId as string,
+    attemptId: record.attemptId as string,
+    imageDigest: record.imageDigest as TSha256Digest,
+  });
+};
+
+/**
+ * The identity of the replica one runtime assignment runs.
+ *
+ * Read from the assignment the runtime admitted, through its exact schema, so the answer always
+ * satisfies `validateWorkloadReplicaIdentity`. It proves nothing about the assignment's digest or
+ * admission; the runtime has judged those before it runs anything.
+ */
+export const buildWorkloadReplicaIdentity = (assignmentArg: IRuntimeAssignment): IWorkloadReplicaIdentity => {
+  const assignment = snapshotRuntimeAssignment(assignmentArg);
+  return Object.freeze({
+    serviceId: assignment.serviceId,
+    replicaId: assignment.replicaId,
+    attemptId: assignment.attemptId,
+    imageDigest: assignment.workload.imageDigest,
+  });
+};
+
+/**
+ * The injected names among `namesArg`, sorted and unique: empty when none collides.
+ *
+ * Cloudly's composition refusal passes the keys of a replica's effective environment together with
+ * the variable names of its launcher-environment secrets, because WorkloadInit sets a secret over a
+ * plain variable of the same name and so would replace the injected identity just as silently.
+ */
+export const findWorkloadReplicaIdentityEnvironmentConflicts = (
+  namesArg: readonly string[],
+): TWorkloadReplicaIdentityEnvironmentName[] => identityEnvironmentNames
+  .filter((nameArg) => namesArg.includes(nameArg))
+  .sort() as TWorkloadReplicaIdentityEnvironmentName[];
+
+/** The one reason a workload environment cannot carry its replica identity. */
+export type TWorkloadReplicaEnvironmentRefusal = Extract<
+  TServiceRuntimeRefusal,
+  'workload-identity-environment-conflict'
+>;
+
+/** What a replica runs with, or the one reason its identity cannot be injected. */
+export type TWorkloadReplicaEnvironmentComposition =
+  | { status: 'composed'; environment: Record<string, string> }
+  | { status: 'refused'; reason: TWorkloadReplicaEnvironmentRefusal; message: string };
+
+/**
+ * The environment one replica runs with: its runtime config's environment with the replica's
+ * identity added under `workloadReplicaIdentityEnvironmentNames`.
+ *
+ * Every runtime injects the identity into every workload, whether the workload reads it or not. A
+ * config environment that already states one of the names is refused
+ * `workload-identity-environment-conflict`, naming every such key and none of their values, rather
+ * than having one value silently replace the other. The reason stays inside the runtime: only
+ * Cloudly states it on the wire, in a service's status. A Pallet reports the refused run as the
+ * existing `TRuntimeAssignmentFailureCause` `{ kind: 'refused', reason: 'invalid' }`, which every
+ * reader since 32.45.0 reads and a controller never re-places with an identical configuration. An
+ * identity that is not exactly one is the caller's error and is thrown. The inputs are not
+ * changed. A config within
+ * `runtimeConfigContract.maximumEnvironmentEntries` composes to at most
+ * `workloadReplicaIdentityContract.maximumExecutorEnvironmentEntries` entries.
+ */
+export const composeWorkloadReplicaEnvironment = (
+  environmentArg: Readonly<Record<string, string>>,
+  identityArg: IWorkloadReplicaIdentity,
+): TWorkloadReplicaEnvironmentComposition => {
+  const identity = snapshotWorkloadReplicaIdentity(identityArg);
+  const conflicts = findWorkloadReplicaIdentityEnvironmentConflicts(Object.keys(environmentArg));
+  if (conflicts.length > 0) {
+    return { status: 'refused', reason: 'workload-identity-environment-conflict',
+      message: `workload environment already states ${conflicts.join(', ')}, which the runtime injects` };
+  }
+  const injected: Record<string, string> = {};
+  for (const key of identityKeys) {
+    injected[workloadReplicaIdentityEnvironmentNames[key]] = identity[key];
+  }
+  return { status: 'composed', environment: { ...environmentArg, ...injected } };
+};
+
+/**
+ * The replica identity a workload reads from its own environment (`process.env`).
+ *
+ * Reads the four injected names only, as own data properties, and nothing else of the environment.
+ * Throws naming every name that is missing and every name whose value is not a valid member, never
+ * a value, so a workload refuses to start with the exact variable its runtime did not inject.
+ */
+export const readWorkloadReplicaIdentityEnvironment = (
+  environmentArg: Readonly<Record<string, string | undefined>>,
+): IWorkloadReplicaIdentity => {
+  const missing: string[] = [];
+  const invalid: string[] = [];
+  const identity: Record<string, string> = {};
+  for (const key of identityKeys) {
+    const name = workloadReplicaIdentityEnvironmentNames[key];
+    const descriptor = Object.getOwnPropertyDescriptor(environmentArg, name);
+    if (descriptor === undefined || !Object.hasOwn(descriptor, 'value') || typeof descriptor.value !== 'string') {
+      missing.push(name);
+    } else if (!memberRules[key].accepts(descriptor.value)) {
+      invalid.push(name);
+    } else {
+      identity[key] = descriptor.value;
+    }
+  }
+  if (missing.length > 0 || invalid.length > 0) {
+    throw new Error(`workload replica identity environment ${[
+      ...missing.length > 0 ? [`lacks ${missing.join(', ')}`] : [],
+      ...invalid.length > 0 ? [`states an invalid ${invalid.join(', ')}`] : [],
+    ].join('; ')}`);
+  }
+  return snapshotWorkloadReplicaIdentity(identity);
+};

package/ts/requests/coremail.ts

@@ -18,6 +18,7 @@ import type {
   TCoreMailWorkloadOperation,
 } from '../data/coremail.js';
 import type { IMailConnectionInfo } from '../data/mail.js';
+import type { IWorkloadReplicaIdentity } from '../data/workloadreplicaidentity.js';
 
 export interface IReq_CoreMailAuthenticateWorkload extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -186,7 +187,11 @@ export interface IReq_CoreMailAuthenticateControl extends plugins.typedrequestIn
     authenticated: true;
     credentialId: string;
     credentialVersion: number;
-    replica: ICoreMailReplicaIdentity;
+    /**
+     * The authenticated replica: `IWorkloadReplicaIdentity` from CoreMail 34 on, the deprecated
+     * `ICoreMailReplicaIdentity` from an earlier CoreMail (`normalizeCoreMailReplicaIdentity`).
+     */
+    replica: IWorkloadReplicaIdentity | ICoreMailReplicaIdentity;
   };
 }