@zero-server/observe 0.9.1 → 0.9.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Tony Wiedman
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Tony Wiedman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.js

@@ -1,27 +1,27 @@
 // AUTO-GENERATED by .tools/generate-package-stubs.js — edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
 'use strict';
-const sdk = require("@zero-server/sdk");
+const lib = require("./lib/observe");
 
 module.exports = {
-    Logger: sdk.Logger,
-    structuredLogger: sdk.structuredLogger,
-    Counter: sdk.Counter,
-    Gauge: sdk.Gauge,
-    Histogram: sdk.Histogram,
-    MetricsRegistry: sdk.MetricsRegistry,
-    DEFAULT_BUCKETS: sdk.DEFAULT_BUCKETS,
-    createDefaultMetrics: sdk.createDefaultMetrics,
-    metricsMiddleware: sdk.metricsMiddleware,
-    metricsEndpoint: sdk.metricsEndpoint,
-    Span: sdk.Span,
-    Tracer: sdk.Tracer,
-    parseTraceparent: sdk.parseTraceparent,
-    formatTraceparent: sdk.formatTraceparent,
-    tracingMiddleware: sdk.tracingMiddleware,
-    instrumentFetch: sdk.instrumentFetch,
-    healthCheck: sdk.healthCheck,
-    createHealthHandlers: sdk.createHealthHandlers,
-    memoryCheck: sdk.memoryCheck,
-    eventLoopCheck: sdk.eventLoopCheck,
-    diskSpaceCheck: sdk.diskSpaceCheck,
+    Logger: lib.Logger,
+    structuredLogger: lib.structuredLogger,
+    Counter: lib.Counter,
+    Gauge: lib.Gauge,
+    Histogram: lib.Histogram,
+    MetricsRegistry: lib.MetricsRegistry,
+    DEFAULT_BUCKETS: lib.DEFAULT_BUCKETS,
+    createDefaultMetrics: lib.createDefaultMetrics,
+    metricsMiddleware: lib.metricsMiddleware,
+    metricsEndpoint: lib.metricsEndpoint,
+    Span: lib.Span,
+    Tracer: lib.Tracer,
+    parseTraceparent: lib.parseTraceparent,
+    formatTraceparent: lib.formatTraceparent,
+    tracingMiddleware: lib.tracingMiddleware,
+    instrumentFetch: lib.instrumentFetch,
+    healthCheck: lib.healthCheck,
+    createHealthHandlers: lib.createHealthHandlers,
+    memoryCheck: lib.memoryCheck,
+    eventLoopCheck: lib.eventLoopCheck,
+    diskSpaceCheck: lib.diskSpaceCheck,
 };

package/lib/observe/health.js

