@camstack/server 1.2.47 → 1.2.48

package/dist/api/static/precompressed-asset.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Brotli-compressed copies of static SPA assets, cached on disk.
+ *
+ * The hub re-compressed the viewer's 6.7 MB bundle from disk on EVERY uncached
+ * load: measured `time_starttransfer` 0.622 s with brotli against 0.017 s
+ * without. That is 0.6 s of hub CPU before the first byte, paid again by every
+ * client, for a file whose content is content-hashed and therefore never
+ * changes.
+ *
+ * Populated lazily on the first request rather than at build time, and that is
+ * the important choice. The two SPAs reach this hub down DIFFERENT ship chains
+ * — the admin-ui through a deployed addon dist, the viewer through its own
+ * export — and a build step wired into one of them silently stops covering the
+ * other. A cache built from whatever is on disk cannot fall behind either.
+ *
+ * The first request for a given file still pays the compression, exactly as
+ * every request does today. Every request after it pays nothing.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acceptsBrotli = acceptsBrotli;
+exports.isCompressibleAsset = isCompressibleAsset;
+exports.resolvePrecompressedAsset = resolvePrecompressedAsset;
+exports.resetPrecompressedWarning = resetPrecompressedWarning;
+exports.precompressedSiblingExists = precompressedSiblingExists;
+const fs = __importStar(require("node:fs"));
+const fsp = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const node_zlib_1 = require("node:zlib");
+const node_util_1 = require("node:util");
+const brotli = (0, node_util_1.promisify)(node_zlib_1.brotliCompress);
+/** Below this, the framing costs more than the compression saves — the same
+ *  threshold `@fastify/compress` is registered with. */
+const MIN_BYTES = 1024;
+/** Types worth compressing. Images and fonts are already compressed; running
+ *  brotli over a JPEG burns CPU to make it marginally bigger. */
+const COMPRESSIBLE = /\.(js|mjs|cjs|css|html|json|svg|map|txt|webmanifest|wasm)$/i;
+/** One in-flight compression per path, so a cold cache hit by twelve parallel
+ *  asset requests compresses once instead of twelve times. */
+const inFlight = new Map();
+/** Logged once per process — a read-only dist is a deployment fact, not an
+ *  error to repeat on every asset. */
+let warnedUnwritable = false;
+/** Does the client accept brotli? */
+function acceptsBrotli(acceptEncoding) {
+    if (acceptEncoding === undefined)
+        return false;
+    return /\bbr\b/.test(acceptEncoding);
+}
+function isCompressibleAsset(relOrAbs) {
+    return COMPRESSIBLE.test(relOrAbs);
+}
+/**
+ * A `.br` sibling is only valid while it is NEWER than its source.
+ *
+ * A redeploy rewrites an asset in place under an unchanged name (the SPA shell
+ * and the service worker both do), and a stale sibling would serve the previous
+ * build forever — the exact failure mode of every cache that skips this check.
+ */
+async function freshSibling(filePath, brPath) {
+    try {
+        const [src, br] = await Promise.all([fsp.stat(filePath), fsp.stat(brPath)]);
+        return br.mtimeMs >= src.mtimeMs && br.size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function compressToDisk(filePath, brPath, log) {
+    try {
+        const raw = await fsp.readFile(filePath);
+        const out = await brotli(raw, {
+            params: {
+                // Quality 11 is worth it BECAUSE this runs once. The per-request path
+                // could never afford it, which is why it was set to 4.
+                [node_zlib_1.constants.BROTLI_PARAM_QUALITY]: 11,
+                [node_zlib_1.constants.BROTLI_PARAM_SIZE_HINT]: raw.byteLength,
+            },
+        });
+        // Write via a temp file + rename so a concurrent reader never sees a
+        // half-written body.
+        const tmp = `${brPath}.${String(process.pid)}.tmp`;
+        await fsp.writeFile(tmp, out);
+        await fsp.rename(tmp, brPath);
+        log?.('precompressed a static asset', {
+            file: path.basename(filePath),
+            rawBytes: raw.byteLength,
+            brBytes: out.byteLength,
+        });
+        return brPath;
+    }
+    catch (err) {
+        if (!warnedUnwritable) {
+            warnedUnwritable = true;
+            log?.('cannot cache precompressed assets — serving compressed per request', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        return null;
+    }
+}
+/**
+ * Resolve what to actually send for one static asset.
+ *
+ * Returns the original with `encoding: null` whenever anything is off — the
+ * client does not accept brotli, the file is not worth compressing, or the
+ * cache could not be written. The caller then serves exactly what it served
+ * before, so this can only ever be an optimisation.
+ */
+async function resolvePrecompressedAsset(filePath, acceptEncoding, log) {
+    const plain = { filePath, encoding: null };
+    if (!acceptsBrotli(acceptEncoding) || !isCompressibleAsset(filePath))
+        return plain;
+    let size = 0;
+    try {
+        size = (await fsp.stat(filePath)).size;
+    }
+    catch {
+        return plain;
+    }
+    if (size < MIN_BYTES)
+        return plain;
+    const brPath = `${filePath}.br`;
+    if (await freshSibling(filePath, brPath))
+        return { filePath: brPath, encoding: 'br' };
+    const pending = inFlight.get(filePath) ?? compressToDisk(filePath, brPath, log);
+    inFlight.set(filePath, pending);
+    try {
+        const produced = await pending;
+        return produced === null ? plain : { filePath: produced, encoding: 'br' };
+    }
+    finally {
+        inFlight.delete(filePath);
+    }
+}
+/** Test seam — the "read-only dist" warning is once per process. */
+function resetPrecompressedWarning() {
+    warnedUnwritable = false;
+}
+/** Synchronous existence probe used by the callers' own guards. */
+function precompressedSiblingExists(filePath) {
+    return fs.existsSync(`${filePath}.br`);
+}

package/dist/main.js

@@ -86,6 +86,7 @@ const system_2 = require("@camstack/system");
 const session_cookie_js_1 = require("./auth/session-cookie.js");
 const health_routes_1 = require("./api/health/health.routes");
 const spa_static_1 = require("./api/static/spa-static");
+const precompressed_asset_js_1 = require("./api/static/precompressed-asset.js");
 const oauth2_routes_js_1 = require("./api/oauth2/oauth2-routes.js");
 const system_3 = require("@camstack/system");
 const boot_config_1 = require("./boot/boot-config");
@@ -177,6 +178,43 @@ function cleanupOrphanProcesses() {
         console.log(`[cleanup] Killed ${killed} orphaned camstack process(es) from a previous run`);
     }
 }
+/**
+ * Send a static SPA asset, preferring a cached brotli copy.
+ *
+ * Setting `content-encoding` is what stops `@fastify/compress` from running:
+ * its `onSend` hook bails out when the reply already declares an encoding
+ * other than `identity` (`@fastify/compress/index.js:250`). Verified in the
+ * plugin, not assumed — a second pass over an already-compressed body would
+ * reach the client as garbage.
+ *
+ * The content type is set from the ORIGINAL path. The file being streamed is
+ * `<name>.br`, and inferring from that would label a JavaScript bundle
+ * `application/brotli`, which no browser will execute.
+ *
+ * Every failure path serves the original file unchanged, so this can only ever
+ * be an optimisation: a client that does not accept brotli, an image, a
+ * read-only dist and a missing file all end up on exactly the previous
+ * behaviour.
+ */
+async function sendMaybePrecompressed(reply, absolutePath, acceptEncoding) {
+    if (reply.getHeader('content-type') === undefined) {
+        reply.type((0, spa_static_1.contentTypeForPath)(absolutePath));
+    }
+    const resolved = await (0, precompressed_asset_js_1.resolvePrecompressedAsset)(absolutePath, acceptEncoding, (msg, meta) => console.log(`[static] ${msg} ${JSON.stringify(meta)}`));
+    if (resolved.encoding === 'br') {
+        reply.header('content-encoding', 'br');
+        reply.header('vary', 'accept-encoding');
+    }
+    // `sendFile` used to set this; a raw stream would go out chunked, which
+    // costs the client its download progress and any length-based preload.
+    try {
+        reply.header('content-length', String(fs.statSync(resolved.filePath).size));
+    }
+    catch {
+        // Racing a redeploy that replaced the file — chunked is a fine fallback.
+    }
+    return reply.send(fs.createReadStream(resolved.filePath));
+}
 // ---- Bootstrap ----
 async function bootstrap() {
     // hub-main's own memory, on the record. Deliberately started HERE and not in
@@ -904,7 +942,33 @@ async function bootstrap() {
         console.log('[bootstrap] OAuth2 routes registered at /api/oauth2/*');
         // Attach tRPC WebSocket handler using noServer mode to avoid
         // Fastify intercepting the upgrade request with a 400 response.
-        const wss = new ws_2.WebSocketServer({ noServer: true });
+        //
+        // `perMessageDeflate` is NOT the default — `ws` ships it off — and the
+        // viewer talks to us over `wsLink` EXCLUSIVELY, so without this every
+        // boot response travelled uncompressed while the HTTP routes were getting
+        // brotli. Measured on the live hub: `deviceManager.listAll` is 271 KB raw
+        // and 22 KB brotli, and the whole viewer boot is ~1.8 MB of tRPC JSON.
+        //
+        // The zlib settings are deliberately conservative rather than maximal.
+        // `serverNoContextTakeover` + a 1024-byte window mean each connection
+        // keeps NO persistent deflate context between messages: it costs a few
+        // points of ratio and it bounds per-socket memory, which is the trade this
+        // hub wants — it has hit a heap ceiling before, and a compression context
+        // per viewer is exactly the kind of growth that is invisible until it is
+        // not. `threshold` leaves small frames (subscription ticks) alone, where
+        // framing overhead would exceed the saving.
+        const wss = new ws_2.WebSocketServer({
+            noServer: true,
+            perMessageDeflate: {
+                threshold: 1024,
+                zlibDeflateOptions: { level: 3, memLevel: 7, chunkSize: 16 * 1024 },
+                zlibInflateOptions: { chunkSize: 16 * 1024 },
+                serverNoContextTakeover: true,
+                clientNoContextTakeover: true,
+                serverMaxWindowBits: 10,
+                concurrencyLimit: 10,
+            },
+        });
         (0, ws_1.applyWSSHandler)({
             wss,
             router: appRouter,
@@ -1063,7 +1127,7 @@ async function bootstrap() {
                             // build assets (assets/index-<hash>.js) are immutable. Everything
                             // else gets a short cache.
                             reply.header('cache-control', (0, spa_static_1.spaAssetCacheControl)(rel));
-                            return reply.sendFile(rel);
+                            return sendMaybePrecompressed(reply, abs, request.headers['accept-encoding']);
                         }
                         return reply.callNotFound();
                     }
@@ -1143,7 +1207,7 @@ async function bootstrap() {
                         if ((abs === staticDir || abs.startsWith(staticDir + path.sep)) && fs.existsSync(abs)) {
                             reply.header('cache-control', (0, spa_static_1.spaAssetCacheControl)(rel));
                             reply.type((0, spa_static_1.contentTypeForPath)(rel));
-                            return reply.send(fs.createReadStream(abs));
+                            return sendMaybePrecompressed(reply, abs, request.headers['accept-encoding']);
                         }
                         return reply.callNotFound();
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.2.47",
+  "version": "1.2.48",
   "private": false,
   "files": [
     "dist",
@@ -40,12 +40,12 @@
     "@camstack/addon-notifiers": "1.2.12",
     "@camstack/addon-pipeline": "1.2.40",
     "@camstack/addon-pipeline-orchestrator": "1.2.21",
-    "@camstack/addon-post-analysis": "1.2.30",
+    "@camstack/addon-post-analysis": "1.2.31",
     "@camstack/sdk": "1.2.9",
     "@camstack/shm-ring": "1.1.9",
-    "@camstack/system": "1.2.39",
-    "@camstack/types": "1.2.28",
-    "@camstack/ui-library": "1.2.22",
+    "@camstack/system": "1.2.40",
+    "@camstack/types": "1.2.29",
+    "@camstack/ui-library": "1.2.23",
     "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^11.2.0",