@serve.zone/interfaces 32.31.0 → 32.33.0

package/ts/data/networkprojection.ts

@@ -87,7 +87,9 @@ export interface IRuntimeNetworkPublishedPort {
    * Outbound flows the workload originates from a published target port leave the node from the
    * matching host port, so a peer sees one address and port in both directions (SIP, RTP). Only
    * `true` is ever stated; omitted, outbound flows keep the handoff lease's translation. It grants
-   * no egress: an endpoint carrying a symmetric entry has `publicEgress: true`.
+   * no egress: an endpoint carrying a symmetric entry has `publicEgress: true`. Its target ports
+   * are its own: no other entry of the list publishes to any of them
+   * (`findRuntimeNetworkPublishedPortInsideOverlap`).
    */
   symmetric?: true;
   /**
@@ -115,7 +117,10 @@ export interface IRuntimeNetworkPublishedPortRequest {
   /** The last port of a range; `targetPort` then equals `hostPort`. */
   hostPortEnd?: number;
   targetPort: number;
-  /** Same-port outbound; valid only while the service's policy document grants public egress. */
+  /**
+   * Same-port outbound; valid only while the service's policy document grants public egress, and
+   * only on target ports no other entry of the list publishes to.
+   */
   symmetric?: true;
 }
 
@@ -132,7 +137,8 @@ export interface IServicePublishedPorts {
   /**
    * Sorted by protocol and host port, never overlapping, at most
    * `runtimeNetworkPublishedPortContract.maximumEntries` entries covering at most its
-   * `maximumPortsPerService` ports. Empty means the service publishes nothing.
+   * `maximumPortsPerService` ports, and no symmetric entry sharing a target port with another
+   * entry of its protocol. Empty means the service publishes nothing.
    */
   publishedPorts: IRuntimeNetworkPublishedPortRequest[];
 }
@@ -235,7 +241,8 @@ export interface IRuntimeNetworkEndpoint {
   /**
    * Sorted by protocol and host port and never overlapping, within the bounds of
    * `runtimeNetworkPublishedPortContract`. Absent publishes nothing; a present member is never
-   * empty. A `symmetric` entry is admitted only while `publicEgress` is true.
+   * empty. A `symmetric` entry is admitted only while `publicEgress` is true and only on target
+   * ports no other entry of the endpoint publishes to.
    */
   publishedPorts?: IRuntimeNetworkPublishedPort[];
 }
@@ -414,6 +421,38 @@ export const isRuntimeNetworkPublishedPortReserved = (value: TPublishedPortSpan)
   value.hostPort < runtimeNetworkPublishedPortContract.publishablePorts.first
   || publishedPortLast(value) > runtimeNetworkPublishedPortContract.publishablePorts.last;
 
+type TPublishedPortInside = Pick<IRuntimeNetworkPublishedPortRequest, 'protocol' | 'hostPort' | 'hostPortEnd' | 'targetPort' | 'symmetric'>;
+/** The last workload port an entry publishes to; its inside span starts at `targetPort`. */
+const publishedPortInsideLast = (value: TPublishedPortInside): number =>
+  value.targetPort + publishedPortLast(value) - value.hostPort;
+
+/**
+ * The first pair of one list in which a `symmetric` entry's inside ports (`targetPort` onwards, a
+ * range's every port) share a port with another entry of the same protocol, or `null`: Cloudly's
+ * `published-port-symmetric-inside-overlap`.
+ *
+ * A symmetric entry translates the flows its workload opens from those ports back to its own host
+ * ports, so no other entry of the workload may publish to any of them, symmetric or not: the flows
+ * would have two published sources. The lists of one service's policy document and of each of its
+ * projection endpoints are judged alike, and their snapshots refuse any pair. Distinct protocols
+ * never conflict. It judges entries their snapshot already accepted.
+ */
+export const findRuntimeNetworkPublishedPortInsideOverlap = <T extends TPublishedPortInside>(
+  ports: readonly T[],
+): { symmetric: T; other: T } | null => {
+  for (let index = 0; index < ports.length; index++) {
+    const symmetric = ports[index];
+    if (symmetric.symmetric !== true) continue;
+    const first = symmetric.targetPort, last = publishedPortInsideLast(symmetric);
+    for (let other = 0; other < ports.length; other++) {
+      const candidate = ports[other];
+      if (other !== index && candidate.protocol === symmetric.protocol
+        && candidate.targetPort <= last && first <= publishedPortInsideLast(candidate)) return { symmetric, other: candidate };
+    }
+  }
+  return null;
+};
+
 /** The members every published-port entry shares; an optional member is stated only when present. */
 const publishedPortSpan = (item: Record<string, unknown>): IRuntimeNetworkPublishedPortRequest => {
   requireNetwork(item.protocol === 'tcp' || item.protocol === 'udp');
@@ -426,8 +465,11 @@ const publishedPortSpan = (item: Record<string, unknown>): IRuntimeNetworkPublis
   return { protocol: item.protocol, hostPort, ...(hasEnd ? { hostPortEnd } : {}), targetPort,
     ...(hasSymmetric ? { symmetric: true as const } : {}) };
 };
