@norskvideo/norsk-auto-manager 0.1.0

package/src/settingsValidation.ts

@@ -0,0 +1,386 @@
+// Phase D1 — runtime validation of AutoSettings. Hand-rolled in the
+// same shape as `validateBundle` (validation.ts) rather than dragging
+// in zod for a small surface. Returns a list of structured errors —
+// empty means valid.
+//
+// `AutoManager.run` invokes this at entry and throws
+// `AutoSettingsValidationError` if anything fails. Catches typos and
+// shape mistakes at boot rather than mid-flight.
+
+import type { AutoSettings, BandConfig, HotSpareConfig, PlacementConfig } from "./automanager";
+import type { PlacementPool } from "./placement";
+
+/** @public */
+export interface SettingsValidationError {
+  code: SettingsValidationErrorCode;
+  /** Dotted path to the offending field. */
+  path: string;
+  message: string;
+}
+
+/** @public */
+export type SettingsValidationErrorCode =
+  | "invalidType"
+  | "missingRequired"
+  | "outOfRange"
+  | "invalidEnumValue"
+  | "unknownPool"
+  | "duplicatePool"
+  | "incompatibleConfig";
+
+/**
+ * Validate an `AutoSettings` value at boot. Returns all errors found
+ * (does not short-circuit). Callbacks are not validated — TypeScript
+ * structural typing already covers them as well as a runtime check
+ * usefully can. The point of this validator is to catch
+ * configuration mistakes operators make (typos in pool names, bad
+ * enum values, negative timeouts), not to second-guess the type
+ * system.
+ *
+ * @public
+ */
+export function validateAutoSettings(
+  settings: AutoSettings
+): SettingsValidationError[] {
+  const errors: SettingsValidationError[] = [];
+  const ctx = new Ctx(errors);
+
+  ctx.checkPositive(settings.pendingWindow, "pendingWindow");
+  ctx.checkPositive(settings.removeStoppedNodesAfter, "removeStoppedNodesAfter");
+
+  // Flat optional tunables.
+  ctx.checkOptionalPositive(settings.rejectionBackoffMs, "rejectionBackoffMs");
+  ctx.checkOptionalPositive(
+    settings.rejectionEscalationCount,
+    "rejectionEscalationCount"
+  );
+  ctx.checkOptionalPositive(settings.failureBackoffMs, "failureBackoffMs");
+  ctx.checkOptionalPositive(settings.maxRestartsPerHour, "maxRestartsPerHour");
+  ctx.checkOptionalPositive(settings.jobStartupGraceMs, "jobStartupGraceMs");
+  ctx.checkOptionalPositive(
+    settings.hotSpareReconcileIntervalMs,
+    "hotSpareReconcileIntervalMs"
+  );
+
+  // Placement pools.
+  const knownPoolNames = new Set<string>();
+  if (!Array.isArray(settings.placementPools)) {
+    ctx.add("invalidType", "placementPools", "must be an array");
+  } else {
+    settings.placementPools.forEach((pool, i) => {
+      validatePool(pool, `placementPools[${i}]`, knownPoolNames, ctx);
+    });
+  }
+
+  // Typed configs.
+  if (settings.bands !== undefined) {
+    validateBandConfig(settings.bands, "bands", ctx);
+  }
+  if (settings.placement !== undefined) {
+    validatePlacementConfig(settings.placement, "placement", ctx);
+  }
+  if (settings.hotSpares !== undefined) {
+    if (!Array.isArray(settings.hotSpares)) {
+      ctx.add("invalidType", "hotSpares", "must be an array");
+    } else {
+      settings.hotSpares.forEach((entry, i) => {
+        validateHotSpare(
+          entry,
+          `hotSpares[${i}]`,
+          knownPoolNames,
+          settings.placementPools ?? [],
+          ctx
+        );
+      });
+    }
+  }
+
+  return errors;
+}
+
+function validatePool(
+  pool: PlacementPool,
+  path: string,
+  knownPoolNames: Set<string>,
+  ctx: Ctx
+): void {
+  if (typeof pool.name !== "string" || pool.name.length === 0) {
+    ctx.add("invalidType", `${path}.name`, "must be a non-empty string");
+  } else if (knownPoolNames.has(pool.name)) {
+    ctx.add(
+      "duplicatePool",
+      `${path}.name`,
+      `duplicate pool name "${pool.name}"`
+    );
+  } else {
+    knownPoolNames.add(pool.name);
+  }
+  if (!Array.isArray(pool.tiers) || pool.tiers.length === 0) {
+    ctx.add(
+      "incompatibleConfig",
+      `${path}.tiers`,
+      `pool needs at least one tier`
+    );
+    return;
+  }
+  const tierNames = new Set<string>();
+  let fixedTierCount = 0;
+  pool.tiers.forEach((tier, i) => {
+    const tp = `${path}.tiers[${i}]`;
+    if (typeof tier.name !== "string" || tier.name.length === 0) {
+      ctx.add("invalidType", `${tp}.name`, "must be a non-empty string");
+    } else if (tierNames.has(tier.name)) {
+      ctx.add("duplicatePool", `${tp}.name`, `duplicate tier name "${tier.name}"`);
+    } else {
+      tierNames.add(tier.name);
+    }
+    if (tier.scaleOut === "fixed") fixedTierCount++;
+    validateTier(tier, tp, ctx);
+  });
+  // nodeMatchesTier maps an untagged (pre-registered cluster) node to the
+  // pool's fixed tier, so that mapping must be unambiguous.
+  if (fixedTierCount > 1) {
+    ctx.add(
+      "incompatibleConfig",
+      `${path}.tiers`,
+      `pool may have at most one "fixed" tier (found ${fixedTierCount})`
+    );
+  }
+}
+
+function validateTier(
+  tier: PlacementPool["tiers"][number],
+  path: string,
+  ctx: Ctx
+): void {
+  if (!["aws", "oci", "local-servers"].includes(tier.kind)) {
+    ctx.add(
+      "invalidEnumValue",
+      `${path}.kind`,
+      `must be one of "aws" | "oci" | "local-servers"`
+    );
+  }
+  if (!["binpack", "spread"].includes(tier.packingStrategy)) {
+    ctx.add(
+      "invalidEnumValue",
+      `${path}.packingStrategy`,
+      `must be "binpack" or "spread"`
+    );
+  }
+  if (!["elastic", "fixed"].includes(tier.scaleOut)) {
+    ctx.add(
+      "invalidEnumValue",
+      `${path}.scaleOut`,
+      `must be "elastic" or "fixed"`
+    );
+  }
+  if (tier.kind === "local-servers" && tier.scaleOut === "elastic") {
+    ctx.add(
+      "incompatibleConfig",
+      `${path}`,
+      `cluster tiers cannot be "elastic" (no auto-scale)`
+    );
+  }
+  if (!Array.isArray(tier.candidateInstanceTypes)) {
+    ctx.add(
+      "invalidType",
+      `${path}.candidateInstanceTypes`,
+      "must be an array"
+    );
+  } else {
+    if (tier.scaleOut === "elastic" && tier.candidateInstanceTypes.length === 0) {
+      ctx.add(
+        "incompatibleConfig",
+        `${path}.candidateInstanceTypes`,
+        `elastic tier needs at least one candidate instance type`
+      );
+    }
+    tier.candidateInstanceTypes.forEach((c, i) => {
+      const p = `${path}.candidateInstanceTypes[${i}]`;
+      if (typeof c.instanceType !== "string" || c.instanceType.length === 0) {
+        ctx.add("invalidType", `${p}.instanceType`, "must be non-empty string");
+      }
+      if (typeof c.totalCapacity !== "number" || c.totalCapacity <= 0) {
+        ctx.add("outOfRange", `${p}.totalCapacity`, "must be > 0");
+      }
+      if (
+        typeof c.totalCores !== "number" ||
+        c.totalCores <= 0 ||
+        !Number.isInteger(c.totalCores)
+      ) {
+        ctx.add("outOfRange", `${p}.totalCores`, "must be a positive integer");
+      }
+    });
+  }
+}
+
+function validateBandConfig(
+  bands: BandConfig,
+  path: string,
+  ctx: Ctx
+): void {
+  if (bands.gold) {
+    if (bands.gold.onFailure !== "restart") {
+      ctx.add(
+        "invalidEnumValue",
+        `${path}.gold.onFailure`,
+        `must be "restart"`
+      );
+    }
+    if (!["preferHotSpare", "any"].includes(bands.gold.restartPlacement)) {
+      ctx.add(
+        "invalidEnumValue",
+        `${path}.gold.restartPlacement`,
+        `must be "preferHotSpare" or "any"`
+      );
+    }
+    ctx.checkOptionalPositive(
+      bands.gold.maxRestartsPerHour,
+      `${path}.gold.maxRestartsPerHour`
+    );
+  }
+  if (bands.silver) {
+    if (bands.silver.onFailure !== "restart") {
+      ctx.add(
+        "invalidEnumValue",
+        `${path}.silver.onFailure`,
+        `must be "restart"`
+      );
+    }
+    if (bands.silver.restartPlacement !== "any") {
+      ctx.add(
+        "invalidEnumValue",
+        `${path}.silver.restartPlacement`,
+        `must be "any"`
+      );
+    }
+    ctx.checkOptionalPositive(
+      bands.silver.maxRestartsPerHour,
+      `${path}.silver.maxRestartsPerHour`
+    );
+  }
+  if (bands.bronze) {
+    if (bands.bronze.onFailure !== "drop") {
+      ctx.add(
+        "invalidEnumValue",
+        `${path}.bronze.onFailure`,
+        `must be "drop"`
+      );
+    }
+  }
+}
+
+function validatePlacementConfig(
+  cfg: PlacementConfig,
+  path: string,
+  ctx: Ctx
+): void {
+  ctx.checkOptionalPositive(cfg.rejectionBackoffMs, `${path}.rejectionBackoffMs`);
+  ctx.checkOptionalPositive(
+    cfg.rejectionEscalationCount,
+    `${path}.rejectionEscalationCount`
+  );
+  ctx.checkOptionalPositive(cfg.failureBackoffMs, `${path}.failureBackoffMs`);
+  ctx.checkOptionalPositive(cfg.jobStartupGraceMs, `${path}.jobStartupGraceMs`);
+}
+
+function validateHotSpare(
+  cfg: HotSpareConfig,
+  path: string,
+  knownPoolNames: Set<string>,
+  placementPools: PlacementPool[],
+  ctx: Ctx
+): void {
+  if (typeof cfg.pool !== "string" || cfg.pool.length === 0) {
+    ctx.add("invalidType", `${path}.pool`, "must be a non-empty string");
+  } else if (!knownPoolNames.has(cfg.pool)) {
+    ctx.add(
+      "unknownPool",
+      `${path}.pool`,
+      `pool "${cfg.pool}" is not declared in placementPools`
+    );
+  }
+  if (
+    typeof cfg.targetCount !== "number" ||
+    cfg.targetCount < 0 ||
+    !Number.isInteger(cfg.targetCount)
+  ) {
+    ctx.add(
+      "outOfRange",
+      `${path}.targetCount`,
+      `must be a non-negative integer (got ${cfg.targetCount})`
+    );
+  }
+  if (cfg.forBand !== undefined && !["gold", "silver", "bronze"].includes(cfg.forBand)) {
+    ctx.add(
+      "invalidEnumValue",
+      `${path}.forBand`,
+      `must be "gold" | "silver" | "bronze"`
+    );
+  }
+  if (cfg.spec === undefined || typeof cfg.spec !== "object") {
+    ctx.add("missingRequired", `${path}.spec`, "spec is required");
+    return;
+  }
+  // A pool with an elastic tier needs an instance type to provision against.
+  const pool = placementPools.find((p) => p.name === cfg.pool);
+  if (
+    pool &&
+    pool.tiers.some((t) => t.scaleOut === "elastic") &&
+    !cfg.spec.instanceType
+  ) {
+    ctx.add(
+      "missingRequired",
+      `${path}.spec.instanceType`,
+      `elastic pool spares require spec.instanceType`
+    );
+  }
+}
+
+class Ctx {
+  constructor(private readonly errors: SettingsValidationError[]) {}
+
+  add(code: SettingsValidationErrorCode, path: string, message: string): void {
+    this.errors.push({ code, path, message });
+  }
+
+  checkPositive(value: number, path: string): void {
+    if (typeof value !== "number" || value <= 0) {
+      this.add(
+        "outOfRange",
+        path,
+        `must be a positive number (got ${value})`
+      );
+    }
+  }
+
+  checkOptionalPositive(value: number | undefined, path: string): void {
+    if (value === undefined) return;
+    if (typeof value !== "number" || value <= 0) {
+      this.add(
+        "outOfRange",
+        path,
+        `must be a positive number when set (got ${value})`
+      );
+    }
+  }
+}
+
+/**
+ * Thrown by `AutoManager.run` when `validateAutoSettings` finds
+ * configuration errors. The `.errors` property carries the structured
+ * details; `.message` contains a human-readable summary.
+ *
+ * @public
+ */
+export class AutoSettingsValidationError extends Error {
+  constructor(public readonly errors: SettingsValidationError[]) {
+    super(
+      `AutoSettings validation failed (${errors.length} error${
+        errors.length === 1 ? "" : "s"
+      }):\n  ` +
+        errors.map((e) => `${e.path}: ${e.message}`).join("\n  ")
+    );
+    this.name = "AutoSettingsValidationError";
+  }
+}