@serve.zone/interfaces 32.62.0 → 32.64.0

package/readme.md

@@ -627,6 +627,26 @@ locally, but only to a workload that selects it.
 
 `getRuntimeNetworkProjectionPacketGrants` derives directed member connectivity
 and explicit local public/platform egress independently of DNS readiness.
+
+`getRuntimeNetworkProjectionPrivateMeshes` validates the complete projection and
+returns its private meshes (`IRuntimeNetworkPrivateMesh`): one per
+`(organizationId, networkId)` that some endpoint's service membership attaches,
+with the lease references of every such endpoint, local or remote, sorted by
+lease id. Meshes are sorted by organization and then network id; a network no
+endpoint attaches has no mesh, and an endpoint whose membership attaches no
+network is in none. This grouping is the one definition of who may reach whom:
+the workload grants of `getRuntimeNetworkProjectionPacketGrants` are exactly the
+ordered pairs of distinct members of each mesh with at least one end on the
+projection's node, each pair once however many networks its ends share. A
+receiver realizes a mesh from it without deriving membership again. Whether a
+member is local is its lease's node scope (the projection's `nodeId`,
+`runtimeNamespace` and `controller`), and which local members are attached, or
+whether remote members are reachable through a tunnel, is the receiver's own
+fact; the mesh grants nothing beyond the pairs above. A projection names each
+network id once and only for the organization that owns it, so the key's
+organization never separates two meshes of one validated projection; it is kept
+so that the grouping holds without that rule.
+
 `composeRuntimeNetworkProjectionDnsViews` builds one union view per local
 workload source address, with every authorized FQDN and complete ready-replica A
 set. An empty array declares NODATA; absent/unauthorized names remain NXDOMAIN,
@@ -1305,6 +1325,14 @@ and never content, and a controller and a node cannot disagree about the referen
 absence: an assignment that states no endpoint is different content, and so a different digest, from
 one that does.
 
+`designation` is the optional role its cluster gives the attempt's service, from
+`data.runtimeAssignmentDesignations`: `cluster-ingress` for the service Cloudly lists as the cluster's
+designated ingress (and delivers first). A node begins such a run before every other run it holds,
+by this statement rather than by delivery order. It is part of the attempt, so every later revision
+states the same value, and it grants nothing. A reader built before the member refuses an assignment
+that states it, so a controller states it only on a session whose offer speaks the release that added
+it or a later one.
+
 All fields except the digest itself participate in a domain-separated
 SHA-256 digest. Digests provide integrity and compare-and-swap identity;
 authentication must separately establish the trusted controller/node scope.
@@ -1564,6 +1592,15 @@ answer, more than a second beyond Cloudly's budget and below TypedSocket's 10 s
 connection-restore deadline); and a relay's `relaySessionForwardMs` (8 s) for a
 session read or report forwarded over its established Cloudly link.
 
+`data.runtimeSessionPushBounds.maximumInFlightPerNode` (8) is the other direction: how many requests a
+controller holds outstanding on one node's runtime session at once, every method and lane together
+(assignments, local storage claims, the network signing authority, projection and DNS lease renewals,
+stats reads), counted per node rather than per relay peer. A node holds that many beside the answers to
+its own requests and their cancellations without closing its session, and answers each within the
+relay's forward timeout for a push to a node (coreflow's `nodeForwardMs`, 8 s; not
+`runtimeSessionRequestBounds.relaySessionForwardMs`, which bounds the node's own requests to the
+controller); a controller that sends more may lose the session.
+
 ### Assignment-Bound Runtime Secrets
 
 `@serve.zone/interfaces/runtime` exports the Pallet assignment-secret contract.
@@ -3511,7 +3548,9 @@ checks the hostname's source profile stays the only way in whether or not the no
 reachable from elsewhere. `validateClusterRouteSourceAllowList(value, path?)` judges one list. A
 reader built before the member refuses the whole table that carries it, so an ingress that applies
 it registers with `clusterIngressCapabilities.routeSourceAllowList` (`route-source-allowlist`), and
-Cloudly sends the member only to such an ingress through a relay that reads it.
+Cloudly sends the member only to such an ingress through a relay that reads it. An ingress that
+reads the registration refusal `controller-deadline` registers with
+`clusterIngressCapabilities.controllerDeadlineRefusal` (`controller-deadline-refusal`).
 `IClusterPortRoute` forwards a TCP or UDP listen port without terminating anything. `validateClusterRouteTable(value, path?)` returns one
 named reason per violation, refuses two routes for one hostname and two port routes for one
 transport and port, and — because a validation reason travels into logs — **never quotes