-/** Sorted, never overlapping within a protocol, and bounded in entries and in covered ports. */
-const publishedPortList = <T extends TPublishedPortSpan>(value: unknown, read: (item: unknown) => T): T[] => {
+/**
+ * Sorted, never overlapping within a protocol, bounded in entries and in covered ports, and no
+ * symmetric entry sharing an inside port with another entry.
+ */
+const publishedPortList = <T extends TPublishedPortInside>(value: unknown, read: (item: unknown) => T): T[] => {
   const ports = networkSorted(networkList(value, runtimeNetworkPublishedPortContract.maximumEntries, read), publishedPortKey);
   let covered = 0;
   ports.forEach((port, index) => {
@@ -436,6 +478,7 @@ const publishedPortList = <T extends TPublishedPortSpan>(value: unknown, read: (
     covered += publishedPortLast(port) - port.hostPort + 1;
   });
   requireNetwork(covered <= runtimeNetworkPublishedPortContract.maximumPortsPerService);
+  requireNetwork(findRuntimeNetworkPublishedPortInsideOverlap(ports) === null);
   return ports;
 };
 const publishedPort = (value: unknown): IRuntimeNetworkPublishedPort => {

package/ts/requests/admin.ts

@@ -4,6 +4,10 @@ import type {
   IServiceMachineCredentialMetadata, IServiceMachineCredentialMutationResult,
   TServiceMachineCredentialMutation,
 } from '../data/servicecredential.js';
+import type {
+  IDeploymentMachineUserMetadata, IDeploymentMachineUserMutationResult,
+  TDeploymentMachineUserMutation,
+} from '../data/deploymentmachineuser.js';
 
 export interface IReq_Admin_GetServiceMachineCredential extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetServiceMachineCredential
@@ -84,6 +88,39 @@ export interface IReq_Admin_LoginWithUsernameAndPassword extends plugins.typedre
   }
 }
 
+/**
+ * Lists every deployment machine user, value-free: no token value is ever answered here.
+ * Requires an administrator; refusals travel as `IDeploymentMachineUserErrorData`.
+ */
+export interface IReq_Admin_GetDeploymentMachineUsers extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetDeploymentMachineUsers
+> {
+  method: 'getDeploymentMachineUsers';
+  request: { identity: IIdentityCredential };
+  response: { users: IDeploymentMachineUserMetadata[] };
+}
+
+/**
+ * Creates a deployment machine user, or rotates or revokes its token.
+ *
+ * Requires an administrator. The token is answered exactly once, on the first answer to `create`
+ * or `rotate-token`; a replay of the same mutation ID by the same administrator answers the
+ * historical metadata with `token: null` and never issues another token. Grants are attached with
+ * `configureServiceDeploymentMachineUser`. Refusals travel as `IDeploymentMachineUserErrorData`.
+ */
+export interface IReq_Admin_MutateDeploymentMachineUser extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_MutateDeploymentMachineUser
+> {
+  method: 'mutateDeploymentMachineUser';
+  request: { identity: IIdentityCredential; mutation: TDeploymentMachineUserMutation };
+  response: IDeploymentMachineUserMutationResult;
+}
+
+/**
+ * Attaches one deployment grant to a deployment machine user that holds a token, replacing the
+ * grant it held for the same organization and service. `mutateDeploymentMachineUser` creates such
+ * a user.
+ */
 export interface IReq_Admin_ConfigureServiceDeploymentMachineUser
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,

package/ts/requests/service.ts

@@ -231,6 +231,14 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * Reserves one immutable deployment for the authenticated deployment machine user.
+ *
+ * Only an API machine user can complete the operation it reserves, because only its registry
+ * push is bound to that operation. An actor that is not an API machine user, an administrator
+ * included, is refused with the code `DEPLOYMENT_MACHINE_IDENTITY_REQUIRED` before anything is
+ * reserved.
+ */
 export interface IRequest_Any_Cloudly_ReserveServiceDeployment
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,