@norskvideo/norsk-auto-manager 0.1.0

package/src/clock.ts

@@ -0,0 +1,29 @@
+// Clock abstraction so AutoManager can be tested deterministically.
+// Production code uses RealClock; tests inject a MockClock that exposes
+// advanceTime() to drive timers manually.
+
+export interface CancellableTimer {
+  cancel(): void;
+}
+
+export interface Clock {
+  now(): Date;
+  setTimeout(fn: () => void, ms: number): CancellableTimer;
+  setInterval(fn: () => void, ms: number): CancellableTimer;
+}
+
+export class RealClock implements Clock {
+  public now(): Date {
+    return new Date();
+  }
+
+  public setTimeout(fn: () => void, ms: number): CancellableTimer {
+    const handle = setTimeout(fn, ms);
+    return { cancel: () => clearTimeout(handle) };
+  }
+
+  public setInterval(fn: () => void, ms: number): CancellableTimer {
+    const handle = setInterval(fn, ms);
+    return { cancel: () => clearInterval(handle) };
+  }
+}

package/src/conversions.ts

@@ -0,0 +1,458 @@
+// PB ↔ AutoManager-typed conversions. The SDK passes raw protobuf
+// payloads through for the new AutoManager events; AutoManager runs
+// these converters at the boundary so the rest of the codebase works
+// against the cleaner typed shapes from `./types`.
+//
+// Converters are deliberately permissive about defaults: an empty map
+// from PB becomes `undefined` to match the optional-field convention
+// used in the typed model, an absent ID wrapper stays the empty string.
+
+import { create } from "@bufbuild/protobuf";
+import { timestampDate, timestampFromDate } from "@bufbuild/protobuf/wkt";
+import * as ManagerPB from "@norskvideo/norsk-api/lib/manager_pb";
+import * as CommonPB from "@norskvideo/norsk-api/lib/shared/common_pb";
+import {
+  BundleIdSchema,
+  CapabilityRequirementSchema,
+  CapabilitySchema,
+  OptionalIntSchema,
+  OptionalStringSchema,
+} from "@norskvideo/norsk-api/lib/shared/common_pb";
+import { fromProductTemplateRef, toProductTemplateRef } from "@norskvideo/norsk-manager-sdk";
+import { JobSchema as PbJobSchema } from "@norskvideo/norsk-api/lib/manager_pb";
+import {
+  Bundle,
+  BundleId,
+  BundleJobSpec,
+  BundleState,
+  Capability,
+  CapabilityRequirement,
+  AntiAffinity,
+  GpuResource,
+  IntraReplicaRules,
+  JobRequirements,
+  LaunchSpec,
+  NodeAssignedJob,
+  NodeInventory,
+  PriorityBand,
+  ResiliencePolicy,
+} from "./types";
+
+// ----- enums -----------------------------------------------------------
+
+export function fromPbPriorityBand(pb: ManagerPB.PriorityBand): PriorityBand {
+  switch (pb) {
+    case ManagerPB.PriorityBand.GOLD:
+      return "gold";
+    case ManagerPB.PriorityBand.SILVER:
+      return "silver";
+    case ManagerPB.PriorityBand.BRONZE:
+      return "bronze";
+  }
+}
+
+export function fromPbPlacementRule(
+  pb: ManagerPB.PlacementRule
+): "off" | "soft" | "hard" {
+  switch (pb) {
+    case ManagerPB.PlacementRule.OFF:
+      return "off";
+    case ManagerPB.PlacementRule.SOFT:
+      return "soft";
+    case ManagerPB.PlacementRule.HARD:
+      return "hard";
+  }
+}
+
+// ----- capabilities ----------------------------------------------------
+
+export function fromPbCapability(pb: CommonPB.Capability): Capability {
+  return {
+    name: pb.name,
+    count: pb.count,
+    attributes: emptyMapToUndefined(pb.attributes),
+  };
+}
+
+export function fromPbCapabilityRequirement(
+  pb: CommonPB.CapabilityRequirement
+): CapabilityRequirement {
+  return {
+    name: pb.name,
+    count: pb.count,
+    attributeMatches: emptyMapToUndefined(pb.attributeMatches),
+  };
+}
+
+// ----- GPU -------------------------------------------------------------
+
+export function fromPbGpuResource(pb: CommonPB.GpuResource): GpuResource {
+  return {
+    index: pb.index,
+    model: pb.model?.value,
+    totalCapacity: pb.totalCapacity,
+    reservedCapacity: pb.reservedCapacity,
+    exclusivelyReserved: pb.exclusivelyReserved,
+  };
+}
+
+// ----- requirements ----------------------------------------------------
+
+export function fromPbJobRequirements(
+  pb: ManagerPB.JobRequirements
+): JobRequirements {
+  return {
+    requiredCapacity: pb.requiredCapacity,
+    requiredCores: pb.requiredCores?.value,
+    requiredGpuCapacity: pb.requiredGpuCapacity?.value,
+    requiredGpuModel: pb.requiredGpuModel?.value,
+    requiredCapabilities: pb.requiredCapabilities.map(fromPbCapabilityRequirement),
+    priorityBand: fromPbPriorityBand(pb.priorityBand),
+  };
+}
+
+// ----- bundle ----------------------------------------------------------
+
+export function fromPbBundle(pb: ManagerPB.Bundle): Bundle {
+  return {
+    bundleId: bundleIdString(pb.bundleId),
+    pool: pb.pool,
+    jobs: pb.jobs.map(fromPbBundleJobSpec),
+    intraReplicaPlacement: pb.intraReplicaPlacement
+      ? fromPbIntraReplicaRules(pb.intraReplicaPlacement)
+      : undefined,
+    resiliencePolicy: pb.resiliencePolicy ? fromPbResiliencePolicy(pb.resiliencePolicy) : undefined,
+    state: fromPbBundleState(pb.state),
+  };
+}
+
+export function fromPbBundleState(pb: ManagerPB.BundleState): BundleState {
+  switch (pb) {
+    case ManagerPB.BundleState.DELETING:
+      return "deleting";
+    default:
+      return "live";
+  }
+}
+
+export function toPbBundleState(s: BundleState): ManagerPB.BundleState {
+  switch (s) {
+    case "deleting":
+      return ManagerPB.BundleState.DELETING;
+    case "live":
+      return ManagerPB.BundleState.LIVE;
+  }
+}
+
+export function fromPbBundleJobSpec(
+  pb: ManagerPB.BundleJobSpec
+): BundleJobSpec {
+  return {
+    jobName: pb.jobName,
+    requirements: pb.requirements
+      ? fromPbJobRequirements(pb.requirements)
+      : ({} as JobRequirements),
+    coLocateWith: emptyArrayToUndefined(pb.coLocateWith),
+    separateFrom: emptyArrayToUndefined(pb.separateFrom),
+    launch: pb.job ? fromPbLaunchSpec(pb.job) : undefined,
+  };
+}
+
+/**
+ * Reconstruct the typed `LaunchSpec` from the wire-form `Job` carried
+ * on a `BundleJobSpec`. If the carried Job has `productTemplate` set, this
+ * is a product-template launch; otherwise it's the legacy services/volumes
+ * path. The legacy variant passes the Job through as-is (cast to the
+ * SDK's typed shape — same trick the v0 code used).
+ */
+/** Tags starting with this prefix are SDK-managed (well-known reserved
+ *  names) — `__stopDateTime` carries the auto-stop instant for example.
+ *  Callers can't set them via `LaunchSpec.tags` (silently stripped on
+ *  outbound) and they're surfaced as typed fields rather than raw tags
+ *  on inbound. */
+export const RESERVED_TAG_PREFIX = "__";
+/** Well-known reserved tag carrying the operator's submitted auto-stop
+ *  instant. The daemon has no first-class concept of stop time, so we
+ *  ride along on its tag-preservation behaviour. */
+export const STOP_DATE_TIME_TAG = "__stopDateTime";
+
+function buildJobTags(
+  stopDateTime: Date | undefined,
+  userTags: Record<string, string> | undefined,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (userTags) {
+    for (const [k, v] of Object.entries(userTags)) {
+      if (k.startsWith(RESERVED_TAG_PREFIX)) continue; // silently strip
+      out[k] = v;
+    }
+  }
+  if (stopDateTime) out[STOP_DATE_TIME_TAG] = stopDateTime.toISOString();
+  return out;
+}
+
+function splitJobTags(tags: Record<string, string>): {
+  stopDateTime?: Date;
+  userTags?: Record<string, string>;
+} {
+  const userTags: Record<string, string> = {};
+  let stopDateTime: Date | undefined;
+  for (const [k, v] of Object.entries(tags)) {
+    if (k === STOP_DATE_TIME_TAG) {
+      const d = new Date(v);
+      if (!Number.isNaN(d.getTime())) stopDateTime = d;
+      continue;
+    }
+    if (k.startsWith(RESERVED_TAG_PREFIX)) continue; // unknown reserved — hide
+    userTags[k] = v;
+  }
+  return {
+    ...(stopDateTime ? { stopDateTime } : {}),
+    ...(Object.keys(userTags).length > 0 ? { userTags } : {}),
+  };
+}
+
+export function fromPbLaunchSpec(pbJob: ManagerPB.Job): LaunchSpec {
+  if (pbJob.productTemplate) {
+    const { stopDateTime, userTags } = splitJobTags(pbJob.tags ?? {});
+    return {
+      kind: "productTemplate",
+      ref: fromProductTemplateRef(pbJob.productTemplate),
+      parameters:
+        Object.keys(pbJob.productTemplateParameters).length > 0
+          ? pbJob.productTemplateParameters
+          : undefined,
+      // Preserve the operator's submitted schedule so consumers can
+      // surface it even before a JobPending event has been streamed
+      // (e.g. bundles in mgr's bundleMap whose materialised jobs
+      // haven't arrived yet — calendar view depends on this).
+      ...(pbJob.startDateTime ? { startDateTime: timestampDate(pbJob.startDateTime) } : {}),
+      ...(stopDateTime ? { stopDateTime } : {}),
+      ...(userTags ? { tags: userTags } : {}),
+    };
+  }
+  return { kind: "legacy", job: pbJob as never };
+}
+
+export function fromPbIntraReplicaRules(
+  pb: ManagerPB.IntraReplicaRules
+): IntraReplicaRules {
+  return {
+    sameNodeDefault: pb.sameNodeDefault,
+    sameAz: fromPbPlacementRule(pb.sameAz),
+  };
+}
+
+export function fromPbResiliencePolicy(pb: ManagerPB.ResiliencePolicy): ResiliencePolicy {
+  return {
+    ...(pb.pool.length > 0 ? { pool: pb.pool } : {}),
+    sameNode: fromPbAntiAffinity(pb.sameNode),
+    sameAz: fromPbAntiAffinity(pb.sameAz),
+    sameCloud: fromPbAntiAffinity(pb.sameCloud),
+  };
+}
+
+function fromPbAntiAffinity(pb: ManagerPB.AntiAffinity): AntiAffinity {
+  return pb === ManagerPB.AntiAffinity.FORBID ? "forbid" : "allow";
+}
+
+function toPbAntiAffinity(a: AntiAffinity): ManagerPB.AntiAffinity {
+  return a === "forbid" ? ManagerPB.AntiAffinity.FORBID : ManagerPB.AntiAffinity.ALLOW;
+}
+
+// ----- inventory -------------------------------------------------------
+
+export function fromPbNodeInventory(
+  pb: CommonPB.NodeInventory
+): NodeInventory {
+  return {
+    totalCapacity: pb.totalCapacity,
+    utilizationCap: pb.utilizationCap,
+    totalCores: pb.totalCores,
+    gpus: pb.gpus.map(fromPbGpuResource),
+    capabilities: pb.capabilities.map(fromPbCapability),
+    reservedCapacity: pb.reservedCapacity,
+    reservedCores: pb.reservedCores,
+    reservedCapabilities: pb.reservedCapabilities.map(fromPbCapability),
+    reachable: pb.reachable,
+    lastSeen: pb.lastSeen
+      ? new Date(Number(pb.lastSeen.seconds) * 1000 + (pb.lastSeen.nanos ?? 0) / 1_000_000)
+      : new Date(0),
+    cordoned: pb.cordoned,
+    assignedJobs: pb.assignedJobs.map(fromPbNodeAssignedJob),
+  };
+}
+
+export function fromPbNodeAssignedJob(
+  pb: CommonPB.NodeAssignedJob
+): NodeAssignedJob {
+  return {
+    jobId: jobIdString(pb.jobId),
+    coreSet: pb.coreSet.length > 0 ? [...pb.coreSet] : undefined,
+    gpuIndex: pb.gpuIndex?.value,
+  };
+}
+
+// ----- helpers ---------------------------------------------------------
+
+function bundleIdString(pb?: { bundleId: string }): BundleId {
+  return pb?.bundleId ?? "";
+}
+
+function jobIdString(pb?: { jobId: string }): string {
+  return pb?.jobId ?? "";
+}
+
+function emptyMapToUndefined<V>(
+  m: Record<string, V>
+): Record<string, V> | undefined {
+  return Object.keys(m).length > 0 ? { ...m } : undefined;
+}
+
+function emptyArrayToUndefined<V>(arr: V[]): V[] | undefined {
+  return arr.length > 0 ? [...arr] : undefined;
+}
+
+// =============================================================================
+// AutoManager-typed → PB conversions. Used when AutoManager submits a Bundle
+// (or future request types) over the wire.
+// =============================================================================
+
+import {
+  BundleSchema,
+  BundleJobSpecSchema,
+  IntraReplicaRulesSchema,
+  ResiliencePolicySchema,
+  JobRequirementsSchema,
+  PlacementRule,
+  PriorityBand as PbPriorityBand,
+} from "@norskvideo/norsk-api/lib/manager_pb";
+import { OptionalFloatSchema } from "@norskvideo/norsk-api/lib/shared/common_pb";
+
+export function toPbPriorityBand(b: PriorityBand): PbPriorityBand {
+  switch (b) {
+    case "gold":
+      return PbPriorityBand.GOLD;
+    case "silver":
+      return PbPriorityBand.SILVER;
+    case "bronze":
+      return PbPriorityBand.BRONZE;
+  }
+}
+
+export function toPbPlacementRule(r: "off" | "soft" | "hard"): PlacementRule {
+  switch (r) {
+    case "off":
+      return PlacementRule.OFF;
+    case "soft":
+      return PlacementRule.SOFT;
+    case "hard":
+      return PlacementRule.HARD;
+  }
+}
+
+export function toPbCapability(c: Capability): CommonPB.Capability {
+  return create(CapabilitySchema, {
+    name: c.name,
+    count: c.count,
+    attributes: c.attributes ?? {},
+  });
+}
+
+export function toPbCapabilityRequirement(
+  r: CapabilityRequirement
+): CommonPB.CapabilityRequirement {
+  return create(CapabilityRequirementSchema, {
+    name: r.name,
+    count: r.count,
+    attributeMatches: r.attributeMatches ?? {},
+  });
+}
+
+export function toPbJobRequirements(
+  r: JobRequirements
+): ManagerPB.JobRequirements {
+  return create(JobRequirementsSchema, {
+    requiredCapacity: r.requiredCapacity,
+    requiredCores:
+      r.requiredCores !== undefined
+        ? create(OptionalIntSchema, { value: r.requiredCores })
+        : undefined,
+    requiredGpuCapacity:
+      r.requiredGpuCapacity !== undefined
+        ? create(OptionalFloatSchema, { value: r.requiredGpuCapacity })
+        : undefined,
+    requiredGpuModel:
+      r.requiredGpuModel !== undefined
+        ? create(OptionalStringSchema, { value: r.requiredGpuModel })
+        : undefined,
+    requiredCapabilities: r.requiredCapabilities.map(toPbCapabilityRequirement),
+    priorityBand: toPbPriorityBand(r.priorityBand),
+  });
+}
+
+export function toPbBundleJobSpec(j: BundleJobSpec): ManagerPB.BundleJobSpec {
+  return create(BundleJobSpecSchema, {
+    jobName: j.jobName,
+    requirements: toPbJobRequirements(j.requirements),
+    coLocateWith: j.coLocateWith ?? [],
+    separateFrom: j.separateFrom ?? [],
+    job: j.launch ? toPbLaunchSpec(j.launch) : undefined,
+  });
+}
+
+/**
+ * Project a typed `LaunchSpec` into the wire-form `Job` slot on
+ * `BundleJobSpec`. Manager stamps this template per replica during
+ * bundle expansion (setting jobId, tags, state, currentHash). For the
+ * product-template variant only `productTemplate`, `productTemplateParameters`, and
+ * `startDateTime` are meaningful — the rest stays at proto defaults.
+ * The worker reads `productTemplate` + `productTemplateParameters` and ignores
+ * services / volumes / writeFiles.
+ *
+ * `startDateTime` defaults to `new Date()` (immediate) when callers
+ * omit it; Manager-daemon's `apiToJobTemplate` rejects unset values.
+ */
+export function toPbLaunchSpec(launch: LaunchSpec): ManagerPB.Job {
+  if (launch.kind === "productTemplate") {
+    const tags = buildJobTags(launch.stopDateTime, launch.tags);
+    return create(PbJobSchema, {
+      startDateTime: timestampFromDate(launch.startDateTime ?? new Date()),
+      productTemplate: toProductTemplateRef(launch.ref),
+      productTemplateParameters: launch.parameters ?? {},
+      ...(Object.keys(tags).length > 0 ? { tags } : {}),
+    });
+  }
+  return launch.job as never;
+}
+
+export function toPbIntraReplicaRules(
+  r: IntraReplicaRules
+): ManagerPB.IntraReplicaRules {
+  return create(IntraReplicaRulesSchema, {
+    sameNodeDefault: r.sameNodeDefault,
+    sameAz: toPbPlacementRule(r.sameAz),
+  });
+}
+
+export function toPbResiliencePolicy(r: ResiliencePolicy): ManagerPB.ResiliencePolicy {
+  return create(ResiliencePolicySchema, {
+    pool: r.pool ?? "",
+    sameNode: toPbAntiAffinity(r.sameNode),
+    sameAz: toPbAntiAffinity(r.sameAz),
+    sameCloud: toPbAntiAffinity(r.sameCloud),
+  });
+}
+
+export function toPbBundle(b: Bundle): ManagerPB.Bundle {
+  return create(BundleSchema, {
+    bundleId: create(BundleIdSchema, { bundleId: b.bundleId }),
+    pool: b.pool,
+    jobs: b.jobs.map(toPbBundleJobSpec),
+    intraReplicaPlacement: b.intraReplicaPlacement
+      ? toPbIntraReplicaRules(b.intraReplicaPlacement)
+      : undefined,
+    resiliencePolicy: b.resiliencePolicy ? toPbResiliencePolicy(b.resiliencePolicy) : undefined,
+    state: toPbBundleState(b.state ?? "live"),
+  });
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// Public exports for @norskvideo/norsk-auto-manager.
+export * from "./automanager";
+export * from "./types";
+export { Clock, RealClock, CancellableTimer } from "./clock";
+export { KnownCapabilities, KnownCapabilityName } from "./knownCapabilities";
+export {
+  validateBundle,
+  ValidationError,
+  ValidationErrorCode,
+  ValidationResult,
+  PoolDescriptor,
+  NodeProfile,
+} from "./validation";
+export * from "./placement";
+export {
+  freeCapability,
+  freeCapacity,
+  freeCores,
+  findCapability,
+  usedCapacityFraction,
+} from "./inventory";
+export {
+  AutoSettingsValidationError,
+  SettingsValidationError,
+  SettingsValidationErrorCode,
+  validateAutoSettings,
+} from "./settingsValidation";

package/src/inventory.ts

@@ -0,0 +1,64 @@
+// Derivation helpers over NodeInventory snapshots. These are pure
+// projections — no state of their own — so the placement algorithm can
+// remain a pure function over what the worker advertised.
+
+import { Capability, NodeInventory } from "./types";
+
+/**
+ * Free capacity available for placement. `(totalCapacity * utilizationCap)
+ * - reservedCapacity`. Can be negative if the node is over-allocated;
+ * placement should treat negative values as "no room".
+ *
+ * @public
+ */
+export function freeCapacity(inv: NodeInventory): number {
+  return inv.totalCapacity * inv.utilizationCap - inv.reservedCapacity;
+}
+
+/** @public */
+export function freeCores(inv: NodeInventory): number {
+  return inv.totalCores - inv.reservedCores;
+}
+
+/**
+ * Fraction (0-1) of the node's total capacity currently reserved.
+ * Used by the bin-pack scoring strategy.
+ *
+ * @public
+ */
+export function usedCapacityFraction(inv: NodeInventory): number {
+  if (inv.totalCapacity <= 0) return 0;
+  return inv.reservedCapacity / inv.totalCapacity;
+}
+
+/**
+ * Free count of a specific capability on this node. Looks up the total
+ * by name and subtracts whatever's currently reserved. Returns 0 if the
+ * capability isn't advertised.
+ *
+ * @public
+ */
+export function freeCapability(inv: NodeInventory, name: string): number {
+  const total = capabilityCount(inv.capabilities, name);
+  const used = capabilityCount(inv.reservedCapabilities, name);
+  return Math.max(0, total - used);
+}
+
+/**
+ * Find the advertised capability with the given name. Returns undefined
+ * if not present. Useful when callers also need attribute info.
+ *
+ * @public
+ */
+export function findCapability(
+  inv: NodeInventory,
+  name: string
+): Capability | undefined {
+  return inv.capabilities.find((c) => c.name === name);
+}
+
+function capabilityCount(caps: Capability[], name: string): number {
+  let total = 0;
+  for (const c of caps) if (c.name === name) total += c.count;
+  return total;
+}

package/src/knownCapabilities.ts

@@ -0,0 +1,23 @@
+// Standard capability names shipped with Norsk. Use these constants
+// rather than literal strings — typos in user code surface at compile
+// time rather than as silent placement misses.
+
+/** @public */
+export const KnownCapabilities = {
+  /** Whole NVIDIA GPU, exclusive. For fractional, use requiredGpuCapacity. */
+  NvidiaGpu: "norsk.io/nvidia-gpu",
+  /** Intel Quick Sync Video — fixed-function media accelerator. */
+  IntelQsv: "norsk.io/intel-qsv",
+  /** Netint Quadra T1U accelerator. */
+  Quadra: "norsk.io/quadra",
+  /** Blackmagic DeckLink capture/playout card. */
+  Decklink: "norsk.io/decklink",
+  /** SMPTE ST 2110 capable NIC. */
+  St2110Nic: "norsk.io/st2110-nic",
+  /** Media eXchange Layer slot, provided by an MXL bridge NodeService. */
+  Mxl: "norsk.io/mxl",
+} as const;
+
+/** @public */
+export type KnownCapabilityName =
+  (typeof KnownCapabilities)[keyof typeof KnownCapabilities];