@serve.zone/interfaces 32.2.0 → 32.4.0

package/dist_ts/requests/cluster.js

@@ -1,4 +1,4 @@
 import * as userInterfaces from '../data/user.js';
 import * as clusterInterfaces from '../data/cluster.js';
 import * as plugins from '../plugins.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2x1c3Rlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3JlcXVlc3RzL2NsdXN0ZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLGNBQWMsTUFBTSxpQkFBaUIsQ0FBQztBQUNsRCxPQUFPLEtBQUssaUJBQWlCLE1BQU0sb0JBQW9CLENBQUM7QUFJeEQsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2x1c3Rlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3JlcXVlc3RzL2NsdXN0ZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLGNBQWMsTUFBTSxpQkFBaUIsQ0FBQztBQUNsRCxPQUFPLEtBQUssaUJBQWlCLE1BQU0sb0JBQW9CLENBQUM7QUFLeEQsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.2.0",
+  "version": "32.4.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/readme.md

@@ -146,6 +146,22 @@ rather than with this release. `ISparkSwarmNodeHeartbeatRequest` is now owned he
 so Cloudly and Spark no longer carry private copies of it, and every Swarm-era body
 — request and answer alike — carries `protocol` and is judged in the same order.
 
+Each of the four routes has its validator here, so a server never writes its own
+member checks: `data.validateSparkSwarmNodeHeartbeatRequest`,
+`data.validateSparkMetricsSampleRequest`, `data.validateSparkActionResultRequest`
+and `data.validateSparkSwarmObservationRequest`. All four answer the same way —
+one string per refused member, naming the member, and an empty list for an
+admissible body — so a route table can hold them side by side. They read the
+envelope first (exact key set, the sender's offer, then the reporter's identity),
+then the payload: a heartbeat's metrics and full runtime description including
+each described serve.zone service, a sample's four observations and optional
+network rates, and an action result whose status is one a node can actually
+report, never `pending`. Bodies are judged member by member rather than as
+canonical bytes, because only the observation is digested and the others carry
+fractional CPU, memory and rate observations; every level is copied away from the
+caller's object first, so an accessor is refused instead of run. None of them
+authenticates a node or acts on the body.
+
 Cloudly must authenticate the bearer against current Spark authority and fence
 credential generation and session epoch transactionally before recording host
 liveness. `ISparkNodeHeartbeatReceipt` contains only server-derived acceptance
