@camstack/system 1.2.63 → 1.2.64

package/dist/{model-download-service-D8B-4ktF.mjs → model-download-service-CTBHzORJ.mjs}

@@ -4,6 +4,8 @@ import * as fs from "node:fs";
 import { createReadStream, promises } from "node:fs";
 import * as path$1 from "node:path";
 import path from "node:path";
+import { promisify } from "node:util";
+import { brotliCompress, constants as constants$1, gzip } from "node:zlib";
 //#region src/http/authenticated-file-server.ts
 /**
 * Authenticated data-plane file-server — a shared host primitive for addons that
@@ -214,6 +216,188 @@ async function handle(opts, cors, req, res) {
 	createReadStream(absPath).pipe(res);
 }
 //#endregion
+//#region src/http/asset-compression.ts
+/**
+* Content-coding for addon-served static assets: `Accept-Encoding` negotiation,
+* an eligibility rule, and a BOUNDED cache of the compressed bytes.
+*
+* ## Why the ADDON owns the encoding
+*
+* The hub's `/addon/:addonId/*` bridge is registered `{ compress: false }`. That
+* is not an oversight — on 2026-07-16 the global `@fastify/compress` was found
+* emitting an EMPTY brotli stream (`content-encoding: br`, `content-length: 0`)
+* for any compressible body over its 1 KiB threshold once the body had crossed
+* the UDS route bridge of a FORKED addon. It silently broke the notifier SVG
+* icons; the deploy-bundle pull route had already dodged the same class with
+* `compress: false`. The resolution then, and the contract now, is that an addon
+* route owns its content-coding END TO END: it negotiates, it compresses, it
+* stamps `content-encoding` + `Vary`, and the hub pipes those bytes through
+* untouched (`proxyToUpstream` replays the upstream headers verbatim).
+*
+* So compression belongs HERE, in the shared file data-plane, and nowhere above
+* it. Anything that re-compresses on top of this reintroduces the empty-brotli
+* bug rather than doubling the ratio.
+*
+* ## Why the bytes are cached, and why the cache is bounded
+*
+* Measured on the stream-broker embed bundle (`index-<hash>.js`, 1,443,142 B):
+* gzip-6 → 360,868 B, brotli-5 → 327,419 B in 27 ms, brotli-11 → 293,677 B in
+* 2,233 ms. Quality 5 is the request-path choice: 77% off the wire for 27 ms
+* paid ONCE. Quality 11 buys another 2.3% for eighty times the CPU, on a path
+* where a real client is waiting.
+*
+* The cache is an LRU bounded by BOTH entry count and total bytes, and it
+* refuses assets over {@link COMPRESSION_MAX_ASSET_BYTES} outright. An unbounded
+* `Map` keyed by URL is how a long-lived process walks into an OOM, and this
+* repo has already spent a session on one.
+*
+* The key carries `mtimeMs` and `size`, so a rebuild that rewrites an asset in
+* place under an UNCHANGED name (an SPA shell, a service worker) can never be
+* served from the previous build's bytes.
+*/
+var brotliAsync = promisify(brotliCompress);
+var gzipAsync = promisify(gzip);
+/** LRU bounds. Both are enforced; whichever binds first evicts. */
+var MAX_CACHE_ENTRIES = 64;
+var MAX_CACHE_BYTES = 32 * 1024 * 1024;
+/** Brotli quality — see the file header for the measured trade. */
+var BROTLI_QUALITY = 5;
+/**
+* Content types worth compressing. An ALLOW-list, not a deny-list: an unknown
+* type (`application/octet-stream`) is assumed to be opaque binary. This is what
+* keeps jpeg/png/webp/mp4/m4s/woff2 out — running brotli over them burns CPU to
+* make the body marginally BIGGER.
+*/
+var COMPRESSIBLE_EXACT = new Set([
+	"application/javascript",
+	"application/ecmascript",
+	"application/json",
+	"application/manifest+json",
+	"application/wasm",
+	"application/xml",
+	"application/xhtml+xml",
+	"application/vnd.apple.mpegurl",
+	"image/svg+xml"
+]);
+/** Is a body of this content type worth compressing at all? */
+function isCompressibleContentType(contentType) {
+	const base = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+	if (base.length === 0) return false;
+	if (base.startsWith("text/")) return true;
+	if (base.endsWith("+json") || base.endsWith("+xml")) return true;
+	return COMPRESSIBLE_EXACT.has(base);
+}
+/** Parse `Accept-Encoding` into tokens with their q-values (default 1). */
+function parseAcceptEncoding(header) {
+	if (header === void 0 || header.trim().length === 0) return [];
+	const out = [];
+	for (const part of header.split(",")) {
+		const [rawToken, ...params] = part.split(";");
+		const token = rawToken?.trim().toLowerCase() ?? "";
+		if (token.length === 0) continue;
+		let q = 1;
+		for (const param of params) {
+			const [name, value] = param.split("=");
+			if (name?.trim().toLowerCase() !== "q") continue;
+			const parsed = Number(value?.trim());
+			q = Number.isFinite(parsed) ? parsed : 1;
+		}
+		out.push({
+			token,
+			q
+		});
+	}
+	return out;
+}
+function accepts(prefs, token) {
+	const exact = prefs.find((p) => p.token === token);
+	if (exact) return exact.q > 0;
+	const wildcard = prefs.find((p) => p.token === "*");
+	return wildcard !== void 0 && wildcard.q > 0;
+}
+/**
+* Pick a coding for this request: brotli when offered, else gzip, else identity.
+*
+* Returns `null` for identity — including when the header is ABSENT. A client
+* that offers nothing gets the raw bytes; guessing on its behalf is how a
+* non-negotiating consumer (a native fetch, a probe, an OTA puller) ends up with
+* a body it cannot read.
+*/
+function negotiateContentEncoding(acceptEncoding) {
+	const prefs = parseAcceptEncoding(acceptEncoding);
+	if (prefs.length === 0) return null;
+	if (accepts(prefs, "br")) return "br";
+	if (accepts(prefs, "gzip")) return "gzip";
+	return null;
+}
+var cache = /* @__PURE__ */ new Map();
+var inFlight = /* @__PURE__ */ new Map();
+var compressions = 0;
+var hits = 0;
+var cachedBytes = 0;
+function cacheKey(key) {
+	return `${key.encoding}|${String(key.mtimeMs)}|${String(key.size)}|${key.path}`;
+}
+/** Evict least-recently-used entries until both bounds hold. */
+function evictToBounds() {
+	for (const [k, buf] of cache) {
+		if (cache.size <= MAX_CACHE_ENTRIES && cachedBytes <= MAX_CACHE_BYTES) return;
+		cache.delete(k);
+		cachedBytes -= buf.byteLength;
+	}
+}
+async function compressBody(raw, encoding) {
+	if (encoding === "gzip") return await gzipAsync(raw);
+	return await brotliAsync(raw, { params: {
+		[constants$1.BROTLI_PARAM_QUALITY]: BROTLI_QUALITY,
+		[constants$1.BROTLI_PARAM_SIZE_HINT]: raw.byteLength
+	} });
+}
+/**
+* Compressed bytes for one asset, compressing at most once per key.
+*
+* `null` means "send the original" — the asset is too large to buffer, the
+* source could not be read, or compression did not actually shrink it. Every
+* failure degrades to identity, so this can only ever be an optimisation.
+*
+* Concurrent callers for the same key share ONE compression: a cold cache hit by
+* a dozen parallel asset requests must not run zlib a dozen times.
+*/
+async function getCompressedAsset(key, readSource) {
+	if (key.size > 8388608) return null;
+	const id = cacheKey(key);
+	const cached = cache.get(id);
+	if (cached) {
+		cache.delete(id);
+		cache.set(id, cached);
+		hits += 1;
+		return cached;
+	}
+	const pending = inFlight.get(id) ?? (async () => {
+		let raw;
+		try {
+			raw = await readSource();
+		} catch {
+			return null;
+		}
+		const out = await compressBody(raw, key.encoding);
+		compressions += 1;
+		if (out.byteLength >= raw.byteLength) return null;
+		cache.set(id, out);
+		cachedBytes += out.byteLength;
+		evictToBounds();
+		return out;
+	})();
+	inFlight.set(id, pending);
+	try {
+		return await pending;
+	} catch {
+		return null;
+	} finally {
+		inFlight.delete(id);
+	}
+}
+//#endregion
 //#region src/http/file-data-plane.ts
 /**
 * A ready-made data-plane request handler that serves files from a set of roots
@@ -226,6 +410,11 @@ async function handle(opts, cors, req, res) {
 * the hub already authenticated the caller and the data plane is same-origin
 * through the hub's port. Reuses the shared Range/content-type/traversal helpers
 * so there is one implementation across the standalone file-server and this.
+*
+* It also owns its own CONTENT-CODING. The hub bridge is `{ compress: false }`
+* because the global compressor emits an empty brotli stream over the forked-
+* addon route bridge, so nothing above this layer will ever compress an addon
+* body — see `asset-compression.ts` for the incident and the contract.
 */
 /** Build a `(req, res)` handler that serves `getRoots()` files with Range. */
 function createFileDataPlaneHandler(opts) {
@@ -253,11 +442,13 @@ function createFileDataPlaneHandler(opts) {
 		}
 		let absPath = null;
 		let size = 0;
+		let mtimeMs = 0;
 		for (const candidate of resolved.candidates) try {
 			const st = await promises.stat(candidate);
 			if (st.isFile()) {
 				absPath = candidate;
 				size = st.size;
+				mtimeMs = st.mtimeMs;
 				break;
 			}
 		} catch {}
@@ -265,10 +456,13 @@ function createFileDataPlaneHandler(opts) {
 			res.writeHead(404).end();
 			return;
 		}
+		const contentType = contentTypeFor(absPath, opts.contentTypes);
+		const compressible = isCompressibleContentType(contentType);
 		const baseHeaders = {
-			"content-type": contentTypeFor(absPath, opts.contentTypes),
+			"content-type": contentType,
 			"accept-ranges": "bytes",
-			"cache-control": opts.cacheControl?.(rel) ?? "no-cache"
+			"cache-control": opts.cacheControl?.(rel) ?? "no-cache",
+			...compressible ? { vary: "accept-encoding" } : {}
 		};
 		const range = parseRangeHeader(req.headers.range, size);
 		if (range) {
@@ -287,6 +481,30 @@ function createFileDataPlaneHandler(opts) {
 			}).pipe(res);
 			return;
 		}
