@serve.zone/interfaces 32.2.0 → 32.4.0

package/ts/data/clusternode.ts

@@ -6,7 +6,11 @@ import {
   canonicalizeStrictJson,
   createCanonicalJsonSha256Hex,
 } from '../private/canonicaljson.js';
-import { hasExactKeys } from '../private/dataproperties.js';
+import {
+  hasExactKeys,
+  readDataElements,
+  readDataProperties,
+} from '../private/dataproperties.js';
 
 export interface IClusterNodeMetrics {
   cpuUsagePercent: number;
@@ -610,6 +614,29 @@ export const validateSparkSwarmObservation = async (
   }
 };
 
+/**
+ * Which node is reporting, in the two members every Spark route body carries.
+ *
+ * All four routes authenticate the same reporter from the same pair, so the rule lives here: a
+ * copy per route is how one route ends up admitting a bearer another refuses.
+ */
+const validateSparkReporterIdentity = (
+  requestArg: Record<string, unknown>,
+  labelArg: string,
+): string[] => {
+  const errors: string[] = [];
+  if (!isRuntimeIdentifier(requestArg.nodeId)) {
+    errors.push(`${labelArg} nodeId must be canonical`);
+  }
+  if (typeof requestArg.nodeToken !== 'string'
+    || requestArg.nodeToken.length < 1
+    || requestArg.nodeToken.length > 512
+    || requestArg.nodeToken.trim() !== requestArg.nodeToken) {
+    errors.push(`${labelArg} nodeToken must be a bounded opaque token`);
+  }
+  return errors;
+};
+
 export const validateSparkSwarmObservationRequest = async (
   requestArg: unknown,
 ): Promise<string[]> => {
@@ -632,15 +659,10 @@ export const validateSparkSwarmObservationRequest = async (
       'Spark Swarm observation request protocol',
     );
     errors.push(...await validateSparkSwarmObservation(requestArg.observation));
-    if (!isRuntimeIdentifier(requestArg.nodeId)) {
-      errors.push('Spark Swarm observation request nodeId must be canonical');
-    }
-    if (typeof requestArg.nodeToken !== 'string'
-      || requestArg.nodeToken.length < 1
-      || requestArg.nodeToken.length > 512
-      || requestArg.nodeToken.trim() !== requestArg.nodeToken) {
-      errors.push('Spark Swarm observation request nodeToken must be a bounded opaque token');
-    }
+    errors.push(...validateSparkReporterIdentity(
+      requestArg,
+      'Spark Swarm observation request',
+    ));
     return errors;
   } catch {
     return ['Spark Swarm observation request must be safely inspectable'];
@@ -735,6 +757,431 @@ export const validateSparkSwarmObservationResponse = async (
   }
 };
 
