@serve.zone/interfaces 7.6.0 → 7.8.0

package/changelog.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 2026-06-10 - 7.8.0
+
+### Features
+
+- add live node metrics and action interfaces (node)
+  - Add high-frequency node metrics sample types for Spark-to-Cloudly reporting and admin UI relay.
+  - Add node action types and TypedRequest contracts for creating, listing, and pushing action updates.
+  - Add Spark action result request and response interfaces.
+
+## 2026-06-10 - 7.7.0
+
+### Features
+
+- add reporter node scoping to deployment snapshots (deployment)
+  - Adds optional reporterNodeNames to deployment snapshot requests to identify the node hostnames a report is authoritative for.
+  - Preserves existing full-service replacement behavior when reporterNodeNames is omitted.
+
 ## 2026-06-10 - 7.6.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '7.6.0',
+    version: '7.8.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/clusternode.d.ts

@@ -8,6 +8,65 @@ export interface IClusterNodeMetrics {
     containerCount: number;
     timestamp: number;
 }
+/**
+ * Lightweight high-frequency node metrics sample (1s cadence).
+ * Streamed spark -> cloudly -> admin UIs; never persisted.
+ */
+export interface INodeMetricsSample {
+    timestamp: number;
+    cpuUsagePercent: number;
+    memoryUsedMB: number;
+    memoryAvailableMB: number;
+    /** Host-level network receive rate across non-loopback interfaces. */
+    networkRxBytesPerSec?: number;
+    /** Host-level network transmit rate across non-loopback interfaces. */
+    networkTxBytesPerSec?: number;
+}
+export type TNodeActionName = 'systemUpgrade' | 'reboot';
+export type TNodeActionStatus = 'pending' | 'running' | 'succeeded' | 'failed';
+/**
+ * An operator-requested action executed by spark on a node.
+ * Delivered to spark in metrics-sample responses; results posted back.
+ */
+export interface INodeAction {
+    id: string;
+    nodeId: string;
+    actionName: TNodeActionName;
+    payload?: {
+        /** Reboot only: gracefully stop workloads before rebooting. */
+        drainFirst?: boolean;
+    };
+    status: TNodeActionStatus;
+    requestedAt: number;
+    requestedBy?: string;
+    startedAt?: number;
+    finishedAt?: number;
+    resultText?: string;
+}
+/** Spark -> Cloudly HTTP body for POST /spark/v1/nodes/metrics-sample */
+export interface ISparkMetricsSampleRequest {
+    nodeId: string;
+    nodeToken: string;
+    sample: INodeMetricsSample;
+}
+export interface ISparkMetricsSampleResponse {
+    accepted: boolean;
+    message?: string;
+    /** Actions queued for this node; spark executes them and posts results. */
+    pendingActions?: INodeAction[];
+}
+/** Spark -> Cloudly HTTP body for POST /spark/v1/nodes/action-result */
+export interface ISparkActionResultRequest {
+    nodeId: string;
+    nodeToken: string;
+    actionId: string;
+    status: Extract<TNodeActionStatus, 'running' | 'succeeded' | 'failed'>;
+    resultText?: string;
+}
+export interface ISparkActionResultResponse {
+    accepted: boolean;
+    message?: string;
+}
 export type TSparkNodeMode = 'cloudly' | 'coreflow-node';
 export type TSparkCloudlyConnectionStatus = 'not-configured' | 'connecting' | 'connected' | 'failed';
 export interface ISparkNodeRuntimeInfo {

package/dist_ts/requests/deployment.d.ts

@@ -302,6 +302,13 @@ export interface IReq_Coreflow_Cloudly_ReportDeploymentSnapshots extends plugins
         serviceId: string;
         serviceName?: string;
         deployments: IDeployment[];
+        /**
+         * Node hostnames this snapshot is authoritative for (the reporter's swarm).
+         * Cloudly prunes stale deployments for the service only on these nodes, so
+         * reports from different swarms/nodes do not delete each other's records.
+         * When absent, the snapshot replaces all persisted deployments of the service.
+         */
+        reporterNodeNames?: string[];
         reportedAt: number;
     };
     response: Record<string, never>;