@@ -3565,8 +3604,15 @@ the order Cloudly judges them: `not-ready` (Cloudly cannot judge registrations y
 not the connection Cloudly elected for its cluster), `ingress-not-designated`, `node-mismatch` (the
 node is not one the designation lets the ingress run on), `assignment-not-running` (no ready
 assignment of the ingress service runs on that node under its current session, or it does not carry
-the designation's current credential), `bearer-refused` and `conflict` (the designation, assignment
-or session changed while the registration was judged). `retryAfterMs` is how long the ingress waits
+the designation's current credential), `bearer-refused`, `conflict` (the designation, assignment
+or session changed while the registration was judged) and `controller-deadline` (Cloudly did not
+settle the registration within its request budget, `runtimeSessionRequestBounds.controllerBudgetMs`;
+a momentary state of Cloudly's, so the ingress registers again soon, and a registration whose commit
+the deadline interrupted is answered as its replay). A reader built before `controller-deadline`
+reads such a refusal as no named refusal, so Cloudly sends it only to an ingress whose registration
+states `clusterIngressCapabilities.controllerDeadlineRefusal` (`controller-deadline-refusal`) and
+answers `not-ready` to every other; the relay forwards a refusal untouched and never reads its
+reason. `retryAfterMs` is how long the ingress waits
 before it registers again, 1 s to 300 s (`clusterIngressRegistrationContract`).
 `validateClusterIngressRegistrationRefusal` names every violation and
 `readClusterIngressRegistrationRefusal(errorData)` answers the refusal or `null`, reading plain data

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '32.62.0',
+  version: '32.64.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/clusteringress.ts

