@serve.zone/interfaces 32.30.0 → 32.32.0

package/ts/data/networkprojection.ts

@@ -61,15 +61,37 @@ export interface IRuntimeNetworkWorkloadLease extends IRuntimeNetworkNodeScope {
 }
 
 /**
- * One node-level published port for a workload. Mirrors `IAppStorePublishedPort`
- * without range fields: the runtime publishes exactly one host port per entry.
+ * One node-level published port, or one contiguous range of them, for a workload.
+ *
+ * Without `hostPortEnd` the entry publishes exactly `hostPort` to `targetPort`. With it the entry
+ * publishes every port from `hostPort` to `hostPortEnd` inclusive, each to the same port inside the
+ * workload, so `targetPort` equals `hostPort`. Every port an entry covers is claimed on its node:
+ * two entries of one node and protocol never share a port, and the entries of one endpoint never
+ * overlap and cover at most `runtimeNetworkPublishedPortContract.maximumPortsPerService` ports.
  */
 export interface IRuntimeNetworkPublishedPort {
   protocol: 'tcp' | 'udp';
-  /** 1..65535 and unique per node across the projection for its protocol. */
+  /**
+   * 1..65535; the first port of a range. Cloudly publishes only ports inside
+   * `runtimeNetworkPublishedPortContract.publishablePorts` (`published-port-reserved`).
+   */
   hostPort: number;
-  /** The workload's own listening port inside its network namespace. */
+  /**
+   * The last port of a range, above `hostPort` and at most 65535. Omitted, the entry is one port;
+   * a one-port range is never written with it.
+   */
+  hostPortEnd?: number;
+  /** The workload's own listening port inside its network namespace; `hostPort` for a range. */
   targetPort: number;
+  /**
+   * 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`. Its target ports
+   * are its own: no other entry of the list publishes to any of them
+   * (`findRuntimeNetworkPublishedPortInsideOverlap`).
+   */
+  symmetric?: true;
   /**
    * Never the wildcard or loopback. Omitted means the node's uplink address.
    * The contract cannot prove an uplink fact, so binding the port to that exact
@@ -84,15 +106,22 @@ export interface IRuntimeNetworkPublishedPort {
 }
 
 /**
- * Caller-authored published-port request. It carries no `hostIp` (an omitted
- * address means the node uplink) and no ranges: exactly one host port per entry.
- * The `authorization` reference of the resulting projection entry is derived by
- * Cloudly from the policy revision and digest, never supplied by the caller.
+ * Caller-authored published-port request. It carries no `hostIp` (an omitted address means the
+ * node uplink). `hostPortEnd` and `symmetric` follow the rules of `IRuntimeNetworkPublishedPort`.
+ * The `authorization` reference of the resulting projection entry is derived by Cloudly from the
+ * policy revision and digest, never supplied by the caller.
  */
 export interface IRuntimeNetworkPublishedPortRequest {
   protocol: 'tcp' | 'udp';
   hostPort: number;
+  /** 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, and
+   * only on target ports no other entry of the list publishes to.
+   */
+  symmetric?: true;
 }
 
 /**
@@ -105,13 +134,23 @@ export interface IServicePublishedPorts {
   organizationId: string;
   serviceId: string;
   revision: number;
-  /** Sorted by protocol and host port. Empty means the service publishes nothing. */
+  /**
+   * Sorted by protocol and host port, never overlapping, at most
+   * `runtimeNetworkPublishedPortContract.maximumEntries` entries covering at most its
+   * `maximumPortsPerService` ports, and no symmetric entry sharing a target port with another
+   * entry of its protocol. Empty means the service publishes nothing.
+   */
   publishedPorts: IRuntimeNetworkPublishedPortRequest[];
 }
 
 /**
  * Exact desired policy. Node-level host-port placement remains Cloudly's decision.
  *
+ * Beyond the shape its snapshot checks, Cloudly refuses a port outside
+ * `runtimeNetworkPublishedPortContract.publishablePorts` and a symmetric entry while the document's
+ * `publicEgress` is false; `setServiceNetworkEgress` likewise refuses clearing `publicEgress` while a
+ * symmetric entry remains.
+ *
  * One document per service holds its published ports and its egress under one `revision`. The
  * first accepted write of either (`expectedRevision: null`) creates it: `setServicePublishedPorts`
  * with egress `publicEgress: false` and `platformEndpointIds: []`, `setServiceNetworkEgress` with
@@ -160,7 +199,8 @@ export interface IServiceNetworkEgress {
 
 /**
  * Exact desired egress. The published ports of the same document are carried forward unchanged.
- * Whether each id names a current platform endpoint is Cloudly's decision at acceptance.
+ * Whether each id names a current platform endpoint is Cloudly's decision at acceptance, and so is
+ * the refusal of `publicEgress: false` while a carried published port is `symmetric`.
  *
  * One document per service holds its published ports and its egress under one `revision`. The
  * first accepted write of either (`expectedRevision: null`) creates it: `setServicePublishedPorts`
@@ -198,7 +238,12 @@ export interface IRuntimeNetworkEndpoint {
   /** TCP/UDP only; the complete protected union remains denied. */
   publicEgress: boolean;
   platformEndpointIds: string[];