@@ -0,0 +1,326 @@
+/**
+ * @module observe/health
+ * @description Health check middleware with liveness and readiness probes.
+ *              Kubernetes-compatible `/healthz` and `/readyz` endpoints with
+ *              composable checks (database ping, memory, event loop lag,
+ *              disk space) and custom check registration.
+ *
+ *              Returns `200` when healthy, `503` when degraded or during
+ *              shutdown drain phase, with a JSON body detailing each check.
+ *
+ * @example
+ *   const { healthCheck } = require('@zero-server/sdk');
+ *
+ *   app.get('/healthz', healthCheck());
+ *   app.get('/readyz', healthCheck({
+ *       checks: {
+ *           database: () => db.ping(),
+ *           cache: () => redis.ping(),
+ *       },
+ *   }));
+ *
+ * @example | Using the App Integration
+ *   app.health('/healthz');
+ *   app.ready('/readyz', {
+ *       database: () => db.ping(),
+ *   });
+ */
+const os = require('os');
+
+// -- Built-in Checks -----------------------------------------------
+
+/**
+ * Check memory usage against a threshold.
+ *
+ * @param {object} [opts] - Check options.
+ * @param {number} [opts.maxHeapUsedPercent=90] - Max heap usage percentage.
+ * @param {number} [opts.maxRssBytes] - Max RSS in bytes.
+ * @returns {Function} Check function.
+ *
+ * @example
+ *   app.get('/healthz', healthCheck({
+ *       checks: { memory: memoryCheck({ maxHeapUsedPercent: 85 }) },
+ *   }));
+ */
+function memoryCheck(opts = {})
+{
+    const maxPercent = typeof opts.maxHeapUsedPercent === 'number' ? opts.maxHeapUsedPercent : 90;
+    const maxRss = opts.maxRssBytes || Infinity;
+
+    return () =>
+    {
+        const mem = process.memoryUsage();
+        const heapPercent = (mem.heapUsed / mem.heapTotal) * 100;
+        const healthy = heapPercent < maxPercent && mem.rss < maxRss;
+
+        return {
+            healthy,
+            details: {
+                heapUsed: mem.heapUsed,
+                heapTotal: mem.heapTotal,
+                heapPercent: Math.round(heapPercent * 100) / 100,
+                rss: mem.rss,
+                external: mem.external,
+            },
+        };
+    };
+}
+
+/**
+ * Check event loop lag against a threshold.
+ *
+ * @param {object} [opts] - Check options.
+ * @param {number} [opts.maxLagMs=500] - Max acceptable lag in ms.
+ * @returns {Function} Check function.
+ *
+ * @example
+ *   app.get('/healthz', healthCheck({
+ *       checks: { eventLoop: eventLoopCheck({ maxLagMs: 200 }) },
+ *   }));
+ */
+function eventLoopCheck(opts = {})
+{
+    const maxLag = opts.maxLagMs || 500;
+    let _lastCheck = process.hrtime.bigint();
+    let _lag = 0;
+
+    // Sample event loop lag periodically
+    const _check = () =>
+    {
+        const now = process.hrtime.bigint();
+        const expected = 1_000_000_000n; // 1 second in nanoseconds
+        const actual = now - _lastCheck;
+        _lag = Math.max(0, Number(actual - expected) / 1e6); // ms
+        _lastCheck = now;
+    };
+
+    const timer = setInterval(_check, 1000);
+    if (timer.unref) timer.unref();
+
+    const check = () => ({
+        healthy: _lag < maxLag,
+        details: { lagMs: Math.round(_lag * 100) / 100, maxLagMs: maxLag },
+    });
+
+    // Expose cleanup for testing
+    check._cleanup = () => clearInterval(timer);
+    return check;
+}
+
+/**
+ * Check available disk space (simple heuristic using os.freemem).
+ *
+ * @param {object} [opts] - Check options.
+ * @param {number} [opts.minFreeBytes=104857600] - Minimum free memory in bytes (default: 100MB).
+ * @returns {Function} Check function.
+ */
+function diskSpaceCheck(opts = {})
+{
+    const minFree = opts.minFreeBytes || 104857600; // 100MB
+
+    return () =>
+    {
+        const free = os.freemem();
+        return {
+            healthy: free > minFree,
+            details: {
+                freeMemory: free,
+                totalMemory: os.totalmem(),
+                minRequired: minFree,
+            },
+        };
+    };
+}
+
+// -- Health Check Handler ------------------------------------------
+
+/**
+ * Create a health check route handler.
+ *
+ * Returns a JSON response with the status of all registered checks.
+ * Returns `200` when all checks pass, `503` when any check fails
+ * or when the application is in drain/shutdown state.
+ *
+ * Response format:
+ * ```json
+ * {
+ *   "status": "healthy",
+ *   "uptime": 12345,
+ *   "timestamp": "2026-01-01T00:00:00.000Z",
+ *   "checks": {
+ *     "database": { "healthy": true, "duration": 5, "details": {} }
+ *   }
+ * }
+ * ```
+ *
+ * @param {object} [opts] - Options.
+ * @param {Object<string, Function>} [opts.checks] - Named check functions. Each returns `{ healthy, details }` or a boolean/Promise.
+ * @param {number} [opts.timeout=5000] - Max time to wait for all checks in ms.
+ * @param {boolean} [opts.verbose=true] - Include check details in response.
+ * @param {Function} [opts.onFailure] - `(results) => void` — called when any check fails.
+ * @returns {Function} Route handler `(req, res) => void`.
+ *
+ * @example
+ *   app.get('/healthz', healthCheck());
+ *
+ * @example
+ *   app.get('/readyz', healthCheck({
+ *       checks: {
+ *           database: async () => {
+ *               await db.ping();
+ *               return { healthy: true };
+ *           },
+ *           cache: () => ({ healthy: cacheClient.isConnected }),
+ *       },
+ *   }));
+ *
+ * @example | Auto-deregister from Load Balancer
+ *   app.get('/readyz', healthCheck({
+ *       checks: {
+ *           lifecycle: () => ({ healthy: app.lifecycleState === 'running' }),
+ *       },
+ *   }));
+ */
+function healthCheck(opts = {})
+{
+    const checks = opts.checks || {};
+    const timeout = opts.timeout || 5000;
+    const verbose = opts.verbose !== false;
+    const onFailure = typeof opts.onFailure === 'function' ? opts.onFailure : null;
+
+    return async (req, res) =>
+    {
+        const start = Date.now();
+
+        // Check lifecycle state (auto-deregister during shutdown)
+        const app = req.app;
+        if (app && app.lifecycleState && app.lifecycleState !== 'running')
+        {
+            res.status(503).json({
+                status: 'unavailable',
+                reason: 'shutdown',
+                lifecycleState: app.lifecycleState,
+                timestamp: new Date().toISOString(),
+            });
+            return;
+        }
+
+        const checkNames = Object.keys(checks);
+        const results = {};
+        let allHealthy = true;
+
+        if (checkNames.length > 0)
+        {
+            // Run all checks concurrently with timeout
+            const promises = checkNames.map(async (name) =>
+            {
+                const checkStart = Date.now();
+                try
+                {
+                    const result = await Promise.race([
+                        Promise.resolve(checks[name]()),
+                        new Promise((_, reject) =>
+                            setTimeout(() => reject(new Error('Check timed out')), timeout)
+                        ),
+                    ]);
+
+                    const duration = Date.now() - checkStart;
+
+                    if (typeof result === 'boolean')
+                    {
+                        results[name] = { healthy: result, duration };
+                    }
+                    else if (result && typeof result === 'object')
+                    {
+                        results[name] = { healthy: !!result.healthy, duration };
+                        if (verbose && result.details) results[name].details = result.details;
+                    }
+                    else
+                    {
+                        results[name] = { healthy: true, duration };
+                    }
+                }
+                catch (err)
+                {
+                    results[name] = {
+                        healthy: false,
+                        duration: Date.now() - checkStart,
+                        error: err.message,
+                    };
+                }
+
+                if (!results[name].healthy) allHealthy = false;
+            });
+
+            await Promise.all(promises);
+        }
+
+        const body = {
+            status: allHealthy ? 'healthy' : 'unhealthy',
+            uptime: process.uptime(),
+            timestamp: new Date().toISOString(),
+            duration: Date.now() - start,
+        };
+
+        if (checkNames.length > 0) body.checks = results;
+
+        if (!allHealthy && onFailure)
+        {
+            try { onFailure(results); }
+            catch (_) { /* ignore callback errors */ }
+        }
+
+        res.status(allHealthy ? 200 : 503).json(body);
+    };
+}
+
+// -- Convenience Health & Ready Factory ----------------------------
+
+/**
+ * Create paired liveness and readiness handlers for an app.
+ * Liveness includes basic process checks; readiness includes
+ * all registered dependency checks.
+ *
+ * @param {object} [opts] - Options.
+ * @param {Object<string, Function>} [opts.checks] - Named readiness checks.
+ * @param {boolean} [opts.includeMemory=false] - Include memory check in liveness.
+ * @param {boolean} [opts.includeEventLoop=false] - Include event loop lag check.
+ * @param {number} [opts.timeout=5000] - Check timeout.
+ * @returns {{ health: Function, ready: Function }} Route handlers.
+ *
+ * @example
+ *   const { health, ready } = createHealthHandlers({
+ *       checks: { database: () => db.ping() },
+ *       includeMemory: true,
+ *   });
+ *   app.get('/healthz', health);
+ *   app.get('/readyz', ready);
+ */
+function createHealthHandlers(opts = {})
+{
+    const livenessChecks = {};
+    if (opts.includeMemory) livenessChecks.memory = memoryCheck(opts.memoryOpts);
+    if (opts.includeEventLoop) livenessChecks.eventLoop = eventLoopCheck(opts.eventLoopOpts);
+
+    const readinessChecks = { ...livenessChecks };
+    if (opts.checks)
+    {
+        for (const [name, fn] of Object.entries(opts.checks))
+        {
+            readinessChecks[name] = fn;
+        }
+    }
+
+    return {
+        health: healthCheck({ checks: livenessChecks, timeout: opts.timeout }),
+        ready: healthCheck({ checks: readinessChecks, timeout: opts.timeout, onFailure: opts.onFailure }),
+    };
+}
+
+module.exports = {
+    healthCheck,
+    createHealthHandlers,
+    memoryCheck,
+    eventLoopCheck,
+    diskSpaceCheck,
+};

