@serve.zone/interfaces 32.33.0 → 32.35.0

package/ts/data/corestorelegacyadoption.ts

@@ -29,6 +29,12 @@ import { isClusterNodeId } from '../private/nodeidentifier.js';
  *    answers the plan (`ICorestoreLegacyResourceAdoptionPlanEntry[]`).
  * 3. The operator stops Corestore and runs its `legacy-resource-adoption` migration with that plan.
  *    Until then Corestore refuses the binding, which reports `legacy-adoption-pending`.
+ *
+ * A resource is adopted by a binding of the service that owns it, or, when the selection names a
+ * `successorServiceId`, by a binding of that successor: a fresh service of the same organization
+ * that replaces the legacy one and takes over its data. The successor's binding records the legacy
+ * owner as `corestoreLegacyAdoption.legacyServiceId`, and the plan entry carries the successor, so
+ * Corestore moves the resource from the legacy owner's manifest entry to the successor's binding.
  */
 
 export type TCorestoreLegacyCapability = 'database' | 'objectstorage';
@@ -100,21 +106,30 @@ export type TClusterCorestoreLegacyResourceInventory =
       errorCode: 'CORESTORE_ENDPOINT_UNKNOWN' | 'CORESTORE_UNREACHABLE';
     };
 
-/** One resource an administrator selects for adoption. */
+/**
+ * One resource an administrator selects for adoption: the legacy resource `serviceId` owns of
+ * `capability`. Without `successorServiceId` a binding of `serviceId` adopts it; with it, a binding of
+ * that other service does, which must be a greenfield service of the same organization.
+ */
 export interface ICorestoreLegacyResourceSelection {
   serviceId: string;
   capability: TCorestoreLegacyCapability;
+  /** The service whose binding adopts the resource, when it is not `serviceId`; never `serviceId`. */
+  successorServiceId?: string;
 }
 
 /**
  * One entry of Corestore's offline adoption plan, exactly the object its
- * `legacy-resource-adoption` migration reads: the service, the capability and the binding that may
- * adopt its legacy resource. The legacy identity is Corestore's own and is not restated here.
+ * `legacy-resource-adoption` migration reads: the service that owns the legacy resource, the
+ * capability, the binding that may adopt it and, when that binding belongs to another service, that
+ * successor service. The legacy identity is Corestore's own and is not restated here.
  */
 export interface ICorestoreLegacyResourceAdoptionPlanEntry {
   serviceId: string;
   capability: TCorestoreLegacyCapability;
   bindingId: string;
+  /** The service `bindingId` belongs to, when it is not `serviceId`; never `serviceId`. */
+  successorServiceId?: string;
 }
 
 /**
@@ -126,9 +141,17 @@ export interface ICorestoreLegacyResourceAdoptionPlanEntry {
  * - `legacy-resource-blocked`: a selected resource is unadopted with a blocker;
  * - `legacy-resource-authorized-elsewhere`: a selected resource is authorized for a binding Cloudly
  *   does not hold as that resource's adoption;
- * - `service-absent`: Cloudly has no such service;
- * - `binding-exists`: the service already has a binding of that capability that adopts nothing,
- *   or adopts another resource.
+ * - `legacy-resource-adopted-elsewhere`: Cloudly already holds a binding of another service as a
+ *   selected resource's adoption;
+ * - `service-absent`: Cloudly has no such service, legacy owner or successor;
+ * - `binding-exists`: the adopting service already has a binding of that capability that adopts
+ *   nothing, or adopts another resource;
+ * - `successor-organization-mismatch`: the successor belongs to another organization than the
+ *   legacy owner, or either names none;
+ * - `successor-not-greenfield`: the successor is not an immutable-deployment service (it deploys on
+ *   push, or does not require an immutable image);
+ * - `successor-owns-legacy-resource`: the successor owns a legacy resource of that capability
+ *   itself, which Corestore would keep beside the adopted one.
  */
 export type TCorestoreLegacyAdoptionRefusal =
   | 'legacy-inventory-unreachable'
