@serve.zone/interfaces 32.29.0 → 32.31.0

package/ts/data/networkprojection.ts

@@ -2,7 +2,7 @@ import type { TSha256Digest } from './immutableimage.js';
 import type { IRuntimeAssignmentReference, IRuntimeAuthorityReference, IRuntimeController } from './runtimeassignment.js';
 import { isRuntimeReplicaId, snapshotRuntimeAssignment, validateRuntimeAssignment } from './runtimeassignment.js';
 import type { IRuntimeNetworkHandoffLease, IRuntimeNetworkProtectedAuthority } from './networkauthority.js';
-import { bindRuntimeNetworkHandoffLease, computeRuntimeNetworkProtectedAuthorityDigest,
+import { bindRuntimeNetworkHandoffLease, computeRuntimeNetworkProtectedAuthorityDigest, runtimeNetworkAuthorityContract,
   snapshotRuntimeNetworkHandoffLease, snapshotRuntimeNetworkProtectedAuthority } from './networkauthority.js';
 import type { IPrivateNetwork, IServicePrivateNetworks, IServicePrivateNetworkDnsPolicy } from './privatenetwork.js';
 import { routerPacketGrantsOf, snapshotRouterProjection,
@@ -61,15 +61,35 @@ 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`.
+   */
+  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,37 +104,121 @@ 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. */
+  symmetric?: true;
 }
 
-/** Current authorized published-port policy for one service. */
+/**
+ * Current authorized published-port policy for one service.
+ *
+ * The published-port half of the service's one policy document; `IServiceNetworkEgress` reads the
+ * egress half of the same document, so both carry the same `revision`.
+ */
 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. Empty means the service publishes nothing.
+   */
   publishedPorts: IRuntimeNetworkPublishedPortRequest[];
 }
 
-/** Exact desired policy. Node-level host-port placement remains Cloudly's decision. */
+/**
+ * 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
+ * no published ports. From then on both reads return it, never null. It is an explicit policy: an
+ * attached spec stating `publicEgress: false` and `platformEndpointIds: []` matches it and reaches
+ * no public address and no platform endpoint; `network-policy-missing` means the service has no
+ * document at all.
+ */
 export interface ISetServicePublishedPorts {
   organizationId: string;
   serviceId: string;
   /** Retain the exact body and this identifier across retries. */
   mutationId: string;
-  /** null means the service has never had a published-port document; not an empty list. */
+  /**
+   * The revision of the service's one policy document the caller read, shared with its egress: an
+   * accepted `ISetServiceNetworkEgress` advances it too. null means the service has never had a
+   * policy document, neither published ports nor egress; it is not an empty list.
+   */
   expectedRevision: number | null;
   publishedPorts: IRuntimeNetworkPublishedPortRequest[];
 }
 
+/**
+ * Current authorized egress policy for one service: whether its attached workloads reach the public
+ * internet, and which platform endpoints of the protected authority they reach.
+ *
+ * The egress half of the service's one policy document; `IServicePublishedPorts` reads the
+ * published-port half of the same document, so both carry the same `revision`. Every projection
+ * endpoint of the service carries exactly these values (`IRuntimeNetworkEndpoint`), and an attached
+ * runtime spec (`TServiceRuntimeNetwork`) is admitted only while it states the same ones: its
+ * disagreement is `network-policy-mismatch`, a service without a document `network-policy-missing`.
+ * Nothing else grants a workload egress.
+ */
+export interface IServiceNetworkEgress {
+  organizationId: string;
+  serviceId: string;
+  revision: number;
+  /** TCP/UDP only; the complete protected union remains denied. */
+  publicEgress: boolean;
+  /**
+   * Ids of `IRuntimeNetworkProtectedAuthority.platformEndpoints`, sorted and unique, at most
+   * `runtimeNetworkAuthorityContract.maximumPlatformEndpoints`. Empty selects none.
+   */
+  platformEndpointIds: string[];
+}
+
+/**
+ * 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, 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`
+ * with egress `publicEgress: false` and `platformEndpointIds: []`, `setServiceNetworkEgress` with
+ * no published ports. From then on both reads return it, never null. It is an explicit policy: an
+ * attached spec stating `publicEgress: false` and `platformEndpointIds: []` matches it and reaches
+ * no public address and no platform endpoint; `network-policy-missing` means the service has no
+ * document at all.
+ */
+export interface ISetServiceNetworkEgress {
+  organizationId: string;
+  serviceId: string;
+  /** Retain the exact body and this identifier across retries. */
+  mutationId: string;
+  /**
+   * The revision of the service's one policy document the caller read, shared with its published
+   * ports: an accepted `ISetServicePublishedPorts` advances it too. null means the service has
+   * never had a policy document, neither published ports nor egress.
+   */
+  expectedRevision: number | null;
+  publicEgress: boolean;
+  platformEndpointIds: string[];
+}
+
 /** Controller-owned readiness evidence. A signature does not prove this evidence's provenance. */
 export interface IRuntimeNetworkEndpoint {
   lease: IRuntimeNetworkWorkloadLease;
@@ -128,7 +232,11 @@ 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.
+   */
   publishedPorts?: IRuntimeNetworkPublishedPort[];
 }
 
@@ -216,6 +324,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;
@@ -276,28 +401,59 @@ 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;
+
+/** 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, and bounded in entries and in covered ports. */
+const publishedPortList = <T extends TPublishedPortSpan>(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);
+  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(() => {
@@ -313,6 +469,28 @@ export const snapshotSetServicePublishedPorts = (value: unknown): ISetServicePub
     publishedPorts: publishedPortRequests(item.publishedPorts) };
 });
 
+const servicePlatformEndpointIds = (value: unknown): string[] => networkSorted(
+  networkList(value, runtimeNetworkAuthorityContract.maximumPlatformEndpoints, networkId), id => id);
+const servicePublicEgress = (value: unknown): boolean => {
+  requireNetwork(typeof value === 'boolean'); return value;
+};
+
+/** Structural snapshot only; whether each id names a current platform endpoint remains Cloudly's decision. */
+export const snapshotServiceNetworkEgress = (value: unknown): IServiceNetworkEgress => networkSafe(() => {
+  const item = networkRecord(value, ['organizationId', 'serviceId', 'revision', 'publicEgress', 'platformEndpointIds']);
+  return { organizationId: networkId(item.organizationId), serviceId: networkId(item.serviceId),
+    revision: networkCounter(item.revision), publicEgress: servicePublicEgress(item.publicEgress),
+    platformEndpointIds: servicePlatformEndpointIds(item.platformEndpointIds) };
+});
+
+export const snapshotSetServiceNetworkEgress = (value: unknown): ISetServiceNetworkEgress => networkSafe(() => {
+  const item = networkRecord(value, ['organizationId', 'serviceId', 'mutationId', 'expectedRevision', 'publicEgress',
+    'platformEndpointIds']);
+  return { organizationId: networkId(item.organizationId), serviceId: networkId(item.serviceId),
+    mutationId: networkId(item.mutationId), expectedRevision: item.expectedRevision === null ? null : networkCounter(item.expectedRevision),
+    publicEgress: servicePublicEgress(item.publicEgress), platformEndpointIds: servicePlatformEndpointIds(item.platformEndpointIds) };
+});
+
 const endpoint = (value: unknown): IRuntimeNetworkEndpoint => {
   const hasPublishedPorts = value !== null && typeof value === 'object' && Object.hasOwn(value, 'publishedPorts');
   const item = networkRecord(value, ['lease', 'ready', 'observation', 'publicEgress', 'platformEndpointIds',
@@ -328,9 +506,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. */
@@ -435,7 +616,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.
@@ -454,12 +636,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

@@ -33,7 +33,8 @@ export interface IServiceRuntimeProfile {
 
 /**
  * `isolated` gives the workload no network authority. `attached` joins the runtime network with
- * public egress on or off and the platform endpoints it may reach, by id: sorted and unique.
+ * public egress on or off and the platform endpoints it may reach, by id: sorted and unique. The
+ * service's `IServiceNetworkEgress` must state the same values, or the workload is not admitted.
  */
 export type TServiceRuntimeNetwork =
   | { mode: 'isolated' }
@@ -89,7 +90,8 @@ const serviceRuntimeRefusals = [
   'volume-driver-unsupported', 'volume-options-unsupported', 'volume-shared-unsupported',
   'volume-placement-unsupported', 'volume-initialization-unknown', 'volume-ownership-unknown',
   'objectstorage-endpoint-missing', 'objectstorage-binding-invalid', 'objectstorage-environment-conflict',
-  'database-endpoint-missing',
+  'objectstorage-endpoint-unselected', 'database-endpoint-missing', 'database-endpoint-unselected',
+  'published-port-reserved', 'published-port-symmetric-without-egress',
 ] as const;
 
 /**
@@ -114,7 +116,8 @@ export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[n
  * `port-protocol-unsupported` is about one port's protocol — and `node-authority-unsupported` is a
  * node whose session resolved fewer workload authorities than this spec needs, which the admit step
  * refuses rather than handing the node work it would silently park. An attached network needs an
- * explicit matching policy and a current workload address pool; neither is defaulted.
+ * explicit matching policy (`IServiceNetworkEgress`, written by `setServiceNetworkEgress`) and a
+ * current workload address pool; neither is defaulted.
  *
  * The volume refusals name what a local storage claim cannot express: `volume-driver-unsupported`
  * a volume of a driver other than a node-local directory, `volume-options-unsupported` driver or
@@ -133,6 +136,28 @@ export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[n
  * `database-endpoint-missing` is an enabled database binding placed on a node that states no valid
  * `corestoreDatabase`: its credential cannot be addressed to any host a workload reaches, so it is
  * neither granted nor published, and the workload is not started with a guessed one.
+ *
+ * The two `-unselected` refusals name a binding endpoint the workload's network cannot reach, so a
+ * workload is refused rather than started against a connection that stays dark. A workload reaches
+ * a platform endpoint only when its spec's attached network selects it (`platformEndpointIds`), and
+ * an `isolated` network selects none. `database-endpoint-unselected` is an enabled database binding
+ * whose node's valid `corestoreDatabase` is not a selected endpoint: none of the selected
+ * `IRuntimeNetworkProtectedAuthority.platformEndpoints` has the endpoint's `host` as its `address`,
+ * `tcp` as its `protocol` and the endpoint's `port` as its `port`. `objectstorage-endpoint-unselected`
+ * is the same for an enabled object-storage binding's node's valid `corestoreObjectStorage`, whose
+ * `endpoint` origin states the host and the port (the scheme's default, 80 for `http:` and 443 for
+ * `https:`, when it states none). Platform endpoints are IPv4, so an endpoint whose host is a DNS name
+ * 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];
 

package/ts/platform/corestoreendpointselection.ts

@@ -0,0 +1,79 @@
+import type { IRuntimeNetworkProtectedAuthority } from '../data/networkauthority.js';
+import type { TServiceRuntimeNetwork, TServiceRuntimeRefusal } from '../data/serviceruntime.js';
+import { isNetworkIpv4 } from '../private/networkcontract.js';
+import { validatePlatformDatabaseEndpoint, type IPlatformDatabaseEndpoint } from './database.js';
+import { validatePlatformObjectStorageEndpoint, type IPlatformObjectStorageEndpoint } from './objectstorage.js';
+
+/** The service runtime refusals a Corestore endpoint the workload's network does not select raises. */
+export type TCorestoreEndpointSelectionRefusal = Extract<TServiceRuntimeRefusal,
+  'database-endpoint-unselected' | 'objectstorage-endpoint-unselected'>;
+
+/** What `findUnselectedCorestoreEndpoints` judges for one node a service's bindings are placed on. */
+export interface ICorestoreEndpointSelection {
+  /**
+   * The node's `corestoreDatabase` when an enabled database binding of the service is placed on it,
+   * otherwise `null`. A node stating none is `database-endpoint-missing`, never judged here.
+   */
+  database: IPlatformDatabaseEndpoint | null;
+  /**
+   * The node's `corestoreObjectStorage` when an enabled object-storage binding of the service is
+   * placed on it, otherwise `null`. A node stating none is `objectstorage-endpoint-missing`.
+   */
+  objectStorage: IPlatformObjectStorageEndpoint | null;
+  /** The current protected authority's platform endpoints, which the selected ids resolve against. */
+  platformEndpoints: IRuntimeNetworkProtectedAuthority['platformEndpoints'];
+  /** The runtime spec's network: `attached` selects its `platformEndpointIds`, `isolated` selects none. */
+  network: TServiceRuntimeNetwork;
+}
+
+type TPlatformEndpoint = IRuntimeNetworkProtectedAuthority['platformEndpoints'][number];
+
+const selectedPlatformEndpoints = (selectionArg: ICorestoreEndpointSelection): TPlatformEndpoint[] => {
+  if (selectionArg.network.mode !== 'attached') return [];
+  const selectedIds = new Set(selectionArg.network.platformEndpointIds);
+  return selectionArg.platformEndpoints.filter((endpointArg) => selectedIds.has(endpointArg.id));
+};
+
+/** Platform endpoints are IPv4, so only a canonical IPv4 host can be one; a DNS name or IPv6 literal never is. */
+const selectsTcp = (endpointsArg: TPlatformEndpoint[], hostArg: string, portArg: number): boolean => (
+  isNetworkIpv4(hostArg) && endpointsArg.some((endpointArg) => endpointArg.address === hostArg
+    && endpointArg.protocol === 'tcp' && endpointArg.port === portArg)
+);
+
+/** The origin's port, or the scheme's default (80 for `http:`, 443 for `https:`) when it states none. */
+const objectStorageOriginPort = (originArg: URL): number => (
+  originArg.port === '' ? (originArg.protocol === 'https:' ? 443 : 80) : Number(originArg.port)
+);
+
+/**
+ * Which of a node's Corestore endpoints a service's workload would dial without its network
+ * selecting them, as the service runtime refusals that name them; empty when none.
+ *
+ * An endpoint is selected when one of the spec's selected platform endpoints has the endpoint's host
+ * as its `address`, `tcp` as its `protocol` and the endpoint's port as its `port`: the database
+ * endpoint's `host` and `port`, and the object-storage endpoint origin's host and port, or 80 for
+ * `http:` and 443 for `https:` when the origin states none. An `isolated` network selects nothing, a
+ * selected id the protected authority does not hold selects nothing, and a DNS-name or IPv6 host is
+ * never selected. Only a valid endpoint is judged: one `validatePlatformDatabaseEndpoint` or
+ * `validatePlatformObjectStorageEndpoint` refuses is the `-missing` refusal's, not this one's. The
+ * answer is sorted, so it does not depend on the order of the inputs.
+ */
+export const findUnselectedCorestoreEndpoints = (
+  selectionArg: ICorestoreEndpointSelection,
+): TCorestoreEndpointSelectionRefusal[] => {
+  const selected = selectedPlatformEndpoints(selectionArg);
+  const refusals: TCorestoreEndpointSelectionRefusal[] = [];
+  const database = selectionArg.database;
+  if (database !== null && validatePlatformDatabaseEndpoint(database).length === 0
+    && !selectsTcp(selected, database.host, database.port)) {
+    refusals.push('database-endpoint-unselected');
+  }
+  const objectStorage = selectionArg.objectStorage;
+  if (objectStorage !== null && validatePlatformObjectStorageEndpoint(objectStorage).length === 0) {
+    const origin = new URL(objectStorage.endpoint);
+    if (!selectsTcp(selected, origin.hostname, objectStorageOriginPort(origin))) {
+      refusals.push('objectstorage-endpoint-unselected');
+    }
+  }
+  return refusals;
+};

package/ts/platform/index.ts

@@ -1,5 +1,6 @@
 import * as ai from './ai.js';
 import * as backup from './backup.js';
+import * as corestoreendpointselection from './corestoreendpointselection.js';
 import * as database from './database.js';
 import * as email from './email.js';
 import * as letter from './letter.js';
@@ -17,6 +18,7 @@ import * as types from './types.js';
 export {
   ai,
   backup,
+  corestoreendpointselection,
   database,
   email,
   letter,
@@ -32,6 +34,7 @@ export {
   types,
 };
 
+export * from './corestoreendpointselection.js';
 export * from './database.js';
 export * from './storage.js';
 export * from './objectstorage.js';

package/ts/platform/objectstorage.ts

@@ -102,6 +102,10 @@ export const validatePlatformObjectStorageEndpoint = (
         errors.push(`${pathArg} endpoint must be a canonical origin without a path, query, `
           + 'fragment, trailing slash or default port');
       }
+      // A URL parser refuses a port above 65535 but reads port 0 as stated; no workload dials it.
+      if (parsedEndpoint.port !== '' && Number(parsedEndpoint.port) < 1) {
+        errors.push(`${pathArg} endpoint port must be from 1 to 65535`);
+      }
     }
   }
   if (typeof valueArg.region !== 'string'

package/ts/private/networkcontract.ts

@@ -209,10 +209,14 @@ export const networkHash = async (domain: string, value: { digest: TSha256Digest
   const { digest: omitted, ...payload } = value;
   return `sha256:${await createCanonicalJsonSha256Hex(networkCanonical({ domain, payload }), failNetwork)}`;
 };
-export const networkIpv4 = (value: unknown): string => {
-  requireNetwork(typeof value === 'string' && value.length <= 15);
+/** A canonical dotted-quad IPv4 literal: four decimal octets, no leading zeros. */
+export const isNetworkIpv4 = (value: unknown): value is string => {
+  if (typeof value !== 'string' || value.length > 15) return false;
   const parts = value.split('.');
-  requireNetwork(parts.length === 4 && parts.every(part => /^(?:0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255));
+  return parts.length === 4 && parts.every(part => /^(?:0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255);
+};
+export const networkIpv4 = (value: unknown): string => {
+  requireNetwork(isNetworkIpv4(value));
   return value;
 };
 export const networkIpv4Number = (value: string): number => value.split('.').reduce((sum, part) => sum * 256 + Number(part), 0);

package/ts/requests/network.ts

@@ -6,7 +6,9 @@ import type {
   IPrivateNetwork, IServicePrivateNetworks, ISetServicePrivateNetworks,
   TPrivateNetworkMutation,
 } from '../data/privatenetwork.js';
-import type { IServicePublishedPorts, ISetServicePublishedPorts } from '../data/networkprojection.js';
+import type {
+  IServiceNetworkEgress, IServicePublishedPorts, ISetServiceNetworkEgress, ISetServicePublishedPorts,
+} from '../data/networkprojection.js';
 
 /** Current organization picker data. Entries are never cached authorization grants. */
 export interface IReq_Cloudly_ListOwnedOrganizations extends plugins.typedrequestInterfaces.implementsTR<
@@ -71,7 +73,7 @@ export interface IReq_Cloudly_SetServicePrivateNetworks extends plugins.typedreq
   response: { membership: IServicePrivateNetworks; replayed: boolean };
 }
 
-/** null means the service has never had an authorized published-port policy. */
+/** null means the service has never had a policy document, neither published ports nor egress. */
 export interface IReq_Cloudly_GetServicePublishedPorts extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_GetServicePublishedPorts
 > {
@@ -80,6 +82,17 @@ export interface IReq_Cloudly_GetServicePublishedPorts extends plugins.typedrequ
   response: { publishedPorts: IServicePublishedPorts | null };
 }
 
+/**
+ * Writes the published-port half of one service's policy document, carrying its egress forward.
+ *
+ * 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
+ * no published ports. From then on both reads return it, never null. It is an explicit policy: an
+ * attached spec stating `publicEgress: false` and `platformEndpointIds: []` matches it and reaches
+ * no public address and no platform endpoint; `network-policy-missing` means the service has no
+ * document at all.
+ */
 export interface IReq_Cloudly_SetServicePublishedPorts extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_SetServicePublishedPorts
 > {
@@ -93,6 +106,47 @@ export interface IReq_Cloudly_SetServicePublishedPorts extends plugins.typedrequ
   response: { publishedPorts: IServicePublishedPorts; replayed: boolean };
 }
 
+/**
+ * The egress half of one service's policy document; null means the service has never had a policy
+ * document. Only a verified administrator reads it: platform endpoints are platform authority.
+ */
+export interface IReq_Admin_Cloudly_GetServiceNetworkEgress extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_Cloudly_GetServiceNetworkEgress
+> {
+  method: 'getServiceNetworkEgress';
+  request: { identity: IIdentityCredential; organizationId: string; serviceId: string };
+  response: { networkEgress: IServiceNetworkEgress | null };
+}
+
+/**
+ * Writes the egress half of one service's policy document, carrying its published ports forward.
+ *
+ * Only a verified administrator writes it, as only an administrator writes the runtime spec whose
+ * attached network must state the same values. `expectedRevision` is the revision of the one
+ * document shared with the published ports; any other stored revision refuses the write, and an id
+ * that names no current platform endpoint refuses it. A retry of the exact body under the same
+ * `mutationId` answers the stored document with `replayed: true`.
+ *
+ * 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
+ * no published ports. From then on both reads return it, never null. It is an explicit policy: an
+ * attached spec stating `publicEgress: false` and `platformEndpointIds: []` matches it and reaches
+ * no public address and no platform endpoint; `network-policy-missing` means the service has no
+ * document at all.
+ */
+export interface IReq_Admin_Cloudly_SetServiceNetworkEgress extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_Cloudly_SetServiceNetworkEgress
+> {
+  method: 'setServiceNetworkEgress';
+  request: { identity: IIdentityCredential; mutation: ISetServiceNetworkEgress };
+  /**
+   * The accepted document including its `revision`; historical on replay. Acceptance is neither an
+   * admitted workload nor applied packet state.
+   */
+  response: { networkEgress: IServiceNetworkEgress; replayed: boolean };
+}
+
 export interface IRequest_Any_Cloudly_GetNetworkNodes {
   method: 'getNetworkNodes';
   request: {};