@norskvideo/ctl-sdk 0.1.5 → 0.1.7

package/index.d.ts

@@ -5,6 +5,7 @@ export * from "./dev-url.js";
 export * from "./docker-runner.js";
 export * from "./http-proxy.js";
 export * from "./license-registration.js";
+export * from "./license-staged.js";
 export * from "./license-stager.js";
 export * from "./license-v2.js";
 export * from "./manifest-fetch.js";

package/index.js

@@ -7,6 +7,7 @@ export * from "./dev-url.js";
 export * from "./docker-runner.js";
 export * from "./http-proxy.js";
 export * from "./license-registration.js";
+export * from "./license-staged.js";
 export * from "./license-stager.js";
 export * from "./license-v2.js";
 export * from "./manifest-fetch.js";

package/license-staged.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The staged copy corresponding to an operator-supplied licence path, if one
+ * exists under `licensesDir`. `exists` is injected so this stays unit-testable.
+ */
+export declare function stagedLicenseCandidate(operatorPath: string, licensesDir: string | undefined, exists?: (path: string) => boolean): string | undefined;
+/**
+ * Explain an unreadable licence in terms of the thing that's actually wrong.
+ *
+ * A permissions failure and a missing file are different mistakes: the first is
+ * "right file, wrong path for this process", the second is a typo. Naming the
+ * daemon user on an ENOENT would send the operator hunting a permissions
+ * problem that isn't there.
+ */
+export declare function unreadableLicenseMessage(opts: {
+    operatorPath: string;
+    cause: string;
+    daemonUser: string;
+    licensesDir?: string;
+    stagedCandidate?: string;
+}): string;

package/license-staged.js

