@serve.zone/interfaces 31.8.0 → 32.0.0

package/ts/00_commitinfo_data.ts

@@ -2,7 +2,7 @@
  * autocreated commitinfo by @push.rocks/commitinfo
  */
 export const commitinfo = {
-  name: '@serve.zone/interfaces',
-  version: '31.8.0',
-  description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
+  name: "@serve.zone/interfaces",
+  version: "32.0.0",
+  description: "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem."
 }

package/ts/appstore/types.ts

@@ -57,10 +57,10 @@ export type TAppStoreTrackingMode = 'tag' | 'digest';
 export type TAppStoreUpgradeStrategy = 'semver' | 'branch' | 'dockerDigest';
 
 export const appStoreStorageFeatureIds = {
-  bindingsV2: 'storage.bindings.v2',
-  filesystemV1: 'storage.filesystem.v1',
-  objectStorageV2: 'storage.object-storage.v2',
-  objectStorageFileV2: 'storage.object-storage.file.v2',
+  bindings: 'storage.bindings',
+  filesystem: 'storage.filesystem',
+  objectStorage: 'storage.object-storage',
+  objectStorageFile: 'storage.object-storage.file',
 } as const;
 
 export type TAppStoreStorageFeatureId =
@@ -333,7 +333,6 @@ export interface IAppStoreApp {
 }
 
 export interface IAppStoreIndex {
-  schemaVersion: number;
   updatedAt: string;
   resolvedAt?: string;
   apps: IAppStoreApp[];
@@ -423,7 +422,6 @@ export interface IServezoneAppStoreVersion extends IAppStoreVersionConfig {
 }
 
 export interface IServezoneAppStoreManifest {
-  schemaVersion: number;
   app: IServezoneAppStoreAppInfo;
   latestVersion?: string;
   channel?: string;

package/ts/data/backup.ts

@@ -56,7 +56,6 @@ export interface IBackupArchiveObject {
 }
 
 export interface IBackupArchiveManifest {
-  version: 1;
   backupId: string;
   createdAt: number;
   objects: IBackupArchiveObject[];
@@ -362,43 +361,6 @@ export interface IIsolatedRestoreSourceBackupHold {
   releaseReason?: string;
 }
 
-export type TIsolatedRestoreNodeStatus =
-  | 'preparing'
-  | 'prepared'
-  | 'staging'
-  | 'restoring'
-  | 'verifying'
-  | 'ready'
-  | 'failed'
-  | 'cleaning'
-  | 'cleaned'
-  | 'cleanup-failed';
-
-/**
- * Data-plane state for one exact cluster/node/restore routing key. `revision`
- * advances after every mutation and is the compare-and-swap value used by
- * prepare, execute, and cleanup requests.
- */
-export interface IIsolatedRestoreNodeState {
-  restoreId: string;
-  clusterId: string;
-  targetNodeName: string;
-  sourceBackupId: string;
-  sourceServiceId: string;
-  scratchNamespaceId: string;
-  stagingArchiveId: string;
-  revision: number;
-  status: TIsolatedRestoreNodeStatus;
-  completedResourceMappingIds: string[];
-  verification: IIsolatedRestoreVerification;
-  cleanup?: IIsolatedRestoreCleanupProgress;
-  preparedAt?: number;
-  readyAt?: number;
-  updatedAt: number;
-  lastErrorCode?: string;
-  lastErrorMessage?: string;
-}
-
 /**
  * Durable control-plane record for a restore into a generated data-plane
  * scratch namespace. The namespace is not an IService and carries no image,
@@ -423,6 +385,9 @@ export interface IIsolatedRestoreRecord {
   scratchNamespaceId: string;
   /** Server-generated archive namespace, distinct from sourceBackupId. */
   stagingArchiveId: string;
+  /** The cluster node every control call is dispatched to, as the cluster document names it. */
+  targetNodeId: string;
+  /** The node name the signed restore grant authorizes, read from that node's cluster document. */
   targetNodeName: string;
   purpose: string;
   requestedBy: IIsolatedRestoreActor;

package/ts/data/cluster.ts

@@ -3,6 +3,8 @@ import * as plugins from '../plugins.js';
 import { type IDockerRegistryInfo } from '../data/docker.js';
 import type { IClusterNode } from './clusternode.js';
 import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
+import { validateProtocolOfferOn, type IProtocolOffer } from '../protocol.js';
+import { hasExactKeys } from '../private/dataproperties.js';
 
 export interface ICluster {
   id: string;
@@ -43,7 +45,7 @@ export interface ICluster {
      * How cluster-side components reach this cluster's relay. Absent on a
      * cluster whose nodes still target Cloudly directly.
      */
-    relay?: IClusterRelayV1;
+    relay?: IClusterRelay;
   };
 }
 
@@ -56,15 +58,14 @@ export interface ICluster {
  * `new URL(origin).origin === origin`. A default `:443` is therefore written
  * implicitly, because `URL` drops it from the origin it computes.
  */
-export interface IClusterRelayV1 {
-  schemaVersion: 1;
+export interface IClusterRelay {
   origin: string;
 }
 
 /**
  * What a cluster relay tells Cloudly about itself once its socket is authenticated.
  *
- * The relay sends this after `registerCloudlyClientSessionV1`, so the cluster it registers for
+ * The relay sends this after `registerCloudlyClientSession`, so the cluster it registers for
  * is the one its verified machine identity names and is never a field here. `relay.nodeId` is
  * the cluster node the relay process runs on, `listenAddress` and `listenPort` are the exact
  * endpoint it bound for the Pallet nodes of its cluster, and `registrationSequence` counts up
@@ -72,8 +73,7 @@ export interface IClusterRelayV1 {
  * peer, where it must strictly increase, a refused registration does not consume it, and a
  * repeat of an accepted sequence is refused; across peers Cloudly's own acceptance time orders.
  */
-export interface IClusterRelayRegistrationV1 {
-  schemaVersion: 1;
+export interface IRegisterClusterRelayRequest {
   relay: {
     /** The relay build that is registering; a bounded label for operators and logs. */
     version: string;
@@ -91,6 +91,12 @@ export interface IClusterRelayRegistrationV1 {
   };
   /** Monotonic within one relay process; it restarts at 0 when the process restarts. */
   registrationSequence: number;
+  /**
+   * Read and negotiated before the registration is validated; see
+   * `validateRegisterClusterRelayRequest`. `relay.version` is the relay build and stays a
+   * different fact from `protocol.interfacesVersion`, which is the contract it speaks.
+   */
+  protocol: IProtocolOffer;
 }
 
 /**
@@ -101,11 +107,34 @@ export interface IClusterRelayRegistrationV1 {
  * registration always carries one: a cluster whose relay nobody enabled has no origin to
  * register into, and that registration is refused by name instead of answered.
  */
-export interface IClusterRelayRegistrationResponseV1 {
+export interface IRegisterClusterRelayResponse {
   accepted: true;
   origin: string;
+  /** Cloudly's own offer, so an accepted relay judges the session it just registered into. */
+  protocol: IProtocolOffer;
 }
 
+/**
+ * The registration refusals that end a relay's custody of its cluster.
+ *
+ * Each of them is Cloudly reading its own records and stating that this relay is not the one it
+ * dispatches to, so the answer outlives the socket it arrived on and a relay that hears one drops
+ * what it holds for its nodes instead of waiting. Cloudly's other answers — a refusal that only
+ * says it could not verify the relay, a malformed or conflicting registration, an internal error —
+ * state nothing about dispatch and are not listed here.
+ */
+export const clusterRelayUndispatchedRefusals = Object.freeze([
+  /** The cluster has no relay enabled, so there is no registration to accept. */
+  'relay-cluster-not-enabled',
+  /** The node the relay names belongs to another cluster than the one its identity names. */
+  'relay-node-foreign',
+  /** A registration of this relay identity at the same or a higher sequence is already recorded. */
+  'relay-sequence-not-advancing',
+] as const);
+
+/** One of the reasons Cloudly states that it does not dispatch to a relay. */
+export type TClusterRelayUndispatchedRefusal = typeof clusterRelayUndispatchedRefusals[number];
+
 const maximumClusterRelayOriginLength = 2048;
 const maximumClusterRelayVersionLength = 64;
 
@@ -117,16 +146,6 @@ const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
     || Object.getPrototypeOf(valueArg) === null)
 );
 
-const hasExactKeys = (
-  valueArg: Record<string, unknown>,
-  keysArg: readonly string[],
-): boolean => {
-  const actualKeys = Object.keys(valueArg).sort();
-  const expectedKeys = [...keysArg].sort();
-  return actualKeys.length === expectedKeys.length
-    && actualKeys.every((keyArg, indexArg) => keyArg === expectedKeys[indexArg]);
-};
-
 const validateClusterRelayOrigin = (valueArg: unknown, pathArg: string): string[] => {
   if (typeof valueArg !== 'string'
     || valueArg.length === 0
@@ -162,19 +181,14 @@ const validateClusterRelayOrigin = (valueArg: unknown, pathArg: string): string[
  * identity store: it is the transport authority the node's runtime session
  * registers over.
  */
-export const validateClusterRelayV1 = (
+export const validateClusterRelay = (
   valueArg: unknown,
   pathArg = 'cluster relay',
 ): string[] => {
-  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['schemaVersion', 'origin'])) {
+  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['origin'])) {
     return [`${pathArg} must use its exact schema`];
   }
-  const errors: string[] = [];
-  if (valueArg.schemaVersion !== 1) {
-    errors.push(`${pathArg} schemaVersion must be 1`);
-  }
-  errors.push(...validateClusterRelayOrigin(valueArg.origin, `${pathArg} origin`));
-  return errors;
+  return validateClusterRelayOrigin(valueArg.origin, `${pathArg} origin`);
 };
 
 const validateClusterRelayVersion = (valueArg: unknown, pathArg: string): string[] => (
@@ -242,19 +256,22 @@ const validateClusterRelayEndpoint = (valueArg: unknown, pathArg: string): strin
  * stored one is Cloudly's decision too. `registrationSequence` restarts with the relay process,
  * so it orders registrations only within one live peer. A registration that passes here has
  * claimed nothing.
+ *
+ * Cloudly judges the body in the one server order `protocol.readProtocolOffer` states, against its
+ * `clusterRelay` offer, and reaches this check only afterwards — so a refused relay never consumes
+ * a sequence. The `validateProtocolOfferOn` call below is therefore the self-consistency check of
+ * a body that was already negotiated, never the negotiation step; it reads the offer the same way,
+ * as data, so naming reasons never runs an accessor a peer put on the body.
  */
-export const validateClusterRelayRegistrationV1 = (
+export const validateRegisterClusterRelayRequest = (
   valueArg: unknown,
   pathArg = 'cluster relay registration',
 ): string[] => {
   if (!isRecord(valueArg)
-    || !hasExactKeys(valueArg, ['schemaVersion', 'relay', 'registrationSequence'])) {
+    || !hasExactKeys(valueArg, ['relay', 'registrationSequence', 'protocol'])) {
     return [`${pathArg} must use its exact schema`];
   }
-  const errors: string[] = [];
-  if (valueArg.schemaVersion !== 1) {
-    errors.push(`${pathArg} schemaVersion must be 1`);
-  }
+  const errors: string[] = validateProtocolOfferOn(valueArg, `${pathArg} protocol`);
   errors.push(...validateClusterRelayEndpoint(valueArg.relay, `${pathArg} relay`));
   errors.push(...validateClusterRelayNonNegativeInteger(valueArg.registrationSequence,
     `${pathArg} registrationSequence`));
@@ -264,7 +281,7 @@ export const validateClusterRelayRegistrationV1 = (
 /**
  * One cluster's relay as Cloudly serves it to an administrator.
  *
- * This is the read shape, not the registration a relay sends: `IClusterRelayRegistrationV1` is
+ * This is the read shape, not the registration a relay sends: `IRegisterClusterRelayRequest` is
  * what the relay puts on the wire, and this is what Cloudly answers with after it accepted one.
  * `clusterId` names the cluster the relay serves, and `acceptedAt` is Cloudly's own acceptance
  * time, which is what orders two registrations of one cluster.
@@ -321,8 +338,8 @@ export const validateClusterRelayRegistration = (
  * identically; an origin that names an address literal instead of a domain
  * therefore has no issuable certificate.
  */
-export const clusterRelayCertificateDomainName = (relayArg: IClusterRelayV1): string => {
-  const errors = validateClusterRelayV1(relayArg);
+export const clusterRelayCertificateDomainName = (relayArg: IClusterRelay): string => {
+  const errors = validateClusterRelay(relayArg);
   if (errors.length > 0) {
     throw new Error(errors[0]);
   }

package/ts/data/clusteringress.ts

@@ -1,5 +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';
 
 /**
  * The cluster ingress contracts.
@@ -119,16 +121,6 @@ const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
     || Object.getPrototypeOf(valueArg) === null)
 );
 
-const hasExactKeys = (
-  valueArg: Record<string, unknown>,
-  keysArg: readonly string[],
-  optionalKeysArg: readonly string[] = [],
-): boolean => {
-  const actualKeys = Object.keys(valueArg);
-  return keysArg.every((keyArg) => actualKeys.includes(keyArg))
-    && actualKeys.every((keyArg) => keysArg.includes(keyArg) || optionalKeysArg.includes(keyArg));
-};
-
 const isCounter = (valueArg: unknown): valueArg is number => (
   Number.isSafeInteger(valueArg) && (valueArg as number) >= 0
 );
@@ -390,16 +382,24 @@ export const validateClusterTrafficStatisticsPage = (
  * which cluster is speaking comes from the identity tag on the relay's session.
  * A registration that passes here has proven nothing — and no reason it returns
  * ever quotes the bearer, because a reason travels into logs.
+ *
+ * Both hops judge the body in the one server order `protocol.readProtocolOffer`
+ * states, each against its own `clusterIngress` offer, so the relay refuses a peer
+ * it cannot serve without asking Cloudly and reaches this check only afterwards.
+ * The `validateProtocolOfferOn` call below is therefore the self-consistency
+ * check of a body that was already negotiated, never the negotiation step; it
+ * reads the offer the same way, as data, so naming reasons never runs an
+ * accessor a peer put on the body.
  */
 export const validateClusterIngressRegistration = (
   valueArg: unknown,
   pathArg = 'cluster ingress registration',
 ): string[] => {
   if (!isRecord(valueArg)
-    || !hasExactKeys(valueArg, ['bearer', 'version', 'nodeId'], ['capabilities'])) {
+    || !hasExactKeys(valueArg, ['bearer', 'version', 'nodeId', 'protocol'], ['capabilities'])) {
     return [`${pathArg} must use its exact schema`];
   }
-  const errors: string[] = [];
+  const errors: string[] = validateProtocolOfferOn(valueArg, `${pathArg} protocol`);
   if (typeof valueArg.bearer !== 'string'
     || valueArg.bearer.length < clusterIngressLimits.minimumIngressBearerLength
     || valueArg.bearer.length > clusterIngressLimits.maximumIngressBearerLength) {