package/dist_ts/requests/node.d.ts

@@ -1,7 +1,7 @@
 import * as plugins from '../plugins.js';
 import type { IBareMetal } from '../data/baremetal.js';
 import type { ICluster } from '../data/cluster.js';
-import type { IClusterNode, IClusterNodeMetrics, ISparkNodeRuntimeInfo } from '../data/clusternode.js';
+import type { IClusterNode, IClusterNodeMetrics, INodeAction, INodeMetricsSample, ISparkNodeRuntimeInfo, TNodeActionName } from '../data/clusternode.js';
 import type { IDeployment } from '../data/deployment.js';
 import type { IIdentity } from '../data/user.js';
 export interface IRequest_Any_Cloudly_GetNodeConfig {
@@ -106,3 +106,46 @@ export interface IRequest_Spark_Cloudly_SendHeartbeat extends plugins.typedreque
         message?: string;
     };
 }
+export interface IReq_Any_Cloudly_CreateNodeAction extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_CreateNodeAction> {
+    method: 'createNodeAction';
+    request: {
+        identity: IIdentity;
+        nodeId: string;
+        actionName: TNodeActionName;
+        payload?: INodeAction['payload'];
+    };
+    response: {
+        action: INodeAction;
+    };
+}
+export interface IReq_Any_Cloudly_GetNodeActions extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetNodeActions> {
+    method: 'getNodeActions';
+    request: {
+        identity: IIdentity;
+        nodeId: string;
+    };
+    response: {
+        actions: INodeAction[];
+    };
+}
+/**
+ * Cloudly -> admin UIs: live node metrics relay (1s cadence, not persisted).
+ */
+export interface IReq_Cloudly_Any_PushNodeMetricsSample extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Any_PushNodeMetricsSample> {
+    method: 'pushNodeMetricsSample';
+    request: {
+        nodeId: string;
+        sample: INodeMetricsSample;
+    };
+    response: Record<string, never>;
+}
+/**
+ * Cloudly -> admin UIs: node action lifecycle updates.
+ */
+export interface IReq_Cloudly_Any_PushNodeActionUpdate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Any_PushNodeActionUpdate> {
+    method: 'pushNodeActionUpdate';
+    request: {
+        action: INodeAction;
+    };
+    response: Record<string, never>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "7.6.0",
+  "version": "7.8.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '7.6.0',
+  version: '7.8.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/clusternode.ts

@@ -10,6 +10,73 @@ export interface IClusterNodeMetrics {
   timestamp: number;
 }
 
+/**
+ * Lightweight high-frequency node metrics sample (1s cadence).
+ * Streamed spark -> cloudly -> admin UIs; never persisted.
+ */
+export interface INodeMetricsSample {
+  timestamp: number;
+  cpuUsagePercent: number;
+  memoryUsedMB: number;
+  memoryAvailableMB: number;
+  /** Host-level network receive rate across non-loopback interfaces. */
+  networkRxBytesPerSec?: number;
+  /** Host-level network transmit rate across non-loopback interfaces. */
+  networkTxBytesPerSec?: number;
+}
+
+export type TNodeActionName = 'systemUpgrade' | 'reboot';
+
+export type TNodeActionStatus = 'pending' | 'running' | 'succeeded' | 'failed';
+
+/**
+ * An operator-requested action executed by spark on a node.
+ * Delivered to spark in metrics-sample responses; results posted back.
+ */
+export interface INodeAction {
+  id: string;
+  nodeId: string;
+  actionName: TNodeActionName;
+  payload?: {
+    /** Reboot only: gracefully stop workloads before rebooting. */
+    drainFirst?: boolean;
+  };
+  status: TNodeActionStatus;
+  requestedAt: number;
+  requestedBy?: string;
+  startedAt?: number;
+  finishedAt?: number;
+  resultText?: string;
+}
+
+/** Spark -> Cloudly HTTP body for POST /spark/v1/nodes/metrics-sample */
+export interface ISparkMetricsSampleRequest {
+  nodeId: string;
+  nodeToken: string;
+  sample: INodeMetricsSample;
+}
+
+export interface ISparkMetricsSampleResponse {
+  accepted: boolean;
+  message?: string;
+  /** Actions queued for this node; spark executes them and posts results. */
+  pendingActions?: INodeAction[];
+}
+
+/** Spark -> Cloudly HTTP body for POST /spark/v1/nodes/action-result */
+export interface ISparkActionResultRequest {
+  nodeId: string;
+  nodeToken: string;
+  actionId: string;
+  status: Extract<TNodeActionStatus, 'running' | 'succeeded' | 'failed'>;
+  resultText?: string;
+}
+
+export interface ISparkActionResultResponse {
+  accepted: boolean;
+  message?: string;
+}
+
 export type TSparkNodeMode = 'cloudly' | 'coreflow-node';
 
 export type TSparkCloudlyConnectionStatus =

package/ts/requests/deployment.ts

@@ -443,6 +443,13 @@ extends plugins.typedrequestInterfaces.implementsTR<
     serviceId: string;
     serviceName?: string;
     deployments: IDeployment[];
+    /**
+     * Node hostnames this snapshot is authoritative for (the reporter's swarm).
+     * Cloudly prunes stale deployments for the service only on these nodes, so
+     * reports from different swarms/nodes do not delete each other's records.
+     * When absent, the snapshot replaces all persisted deployments of the service.
+     */
+    reporterNodeNames?: string[];
     reportedAt: number;
   };
   response: Record<string, never>;

