@norskvideo/ctl-sdk 0.1.7 → 0.1.8

package/package.json

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

package/product-service.d.ts

@@ -79,6 +79,21 @@ export interface ProductServiceOptions {
     containerOps?: ProductContainerOps;
 }
 export declare class ProductService {
+    /**
+     * Serialises every mutation. `add` decides on a store read — which host port
+     * is free, whether the name is taken — and only commits after starting a
+     * container, waiting for it, fetching its manifest and probing it. That gap
+     * cannot move inside the store's `update` callback: the callback is sync,
+     * and a registration cannot be written under its name before `fetchManifest`
+     * supplies the name. Two concurrent adds therefore allocated the same host
+     * port and both stored under one name.
+     *
+     * This is a lock in a different module from the data it protects, which is
+     * ordinarily the shape to avoid — accepted here because the invariant spans
+     * side effects (a running container, an allocated port) the store cannot
+     * see. See ADR-0008.
+     */
+    private readonly mutations;
     private readonly store;
     private readonly allocatePort;
     private readonly importProductTemplateBytes?;
@@ -92,8 +107,11 @@ export declare class ProductService {
      *  the dev URL — registered no longer implies running. */
     isRunning(reg: ProductRegistration): Promise<boolean>;
     add(spec: ProductSpec, opts?: AddProductOpts): Promise<AddProductResult>;
+    private addSerialised;
     remove(name: string): Promise<void>;
+    private removeSerialised;
     reload(name: string): Promise<ProductRegistration>;
+    private reloadSerialised;
     /** Stop every running container-kind product and clear its tracked
      *  containerId (model B: the daemon owns container lifecycle, so it reaps
      *  the control planes it started). Dev-kind products are externally owned —
@@ -102,6 +120,7 @@ export declare class ProductService {
      *  Best-effort per product — a failing `docker rm` is logged, never thrown,
      *  so one stubborn container can't block a clean shutdown. */
     stopAll(): Promise<void>;
+    private stopAllSerialised;
     /** Relaunch every container-kind product recorded in the store, refreshing
      *  its containerId (model B: called once at daemon boot to re-create the
      *  control planes stopped on the previous shutdown). Dev-kind products are
@@ -109,6 +128,7 @@ export declare class ProductService {
      *  come up is logged and left with its containerId cleared, so isRunning()
      *  reports it down rather than pointing at a container that never started. */
     restoreAll(): Promise<void>;
+    private restoreAllSerialised;
     /** Stop (if still present) and relaunch a single container-kind product,
      *  recording the fresh containerId. Used by the health monitor to recover a
      *  product that has failed its liveness probe. Unlike restoreAll this is not
@@ -117,4 +137,5 @@ export declare class ProductService {
      *  persisted before the readiness wait, so even a timed-out restart leaves a
      *  tracked container the next restart can reap rather than orphan. */
     restart(name: string): Promise<void>;
+    private restartSerialised;
 }

package/product-service.js

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { logger } from "@norskvideo/ctl-foundation";
+import { logger, Mutex } from "@norskvideo/ctl-foundation";
 import { validateDevUrl } from "./dev-url.js";
 import { dockerRename, dockerRm, dockerRun, productContainerName } from "./docker-runner.js";
 import { resolveLicenseFile } from "./license-registration.js";
@@ -31,6 +31,21 @@ const defaultContainerOps = {
     waitForReady,
 };
 export class ProductService {
+    /**
+     * Serialises every mutation. `add` decides on a store read — which host port
+     * is free, whether the name is taken — and only commits after starting a
+     * container, waiting for it, fetching its manifest and probing it. That gap
+     * cannot move inside the store's `update` callback: the callback is sync,
+     * and a registration cannot be written under its name before `fetchManifest`
+     * supplies the name. Two concurrent adds therefore allocated the same host
+     * port and both stored under one name.
+     *
+     * This is a lock in a different module from the data it protects, which is
+     * ordinarily the shape to avoid — accepted here because the invariant spans
+     * side effects (a running container, an allocated port) the store cannot
+     * see. See ADR-0008.
+     */
+    mutations = new Mutex();
     store;
     allocatePort;
     importProductTemplateBytes;
@@ -57,6 +72,9 @@ export class ProductService {
         return this.isDevUrlAlive(specBaseUrl(reg.spec));
     }
     async add(spec, opts = {}) {
+        return this.mutations.run(() => this.addSerialised(spec, opts));
+    }
+    async addSerialised(spec, opts) {
         const existing = this.store.read();
         let baseUrl;
         let port;
@@ -222,6 +240,9 @@ export class ProductService {
         return { registration, warnings };
     }
     async remove(name) {
+        return this.mutations.run(() => this.removeSerialised(name));
+    }
+    async removeSerialised(name) {
         const existing = this.store.read();
         const target = existing.find((p) => p.name === name);
         if (!target)
@@ -232,6 +253,9 @@ export class ProductService {
         logger.info(`Product '${name}' removed`);
     }
     async reload(name) {
+        return this.mutations.run(() => this.reloadSerialised(name));
+    }
+    async reloadSerialised(name) {
         const existing = this.store.read();
         const target = existing.find((p) => p.name === name);
         if (!target)
@@ -254,6 +278,9 @@ export class ProductService {
      *  Best-effort per product — a failing `docker rm` is logged, never thrown,
      *  so one stubborn container can't block a clean shutdown. */
     async stopAll() {
+        return this.mutations.run(() => this.stopAllSerialised());
+    }
+    async stopAllSerialised() {
         const toStop = this.store.read().filter((p) => p.spec.kind === "container" && p.containerId !== undefined);
         if (toStop.length === 0)
             return;
@@ -276,6 +303,9 @@ export class ProductService {
      *  come up is logged and left with its containerId cleared, so isRunning()
      *  reports it down rather than pointing at a container that never started. */
     async restoreAll() {
+        return this.mutations.run(() => this.restoreAllSerialised());
+    }
+    async restoreAllSerialised() {
         const toRestore = this.store.read().filter((p) => p.spec.kind === "container");
         if (toRestore.length === 0)
             return;
@@ -308,6 +338,9 @@ export class ProductService {
      *  persisted before the readiness wait, so even a timed-out restart leaves a
      *  tracked container the next restart can reap rather than orphan. */
     async restart(name) {
+        return this.mutations.run(() => this.restartSerialised(name));
+    }
+    async restartSerialised(name) {
         const target = this.store.read().find((p) => p.name === name);
         if (!target)
             throw new ProductError("NOT_FOUND", `product '${name}' not registered`);