-  /** Sorted by protocol and host port. Absent publishes nothing; a present member is never empty. */
+  /**
+   * 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 and only on target
+   * ports no other entry of the endpoint publishes to.
+   */
   publishedPorts?: IRuntimeNetworkPublishedPort[];
 }
 
@@ -286,6 +331,23 @@ export const runtimeNetworkProjectionContract = Object.freeze({
   allocationReuse: 'requires-controller-quarantine-and-all-affected-authority-fences',
 } as const);
 
+/**
+ * The bounds of one service's published ports, the same on its policy document and on each of its
+ * projection endpoints.
+ *
+ * `maximumEntries` bounds the list and `maximumPortsPerService` the ports its entries cover
+ * together, a range counting every port in it; the snapshots refuse either excess.
+ * `publishablePorts` is Cloudly's placement rule, not a snapshot rule: the ports above it are
+ * `runtimeNetworkHandoffSnatPortRange`, which a handoff lease translates outbound flows to, so
+ * Cloudly refuses a policy with a port outside it as `published-port-reserved`
+ * (`isRuntimeNetworkPublishedPortReserved`). A policy written before this rule stays readable.
+ */
+export const runtimeNetworkPublishedPortContract = Object.freeze({
+  maximumEntries: 64,
+  maximumPortsPerService: 1024,
+  publishablePorts: Object.freeze({ first: 1, last: 49_151 } as const),
+} as const);
+
 /** The assignment contract owns the replica rule; a lease names the same slot by the same name. */
 const replicaId = (value: unknown): string => {
   requireNetwork(isRuntimeReplicaId(value)); return value as string;
@@ -346,28 +408,95 @@ const packetGrant = (value: unknown): IRuntimeNetworkPacketGrant => {
   return { source: networkReference(item.source), destination: { kind, id: networkId(destination.id), address: networkIpv4(destination.address),
     protocol: destination.protocol, port: networkCounter(destination.port, 65535) } };
 };
-const publishedPortKey = (value: { protocol: 'tcp' | 'udp'; hostPort: number }): string =>
+type TPublishedPortSpan = Pick<IRuntimeNetworkPublishedPortRequest, 'protocol' | 'hostPort' | 'hostPortEnd'>;
+const publishedPortKey = (value: TPublishedPortSpan): string =>
   `${value.protocol}/${String(value.hostPort).padStart(5, '0')}`;
-const publishedPort = (value: unknown): IRuntimeNetworkPublishedPort => {
-  const hasHostIp = value !== null && typeof value === 'object' && Object.hasOwn(value, 'hostIp');
-  const item = networkRecord(value, ['protocol', 'hostPort', 'targetPort', 'authorization', ...(hasHostIp ? ['hostIp'] : [])]);
+const publishedPortLast = (value: TPublishedPortSpan): number => value.hostPortEnd ?? value.hostPort;
+
+/**
+ * Whether any port an entry covers lies outside `runtimeNetworkPublishedPortContract.publishablePorts`:
+ * Cloudly's `published-port-reserved`. It judges an entry its snapshot already accepted.
+ */
+export const isRuntimeNetworkPublishedPortReserved = (value: TPublishedPortSpan): boolean =>
+  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');
-  const hostIp = hasHostIp ? networkIpv4(item.hostIp) : null;
+  const hostPort = networkCounter(item.hostPort, 65535), targetPort = networkCounter(item.targetPort, 65535);
+  const hasEnd = Object.hasOwn(item, 'hostPortEnd'), hasSymmetric = Object.hasOwn(item, 'symmetric');
+  const hostPortEnd = hasEnd ? networkCounter(item.hostPortEnd, 65535) : hostPort;
+  // A range maps each host port to the same workload port; a one-port range has one encoding, none.
+  requireNetwork(!hasEnd || (hostPortEnd > hostPort && targetPort === hostPort));
+  requireNetwork(!hasSymmetric || item.symmetric === true);
+  return { protocol: item.protocol, hostPort, ...(hasEnd ? { hostPortEnd } : {}), targetPort,
+    ...(hasSymmetric ? { symmetric: true as const } : {}) };
+};
+/**
+ * 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) => {
+    const previous = index === 0 ? null : ports[index - 1];
+    requireNetwork(previous === null || previous.protocol !== port.protocol || publishedPortLast(previous) < port.hostPort);
+    covered += publishedPortLast(port) - port.hostPort + 1;
+  });
+  requireNetwork(covered <= runtimeNetworkPublishedPortContract.maximumPortsPerService);
+  requireNetwork(findRuntimeNetworkPublishedPortInsideOverlap(ports) === null);
+  return ports;
+};
+const publishedPort = (value: unknown): IRuntimeNetworkPublishedPort => {
+  const item = networkRecord(value, ['protocol', 'hostPort', 'targetPort', 'authorization'], ['hostIp', 'hostPortEnd', 'symmetric']);
+  const { symmetric, ...span } = publishedPortSpan(item);
+  const hostIp = Object.hasOwn(item, 'hostIp') ? networkIpv4(item.hostIp) : null;
   requireNetwork(hostIp === null || (hostIp !== '0.0.0.0' && !networkContains('127.0.0.0/8', `${hostIp}/32`)));
-  return { protocol: item.protocol, hostPort: networkCounter(item.hostPort, 65535), targetPort: networkCounter(item.targetPort, 65535),
-    ...(hostIp === null ? {} : { hostIp }), authorization: networkReference(item.authorization) };
+  return { ...span, ...(hostIp === null ? {} : { hostIp }), ...(symmetric ? { symmetric } : {}),
+    authorization: networkReference(item.authorization) };
 };
 const publishedPorts = (value: unknown): IRuntimeNetworkPublishedPort[] => {
-  const ports = networkSorted(networkList(value, 64, publishedPort), publishedPortKey);
+  const ports = publishedPortList(value, publishedPort);
   requireNetwork(ports.length > 0); return ports;
 };
-const publishedPortRequest = (value: unknown): IRuntimeNetworkPublishedPortRequest => {
-  const item = networkRecord(value, ['protocol', 'hostPort', 'targetPort']);
-  requireNetwork(item.protocol === 'tcp' || item.protocol === 'udp');
-  return { protocol: item.protocol, hostPort: networkCounter(item.hostPort, 65535), targetPort: networkCounter(item.targetPort, 65535) };
-};
+const publishedPortRequest = (value: unknown): IRuntimeNetworkPublishedPortRequest =>
+  publishedPortSpan(networkRecord(value, ['protocol', 'hostPort', 'targetPort'], ['hostPortEnd', 'symmetric']));
 const publishedPortRequests = (value: unknown): IRuntimeNetworkPublishedPortRequest[] =>
-  networkSorted(networkList(value, 64, publishedPortRequest), publishedPortKey);
+  publishedPortList(value, publishedPortRequest);
 
 /** Structural snapshot only; node placement, quota and authorization remain Cloudly's decision. */
 export const snapshotServicePublishedPorts = (value: unknown): IServicePublishedPorts => networkSafe(() => {
@@ -420,9 +549,12 @@ const endpoint = (value: unknown): IRuntimeNetworkEndpoint => {
       reporterSessionId: networkId(observed.reporterSessionId), sequence: networkCounter(observed.sequence), digest: networkDigest(observed.digest) };
   }
   requireNetwork(!item.ready || (observation !== null && observation.assignment.generation === 1));
+  const ports = hasPublishedPorts ? publishedPorts(item.publishedPorts) : null;
+  // Same-port outbound rides the public egress grant; it never grants egress of its own.
+  requireNetwork(item.publicEgress || !(ports ?? []).some(port => port.symmetric));
   return { lease, ready: item.ready, observation, publicEgress: item.publicEgress,
     platformEndpointIds: networkSorted(networkList(item.platformEndpointIds, 64, networkId), value => value),
-    ...(hasPublishedPorts ? { publishedPorts: publishedPorts(item.publishedPorts) } : {}) };
+    ...(ports === null ? {} : { publishedPorts: ports }) };
 };
 
 /** Structural snapshot only; use validate/signature/admission helpers before accepting authority. */
