@serve.zone/interfaces 32.22.0 → 32.24.0

package/readme.md

@@ -1418,17 +1418,22 @@ phase, settlement, release or authority booleans or evidence.
 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`, `failure-backoff`, `storage-import-pending` (an `import` local storage claim whose bytes
-have not arrived on its node) or `bindings-pending` (the secret manifest does not cover every enabled
-binding of the service yet). `refused` carries a `TServiceRuntimeRefusal`:
+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`, `network-workload-pool-exhausted`, `volume-driver-unsupported`,
-`volume-options-unsupported`, `volume-shared-unsupported` or `volume-placement-unsupported`. The 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. `ports-too-many` is a service declaring more target ports than the
+`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
@@ -1440,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
@@ -1933,25 +1984,64 @@ 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;
+`data.IRuntimeLocalStorageClaim` is a controller's authority for one retained volume of one service,
+mounted on one node. 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` (`TRuntimeLocalStorageSource`), one of:
+  - `{ kind: 'directory' }` (`TRuntimeLocalStorageDirectorySource`), a node-local directory the node
+    derives from the claim's identity under a root only the node knows;
+  - `{ kind: 'nfs', server, export, subPath, version }` (`TRuntimeLocalStorageNfsSource`), the
+    directory `subPath` below the NFS export `server:export`;
+  - `{ kind: 'smb', server, share, subPath, version, credential }` (`TRuntimeLocalStorageSmbSource`),
+    the directory `subPath` below the SMB share `//server/share`. `credential` is an
+    `IRuntimeAuthorityReference { id, generation, digest }` naming the credential the node
+    authenticates with; the claim never carries a user name, password or domain, and the node
+    resolves the material through the controller's secret delivery. NFS authenticates the node's
+    host, so an `nfs` source names no credential;
 - `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);
+  (`runtimeLocalStorageClaimContract.directoryModeBits`, `0o3777`; setuid is refused). SMB carries no
+  POSIX ownership, so the node presents an SMB volume with `initialOwnership`, and an `smb` claim is
+  always `empty`;
 - `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.
+A network source names the remote directory and nothing about how to mount it, so the node derives
+every mount parameter from these fields alone and a claim cannot smuggle an option in:
+
+| Field | Rule |
+| --- | --- |
+| `server` | a lowercase fully qualified hostname of two or more labels whose last label is not numeric (a single label would resolve through each node's own search domains), or a canonical IP literal (a dotted quad without leading zeros, or RFC 5952 IPv6 without brackets or zone). No scheme, user info or port: the node connects to the protocol's standard port |
+| `export` | `/`, or `/` and canonical segments without a trailing slash |
+| `subPath` | `.` for the export or share itself, or canonical relative segments |
+| `share` | one segment of at most 80 characters, without `+`, `;`, `[` or `]` |
+| `version` | `nfs`: `3`, `4.0`, `4.1` or `4.2`; `smb`: `3.0`, `3.02` or `3.1.1` |
+
+A segment is printable ASCII without a space, at most 255 characters, never `.` or `..`, and holds
+none of `"`, `*`, `,`, `/`, `:`, `<`, `=`, `>`, `?`, `\` or `|`: a comma or `=` would read as a mount
+option, and the rest have meaning in a mount source or an SMB name. `export` and `subPath` are at
+most 1024 characters. ASCII keeps one spelling per segment, but one remote directory can still be
+named several ways: a hostname and an address of the same server, a different `export`/`subPath`
+split, or a nested `subPath`. The contract cannot detect these aliases, so the controller must refuse
+overlapping bound claims itself. The versions are the kernel's own `vers=` spellings, and each pins one protocol version: a
+bare NFS `4` or SMB `3` negotiates one, which a claim that must mean the same mount on every node
+cannot allow. NFS version 2 and the SMB 1 and 2 dialects are refused; SMB 3 is the first dialect
+that encrypts. The bounds and version lists
+are `runtimeLocalStorageClaimContract.nfsVersions`, `smbVersions`, `maximumServerLength`,
+`maximumPathLength`, `maximumSegmentLength` and `maximumShareLength`.
+
+`ReadWriteOnce` holds on the node that mounts the claim. A network directory is reachable from more
+than one node, so the controller issues at most one bound claim per remote directory; a node cannot
+see another node's mounts. A `purge` of a network claim deletes everything below `subPath`, the
+whole export or share for `.`.
+
+The claim carries no host path, device, mount option or credential value.
 `snapshotRuntimeLocalStorageClaim` makes a detached exact-schema snapshot,
 `computeRuntimeLocalStorageClaimDigest` hashes it under `serve.zone/runtime-local-storage-claim`,
 `validateRuntimeLocalStorageClaim` verifies the stated digest, and
@@ -2632,6 +2722,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
@@ -3316,6 +3415,77 @@ 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`, `owned-by-binding` or `fence-lineage-conflict` (the
+   bucket's object-storage fence lineage cannot move to the adopting binding: the bucket has more than
+   one lineage, or its lineage does not validate, belongs to another authority or has an unfinished
+   mutation).
+   Only a bucket has a fence lineage, so a database never names `fence-lineage-conflict`. 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.22.0',
+  version: '32.24.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }