@serve.zone/interfaces 32.22.0 → 32.23.0

package/ts/data/servicevolumeinitialization.ts

@@ -0,0 +1,159 @@
+import type { IRuntimeLocalStorageOwnership } from './runtimelocalstorageclaim.js';
+import { runtimeLocalStorageClaimContract } from './runtimelocalstorageclaim.js';
+import type { IServiceRuntimeProfile } from './serviceruntime.js';
+import { hasExactKeys, isPlainRecord } from '../private/dataproperties.js';
+import { isRuntimeIdentityNumber } from '../private/runtimepolicy.js';
+
+/**
+ * Where an `import` volume's bytes come from.
+ *
+ * `docker-volume` is a Docker volume on the host the claim's node runs on, named exactly as Docker
+ * lists it; a Corestore-driver volume is named the same way. The operator copies its tree into the
+ * node's import directory; the node never reads this reference, and the local storage claim does
+ * not carry it.
+ */
+export type TServiceVolumeImportSource = { kind: 'docker-volume'; volumeName: string };
+
+/**
+ * The owner and permission bits an `empty` volume's root directory gets.
+ *
+ * `explicit` states the numeric owner. `run-as` takes the owner from the runtime spec's
+ * `profile.runAs` (user and group) when the claim is first issued; the mode is always stated,
+ * because no mode is right for every image.
+ */
+export type TServiceVolumeOwnership =
+  | { kind: 'explicit'; uid: number; gid: number; mode: number }
+  | { kind: 'run-as'; mode: number };
+
+/**
+ * How a service volume's node-local claim starts: `empty` creates a fresh root with the stated
+ * ownership, `import` waits for the bytes of an existing volume.
+ */
+export type TServiceVolumeInitialization =
+  | { kind: 'empty'; ownership: TServiceVolumeOwnership }
+  | { kind: 'import'; source: TServiceVolumeImportSource };
+
+/**
+ * What a volume's initialization derives for a local storage claim, or why it derives nothing.
+ *
+ * `volume-initialization-unknown` is a volume with no initialization: Cloudly never assumes
+ * `empty`, because an empty volume in front of a service whose data sits in a legacy volume would
+ * start that service without its data. `volume-ownership-unknown` is a `run-as` ownership while
+ * the runtime spec runs the image's own user (`runAs: null`), whose numeric identity Cloudly does
+ * not know.
+ */
+export type TServiceVolumeClaimInitialization =
+  | { status: 'derived'; initialization: 'empty'; initialOwnership: IRuntimeLocalStorageOwnership }
+  | { status: 'derived'; initialization: 'import'; initialOwnership: null }
+  | { status: 'refused'; reason: 'volume-initialization-unknown' | 'volume-ownership-unknown' };
+
+/**
+ * Why `setServiceVolumeInitialization` wrote nothing. `volume-not-found` names no declared volume
+ * at that mount path, `conflict` a stored initialization other than `expected`,
+ * `volume-initialization-invalid` a value this contract refuses, and
+ * `volume-initialization-bound` a change while a bound local storage claim of the volume exists:
+ * a claim keeps the initialization and ownership it was issued with for its whole life.
+ */
+export type TServiceVolumeInitializationRefusal =
+  | 'volume-not-found'
+  | 'conflict'
+  | 'volume-initialization-invalid'
+  | 'volume-initialization-bound';
+
+/** The named refusal of `setServiceVolumeInitialization`, sent as `TypedResponseError.errorData`. */
+export interface IServiceVolumeInitializationErrorData {
+  code: TServiceVolumeInitializationRefusal;
+  retryable: false;
+}
+
+export const serviceVolumeInitializationContract = Object.freeze({
+  /** Every permission bit an ownership may state, the local storage claim's own bound. */
+  directoryModeBits: runtimeLocalStorageClaimContract.directoryModeBits,
+  maximumDockerVolumeNameLength: 255,
+} as const);
+
+/** Docker's own volume name grammar, `[a-zA-Z0-9][a-zA-Z0-9_.-]`, which needs two characters. */
+const dockerVolumeNamePattern = /^[A-Za-z0-9][A-Za-z0-9_.-]+$/;
+
+const isDirectoryMode = (valueArg: unknown): valueArg is number => Number.isSafeInteger(valueArg)
+  && (valueArg as number) >= 0
+  && ((valueArg as number) & ~serviceVolumeInitializationContract.directoryModeBits) === 0;
+
+const validateOwnership = (valueArg: unknown, pathArg: string): string[] => {
+  if (!isPlainRecord(valueArg)) return [`${pathArg} must use its exact schema`];
+  if (valueArg.kind === 'explicit') {
+    if (!hasExactKeys(valueArg, ['kind', 'uid', 'gid', 'mode'])) return [`${pathArg} must use its exact schema`];
+    const errors: string[] = [];
+    if (!isRuntimeIdentityNumber(valueArg.uid) || !isRuntimeIdentityNumber(valueArg.gid)) {
+      errors.push(`${pathArg} uid and gid must be runtime identity numbers`);
+    }
+    if (!isDirectoryMode(valueArg.mode)) errors.push(`${pathArg} mode must hold directory permission bits only`);
+    return errors;
+  }
+  if (valueArg.kind === 'run-as') {
+    if (!hasExactKeys(valueArg, ['kind', 'mode'])) return [`${pathArg} must use its exact schema`];
+    return isDirectoryMode(valueArg.mode) ? [] : [`${pathArg} mode must hold directory permission bits only`];
+  }
+  return [`${pathArg} kind must be explicit or run-as`];
+};
+
+const validateImportSource = (valueArg: unknown, pathArg: string): string[] => {
+  if (!isPlainRecord(valueArg) || valueArg.kind !== 'docker-volume'
+    || !hasExactKeys(valueArg, ['kind', 'volumeName'])) {
+    return [`${pathArg} must be an exact docker-volume source`];
+  }
+  return typeof valueArg.volumeName === 'string'
+    && valueArg.volumeName.length <= serviceVolumeInitializationContract.maximumDockerVolumeNameLength
+    && dockerVolumeNamePattern.test(valueArg.volumeName)
+    ? []
+    : [`${pathArg} volumeName must be a Docker volume name`];
+};
+
+/** Validates one volume initialization and names every reason it is refused. */
+export const validateServiceVolumeInitialization = (
+  valueArg: unknown,
+  pathArg = 'service volume initialization',
+): string[] => {
+  if (!isPlainRecord(valueArg)) return [`${pathArg} must use its exact schema`];
+  if (valueArg.kind === 'empty') {
+    if (!hasExactKeys(valueArg, ['kind', 'ownership'])) return [`${pathArg} must use its exact schema`];
+    return validateOwnership(valueArg.ownership, `${pathArg} ownership`);
+  }
+  if (valueArg.kind === 'import') {
+    if (!hasExactKeys(valueArg, ['kind', 'source'])) return [`${pathArg} must use its exact schema`];
+    return validateImportSource(valueArg.source, `${pathArg} source`);
+  }
+  return [`${pathArg} kind must be empty or import`];
+};
+
+/**
+ * The claim fields a volume's initialization derives under a runtime spec's `runAs`.
+ *
+ * Absent initialization refuses as `volume-initialization-unknown`; a `run-as` ownership under
+ * `runAs: null` refuses as `volume-ownership-unknown`. Nothing is defaulted. The answer is for the
+ * first generation of a claim only: later generations carry that claim's own initialization and
+ * ownership, whatever `runAs` says by then. A malformed initialization or `runAs` throws.
+ */
+export const deriveServiceVolumeClaimInitialization = (
+  initializationArg: TServiceVolumeInitialization | undefined,
+  runAsArg: IServiceRuntimeProfile['runAs'],
+): TServiceVolumeClaimInitialization => {
+  if (initializationArg === undefined) return { status: 'refused', reason: 'volume-initialization-unknown' };
+  const errors = validateServiceVolumeInitialization(initializationArg);
+  if (errors.length > 0) throw new Error(errors[0]);
+  if (runAsArg !== null && !(isPlainRecord(runAsArg) && hasExactKeys(runAsArg, ['user', 'group'])
+    && isRuntimeIdentityNumber(runAsArg.user) && isRuntimeIdentityNumber(runAsArg.group))) {
+    throw new Error('runAs must be null or an exact user and group');
+  }
+  if (initializationArg.kind === 'import') {
+    return { status: 'derived', initialization: 'import', initialOwnership: null };
+  }
+  const ownership = initializationArg.ownership;
+  if (ownership.kind === 'explicit') {
+    return { status: 'derived', initialization: 'empty',
+      initialOwnership: { uid: ownership.uid, gid: ownership.gid, mode: ownership.mode } };
+  }
+  if (runAsArg === null) return { status: 'refused', reason: 'volume-ownership-unknown' };
+  return { status: 'derived', initialization: 'empty',
+    initialOwnership: { uid: runAsArg.user, gid: runAsArg.group, mode: ownership.mode } };
+};

package/ts/platform/types.ts

@@ -16,6 +16,60 @@ export type TPlatformCapability =
 export type TPlatformAccessMode = 'rpc' | 'binding' | 'sidecar' | 'internal';
 export type TPlatformBindingStatus = 'requested' | 'provisioning' | 'ready' | 'degraded' | 'failed' | 'disabled';
 export type TPlatformDesiredState = 'enabled' | 'disabled';
+
+export const platformBindingStatusReasons = [
+  'legacy-adoption-pending',
+  'legacy-adoption-conflict',
+  'legacy-adoption-mismatch',
+] as const;
+
+/**
+ * Why a binding holds the status it reports, where the status alone does not say.
+ *
+ * All three come from Corestore's refusal of a credential binding beside a legacy
+ * `/resources/provision` resource (`code` in its 409 body, read with
+ * `readCorestoreLegacyAdoptionRefusal`):
+ *
+ * - `legacy-adoption-pending` (status `provisioning`): the service owns a legacy resource of this
+ *   capability that no offline adoption authorizes yet. It clears when the operator runs
+ *   Corestore's adoption with the plan Cloudly produced.
+ * - `legacy-adoption-conflict` (status `failed`): the adoption authorizes another binding id, or
+ *   it was already consumed.
+ * - `legacy-adoption-mismatch` (status `failed`): the legacy resource is no longer the one the
+ *   adoption authorized, its database tenant is absent, or the binding's bucket or retention
+ *   intent differs from the legacy bucket's.
+ */
+export type TPlatformBindingStatusReason = typeof platformBindingStatusReasons[number];
+
+const platformBindingStatusOfReason: Readonly<Record<TPlatformBindingStatusReason, TPlatformBindingStatus>> =
+  Object.freeze({
+    'legacy-adoption-pending': 'provisioning',
+    'legacy-adoption-conflict': 'failed',
+    'legacy-adoption-mismatch': 'failed',
+  });
+
+/** The one status each reason is reported with. */
+export const getPlatformBindingStatusOfReason = (
+  reasonArg: TPlatformBindingStatusReason,
+): TPlatformBindingStatus => platformBindingStatusOfReason[reasonArg];
+
+/**
+ * Validates a reported status and its optional reason: a reason must be a member of the
+ * vocabulary and come with its one status. An absent reason is valid with every status.
+ */
+export const validatePlatformBindingStatusReason = (
+  statusArg: unknown,
+  reasonArg: unknown,
+  pathArg = 'platform binding statusReason',
+): string[] => {
+  if (reasonArg === undefined) return [];
+  if (!(platformBindingStatusReasons as readonly unknown[]).includes(reasonArg)) {
+    return [`${pathArg} must be a platform binding status reason`];
+  }
+  return platformBindingStatusOfReason[reasonArg as TPlatformBindingStatusReason] === statusArg
+    ? []
+    : [`${pathArg} ${reasonArg as string} requires status ${platformBindingStatusOfReason[reasonArg as TPlatformBindingStatusReason]}`];
+};
 export type TPlatformEndpointProtocol =
   | 'typedrequest'
   | 'http'
@@ -55,6 +109,23 @@ export interface IPlatformServiceEndpoint {
   port?: number;
 }
 
+/**
+ * The legacy Corestore resource an object-storage or database binding adopts.
+ *
+ * Server-managed: only `adoptCorestoreLegacyResources` writes it, in the same write that creates
+ * the binding, and Cloudly refuses it (and `objectstorageBucketName`) on `upsertPlatformBinding`.
+ * `nodeId` is the node whose Corestore holds the resource, so the binding is placed there and
+ * nowhere else; `resourceName` is the legacy database or bucket name; `inventorySha256` is the
+ * legacy inventory the adoption was checked against. An adopted bucket's
+ * `objectstorageBucketName` is the legacy bucket and its `objectstorageRetention.intent` the legacy
+ * intent exactly, or absent when the legacy bucket has none.
+ */
+export interface IPlatformBindingCorestoreLegacyAdoption {
+  nodeId: string;
+  resourceName: string;
+  inventorySha256: string;
+}
+
 export interface IPlatformBinding {
   id: string;
   serviceId: string;
@@ -69,6 +140,10 @@ export interface IPlatformBinding {
   objectstorageBucketName?: string;
   /** Capability-specific value-free immutable-retention intent and evidence. */
   objectstorageRetention?: IObjectStorageRetentionBinding;
+  /** Server-managed: the legacy Corestore resource this binding adopts. */
+  corestoreLegacyAdoption?: IPlatformBindingCorestoreLegacyAdoption;
+  /** Why the binding holds its status, as the responsible cluster reported it. */
+  statusReason?: TPlatformBindingStatusReason;
   createdAt?: number;
   updatedAt?: number;
 }

package/ts/requests/corestore.ts

@@ -1,5 +1,11 @@
 import * as plugins from '../plugins.js';
 import type { IIdentity } from '../data/user.js';
+import type {
+  ICorestoreLegacyResourceAdoptionPlanEntry,
+  ICorestoreLegacyResourceSelection,
+  TClusterCorestoreLegacyResourceInventory,
+} from '../data/corestorelegacyadoption.js';
+import type { IPlatformBinding } from '../platform/types.js';
 import { hasExactKeys } from '../private/dataproperties.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 
@@ -277,3 +283,76 @@ extends plugins.typedrequestInterfaces.implementsTR<
     inventory: ICorestoreNodeInventory;
   };
 }