@@ -527,7 +659,8 @@ export const validateRuntimeNetworkProjection = async (value: unknown): Promise<
         requireNetwork(!aliases.has(name)); aliases.add(name);
       }
     }
-    const assignments = new Set<string>(), attempts = new Set<string>(), readyReplicas = new Set<string>(), hostPorts = new Set<string>();
+    const assignments = new Set<string>(), attempts = new Set<string>(), readyReplicas = new Set<string>();
+    const hostPortClaims: Array<{ node: string; first: number; last: number }> = [];
     for (const endpoint of projection.endpoints) {
       const lease = endpoint.lease, authority = allocationAuthority(lease.protectedAuthority);
       // A controller on the node itself has no other node: every endpoint it projects is local.
@@ -546,12 +679,16 @@ export const validateRuntimeNetworkProjection = async (value: unknown): Promise<
         pool.id === lease.ipv4.poolId && pool.purpose === 'workload' && networkContains(pool.prefix, lease.ipv4.linkSubnet)));
       if (networkSameScope(lease, projection)) requireNetwork(projection.handoff !== null && lease.routerIncarnationId === projection.handoff.routerIncarnationId);
       for (const id of endpoint.platformEndpointIds) requireNetwork(current.platformEndpoints.some(platform => platform.id === id));
-      for (const port of endpoint.publishedPorts ?? []) {
-        const claim = networkCanonical([lease.nodeId, port.protocol, port.hostPort]);
-        requireNetwork(!hostPorts.has(claim)); hostPorts.add(claim);
-      }
+      for (const port of endpoint.publishedPorts ?? []) hostPortClaims.push({ node: networkCanonical([lease.nodeId, port.protocol]),
+        first: port.hostPort, last: publishedPortLast(port) });
       requireNetwork(!projection.retiredLeases.some(retired => networkEqual(retired, networkReferenceOf(lease))));
     }
