@serve.zone/interfaces 32.0.2 → 32.2.0

package/ts/data/noderetirement.ts

@@ -0,0 +1,63 @@
+import { captureNetwork, networkCounter, networkId, networkRecord, requireNetwork } from '../private/networkcontract.js';
+import { isOneOf, producerSafe } from '../private/producercontract.js';
+
+const nodeRuntimeRetirementStates = ['retiring', 'retired'] as const;
+
+/**
+ * How far a node's retirement has come: `retiring` while the producer still stops and removes the
+ * node's slots, the compiler quarantines its handoff and both node credentials are revoked;
+ * `retired` once all of that has settled and nothing but the node document is left to delete.
+ */
+export type TNodeRuntimeRetirementState = typeof nodeRuntimeRetirementStates[number];
+
+/**
+ * That one node leaves its cluster's runtime, stored beside the node document rather than inside
+ * it, because a node update merges caller data and no caller may retire a node with it.
+ *
+ * The producers read the row's presence rather than its state: a node that has one is no longer an
+ * egress member and desires no slots. The row is therefore written before anything is taken away,
+ * and it stays for as long as the node document does.
+ */
+export interface INodeRuntimeRetirement {
+  /** The node id. */
+  id: string;
+  /** The cluster the node is retiring from, copied by Cloudly; never caller-chosen. */
+  clusterId: string;
+  state: TNodeRuntimeRetirementState;
+  /** The administrator who asked for the retirement. */
+  actorId: string;
+  /** Unix milliseconds on Cloudly's clock, when the row entered its current state. */
+  since: number;
+}
+
+/**
+ * Every reason Cloudly answers instead of retiring a node. Each travels as a `TypedResponseError`,
+ * and none of them takes anything away: a refused retirement leaves the node exactly as it was.
+ */
+export const nodeRuntimeRetirementRefusals = Object.freeze([
+  /** No node of that id exists, so there is nothing to retire. */
+  'node-missing',
+  /**
+   * The node's cluster runs no Pallet runtime — it has no phase record, or a phase other than
+   * `pallet`. Which of the two it is, `getClusterRuntime` says.
+   */
+  'cluster-runtime-not-pallet',
+  /** The node already carries a retirement row; neither of its states is left by retiring again. */
+  'node-already-retired',
+  /** `expectedGeneration` is not the cluster runtime's current generation, so a cutover moved underneath the caller. */
+  'conflict',
+] as const);
+
+/** One of the reasons Cloudly answers instead of a retirement row. */
+export type TNodeRuntimeRetirementRefusal = typeof nodeRuntimeRetirementRefusals[number];
+
+/**
+ * Structural snapshot for exact persistence; whether the node exists and whether its cluster admits
+ * the retirement is Cloudly's.
+ */
+export const snapshotNodeRuntimeRetirement = (value: unknown): INodeRuntimeRetirement => producerSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['id', 'clusterId', 'state', 'actorId', 'since']);
+  requireNetwork(isOneOf(nodeRuntimeRetirementStates, item.state));
+  return { id: networkId(item.id), clusterId: networkId(item.clusterId), state: item.state,
+    actorId: networkId(item.actorId), since: networkCounter(item.since) };
+});

package/ts/data/serviceruntime.ts

