@hydranium/core 1.0.0-next.10

package/lib/node/process-memory.js

@@ -0,0 +1,252 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+/*
+ * Node-only process- and pod-level memory introspection plus heap-snapshot
+ * writing. Everything here is generic OS-level code (V8 stats, cgroup v2/v1,
+ * `/proc`); the only host-specific part is naming the processes, which a head
+ * supplies through a `ProcessClassifier`.
+ */
+import { Format } from '@hydranium/protocol';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as v8 from 'node:v8';
+/**
+ * Format a one-shot memory snapshot of the CURRENT process (heap, rss, external, V8 limit).
+ * Suited to a process that hosts no Langium documents (e.g. a host backend); for the
+ * language-server process with document counts, see `formatServerState`.
+ */
+export function formatProcessMemory(label) {
+    const mem = process.memoryUsage();
+    const heap = v8.getHeapStatistics();
+    const heapPercent = Math.round((mem.heapUsed / heap.heap_size_limit) * 100);
+    return [
+        `${label}:`,
+        `  heap      ${Format.bytes(mem.heapUsed)} used / ${Format.bytes(mem.heapTotal)} total / ` +
+            `${Format.bytes(heap.heap_size_limit)} limit (${heapPercent}% of limit)`,
+        `  rss       ${Format.bytes(mem.rss)}, external ${Format.bytes(mem.external)}, arrayBuffers ${Format.bytes(mem.arrayBuffers)}`,
+        `  uptime    ${Math.round(process.uptime())}s, pid ${process.pid}`
+    ].join('\n');
+}
+/**
+ * Compose an absolute artifact file path of the form `<prefix>[-<label>].<ext>` inside
+ * {@link directory} (e.g. the workspace folder, so it lands on the persistent volume in cloud and
+ * is visible in the file explorer), falling back to the OS temp dir when the directory is missing
+ * or does not exist. The {@link prefix} carries the origin-first stem (e.g. `server-cpu`) and, when
+ * a non-empty {@link label} is given (a named capture window), it is sanitised (non-word characters
+ * → `_`, truncated to 40 chars) and appended as `-<label>`; an empty label yields the bare
+ * `<prefix>.<ext>` so the manifest `kind` equals the filename stem. No timestamp — a fresh session
+ * directory per run keeps names stable and collision-free. Shared by the heap-snapshot writer and
+ * the sampled-profile capture so heap / CPU / allocation artefacts land identically, differing only
+ * by extension.
+ */
+export function snapshotFilePath(directory, label, prefix, ext) {
+    const safeLabel = label ? label.replace(/[^\w.-]+/g, '_').slice(0, 40) : '';
+    const dir = directory && fs.existsSync(directory) ? directory : os.tmpdir();
+    const stem = safeLabel ? `${prefix}-${safeLabel}` : prefix;
+    return path.join(dir, `${stem}.${ext}`);
+}
+/**
+ * Write a V8 heap snapshot of the CURRENT process to {@link directory}, falling back to the OS temp
+ * dir when it is missing (see {@link snapshotFilePath}). `v8.writeHeapSnapshot` runs a full GC first and
+ * briefly pauses the process; it also transiently inflates RSS while serialising. Returns the
+ * absolute file path. The {@link prefix} (default `server-heap`, the origin-first stem) and
+ * {@link label} are folded into the name.
+ */
+export function writeHeapSnapshotToDir(directory, label, prefix = 'server-heap') {
+    const filePath = snapshotFilePath(directory, label, prefix, 'heapsnapshot');
+    v8.writeHeapSnapshot(filePath);
+    return filePath;
+}
+const CGROUP_ROOT = '/sys/fs/cgroup';
+function readNumber(file) {
+    try {
+        const text = fs.readFileSync(file, 'utf8').trim();
+        if (text === 'max') {
+            return Number.POSITIVE_INFINITY;
+        }
+        const value = Number(text);
+        return Number.isFinite(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parse a `key value` per-line file (cgroup memory.stat) into a map. */
+function readKeyedBytes(file) {
+    const out = {};
+    try {
+        for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+            const [key, value] = line.trim().split(/\s+/);
+            if (key && value !== undefined) {
+                const num = Number(value);
+                if (Number.isFinite(num)) {
+                    out[key] = num;
+                }
+            }
+        }
+    }
+    catch {
+        // file absent or unreadable; caller handles the empty map.
+    }
+    return out;
+}
+/** Generic fallback: every process is shown under the app heading, labelled by its (truncated) command line. */
+const defaultProcessClassifier = cmdline => ({ role: cmdline ? cmdline.slice(0, 60) : 'process', isApp: true });
+/** Read /proc for every visible process: pid, ppid, RSS, and a command label. */
+function readAllProcs() {
+    const procs = [];
+    let entries = [];
+    try {
+        entries = fs.readdirSync('/proc');
+    }
+    catch {
+        return procs;
+    }
+    for (const entry of entries) {
+        if (!/^\d+$/.test(entry)) {
+            continue;
+        }
+        let status = '';
+        try {
+            status = fs.readFileSync(`/proc/${entry}/status`, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const rssMatch = status.match(/^VmRSS:\s+(\d+)\s+kB/m);
+        if (!rssMatch) {
+            continue;
+        }
+        const ppid = Number(status.match(/^PPid:\s+(\d+)/m)?.[1] ?? 0);
+        let label = '';
+        try {
+            label = fs.readFileSync(`/proc/${entry}/cmdline`, 'utf8').replace(/\0/g, ' ').trim();
+        }
+        catch {
+            // fall back to the process name from status below.
+        }
+        if (!label) {
+            label = status.match(/^Name:\s+(.+)$/m)?.[1] ?? `pid ${entry}`;
+        }
+        procs.push({ pid: Number(entry), ppid, rssBytes: Number(rssMatch[1]) * 1024, label });
+    }
+    return procs;
+}
+/**
+ * Sum and list per-process RSS. When {@link rootPid} is given, restrict to that process and its
+ * descendants (the app's own process tree), which keeps the figure meaningful in local dev where
+ * /proc otherwise shows the whole machine. In a container's PID namespace the tree is effectively
+ * all the pod's processes anyway.
+ */
+function collectProcessRss(rootPid) {
+    const all = readAllProcs();
+    let selected = all;
+    let scoped = false;
+    if (rootPid !== undefined) {
+        const childrenByPpid = new Map();
+        for (const proc of all) {
+            (childrenByPpid.get(proc.ppid) ?? childrenByPpid.set(proc.ppid, []).get(proc.ppid)).push(proc);
+        }
+        const tree = [];
+        const queue = all.filter(proc => proc.pid === rootPid);
+        while (queue.length > 0) {
+            const proc = queue.shift();
+            tree.push(proc);
+            queue.push(...(childrenByPpid.get(proc.pid) ?? []));
+        }
+        if (tree.length > 0) {
+            selected = tree;
+            scoped = true;
+        }
+    }
+    const total = selected.reduce((sum, proc) => sum + proc.rssBytes, 0);
+    selected.sort((a, b) => b.rssBytes - a.rssBytes);
+    return { total, processes: selected, scoped };
+}
+/**
+ * Format a pod/container-level memory snapshot read from the cgroup this process belongs to
+ * (cgroup v2 `memory.current`/`peak`/`max`/`stat`, falling back to cgroup v1). This is the figure
+ * the Kubernetes OOM-killer watches — it covers every process in the pod plus page cache and kernel
+ * memory, so it is higher than any single `process.memoryUsage().rss`. Also sums per-process RSS so
+ * the per-process split is visible. Explains itself when no cgroup memory controller is present
+ * (e.g. local dev outside a container).
+ */
+export function formatPodMemory(options = {}) {
+    const classify = options.classify ?? defaultProcessClassifier;
+    const appLabel = options.appLabel ?? 'Application';
+    const lines = ['Pod memory snapshot:'];
+    const v2Current = path.join(CGROUP_ROOT, 'memory.current');
+    const v1Usage = path.join(CGROUP_ROOT, 'memory', 'memory.usage_in_bytes');
+    if (fs.existsSync(v2Current)) {
+        const current = readNumber(v2Current);
+        const peak = readNumber(path.join(CGROUP_ROOT, 'memory.peak'));
+        const max = readNumber(path.join(CGROUP_ROOT, 'memory.max'));
+        const stat = readKeyedBytes(path.join(CGROUP_ROOT, 'memory.stat'));
+        lines.push('  cgroup    v2');
+        lines.push(`  current   ${current !== undefined ? Format.bytes(current) : 'n/a'}`);
+        lines.push(`  peak      ${peak !== undefined ? Format.bytes(peak) : 'n/a (kernel too old for memory.peak)'}`);
+        lines.push(`  limit     ${max === Number.POSITIVE_INFINITY ? 'unlimited' : max !== undefined ? Format.bytes(max) : 'n/a'}`);
+        if (Object.keys(stat).length > 0) {
+            lines.push(`  breakdown anon ${Format.bytes(stat.anon ?? 0)} (heaps/stacks), file ${Format.bytes(stat.file ?? 0)} (page cache), ` +
+                `kernel ${Format.bytes(stat.kernel ?? stat.slab ?? 0)}, sock ${Format.bytes(stat.sock ?? 0)}`);
+        }
+    }
+    else if (fs.existsSync(v1Usage)) {
+        const v1 = path.join(CGROUP_ROOT, 'memory');
+        const current = readNumber(v1Usage);
+        const peak = readNumber(path.join(v1, 'memory.max_usage_in_bytes'));
+        const limit = readNumber(path.join(v1, 'memory.limit_in_bytes'));
+        const stat = readKeyedBytes(path.join(v1, 'memory.stat'));
+        lines.push('  cgroup    v1');
+        lines.push(`  current   ${current !== undefined ? Format.bytes(current) : 'n/a'}`);
+        lines.push(`  peak      ${peak !== undefined ? Format.bytes(peak) : 'n/a'}`);
+        // v1 reports a huge sentinel for "unlimited"; treat anything >= 2^60 as unlimited.
+        lines.push(`  limit     ${limit !== undefined && limit < 2 ** 60 ? Format.bytes(limit) : 'unlimited'}`);
+        if (Object.keys(stat).length > 0) {
+            lines.push(`  breakdown rss ${Format.bytes(stat.rss ?? 0)}, cache ${Format.bytes(stat.cache ?? 0)} (page cache), ` +
+                `kernel ${Format.bytes(stat.kernel ?? 0)}`);
+        }
+    }
+    else {
+        lines.push('  cgroup    no memory controller under /sys/fs/cgroup (not running in a container?)');
+    }
+    // Root at this process so local dev reports only the app's tree, not the whole machine.
+    const { processes } = collectProcessRss(process.pid);
+    if (processes.length > 0) {
+        const classified = processes.map(proc => ({ ...proc, ...classify(proc.label) }));
+        const appProcs = classified.filter(proc => proc.isApp);
+        const otherProcs = classified.filter(proc => !proc.isApp);
+        const appTotal = appProcs.reduce((sum, proc) => sum + proc.rssBytes, 0);
+        lines.push('');
+        lines.push(`  ${appLabel}: ${Format.bytes(appTotal)} across ${appProcs.length} process(es)`);
+        for (const proc of appProcs) {
+            lines.push(`    ${Format.bytes(proc.rssBytes).padStart(10)}  ${proc.role}  (pid ${proc.pid})`);
+        }
+        const singletonCounts = new Map();
+        for (const proc of appProcs) {
+            if (proc.singletonExpected) {
+                singletonCounts.set(proc.role, (singletonCounts.get(proc.role) ?? 0) + 1);
+            }
+        }
+        for (const [role, count] of singletonCounts) {
+            if (count > 1) {
+                lines.push(`  WARNING: ${count} instances of "${role}" running - likely ghost process(es); expected 1`);
+            }
+        }
+        if (otherProcs.length > 0) {
+            const otherTotal = otherProcs.reduce((sum, proc) => sum + proc.rssBytes, 0);
+            lines.push(`  Other (tooling/debugger, not counted above): ${Format.bytes(otherTotal)} across ${otherProcs.length} process(es)`);
+        }
+        lines.push('  Note: in a real pod the cgroup figure above is the OOM ceiling; this per-process');
+        lines.push('  split is for attribution. Local dev may include debugger processes (excluded here).');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=process-memory.js.map

package/lib/node/process-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-memory.js","sourceRoot":"","sources":["../../src/node/process-memory.ts"],"names":[],"mappings":"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"}

package/lib/node/profile-capture.d.ts

@@ -0,0 +1,118 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type ProfileCaptureOptions } from '@hydranium/protocol';
+import { PerformanceObserver, type IntervalHistogram } from 'node:perf_hooks';
+export declare const DEFAULT_CPU_INTERVAL_MICROS = 1000;
+export declare const DEFAULT_ALLOCATION_INTERVAL_BYTES = 32768;
+export type { ProfileCaptureOptions };
+/** One GC pause: the numeric V8 kind flag and its duration in ms. */
+export interface GcEntry {
+    kind: number;
+    durationMs: number;
+}
+/** The `count`/`mean`/`max`/`percentile` surface of a `node:perf_hooks` event-loop-delay histogram (ns). */
+export interface EventLoopDelayHistogram {
+    readonly count: number;
+    readonly mean: number;
+    readonly max: number;
+    percentile(percent: number): number;
+}
+/** The captured artefacts + a compact summary. Profile files are written to the session directory. */
+export interface ProfileReport {
+    durationMs: number;
+    cpuProfilePath?: string;
+    allocationProfilePath?: string;
+    heapSnapshotPath?: string;
+    gc?: {
+        count: number;
+        totalPauseMs: number;
+        byKind: Record<string, {
+            count: number;
+            pauseMs: number;
+        }>;
+    };
+    eventLoopDelay?: {
+        meanMs: number;
+        p50Ms: number;
+        p99Ms: number;
+        maxMs: number;
+    };
+    cpuUsage: {
+        userMs: number;
+        systemMs: number;
+    };
+    memoryDelta: {
+        rssBytes: number;
+        heapUsedBytes: number;
+    };
+}
+/**
+ * Tally GC pauses by kind, mapping V8's numeric kind flag to a readable name.
+ * Pure — the timing-dependent capture feeds it the entries.
+ */
+export declare function summarizeGc(entries: readonly GcEntry[]): NonNullable<ProfileReport['gc']>;
+/**
+ * Convert an event-loop-delay histogram (nanoseconds) to a millisecond summary,
+ * or `undefined` when the histogram recorded nothing (a purely synchronous
+ * window never lets the sampler tick, leaving `mean === NaN`). Pure.
+ */
+export declare function summarizeEventLoopDelay(histogram: EventLoopDelayHistogram): NonNullable<ProfileReport['eventLoopDelay']> | undefined;
+/**
+ * Render a {@link ProfileReport} as a compact multi-line block for a log line or a
+ * command channel — the sampled-profile counterpart to `formatProcessMemory`.
+ * Absent dimensions (no gc/eld capture, no written artefacts) are simply omitted.
+ */
+export declare function formatProfileReport(report: ProfileReport, label?: string): string;
+/** Minimal structural view of a `node:inspector` `Session` — its typed per-method overloads can't be called generically. */
+interface InspectorSessionLike {
+    connect(): void;
+    disconnect(): void;
+    post(method: string, params: Record<string, unknown>, callback: (error: Error | null, result?: unknown) => void): void;
+}
+/**
+ * A windowed, sampled profile of the current process. Start it, run the workload,
+ * stop it to get artefact paths + a summary. Singleton-guarded (one inspector
+ * session at a time); prefer {@link profileWorkload} for the common wrap-a-block case.
+ */
+export declare class ProfileCapture {
+    protected readonly options: ProfileCaptureOptions;
+    protected startedAt: number;
+    protected startCpu: NodeJS.CpuUsage;
+    protected startMem: NodeJS.MemoryUsage;
+    protected session?: InspectorSessionLike;
+    protected histogram?: IntervalHistogram;
+    protected gcObserver?: PerformanceObserver;
+    protected gcEntries: GcEntry[];
+    protected constructor(options: ProfileCaptureOptions);
+    static isActive(): boolean;
+    static start(options: ProfileCaptureOptions): Promise<ProfileCapture>;
+    protected begin(): Promise<void>;
+    stop(directory: string | undefined, label: string): Promise<ProfileReport>;
+    /**
+     * Release the inspector session, perf_hooks observers and the process-wide
+     * singleton. Each disposal is best-effort so one failure cannot skip the rest
+     * (or mask the error that triggered teardown), and nulling the handles makes a
+     * repeat teardown a no-op.
+     */
+    protected teardown(): void;
+    protected writeProfileFile(profile: unknown, directory: string | undefined, label: string, prefix: string, ext: string): string;
+}
+/**
+ * Capture a subset of dimensions around an arbitrary async block — the harness /
+ * bench / CLI entry. Always releases the singleton session, even if {@link run}
+ * throws (the error propagates). Writes profile files to `options.directory`.
+ */
+export declare function profileWorkload<T>(options: ProfileCaptureOptions & {
+    directory?: string;
+    label?: string;
+}, run: () => Promise<T>): Promise<{
+    result: T;
+    report: ProfileReport;
+}>;
+//# sourceMappingURL=profile-capture.d.ts.map

package/lib/node/profile-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-capture.d.ts","sourceRoot":"","sources":["../../src/node/profile-capture.ts"],"names":[],"mappings":"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"}