@@ -44,9 +44,15 @@ export const clusterIngressLimits = Object.freeze({
  * `routeSourceAllowList`: the ingress applies `IClusterHttpRoute.sourceAllowList`. A route table
  * that carries the member is refused whole by a reader built before it, so Cloudly sends a route
  * with a source allowlist only to an ingress that registered with this capability.
+ *
+ * `controllerDeadlineRefusal`: the ingress reads the registration refusal `controller-deadline`
+ * (`clusterIngressRegistrationRefusalReasons`) as a named refusal and waits its `retryAfterMs`. A
+ * reader built before the reason reads such a refusal as no named refusal, so Cloudly answers it
+ * only to a registration that states this capability and answers `not-ready` to every other.
  */
 export const clusterIngressCapabilities = Object.freeze({
   routeSourceAllowList: 'route-source-allowlist',
+  controllerDeadlineRefusal: 'controller-deadline-refusal',
 } as const);
 
 export type TClusterIngressCapability =
@@ -618,6 +624,14 @@ export const clusterIngressRegistrationRefusalReasons = Object.freeze([
   'bearer-refused',
   /** The designation, the assignment or the session changed while the registration was judged. */
   'conflict',
+  /**
+   * Cloudly did not settle the registration within its request budget
+   * (`runtimeSessionRequestBounds.controllerBudgetMs`): a momentary state of Cloudly's, never a
+   * verdict on the ingress, which registers again soon. A registration whose commit the deadline
+   * interrupted may have been accepted; registering again is answered as its replay. Sent only to
+   * an ingress that registered with `clusterIngressCapabilities.controllerDeadlineRefusal`.
+   */
+  'controller-deadline',
 ] as const);
 
 export type TClusterIngressRegistrationRefusalReason = typeof clusterIngressRegistrationRefusalReasons[number];

package/ts/data/index.ts

@@ -46,6 +46,7 @@ export * from './networklease.js';
 export * from './networknode.js';
 export * from './networkprojection.js';
 export type { IRuntimeNetworkRouterPacketGrant, IRuntimeNetworkRouterProjection } from './networkrouter.js';
+export type { IRuntimeNetworkPrivateMesh } from './networkprivatemesh.js';
 export type { IRuntimeNetworkHostIngress, IRuntimeNetworkHostPacketGrant, IRuntimeNetworkHostProjection } from './networkhost.js';
 export { runtimeNetworkHostContract } from './networkhost.js';
 export type { IRuntimeNetworkWorkloadIngress, IRuntimeNetworkWorkloadIngressPacketGrant,
@@ -67,6 +68,7 @@ export * from './runtimestorageclaim.js';
 export * from './runtimelocalstorageclaim.js';
 export * from './runtimelocalvolumearchive.js';
 export * from './runtimesession.js';
+export * from './runtimesessionpush.js';
 export * from './runtimesessionrefusal.js';
 export * from './runtimeterminalreceipt.js';
 export * from './secret.js';

package/ts/data/networkprivatemesh.ts

@@ -0,0 +1,45 @@
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import type { IServicePrivateNetworks } from './privatenetwork.js';
+import type { IRuntimeNetworkEndpoint } from './networkprojection.js';
+import { networkCanonical, requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * One private network of one organization and every projection endpoint, local or remote, whose
+ * service membership attaches it. Any two members on different nodes may reach each other, and no
+ * other workload may: this is the grouping the projection's workload packet grants are made of.
+ */
+export interface IRuntimeNetworkPrivateMesh {
+  organizationId: string;
+  networkId: string;
+  /** The lease references of the members, sorted by lease id; never empty. */
+  members: IRuntimeAuthorityReference[];
+}
+
+const ownerKey = (value: { organizationId: string; serviceId: string }): string => networkCanonical([value.organizationId, value.serviceId]);
+
+/**
+ * Internal grouping after capture. The public helper validates the whole projection. Keyed by the
+ * membership's organization and the attached network id, sorted by both, with members sorted by
+ * lease id; a network no endpoint's membership attaches has no mesh.
+ */
+export const privateMeshEndpointsOf = (projection: {
+  memberships: IServicePrivateNetworks[];
+  endpoints: IRuntimeNetworkEndpoint[];
+}): Array<{ organizationId: string; networkId: string; members: IRuntimeNetworkEndpoint[] }> => {
+  const memberships = new Map(projection.memberships.map(member => [ownerKey(member), member]));
+  const meshes = new Map<string, { organizationId: string; networkId: string; members: IRuntimeNetworkEndpoint[] }>();
+  for (const endpoint of projection.endpoints) {
+    const member = memberships.get(ownerKey(endpoint.lease)); requireNetwork(member);
+    for (const attachment of member.attachments) {
+      const key = networkCanonical([member.organizationId, attachment.networkId]);
+      let mesh = meshes.get(key);
+      if (!mesh) meshes.set(key, mesh = { organizationId: member.organizationId, networkId: attachment.networkId, members: [] });
+      mesh.members.push(endpoint);
+    }
+  }
+  const byId = (left: IRuntimeNetworkEndpoint, right: IRuntimeNetworkEndpoint) =>
+    left.lease.id < right.lease.id ? -1 : left.lease.id > right.lease.id ? 1 : 0;
+  return [...meshes.values()].sort((left, right) => left.organizationId < right.organizationId ? -1
+    : left.organizationId > right.organizationId ? 1 : left.networkId < right.networkId ? -1 : left.networkId > right.networkId ? 1 : 0)
+    .map(mesh => ({ ...mesh, members: mesh.members.sort(byId) }));
+};

package/ts/data/networkprojection.ts

@@ -9,6 +9,7 @@ import { routerPacketGrantsOf, snapshotRouterProjection,
   type IRuntimeNetworkRouterPacketGrant, type IRuntimeNetworkRouterProjection } from './networkrouter.js';
 import { hostPacketGrantsOf, snapshotHostProjection,
   type IRuntimeNetworkHostPacketGrant, type IRuntimeNetworkHostProjection } from './networkhost.js';
+import { privateMeshEndpointsOf, type IRuntimeNetworkPrivateMesh } from './networkprivatemesh.js';
 import { snapshotWorkloadIngressProjection, workloadIngressPacketGrantsOf,
   type IRuntimeNetworkWorkloadIngressPacketGrant, type IRuntimeNetworkWorkloadIngressProjection } from './networkworkloadingress.js';
 import { requireFirstProjectionRetirement, requireProjectionRetirement, snapshotRuntimeNetworkProjectionRetirement,
@@ -601,23 +602,28 @@ export const snapshotRuntimeNetworkProjection = (value: unknown): IRuntimeNetwor
     retiredLeases: sortedReferences(item.retiredLeases), retiredHandoffs: sortedReferences(item.retiredHandoffs), digest: networkDigest(item.digest) };
 });
 
+/**
+ * Workload grants are the ordered pairs of distinct members of each private mesh with at least one
+ * end on this projection's node, each pair once however many networks its ends share; egress grants
+ * follow per local source. At most `maximumGrants` in all.
+ */
 const grantsOf = (projection: IRuntimeNetworkProjection): IRuntimeNetworkPacketGrant[] => {
   const result: IRuntimeNetworkPacketGrant[] = [];
-  const memberships = new Map(projection.memberships.map(member => [ownerKey(member), member]));
   const append = (grant: IRuntimeNetworkPacketGrant) => {
     requireNetwork(result.length < 4096); result.push(grant);
   };
+  const local = new Set(projection.endpoints.filter(endpoint => networkSameScope(endpoint.lease, projection)));
+  const granted = new Map<IRuntimeNetworkEndpoint, Set<IRuntimeNetworkEndpoint>>();
+  for (const mesh of privateMeshEndpointsOf(projection)) for (const source of mesh.members) for (const destination of mesh.members) {
+    if (source === destination || (!local.has(source) && !local.has(destination))) continue;
+    let reached = granted.get(source);
+    if (!reached) granted.set(source, reached = new Set());
+    if (reached.has(destination)) continue;
+    reached.add(destination);
+    append({ source: networkReferenceOf(source.lease), destination: { kind: 'workload', lease: networkReferenceOf(destination.lease) } });
+  }
   for (const source of projection.endpoints) {
-    const member = memberships.get(ownerKey(source.lease)); requireNetwork(member);
-    for (const destination of projection.endpoints) {
-      if (source === destination || (!networkSameScope(source.lease, projection) && !networkSameScope(destination.lease, projection))) continue;
-      const target = memberships.get(ownerKey(destination.lease)); requireNetwork(target);
-      if (member.organizationId === target.organizationId && member.attachments.some(attachment =>
-        target.attachments.some(other => other.networkId === attachment.networkId))) {
-        append({ source: networkReferenceOf(source.lease), destination: { kind: 'workload', lease: networkReferenceOf(destination.lease) } });
-      }
-    }
-    if (!networkSameScope(source.lease, projection)) continue;
+    if (!local.has(source)) continue;
     if (source.publicEgress) append({ source: networkReferenceOf(source.lease), destination: { kind: 'public' } });
     for (const id of source.platformEndpointIds) {
       const platform = projection.protectedAuthority.platformEndpoints.find(item => item.id === id); requireNetwork(platform);
@@ -726,6 +732,16 @@ export const validateRuntimeNetworkProjection = async (value: unknown): Promise<
 export const getRuntimeNetworkProjectionPacketGrants = async (value: unknown): Promise<IRuntimeNetworkPacketGrant[]> =>
   grantsOf(await validateRuntimeNetworkProjection(value));
 
+/**
+ * Every private network of every organization with the projection endpoints, local or remote, whose
+ * membership attaches it (`IRuntimeNetworkPrivateMesh`): the grouping the workload packet grants
+ * are made of, sorted by organization and network id. Which members a node realizes is its own
+ * decision; who may reach whom is this one.
+ */
+export const getRuntimeNetworkProjectionPrivateMeshes = async (value: unknown): Promise<IRuntimeNetworkPrivateMesh[]> =>
+  privateMeshEndpointsOf(await validateRuntimeNetworkProjection(value)).map(mesh => ({ organizationId: mesh.organizationId,
+    networkId: mesh.networkId, members: mesh.members.map(member => networkReferenceOf(member.lease)) }));
+
 /** Router-origin authority comes only from explicit signed selections, never DNS names or workload grants. */
 export const getRuntimeNetworkProjectionRouterPacketGrants = async (value: unknown): Promise<IRuntimeNetworkRouterPacketGrant[]> =>
   routerPacketGrantsOf(await validateRuntimeNetworkProjection(value));

package/ts/data/runtimeassignment.ts

@@ -39,6 +39,19 @@ export type TRuntimeAssignmentDisposition =
   | 'stop-preserve'
   | 'remove-runtime-preserve-storage';
 
+/**
+ * What a cluster designates the service of an attempt as, stated by the controller so a node can
+ * order its work by the service's role instead of by the order the deliveries arrived in.
+ *
+ * `cluster-ingress`: the service is its cluster's designated ingress, the service Cloudly lists as
+ * designated (`IClusterIngressDesignation` for a cluster born on Pallet,
+ * `IFleetCutoverIngressDesignation` after a Swarm cutover) and delivers first, because a cluster
+ * serves nothing until its ingress runs. A node begins such a run before every other run it holds.
+ */
+export const runtimeAssignmentDesignations = ['cluster-ingress'] as const;
+
+export type TRuntimeAssignmentDesignation = (typeof runtimeAssignmentDesignations)[number];
+
 export interface IRuntimeAssignment extends IRuntimeAssignmentScope {
   assignmentId: string;
   serviceId: string;
@@ -55,6 +68,19 @@ export interface IRuntimeAssignment extends IRuntimeAssignmentScope {
   disposition: TRuntimeAssignmentDisposition;
   /** No automatic relocation or expiry-based claim of a stopped writer. */
   offlinePolicy: 'continue-node-bound';
+  /**
+   * The cluster's designation of this attempt's service (`runtimeAssignmentDesignations`); absent
+   * for a service the cluster designates nothing. It is part of the attempt, as every member but
+   * `generation`, `previous`, `disposition` and `digest` is: every later revision of the attempt
+   * states the same value, so a designation that moves to another service reaches the nodes with
+   * the services' next attempts. It orders a node's work and grants nothing: no authority,
+   * placement, credential or network access follows from it.
+   *
+   * A reader built before this member refuses an assignment that states it (exact keys), so a
+   * controller states it only on a session whose offer speaks the release that added it or a later
+   * one, and states nothing on any other.
+   */
+  designation?: TRuntimeAssignmentDesignation;
   workload: {
     /**
      * The registry that published this image, which is the publication identity the image release
@@ -320,15 +346,21 @@ const assignmentKeys = [
   'assignmentId', 'serviceId', 'replicaId', 'attemptId', 'workerGroupId', 'siteId',
   'generation', 'previous', 'disposition', 'offlinePolicy', 'workload', 'digest',
 ] as const;
+/** Stated only for a service its cluster designates (`runtimeAssignmentDesignations`). */
+const optionalAssignmentKeys = ['designation'] as const;
 
 const assertAssignment = (valueArg: unknown): IRuntimeAssignment => {
-  if (!isExactRecord(valueArg, assignmentKeys)
+  if (!isExactRecord(valueArg, assignmentKeys, optionalAssignmentKeys)
     || !isController(valueArg.controller)
     || !isPositiveInteger(valueArg.generation) || !isDigest(valueArg.digest)
     || valueArg.offlinePolicy !== 'continue-node-bound'
     || !['run', 'stop-preserve', 'remove-runtime-preserve-storage'].includes(
       valueArg.disposition as string,
     )) fail('runtime assignment must use its exact schema');
+  if (Object.hasOwn(valueArg, 'designation')
+    && !runtimeAssignmentDesignations.some((designationArg) => designationArg === valueArg.designation)) {
+    fail('runtime assignment designation must be a stated designation');
+  }
   for (const key of ['organizationId', 'runtimeNamespace', 'assignmentId', 'serviceId', 'attemptId']) {
     if (!isIdentifier(valueArg[key])) fail(`runtime assignment ${key} must be a canonical identifier`);
   }

package/ts/data/runtimesessionpush.ts

@@ -0,0 +1,24 @@
+/**
+ * How many requests a controller holds outstanding on one node's runtime session at once.
+ *
+ * Counted per node, never per lane, method or carrier: every request a controller sends a node over
+ * its runtime session counts — `applyRuntimeAssignment`, `applyRuntimeLocalStorageClaim`,
+ * `applyRuntimeNetworkSigningAuthority`, `applyRuntimeNetworkProjection`,
+ * `applyRuntimeNetworkDnsLeaseRenewal` and `readRuntimeAssignmentStats` together, whatever pass or
+ * lane of the controller sends it — from the moment it is sent until its answer or its failure
+ * arrived. One relay peer carries a whole cluster, so the count is each node's own, not the peer's.
+ * A relay adds no request of its own while the controller's session is up (its DNS lease escrow
+ * offers one renewal per node, and only while that session is down), so it stays within the same
+ * count.
+ *
+ * A node holds this many at once beside the answers to its own requests and the cancellation each
+ * of them may draw, and never closes its session over them; it answers each within the relay's
+ * forward timeout for a push to a node (coreflow's `nodeForwardMs`, 8 s; not
+ * `runtimeSessionRequestBounds.relaySessionForwardMs`, which bounds the node's own requests to the
+ * controller), so a request the controller stopped waiting for is no longer held on the node. A
+ * controller that sends more than this may lose the node's session: the node's transport bounds
+ * what it queues and closes the connection past that bound.
+ */
+export const runtimeSessionPushBounds = Object.freeze({
+  maximumInFlightPerNode: 8,
+} as const);