@serve.zone/interfaces 32.21.0 → 32.23.0

package/readme.md

@@ -572,6 +572,41 @@ overlapping current grants reject, and up to 4,096 retained withdrawals carry
 forward until the caller supplies its exact joined application of the preceding
 projection.
 
+The optional `IRuntimeNetworkProjection.workloadIngress` member exists only on
+`cloudly` projections; any other controller kind carrying it rejects. It is how
+the cluster ingress workload reaches the workloads it routes to without a
+published host port: each `grants` entry names the exact lease reference of the
+ingress workload (`source`), the exact lease reference of the target workload
+(`destination`), a protocol, the target's own listening port and an
+`authorization` reference. Unlike the full-mesh workload grants, it needs neither
+the same organization nor a shared private network, it opens exactly one port,
+and it is one-way: nothing flows back except the replies of a connection the
+ingress opened. Both leases must be endpoints of the projection, they must
+differ, and at least one of them must be placed on the projection's own node.
+Entries are unique and strictly ordered by `[source.id, destination.id, protocol,
+port]`; at most 1,024 are allowed (`runtimeNetworkWorkloadIngressContract`). The
+authorization is signed content, not grant identity. A projection that omits the
+member retains its exact canonical bytes, digest and signature.
+`getRuntimeNetworkProjectionWorkloadIngressPacketGrants` validates the complete
+projection and returns detached `IRuntimeNetworkWorkloadIngressPacketGrant`s
+(`{ source, destination: { lease, protocol, port } }`). Their withdrawals follow
+the host rules: an omitted grant needs its exact withdrawal, unknown or current
+denials reject, and up to 4,096 retained withdrawals carry forward until the
+exact joined application of the preceding projection is supplied. Cloudly routes
+a cluster ingress route to the target lease address and port once the grant
+exists.
+
+The optional `IRuntimeNetworkProjection.hostPlatformEndpointIds` lists the ids of
+the protected authority's platform endpoints whose address the projection's
+node's own host carries, such as a relay listener or a Corestore beside the node
+on one machine. A node delivers workload flows to those endpoints locally instead
+of forwarding them. The list is sorted, unique, never empty when present, and
+every id must be a current platform endpoint; omitting it keeps the canonical
+bytes and states that no endpoint is local. It grants nothing: a workload still
+reaches only the endpoints it selects. The platform endpoint contract itself
+(`{ id, address, protocol, port }`) names no node, which is why this statement is
+per projection.
+
 `admitRuntimeNetworkProjection` checks exact predecessor/replay identity and
 rejects changed same-generation content, regressed membership/readiness evidence,
 changed immutable address/DNS keys, and omitted packet grants without explicit
@@ -811,6 +846,15 @@ named once; an empty `hubs` composes the authority of a runtime network whose cl
 yet. One hub costs one of the authority's 64 platform endpoints, so 64 clusters fit one
 authority.
 