+		const encoding = compressible ? negotiateContentEncoding(req.headers["accept-encoding"]) : null;
+		if (encoding !== null && size >= 1024) {
+			const filePath = absPath;
+			const body = await getCompressedAsset({
+				path: filePath,
+				mtimeMs,
+				size,
+				encoding
+			}, () => promises.readFile(filePath));
+			if (body !== null) {
+				res.writeHead(200, {
+					...baseHeaders,
+					"content-encoding": encoding,
+					"accept-ranges": "none",
+					"content-length": String(body.byteLength)
+				});
+				if (req.method === "HEAD") {
+					res.end();
+					return;
+				}
+				res.end(body);
+				return;
+			}
+		}
 		res.writeHead(200, {
 			...baseHeaders,
 			"content-length": String(size)

package/dist/{model-download-service-Cpc6SWzV.js → model-download-service-Caj1kaSi.js}

@@ -5,6 +5,8 @@ let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
+let node_util = require("node:util");
+let node_zlib = require("node:zlib");
 //#region src/http/authenticated-file-server.ts
 /**
 * Authenticated data-plane file-server — a shared host primitive for addons that
@@ -215,6 +217,188 @@ async function handle(opts, cors, req, res) {
 	(0, node_fs.createReadStream)(absPath).pipe(res);
 }
 //#endregion
+//#region src/http/asset-compression.ts
+/**
+* Content-coding for addon-served static assets: `Accept-Encoding` negotiation,
+* an eligibility rule, and a BOUNDED cache of the compressed bytes.
+*
+* ## Why the ADDON owns the encoding
+*
+* The hub's `/addon/:addonId/*` bridge is registered `{ compress: false }`. That
+* is not an oversight — on 2026-07-16 the global `@fastify/compress` was found
+* emitting an EMPTY brotli stream (`content-encoding: br`, `content-length: 0`)
+* for any compressible body over its 1 KiB threshold once the body had crossed
+* the UDS route bridge of a FORKED addon. It silently broke the notifier SVG
+* icons; the deploy-bundle pull route had already dodged the same class with
+* `compress: false`. The resolution then, and the contract now, is that an addon
+* route owns its content-coding END TO END: it negotiates, it compresses, it
+* stamps `content-encoding` + `Vary`, and the hub pipes those bytes through
+* untouched (`proxyToUpstream` replays the upstream headers verbatim).
+*
+* So compression belongs HERE, in the shared file data-plane, and nowhere above
+* it. Anything that re-compresses on top of this reintroduces the empty-brotli
+* bug rather than doubling the ratio.
+*
+* ## Why the bytes are cached, and why the cache is bounded
+*
+* Measured on the stream-broker embed bundle (`index-<hash>.js`, 1,443,142 B):
+* gzip-6 → 360,868 B, brotli-5 → 327,419 B in 27 ms, brotli-11 → 293,677 B in
+* 2,233 ms. Quality 5 is the request-path choice: 77% off the wire for 27 ms
+* paid ONCE. Quality 11 buys another 2.3% for eighty times the CPU, on a path
+* where a real client is waiting.
+*
+* The cache is an LRU bounded by BOTH entry count and total bytes, and it
+* refuses assets over {@link COMPRESSION_MAX_ASSET_BYTES} outright. An unbounded
+* `Map` keyed by URL is how a long-lived process walks into an OOM, and this
+* repo has already spent a session on one.
+*
+* The key carries `mtimeMs` and `size`, so a rebuild that rewrites an asset in
+* place under an UNCHANGED name (an SPA shell, a service worker) can never be
+* served from the previous build's bytes.
+*/
+var brotliAsync = (0, node_util.promisify)(node_zlib.brotliCompress);
+var gzipAsync = (0, node_util.promisify)(node_zlib.gzip);
+/** LRU bounds. Both are enforced; whichever binds first evicts. */
+var MAX_CACHE_ENTRIES = 64;
+var MAX_CACHE_BYTES = 32 * 1024 * 1024;
+/** Brotli quality — see the file header for the measured trade. */
+var BROTLI_QUALITY = 5;
+/**
+* Content types worth compressing. An ALLOW-list, not a deny-list: an unknown
+* type (`application/octet-stream`) is assumed to be opaque binary. This is what
+* keeps jpeg/png/webp/mp4/m4s/woff2 out — running brotli over them burns CPU to
+* make the body marginally BIGGER.
+*/
+var COMPRESSIBLE_EXACT = new Set([
+	"application/javascript",
+	"application/ecmascript",
+	"application/json",
+	"application/manifest+json",
+	"application/wasm",
+	"application/xml",
+	"application/xhtml+xml",
+	"application/vnd.apple.mpegurl",
+	"image/svg+xml"
+]);
+/** Is a body of this content type worth compressing at all? */
+function isCompressibleContentType(contentType) {
+	const base = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+	if (base.length === 0) return false;
+	if (base.startsWith("text/")) return true;
+	if (base.endsWith("+json") || base.endsWith("+xml")) return true;
+	return COMPRESSIBLE_EXACT.has(base);
+}
+/** Parse `Accept-Encoding` into tokens with their q-values (default 1). */
+function parseAcceptEncoding(header) {
+	if (header === void 0 || header.trim().length === 0) return [];
+	const out = [];
+	for (const part of header.split(",")) {
+		const [rawToken, ...params] = part.split(";");
+		const token = rawToken?.trim().toLowerCase() ?? "";
+		if (token.length === 0) continue;
+		let q = 1;
+		for (const param of params) {
+			const [name, value] = param.split("=");
+			if (name?.trim().toLowerCase() !== "q") continue;
+			const parsed = Number(value?.trim());
+			q = Number.isFinite(parsed) ? parsed : 1;
+		}
+		out.push({
+			token,
+			q
+		});
+	}
+	return out;
+}
+function accepts(prefs, token) {
+	const exact = prefs.find((p) => p.token === token);
+	if (exact) return exact.q > 0;
+	const wildcard = prefs.find((p) => p.token === "*");
+	return wildcard !== void 0 && wildcard.q > 0;
+}
+/**
+* Pick a coding for this request: brotli when offered, else gzip, else identity.
+*
+* Returns `null` for identity — including when the header is ABSENT. A client
+* that offers nothing gets the raw bytes; guessing on its behalf is how a
+* non-negotiating consumer (a native fetch, a probe, an OTA puller) ends up with
+* a body it cannot read.
+*/
+function negotiateContentEncoding(acceptEncoding) {
+	const prefs = parseAcceptEncoding(acceptEncoding);
+	if (prefs.length === 0) return null;
+	if (accepts(prefs, "br")) return "br";
+	if (accepts(prefs, "gzip")) return "gzip";
+	return null;
+}
+var cache = /* @__PURE__ */ new Map();
+var inFlight = /* @__PURE__ */ new Map();
+var compressions = 0;
+var hits = 0;
+var cachedBytes = 0;
+function cacheKey(key) {
+	return `${key.encoding}|${String(key.mtimeMs)}|${String(key.size)}|${key.path}`;
+}
+/** Evict least-recently-used entries until both bounds hold. */
+function evictToBounds() {
+	for (const [k, buf] of cache) {
+		if (cache.size <= MAX_CACHE_ENTRIES && cachedBytes <= MAX_CACHE_BYTES) return;
+		cache.delete(k);
+		cachedBytes -= buf.byteLength;
+	}
+}
+async function compressBody(raw, encoding) {
+	if (encoding === "gzip") return await gzipAsync(raw);
+	return await brotliAsync(raw, { params: {
+		[node_zlib.constants.BROTLI_PARAM_QUALITY]: BROTLI_QUALITY,
+		[node_zlib.constants.BROTLI_PARAM_SIZE_HINT]: raw.byteLength
+	} });
+}
+/**
+* Compressed bytes for one asset, compressing at most once per key.
+*
+* `null` means "send the original" — the asset is too large to buffer, the
+* source could not be read, or compression did not actually shrink it. Every
+* failure degrades to identity, so this can only ever be an optimisation.
+*
+* Concurrent callers for the same key share ONE compression: a cold cache hit by
+* a dozen parallel asset requests must not run zlib a dozen times.
+*/
+async function getCompressedAsset(key, readSource) {
+	if (key.size > 8388608) return null;
+	const id = cacheKey(key);
+	const cached = cache.get(id);
+	if (cached) {
+		cache.delete(id);
+		cache.set(id, cached);
+		hits += 1;
+		return cached;
+	}
+	const pending = inFlight.get(id) ?? (async () => {
+		let raw;
+		try {
+			raw = await readSource();
+		} catch {
+			return null;
+		}
+		const out = await compressBody(raw, key.encoding);
+		compressions += 1;
+		if (out.byteLength >= raw.byteLength) return null;
+		cache.set(id, out);
+		cachedBytes += out.byteLength;
+		evictToBounds();
+		return out;
+	})();
+	inFlight.set(id, pending);
+	try {
+		return await pending;
+	} catch {
+		return null;
+	} finally {
+		inFlight.delete(id);
+	}
+}
+//#endregion
 //#region src/http/file-data-plane.ts
 /**
 * A ready-made data-plane request handler that serves files from a set of roots
@@ -227,6 +411,11 @@ async function handle(opts, cors, req, res) {
 * the hub already authenticated the caller and the data plane is same-origin
 * through the hub's port. Reuses the shared Range/content-type/traversal helpers
 * so there is one implementation across the standalone file-server and this.
+*
+* It also owns its own CONTENT-CODING. The hub bridge is `{ compress: false }`
+* because the global compressor emits an empty brotli stream over the forked-
+* addon route bridge, so nothing above this layer will ever compress an addon
+* body — see `asset-compression.ts` for the incident and the contract.
 */
 /** Build a `(req, res)` handler that serves `getRoots()` files with Range. */
 function createFileDataPlaneHandler(opts) {
@@ -254,11 +443,13 @@ function createFileDataPlaneHandler(opts) {
 		}
 		let absPath = null;
 		let size = 0;
+		let mtimeMs = 0;
 		for (const candidate of resolved.candidates) try {
 			const st = await node_fs.promises.stat(candidate);
 			if (st.isFile()) {
 				absPath = candidate;
 				size = st.size;
+				mtimeMs = st.mtimeMs;
 				break;
 			}
 		} catch {}
@@ -266,10 +457,13 @@ function createFileDataPlaneHandler(opts) {
 			res.writeHead(404).end();
 			return;
 		}
+		const contentType = contentTypeFor(absPath, opts.contentTypes);
+		const compressible = isCompressibleContentType(contentType);
 		const baseHeaders = {
-			"content-type": contentTypeFor(absPath, opts.contentTypes),
+			"content-type": contentType,
 			"accept-ranges": "bytes",
-			"cache-control": opts.cacheControl?.(rel) ?? "no-cache"
+			"cache-control": opts.cacheControl?.(rel) ?? "no-cache",
+			...compressible ? { vary: "accept-encoding" } : {}
 		};
 		const range = parseRangeHeader(req.headers.range, size);
 		if (range) {
@@ -288,6 +482,30 @@ function createFileDataPlaneHandler(opts) {
 			}).pipe(res);
 			return;
 		}
+		const encoding = compressible ? negotiateContentEncoding(req.headers["accept-encoding"]) : null;
+		if (encoding !== null && size >= 1024) {
+			const filePath = absPath;
+			const body = await getCompressedAsset({
+				path: filePath,
+				mtimeMs,
+				size,
+				encoding
+			}, () => node_fs.promises.readFile(filePath));
+			if (body !== null) {
+				res.writeHead(200, {
+					...baseHeaders,
+					"content-encoding": encoding,
+					"accept-ranges": "none",
+					"content-length": String(body.byteLength)
+				});
+				if (req.method === "HEAD") {
+					res.end();
+					return;
+				}
+				res.end(body);
+				return;
+			}
+		}
 		res.writeHead(200, {
 			...baseHeaders,
 			"content-length": String(size)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.63",
+  "version": "1.2.64",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",

package/dist/{manifest-python-deps-DNfmBu20.js → manifest-python-deps-BE6l8Y4W.js}

@@ -7,9 +7,9 @@ let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
+let node_util = require("node:util");
 let _camstack_types_addon = require("@camstack/types/addon");
 let node_child_process = require("node:child_process");
-let node_util = require("node:util");
 let node_os = require("node:os");
 node_os = require_chunk.__toESM(node_os);
 let node_fs_promises = require("node:fs/promises");

package/dist/{manifest-python-deps-CopL1_5C.mjs → manifest-python-deps-Dz1ryHIN.mjs}

@@ -5,9 +5,9 @@ import { createServer } from "node:http";
 import * as fs from "node:fs";
 import * as path$1 from "node:path";
 import { isAbsolute, join } from "node:path";
+import { promisify } from "node:util";
 import { DATAPLANE_SECRET_HEADER, DeviceType, DisposerChain, EventCategory, ReadinessRegistry, asJsonObject, asString, createDeviceProxy, deviceOpsCapability, emitReadiness, errMsg, expandCapMethods, readNodePin, scopeKey, sleep, withCapInputDefaults } from "@camstack/types/addon";
 import { execFile } from "node:child_process";
-import { promisify } from "node:util";
 import * as os from "node:os";
 import { tmpdir } from "node:os";
 import { unlink } from "node:fs/promises";