+/** A runtime description or a service name: bounded, and free of bytes JSON text cannot carry. */
+const maximumSparkRuntimeTextLength = 512;
+/** An operator-facing message, which may hold line breaks but is still bounded. */
+const maximumSparkMessageTextLength = 2048;
+/** `sparkSwarmNodeContracts.actionResult` states what a server keeps of an action's output. */
+const maximumSparkActionResultTextLength = 4000;
+/**
+ * The route's own byte bound refuses an oversized runtime description first; this stops an
+ * in-process caller from making the validator walk a list no route could have delivered.
+ */
+const maximumSparkRuntimeServices = 64;
+
+const sparkCloudlyConnectionStatuses = new Set<TSparkCloudlyConnectionStatus>([
+  'not-configured',
+  'connecting',
+  'connected',
+  'failed',
+]);
+const sparkNodeModes = new Set<TSparkNodeMode>(['cloudly', 'coreflow-node']);
+const sparkActionResultStatuses = new Set<TNodeActionStatus>([
+  'running',
+  'succeeded',
+  'failed',
+]);
+
+const isBoundedText = (
+  valueArg: unknown,
+  maximumLengthArg = maximumSparkRuntimeTextLength,
+): valueArg is string => (
+  typeof valueArg === 'string'
+  && valueArg.length > 0
+  && valueArg.length <= maximumLengthArg
+  && !/[\u0000-\u001f\u007f]/u.test(valueArg)
+);
+
+/** Message text a node reports: line breaks and tabs are its content, other control bytes are not. */
+const isBoundedMessageText = (
+  valueArg: unknown,
+  maximumLengthArg: number,
+): valueArg is string => (
+  typeof valueArg === 'string'
+  && valueArg.length <= maximumLengthArg
+  && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(valueArg)
+);
+
+const isNonNegativeNumber = (
+  valueArg: unknown,
+  maximumArg = Number.MAX_SAFE_INTEGER,
+): valueArg is number => (
+  typeof valueArg === 'number'
+  && Number.isFinite(valueArg)
+  && !Object.is(valueArg, -0)
+  && valueArg >= 0
+  && valueArg <= maximumArg
+);
+
+const isNonNegativeSafeInteger = (valueArg: unknown): valueArg is number => (
+  Number.isSafeInteger(valueArg) && !Object.is(valueArg, -0) && (valueArg as number) >= 0
+);
+
+/** A record a Spark body states, detached from the caller's object, or `null` with the reason. */
+interface ISparkRecordReading {
+  record: Record<string, unknown> | null;
+  errors: string[];
+}
+
+/**
+ * One level of a Spark body: own enumerable data properties only, then the exact key set.
+ *
+ * The heartbeat, metrics-sample and action-result bodies are judged member by member rather than
+ * as canonical bytes, because only the observation is digested and those three legitimately carry
+ * fractional CPU, memory and rate observations that the digest's integer encoding would refuse.
+ * What the canonical reader also gave — a body that cannot run code or answer differently on a
+ * second read — is kept here by copying the data properties away from the caller's object before
+ * any member is judged.
+ */
+const readSparkRecord = (
+  valueArg: unknown,
+  labelArg: string,
+  requiredKeysArg: readonly string[],
+  optionalKeysArg: readonly string[] = [],
+): ISparkRecordReading => {
+  const record = readDataProperties(valueArg);
+  if (record === null) {
+    return { record: null, errors: [`${labelArg} must contain plain JSON data properties`] };
+  }
+  if (!hasExactKeys(record, requiredKeysArg, optionalKeysArg)) {
+    return { record: null, errors: [`${labelArg} must use its exact schema`] };
+  }
+  return { record, errors: [] };
+};
+
+/**
+ * The envelope a Spark route body states before its payload: the exact key set, the reporter's
+ * protocol offer read by name, and the reporter's identity — in that order, because a server
+ * answers an unreadable offer before it looks at anything the body claims about a node.
+ */
+const readSparkRouteEnvelope = (
+  requestArg: unknown,
+  labelArg: string,
+  requiredKeysArg: readonly string[],
+  optionalKeysArg: readonly string[] = [],
+): ISparkRecordReading => {
+  const reading = readSparkRecord(requestArg, labelArg, requiredKeysArg, optionalKeysArg);
+  if (reading.record === null) {
+    return reading;
+  }
+  return {
+    record: reading.record,
+    errors: [
+      ...validateProtocolOfferOn(reading.record, `${labelArg} protocol`),
+      ...validateSparkReporterIdentity(reading.record, labelArg),
+    ],
+  };
+};
+
+/**
+ * One reason per member, collected rather than thrown.
+ *
+ * A Spark route answers a refusal before the node is authenticated, so the reporter only ever
+ * learns which member of its own body was wrong; naming that member is what lets an operator fix
+ * a node without reading the server's source.
+ */
+const createSparkFieldErrors = (
+  recordArg: Record<string, unknown>,
+  labelArg: string,
+) => {
+  const errors: string[] = [];
+  return {
+    errors,
+    number: (keyArg: string, maximumArg?: number): void => {
+      if (!isNonNegativeNumber(recordArg[keyArg], maximumArg)) {
+        errors.push(`${labelArg} ${keyArg} must be a bounded non-negative number`);
+      }
+    },
+    percentage: (keyArg: string): void => {
+      if (!isNonNegativeNumber(recordArg[keyArg], 100)) {
+        errors.push(`${labelArg} ${keyArg} must be a percentage between 0 and 100`);
+      }
+    },
+    count: (keyArg: string): void => {
+      if (!isNonNegativeSafeInteger(recordArg[keyArg])) {
+        errors.push(`${labelArg} ${keyArg} must be a non-negative safe integer`);
+      }
+    },
+    instant: (keyArg: string): void => {
+      if (!isPositiveSafeInteger(recordArg[keyArg])) {
+        errors.push(`${labelArg} ${keyArg} must be a positive safe integer timestamp`);
+      }
+    },
+    text: (keyArg: string): void => {
+      if (!isBoundedText(recordArg[keyArg])) {
+        errors.push(`${labelArg} ${keyArg} must be bounded non-empty text`);
+      }
+    },
+    messageText: (keyArg: string, maximumLengthArg: number): void => {
+      if (!isBoundedMessageText(recordArg[keyArg], maximumLengthArg)) {
+        errors.push(`${labelArg} ${keyArg} must be bounded message text`);
+      }
+    },
+    identifier: (keyArg: string): void => {
+      if (!isRuntimeIdentifier(recordArg[keyArg])) {
+        errors.push(`${labelArg} ${keyArg} must be canonical`);
+      }
+    },
+    boolean: (keyArg: string): void => {
+      if (typeof recordArg[keyArg] !== 'boolean') {
+        errors.push(`${labelArg} ${keyArg} must be a boolean`);
+      }
+    },
+    member: <TMember extends string>(keyArg: string, allowedArg: ReadonlySet<TMember>): void => {
+      if (!allowedArg.has(recordArg[keyArg] as TMember)) {
+        errors.push(`${labelArg} ${keyArg} is outside the supported values`);
+      }
+    },
+    /** Runs `checkArg` only when the optional member is present at all. */
+    optional: (keyArg: string, checkArg: (keyArg: string) => void): void => {
+      if (recordArg[keyArg] !== undefined) {
+        checkArg(keyArg);
+      }
+    },
+  };
+};
+
+const validateSparkNodeMetrics = (valueArg: unknown, labelArg: string): string[] => {
+  const reading = readSparkRecord(valueArg, labelArg, [
+    'cpuUsagePercent',
+    'memoryUsedMB',
+    'memoryAvailableMB',
+    'diskUsedGB',
+    'diskAvailableGB',
+    'containerCount',
+    'timestamp',
+  ]);
+  if (reading.record === null) {
+    return reading.errors;
+  }
+  const field = createSparkFieldErrors(reading.record, labelArg);
+  field.percentage('cpuUsagePercent');
+  field.number('memoryUsedMB');
+  field.number('memoryAvailableMB');
+  field.number('diskUsedGB');
+  field.number('diskAvailableGB');
+  field.count('containerCount');
+  field.instant('timestamp');
+  return field.errors;
+};
+
+const validateNodeMetricsSample = (valueArg: unknown, labelArg: string): string[] => {
+  const reading = readSparkRecord(
+    valueArg,
+    labelArg,
+    ['timestamp', 'cpuUsagePercent', 'memoryUsedMB', 'memoryAvailableMB'],
+    ['networkRxBytesPerSec', 'networkTxBytesPerSec'],
+  );
+  if (reading.record === null) {
+    return reading.errors;
+  }
+  const field = createSparkFieldErrors(reading.record, labelArg);
+  field.instant('timestamp');
+  field.percentage('cpuUsagePercent');
+  field.number('memoryUsedMB');
+  field.number('memoryAvailableMB');
+  field.optional('networkRxBytesPerSec', field.number);
+  field.optional('networkTxBytesPerSec', field.number);
+  return field.errors;
+};
+
+const validateServeZoneServiceRuntimeInfo = (
+  valueArg: unknown,
+  labelArg: string,
+): string[] => {
+  const reading = readSparkRecord(
+    valueArg,
+    labelArg,
+    ['name', 'running', 'checkedAt'],
+    [
+      'serviceId',
+      'image',
+      'desiredImage',
+      'imageVersion',
+      'runningImageId',
+      'runningTaskCount',
+      'updatedAt',
+      'error',
+    ],
+  );
+  if (reading.record === null) {
+    return reading.errors;
+  }
+  const field = createSparkFieldErrors(reading.record, labelArg);
+  field.text('name');
+  field.boolean('running');
+  field.instant('checkedAt');
+  field.optional('serviceId', field.text);
+  field.optional('image', field.text);
+  field.optional('desiredImage', field.text);
+  field.optional('imageVersion', field.text);
+  field.optional('runningImageId', field.text);
+  field.optional('runningTaskCount', field.count);
+  field.optional('updatedAt', field.instant);
+  field.optional('error', (keyArg) => field.messageText(keyArg, maximumSparkMessageTextLength));
+  return field.errors;
+};
+
+const validateSparkNodeRuntimeInfo = (valueArg: unknown, labelArg: string): string[] => {
+  const reading = readSparkRecord(
+    valueArg,
+    labelArg,
+    [
+      'runtime',
+      'nodeId',
+      'platform',
+      'arch',
+      'sparkVersion',
+      'cloudlyConnectionStatus',
+      'dockerAvailable',
+      'checkedAt',
+    ],
+    [
+      'mode',
+      'hostname',
+      'osRelease',
+      'cloudlyUrl',
+      'swarmNodeId',
+      'serveZoneServices',
+      'lastError',
+    ],
+  );
+  if (reading.record === null) {
+    return reading.errors;
+  }
+  const runtimeInfo = reading.record;
+  const field = createSparkFieldErrors(runtimeInfo, labelArg);
+  if (runtimeInfo.runtime !== 'spark') {
+    field.errors.push(`${labelArg} runtime must be spark`);
+  }
+  field.identifier('nodeId');
+  field.text('platform');
+  field.text('arch');
+  field.text('sparkVersion');
+  field.member('cloudlyConnectionStatus', sparkCloudlyConnectionStatuses);
+  field.boolean('dockerAvailable');
+  field.instant('checkedAt');
+  field.optional('mode', (keyArg) => field.member(keyArg, sparkNodeModes));
+  field.optional('hostname', field.text);
+  field.optional('osRelease', field.text);
+  field.optional('cloudlyUrl', field.text);
+  field.optional('swarmNodeId', field.identifier);
+  field.optional('lastError', (keyArg) => field.messageText(keyArg, maximumSparkMessageTextLength));
+  if (runtimeInfo.serveZoneServices !== undefined) {
+    const services = readDataElements(runtimeInfo.serveZoneServices, maximumSparkRuntimeServices);
+    if (services === null) {
+      field.errors.push(
+        `${labelArg} serveZoneServices must be a bounded list of at most `
+        + `${maximumSparkRuntimeServices} described services`,
+      );
+    } else {
+      services.forEach((serviceArg, indexArg) => {
+        field.errors.push(...validateServeZoneServiceRuntimeInfo(
+          serviceArg,
+          `${labelArg} serveZoneServices[${indexArg}]`,
+        ));
+      });
+    }
+  }
+  return field.errors;
+};
+
+/**
+ * Spark -> Cloudly body for `sparkSwarmNodeContracts.heartbeat.endpoint`.
+ *
+ * Stated here beside the shape it judges, so the server that reads the beat and the node that
+ * writes it apply one set of acceptance rules; a reader that kept its own member checks would
+ * decide on its own which beats exist.
+ *
+ * Every Spark route validator answers the same way — one string per refused member, empty for an
+ * admissible body, and the same `(body) => Promise<string[]>` signature, so a server can hold the
+ * four routes in one table.
+ */
+export const validateSparkSwarmNodeHeartbeatRequest = async (
+  requestArg: unknown,
+): Promise<string[]> => {
+  const label = 'Spark Swarm node heartbeat request';
+  try {
+    const envelope = readSparkRouteEnvelope(
+      requestArg,
+      label,
+      ['nodeId', 'nodeToken', 'protocol', 'metrics', 'runtimeInfo'],
+    );
+    if (envelope.record === null) {
+      return envelope.errors;
+    }
+    envelope.errors.push(...validateSparkNodeMetrics(
+      envelope.record.metrics,
+      `${label} metrics`,
+    ));
+    envelope.errors.push(...validateSparkNodeRuntimeInfo(
+      envelope.record.runtimeInfo,
+      `${label} runtimeInfo`,
+    ));
+    return envelope.errors;
+  } catch {
+    return [`${label} must be safely inspectable`];
+  }
+};
+
+/** Spark -> Cloudly body for `sparkSwarmNodeContracts.metricsSample.endpoint`. */
+export const validateSparkMetricsSampleRequest = async (
+  requestArg: unknown,
+): Promise<string[]> => {
+  const label = 'Spark metrics sample request';
+  try {
+    const envelope = readSparkRouteEnvelope(
+      requestArg,
+      label,
+      ['nodeId', 'nodeToken', 'protocol', 'sample'],
+    );
+    if (envelope.record === null) {
+      return envelope.errors;
+    }
+    envelope.errors.push(...validateNodeMetricsSample(
+      envelope.record.sample,
+      `${label} sample`,
+    ));
+    return envelope.errors;
+  } catch {
+    return [`${label} must be safely inspectable`];
+  }
+};
+
+/**
+ * Spark -> Cloudly body for `sparkSwarmNodeContracts.actionResult.endpoint`.
+ *
+ * `pending` is the one status a node never reports: an action it has not started has no result to
+ * post, and a server that accepted one would reopen an action it already handed out.
+ */
+export const validateSparkActionResultRequest = async (
+  requestArg: unknown,
+): Promise<string[]> => {
+  const label = 'Spark action result request';
+  try {
+    const envelope = readSparkRouteEnvelope(
+      requestArg,
+      label,
+      ['nodeId', 'nodeToken', 'protocol', 'actionId', 'status'],
+      ['resultText'],
+    );
+    if (envelope.record === null) {
+      return envelope.errors;
+    }
+    const field = createSparkFieldErrors(envelope.record, label);
+    field.identifier('actionId');
+    field.member('status', sparkActionResultStatuses);
+    field.optional('resultText', (keyArg) => field.messageText(
+      keyArg,
+      maximumSparkActionResultTextLength,
+    ));
+    envelope.errors.push(...field.errors);
+    return envelope.errors;
+  } catch {
+    return [`${label} must be safely inspectable`];
+  }
+};
+
 /**
  * The exact five members of a target that the set digest is taken over.
  *