+A single host that carries both a cluster's hub and platform endpoints, for example the relay
+listener and a Corestore, holds more than one address. The hub address sits inside `vpn.hubPrefix`,
+as every hub's does. The plan's own platform endpoints may not: they sit on another address of the
+same host, inside `prefixes`, outside every pool and outside both VPN prefixes. Several endpoints may
+share that one address on distinct ports, because the authority requires only each
+`address:port:protocol` to be unique. For example, with `hubPrefix` `192.0.2.0/28`, the hub binds
+`192.0.2.1` and the plan lists the relay listener and Corestore on `192.0.2.17` with two ports. The
+node's projection then names those endpoints in `hostPlatformEndpointIds`.
+
 `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:
@@ -1373,12 +1417,23 @@ phase, settlement, release or authority booleans or evidence.
 `data.IServiceRuntimeStatus { id, specRevision, state, reason, changedAt }` is the producer's verdict
 on one spec revision, and each reason belongs to exactly one state. `converged` and `converging`
 carry `reason: null`. `waiting` carries a `TServiceRuntimeWaitingReason`: `node-network-pending`,
-`conflict` or `failure-backoff`. `refused` carries a `TServiceRuntimeRefusal`:
+`conflict`, `failure-backoff`, `storage-import-pending` (an `import` local storage claim whose bytes
+have not arrived on its node), `bindings-pending` (the secret manifest does not cover every enabled
+binding of the service yet) or `legacy-adoption-pending` (a Corestore binding of the service waits for
+the offline adoption of its legacy resource, see
+[Corestore Legacy Resource Adoption](#corestore-legacy-resource-adoption)). `refused` carries a
+`TServiceRuntimeRefusal`:
 `cluster-runtime-missing`, `organization-missing`, `image-plan-missing`, `platform-unsupported`,
 `secrets-unsupported`, `volumes-unsupported`, `port-protocol-unsupported`, `ports-too-many`,
 `readiness-target-undeclared`, `environment-too-large`, `no-eligible-node`, `replica-limit`,
 `node-authority-unsupported`, `network-policy-missing`, `network-policy-mismatch`,
-`network-workload-pool-missing` or `network-workload-pool-exhausted`. `ports-too-many` is a service declaring more target ports than the
+`network-workload-pool-missing`, `network-workload-pool-exhausted`, `volume-driver-unsupported`,
+`volume-options-unsupported`, `volume-shared-unsupported`, `volume-placement-unsupported`,
+`volume-initialization-unknown` or `volume-ownership-unknown`. The first four volume refusals name
+what a local storage claim cannot express: a volume driver other than a node-local directory, driver
+or mount options, one volume mounted by more than one replica or service, and a placement that does
+not pin each volume to one node. The last two name what Cloudly will not guess, see
+[Service Volume Initialization](#service-volume-initialization). `ports-too-many` is a service declaring more target ports than the
 `runtimeConfigContract.maximumTargetPorts` (64) a config carries, where `port-protocol-unsupported`
 is about one port's protocol; `node-authority-unsupported` is a node whose session resolved fewer
 workload authorities than the spec needs, refused at the admit step rather than handed to a node
@@ -1390,6 +1445,52 @@ is `network-policy-missing`, and a disagreement with the requested egress or pla
 retires running slots.
 `snapshotServiceRuntimeStatus` enforces the pairing.
 
+### Service Volume Initialization
+
+A local storage claim has to say how its volume starts: `empty` with an owner and mode, or `import`
+of bytes that already exist. `IServiceVolume.initialization` (`TServiceVolumeInitialization`) is
+where the service states it, per volume, beside the mount path it belongs to:
+
+- `{ kind: 'empty', ownership }` creates an empty root. `ownership` is
+  `{ kind: 'explicit', uid, gid, mode }`, or `{ kind: 'run-as', mode }`, which takes the owner from
+  the runtime spec's `profile.runAs`. The mode is always stated; it holds directory permission bits
+  only (`serviceVolumeInitializationContract.directoryModeBits`, `0o3777`, setuid refused).
+- `{ kind: 'import', source: { kind: 'docker-volume', volumeName } }` waits for the bytes of an
+  existing Docker volume on the claim node's host, named exactly as Docker lists it (a
+  Corestore-driver volume included). The operator copies that tree into the node's import directory;
+  the claim does not carry the source, and the node never reads it.
+
+It lives on the volume and not on the runtime spec because it is a fact about the volume's data,
+which the service declares, while the runtime spec carries only execution policy and is stored
+exactly, so a new member there would refuse every stored spec. It is server-managed:
+`setServiceVolumeInitialization { identity, serviceId, mountPath, expected, initialization }` is its
+only write. The volume is named by its exact mount path; `expected` is the value the caller read, or
+`null` for none, and any other stored value refuses. `createService` and `updateService` take volumes
+as `TServiceWritableVolume` (no `initialization`) and Cloudly refuses one that states it; a stored
+initialization stays with the volume of the same mount path and goes with the volume. Refusals travel
+as `IServiceVolumeInitializationErrorData { code, retryable: false }`: `volume-not-found`,
+`conflict`, `volume-initialization-invalid`, and `volume-initialization-bound`, a change while a
+bound local storage claim of the volume exists.
+
+`validateServiceVolumeInitialization(value, path?)` names every reason a value is refused.
+`deriveServiceVolumeClaimInitialization(initialization, runAs)` is the one rule for the claim fields,
+and nothing in it is a default:
+
+| Volume initialization | `runAs` | Claim `initialization` / `initialOwnership` |
+| --- | --- | --- |
+| absent | any | refused `volume-initialization-unknown` |
+| `empty`, `explicit` | any | `empty` / the stated `{ uid, gid, mode }` |
+| `empty`, `run-as` | `{ user, group }` | `empty` / `{ uid: user, gid: group, mode }` |
+| `empty`, `run-as` | `null` | refused `volume-ownership-unknown` |
+| `import` | any | `import` / `null` |
+
+An absent initialization is refused rather than created empty, because an empty volume in front of a
+service whose data sits in a legacy Docker volume would start that service without its data. A
+`run-as` ownership under `runAs: null` is refused because the image's own user is not a number
+Cloudly knows. The rule decides the first generation of a claim only: every later generation carries
+that claim's own initialization and ownership, whatever `runAs` says by then, since the node refuses
+a claim whose initial ownership changed.
+
 ### Runtime Assignment Views
 
 `data.IServiceRuntimeAssignmentView` is one replica slot's current assignment as an administrator
@@ -1881,6 +1982,47 @@ storage provider's binding identity/generation, selected policy, matching observ
 join: callers still authenticate Cloudly and the provider, check current readiness and retain the
 native fence.
 
+### Runtime local storage claims
+
+`data.IRuntimeLocalStorageClaim` is a controller's authority for one retained, node-local volume of
+one service. Cloudly and Onebox issue it alike (`controller.kind` is `cloudly` or `onebox`). It names
+the claim revision (`id`, `generation`, `previous`), the organization, cluster, node, runtime
+namespace, service and the service's own `volumeId`, and it states:
+
+- `source`: `{ kind: 'directory' }`, a node-local directory the node derives from the claim's
+  identity under a root only the node knows. Network filesystems join this union later as further
+  kinds, with their credentials delivered as secrets and never inside a claim;
+- `initialization`: `empty` creates an empty root with `initialOwnership { uid, gid, mode }`, which
+  an `empty` claim must state, so a workload without `runAs` never meets a root-owned directory by
+  accident; `import` waits for the volume's bytes to be imported and states `initialOwnership: null`,
+  because an imported tree keeps its own ownership. `mode` holds directory permission bits only
+  (`runtimeLocalStorageClaimContract.directoryModeBits`, `0o3777`; setuid is refused);
+- `mount { mountPath, readOnly }`, judged by the storage request's own mount path rule: canonical,
+  absolute, not `/`, and never overlapping `/run/secrets`;
+- `accessMode: 'ReadWriteOnce'`, `reclaimPolicy: 'retain'`, and `lifecycle`: `bound` keeps the
+  volume, `purge` orders its bytes deleted and always follows a bound generation of the same claim.
+
+The claim carries no host path, device, mount option or credential.
+`snapshotRuntimeLocalStorageClaim` makes a detached exact-schema snapshot,
+`computeRuntimeLocalStorageClaimDigest` hashes it under `serve.zone/runtime-local-storage-claim`,
+`validateRuntimeLocalStorageClaim` verifies the stated digest, and
+`getRuntimeLocalStorageClaimReference` is the `{ id, generation, digest }` an assignment seals in
+`workload.storage`. `bindRuntimeLocalStorageClaimToAssignment(claim, assignment, expectedClusterId)`
+checks that reference and the exact controller, organization, node, runtime namespace, service and
+cluster; a `purge` claim binds to no assignment, because no workload may mount a volume being deleted.
+
+`requests.runtimesession.IReq_Controller_Pallet_ApplyRuntimeLocalStorageClaim`
+(`applyRuntimeLocalStorageClaim`) pushes one claim over the node's authenticated session:
+`{ session, claim }` → `{ status, state, claim }`. `status` is `accepted`, `replay` or `historical`;
+`state` is `ready`, `import-required`, `purged` or `uncertain` (a volume the node can vouch for
+neither way, which it neither mounts nor deletes until an operator decides); `claim` is the sent
+claim's reference. `bindApplyRuntimeLocalStorageClaimRequest(request, trustedSession)` requires the
+request's session to equal the node's current one and the claim to name its controller, cluster,
+node and runtime namespace. `bindApplyRuntimeLocalStorageClaimResponse(response, request)` binds the
+answer to the sent claim and, for `accepted` and `replay`, to a state the claim can be in: a bound
+claim is `ready`, `import-required` (an `import` claim only) or `uncertain`, a purge is `purged` or
+`uncertain`. A `historical` answer describes the newer generation the node holds.
+
 `platform.storagemigration` defines the provider-neutral cutover contract for a
 named object-storage binding. Corestore atomically owns and fences the source
 binding after validating a distinct, unfenced active-object snapshot. Onebox
@@ -2440,6 +2582,9 @@ credential is excluded.
 | `registerClusterIngress` | ingress → relay → Cloudly | `{ bearer, version, nodeId, capabilities?, protocol }` → `{ accepted: true, revision \| null, protocol }` |
 | `getClusterIngressRouteTable` | ingress → relay | `{ knownRevision \| null }` → `{ table \| null }` |
 | `getClusterTrafficStatistics` | Cloudly → relay → ingress | `{ fromDayUtc, toDayUtc, cursor?, limit }` → `{ statistics, nextCursor? }` |
+| `pushClusterIngressRouteTableChanged` | relay → ingress | `{ revision }` → `{}` |
+| `designateClusterIngress` | admin → Cloudly | `{ identity, designation }` → `{ designation, spec, replayed }` |
+| `getClusterIngressDesignation` | admin → Cloudly | `{ identity, clusterId }` → `{ designation \| null }` |
 
 `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