@@ -474,17 +490,25 @@ The `getRuntimeManagedVpnCredential` method contract in `requests.runtimesession
 uses `IGetRuntimeManagedVpnCredentialRequest` and
 `IGetRuntimeManagedVpnCredentialResponse`. Its request carries the exact current
 session and signed projection reference. The secret response repeats those
-bindings and supplies a QUIC relay tuple, managed authority ID, Noise server
-public key, client keypair and expiry in Unix milliseconds. Keep the response
-process-local; never persist, hash, log or embed it in a signed projection.
+bindings and supplies the `hub` tuple the node dials, the `transport` it dials it
+over (`quic` or `websocket`), the managed authority ID, the Noise server public
+key, the client keypair and the expiry in Unix milliseconds. `serverName` is present
+exactly when the transport is `websocket` — the TLS name that hub is dialled under,
+which the node cross-checks against the relay origin it stores — and absent for
+`quic`, which is dialled on the address alone. The hub is the node's own cluster's
+relay (see [Cluster VPN Hub And Network](#cluster-vpn-hub-and-network)). Keep the
+response process-local; never persist, hash, log or embed it in a signed projection.
 
 `snapshotGetRuntimeManagedVpnCredentialRequest` and its response counterpart
 capture closed detached JSON shapes and canonical 32-byte key encodings.
 `bindGetRuntimeManagedVpnCredentialRequest(request, projection, trustedSession)`
 validates the complete projection digest and binds node, controller, namespace,
 physical-session identity and projection reference. The response binder takes
-`(response, request, projection, trustedSession, now, renewal = null)` and additionally requires
-the relay's exact UDP tuple to be selected in `router.platformEndpointIds`.
+`(response, request, projection, trustedSession, now, renewal = null)` and additionally requires the
+hub's exact tuple to be selected in `router.platformEndpointIds`, carrying the protocol of the
+credential's transport — `udp` for `quic` and `tcp` for `websocket`, as
+`runtimeNetworkAddressPlanContract.hubTransports` states. A relay therefore cannot name itself: the
+endpoint has to be one the node's **signed** projection already selected.
 Expiry must be after the caller-qualified time and no later than the referenced
 projection's effective DNS window (see [DNS Lease Renewals](#dns-lease-renewals));
 acceptance before that window starts rejects.
@@ -634,30 +658,45 @@ const window = await data.getRuntimeNetworkEffectiveDnsWindow(admittedProjection
 
 `data.IRuntimeNetworkAddressPlan` is the address space an administrator gives the runtime network,
 and the single input Cloudly composes the protected authority from:
-`{ id: 'address-plan', revision, prefixes, pools, resolvers, platformEndpoints, vpn: { controlPrefix, relay } }`.
-Pools, resolvers and platform endpoints use the protected authority's own element shapes, and the
-relay uses the managed-VPN credential's `{ id, address, port }`. `platformEndpoints` never lists the
-relay: the composed authority adds it, in id order, as the UDP platform endpoint every node dials.
+`{ id: 'address-plan', revision, prefixes, pools, resolvers, platformEndpoints, vpn: { controlPrefix, hubPrefix } }`.
+Pools, resolvers and platform endpoints use the protected authority's own element shapes.
+`controlPrefix` is the private prefix VPN control addresses are allocated from, and `hubPrefix` is
+the protected prefix every cluster's VPN hub binds inside. The hub endpoints themselves are no
+administrator's input: each cluster's relay reports what it bound, and the composition turns that
+into platform endpoints, so `platformEndpoints` never lists one.
 
 `snapshotRuntimeNetworkAddressPlan` refuses any plan that could describe an authority the authority
-contract refuses. It runs `snapshotRuntimeNetworkProtectedAuthority` twice, once over the plan's
-own sets and once with the relay added, so overlapping pools, more than 16 resolvers, a resolver or
-endpoint outside `prefixes` or inside a pool, and a relay that `prefixes` do not cover are all
-refused by that one validator. On top it requires the VPN `controlPrefix` to be a private prefix no
-longer than /30 (`runtimeNetworkAddressPlanContract.maximumControlPrefixLength`) inside `prefixes`
-that overlaps no pool and holds no resolver or platform endpoint, the relay included. No minimum
-length is stated: the private-range rule already keeps it at /8 or longer.
-`composeRuntimeNetworkProtectedAuthority(plan, frame)` is the composition itself: the producer
+contract refuses: it runs `snapshotRuntimeNetworkProtectedAuthority` over the plan's own sets, so
+overlapping pools, more than 16 resolvers and a resolver or endpoint outside `prefixes` or inside a
+pool are all refused by that one validator. On top it requires both VPN prefixes to sit inside
+`prefixes`, to overlap no pool, to hold no resolver or platform endpoint, and never to overlap each
+other — control addresses live inside the tunnel, hub endpoints on the underlay. `controlPrefix` is
+additionally a private prefix no longer than /30
+(`runtimeNetworkAddressPlanContract.maximumControlPrefixLength`); no minimum length is stated,
+because the private-range rule already keeps it at /8 or longer.
+
+`data.IRuntimeNetworkVpnHub { clusterId, address, quicPort, websocketPort }` is one cluster's hub as
+its relay bound it, with `null` for a transport it did not bind and at least one of the two bound.
+`runtimeNetworkVpnHubEndpoints(hub)` is the one derivation of what it contributes:
+`<clusterId>:quic` on `udp` and `<clusterId>:ws` on `tcp`, in id order, as
+`runtimeNetworkAddressPlanContract.hubTransports` states. Every reader calls it — the composition
+that seals the authority and the router selection that names which endpoint a node may dial — so
+two readers can never derive two ids for one hub.
+`composeRuntimeNetworkProtectedAuthority(plan, frame, hubs)` is the composition itself: the producer
 supplies the frame (`TRuntimeNetworkProtectedAuthorityFrame`: authority id, generation, controller,
-previous reference and egress authorities) and receives the complete authority with its digest, so
-the validator and the protection producer can never compose differently.
+previous reference and egress authorities) and the hubs of the clusters that registered one, and
+receives the complete authority with its digest, so the validator and the protection producer can
+never compose differently. Each hub's address must sit inside `vpn.hubPrefix` and one cluster is
+named once; an empty `hubs` composes the authority of a runtime network whose clusters have no hub
+yet. One hub costs up to two of the authority's 64 platform endpoints, so 32 clusters fit one
+authority.
 
 `admitRuntimeNetworkAddressPlanChange(previous | null, next)` is the pure decision for a plan write at
 the following revision; any other revision is a contract violation. Leases and the managed VPN
 outlive a plan revision, so it answers:
 
 - `unchanged` when the content equals the stored plan; Cloudly writes nothing;
-- `refused` with `plan-vpn-immutable` when the VPN differs, `plan-pool-removed` when any pool is gone
+- `refused` with `plan-vpn-immutable` when either VPN prefix differs, `plan-pool-removed` when any pool is gone
   or changed its purpose or prefix, and `plan-prefix-shrunk` when the new prefixes, however split,
   no longer cover every address the old ones did;
 - `accepted` with the ids of the resolvers and platform endpoints the change removes or changes. An
@@ -706,7 +745,19 @@ rule read the other way, for a receiver checking a list it was sent. Canonical i
 strictly increasing in the code-unit order of the names themselves — a rule a peer
 in another language implements from the vocabulary alone, rather than from the
 order this package happens to declare it in — and both directions compare through
-that one rule, so neither can drift from the other. All fields except the digest itself participate in a domain-separated
+that one rule, so neither can drift from the other.
+
+`workload.registryHost` is the registry that published the image, which is the publication identity
+the image release is bound to, and it is never rewritten. `workload.pullEndpoint` is the optional
+`host[:port]` the node fetches the bytes from instead — a cluster whose relay forwards the registry
+states the relay's own origin, so a node pulls inside its cluster and nothing cluster-side dials the
+control plane. `data.buildRuntimeAssignmentImageReference(workload)` is the one place that choice is
+made: `pullEndpoint ?? registryHost`, digest-pinned either way, so the endpoint decides reachability
+and never content, and a controller and a node cannot disagree about the reference. Absence stays
+absence: an assignment that states no endpoint is different content, and so a different digest, from
+one that does.
+
+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.
 
@@ -1308,6 +1359,25 @@ around the request. A body that is not a storage request is refused with
 taken over. `platform.storageRequestCanonicalDigestGoldenVectors` states both
 for a filesystem request and for both object-storage deliveries.
 
+Which requests exist at all is stated by the same contract:
+
+```typescript
+const storageRequest = platform.normalizeStorageRequest(declaredRequest);
+```
+
+`platform.normalizeStorageRequest` reads a body against the exact request schema
+and returns the request in its contract shape — required members present,
+optional members carried only when declared, canonical environment keys, no
+empty `protection` block, no explicitly undefined member, no `-0` or unsafe
+integer, and plain JSON data members only. It is the value the other two
+functions are derived from: canonicalizing and digesting a request normalize it
+first, so a consumer that admits a request through this function and a control
+plane that digests it cannot accept different sets of requests. The input is
+never mutated and the returned request is a fresh object. A body that is not a
+storage request is refused with `platform.StorageContractError`, whose message
+names the failing member so a consumer can map the refusal to its own status
+vocabulary instead of restating the rules.
+
 Portable manifests and resolved bindings intentionally have no fields for
 Synology, NFS, Kerberos, Corestore, Kubernetes, Docker drivers, servers,
 exports, mount options, provider credential values, or local fallback paths. Runtimes
@@ -1631,6 +1701,54 @@ const registrationReasons = data.validateRegisterClusterRelayRequest(registratio
 How the relay reaches each node's Corestore is part of the same document: see
 [Corestore Through The Relay](#corestore-through-the-relay).
 
+### Cluster VPN Hub And Network
+
+A cluster's relay is also that cluster's managed VPN hub: every node of the cluster dials it, and
+an inter-node workload packet is relayed inside the cluster instead of crossing the control plane.
+Cloudly keeps every authority — it compiles the network and issues each node's credential — and
+carries no packet.
+
+A relay that bound a hub says so in its registration, in `relay.vpnHub`:
+`data.IClusterRelayVpnHub { publicKey, address, quicPort, websocketPort }`. It reports what it
+bound, exactly like `listenAddress` and `listenPort`: `address` is an IPv4 literal inside the
+address plan's `vpn.hubPrefix`, a transport it did not bind is `null`, and at least one of the two
+is bound. `publicKey` is the hub's Noise public key in the one canonical 32-byte base64 encoding
+every Noise key of this contract is read with — this advertisement, the managed VPN credential's
+keys and a cluster network's nodes all pass the same reader. A relay names no endpoint id and no
+TLS name of its own: Cloudly composes the endpoints with `runtimeNetworkVpnHubEndpoints` (see
+[Runtime Network Address Plan](#runtime-network-address-plan)) and states the TLS name from the
+origin it published for that relay. The member is optional — a relay that serves no hub registers
+exactly as before, and Cloudly selects no hub for that cluster, stating `relay-vpn-hub-absent`.
+`validateClusterRelayVpnHub(value, path?)` returns one named reason per violation.
+
+`data.IClusterVpnNetwork { authorityId, revision, nodes, grants }` is the whole managed VPN of one
+cluster. It is never a patch: a node or a grant the network does not carry is withdrawn, and
+membership is presence, so there is no enabled flag. Each node states `{ nodeId, publicKey,
+controlAddress, expiresAt, workloadPrefixes }`, where `expiresAt` is that node's credential expiry
+in Unix milliseconds and each prefix is `{ cidr, policyDomain }`. Each grant is one directed
+`{ sourceDomain, destinationDomain }` pair. `clusterVpnControlPolicyDomain(address)` and
+`clusterVpnWorkloadPolicyDomain(leaseDigest)` state the domain names once for both sides.
+
+`snapshotClusterVpnNetwork` requires sorted, unique members, prefixes and grants, and requires
+every grant to join two workload domains the network itself carries, on two different nodes. That
+is what a per-cluster hub means: a grant whose other end sits on another cluster's hub cannot be
+expressed at all, which is why Cloudly refuses it while it compiles, by name, with
+`grant-cross-cluster-unsupported` from `data.clusterVpnNetworkSelectionRefusals`.
+`clusterVpnNetworkContract` bounds a network at 256 nodes, 128 workload prefixes per node, 4096
+grants and 917 504 canonical bytes.
+
+`applyClusterVpnNetwork { network }` is Cloudly's push over the relay's already registered session;
+the relay answers `{ appliedRevision, state }`, where `state` is `idle`, `applying` or `failed` and
+`idle` means the pushed revision is the applied one — which is what
+`bindApplyClusterVpnNetworkResponse(response, sentRequest)` checks. `admitClusterVpnNetwork(held |
+null, next)` is the pure decision the relay makes against what its hub holds: `accepted` for a
+higher revision or an empty hub, `replay` for a repeat, and `refused` with
+`vpn-network-revision-stale` or `vpn-network-authority-foreign` from
+`data.applyClusterVpnNetworkRefusals`. `getClusterVpnNetwork` is the pull the other way, with no
+request body — the relay's socket names the cluster — answering `{ network }` or `{ network: null }`
+while the cluster has none. A hub daemon starts empty and its lifetime is the relay's own, so a
+relay that just bound one pulls instead of waiting for the next push.
+
 ### Cluster Ingress
 
 A cluster's ingress terminates TLS for the hostnames its services publish and forwards to the

package/ts/00_commitinfo_data.ts

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

package/ts/data/cluster.ts

@@ -5,6 +5,7 @@ import type { IClusterNode } from './clusternode.js';
 import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
 import { validateProtocolOfferOn, type IProtocolOffer } from '../protocol.js';
 import { hasExactKeys } from '../private/dataproperties.js';
+import { networkNoiseKey } from '../private/networkcontract.js';
 
 export interface ICluster {
   id: string;
@@ -62,6 +63,25 @@ export interface IClusterRelay {
   origin: string;
 }
 
+/**
+ * The managed VPN hub a cluster relay bound for its own cluster.
+ *
+ * The relay is its cluster's packet relay: every node of the cluster dials this hub and no
+ * inter-node packet leaves the cluster. It reports what it bound, exactly like `listenAddress` and
+ * `listenPort`, and Cloudly composes the platform endpoints from it — a relay names no endpoint id
+ * and no TLS name of its own. `publicKey` is the hub's Noise public key in the one canonical
+ * 32-byte base64 encoding every Noise key of this contract is read with; it is public material and
+ * authenticates nothing by itself. A hub that bound only one transport reports the other port as
+ * `null`.
+ */
+export interface IClusterRelayVpnHub {
+  publicKey: string;
+  /** The address the hub bound, as an IPv4 literal inside the address plan's `vpn.hubPrefix`. */
+  address: string;
+  quicPort: number | null;
+  websocketPort: number | null;
+}
+
 /**
  * What a cluster relay tells Cloudly about itself once its socket is authenticated.
  *
@@ -88,6 +108,11 @@ export interface IRegisterClusterRelayRequest {
      */
     listenAddress: string;
     listenPort: number;
+    /**
+     * Absent on a relay that serves no managed VPN hub, which registers exactly as it did before.
+     * Cloudly selects no hub for such a cluster and states `relay-vpn-hub-absent` instead.
+     */
+    vpnHub?: IClusterRelayVpnHub;
   };
   /** Monotonic within one relay process; it restarts at 0 when the process restarts. */
   registrationSequence: number;
@@ -234,9 +259,56 @@ const validateClusterRelayNonNegativeInteger = (valueArg: unknown, pathArg: stri
     : [`${pathArg} must be a non-negative safe integer`]
 );
 
+/**
+ * The one canonical 32-byte base64 reading every Noise key of this contract passes, stated as a
+ * refusal this validator's callers can collect: a hub key is the same key material the managed VPN
+ * credential carries, so it is never read by a second rule that could drift from it.
+ */
+const validateClusterRelayVpnKey = (valueArg: unknown, pathArg: string): string[] => {
+  try {
+    networkNoiseKey(valueArg);
+    return [];
+  } catch {
+    return [`${pathArg} must be a canonical 32-byte base64 public key`];
+  }
+};
+
+/** A port the hub bound, or `null` for a transport it did not bind. */
+const validateClusterRelayHubPort = (valueArg: unknown, pathArg: string): string[] => (
+  valueArg === null || validateClusterRelayListenPort(valueArg, pathArg).length === 0
+    ? []
+    : [`${pathArg} must be null or an integer from 1 to 65535`]
+);
+
+/**
+ * Validates one hub advertisement and names every reason it is refused.
+ *
+ * Shape only: whether the address sits inside the address plan's `vpn.hubPrefix` is Cloudly's to
+ * decide against the plan it stores, and the endpoints themselves are composed there.
+ */
+export const validateClusterRelayVpnHub = (
+  valueArg: unknown,
+  pathArg = 'cluster relay vpn hub',
+): string[] => {
+  if (!isRecord(valueArg)
+    || !hasExactKeys(valueArg, ['publicKey', 'address', 'quicPort', 'websocketPort'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors = [
+    ...validateClusterRelayVpnKey(valueArg.publicKey, `${pathArg} publicKey`),
+    ...validateClusterRelayListenAddress(valueArg.address, `${pathArg} address`),
+    ...validateClusterRelayHubPort(valueArg.quicPort, `${pathArg} quicPort`),
+    ...validateClusterRelayHubPort(valueArg.websocketPort, `${pathArg} websocketPort`),
+  ];
+  if (valueArg.quicPort === null && valueArg.websocketPort === null) {
+    errors.push(`${pathArg} must bind at least one of quicPort and websocketPort`);
+  }
+  return errors;
+};
+
 const validateClusterRelayEndpoint = (valueArg: unknown, pathArg: string): string[] => {
   if (!isRecord(valueArg)
-    || !hasExactKeys(valueArg, ['version', 'nodeId', 'listenAddress', 'listenPort'])) {
+    || !hasExactKeys(valueArg, ['version', 'nodeId', 'listenAddress', 'listenPort'], ['vpnHub'])) {
     return [`${pathArg} must use its exact schema`];
   }
   return [
@@ -244,6 +316,9 @@ const validateClusterRelayEndpoint = (valueArg: unknown, pathArg: string): strin
     ...validateClusterRelayIdentifier(valueArg.nodeId, `${pathArg} nodeId`),
     ...validateClusterRelayListenAddress(valueArg.listenAddress, `${pathArg} listenAddress`),
     ...validateClusterRelayListenPort(valueArg.listenPort, `${pathArg} listenPort`),
+    ...(Object.keys(valueArg).includes('vpnHub')
+      ? validateClusterRelayVpnHub(valueArg.vpnHub, `${pathArg} vpnHub`)
+      : []),
   ];
 };