package/ts/requests/node.ts

@@ -1,7 +1,7 @@
 import * as plugins from '../plugins.js';
 import type { IBareMetal } from '../data/baremetal.js';
 import type { ICluster } from '../data/cluster.js';
-import type { IClusterNode, IClusterNodeMetrics, ISparkNodeRuntimeInfo } from '../data/clusternode.js';
+import type { IClusterNode, IClusterNodeMetrics, INodeAction, INodeMetricsSample, ISparkNodeRuntimeInfo, TNodeActionName } from '../data/clusternode.js';
 import type { IDeployment } from '../data/deployment.js';
 import type { IIdentity } from '../data/user.js';
 
@@ -133,3 +133,62 @@ export interface IRequest_Spark_Cloudly_SendHeartbeat extends plugins.typedreque
     message?: string;
   };
 }
+
+export interface IReq_Any_Cloudly_CreateNodeAction extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_CreateNodeAction
+> {
+  method: 'createNodeAction';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+    actionName: TNodeActionName;
+    payload?: INodeAction['payload'];
+  };
+  response: {
+    action: INodeAction;
+  };
+}
+
+export interface IReq_Any_Cloudly_GetNodeActions extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetNodeActions
+> {
+  method: 'getNodeActions';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+  };
+  response: {
+    actions: INodeAction[];
+  };
+}
+
+/**
+ * Cloudly -> admin UIs: live node metrics relay (1s cadence, not persisted).
+ */
+export interface IReq_Cloudly_Any_PushNodeMetricsSample extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Any_PushNodeMetricsSample
+> {
+  method: 'pushNodeMetricsSample';
+  request: {
+    nodeId: string;
+    sample: INodeMetricsSample;
+  };
+  response: Record<string, never>;
+}
+
+/**
+ * Cloudly -> admin UIs: node action lifecycle updates.
+ */
+export interface IReq_Cloudly_Any_PushNodeActionUpdate extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Any_PushNodeActionUpdate
+> {
+  method: 'pushNodeActionUpdate';
+  request: {
+    action: INodeAction;
+  };
+  response: Record<string, never>;
+}