@norskvideo/norsk-auto-manager 0.1.0

package/lib/src/settingsValidation.js

@@ -0,0 +1,232 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutoSettingsValidationError = void 0;
+exports.validateAutoSettings = validateAutoSettings;
+/**
+ * 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
+ */
+function validateAutoSettings(settings) {
+    const errors = [];
+    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();
+    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, path, knownPoolNames, ctx) {
+    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();
+    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, path, ctx) {
+    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, path, ctx) {
+    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, path, ctx) {
+    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, path, knownPoolNames, placementPools, ctx) {
+    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(errors) {
+        this.errors = errors;
+    }
+    add(code, path, message) {
+        this.errors.push({ code, path, message });
+    }
+    checkPositive(value, path) {
+        if (typeof value !== "number" || value <= 0) {
+            this.add("outOfRange", path, `must be a positive number (got ${value})`);
+        }
+    }
+    checkOptionalPositive(value, path) {
+        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
+ */
+class AutoSettingsValidationError extends Error {
+    constructor(errors) {
+        super(`AutoSettings validation failed (${errors.length} error${errors.length === 1 ? "" : "s"}):\n  ` +
+            errors.map((e) => `${e.path}: ${e.message}`).join("\n  "));
+        this.errors = errors;
+        this.name = "AutoSettingsValidationError";
+    }
+}
+exports.AutoSettingsValidationError = AutoSettingsValidationError;
+//# sourceMappingURL=settingsValidation.js.map

package/lib/src/shared/utils.d.ts

@@ -0,0 +1,17 @@
+/** @public */
+export declare function norskHost(): string;
+/** @public */
+export declare function norskPort(): string;
+/** @public */
+export declare function publicUrlPrefix(): string;
+/** @public */
+export declare function debugUrlPrefix(): string;
+/** @public */
+export declare function clientHostExternal(): string;
+/** @public */
+export declare function clientPortExternal(): string;
+/** @public */
+export declare function clientHostInternal(): string;
+/** @public */
+export declare function clientPortInternal(): string;
+//# sourceMappingURL=utils.d.ts.map

package/lib/src/shared/utils.js

@@ -0,0 +1,220 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrapEither = exports.isRight = exports.isLeft = exports.makeRight = exports.makeLeft = void 0;
+exports.provideFull = provideFull;
+exports.exhaustiveCheck = exhaustiveCheck;
+exports.mkCase = mkCase;
+exports.mkMessageCase = mkMessageCase;
+exports.mapOptional = mapOptional;
+exports.debuglog = debuglog;
+exports.errorlog = errorlog;
+exports.invokeOnCreate = invokeOnCreate;
+exports.mandatory = mandatory;
+exports.norskHost = norskHost;
+exports.norskPort = norskPort;
+exports.publicUrlPrefix = publicUrlPrefix;
+exports.debugUrlPrefix = debugUrlPrefix;
+exports.clientHostExternal = clientHostExternal;
+exports.clientPortExternal = clientPortExternal;
+exports.clientHostInternal = clientHostInternal;
+exports.clientPortInternal = clientPortInternal;
+const util = __importStar(require("util"));
+const protobuf_1 = require("@bufbuild/protobuf");
+/**
+ * @internal
+ *
+ * Ask TypeScript to tell us when we've left the fields out of a message.
+ *
+ * Usage:
+ *   provideFull(MyProtobufMessageSchema, { myField })
+ * instead of
+ *   create(MyProtobufMessageSchema, { myField })
+ */
+function provideFull(schema, v) {
+    // This no longer does it's job I'm just trying to compile as a first step
+    return (0, protobuf_1.create)(schema, v);
+}
+/** @internal
+ *
+ * unreachable
+ */
+function exhaustiveCheck(a) {
+    throw new Error(`Unhandled case: ${a}`);
+}
+/** @internal */
+function mkCase(obj) {
+    const keys = Object.keys(obj);
+    if (keys.length !== 1)
+        throw new Error("Bad case");
+    return { case: keys[0], value: obj[keys[0]] };
+}
+/** @internal */
+function mkMessageCase(obj) {
+    return { message: mkCase(obj) };
+}
+/** @internal */
+function mapOptional(fn, value) {
+    return value !== undefined ? fn(value) : undefined;
+}
+/** @internal */
+function debuglog(msg, ...param) {
+    util.debuglog("norsk")(util.formatWithOptions({ maxArrayLength: null, depth: null, colors: true }, "[" + new Date().toISOString() + "] " + msg, ...param));
+}
+/** @internal */
+function errorlog(msg, ...param) {
+    util.debuglog("norsk")(util.formatWithOptions({ maxArrayLength: null, depth: null, colors: true }, "[" + new Date().toISOString() + "] " + msg, ...param));
+}
+/**
+ * @internal
+ * Invoke a node's `onCreate` callback, warning loudly if it returned a Promise.
+ *
+ * `onCreate` MUST be synchronous (its declared type is `(node) => void`). Frames
+ * flow as soon as it returns, so an `async` onCreate doesn't block them — it
+ * suspends at its first `await` and the SDK proceeds, meaning any subscriptions
+ * set up after that `await` race the node's first frames. This catches the
+ * `async`-onCreate footgun at runtime for both TypeScript and plain-JS clients
+ * (no lint or type-checking required), at the cost of one `typeof` per node.
+ */
+function invokeOnCreate(onCreate, node) {
+    if (!onCreate)
+        return;
+    const result = onCreate(node);
+    if (result != null && typeof result.then === "function") {
+        // console.warn (not the NODE_DEBUG-gated errorlog) so this is always visible —
+        // the whole point is to surface the footgun without any opt-in.
+        console.warn("[norsk-sdk] onCreate for node '%s' returned a Promise — onCreate must be SYNCHRONOUS (was it declared `async`?). " +
+            "Frames flow as soon as onCreate returns, so an async onCreate does NOT block them, and any subscriptions " +
+            "set up after an `await` will race the node's first frames. Do subscription setup synchronously in onCreate.", node?.id ?? "<unknown>");
+    }
+}
+/** @internal */
+function mandatory(value, name) {
+    if (value !== undefined) {
+        return value;
+    }
+    else {
+        if (name === undefined) {
+            throw new Error();
+        }
+        else {
+            throw new Error(`Mandatory variable '${name}' is undefined`);
+        }
+    }
+}
+/** @internal */
+const makeLeft = (value) => ({ left: value });
+exports.makeLeft = makeLeft;
+/** @internal */
+const makeRight = (value) => ({ right: value });
+exports.makeRight = makeRight;
+/** @internal */
+const isLeft = (e) => {
+    return e.left !== undefined;
+};
+exports.isLeft = isLeft;
+/** @internal */
+const isRight = (e) => {
+    return e.right !== undefined;
+};
+exports.isRight = isRight;
+/** @internal */
+const unwrapEither = ({ left, right, }) => {
+    if (right !== undefined && left !== undefined) {
+        throw new Error(`Received both left and right values at runtime when opening an Either\nLeft: ${JSON.stringify(left)}\nRight: ${JSON.stringify(right)}`);
+        /*
+         We're throwing in this function because this can only occur at runtime if something
+         happens that the TypeScript compiler couldn't anticipate. That means the application
+         is in an unexpected state and we should terminate immediately.
+        */
+    }
+    if (left !== undefined) {
+        return left; // Typescript is getting confused and returning this type as `T | undefined` unless we add the type assertion
+    }
+    if (right !== undefined) {
+        return right;
+    }
+    throw new Error(`Received no left or right values at runtime when opening Either`);
+};
+exports.unwrapEither = unwrapEither;
+/** @public */
+function norskHost() {
+    if (process.env.NORSK_HOST)
+        return process.env.NORSK_HOST;
+    return "127.0.0.1";
+}
+/** @public */
+function norskPort() {
+    if (process.env.NORSK_PORT)
+        return process.env.NORSK_PORT;
+    return "6790";
+}
+/** @public */
+function publicUrlPrefix() {
+    if (process.env.PUBLIC_URL_PREFIX)
+        return process.env.PUBLIC_URL_PREFIX;
+    return "http://127.0.0.1:8080";
+}
+/** @public */
+function debugUrlPrefix() {
+    if (process.env.DEBUG_URL_PREFIX)
+        return process.env.DEBUG_URL_PREFIX;
+    return "http://" + norskHost() + ":6791";
+}
+/** @public */
+function clientHostExternal() {
+    if (process.env.CLIENT_HOST_EXTERNAL)
+        return process.env.CLIENT_HOST_EXTERNAL;
+    return "127.0.0.1";
+}
+/** @public */
+function clientPortExternal() {
+    if (process.env.CLIENT_PORT_EXTERNAL)
+        return process.env.CLIENT_PORT_EXTERNAL;
+    return "3000";
+}
+/** @public */
+function clientHostInternal() {
+    if (process.env.CLIENT_HOST_INTERNAL)
+        return process.env.CLIENT_HOST_INTERNAL;
+    return "127.0.0.1";
+}
+/** @public */
+function clientPortInternal() {
+    if (process.env.CLIENT_PORT_INTERNAL)
+        return process.env.CLIENT_PORT_INTERNAL;
+    return "3000";
+}
+//# sourceMappingURL=utils.js.map