@serve.zone/interfaces 32.22.0 → 32.23.0

package/dist_ts/requests/platform.d.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../plugins.js';
 import type { IIdentity } from '../data/user.js';
-import type { IPlatformBinding, IPlatformCapability, IPlatformProviderConfig, TPlatformBindingStatus } from '../platform/types.js';
+import type { IPlatformBinding, IPlatformCapability, IPlatformProviderConfig, TPlatformBindingStatus, TPlatformBindingStatusReason } from '../platform/types.js';
 export interface IReq_Any_Cloudly_GetPlatformDesiredState extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetPlatformDesiredState> {
     method: 'getPlatformDesiredState';
     request: {
@@ -111,6 +111,11 @@ export interface IReq_Any_Cloudly_UpdatePlatformBindingStatus extends plugins.ty
         endpoints?: IPlatformBinding['endpoints'];
         /** Reports the exact provider-returned bucket for an objectstorage binding. */
         objectstorageBucketName?: IPlatformBinding['objectstorageBucketName'];
+        /**
+         * Why the binding holds `status`; `validatePlatformBindingStatusReason` pairs each reason with
+         * its one status. Absent clears a stored reason.
+         */
+        statusReason?: TPlatformBindingStatusReason;
         errorText?: string;
     };
     response: {

package/dist_ts/requests/service.d.ts

@@ -2,6 +2,7 @@ import * as plugins from '../plugins.js';
 import type { IService } from '../data/service.js';
 import type { TServiceUpdateWritableData, TServiceWritableData } from '../data/service.js';
 import type { IServicePlacement } from '../data/service.js';
+import type { TServiceVolumeInitialization } from '../data/servicevolumeinitialization.js';
 import type { IRegistryTarget } from '../data/registry.js';
 import type { IIdentity, IIdentityCredential } from '../data/user.js';
 import type { IImageRelease } from '../data/immutableimage.js';
@@ -267,6 +268,28 @@ export interface IRequest_Any_Cloudly_DeleteServiceById extends plugins.typedreq
         success: boolean;
     };
 }
+/**
+ * Sets how one declared volume's node-local storage claim starts, the only write of
+ * `IServiceVolume.initialization`.
+ *
+ * The volume is named by its exact declared `mountPath`. `expected` is the initialization the
+ * caller read, or `null` when the volume has none; any other stored value refuses as `conflict`.
+ * While a bound local storage claim of the volume exists, a different initialization refuses as
+ * `volume-initialization-bound`. Refusals travel as `IServiceVolumeInitializationErrorData`.
+ */
+export interface IRequest_Any_Cloudly_SetServiceVolumeInitialization extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_SetServiceVolumeInitialization> {
+    method: 'setServiceVolumeInitialization';
+    request: {
+        identity: IIdentity;
+        serviceId: string;
+        mountPath: string;
+        expected: TServiceVolumeInitialization | null;
+        initialization: TServiceVolumeInitialization;
+    };
+    response: {
+        service: IService;
+    };
+}
 /**
  * Writes the complete runtime spec of one service.
  *

package/package.json

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

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
@@ -2632,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
@@ -3316,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.22.0',
+  version: '32.23.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }