@serve.zone/interfaces 31.2.0 → 31.4.0

package/readme.md

@@ -1113,6 +1113,132 @@ const certificateDomainName = data.clusterRelayCertificateDomainName(relay);
 // 'relay.cluster-a.serve.zone'
 ```
 
+Enabling a relay is one operator flip per cluster. `enableClusterRelayV1 { identity, clusterId }`
+answers with the block Cloudly published, and `disableClusterRelayV1` removes it and answers with
+an explicit `relay: null`. The caller names only the cluster: Cloudly derives the origin itself
+from that cluster and its own public hostname, and refuses the request when no DNS zone it
+manages matches the derived name, so a relay name that nothing can publish is never written.
+
+Once its socket is authenticated with `registerCloudlyClientSessionV1`, the relay sends
+`registerClusterRelayV1` carrying `IClusterRelayRegistrationV1`: the relay build, the cluster node
+it runs on, the exact endpoint it bound for its cluster's Pallet nodes, and a
+`registrationSequence` that counts up once per registration within one relay process and restarts
+at `0` when that process restarts. `validateClusterRelayRegistrationV1(value, path?)` returns one
+named reason per violation, like every validator here, and checks shape only. `listenAddress` is
+an IPv4 literal because Cloudly publishes it verbatim as the A record of the relay's certificate
+domain name — a hostname would need a `CNAME` and an IPv6 address an `AAAA` record, so admitting
+either is an additive change once Cloudly publishes it. A loopback or link-local address is
+refused by its own name, because a relay that bound one can never serve the nodes of its cluster.
+
+Authority stays with Cloudly, and none of it is a request field. The cluster is the one the
+verified machine identity on that socket names; whether `relay.nodeId` is a node of that cluster
+is decided against Cloudly's own records; and one cluster has one relay, so when two peers are
+live the one holding the highest accepted `registrationSequence` is the relay and the other is
+never selected. The response carries the origin Cloudly published, or `null` while the cluster
+carries no relay block, which a relay must read as "not enabled yet" rather than as licence to
+invent an origin: it is how the relay checks that the certificate it holds and the name its nodes
+are told to reach are the same one.
+
+```typescript
+const registration: data.IClusterRelayRegistrationV1 = {
+  schemaVersion: 1,
+  relay: {
+    version: '4.0.0',
+    nodeId: 'node-a',
+    listenAddress: '10.0.4.7',
+    listenPort: 8443,
+  },
+  registrationSequence: 0,
+};
+
+const registrationReasons = data.validateClusterRelayRegistrationV1(registration); // []
+```
+
+### Cluster Ingress
+
+A cluster's ingress terminates TLS for the hostnames its services publish and forwards to the
+host ports Pallet published for the workloads behind them. Cloudly computes what it serves — it
+is the only party that knows every service, every ready endpoint, the node address each published
+port answers on and the certificate each hostname needs — and the cluster relay carries that table
+to the ingress and the ingress's counters back. These contracts carry no version suffix and no
+schema field: the protocol version is the installed `@serve.zone/interfaces` version.
+
+`IClusterRouteTable { revision, issuedAt, routes, portRoutes }` is the whole table, never a delta.
+`revision` is its only idempotency: a relay and an ingress apply a table whose revision is greater
+than the one they hold and ignore anything else, so a repeated push, a replayed push and a push
+that crossed a newer one all settle the same way. `IClusterHttpRoute` names one hostname, its
+`destinations` (`{ address, port }`, unicast IPv4 and a real port), the `certificate` that
+terminates it and optional Basic `authentication`; `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
+certificate material or a password in a reason**.
+
+The table is secret-bearing end to end: it carries the private key of every hostname the ingress
+serves. Exclude it from hooks, logs, journals and disk on every hop, exactly as a runtime session
+credential is excluded.
+
+| Method | Direction | Body |
+| --- | --- | --- |
+| `pushClusterRouteTable` | Cloudly → relay | `{ table }` → `{ appliedRevision }` |
+| `getClusterRouteTable` | relay → Cloudly | `{}` → `{ table \| null }` |
+| `registerClusterIngress` | ingress → relay → Cloudly | `{ bearer, version, nodeId, capabilities? }` → `{ accepted: true, revision \| null }` |
+| `getClusterIngressRouteTable` | ingress → relay | `{ knownRevision \| null }` → `{ table \| null }` |
+| `getClusterTrafficStatistics` | Cloudly → relay → ingress | `{ fromDayUtc, toDayUtc, cursor?, limit }` → `{ statistics, nextCursor? }` |
+
+`null` for a table means Cloudly has computed none yet — a fact, not an empty table, and an
+ingress must not serve it as one. An ingress announces itself with a **method**, not a connection
+tag: the relay learns what connected from what it registered through, which a server owns, rather
+than from a label a client authored.
+
+**Who may be the ingress is Cloudly's decision, not the relay's.** The ingress shares the relay's
+node listener, so anything that reaches it could ask to register, and a relay cannot tell an
+ingress from anything else. `registerClusterIngress` therefore carries the `bearer` Cloudly minted
+into the ingress workload's assignment environment and travels both hops with one body: the
+ingress sends it to its relay, the relay forwards it untouched, and Cloudly verifies the bearer
+and derives the cluster from the identity tag on the relay's own session. The bearer is sensitive
+ephemeral input — excluded from hooks, logs, diagnostics and journals on every hop, and never
+quoted in a validation reason.
+
+Isolation on that shared listener is therefore by **authorization, not by routing**: only the
+connection whose registration Cloudly accepted is the ingress, `getClusterIngressRouteTable` and
+`getClusterTrafficStatistics` are answered for that connection alone, and any other connection —
+including a Pallet node's — is refused by name. `validateClusterIngressRegistration(value, path?)`
+checks shape only: whether the bearer is the one Cloudly minted is Cloudly's to verify.
+
+`IClusterTrafficStatistics` is one UTC day of one hostname's traffic on one node —
+`requests`, `bytesIn`, `bytesOut`, `connections` and the backend failures the proxy can observe
+(`connect`, `handshake`, `request`). Day buckets rather than rates: a rate answers "how busy is it
+now", which the live proxy already answers, while a bucket survives a restart, a poll that
+straddles midnight and a Cloudly outage. HTTP status classes are deliberately absent — the proxy
+exposes no status counters today, and a number this contract cannot source would be a guess.
+Readers page it exactly like CoreMail's mail statistics — the same `fromDayUtc`, `toDayUtc`,
+`cursor` and `limit`, answered as `{ statistics, nextCursor? }` — re-reading yesterday and today on
+every pass because a day only stops changing once it has closed. `dayUtc` must name a day that
+exists: the shared UTC calendar-day rule round-trips through `Date.UTC`, so `2026-13-45` is
+refused rather than stored.
+
+```typescript
+const reasons = data.validateClusterRouteTable(table); // []
+const pageReasons = data.validateClusterTrafficStatisticsPage({ statistics: [] }); // []
+const ingressReasons = data.validateClusterIngressRegistration({
+  bearer: ingressBearerFromAssignmentEnvironment,
+  version: '3.0.0',
+  nodeId: 'node-a',
+}); // []
+```
+
+### Node Uplink Address
+
+A route to a node's published host ports needs the address that node answers on, and only the
+node can prove it: it holds the uplink observation the address belongs to. It therefore states it
+on the network report it already sends — `IReportRuntimeNetworkProtectionRequestV1` gains the
+optional `uplinkAddress`, a unicast IPv4 literal that is neither loopback nor link-local
+(`runtimeNodeUplinkAddress`). Absence stays absent: a node that states no address is told apart
+from one that states a value, and nothing downstream defaults or infers one. Cloudly stores what
+the node stated and resolves it into the route table; the relay never substitutes an address of
+its own.
+
 Shared service port helpers are exported from `data` so Cloudly, App Store resolution, Coreflow, Coretraffic, Onebox, and dcrouter agree on the same normalization rules:
 
 ```typescript

package/ts/00_commitinfo_data.ts

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

package/ts/data/cluster.ts

@@ -2,6 +2,7 @@ import * as plugins from '../plugins.js';
 
 import { type IDockerRegistryInfo } from '../data/docker.js';
 import type { IClusterNode } from './clusternode.js';
+import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
 
 export interface ICluster {
   id: string;
@@ -60,7 +61,52 @@ export interface IClusterRelayV1 {
   origin: string;
 }
 
+/**
+ * What a cluster relay tells Cloudly about itself once its socket is authenticated.
+ *
+ * The relay sends this after `registerCloudlyClientSessionV1`, so the cluster it registers for
+ * is the one its verified machine identity names and is never a field here. `relay.nodeId` is
+ * the cluster node the relay process runs on, `listenAddress` and `listenPort` are the exact
+ * endpoint it bound for the Pallet nodes of its cluster, and `registrationSequence` counts up
+ * once per registration within one relay process, so Cloudly can tell a newer registration from
+ * a replayed older one while both peers are live.
+ */
+export interface IClusterRelayRegistrationV1 {
+  schemaVersion: 1;
+  relay: {
+    /** The relay build that is registering; a bounded label for operators and logs. */
+    version: string;
+    nodeId: string;
+    /**
+     * The address the relay bound, as an IPv4 literal.
+     *
+     * Cloudly publishes this value verbatim as the A record of the relay's certificate domain
+     * name, so the contract admits exactly what that record can carry: a hostname would need a
+     * `CNAME` and an IPv6 address an `AAAA` record, and neither is published today. Admitting
+     * either is an additive change once Cloudly publishes it.
+     */
+    listenAddress: string;
+    listenPort: number;
+  };
+  /** Monotonic within one relay process; it restarts at 0 when the process restarts. */
+  registrationSequence: number;
+}
+
+/**
+ * What Cloudly tells the relay back.
+ *
+ * `origin` is the origin Cloudly has published for this cluster, so a relay can check that the
+ * certificate it holds and the name its nodes are told to reach are the same one. It is `null`
+ * while the cluster carries no relay block, which a relay must treat as "not enabled yet"
+ * rather than as an origin it may invent.
+ */
+export interface IClusterRelayRegistrationResponseV1 {
+  accepted: true;
+  origin: string | null;
+}
+
 const maximumClusterRelayOriginLength = 2048;
+const maximumClusterRelayVersionLength = 64;
 
 const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
   Boolean(valueArg)
@@ -130,6 +176,86 @@ export const validateClusterRelayV1 = (
   return errors;
 };
 
+const validateClusterRelayVersion = (valueArg: unknown, pathArg: string): string[] => (
+  typeof valueArg === 'string'
+    && valueArg.length <= maximumClusterRelayVersionLength
+    && /^[0-9A-Za-z][0-9A-Za-z.+_-]*$/.test(valueArg)
+    ? []
+    : [`${pathArg} must be 1 to ${maximumClusterRelayVersionLength} characters of letters, `
+      + 'digits, dot, plus, underscore or hyphen, starting with a letter or digit']
+);
+
+/** The same node id rule a node's own runtime session registers under. */
+const validateClusterRelayNodeId = (valueArg: unknown, pathArg: string): string[] => (
+  typeof valueArg === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(valueArg)
+    ? []
+    : [`${pathArg} must be 1 to 128 characters of letters, digits, underscore or hyphen`]
+);
+
+const validateClusterRelayListenAddress = (valueArg: unknown, pathArg: string): string[] => {
+  if (!isPlausibleUnicastIpv4(valueArg)) {
+    return [`${pathArg} must be a unicast IPv4 literal`];
+  }
+  // A relay that bound one of these can never serve the nodes of its cluster, and publishing
+  // it would put an unreachable address into every node's relay origin.
+  if (valueArg.startsWith('127.')) {
+    return [`${pathArg} must not be a loopback address`];
+  }
+  if (valueArg.startsWith('169.254.')) {
+    return [`${pathArg} must not be a link-local address`];
+  }
+  return [];
+};
+
+const validateClusterRelayListenPort = (valueArg: unknown, pathArg: string): string[] => (
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= 1 && valueArg <= 65535
+    ? []
+    : [`${pathArg} must be an integer from 1 to 65535`]
+);
+
+const validateClusterRelayEndpoint = (valueArg: unknown, pathArg: string): string[] => {
+  if (!isRecord(valueArg)
+    || !hasExactKeys(valueArg, ['version', 'nodeId', 'listenAddress', 'listenPort'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  return [
+    ...validateClusterRelayVersion(valueArg.version, `${pathArg} version`),
+    ...validateClusterRelayNodeId(valueArg.nodeId, `${pathArg} nodeId`),
+    ...validateClusterRelayListenAddress(valueArg.listenAddress, `${pathArg} listenAddress`),
+    ...validateClusterRelayListenPort(valueArg.listenPort, `${pathArg} listenPort`),
+  ];
+};
+
+/**
+ * Validates one cluster relay registration and names every reason it is refused.
+ *
+ * Shape only, exactly like every other validator here: which cluster the relay speaks for comes
+ * from the verified identity on its socket, whether `relay.nodeId` is a node of that cluster is
+ * Cloudly's to decide against its own records, and whether this registration supersedes a live
+ * one is Cloudly's comparison of `registrationSequence` between peers. A registration that
+ * passes here has claimed nothing.
+ */
+export const validateClusterRelayRegistrationV1 = (
+  valueArg: unknown,
+  pathArg = 'cluster relay registration',
+): string[] => {
+  if (!isRecord(valueArg)
+    || !hasExactKeys(valueArg, ['schemaVersion', 'relay', 'registrationSequence'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (valueArg.schemaVersion !== 1) {
+    errors.push(`${pathArg} schemaVersion must be 1`);
+  }
+  errors.push(...validateClusterRelayEndpoint(valueArg.relay, `${pathArg} relay`));
+  if (typeof valueArg.registrationSequence !== 'number'
+    || !Number.isSafeInteger(valueArg.registrationSequence)
+    || valueArg.registrationSequence < 0) {
+    errors.push(`${pathArg} registrationSequence must be a non-negative safe integer`);
+  }
+  return errors;
+};
+
 /**
  * The name the relay's certificate is issued for, and the A record Cloudly
  * owns for it. Derived from the origin so every consumer derives it