@camstack/system 1.2.21 → 1.2.23

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-OQ1yU92D.js");
+const require_dist = require("../../dist-CS0pdC8l.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
 let node_fs_promises = require("node:fs/promises");
@@ -14,6 +14,8 @@ var StorageOrchestratorService = class {
 	logger;
 	getProviders;
 	locationStore;
+	localNodeId;
+	getRemoteProvider;
 	locations = /* @__PURE__ */ new Map();
 	/**
 	* Declaration-driven cardinality source, injected by the addon after
@@ -31,10 +33,12 @@ var StorageOrchestratorService = class {
 	* early-boot path that predates the resolver wiring.
 	*/
 	nodeLocalResolver = null;
-	constructor(logger, getProviders, locationStore = null) {
+	constructor(logger, getProviders, locationStore = null, localNodeId = "hub", getRemoteProvider) {
 		this.logger = logger;
 		this.getProviders = getProviders;
 		this.locationStore = locationStore;
+		this.localNodeId = localNodeId;
+		this.getRemoteProvider = getRemoteProvider;
 	}
 	/** True once a persistence store is wired (constructor or {@link attachStore}). */
 	hasStore() {
@@ -349,6 +353,12 @@ var StorageOrchestratorService = class {
 	* the right place to fix the config.
 	*/
 	async getProviderFor(location) {
+		const nodeId = location.nodeId;
+		if (nodeId !== void 0 && nodeId !== this.localNodeId) {
+			const remote = this.getRemoteProvider?.(nodeId);
+			if (remote) return remote;
+			throw new Error(`storage-provider for location "${location.id}" lives on node "${nodeId}" which is not reachable`);
+		}
 		const providers = this.getProviders();
 		for (const p of providers) if ((await p.getProviderInfo()).providerId === location.providerId) return p;
 		throw new Error(`No storage-provider registered for providerId "${location.providerId}" (location "${location.id}")`);
@@ -378,8 +388,8 @@ var StorageOrchestratorService = class {
 		let added = 0;
 		const declById = new Map(input.declarations.map((d) => [d.id, d]));
 		const rootFor = (d) => {
-			const useMedia = d.defaultRoot === "media" && input.mediaBasePath;
-			return node_path.join(useMedia ? input.mediaBasePath : input.basePath, d.id);
+			const dedicated = d.defaultRoot === "media" ? input.mediaBasePath : d.defaultRoot === "backup" ? input.backupBasePath : void 0;
+			return node_path.join(dedicated ?? input.basePath, d.id);
 		};
 		for (const d of input.declarations) {
 			if (this.hasAnyLocationOfType(d.id)) continue;
@@ -634,6 +644,53 @@ var StoragePressureManager = class {
 				} });
 			}
 		}
+		const caps = await this.deps.getLocationMaxUsedBytes?.() ?? /* @__PURE__ */ new Map();
+		for (const [locationId, maxBytes] of caps) {
+			if (relievedDevices.size > 0) {
+				const deviceKey = await this.deps.getLocationDeviceKey?.(locationId) ?? null;
+				if (deviceKey !== null && relievedDevices.has(deviceKey)) continue;
+			}
+			try {
+				await this.relieveToUsageCap(locationId, maxBytes);
+			} catch (err) {
+				this.deps.logger.warn("storage pressure: usage-cap relief failed", { meta: {
+					locationId,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+			}
+		}
+	}
+	/** Evict oldest-first until the location's evictable usage fits `maxBytes`. */
+	async relieveToUsageCap(locationId, maxBytes) {
+		const maxRounds = this.deps.maxRounds ?? DEFAULT_MAX_ROUNDS;
+		for (let round = 0; round < maxRounds; round++) {
+			const providers = this.deps.getEvictableProviders();
+			const usages = await Promise.all(providers.map(async (p) => ({
+				p,
+				bytes: (await p.getEvictableUsage({ locationId })).bytes
+			})));
+			const totalUsed = usages.reduce((s, u) => s + u.bytes, 0);
+			const excess = totalUsed - maxBytes;
+			if (excess <= 0) return;
+			let reclaimed = 0;
+			for (const u of usages) {
+				if (u.bytes <= 0) continue;
+				const share = Math.max(1, Math.ceil(excess * u.bytes / totalUsed));
+				const res = await u.p.evict({
+					locationId,
+					targetBytes: share
+				});
+				reclaimed += res.reclaimedBytes;
+			}
+			this.deps.logger.info("storage pressure: usage-cap relief round", { meta: {
+				locationId,
+				round,
+				totalUsed,
+				maxBytes,
+				reclaimedBytes: reclaimed
+			} });
+			if (reclaimed <= 0) return;
+		}
 	}
 	/**
 	* Relieve one location until it recovers, nothing is evictable, or a round
@@ -772,13 +829,21 @@ var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 			return reg.getCollection(STORAGE_PROVIDER_CAP_NAME);
 		};
 		const locationStore = this.resolveLocationStore();
-		const service = new StorageOrchestratorService(this.ctx.logger, getProviders, locationStore);
+		const service = new StorageOrchestratorService(this.ctx.logger, getProviders, locationStore, this.ctx.kernel.localNodeId ?? "hub", (nodeId) => {
+			const proxy = this.ctx.kernel.resolveNodeCapability?.("storage-provider", nodeId);
+			if (!proxy) return null;
+			return proxy;
+		});
 		this.service = service;
 		service.setNodeLocalResolver((providerId) => this.nodeLocalByProvider.get(providerId));
 		await service.initialize();
 		const provider = {
 			listLocations: async ({ type }) => {
-				return type !== void 0 ? service.listLocations({ type }) : service.listLocations();
+				const rows = type !== void 0 ? service.listLocations({ type }) : service.listLocations();
+				return Promise.all(rows.map(async (loc) => ({
+					...loc,
+					capacity: await this.localCapacityOf(loc)
+				})));
 			},
 			getDefaultLocation: async ({ type }) => service.getDefaultLocation(type),
 			listLocationDeclarations: async () => service.listDeclarations(),
@@ -944,6 +1009,7 @@ var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 			getVolumeTotalBytes: (id) => this.locationVolumeTotalBytes(id),
 			getEvictableProviders: () => this.ctx.kernel.capabilityRegistry?.getCollection(STORAGE_EVICTABLE_CAP_NAME) ?? [],
 			getLocationThresholds: () => this.resolveLocationThresholds(),
+			getLocationMaxUsedBytes: () => this.resolveLocationMaxUsedBytes(),
 			getLocationDeviceKey: (id) => this.locationDeviceKey(id)
 		});
 		this.pressureTimer = setInterval(() => {
@@ -1053,6 +1119,44 @@ var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 		}
 		return out;
 	}
+	/** statfs capacity of a location's basePath, walking up to the nearest
+	*  existing ancestor. Null for remote-node locations or unstattable paths. */
+	async localCapacityOf(loc) {
+		if (loc.nodeId !== void 0 && loc.nodeId !== "hub" && loc.nodeId !== this.ctx.nodeId) return null;
+		const bp = loc.config["basePath"];
+		if (typeof bp !== "string" || bp.length === 0) return null;
+		try {
+			let target = node_path.resolve(bp);
+			for (;;) try {
+				await node_fs_promises.access(target);
+				break;
+			} catch {
+				const parent = node_path.dirname(target);
+				if (!parent || parent === target) return null;
+				target = parent;
+			}
+			const st = await node_fs_promises.statfs(target);
+			return {
+				totalBytes: st.blocks * st.bsize,
+				availableBytes: st.bavail * st.bsize
+			};
+		} catch {
+			return null;
+		}
+	}
+	/** Per-location cap on EVICTABLE bytes (`config.maxUsedGb`): the operator's
+	*  "recordings may use at most N GB in total" — enforced by the pressure
+	*  manager alongside the free-percent guard. */
+	async resolveLocationMaxUsedBytes() {
+		const out = /* @__PURE__ */ new Map();
+		const svc = this.service;
+		if (!svc) return out;
+		for (const loc of svc.listLocations()) {
+			const raw = loc.config["maxUsedGb"];
+			if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) out.set(loc.id, Math.floor(raw * 1024 ** 3));
+		}
+		return out;
+	}
 	locationBasePath(locationId) {
 		const bp = (this.service?.listLocations().find((l) => l.id === locationId))?.config["basePath"];
 		return typeof bp === "string" && bp.length > 0 ? bp : null;
@@ -1120,10 +1224,12 @@ var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 		this.service.setRegistry(registry);
 		this.service.pruneUndeclaredSystemLocations();
 		const mediaRoot = process.env.CAMSTACK_MEDIA_ROOT?.trim();
+		const backupRoot = process.env.CAMSTACK_BACKUP_ROOT?.trim();
 		this.service.seedDefaults({
 			providerId: "filesystem-storage",
 			basePath: this.ctx.nodeDataDir,
 			mediaBasePath: mediaRoot && mediaRoot.length > 0 ? mediaRoot : void 0,
+			backupBasePath: backupRoot && backupRoot.length > 0 ? backupRoot : void 0,
 			declarations: registry.list()
 		});
 		await this.service.backfillNodeIds(HUB_NODE_ID);

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { Q as storageCapability, Tt as parseJsonObject, at as BaseAddon, d as StorageLocationTypeSchema } from "../../dist-DmQ6thmF.mjs";
+import { Q as storageCapability, Tt as parseJsonObject, at as BaseAddon, d as StorageLocationTypeSchema } from "../../dist-CIek6F9X.mjs";
 import * as path$1 from "node:path";
 import * as fs from "node:fs/promises";
 import { buildStorageLocationRegistry } from "@camstack/system";
@@ -7,6 +7,8 @@ var StorageOrchestratorService = class {
 	logger;
 	getProviders;
 	locationStore;
+	localNodeId;
+	getRemoteProvider;
 	locations = /* @__PURE__ */ new Map();
 	/**
 	* Declaration-driven cardinality source, injected by the addon after
@@ -24,10 +26,12 @@ var StorageOrchestratorService = class {
 	* early-boot path that predates the resolver wiring.
 	*/
 	nodeLocalResolver = null;
-	constructor(logger, getProviders, locationStore = null) {
+	constructor(logger, getProviders, locationStore = null, localNodeId = "hub", getRemoteProvider) {
 		this.logger = logger;
 		this.getProviders = getProviders;
 		this.locationStore = locationStore;
+		this.localNodeId = localNodeId;
+		this.getRemoteProvider = getRemoteProvider;
 	}
 	/** True once a persistence store is wired (constructor or {@link attachStore}). */
 	hasStore() {
@@ -342,6 +346,12 @@ var StorageOrchestratorService = class {
 	* the right place to fix the config.
 	*/
 	async getProviderFor(location) {
+		const nodeId = location.nodeId;
+		if (nodeId !== void 0 && nodeId !== this.localNodeId) {
+			const remote = this.getRemoteProvider?.(nodeId);
+			if (remote) return remote;
+			throw new Error(`storage-provider for location "${location.id}" lives on node "${nodeId}" which is not reachable`);
+		}
 		const providers = this.getProviders();
 		for (const p of providers) if ((await p.getProviderInfo()).providerId === location.providerId) return p;
 		throw new Error(`No storage-provider registered for providerId "${location.providerId}" (location "${location.id}")`);
@@ -371,8 +381,8 @@ var StorageOrchestratorService = class {
 		let added = 0;
 		const declById = new Map(input.declarations.map((d) => [d.id, d]));
 		const rootFor = (d) => {
-			const useMedia = d.defaultRoot === "media" && input.mediaBasePath;
-			return path$1.join(useMedia ? input.mediaBasePath : input.basePath, d.id);
+			const dedicated = d.defaultRoot === "media" ? input.mediaBasePath : d.defaultRoot === "backup" ? input.backupBasePath : void 0;
+			return path$1.join(dedicated ?? input.basePath, d.id);
 		};
 		for (const d of input.declarations) {
 			if (this.hasAnyLocationOfType(d.id)) continue;
@@ -627,6 +637,53 @@ var StoragePressureManager = class {
 				} });
 			}
 		}
+		const caps = await this.deps.getLocationMaxUsedBytes?.() ?? /* @__PURE__ */ new Map();
+		for (const [locationId, maxBytes] of caps) {
+			if (relievedDevices.size > 0) {
+				const deviceKey = await this.deps.getLocationDeviceKey?.(locationId) ?? null;
+				if (deviceKey !== null && relievedDevices.has(deviceKey)) continue;
+			}
+			try {
+				await this.relieveToUsageCap(locationId, maxBytes);
+			} catch (err) {
+				this.deps.logger.warn("storage pressure: usage-cap relief failed", { meta: {
+					locationId,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+			}
+		}
+	}
+	/** Evict oldest-first until the location's evictable usage fits `maxBytes`. */
+	async relieveToUsageCap(locationId, maxBytes) {
+		const maxRounds = this.deps.maxRounds ?? DEFAULT_MAX_ROUNDS;
+		for (let round = 0; round < maxRounds; round++) {
+			const providers = this.deps.getEvictableProviders();
+			const usages = await Promise.all(providers.map(async (p) => ({
+				p,
+				bytes: (await p.getEvictableUsage({ locationId })).bytes
+			})));
+			const totalUsed = usages.reduce((s, u) => s + u.bytes, 0);
+			const excess = totalUsed - maxBytes;
+			if (excess <= 0) return;
+			let reclaimed = 0;
+			for (const u of usages) {
+				if (u.bytes <= 0) continue;
+				const share = Math.max(1, Math.ceil(excess * u.bytes / totalUsed));
+				const res = await u.p.evict({
+					locationId,
+					targetBytes: share
+				});
+				reclaimed += res.reclaimedBytes;
+			}
+			this.deps.logger.info("storage pressure: usage-cap relief round", { meta: {
+				locationId,
+				round,
+				totalUsed,
+				maxBytes,
+				reclaimedBytes: reclaimed
+			} });
+			if (reclaimed <= 0) return;
+		}
 	}
 	/**
 	* Relieve one location until it recovers, nothing is evictable, or a round
@@ -765,13 +822,21 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 			return reg.getCollection(STORAGE_PROVIDER_CAP_NAME);
 		};
 		const locationStore = this.resolveLocationStore();
-		const service = new StorageOrchestratorService(this.ctx.logger, getProviders, locationStore);
+		const service = new StorageOrchestratorService(this.ctx.logger, getProviders, locationStore, this.ctx.kernel.localNodeId ?? "hub", (nodeId) => {
+			const proxy = this.ctx.kernel.resolveNodeCapability?.("storage-provider", nodeId);
+			if (!proxy) return null;
+			return proxy;
+		});
 		this.service = service;
 		service.setNodeLocalResolver((providerId) => this.nodeLocalByProvider.get(providerId));
 		await service.initialize();
 		const provider = {
 			listLocations: async ({ type }) => {
-				return type !== void 0 ? service.listLocations({ type }) : service.listLocations();
+				const rows = type !== void 0 ? service.listLocations({ type }) : service.listLocations();
+				return Promise.all(rows.map(async (loc) => ({
+					...loc,
+					capacity: await this.localCapacityOf(loc)
+				})));
 			},
 			getDefaultLocation: async ({ type }) => service.getDefaultLocation(type),
 			listLocationDeclarations: async () => service.listDeclarations(),
@@ -937,6 +1002,7 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 			getVolumeTotalBytes: (id) => this.locationVolumeTotalBytes(id),
 			getEvictableProviders: () => this.ctx.kernel.capabilityRegistry?.getCollection(STORAGE_EVICTABLE_CAP_NAME) ?? [],
 			getLocationThresholds: () => this.resolveLocationThresholds(),
+			getLocationMaxUsedBytes: () => this.resolveLocationMaxUsedBytes(),
 			getLocationDeviceKey: (id) => this.locationDeviceKey(id)
 		});
 		this.pressureTimer = setInterval(() => {
@@ -1046,6 +1112,44 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 		}
 		return out;
 	}
+	/** statfs capacity of a location's basePath, walking up to the nearest
+	*  existing ancestor. Null for remote-node locations or unstattable paths. */
+	async localCapacityOf(loc) {
+		if (loc.nodeId !== void 0 && loc.nodeId !== "hub" && loc.nodeId !== this.ctx.nodeId) return null;
+		const bp = loc.config["basePath"];
+		if (typeof bp !== "string" || bp.length === 0) return null;
+		try {
+			let target = path$1.resolve(bp);
+			for (;;) try {
+				await fs.access(target);
+				break;
+			} catch {
+				const parent = path$1.dirname(target);
+				if (!parent || parent === target) return null;
+				target = parent;
+			}
+			const st = await fs.statfs(target);
+			return {
+				totalBytes: st.blocks * st.bsize,
+				availableBytes: st.bavail * st.bsize
+			};
+		} catch {
+			return null;
+		}
+	}
+	/** Per-location cap on EVICTABLE bytes (`config.maxUsedGb`): the operator's
+	*  "recordings may use at most N GB in total" — enforced by the pressure
+	*  manager alongside the free-percent guard. */
+	async resolveLocationMaxUsedBytes() {
+		const out = /* @__PURE__ */ new Map();
+		const svc = this.service;
+		if (!svc) return out;
+		for (const loc of svc.listLocations()) {
+			const raw = loc.config["maxUsedGb"];
+			if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) out.set(loc.id, Math.floor(raw * 1024 ** 3));
+		}
+		return out;
+	}
 	locationBasePath(locationId) {
 		const bp = (this.service?.listLocations().find((l) => l.id === locationId))?.config["basePath"];
 		return typeof bp === "string" && bp.length > 0 ? bp : null;
@@ -1113,10 +1217,12 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 		this.service.setRegistry(registry);
 		this.service.pruneUndeclaredSystemLocations();
 		const mediaRoot = process.env.CAMSTACK_MEDIA_ROOT?.trim();
+		const backupRoot = process.env.CAMSTACK_BACKUP_ROOT?.trim();
 		this.service.seedDefaults({
 			providerId: "filesystem-storage",
 			basePath: this.ctx.nodeDataDir,
 			mediaBasePath: mediaRoot && mediaRoot.length > 0 ? mediaRoot : void 0,
+			backupBasePath: backupRoot && backupRoot.length > 0 ? backupRoot : void 0,
 			declarations: registry.list()
 		});
 		await this.service.backfillNodeIds(HUB_NODE_ID);

package/dist/builtins/storage-orchestrator/storage-orchestrator.service.d.ts

@@ -54,6 +54,11 @@ export declare class StorageOrchestratorService {
      * the provider appears. See {@link attachStore}.
      */
     private locationStore;
+    /** This node's id — locations pinned to OTHER nodes dispatch remotely. */
+    private readonly localNodeId;
+    /** Cross-node provider resolver (hub wiring: a node-routed capability
+     *  proxy over `storage-provider`). Absent → remote locations error. */
+    private readonly getRemoteProvider?;
     private readonly locations;
     /**
      * Declaration-driven cardinality source, injected by the addon after
@@ -85,7 +90,12 @@ export declare class StorageOrchestratorService {
      * service starts store-less and the addon calls {@link attachStore} once
      * the provider appears. See {@link attachStore}.
      */
-    locationStore?: ILocationStore | null);
+    locationStore?: ILocationStore | null, 
+    /** This node's id — locations pinned to OTHER nodes dispatch remotely. */
+    localNodeId?: string, 
+    /** Cross-node provider resolver (hub wiring: a node-routed capability
+     *  proxy over `storage-provider`). Absent → remote locations error. */
+    getRemoteProvider?: ((nodeId: string) => IStorageProviderImpl | null) | undefined);
     /** True once a persistence store is wired (constructor or {@link attachStore}). */
     hasStore(): boolean;
     /**
@@ -235,6 +245,12 @@ export declare class StorageOrchestratorService {
          * `basePath` like everything else.
          */
         readonly mediaBasePath?: string;
+        /**
+         * Root for declarations marked `defaultRoot: 'backup'` (the dedicated
+         * backup volume, `CAMSTACK_BACKUP_ROOT`, default `/backups`). Absent →
+         * backup declarations fall back to `basePath`.
+         */
+        readonly backupBasePath?: string;
         readonly declarations: readonly StorageLocationDeclaration[];
     }): void;
     /** Internal: check whether any location of the given type exists. */

package/dist/builtins/storage-orchestrator/storage-pressure-manager.d.ts

@@ -24,6 +24,9 @@ export interface PressureManagerDeps {
     readonly getEvictableProviders: () => readonly IStorageEvictableProvider[];
     /** locationId → minFreePercent threshold; entries with `<= 0` have the guard off. */
     readonly getLocationThresholds: () => Promise<ReadonlyMap<string, number>>;
+    /** locationId → hard cap on EVICTABLE bytes (`config.maxUsedGb`, operator's
+     *  "recordings may use at most N GB total"). Optional — absent = no caps. */
+    readonly getLocationMaxUsedBytes?: () => Promise<ReadonlyMap<string, number>>;
     /** Max relief rounds per location per sweep (backstop, default 8). */
     readonly maxRounds?: number;
     /** Extra headroom % freed beyond the threshold to avoid re-breaching immediately (default 1). */
@@ -53,6 +56,8 @@ export declare class StoragePressureManager {
     constructor(deps: PressureManagerDeps);
     /** Relieve every managed location currently under its threshold. */
     sweep(): Promise<void>;
+    /** Evict oldest-first until the location's evictable usage fits `maxBytes`. */
+    private relieveToUsageCap;
     /**
      * Relieve one location until it recovers, nothing is evictable, or a round
      * makes no progress. Returns `true` when at least one relief round actually

package/dist/builtins/system-config/system-config.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-OQ1yU92D.js");
+const require_dist = require("../../dist-CS0pdC8l.js");
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/system-config/system-config.addon.mjs

@@ -1,4 +1,4 @@
-import { St as hydrateSchema, at as BaseAddon, it as errMsg } from "../../dist-DmQ6thmF.mjs";
+import { St as hydrateSchema, at as BaseAddon, it as errMsg } from "../../dist-CIek6F9X.mjs";
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/winston-logging/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-OQ1yU92D.js");
+const require_dist = require("../../dist-CS0pdC8l.js");
 const require_formatter = require("../../formatter-DqAKDlvN.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);

package/dist/builtins/winston-logging/index.mjs

@@ -1,4 +1,4 @@
-import { at as BaseAddon, z as logDestinationCapability } from "../../dist-DmQ6thmF.mjs";
+import { at as BaseAddon, z as logDestinationCapability } from "../../dist-CIek6F9X.mjs";
 import { t as formatLogLine } from "../../formatter-B7qW8bPJ.mjs";
 import * as path$1 from "node:path";
 import path from "node:path";