@@ -77,8 +77,9 @@ export const serviceRuntimeContract = Object.freeze({
 const serviceRuntimeWaitingReasons = ['node-network-pending', 'conflict', 'failure-backoff'] as const;
 const serviceRuntimeRefusals = [
   'cluster-runtime-missing', 'organization-missing', 'image-plan-missing', 'platform-unsupported',
-  'secrets-unsupported', 'volumes-unsupported', 'port-protocol-unsupported', 'readiness-target-undeclared',
-  'environment-too-large', 'no-eligible-node', 'replica-limit',
+  'secrets-unsupported', 'volumes-unsupported', 'port-protocol-unsupported', 'ports-too-many',
+  'readiness-target-undeclared', 'environment-too-large', 'no-eligible-node', 'replica-limit',
+  'node-authority-unsupported',
 ] as const;
 
 /**
@@ -88,7 +89,15 @@ const serviceRuntimeRefusals = [
  */
 export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[number];
 
-/** Why the producer admits nothing for this spec revision. A refusal never retires running slots. */
+/**
+ * Why the producer admits nothing for this spec revision. A refusal never retires running slots.
+ *
+ * The two a reader cannot derive from the name alone: `ports-too-many` is a service declaring more
+ * target ports than `runtimeConfigContract.maximumTargetPorts` a config carries — a count, where
+ * `port-protocol-unsupported` is about one port's protocol — and `node-authority-unsupported` is a
+ * node whose session resolved fewer workload authorities than this spec needs, which the admit step
+ * refuses rather than handing the node work it would silently park.
+ */
 export type TServiceRuntimeRefusal = typeof serviceRuntimeRefusals[number];
 
 interface IServiceRuntimeStatusBase {

package/ts/platform/storage.golden.ts

@@ -0,0 +1,97 @@
+import type {
+  IAppStoreFilesystemStorageRequest,
+  IAppStoreObjectStorageRequest,
+} from '../appstore/types.js';
+import { deepFreezeValue } from '../private/canonicaljson.js';
+
+export interface IStorageRequestCanonicalDigestGoldenVector<TInput> {
+  input: TInput;
+  canonicalJson: string;
+  sha256: string;
+}
+
+const filesystemRequest: IAppStoreFilesystemStorageRequest = {
+  id: 'app-state',
+  kind: 'filesystem',
+  storageClass: 'databaseFast',
+  accessMode: 'ReadWriteOnce',
+  reclaimPolicy: 'delete',
+  mountPath: '/var/lib/app',
+  capacity: {
+    request: '20GiB',
+    limit: '40GiB',
+  },
+  protection: {
+    backup: 'required',
+    snapshots: 'portable',
+    consistency: 'applicationConsistent',
+  },
+};
+
+const objectStorageLauncherEnvironmentRequest: IAppStoreObjectStorageRequest = {
+  id: 'object-data',
+  kind: 'objectStorage',
+  storageClass: 'backupCapacity',
+  accessMode: 'readWrite',
+  reclaimPolicy: 'retain',
+  delivery: {
+    type: 'launcher-environment',
+    keys: {
+      endpoint: 'APP_S3_ENDPOINT',
+      bucket: 'APP_S3_BUCKET',
+      region: 'APP_S3_REGION',
+      accessKeyId: 'APP_S3_ACCESS_KEY',
+      secretAccessKey: 'APP_S3_SECRET_KEY',
+    },
+  },
+  capacity: {
+    request: '500GiB',
+  },
+  protection: {
+    backup: 'required',
+    versioning: 'required',
+    retentionDays: 30,
+  },
+};
+
+const objectStorageFileRequest: IAppStoreObjectStorageRequest = {
+  id: 'object-archive',
+  kind: 'objectStorage',
+  storageClass: 'archiveCapacity',
+  accessMode: 'readOnly',
+  reclaimPolicy: 'delete',
+  delivery: {
+    type: 'file',
+    targetPath: '/run/secrets/object-archive.json',
+    format: 'servezone-object-storage',
+    uid: 10_000,
+    gid: 10_000,
+    mode: 0o400,
+  },
+};
+
+/**
+ * The storage request digest, written down for both kinds and both deliveries.
+ *
+ * A control plane and its consumer compare this value, so it is stated here as bytes rather than
+ * as whatever the current normalizer happens to produce: a member that starts or stops
+ * participating, an optional member that starts being carried when it is absent, or a delivery
+ * mode written as anything but its number would move these digests and be caught here.
+ */
+export const storageRequestCanonicalDigestGoldenVectors = deepFreezeValue({
+  filesystem: {
+    input: filesystemRequest,
+    canonicalJson: '{"accessMode":"ReadWriteOnce","capacity":{"limit":"40GiB","request":"20GiB"},"id":"app-state","kind":"filesystem","mountPath":"/var/lib/app","protection":{"backup":"required","consistency":"applicationConsistent","snapshots":"portable"},"reclaimPolicy":"delete","storageClass":"databaseFast"}',
+    sha256: '0f8dc2e480ade7110be1f1d95f666cc56d5b90110d1c4a1b8b8383e2eeda6fae',
+  },
+  objectStorageLauncherEnvironment: {
+    input: objectStorageLauncherEnvironmentRequest,
+    canonicalJson: '{"accessMode":"readWrite","capacity":{"request":"500GiB"},"delivery":{"keys":{"accessKeyId":"APP_S3_ACCESS_KEY","bucket":"APP_S3_BUCKET","endpoint":"APP_S3_ENDPOINT","region":"APP_S3_REGION","secretAccessKey":"APP_S3_SECRET_KEY"},"type":"launcher-environment"},"id":"object-data","kind":"objectStorage","protection":{"backup":"required","retentionDays":30,"versioning":"required"},"reclaimPolicy":"retain","storageClass":"backupCapacity"}',
+    sha256: '88bd943800bea75b576612b966484e66ddbf7ec9529a7f29dd1eadc9a36e2b79',
+  },
+  objectStorageFile: {
+    input: objectStorageFileRequest,
+    canonicalJson: '{"accessMode":"readOnly","delivery":{"format":"servezone-object-storage","gid":10000,"mode":256,"targetPath":"/run/secrets/object-archive.json","type":"file","uid":10000},"id":"object-archive","kind":"objectStorage","reclaimPolicy":"delete","storageClass":"archiveCapacity"}',
+    sha256: '13186abbfe733b3917363e0694d367f2d6aa87a4064445532d7c857ee274f795',
+  },
+});

package/ts/platform/storage.ts

@@ -1,4 +1,9 @@
 import type { TSecretManagementScope } from '../data/secret.js';
+import {
+  canonicalizeStrictJson,
+  createCanonicalJsonSha256Hex,
+} from '../private/canonicaljson.js';
+import { createStorageContractReaders } from '../private/storagecontract.js';
 
 /**
  * Backend-neutral storage vocabulary shared by App Store manifests, control
@@ -186,8 +191,12 @@ export interface IResolvedStorageBindingBase {
   /** Stable App Store storageRequests[].id. */
   requestId: string;
   /**
-   * Canonical digest of the normalized request. Adapters use it to distinguish
-   * an idempotent reconciliation from a migration.
+   * Canonical digest of the normalized request, exactly as
+   * `createStorageRequestSha256` states it: bare lowercase hex over the request
+   * alone. Adapters use it to distinguish an idempotent reconciliation from a
+   * migration, and a consumer re-derives it to recognise the request it asked
+   * for, so the control plane and the consumer call that one function rather
+   * than each deriving a value the other cannot reproduce.
    */
   requestDigest: string;
   kind: TStorageResourceKind;
@@ -232,3 +241,51 @@ extends IResolvedStorageBindingBase {
 export type TResolvedStorageBinding =
   | IResolvedFilesystemStorageBinding
   | IResolvedObjectStorageBinding;
+
+export class StorageContractError extends Error {
+  public constructor(reasonArg: string) {
+    super(`storage contract error: ${reasonArg}`);
+    this.name = 'StorageContractError';
+  }
+}
+
+const fail = (reasonArg: string): never => {
+  throw new StorageContractError(reasonArg);
+};
+
+const { normalizeStorageRequest } = createStorageContractReaders(fail);
+
+/**
+ * The exact bytes a storage request's digest is taken over: the request normalized to its contract
+ * shape, written as strict canonical JSON — keys in UTF-16 code-unit order, no whitespace, no
+ * absent member carried as `null`.
+ *
+ * Anything that is not a storage request is refused rather than hashed, because a digest of an
+ * unjudged body would name a request no adapter could fulfil.
+ */
+export const canonicalizeStorageRequest = (valueArg: unknown): string => {
+  return canonicalizeStrictJson(
+    normalizeStorageRequest(valueArg, 'storage request'),
+    fail,
+  );
+};
+
+/**
+ * The storage request digest: bare lowercase hex SHA-256 over the canonical request, with no
+ * prefix and nothing but the request in the hashed value.
+ *
+ * A control plane issues this value on a binding and a consumer re-derives it from the request it
+ * declared; the two only agree because they call this one function. A second derivation elsewhere
+ * — a prefix, or a wrapper object around the request — is a different value for the same binding,
+ * and the consumer would keep rejecting a binding that is in fact its own.
+ */
+export const createStorageRequestSha256 = async (
+  valueArg: unknown,
+): Promise<string> => {
+  return createCanonicalJsonSha256Hex(canonicalizeStorageRequest(valueArg), fail);
+};
+
+export {
+  storageRequestCanonicalDigestGoldenVectors,
+  type IStorageRequestCanonicalDigestGoldenVector,
+} from './storage.golden.js';