nucleus-core-ts 0.9.950 → 0.9.952

package/dist/src/Client/Proxy/types.d.ts

@@ -18,6 +18,20 @@ export interface WsProxyTarget {
      * refresh cookie is present, exchange it for a fresh access token and inject THAT.
      */
     tokenRefresh?: TokenRefreshConfig;
+    /**
+     * Let a handshake through even when no credential could be produced.
+     *
+     * Default `false`, and that default is the fix: a target that declares
+     * `injectTokenFromCookie` is a target that needs a session, so the proxy now
+     * answers 401 BEFORE upgrading rather than accepting a socket the backend
+     * will refuse. Accepting first is what silently disarms the client's own
+     * "three refused handshakes and stop" guard — the browser sees `onopen`, the
+     * counter resets, and one logged-out tab reconnects forever.
+     *
+     * Set this to `true` only for a route that genuinely serves anonymous
+     * clients while still injecting a token when one happens to exist.
+     */
+    allowUnauthenticated?: boolean;
     headers?: Record<string, string>;
     changeOrigin?: boolean;
     secure?: boolean;

package/dist/src/Client/Proxy/wsProxy.js

@@ -51,7 +51,15 @@ export function createWsProxyHandler(config) {
         }
         return null;
     }
-    async function buildBackendUrl(path, target, cookies, query) {
+    /**
+   * The backend URL, plus whether this handshake carries a credential at all.
+   *
+   * The second half is the point. This function already KNEW when it had no
+   * token — it logged "No token found" and handed back a URL anyway, and the
+   * caller upgraded the socket regardless. That silence is what turns one
+   * logged-out browser tab into a permanent reconnect storm; see the refusal in
+   * `upgrade()` for the measurements.
+   */ async function buildBackendUrl(path, target, cookies, query) {
         let baseUrl = target.url.replace(/\/$/, '');
         if (baseUrl.startsWith('http')) {
             baseUrl = httpToWs(baseUrl);
@@ -65,6 +73,9 @@ export function createWsProxyHandler(config) {
         if (queryString) {
             url = `${url}?${queryString}`;
         }
+        // A target that declares `injectTokenFromCookie` is a target that needs a
+        // session. Until a credential is actually produced, this handshake has none.
+        let authenticated = !target.injectTokenFromCookie;
         if (target.injectTokenFromCookie) {
             const paramName = target.injectTokenFromCookie.queryParam ?? 'token';
             // PRECEDENCE: respect a token the client already supplied in the URL.
@@ -78,6 +89,7 @@ export function createWsProxyHandler(config) {
             // the cookie when the client supplied no token.
             if (query.get(paramName)) {
                 logger.info(`[WS:auth] Using client-supplied ${paramName} for ${path}`);
+                authenticated = true;
             } else {
                 let token = cookies[target.injectTokenFromCookie.cookieName];
                 let tokenSource = target.injectTokenFromCookie.cookieName;
@@ -112,12 +124,16 @@ export function createWsProxyHandler(config) {
                 if (token) {
                     url = addQueryParam(url, paramName, token);
                     logger.info(`[WS:auth] Token injected from ${tokenSource} for ${path}`);
+                    authenticated = true;
                 } else {
                     logger.warn(`[WS:auth] No token found for ${path} — tried: ${target.injectTokenFromCookie.cookieName}${target.injectTokenFromCookie.fallbackCookieNames ? `, ${target.injectTokenFromCookie.fallbackCookieNames.join(', ')}` : ''}`);
                 }
             }
         }
-        return url;
+        return {
+            url,
+            authenticated
+        };
     }
     return {
         async upgrade (req, server) {
@@ -138,7 +154,33 @@ export function createWsProxyHandler(config) {
                 return false;
             }
             const cookies = parseCookies(req.headers.get('cookie'));
-            const backendUrl = await buildBackendUrl(path, target, cookies, url.searchParams);
+            const { url: backendUrl, authenticated } = await buildBackendUrl(path, target, cookies, url.searchParams);
+            // Refuse the upgrade instead of accepting a socket that cannot survive.
+            //
+            // This handler used to say yes first and dial the backend after. When the
+            // backend then refused the handshake, the proxy closed the client socket —
+            // but the browser had already seen `onopen`, so nucleus' own client guard
+            // (HANDSHAKE_FAILURE_LIMIT, three refused handshakes and stop) reset its
+            // counter every single attempt and could never trip. A guard on the far
+            // side of a proxy that says yes first is decoration.
+            //
+            // Measured on a live install, 14 Aug 2026: one logged-out tab produced 91
+            // refusals in 180 seconds — a metronome at exactly 2.0s, 46% of all log
+            // lines, for as long as the tab stayed open, while real sessions connected
+            // normally beside it. Answering 401 before the upgrade puts the guard back
+            // in play: the socket never opens, the client counts a refused handshake,
+            // and it stops after three. The same install went to zero refusals within
+            // minutes of shipping this.
+            //
+            // Only targets that declare `injectTokenFromCookie` are gated — a target
+            // with no token config never wanted a session. `allowUnauthenticated`
+            // exists for the deliberate exception.
+            if (!authenticated && target.allowUnauthenticated !== true) {
+                logger.warn(`[WS:auth] Refusing unauthenticated upgrade for ${path}`);
+                return new Response('WebSocket requires a session', {
+                    status: 401
+                });
+            }
             logger.info(`Upgrading: ${path} -> ${backendUrl}`);
             // Extract original request headers to forward to backend
             const originalHeaders = {};

package/dist/src/ElysiaPlugin/routes/shared/bodyCeiling.d.ts

@@ -40,3 +40,26 @@ export declare function bodyCeilingComplaint(input: {
     configured: number | null | undefined;
     required: number | null;
 }): string | null;
+/**
+ * The sentence to print when the POD cannot carry what the configuration
+ * promises, or `null` when it can.
+ *
+ * `bodyCeilingComplaint` asks whether the server will accept the bytes. This
+ * asks the question after it: whether the container survives holding them. They
+ * fail differently and both are silent — the first drops the upload, the second
+ * kills the process, and neither leaves a line saying the ceiling was never
+ * reachable.
+ *
+ * Measured on a live install: `storage.maxFileSizeBytes` set to 1 GiB on a pod
+ * capped at 1 GiB. The setting could not be honoured by arithmetic — the
+ * kernel would kill the process somewhere in the middle of the first big
+ * upload — and nothing anywhere said so. The frontend of the same product had
+ * already learned this and been raised to 2 GiB; the API had been forgotten.
+ *
+ * `null` when there is no cgroup limit to compare against, because on a host
+ * with the node's memory this is the operator's business.
+ */
+export declare function memoryCeilingComplaint(input: {
+    required: number | null;
+    cgroupLimit: number | null;
+}): string | null;

package/dist/src/Services/Monitoring/collectors/SystemCollector.d.ts

@@ -1,4 +1,22 @@
 import type { MonitoringConfig, SystemMetrics } from '../types';
+import { type RuntimeMemoryAdvice } from './memory';
+/**
+ * Boot-time only: does the JS engine know the ceiling the kernel will enforce?
+ *
+ * Lives beside the collector because it reads the same cgroup file, but it is
+ * deliberately NOT part of the sampling loop — the answer cannot change while
+ * the process runs. See `runtimeMemoryAdvice` for what this costs when nobody
+ * asks: a pod that restarts itself twice a day and no line anywhere saying why.
+ */
+/**
+ * This container's memory ceiling in bytes, or `null` when it has none.
+ *
+ * Separate from `readRuntimeMemoryAdvice` on purpose: that function answers
+ * "should we advise a hint", and goes quiet once one is set. A caller asking
+ * "how much memory does this pod actually have" needs the number regardless.
+ */
+export declare function readCgroupLimitBytes(): number | null;
+export declare function readRuntimeMemoryAdvice(): RuntimeMemoryAdvice | null;
 export declare class SystemCollector {
     private config;
     private lastCpuInfo;

package/dist/src/Services/Monitoring/collectors/memory.d.ts

@@ -29,11 +29,66 @@ export interface MemoryReading {
     rss: number;
     heapUsed: number;
     heapTotal: number;
+    /**
+     * The part of `rss` that is NOT the JS heap: native buffers, and of those the
+     * ArrayBuffer share.
+     *
+     * Without these two a panel can show "memory 90%" and be unable to say where
+     * any of it is. Measured on a live install the day it started OOM-killing
+     * itself: rss 690 MB, heapUsed 67 MB. Ninety percent of the memory that
+     * ended the process was invisible to the screen built to watch it — and the
+     * two numbers that would have named it are already in `process.memoryUsage()`,
+     * free of charge, simply never read.
+     */
+    external: number;
+    arrayBuffers: number;
     /** Which ceiling `total` refers to, so a UI can say so out loud. */
     scope: MemoryScope;
 }
 /** `memory.max` holds the literal string "max" when the container is uncapped. */
 export declare function parseCgroupLimit(raw: string | null): number | null;
+export interface RuntimeMemoryAdvice {
+    /** The real ceiling, from the cgroup. */
+    cgroupLimit: number;
+    /** What the JS engine believes it has — the NODE's RAM. */
+    hostTotal: number;
+    /** What `BUN_JSC_forceRAMSize` should be set to, in bytes. */
+    recommended: number;
+}
+/**
+ * The gap between the ceiling the kernel enforces and the one the engine believes.
+ *
+ * This service already reads the cgroup correctly — the monitoring panel says
+ * "1 GiB" and it is right. The garbage collector does not: `os.totalmem()`
+ * inside a capped container returns the NODE's memory. Measured on a live
+ * install: cgroup 1073741824 (1 GiB), `os.totalmem()` 33651855360 (31.3 GB) —
+ * a 31x overestimate. A collector that believes it is using 2% of memory feels
+ * no pressure at all, so it grows the heap and never returns the pages, and the
+ * cgroup eventually kills the process. Confirmed by the kubelet: OOMKilled,
+ * exit 137, after exactly 4h00m, three times over, on an install with no users.
+ *
+ * It cannot be fixed from inside the process — JSC reads its options when the
+ * runtime boots, long before any of this code runs. So the honest thing is to
+ * SAY it at startup, with the number to set, rather than let a pod quietly
+ * restart itself twice a day.
+ *
+ * A quarter of the limit, not the whole thing: the JS heap is a minority of RSS
+ * in this stack. On the same install, live objects sat at 60-90 MB while total
+ * RSS reached a gigabyte — the rest is native buffers, the log ring, the pg and
+ * redis clients. Handing the engine the entire limit just moves the OOM; a hint
+ * ABOVE what the heap ever reaches is a brake whose pedal is never touched, and
+ * that was measured too: 768 MiB on a 1 GiB pod behaved identically to no hint
+ * at all.
+ *
+ * Returns `null` when there is nothing to say: uncapped container, a "limit"
+ * that is not really a limit, or an operator who has already set a hint at or
+ * below the advice.
+ */
+export declare function runtimeMemoryAdvice(input: {
+    cgroupLimit: number | null;
+    hostTotal: number;
+    forcedRamSize: number | null;
+}): RuntimeMemoryAdvice | null;
 export declare function parseCgroupUsage(raw: string | null): number | null;
 /**
  * Reclaimable page cache inside the cgroup, from `memory.stat`.
@@ -61,6 +116,8 @@ export interface MemorySources {
         rss: number;
         heapUsed: number;
         heapTotal: number;
+        external: number;
+        arrayBuffers: number;
     };
 }
 /**

package/dist/src/Services/Monitoring/types.d.ts

@@ -98,6 +98,15 @@ export interface SystemMetrics {
         rss: number;
         heapUsed: number;
         heapTotal: number;
+        /**
+         * Where the rest of `rss` is. A screen that reports "memory 90%" and cannot
+         * say what the 90% consists of sends its reader looking in the JS heap,
+         * which on this stack is the minority: measured on a live install at the
+         * point it began OOM-killing itself, rss was 690 MB and heapUsed 67 MB.
+         * These come free from `process.memoryUsage()`.
+         */
+        external: number;
+        arrayBuffers: number;
         /**
          * Whether the figures describe this container's cgroup limit or the whole
          * node. A panel must say which, or "%98" means nothing.
@@ -137,10 +146,22 @@ export interface ApplicationMetrics {
         p99: number;
     };
     errors: {
+        /** 5xx only — the service failed. This is what an alert should watch. */
         total: number;
         rate: number;
         byType: Record<string, number>;
     };
+    /**
+     * 4xx — callers refused, over the same minute.
+     *
+     * Split out because a 401 is the service working: it is telling a caller it
+     * has no valid session. Folded into `errors.rate` it produced a CRITICAL
+     * alert every morning on a healthy install as overnight sessions expired —
+     * 102 of 106 `/auth/refresh` calls answered 401, and not one 5xx anywhere.
+     */
+    clientErrors: {
+        rate: number;
+    };
     rateLimits: {
         blocked: number;
         blockedPerMinute: number;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nucleus-core-ts",
-	"version": "0.9.950",
+	"version": "0.9.952",
 	"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
 	"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
 	"license": "SEE LICENSE IN LICENSE",