@@ -2465,6 +2610,45 @@ the body in the one server order `protocol.readProtocolOffer` states — the off
 before this shape check and before the bearer — so a relay refuses a peer it cannot serve without
 asking Cloudly, and an accepted registration carries the accepting side's own offer back.
 
+A refused registration is named. A protocol mismatch stays the `IProtocolRefusal` every hop already
+carries; every other refusal travels as `IClusterIngressRegistrationRefusal { code:
+'cluster-ingress-registration-refused', reason, retryAfterMs }` in `TypedResponseError.errorData`,
+forwarded by the relay untouched. `clusterIngressRegistrationRefusalReasons` lists the reasons in
+the order Cloudly judges them: `not-ready` (Cloudly cannot judge registrations yet), `registration-invalid`
+(the body fails `validateClusterIngressRegistration`), `relay-not-connected` (the forwarding relay is
+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
+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
+only, as `protocol.readProtocolRefusal` does. No refusal quotes the bearer.
+
+`pushClusterIngressRouteTableChanged` is the relay's hint that it holds a newer table. It carries the
+revision alone (`IClusterIngressRouteTableChange`, `validateClusterIngressRouteTableChange`) and
+nothing secret; the ingress answers it by pulling `getClusterIngressRouteTable` with the revision it
+already applied and ignores a hint that is not newer, so a lost or repeated hint costs nothing.
+
+`clusterIngressEnvironmentNames` spells the ingress workload's environment once for both sides:
+`SERVEZONE_CLUSTER_INGRESS_BEARER` (the registration bearer, delivered as a secret),
+`SERVEZONE_CLUSTER_RELAY_ORIGIN` (the exact `IClusterRelay.origin`) and `SERVEZONE_CLUSTER_NODE_ID`
+(the node the assignment runs on). Cloudly writes them; the ingress reads them.
+
+A cluster born on Pallet has no cutover scope, census or target set, so its ingress is designated by
+`IClusterIngressDesignation { id, generation, previous, clusterId, runtime, ingressServiceId,
+preparedSpecRevision, credential, actorId, acceptedAt, digest }` instead of the fleet-cutover
+designation. `runtime` is the cluster's `pallet` phase reference and `credential`
+(`IClusterIngressCredentialReference`) the public identity of the managed bearer, never its value.
+`snapshotClusterIngressDesignation`, `computeClusterIngressDesignationDigest` (domain
+`serve.zone/cluster-ingress-designation`) and `validateClusterIngressDesignation` judge it, and
+`snapshotClusterIngressDesignationRequest` the administrator's compare-and-swap intent
+(`IClusterIngressDesignationRequest { mutationId, clusterId, ingressServiceId, currentRuntime,
+expectedSpecRevision, expectedDesignation }`). **A cluster holds exactly one kind of designation**:
+Cloudly refuses to designate a cluster that holds a fleet-cutover ingress designation, and the
+reverse. Which nodes the ingress runs on is the ingress service's runtime spec placement.
+
 `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
@@ -2499,6 +2683,15 @@ from one that states a value, and nothing downstream defaults or infers one. Clo
 the node stated and resolves it into the route table; the relay never substitutes an address of
 its own.
 
+The same report carries the optional `hostAddresses`: every IPv4 address the node's host carries on
+interfaces the node does not manage itself, sorted as strings, unique, never empty when present, at
+most `runtimeNetworkProtectionContract.maximumHostAddresses` (32), each one admitted by
+`runtimeNodeUplinkAddress`. Workload bridges and the managed VPN interface are the node's own and
+are left out. Cloudly names a plan platform endpoint in that node's `hostPlatformEndpointIds` when
+the endpoint's address is one of them. A relay registration already tells Cloudly which host carries
+the relay listener and hub; `hostAddresses` is how a host without a relay, such as a node with a
+Corestore beside it on one machine, states the same. Absent states nothing and is never defaulted.
+
 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
@@ -3183,6 +3376,73 @@ recipient the relay enrolled with `beginSecretRecipientEnrollment` and
 `completeSecretRecipientEnrollment` — see [Corestore Runtime Credentials](#corestore-runtime-credentials).
 No credential travels in the cluster document, and none is read from the relay's environment.
 
+### Corestore Legacy Resource Adoption
+
+A Corestore root converted from a release before 32 still holds the databases and buckets
+`/resources/provision` created, one per service and capability, in its manifest. Corestore refuses a
+credential binding beside such a resource until an operator authorizes that exact binding to adopt
+it, offline, with a plan file; a fresh binding would otherwise start from an empty database or bucket
+while the data stays behind. These contracts carry that flow across Corestore, the relay, Cloudly and
+Coreflow, all exported from `data` and `platform`:
+
+1. **Inventory.** Corestore answers `GET /control/legacy-resources`
+   (`corestoreLegacyAdoptionContract.inventoryPath`, bearer-authenticated like every control path)
+   with `ICorestoreLegacyResourceInventory { services }`: every service, sorted by id, with one or
+   two `TCorestoreLegacyResource` entries, `database` before `objectstorage`. A database is named by
+   `databaseName`, a bucket by `bucketName` and `retention` (its `IObjectStorageRetentionIntent`, or
+   `null`). Each carries its `adoption`: `{ state: 'unadopted', blocker }` or
+   `{ state: 'authorized', bindingId }`. The blocker names what would stop the offline adoption,
+   `null` when nothing would: `not-adoptable` (an allocation-managed database, another provider, a
+   resource name that is not its database or bucket name, or a bucket name that is not a canonical S3
+   name), `ordinary-credentials-rotated` or `owned-by-binding`. An adoptable bucket must have a
+   canonical S3 name, because a binding request carries only such a name. A consumed adoption removes
+   the legacy entry, so it never appears.
+2. **Relay.** `getClusterCorestoreLegacyResources { nodeId }` asks the relay for one node's
+   inventory, answered as `TClusterCorestoreLegacyResourceInventory`: `reachable: true` with the
+   services, or `reachable: false` with `errorCode` `CORESTORE_ENDPOINT_UNKNOWN` or
+   `CORESTORE_UNREACHABLE` and no list. `getCorestoreLegacyResources { identity, clusterId, nodeId }`
+   is the administrator's read through Cloudly, with `inventorySha256`
+   (`computeClusterCorestoreLegacyResourceInventorySha256`, over the node id and the services, not
+   the read time; `null` for an unreachable node).
+3. **Adoption.** `adoptCorestoreLegacyResources { identity, clusterId, nodeId,
+   expectedInventorySha256, resources }` is the only path that creates a binding carrying a legacy
+   bucket name. `resources` is a sorted, unique `{ serviceId, capability }` selection
+   (`validateCorestoreLegacyResourceSelections`). Cloudly reads the inventory again, requires the
+   expected digest, and creates each adopting binding in one transaction: enabled, placed on `nodeId`,
+   with `corestoreLegacyAdoption { nodeId, resourceName, inventorySha256 }`, and for a bucket
+   `objectstorageBucketName` set to the legacy bucket and `objectstorageRetention.intent` set to the
+   legacy intent exactly, or absent when the legacy bucket has none.
+   `validatePlatformBindingCorestoreLegacyAdoption(binding, inventory, sha)` is that rule. A resource
+   whose adopting binding already exists is answered unchanged. `upsertPlatformBinding` keeps refusing
+   `objectstorageBucketName`, and refuses `corestoreLegacyAdoption` and `statusReason` as well. The
+   answer lists the bindings and the `plan`. Refusals travel as
+   `ICorestoreLegacyAdoptionErrorData { code, retryable }`: `legacy-inventory-unreachable` (the only
+   retryable one), `legacy-inventory-changed`, `legacy-resource-absent`, `legacy-resource-blocked`,
+   `legacy-resource-authorized-elsewhere`, `service-absent` and `binding-exists`.
+4. **Plan.** `ICorestoreLegacyResourceAdoptionPlanEntry` is exactly the
+   `{ serviceId, capability, bindingId }` object Corestore's `legacy-resource-adoption` migration
+   reads. `validateCorestoreLegacyResourceAdoptionPlan` applies that migration's rules: a non-empty
+   array of at most 4096 exact entries, canonical identifiers, no service capability or binding id
+   twice, any order. `createCorestoreLegacyResourceAdoptionPlan(bindings)` builds it from the adopting
+   bindings, sorted by service then capability. The plan restates no legacy name or retention intent:
+   Corestore holds those itself, and the binding request that later reaches it carries the bucket and
+   intent it compares.
+5. **Status.** Until the operator has run the migration, Corestore refuses the binding with a 409
+   whose body is `{ ok: false, error, code }`. `readCorestoreLegacyAdoptionRefusal(statusCode, body)`
+   reads `code` as a `TPlatformBindingStatusReason`, and Coreflow reports it through
+   `updatePlatformBindingStatus { statusReason }`; `validatePlatformBindingStatusReason` pairs each
+   reason with its one status (`getPlatformBindingStatusOfReason`):
+
+| `statusReason` | Status | Corestore refusal |
+| --- | --- | --- |
+| `legacy-adoption-pending` | `provisioning` | the service owns a legacy resource of this capability that no adoption authorizes |
+| `legacy-adoption-conflict` | `failed` | the adoption authorizes another binding id, or it was already consumed |
+| `legacy-adoption-mismatch` | `failed` | the legacy identity changed since authorization, its database tenant is absent, or the bucket or retention intent differs |
+
+`IPlatformBinding.statusReason` holds the reported reason; a status report without one clears it.
+While a binding of a service reports `legacy-adoption-pending`, the service's runtime status waits as
+`legacy-adoption-pending` instead of `bindings-pending`.
+
 ### Launcher Environment Delivery
 
 Launcher environment delivery uses stable `szsv-<base32-sha256>` Docker

package/ts/00_commitinfo_data.ts

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

package/ts/data/clusteringress.ts

@@ -1,7 +1,7 @@
 import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
 import { isUtcCalendarDay } from '../private/utccalendarday.js';
 import { validateProtocolOfferOn } from '../protocol.js';
-import { hasExactKeys } from '../private/dataproperties.js';
+import { hasExactKeys, readExactDataRecord } from '../private/dataproperties.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 
 /**
@@ -424,3 +424,138 @@ export const validateClusterIngressRegistration = (
   }
   return errors;
 };
+
+/**
+ * The environment variable names of the cluster ingress workload.
+ *
+ * Cloudly writes them into the ingress workload's assignment environment and the ingress reads
+ * them, so both sides spell each name once, here. `bearer` is the credential the ingress presents
+ * to `registerClusterIngress`; it is a secret and is delivered as one. `relayOrigin` is the exact
+ * `IClusterRelay.origin` of the cluster's relay, and `nodeId` is the node the assignment runs on,
+ * which the registration's `nodeId` repeats.
+ */
+export const clusterIngressEnvironmentNames = Object.freeze({
+  bearer: 'SERVEZONE_CLUSTER_INGRESS_BEARER',
+  relayOrigin: 'SERVEZONE_CLUSTER_RELAY_ORIGIN',
+  nodeId: 'SERVEZONE_CLUSTER_NODE_ID',
+} as const);
+
+/**
+ * Every reason Cloudly refuses a cluster ingress registration, in the order it judges them.
+ *
+ * A protocol mismatch is not among them: it is refused first, as the `IProtocolRefusal` every
+ * TypedRequest hop already carries, and a second name for it would be a second answer to one fact.
+ */
+export const clusterIngressRegistrationRefusalReasons = Object.freeze([
+  /** Cloudly cannot judge registrations yet: it is starting, stopping or missing its environment. */
+  'not-ready',
+  /** The body fails `validateClusterIngressRegistration`. */
+  'registration-invalid',
+  /** The relay that forwarded the registration is not the connection Cloudly elected for its cluster. */
+  'relay-not-connected',
+  /** The cluster holds no current ingress designation. */
+  'ingress-not-designated',
+  /** The named node is not one the designation lets the ingress run on. */
+  'node-mismatch',
+  /**
+   * No ready assignment of the designated ingress service runs on the named node under that node's
+   * current session, or the one that runs does not carry the designation's current credential.
+   */
+  'assignment-not-running',
+  /** The bearer is not the designation's current credential. */
+  'bearer-refused',
+  /** The designation, the assignment or the session changed while the registration was judged. */
+  'conflict',
+] as const);
+
+export type TClusterIngressRegistrationRefusalReason = typeof clusterIngressRegistrationRefusalReasons[number];
+
+export const clusterIngressRegistrationContract = Object.freeze({
+  refusalCode: 'cluster-ingress-registration-refused',
+  minimumRetryAfterMs: 1_000,
+  maximumRetryAfterMs: 300_000,
+} as const);
+
+/**
+ * The named refusal of `registerClusterIngress`, carried as `TypedResponseError.errorData` from
+ * Cloudly and forwarded by the relay untouched. `retryAfterMs` is how long the ingress waits before
+ * it registers again; it never quotes the bearer or anything derived from it.
+ */
+export interface IClusterIngressRegistrationRefusal {
+  code: 'cluster-ingress-registration-refused';
+  reason: TClusterIngressRegistrationRefusalReason;
+  retryAfterMs: number;
+}
+
+const isRetryAfterMs = (valueArg: unknown): valueArg is number => (
+  Number.isSafeInteger(valueArg)
+  && (valueArg as number) >= clusterIngressRegistrationContract.minimumRetryAfterMs
+  && (valueArg as number) <= clusterIngressRegistrationContract.maximumRetryAfterMs
+);
+
+/** Validates one registration refusal and names every reason it is refused. */
+export const validateClusterIngressRegistrationRefusal = (
+  valueArg: unknown,
+  pathArg = 'cluster ingress registration refusal',
+): string[] => {
+  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['code', 'reason', 'retryAfterMs'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (valueArg.code !== clusterIngressRegistrationContract.refusalCode) {
+    errors.push(`${pathArg} code must be ${clusterIngressRegistrationContract.refusalCode}`);
+  }
+  if (!(clusterIngressRegistrationRefusalReasons as readonly unknown[]).includes(valueArg.reason)) {
+    errors.push(`${pathArg} reason must be a cluster ingress registration refusal reason`);
+  }
+  if (!isRetryAfterMs(valueArg.retryAfterMs)) {
+    errors.push(`${pathArg} retryAfterMs must be an integer from `
+      + `${clusterIngressRegistrationContract.minimumRetryAfterMs} to `
+      + `${clusterIngressRegistrationContract.maximumRetryAfterMs}`);
+  }
+  return errors;
+};
+
+/**
+ * The refusal inside an error payload, or `null` when the value is not one.
+ *
+ * It reads a value that survived serialization, the way `protocol.readProtocolRefusal` does, so an
+ * ingress tells a named registration refusal apart from a protocol refusal and every other error.
+ */
+export const readClusterIngressRegistrationRefusal = (
+  valueArg: unknown,
+): IClusterIngressRegistrationRefusal | null => {
+  const refusal = readExactDataRecord(valueArg, ['code', 'reason', 'retryAfterMs']);
+  if (refusal === null || validateClusterIngressRegistrationRefusal(refusal).length > 0) {
+    return null;
+  }
+  return Object.freeze({
+    code: clusterIngressRegistrationContract.refusalCode,
+    reason: refusal.reason as TClusterIngressRegistrationRefusalReason,
+    retryAfterMs: refusal.retryAfterMs as number,
+  });
+};
+
+/**
+ * The relay's hint that it holds a newer route table.
+ *
+ * It carries the revision alone and no route, certificate or key, so it is safe to log; the
+ * ingress answers it by pulling `getClusterIngressRouteTable` with the revision it already applied,
+ * and ignores a hint whose revision is not greater than that one.
+ */
+export interface IClusterIngressRouteTableChange {
+  revision: number;
+}
+
+/** Validates one route-table change hint. */
+export const validateClusterIngressRouteTableChange = (
+  valueArg: unknown,
+  pathArg = 'cluster ingress route table change',
+): string[] => {
+  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['revision'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  return isCounter(valueArg.revision)
+    ? []
+    : [`${pathArg} revision must be a non-negative safe integer`];
+};

package/ts/data/clusteringressdesignation.ts

@@ -0,0 +1,141 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IClusterRuntimeReference } from './clusterruntime.js';
+import { snapshotClusterRuntimeReference } from './clusterruntime.js';
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import type { ISecretVersionReference } from './secret.js';
+import { captureNetwork, networkCounter, networkDigest, networkHash, networkId, networkRecord, networkReference,
+  networkRevision, requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * The ingress designation of a cluster born on Pallet.
+ *
+ * A cluster that never ran Swarm has no cutover scope, census or target set, so its ingress is
+ * designated by this record instead of `IFleetCutoverIngressDesignation`. A cluster holds exactly
+ * one kind of designation at a time: Cloudly refuses to designate a cluster that holds the other
+ * kind. Which nodes the ingress runs on is the ingress service's runtime spec placement; the
+ * designation names the service and the credential, and nothing else.
+ */
+
+/** Public identity of the active ingress credential generation; it contains no credential value. */
+export interface IClusterIngressCredentialReference {
+  credentialId: string;
+  generation: number;
+  secretVersion: ISecretVersionReference;
+}
+
+/**
+ * Cloudly's accepted designation of one service as a Pallet cluster's ingress. It grants no
+ * assignment, session or registration: the ingress still registers with the credential it names.
+ */
+export interface IClusterIngressDesignation {
+  id: string;
+  generation: number;
+  previous: IRuntimeAuthorityReference | null;
+  clusterId: string;
+  runtime: IClusterRuntimeReference & { phase: 'pallet' };
+  ingressServiceId: string;
+  /** The ingress service's runtime spec revision the designation was accepted against. */
+  preparedSpecRevision: number;
+  credential: IClusterIngressCredentialReference;
+  actorId: string;
+  acceptedAt: number;
+  digest: TSha256Digest;
+}
+
+/**
+ * Administrator intent to designate one service as the cluster's ingress. The caller supplies only
+ * compare-and-swap inputs; Cloudly owns credential generation and acceptance.
+ */
+export interface IClusterIngressDesignationRequest {
+  mutationId: string;
+  clusterId: string;
+  ingressServiceId: string;
+  currentRuntime: IClusterRuntimeReference & { phase: 'pallet' };
+  expectedSpecRevision: number;
+  /** Null for creation; the exact current designation for rotation or a change of service. */
+  expectedDesignation: IRuntimeAuthorityReference | null;
+}
+
+export const clusterIngressDesignationContract = Object.freeze({
+  digestDomain: 'serve.zone/cluster-ingress-designation',
+  error: 'Cluster ingress designation contract rejected.',
+} as const);
+
+const fail = (): never => { throw new Error(clusterIngressDesignationContract.error); };
+const safe = <T>(operationArg: () => T): T => { try { return operationArg(); } catch { return fail(); } };
+
+const palletRuntime = (valueArg: unknown, clusterIdArg: string): IClusterRuntimeReference & { phase: 'pallet' } => {
+  const runtime = snapshotClusterRuntimeReference(valueArg);
+  requireNetwork(runtime.id === clusterIdArg && runtime.phase === 'pallet');
+  return { id: runtime.id, phase: 'pallet', generation: runtime.generation };
+};
+
+const credentialOf = (valueArg: unknown): IClusterIngressCredentialReference => {
+  const value = networkRecord(valueArg, ['credentialId', 'generation', 'secretVersion']);
+  const secretVersion = networkRecord(value.secretVersion, ['secretId', 'secretVersionId']);
+  return {
+    credentialId: networkId(value.credentialId),
+    generation: networkCounter(value.generation),
+    secretVersion: {
+      secretId: networkId(secretVersion.secretId),
+      secretVersionId: networkId(secretVersion.secretVersionId),
+    },
+  };
+};
+
+/** Detached exact-schema snapshot of a designation request. */
+export const snapshotClusterIngressDesignationRequest = (
+  valueArg: unknown,
+): IClusterIngressDesignationRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['mutationId', 'clusterId', 'ingressServiceId',
+    'currentRuntime', 'expectedSpecRevision', 'expectedDesignation']);
+  const clusterId = networkId(value.clusterId);
+  return {
+    mutationId: networkId(value.mutationId),
+    clusterId,
+    ingressServiceId: networkId(value.ingressServiceId),
+    currentRuntime: palletRuntime(value.currentRuntime, clusterId),
+    expectedSpecRevision: networkCounter(value.expectedSpecRevision),
+    expectedDesignation: value.expectedDesignation === null ? null : networkReference(value.expectedDesignation),
+  };
+});
+
+/** Detached exact-schema snapshot. The digest is a separate check. */
+export const snapshotClusterIngressDesignation = (valueArg: unknown): IClusterIngressDesignation => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['id', 'generation', 'previous', 'clusterId', 'runtime',
+    'ingressServiceId', 'preparedSpecRevision', 'credential', 'actorId', 'acceptedAt', 'digest']);
+  const { id, generation, previous } = networkRevision(value);
+  const clusterId = networkId(value.clusterId);
+  return {
+    id,
+    generation,
+    previous,
+    clusterId,
+    runtime: palletRuntime(value.runtime, clusterId),
+    ingressServiceId: networkId(value.ingressServiceId),
+    preparedSpecRevision: networkCounter(value.preparedSpecRevision),
+    credential: credentialOf(value.credential),
+    actorId: networkId(value.actorId),
+    acceptedAt: networkCounter(value.acceptedAt),
+    digest: networkDigest(value.digest),
+  };
+});
+
+export const computeClusterIngressDesignationDigest = async (valueArg: unknown): Promise<TSha256Digest> => {
+  const designation = snapshotClusterIngressDesignation(valueArg);
+  try {
+    return await networkHash(clusterIngressDesignationContract.digestDomain, designation);
+  } catch {
+    return fail();
+  }
+};
+
+export const validateClusterIngressDesignation = async (valueArg: unknown): Promise<string[]> => {
+  try {
+    const designation = snapshotClusterIngressDesignation(valueArg);
+    return designation.digest === await computeClusterIngressDesignationDigest(designation)
+      ? [] : ['cluster ingress designation digest does not match'];
+  } catch {
+    return ['cluster ingress designation must use its exact canonical schema'];
+  }
+};