@@ -136,8 +159,12 @@ export type TCorestoreLegacyAdoptionRefusal =
   | 'legacy-resource-absent'
   | 'legacy-resource-blocked'
   | 'legacy-resource-authorized-elsewhere'
+  | 'legacy-resource-adopted-elsewhere'
   | 'service-absent'
-  | 'binding-exists';
+  | 'binding-exists'
+  | 'successor-organization-mismatch'
+  | 'successor-not-greenfield'
+  | 'successor-owns-legacy-resource';
 
 /** The named refusal of `adoptCorestoreLegacyResources`, sent as `TypedResponseError.errorData`. */
 export interface ICorestoreLegacyAdoptionErrorData {
@@ -327,7 +354,29 @@ export const computeClusterCorestoreLegacyResourceInventorySha256 = async (
 const selectionKey = (entryArg: { serviceId: string; capability: string }): string =>
   `${entryArg.serviceId}\u0000${entryArg.capability}`;
 
-/** Validates an administrator's selection: 1..4096 exact entries, sorted by service then capability. */
+/** The service capability whose binding adopts the entry's resource: the successor's, or the owner's. */
+const adoptingKey = (entryArg: { serviceId: string; capability: string; successorServiceId?: string }): string =>
+  selectionKey({ serviceId: entryArg.successorServiceId ?? entryArg.serviceId, capability: entryArg.capability });
+
+/**
+ * Whether an entry has exactly `baseKeysArg`, and `successorServiceId` at most: `shape` when not,
+ * `successor` when its successor is not a canonical identifier other than its `serviceId`.
+ */
+const successorShape = (
+  entryArg: Record<string, unknown>,
+  baseKeysArg: readonly string[],
+): 'exact' | 'shape' | 'successor' => {
+  if (!hasExactKeys(entryArg, baseKeysArg, ['successorServiceId'])) return 'shape';
+  return !Object.keys(entryArg).includes('successorServiceId')
+    || (isIdentifier(entryArg.successorServiceId) && entryArg.successorServiceId !== entryArg.serviceId)
+    ? 'exact'
+    : 'successor';
+};
+
+/**
+ * Validates an administrator's selection: 1..4096 exact entries, sorted by service then capability,
+ * and no service capability adopting twice, whether as legacy owner or as successor.
+ */
 export const validateCorestoreLegacyResourceSelections = (
   valueArg: unknown,
   pathArg = 'corestore legacy resource selection',
@@ -338,24 +387,36 @@ export const validateCorestoreLegacyResourceSelections = (
   }
   const errors: string[] = [];
   let previous: string | undefined;
+  const adopting = new Set<string>();
   for (const [index, entry] of valueArg.entries()) {
-    if (!isPlainRecord(entry) || !hasExactKeys(entry, ['serviceId', 'capability'])
-      || !isIdentifier(entry.serviceId) || !isCapability(entry.capability)) {
+    const shape = isPlainRecord(entry) ? successorShape(entry, ['serviceId', 'capability']) : 'shape';
+    if (shape === 'shape' || !isIdentifier((entry as Record<string, unknown>).serviceId)
+      || !isCapability((entry as Record<string, unknown>).capability)) {
       errors.push(`${pathArg}[${index}] must be an exact { serviceId, capability }`);
       continue;
     }
-    const key = selectionKey(entry as unknown as ICorestoreLegacyResourceSelection);
+    if (shape === 'successor') {
+      errors.push(`${pathArg}[${index}] successorServiceId must name another service`);
+      continue;
+    }
+    const selection = entry as ICorestoreLegacyResourceSelection;
+    const key = selectionKey(selection);
     if (previous !== undefined && compareWireTokens(previous, key) >= 0) {
       errors.push(`${pathArg} must be sorted by serviceId then capability without repeats`);
     }
     previous = key;
+    if (adopting.has(adoptingKey(selection))) {
+      errors.push(`${pathArg}[${index}] adopts into a service capability another entry adopts into`);
+    }
+    adopting.add(adoptingKey(selection));
   }
   return errors;
 };
 
 /**
  * Validates an adoption plan by the rules Corestore's migration applies: a non-empty array of at
- * most 4096 exact `{ serviceId, capability, bindingId }` entries, canonical identifiers, and no
+ * most 4096 exact `{ serviceId, capability, bindingId }` entries, each with `successorServiceId`
+ * when it names another service, canonical identifiers, and no legacy service capability, adopting
  * service capability or binding id twice. Order is free.
  */
 export const validateCorestoreLegacyResourceAdoptionPlan = (
@@ -368,19 +429,30 @@ export const validateCorestoreLegacyResourceAdoptionPlan = (
   }
   const errors: string[] = [];
   const serviceCapabilities = new Set<string>();
+  const adoptingCapabilities = new Set<string>();
   const bindingIds = new Set<string>();
   for (const [index, entry] of valueArg.entries()) {
-    if (!isPlainRecord(entry) || !hasExactKeys(entry, ['serviceId', 'capability', 'bindingId'])
-      || !isIdentifier(entry.serviceId) || !isIdentifier(entry.bindingId) || !isCapability(entry.capability)) {
+    const shape = isPlainRecord(entry) ? successorShape(entry, ['serviceId', 'capability', 'bindingId']) : 'shape';
+    const record = entry as Record<string, unknown>;
+    if (shape === 'shape' || !isIdentifier(record.serviceId) || !isIdentifier(record.bindingId)
+      || !isCapability(record.capability)) {
       errors.push(`${pathArg} entry ${index} must be an exact { serviceId, capability, bindingId }`);
       continue;
     }
-    const serviceCapability = selectionKey(entry as unknown as ICorestoreLegacyResourceSelection);
-    if (serviceCapabilities.has(serviceCapability) || bindingIds.has(entry.bindingId as string)) {
+    if (shape === 'successor') {
+      errors.push(`${pathArg} entry ${index} successorServiceId must name another service`);
+      continue;
+    }
+    const planEntry = entry as ICorestoreLegacyResourceAdoptionPlanEntry;
+    const serviceCapability = selectionKey(planEntry);
+    const adoptingCapability = adoptingKey(planEntry);
+    if (serviceCapabilities.has(serviceCapability) || adoptingCapabilities.has(adoptingCapability)
+      || bindingIds.has(planEntry.bindingId)) {
       errors.push(`${pathArg} entry ${index} repeats a service capability or binding id`);
     }
     serviceCapabilities.add(serviceCapability);
-    bindingIds.add(entry.bindingId as string);
+    adoptingCapabilities.add(adoptingCapability);
+    bindingIds.add(planEntry.bindingId);
   }
   return errors;
 };
@@ -392,16 +464,27 @@ export interface ICorestoreLegacyAdoptionBindingView {
   capability: string;
   objectstorageBucketName?: string;
   objectstorageRetention?: { intent: IObjectStorageRetentionIntent };
-  corestoreLegacyAdoption?: { nodeId: string; resourceName: string; inventorySha256: string };
+  corestoreLegacyAdoption?: {
+    nodeId: string;
+    resourceName: string;
+    inventorySha256: string;
+    legacyServiceId?: string;
+  };
 }
 
+/** The service that owns the legacy resource a binding adopts: its `legacyServiceId`, else its own. */
+const legacyOwnerOf = (bindingArg: ICorestoreLegacyAdoptionBindingView): string =>
+  bindingArg.corestoreLegacyAdoption?.legacyServiceId ?? bindingArg.serviceId;
+
 /**
  * Content check of one adopting binding against the inventory it was adopted at, and the one rule
  * that lets a binding carry a legacy bucket name: the binding names this node, this inventory
- * digest and the legacy resource's name; the resource is unadopted without a blocker or authorized
- * for exactly this binding; an adopted bucket's `objectstorageBucketName` is the legacy bucket and
- * its retention intent the legacy intent exactly, absent when the legacy bucket has none; a
- * database binding carries neither. Whether the digest is current is the caller's to check.
+ * digest and the legacy resource's name; the resource belongs to `legacyServiceId` when the binding
+ * names one, and then its own service owns no legacy resource of the capability, otherwise to its
+ * own service; the resource is unadopted without a blocker or authorized for exactly this binding;
+ * an adopted bucket's `objectstorageBucketName` is the legacy bucket and its retention intent the
+ * legacy intent exactly, absent when the legacy bucket has none; a database binding carries
+ * neither. Whether the digest is current is the caller's to check.
  */
 export const validatePlatformBindingCorestoreLegacyAdoption = (
   bindingArg: ICorestoreLegacyAdoptionBindingView,
@@ -414,16 +497,27 @@ export const validatePlatformBindingCorestoreLegacyAdoption = (
     return [`${pathArg} needs a valid reachable inventory and its digest`];
   }
   const adoption = bindingArg.corestoreLegacyAdoption;
-  if (!isPlainRecord(adoption) || !hasExactKeys(adoption, ['nodeId', 'resourceName', 'inventorySha256'])) {
+  if (!isPlainRecord(adoption)
+    || !hasExactKeys(adoption, ['nodeId', 'resourceName', 'inventorySha256'], ['legacyServiceId'])) {
     return [`${pathArg} must use its exact schema`];
   }
+  if (Object.keys(adoption).includes('legacyServiceId')
+    && (!isIdentifier(adoption.legacyServiceId) || adoption.legacyServiceId === bindingArg.serviceId)) {
+    return [`${pathArg} legacyServiceId must name another service than the binding's`];
+  }
   if (adoption.nodeId !== inventoryArg.nodeId || adoption.inventorySha256 !== inventorySha256Arg) {
     return [`${pathArg} must name the inventory's node and digest`];
   }
   if (!isCapability(bindingArg.capability)) return [`${pathArg} needs a database or objectstorage binding`];
-  const resource = inventoryArg.services.find((serviceArg) => serviceArg.serviceId === bindingArg.serviceId)
+  const resourceOf = (serviceIdArg: string) => inventoryArg.services
+    .find((serviceArg) => serviceArg.serviceId === serviceIdArg)
     ?.resources.find((resourceArg) => resourceArg.capability === bindingArg.capability);
+  const legacyOwner = legacyOwnerOf(bindingArg);
+  const resource = resourceOf(legacyOwner);
   if (!resource) return [`${pathArg} names no legacy resource of the service and capability`];
+  if (legacyOwner !== bindingArg.serviceId && resourceOf(bindingArg.serviceId)) {
+    return [`${pathArg} names a successor that owns a legacy resource of the capability itself`];
+  }
   const errors: string[] = [];
   const legacyName = resource.capability === 'database' ? resource.databaseName : resource.bucketName;
   if (adoption.resourceName !== legacyName) errors.push(`${pathArg} resourceName must be the legacy resource's name`);
@@ -447,18 +541,27 @@ export const validatePlatformBindingCorestoreLegacyAdoption = (
 };
 
 /**
- * The plan for every adopting binding, sorted by service then capability, in the exact entry shape
- * Corestore's migration reads. Throws unless every binding adopts a legacy resource and the result
- * is a valid plan.
+ * The plan for every adopting binding, sorted by legacy service then capability, in the exact entry
+ * shape Corestore's migration reads: a binding adopting another service's resource names that
+ * service as `serviceId` and its own as `successorServiceId`. Throws unless every binding adopts a
+ * legacy resource and the result is a valid plan.
  */
 export const createCorestoreLegacyResourceAdoptionPlan = (
   bindingsArg: readonly ICorestoreLegacyAdoptionBindingView[],
 ): ICorestoreLegacyResourceAdoptionPlanEntry[] => {
-  const plan = bindingsArg.map((bindingArg) => {
+  const plan = bindingsArg.map((bindingArg): ICorestoreLegacyResourceAdoptionPlanEntry => {
     if (bindingArg.corestoreLegacyAdoption === undefined || !isCapability(bindingArg.capability)) {
       throw new Error(`binding ${bindingArg.id} adopts no legacy Corestore resource`);
     }
-    return { serviceId: bindingArg.serviceId, capability: bindingArg.capability, bindingId: bindingArg.id };
+    const legacyServiceId = bindingArg.corestoreLegacyAdoption.legacyServiceId;
+    return legacyServiceId === undefined
+      ? { serviceId: bindingArg.serviceId, capability: bindingArg.capability, bindingId: bindingArg.id }
+      : {
+          serviceId: legacyServiceId,
+          capability: bindingArg.capability,
+          bindingId: bindingArg.id,
+          successorServiceId: bindingArg.serviceId,
+        };
   }).sort((leftArg, rightArg) => compareWireTokens(selectionKey(leftArg), selectionKey(rightArg)));
   const errors = validateCorestoreLegacyResourceAdoptionPlan(plan);
   if (errors.length > 0) throw new Error(errors[0]);

package/ts/data/networknode.ts

@@ -4,13 +4,20 @@ import { captureNetwork, networkCounter, networkNodeId, networkRecord, networkSa
 type TEgressOwner = IRuntimeNetworkProtectedAuthority['egressAuthorities'][number];
 
 /**
- * One unmet condition of a node's runtime network readiness, in the order the node producer meets
- * them: the node joins the protected authority's egress, every egress owner reports current
- * protection, a handoff is reserved, the router selection carries it, the node's acknowledged
- * projection carries it, and the node is a managed VPN member. `protection-receipts-pending` names
- * the egress owners whose current receipts are still missing.
+ * One unmet condition of a node's runtime network readiness. The first is liveness: the node is
+ * observed running. The rest follow the order the node producer meets them: the node joins the
+ * protected authority's egress, every egress owner reports current protection, a handoff is
+ * reserved, the router selection carries it, the node's acknowledged projection carries it, and the
+ * node is a managed VPN member. `protection-receipts-pending` names the egress owners whose current
+ * receipts are still missing.
  */
 export type TRuntimeNetworkNodeReadinessGap =
+  /**
+   * No accepted report newer than `clusterNodeObservationFreshnessMs` shows the node running.
+   * `lastObservedAt` is when Cloudly accepted the node's last report, or `null` when the node's
+   * status is not `online`, so no report shows it running.
+   */
+  | { condition: 'node-observation-stale'; lastObservedAt: number | null }
   | { condition: 'egress-pending' | 'handoff-pending' | 'selection-pending' | 'projection-pending' | 'vpn-member-pending' }
   | { condition: 'protection-receipts-pending'; owners: [TEgressOwner, ...TEgressOwner[]] };
 

package/ts/platform/types.ts

@@ -116,14 +116,18 @@ export interface IPlatformServiceEndpoint {
  * 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.
+ * legacy inventory the adoption was checked against; `legacyServiceId` is the service that owned the
+ * legacy resource when that is not the binding's own service (a successor adopting its
+ * predecessor's data), absent otherwise. 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;
+  /** The legacy resource's owner, when it is another service than the binding's; never its own. */
+  legacyServiceId?: string;
 }
 
 export interface IPlatformBinding {

package/ts/requests/corestore.ts

@@ -332,8 +332,12 @@ extends plugins.typedrequestInterfaces.implementsTR<
  * 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
+ * intent (`validatePlatformBindingCorestoreLegacyAdoption`). A selection naming a
+ * `successorServiceId` creates the binding on that successor instead, with
+ * `corestoreLegacyAdoption.legacyServiceId` naming the legacy owner; the successor must exist, share
+ * the legacy owner's organization, be an immutable-deployment service, own no legacy resource of
+ * that capability and hold no other binding of it. A legacy resource is adopted by one service
+ * only. 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`.
  */