+
+/**
+ * Cloudly asks the relay for one exact node's legacy Corestore resources.
+ *
+ * The relay reads Corestore's `corestoreLegacyAdoptionContract.inventoryPath` with the control
+ * token and answers `reachable: true` with its services, or `reachable: false` with the reason, never
+ * an empty list for a node it could not read.
+ */
+export interface IReq_Cloudly_Relay_GetClusterCorestoreLegacyResources
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Relay_GetClusterCorestoreLegacyResources
+> {
+  method: 'getClusterCorestoreLegacyResources';
+  request: {
+    nodeId: string;
+  };
+  response: {
+    inventory: TClusterCorestoreLegacyResourceInventory;
+  };
+}
+
+/**
+ * An administrator reads one node's legacy Corestore resources through its cluster's relay, with
+ * the digest an adoption is checked against (`null` for an unreachable node).
+ */
+export interface IReq_Any_Cloudly_GetCorestoreLegacyResources
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetCorestoreLegacyResources
+> {
+  method: 'getCorestoreLegacyResources';
+  request: {
+    identity: IIdentity;
+    clusterId: string;
+    nodeId: string;
+  };
+  response: {
+    inventory: TClusterCorestoreLegacyResourceInventory;
+    inventorySha256: string | null;
+  };
+}
+
+/**
+ * The only path that creates a binding carrying a legacy bucket name.
+ *
+ * Cloudly reads the node's legacy inventory again, requires `expectedInventorySha256`, and for
+ * each selected resource creates the adopting binding in one transaction: enabled, placed on
+ * `nodeId`, with `corestoreLegacyAdoption`, and for a bucket the legacy bucket name and retention
+ * intent (`validatePlatformBindingCorestoreLegacyAdoption`). A resource whose adopting binding
+ * already exists is answered unchanged. The response lists the adopting bindings and the plan
+ * (`createCorestoreLegacyResourceAdoptionPlan`) the operator hands to Corestore's offline
+ * `legacy-resource-adoption` migration. Refusals travel as `ICorestoreLegacyAdoptionErrorData`.
+ */
+export interface IReq_Any_Cloudly_AdoptCorestoreLegacyResources
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_AdoptCorestoreLegacyResources
+> {
+  method: 'adoptCorestoreLegacyResources';
+  request: {
+    identity: IIdentity;
+    clusterId: string;
+    nodeId: string;
+    expectedInventorySha256: string;
+    /** Sorted by service then capability (`validateCorestoreLegacyResourceSelections`). */
+    resources: ICorestoreLegacyResourceSelection[];
+  };
+  response: {
+    bindings: IPlatformBinding[];
+    plan: ICorestoreLegacyResourceAdoptionPlanEntry[];
+  };
+}

package/ts/requests/platform.ts

@@ -5,6 +5,7 @@ import type {
   IPlatformCapability,
   IPlatformProviderConfig,
   TPlatformBindingStatus,
+  TPlatformBindingStatusReason,
 } from '../platform/types.js';
 
 export interface IReq_Any_Cloudly_GetPlatformDesiredState
@@ -162,6 +163,11 @@ extends plugins.typedrequestInterfaces.implementsTR<
     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/ts/requests/service.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 { IServiceRessources } from '../data/docker.js';
@@ -390,6 +391,33 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * 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.
  *