@norskvideo/ctl-sdk 0.1.36 → 0.1.37

package/index.d.ts

@@ -20,4 +20,5 @@ export * from "./product-service.js";
 export * from "./product-template-materials.js";
 export * from "./proxy-middleware.js";
 export * from "./route-error.js";
+export * from "./runner-capabilities.js";
 export * from "./sse.js";

package/index.js

@@ -22,4 +22,5 @@ export * from "./product-service.js";
 export * from "./product-template-materials.js";
 export * from "./proxy-middleware.js";
 export * from "./route-error.js";
+export * from "./runner-capabilities.js";
 export * from "./sse.js";

package/manifest-schema.d.ts

@@ -14,6 +14,7 @@ export declare const ManifestSchema: z.ZodObject<{
     name: z.ZodString;
     version: z.ZodString;
     minRunnerVersion: z.ZodOptional<z.ZodString>;
+    requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
     api: z.ZodObject<{
         basePath: z.ZodString;
         proxyPaths: z.ZodArray<z.ZodString>;

package/manifest-schema.js

@@ -96,6 +96,9 @@ export const ManifestSchema = z.object({
     name: z.string(),
     version: z.string(),
     minRunnerVersion: z.string().optional(),
+    requires: z.array(z.string().min(1)).optional().meta({
+        description: "Named runner capabilities this product version cannot launch without (RFC 0001 §3.6). A runner that lacks any of them refuses the product as too old rather than mis-launching it. Usually absent — evolve the contract additively first; never a runner version number.",
+    }),
     api: z.object({
         basePath: z.string(),
         proxyPaths: z.array(z.string()),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "type": "module",
   "exports": {
     ".": {
@@ -23,6 +23,10 @@
       "types": "./manifest-seed.d.ts",
       "default": "./manifest-seed.js"
     },
+    "./runner-capabilities": {
+      "types": "./runner-capabilities.d.ts",
+      "default": "./runner-capabilities.js"
+    },
     "./runtime": {
       "types": "./runtime.d.ts",
       "default": "./runtime.js"

package/product-error.d.ts

@@ -1,4 +1,4 @@
 export declare class ProductError extends Error {
-    code: "DEV_URL_INVALID" | "DEV_URL_NOT_LOCALHOST" | "PORT_EXHAUSTED" | "DOCKER_PULL_FAILED" | "DOCKER_RUN_FAILED" | "READINESS_TIMEOUT" | "MANIFEST_FETCH_FAILED" | "MANIFEST_INVALID" | "CONFIG_SCREEN_UNREACHABLE" | "CONFIG_SCREEN_DEV_SERVER" | "LICENSE_INVALID" | "NAME_CONFLICT" | "NOT_FOUND" | "NOT_RESTARTABLE" | "PRODUCT_TEMPLATE_FETCH_FAILED";
-    constructor(code: "DEV_URL_INVALID" | "DEV_URL_NOT_LOCALHOST" | "PORT_EXHAUSTED" | "DOCKER_PULL_FAILED" | "DOCKER_RUN_FAILED" | "READINESS_TIMEOUT" | "MANIFEST_FETCH_FAILED" | "MANIFEST_INVALID" | "CONFIG_SCREEN_UNREACHABLE" | "CONFIG_SCREEN_DEV_SERVER" | "LICENSE_INVALID" | "NAME_CONFLICT" | "NOT_FOUND" | "NOT_RESTARTABLE" | "PRODUCT_TEMPLATE_FETCH_FAILED", message: string);
+    code: "DEV_URL_INVALID" | "DEV_URL_NOT_LOCALHOST" | "PORT_EXHAUSTED" | "DOCKER_PULL_FAILED" | "DOCKER_RUN_FAILED" | "READINESS_TIMEOUT" | "MANIFEST_FETCH_FAILED" | "MANIFEST_INVALID" | "CONFIG_SCREEN_UNREACHABLE" | "CONFIG_SCREEN_DEV_SERVER" | "LICENSE_INVALID" | "NAME_CONFLICT" | "NOT_FOUND" | "NOT_RESTARTABLE" | "RUNNER_TOO_OLD" | "PRODUCT_TEMPLATE_FETCH_FAILED";
+    constructor(code: "DEV_URL_INVALID" | "DEV_URL_NOT_LOCALHOST" | "PORT_EXHAUSTED" | "DOCKER_PULL_FAILED" | "DOCKER_RUN_FAILED" | "READINESS_TIMEOUT" | "MANIFEST_FETCH_FAILED" | "MANIFEST_INVALID" | "CONFIG_SCREEN_UNREACHABLE" | "CONFIG_SCREEN_DEV_SERVER" | "LICENSE_INVALID" | "NAME_CONFLICT" | "NOT_FOUND" | "NOT_RESTARTABLE" | "RUNNER_TOO_OLD" | "PRODUCT_TEMPLATE_FETCH_FAILED", message: string);
 }

package/product-service.d.ts

@@ -121,6 +121,10 @@ export interface ProductServiceOptions {
      *  in a container). Default: detected from the daemon's cgroup, overridable
      *  with NORSK_CTL_PRODUCT_REACH. */
     reach?: ProductReach;
+    /** Named runner capabilities this host knows (RFC 0001 §3.6). A product
+     *  whose manifest `requires` any other is refused at add and reload.
+     *  Default: none. */
+    knownCapabilities?: readonly string[];
 }
 export declare class ProductService {
     /**
@@ -145,10 +149,12 @@ export declare class ProductService {
     private readonly isDevUrlAlive;
     private readonly containerOps;
     private readonly reach;
+    private readonly knownCapabilities;
     constructor(opts: ProductServiceOptions);
     /** The address to record for a freshly started container: its own, when
      *  this daemon cannot dial the host loopback; otherwise nothing. */
     private reachHostFor;
+    private refuseUnknownCapabilities;
     list(): ProductRegistration[];
     /** Docker's default `--pull=missing` keeps whatever a moving tag resolved to
      *  last time, so a rebuilt `:latest`/`:dev` never reached a new registration.

package/product-service.js

@@ -7,6 +7,7 @@ import { checkProductEntitlement, notV2EnvelopeMessage, parseLicenseContents } f
 import { fetchManifest, isDevUrlAlive, probeConfigScreen, productBaseUrl, specBaseUrl, waitForReady, } from "./manifest-fetch.js";
 import { ProductError } from "./product-error.js";
 import { detectProductReach } from "./product-reach.js";
+import { checkRequiredCapabilities } from "./runner-capabilities.js";
 /** GET a product-template tar from a product. `url` is whatever the manifest
  *  declared; we treat it as a path on the product's HTTP surface and
  *  resolve against the product's base URL. Returns the raw tar bytes,
@@ -58,6 +59,7 @@ export class ProductService {
     isDevUrlAlive;
     containerOps;
     reach;
+    knownCapabilities;
     constructor(opts) {
         this.store = opts.store;
         this.importProductTemplateBytes = opts.importProductTemplateBytes;
@@ -66,6 +68,7 @@ export class ProductService {
         this.isDevUrlAlive = opts.isDevUrlAlive ?? isDevUrlAlive;
         this.containerOps = opts.containerOps ?? defaultProductContainerOps;
         this.reach = opts.reach ?? detectProductReach({});
+        this.knownCapabilities = opts.knownCapabilities ?? [];
     }
     /** The address to record for a freshly started container: its own, when
      *  this daemon cannot dial the host loopback; otherwise nothing. */
@@ -74,6 +77,10 @@ export class ProductService {
             return undefined;
         return this.containerOps.address(containerId);
     }
+    refuseUnknownCapabilities(manifest) {
+        const check = checkRequiredCapabilities({ product: manifest.name, version: manifest.version, requires: manifest.requires }, this.knownCapabilities);
+        return check.status === "error" ? new ProductError("RUNNER_TOO_OLD", check.error.message) : undefined;
+    }
     list() {
         return this.store.read();
     }
@@ -137,6 +144,12 @@ export class ProductService {
                 await this.containerOps.remove(containerId);
             throw e;
         });
+        const refusal = this.refuseUnknownCapabilities(manifest);
+        if (refusal) {
+            if (containerId)
+                await this.containerOps.remove(containerId);
+            throw refusal;
+        }
         if (existing.some((p) => p.name === manifest.name)) {
             if (containerId)
                 await this.containerOps.remove(containerId);
@@ -319,6 +332,9 @@ export class ProductService {
         const current = this.store.read().find((p) => p.name === name) ?? target;
         const baseUrl = productBaseUrl(current);
         const manifest = await fetchManifest(baseUrl);
+        const refusal = this.refuseUnknownCapabilities(manifest);
+        if (refusal)
+            throw refusal;
         if (manifest.name !== target.name) {
             throw new ProductError("NAME_CONFLICT", `manifest now reports name '${manifest.name}', was '${target.name}' — use remove + add`);
         }

package/runner-capabilities.d.ts

@@ -0,0 +1,10 @@
+import { type Result } from "@norskvideo/ctl-foundation";
+export interface CapabilityRefusal {
+    missing: string[];
+    message: string;
+}
+export declare function checkRequiredCapabilities(target: {
+    product: string;
+    version: string;
+    requires?: readonly string[];
+}, known: readonly string[]): Result<void, CapabilityRefusal>;

package/runner-capabilities.js

@@ -0,0 +1,14 @@
+import { err, ok } from "@norskvideo/ctl-foundation";
+// RFC 0001 §3.6: a version whose `requires` names a capability this runner
+// does not know is refused with an explicit "too old" stop rather than a
+// silent mis-launch. Run it before pulling anything for that version.
+export function checkRequiredCapabilities(target, known) {
+    const missing = (target.requires ?? []).filter((c) => !known.includes(c));
+    if (missing.length === 0)
+        return ok(undefined);
+    const needs = missing.map((c) => `'${c}'`).join(", ");
+    return err({
+        missing,
+        message: `your norsk-ctl can't launch ${target.product} ${target.version} — it needs ${needs}; run 'norsk-ctl upgrade'`,
+    });
+}