+    // Every port of every entry is claimed on its node: ordered by start, no claim reaches the next one.
+    hostPortClaims.sort((left, right) => left.node < right.node ? -1 : left.node > right.node ? 1 : left.first - right.first);
+    for (let index = 1; index < hostPortClaims.length; index++) {
+      const previous = hostPortClaims[index - 1], current = hostPortClaims[index];
+      requireNetwork(previous.node !== current.node || previous.last < current.first);
+    }
     for (const id of projection.hostPlatformEndpointIds ?? []) requireNetwork(current.platformEndpoints.some(platform => platform.id === id));
     for (let index = 0; index < projection.endpoints.length; index++) for (let previous = 0; previous < index; previous++) {
       requireNetwork(!networkOverlaps(projection.endpoints[index].lease.ipv4.linkSubnet, projection.endpoints[previous].lease.ipv4.linkSubnet));

package/ts/data/serviceruntime.ts

@@ -91,6 +91,7 @@ const serviceRuntimeRefusals = [
   'volume-placement-unsupported', 'volume-initialization-unknown', 'volume-ownership-unknown',
   'objectstorage-endpoint-missing', 'objectstorage-binding-invalid', 'objectstorage-environment-conflict',
   'objectstorage-endpoint-unselected', 'database-endpoint-missing', 'database-endpoint-unselected',
+  'published-port-reserved', 'published-port-symmetric-without-egress',
 ] as const;
 
 /**
@@ -149,6 +150,14 @@ export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[n
  * or an IPv6 literal is never selected. Each is judged only for an endpoint that is valid: a node
  * stating none, or an invalid one, stays `database-endpoint-missing` or `objectstorage-endpoint-missing`.
  * `platform.findUnselectedCorestoreEndpoints` is this rule; a producer answers what it returns.
+ *
+ * The two `published-port-` refusals name a service policy document whose published ports no
+ * projection may carry, so its endpoints are not compiled rather than published on some ports only.
+ * `published-port-reserved` is an entry covering a port outside
+ * `runtimeNetworkPublishedPortContract.publishablePorts` (`isRuntimeNetworkPublishedPortReserved`),
+ * which the handoff leases' `runtimeNetworkHandoffSnatPortRange` owns; a document written before
+ * that rule can hold one. `published-port-symmetric-without-egress` is a `symmetric` entry in a
+ * document whose `publicEgress` is false, which a projection endpoint refuses.
  */
 export type TServiceRuntimeRefusal = typeof serviceRuntimeRefusals[number];