@serve.zone/interfaces 31.8.0 → 32.0.0

package/dist_ts/data/clusternode.d.ts

@@ -1,6 +1,7 @@
 import * as plugins from '../plugins.js';
 import type { TSha256Digest, TImmutableContainerPlatform } from './immutableimage.js';
-import type { ISparkNodeReportRecordV2 } from './sparknodereport.js';
+import type { ISparkNodeReportRecord } from './sparknodereport.js';
+import { type IProtocolOffer } from '../protocol.js';
 export interface IClusterNodeMetrics {
     cpuUsagePercent: number;
     memoryUsedMB: number;
@@ -58,10 +59,82 @@ export interface IServeZoneServiceRuntimeInfo {
     updatedAt?: number;
     error?: string;
 }
-/** Spark -> Cloudly HTTP body for POST /spark/v1/nodes/metrics-sample */
+/**
+ * The Swarm-era Spark runtime's own routes.
+ *
+ * A separate runtime, not an older version of the node runtime: a worker in `coreflow-node` mode
+ * posts these four bodies, while a pallet node posts `sparkNodeHeartbeatContract.endpoint`. They
+ * retire together with coreflow, not with this release.
+ *
+ * Each route states its endpoint beside the bytes it reads and writes, in the same three members
+ * as `sparkNodeHeartbeatContract`, so one bounded-read helper serves every Spark route. The four
+ * bounds differ because the bodies do: a bound is the largest body its own shape can carry here,
+ * rounded up, and nothing larger is read before it is refused. Every route is judged in the one
+ * server order `protocol.readProtocolOffer` states, against this server's `sparkSwarmNode` offer;
+ * none of them carries a typed error, so a refusal is answered with `protocolRefusalStatus` and an
+ * `IProtocolRefusal` body before the node is authenticated and before the body is acted on. Every
+ * answer states this server's own offer, exactly as the request states the reporter's, so each
+ * side judges the other from the bodies they exchanged.
+ */
+export declare const sparkSwarmNodeContracts: Readonly<{
+    /** The full runtime description on every beat; each described service costs some 600 bytes. */
+    readonly heartbeat: Readonly<{
+        readonly endpoint: "/spark/swarm-nodes/heartbeat";
+        readonly maxRequestBytes: 32768;
+        readonly maxResponseBytes: 2048;
+    }>;
+    /** One sample up, every action the server holds for this node back down. */
+    readonly metricsSample: Readonly<{
+        readonly endpoint: "/spark/swarm-nodes/metrics-sample";
+        readonly maxRequestBytes: 4096;
+        readonly maxResponseBytes: 32768;
+    }>;
+    /** `resultText` is the body here, and a server keeps at most 4000 characters of it. */
+    readonly actionResult: Readonly<{
+        readonly endpoint: "/spark/swarm-nodes/action-result";
+        readonly maxRequestBytes: 8192;
+        readonly maxResponseBytes: 2048;
+    }>;
+    /**
+     * By far the largest of the four: a manager snapshot carries up to the 1024 observed nodes
+     * `validateSparkSwarmObservationRequest` admits, each with two identifiers of up to 200
+     * characters, which is close to 600 KiB of body this route must still be able to read.
+     */
+    readonly swarmObservation: Readonly<{
+        readonly endpoint: "/spark/swarm-nodes/swarm-observation";
+        readonly maxRequestBytes: 786432;
+        readonly maxResponseBytes: 2048;
+    }>;
+    readonly protocolRefusalStatus: 422;
+}>;
+/**
+ * Spark -> Cloudly body for `sparkSwarmNodeContracts.heartbeat.endpoint`.
+ *
+ * The host presentation of a Swarm-era worker: its metrics and its runtime description, both
+ * stated in full on every beat. This is the one owner of the shape — Cloudly and Spark each
+ * carried a private copy until 32.0.0, which is how the two drifted apart.
+ */
+export interface ISparkSwarmNodeHeartbeatRequest {
+    nodeId: string;
+    nodeToken: string;
+    /** Read and negotiated before the node is authenticated; see `sparkSwarmNodeContracts`. */
+    protocol: IProtocolOffer;
+    metrics: IClusterNodeMetrics;
+    runtimeInfo: ISparkNodeRuntimeInfo;
+}
+/** What Cloudly answers a Swarm-era heartbeat with; `message` explains a refusal to an operator. */
+export interface ISparkSwarmNodeHeartbeatResponse {
+    accepted: boolean;
+    message?: string;
+    /** The answering server's offer; see `sparkSwarmNodeContracts`. */
+    protocol: IProtocolOffer;
+}
+/** Spark -> Cloudly body for `sparkSwarmNodeContracts.metricsSample.endpoint`. */
 export interface ISparkMetricsSampleRequest {
     nodeId: string;
     nodeToken: string;
+    /** Read and negotiated before the node is authenticated; see `sparkSwarmNodeContracts`. */
+    protocol: IProtocolOffer;
     sample: INodeMetricsSample;
 }
 export interface ISparkMetricsSampleResponse {
@@ -69,11 +142,15 @@ export interface ISparkMetricsSampleResponse {
     message?: string;
     /** Actions queued for this node; spark executes them and posts results. */
     pendingActions?: INodeAction[];
+    /** The answering server's offer; see `sparkSwarmNodeContracts`. */
+    protocol: IProtocolOffer;
 }
-/** Spark -> Cloudly HTTP body for POST /spark/v1/nodes/action-result */
+/** Spark -> Cloudly body for `sparkSwarmNodeContracts.actionResult.endpoint`. */
 export interface ISparkActionResultRequest {
     nodeId: string;
     nodeToken: string;
+    /** Read and negotiated before the node is authenticated; see `sparkSwarmNodeContracts`. */
+    protocol: IProtocolOffer;
     actionId: string;
     status: Extract<TNodeActionStatus, 'running' | 'succeeded' | 'failed'>;
     resultText?: string;
@@ -81,8 +158,10 @@ export interface ISparkActionResultRequest {
 export interface ISparkActionResultResponse {
     accepted: boolean;
     message?: string;
+    /** The answering server's offer; see `sparkSwarmNodeContracts`. */
+    protocol: IProtocolOffer;
 }
-export interface ISwarmManagerObservedNodeV1 {
+export interface ISwarmManagerObservedNode {
     swarmNodeId: string;
     nodeName: string;
     platform: TImmutableContainerPlatform;
@@ -94,57 +173,36 @@ export interface ISwarmManagerObservedNodeV1 {
         reachability: 'unknown' | 'unreachable' | 'reachable';
     };
 }
-export interface ISwarmManagerSnapshotV1 {
-    snapshotVersion: 1;
+export interface ISwarmManagerSnapshot {
     snapshotDigest: TSha256Digest;
     nodeCount: number;
     managerCount: number;
-    nodes: ISwarmManagerObservedNodeV1[];
+    nodes: ISwarmManagerObservedNode[];
 }
-interface ISparkSwarmObservationBaseV1 {
-    schemaVersion: 1;
+interface ISparkSwarmObservationBase {
     reporterSessionId: string;
     observationSequence: number;
     observedAt: number;
 }
-export type TSparkSwarmObservationV1 = (ISparkSwarmObservationBaseV1 & {
+export type TSparkSwarmObservation = (ISparkSwarmObservationBase & {
     state: 'unknown';
     reason: 'docker-unavailable' | 'query-failed' | 'not-initialized';
-}) | (ISparkSwarmObservationBaseV1 & {
+}) | (ISparkSwarmObservationBase & {
     state: 'not-member';
-}) | (ISparkSwarmObservationBaseV1 & {
-    state: 'member';
-    swarmClusterId: string;
-    localSwarmNodeId: string;
-    controlAvailable: boolean;
-    managerSnapshot?: ISwarmManagerSnapshotV1;
-});
-interface ISparkSwarmObservationBaseV2 {
-    schemaVersion: 2;
-    reporterSessionId: string;
-    observationSequence: number;
-    observedAt: number;
-}
-export type TSparkSwarmObservationV2 = (ISparkSwarmObservationBaseV2 & {
-    state: 'unknown';
-    reason: 'docker-unavailable' | 'query-failed' | 'not-initialized';
-}) | (ISparkSwarmObservationBaseV2 & {
-    state: 'not-member';
-}) | (ISparkSwarmObservationBaseV2 & {
+}) | (ISparkSwarmObservationBase & {
     state: 'member';
     localSwarmNodeId: string;
     controlAvailable: false;
-}) | (ISparkSwarmObservationBaseV2 & {
+}) | (ISparkSwarmObservationBase & {
     state: 'member';
     swarmClusterId: string;
     localSwarmNodeId: string;
     controlAvailable: true;
-    managerSnapshot?: ISwarmManagerSnapshotV1;
+    managerSnapshot?: ISwarmManagerSnapshot;
 });
-export type TSparkSwarmObservationV2RejectionCode = 'sequence-conflict' | 'sequence-stale' | 'sequence-gap' | 'session-sequence-invalid' | 'session-retired' | 'observation-too-old' | 'observation-from-future' | 'observation-time-not-advancing' | 'acceptance-race';
-export declare const sparkSwarmObservationV2Contract: Readonly<{
-    readonly endpoint: "/spark/v2/nodes/swarm-observation";
-    readonly digestDomain: "serve.zone/spark-swarm-observation-v2";
+export type TSparkSwarmObservationRejectionCode = 'sequence-conflict' | 'sequence-stale' | 'sequence-gap' | 'session-sequence-invalid' | 'session-retired' | 'observation-too-old' | 'observation-from-future' | 'observation-time-not-advancing' | 'acceptance-race';
+export declare const sparkSwarmObservationContract: Readonly<{
+    readonly digestDomain: "serve.zone/spark-swarm-observation";
     readonly maximumPastAgeMs: 300000;
     readonly maximumFutureSkewMs: 30000;
     readonly retainedRetiredSessionIds: 32;
@@ -161,13 +219,14 @@ export declare const sparkSwarmObservationV2Contract: Readonly<{
     }>;
 }>;
 /** Cloudly derives node and cluster scope from this authenticated Spark request. */
-export interface ISparkSwarmObservationV2Request {
+export interface ISparkSwarmObservationRequest {
     nodeId: string;
     nodeToken: string;
-    observation: TSparkSwarmObservationV2;
+    /** Read and negotiated before the node is authenticated; see `sparkSwarmNodeContracts`. */
+    protocol: IProtocolOffer;
+    observation: TSparkSwarmObservation;
 }
-export interface ISparkSwarmObservationV2AcceptedReceipt {
-    schemaVersion: 2;
+export interface ISparkSwarmObservationAcceptedReceipt {
     state: 'accepted';
     nodeId: string;
     reporterSessionId: string;
@@ -176,45 +235,35 @@ export interface ISparkSwarmObservationV2AcceptedReceipt {
     acceptedAt: number;
     /** Runtime target generation observed immediately after this acceptance. */
     targetGenerationAtAcceptance: number;
+    /** The answering server's offer; see `sparkSwarmNodeContracts`. */
+    protocol: IProtocolOffer;
 }
-export interface ISparkSwarmObservationV2RejectedReceipt {
-    schemaVersion: 2;
+export interface ISparkSwarmObservationRejectedReceipt {
     state: 'rejected';
     nodeId: string;
     reporterSessionId: string;
     observationSequence: number;
     observationDigest: TSha256Digest;
     rejectedAt: number;
-    code: TSparkSwarmObservationV2RejectionCode;
+    code: TSparkSwarmObservationRejectionCode;
     retryable: boolean;
+    /** The answering server's offer; see `sparkSwarmNodeContracts`. */
+    protocol: IProtocolOffer;
 }
 /**
  * Bound receipts are returned only after request validation and node
  * authentication. Malformed and authentication failures use generic HTTP
  * errors so they cannot expose credential or persisted replay state.
  */
-export type TSparkSwarmObservationV2Response = ISparkSwarmObservationV2AcceptedReceipt | ISparkSwarmObservationV2RejectedReceipt;
-/** Cloudly derives node and cluster scope from this authenticated Spark request. */
-export interface ISparkSwarmObservationRequest {
-    nodeId: string;
-    nodeToken: string;
-    observation: TSparkSwarmObservationV1;
-}
-export interface ISparkSwarmObservationResponse {
-    accepted: boolean;
-    acceptedSequence?: number;
-    targetGeneration?: number;
-    message?: string;
-}
-export interface IClusterRuntimeTargetV1 {
+export type TSparkSwarmObservationResponse = ISparkSwarmObservationAcceptedReceipt | ISparkSwarmObservationRejectedReceipt;
+export interface IClusterRuntimeTarget {
     cloudlyNodeId: string;
     swarmClusterId: string;
     swarmNodeId: string;
     nodeName: string;
     platform: TImmutableContainerPlatform;
 }
-export interface IClusterRuntimeTargetSetReadyV1 {
-    schemaVersion: 1;
+export interface IClusterRuntimeTargetSetReady {
     state: 'ready';
     cloudlyClusterId: string;
     swarmClusterId: string;
@@ -222,29 +271,27 @@ export interface IClusterRuntimeTargetSetReadyV1 {
     targetSetDigest: TSha256Digest;
     acceptedAt: number;
     freshUntil: number;
-    targets: IClusterRuntimeTargetV1[];
+    targets: IClusterRuntimeTarget[];
 }
-export interface IClusterRuntimeTargetSetUnavailableV1 {
-    schemaVersion: 1;
+export interface IClusterRuntimeTargetSetUnavailable {
     state: 'unavailable';
     cloudlyClusterId: string;
     generation: number;
     changedAt: number;
     reason: 'never-observed' | 'stale' | 'no-manager-consensus' | 'identity-conflict' | 'no-schedulable-targets';
 }
-export type TClusterRuntimeTargetSetV1 = IClusterRuntimeTargetSetReadyV1 | IClusterRuntimeTargetSetUnavailableV1;
-export declare const createSparkSwarmObservationV2DigestInput: (observationArg: TSparkSwarmObservationV2) => string;
-export declare const computeSparkSwarmObservationV2Digest: (observationArg: TSparkSwarmObservationV2) => Promise<TSha256Digest>;
-export declare const createSwarmManagerSnapshotDigestInput: (swarmClusterIdArg: string, snapshotArg: ISwarmManagerSnapshotV1) => string;
-export declare const computeSwarmManagerSnapshotDigest: (swarmClusterIdArg: string, snapshotArg: ISwarmManagerSnapshotV1) => Promise<TSha256Digest>;
+export type TClusterRuntimeTargetSet = IClusterRuntimeTargetSetReady | IClusterRuntimeTargetSetUnavailable;
+export declare const createSparkSwarmObservationDigestInput: (observationArg: TSparkSwarmObservation) => string;
+export declare const computeSparkSwarmObservationDigest: (observationArg: TSparkSwarmObservation) => Promise<TSha256Digest>;
+export declare const createSwarmManagerSnapshotDigestInput: (swarmClusterIdArg: string, snapshotArg: ISwarmManagerSnapshot) => string;
+export declare const computeSwarmManagerSnapshotDigest: (swarmClusterIdArg: string, snapshotArg: ISwarmManagerSnapshot) => Promise<TSha256Digest>;
 export declare const validateSparkSwarmObservation: (observationArg: unknown) => Promise<string[]>;
-export declare const validateSparkSwarmObservationV2: (observationArg: unknown) => Promise<string[]>;
-export declare const validateSparkSwarmObservationV2Request: (requestArg: unknown) => Promise<string[]>;
-export declare const validateSparkSwarmObservationV2Response: (responseArg: unknown, expectedRequestArg: ISparkSwarmObservationV2Request) => Promise<string[]>;
-export declare const createClusterRuntimeTargetSetDigestInput: (targetSetArg: IClusterRuntimeTargetSetReadyV1) => string;
-export declare const computeClusterRuntimeTargetSetDigest: (targetSetArg: IClusterRuntimeTargetSetReadyV1) => Promise<TSha256Digest>;
+export declare const validateSparkSwarmObservationRequest: (requestArg: unknown) => Promise<string[]>;
+export declare const validateSparkSwarmObservationResponse: (responseArg: unknown, expectedRequestArg: ISparkSwarmObservationRequest) => Promise<string[]>;
+export declare const createClusterRuntimeTargetSetDigestInput: (targetSetArg: IClusterRuntimeTargetSetReady) => string;
+export declare const computeClusterRuntimeTargetSetDigest: (targetSetArg: IClusterRuntimeTargetSetReady) => Promise<TSha256Digest>;
 export declare const validateClusterRuntimeTargetSet: (targetSetArg: unknown) => Promise<string[]>;
-export declare const isClusterRuntimeTargetSetFresh: (targetSetArg: TClusterRuntimeTargetSetV1, nowArg: number) => targetSetArg is IClusterRuntimeTargetSetReadyV1;
+export declare const isClusterRuntimeTargetSetFresh: (targetSetArg: TClusterRuntimeTargetSet, nowArg: number) => targetSetArg is IClusterRuntimeTargetSetReady;
 export type TSparkNodeMode = 'cloudly' | 'coreflow-node';
 export type TSparkCloudlyConnectionStatus = 'not-configured' | 'connecting' | 'connected' | 'failed';
 export interface ISparkNodeRuntimeInfo {
@@ -304,7 +351,7 @@ export interface IClusterNode {
          */
         sparkRuntimeInfo?: ISparkNodeRuntimeInfo;
         /** Separately accepted Pallet-era host report; never grants workload readiness. */
-        sparkNodeReport?: ISparkNodeReportRecordV2;
+        sparkNodeReport?: ISparkNodeReportRecord;
         /**
          * Docker swarm node ID if part of swarm
          */