@@ -0,0 +1,55 @@
+/**
+ * Diagnostics for a licence file the daemon cannot read.
+ *
+ * The licence-driven routes (`preview-license`, `from-license`) read the file
+ * daemon-side, and the daemon runs unprivileged as its service user — so an
+ * operator who passes the path they used at install time (`~/licence.json`, in
+ * *their* home) gets an EACCES that reads like a broken licence rather than a
+ * wrong path.
+ *
+ * The remedy is almost always sitting in `licensesDir`: the installers stage a
+ * copy there, deliberately keeping the operator's basename, so the file they
+ * meant can be found by name and named back to them. Shared by the hosts (ctl
+ * and mgr) so the two daemons explain the same mistake the same way.
+ */
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+/**
+ * The staged copy corresponding to an operator-supplied licence path, if one
+ * exists under `licensesDir`. `exists` is injected so this stays unit-testable.
+ */
+export function stagedLicenseCandidate(operatorPath, licensesDir, exists = existsSync) {
+    if (!licensesDir)
+        return undefined;
+    // Already the staged copy — suggesting it back would be circular.
+    if (resolve(dirname(operatorPath)) === resolve(licensesDir))
+        return undefined;
+    const candidate = join(licensesDir, basename(operatorPath));
+    return exists(candidate) ? candidate : undefined;
+}
+/**
+ * Explain an unreadable licence in terms of the thing that's actually wrong.
+ *
+ * A permissions failure and a missing file are different mistakes: the first is
+ * "right file, wrong path for this process", the second is a typo. Naming the
+ * daemon user on an ENOENT would send the operator hunting a permissions
+ * problem that isn't there.
+ */
+export function unreadableLicenseMessage(opts) {
+    const { operatorPath, cause, daemonUser, licensesDir, stagedCandidate } = opts;
+    const missing = /ENOENT/.test(cause);
+    const parts = [`cannot read license file '${operatorPath}': ${cause}`];
+    if (missing) {
+        parts.push("Check the path — nothing exists there.");
+    }
+    else {
+        parts.push(`The daemon runs as '${daemonUser}', which cannot read it.`);
+    }
+    if (stagedCandidate) {
+        parts.push(`A staged licence of the same name exists at '${stagedCandidate}' — pass that instead.`);
+    }
+    else if (!missing) {
+        parts.push(`Licences are staged under ${licensesDir ?? "the daemon's licenses directory"} at install time; pass the staged path, or copy the file there readable by '${daemonUser}'.`);
+    }
+    return parts.join(" ");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "exports": {
     ".": {

package/product-service.d.ts

@@ -49,9 +49,11 @@ export type ImportProductTemplateBytesFn = (opts: {
         kind: "product-default";
     }>;
 }) => Promise<void>;
-/** The container operations stopAll/restoreAll depend on, behind an interface
- *  so tests can drive them without shelling out to Docker. Defaults wire
- *  straight to docker-runner + the readiness probe. */
+/** Every container operation this service performs, behind an interface so
+ *  tests can drive them without shelling out to Docker. Defaults wire straight
+ *  to docker-runner + the readiness probe. Reach for these rather than the
+ *  module functions: calling docker-runner directly re-creates the bypass that
+ *  made an injected fake silently inert on add/remove. */
 export interface ProductContainerOps {
     run(image: string, hostPort: number): Promise<string>;
     remove(containerId: string): Promise<void>;
@@ -72,8 +74,8 @@ export interface ProductServiceOptions {
     /** Liveness probe for dev-mode products. Injectable for tests; defaults to a
      *  fast timeout-bounded GET of the dev URL's `/manifest.json`. */
     isDevUrlAlive?: (baseUrl: string) => Promise<boolean>;
-    /** Container lifecycle ops used by stopAll/restoreAll. Injectable for tests;
-     *  defaults to the real docker-runner functions. */
+    /** Container lifecycle ops used by add/remove/restart/stopAll/restoreAll.
+     *  Injectable for tests; defaults to the real docker-runner functions. */
     containerOps?: ProductContainerOps;
 }
 export declare class ProductService {

package/product-service.js

@@ -76,25 +76,25 @@ export class ProductService {
             }
             port = allocated;
             logger.info(`Starting product container: ${spec.image} on host port ${port}`);
-            containerId = await dockerRun(spec.image, port);
+            containerId = await this.containerOps.run(spec.image, port);
             baseUrl = specBaseUrl(spec, port);
         }
         try {
-            await waitForReady(baseUrl);
+            await this.containerOps.waitForReady(baseUrl);
         }
         catch (e) {
             if (containerId)
-                await dockerRm(containerId);
+                await this.containerOps.remove(containerId);
             throw e;
         }
         const manifest = await fetchManifest(baseUrl).catch(async (e) => {
             if (containerId)
-                await dockerRm(containerId);
+                await this.containerOps.remove(containerId);
             throw e;
         });
         if (existing.some((p) => p.name === manifest.name)) {
             if (containerId)
-                await dockerRm(containerId);
+                await this.containerOps.remove(containerId);
             throw new ProductError("NAME_CONFLICT", `product '${manifest.name}' already registered`);
         }
         const warnings = [];
@@ -111,7 +111,7 @@ export class ProductService {
             licenseFile = resolved.file;
             if (resolved.fatal) {
                 if (containerId)
-                    await dockerRm(containerId);
+                    await this.containerOps.remove(containerId);
                 throw new ProductError("LICENSE_INVALID", resolved.fatal);
             }
             if (resolved.warning)
@@ -137,19 +137,19 @@ export class ProductService {
             const parsed = contents !== undefined ? parseLicenseContents(contents) : undefined;
             if (parsed?.kind === "invalid-v2") {
                 if (containerId)
-                    await dockerRm(containerId);
+                    await this.containerOps.remove(containerId);
                 throw new ProductError("LICENSE_INVALID", parsed.reason);
             }
             if (parsed?.kind === "legacy") {
                 if (containerId)
-                    await dockerRm(containerId);
+                    await this.containerOps.remove(containerId);
                 throw new ProductError("LICENSE_INVALID", notV2EnvelopeMessage("V1 licenses are no longer accepted at registration"));
             }
             if (parsed?.kind === "v2") {
                 const check = checkProductEntitlement(parsed, manifest.name, spec.kind === "container" ? spec.image : undefined);
                 if (!check.ok) {
                     if (containerId)
-                        await dockerRm(containerId);
+                        await this.containerOps.remove(containerId);
                     throw new ProductError("LICENSE_INVALID", check.reason);
                 }
                 warnings.push(...check.warnings);
@@ -159,7 +159,7 @@ export class ProductService {
         // stable, human-readable name (replacing docker's random alias). Tracked
         // by id, so a rename failure is harmless — hence best-effort.
         if (containerId)
-            await dockerRename(containerId, productContainerName(manifest.name));
+            await this.containerOps.rename(containerId, productContainerName(manifest.name));
         // Sanity-probe the config screen so we catch (a) URLs that don't
         // serve anything at the manifest-declared path, and (b) the common
         // "registered the vite dev port" mistake — both are hard rejections
@@ -170,7 +170,7 @@ export class ProductService {
             }
             catch (e) {
                 if (containerId)
-                    await dockerRm(containerId);
+                    await this.containerOps.remove(containerId);
                 throw e;
             }
         }
@@ -227,7 +227,7 @@ export class ProductService {
         if (!target)
             throw new ProductError("NOT_FOUND", `product '${name}' not registered`);
         if (target.containerId)
-            await dockerRm(target.containerId);
+            await this.containerOps.remove(target.containerId);
         await this.store.update((products) => products.filter((p) => p.name !== name));
         logger.info(`Product '${name}' removed`);
     }