nucleus-core-ts 0.9.985 → 0.9.987

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

@@ -0,0 +1,31 @@
+/**
+ * What the process is HOLDING, counted — because a memory number alone cannot
+ * say where the memory went.
+ *
+ * Measured on a live install: resident memory climbing 119.5 MB/hour with the
+ * JS heap floor flat at 38 MB. Two independent sources agreed (the cgroup's own
+ * working set and `process.memoryUsage().rss`), so the growth is real and it is
+ * native. And there the trail ended: the snapshot recorded memory, CPU,
+ * database connections and Redis — and every one of those was flat.
+ *
+ * Something that grows without bound almost always leaves a countable trace:
+ * a socket that is never closed, a file handle, a worker thread, a subscriber.
+ * These are those counts. They cost one directory listing per collection and
+ * they are the difference between "it died holding 981 MB" and "it died holding
+ * 981 MB and 4,000 open sockets".
+ *
+ * Linux-only by nature — `/proc/self` does not exist elsewhere — and every
+ * field is optional, so a Mac or a BSD simply reports nothing rather than
+ * failing a collection that is otherwise fine.
+ */
+export interface HandleCounts {
+    /** Open file descriptors: sockets, files, pipes, everything. */
+    fileDescriptors?: number;
+    /** Of those, how many are sockets — the usual suspect. */
+    sockets?: number;
+    /** OS threads. A pool that keeps growing shows up here first. */
+    threads?: number;
+    /** The kernel's own ceiling, so a count can be read as a fraction of it. */
+    fileDescriptorLimit?: number;
+}
+export declare function collectHandles(root?: string): HandleCounts;

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

@@ -0,0 +1,48 @@
+/**
+ * WHERE the resident memory is, not just how much of it there is.
+ *
+ * This exists because of a night spent guessing. A live install was climbing
+ * with the JS heap floor flat at 37 MB and `external` at 13 MB, which said the
+ * growth was native and said nothing else. Six hypotheses were tested and
+ * plateaued — request handling, loopback fetch, file serving, aborted range
+ * requests, the dominant endpoint, the JS heap. The one number that would have
+ * cut that short is here: the split between anonymous memory (what the process
+ * allocated) and file-backed memory (what it mapped), plus the kernel's own
+ * accounting of what the cgroup is being charged for.
+ *
+ * The distinction that matters most:
+ *
+ *   anon    grows  → the allocator is holding it. On musl this is usually
+ *                    retention rather than a leak: freed, never returned.
+ *   file    grows  → mapped files or page cache. Reclaimable; not a leak, but
+ *                    it still counts against `memory.max`.
+ *   sock    grows  → network buffers, i.e. sockets nobody is draining.
+ *   slab /
+ *   kernel_stack   → the kernel's share, which usually means threads or fds.
+ *
+ * Linux-only, every field optional: elsewhere it reports nothing rather than
+ * failing a collection that is otherwise fine.
+ */
+export interface NativeMemoryBreakdown {
+    /** Resident anonymous memory — heap, stacks, allocator arenas. Bytes. */
+    anonymous?: number;
+    /** Resident file-backed memory — mapped executables, libraries. Bytes. */
+    fileBacked?: number;
+    /** Resident shared memory. Bytes. */
+    shared?: number;
+    /** Swapped out. Bytes. Non-zero here changes what every other number means. */
+    swapped?: number;
+    /** Distinct mappings in /proc/self/maps. A fragmenting arena shows up here. */
+    mappings?: number;
+    /** cgroup: anonymous charge. Bytes. */
+    cgroupAnon?: number;
+    /** cgroup: page cache charge — reclaimable, but inside the limit. Bytes. */
+    cgroupFile?: number;
+    /** cgroup: socket buffers. Bytes. */
+    cgroupSock?: number;
+    /** cgroup: kernel slab. Bytes. */
+    cgroupSlab?: number;
+    /** cgroup: kernel stacks, i.e. threads. Bytes. */
+    cgroupKernelStack?: number;
+}
+export declare function collectNativeMemory(procRoot?: string, cgroupRoot?: string): NativeMemoryBreakdown;

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

@@ -1,3 +1,5 @@
+import type { HandleCounts } from './collectors/handles';
+import type { NativeMemoryBreakdown } from './collectors/nativeMemory';
 export interface MonitoringConfig {
     enabled?: boolean;
     system?: {
@@ -127,6 +129,26 @@ export interface SystemMetrics {
         uptime: number;
         pid: number;
         eventLoopLag: number;
+        /**
+         * What the process is HOLDING — open descriptors, sockets, threads.
+         *
+         * A memory number alone cannot say where memory went. Measured live:
+         * resident memory climbing 119.5 MB/h with the JS heap floor flat, and
+         * every counter the snapshot DID carry (database, Redis) flat too. The
+         * thing that grows usually leaves a countable trace; these are the counts
+         * that would name it.
+         *
+         * Linux-only, and optional everywhere: a platform without /proc reports
+         * nothing rather than failing the collection.
+         */
+        handles?: HandleCounts;
+        /**
+         * WHERE the resident memory is: anonymous vs file-backed, plus the cgroup's
+         * own breakdown. A memory total says a process is growing; this says which
+         * kind of memory is growing, which is the difference between a hypothesis
+         * and a diagnosis.
+         */
+        nativeMemory?: NativeMemoryBreakdown;
     };
 }
 export interface ApplicationMetrics {

package/package.json

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