package/lib/observe/index.js

@@ -0,0 +1,50 @@
+/**
+ * @module observe
+ * @description Observability suite — structured logging, metrics, tracing,
+ *              and health checks. Zero external dependencies.
+ */
+const { Logger, structuredLogger, LEVELS, LEVEL_NAMES } = require('./logger');
+const {
+    Counter, Gauge, Histogram,
+    MetricsRegistry, DEFAULT_BUCKETS,
+    createDefaultMetrics, metricsMiddleware, metricsEndpoint,
+} = require('./metrics');
+const {
+    Span, Tracer,
+    parseTraceparent, formatTraceparent,
+    tracingMiddleware, instrumentFetch,
+} = require('./tracing');
+const {
+    healthCheck, createHealthHandlers,
+    memoryCheck, eventLoopCheck, diskSpaceCheck,
+} = require('./health');
+
+module.exports = {
+    // Structured Logging
+    Logger,
+    structuredLogger,
+    LEVELS,
+    LEVEL_NAMES,
+    // Metrics
+    Counter,
+    Gauge,
+    Histogram,
+    MetricsRegistry,
+    DEFAULT_BUCKETS,
+    createDefaultMetrics,
+    metricsMiddleware,
+    metricsEndpoint,
+    // Tracing
+    Span,
+    Tracer,
+    parseTraceparent,
+    formatTraceparent,
+    tracingMiddleware,
+    instrumentFetch,
+    // Health Checks
+    healthCheck,
+    createHealthHandlers,
+    memoryCheck,
+    eventLoopCheck,
+    diskSpaceCheck,
+};