b2b-platform-utils 1.1.95 → 1.1.96

package/README.md

@@ -8,6 +8,29 @@ This package centralizes small, repeated helpers used across services so they ca
 
 ---
 
+## Service lifecycle
+
+`lifecycle.js` provides single-flight bootstrap, bounded dependency retry with exponential
+backoff and jitter, structured lifecycle events, readiness state, and ordered bounded
+shutdown hooks. Services keep ownership of their dependency order and cleanup actions.
+
+```js
+const { createLifecycle } = require('b2b-platform-utils/lifecycle');
+
+const lifecycle = createLifecycle({ service: 'example' });
+lifecycle.registerSignalHandlers();
+lifecycle.registerFatalHandlers();
+
+void lifecycle.bootstrap(async () => {
+  await lifecycle.connect('config', ({ deadline }) => loadConfig({ deadline }));
+});
+```
+
+Lifecycle and dependency events are emitted as one JSON object per line and include the
+process instance identity, deployment version, phase, and timing fields.
+
+---
+
 ## Install
 
 ```bash

package/lifecycle.js

@@ -0,0 +1,482 @@
+'use strict';
+
+const { structuredEvent } = require('./logger');
+const { setService } = require('./localCache');
+
+const STATES = Object.freeze({
+    STARTING: 'STARTING',
+    INITIALIZING: 'INITIALIZING',
+    READY: 'READY',
+    RUNNING: 'RUNNING',
+    DRAINING: 'DRAINING',
+    TERMINATED: 'TERMINATED',
+});
+
+const TRANSIENT_GRPC_CODES = new Set([4, 8, 13, 14]);
+const PERMANENT_GRPC_CODES = new Set([3, 5, 6, 7, 9, 11, 12, 16]);
+const TRANSIENT_ERROR_CODES = new Set([
+    'ECONNABORTED',
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'EHOSTUNREACH',
+    'ENETDOWN',
+    'ENETUNREACH',
+    'ENOTFOUND',
+    'EPIPE',
+    'ETIMEDOUT',
+]);
+
+let activeLifecycle = null;
+
+function errorReason(error) {
+    const value = error?.details || error?.message || error || 'unknown';
+    return String(value)
+        .replace(/([a-z][a-z0-9+.-]*:\/\/)[^@\s/]+@/gi, '$1[redacted]@')
+        .slice(0, 1000);
+}
+
+function classifyDependencyError(error) {
+    if (error?.permanent === true) return 'permanent';
+    if (error?.transient === true) return 'transient';
+    if (error instanceof SyntaxError) return 'permanent';
+
+    const code = error?.code;
+    if (TRANSIENT_GRPC_CODES.has(code) || TRANSIENT_ERROR_CODES.has(code)) {
+        return 'transient';
+    }
+    if (PERMANENT_GRPC_CODES.has(code)) {
+        return 'permanent';
+    }
+
+    const name = String(error?.name || '');
+    if (
+        /Connection|ConnectionRefused|HostNotFound|MongoServerSelection|RedisSocketClosed|Timeout/i.test(name)
+    ) {
+        return 'transient';
+    }
+    if (/AccessDenied|Authentication|Authorization|Validation/i.test(name)) {
+        return 'permanent';
+    }
+
+    const reason = errorReason(error);
+    if (/timeout|timed out|deadline exceeded|temporar|unavailable|connection (?:closed|lost|refused|reset)/i.test(reason)) {
+        return 'transient';
+    }
+    if (/access denied|authentication|authorization|permission denied|invalid config|required .* missing|malformed/i.test(reason)) {
+        return 'permanent';
+    }
+    return 'permanent';
+}
+
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(Object.assign(new Error('operation aborted'), { name: 'AbortError' }));
+            return;
+        }
+        let timer = null;
+        const cleanup = () => signal.removeEventListener('abort', onAbort);
+        const onElapsed = () => {
+            cleanup();
+            resolve();
+        };
+        const onAbort = () => {
+            clearTimeout(timer);
+            cleanup();
+            reject(Object.assign(new Error('operation aborted'), { name: 'AbortError' }));
+        };
+        timer = setTimeout(onElapsed, ms);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+
+function withTimeout(operation, timeoutMs, parentSignal, attempt) {
+    if (!timeoutMs) {
+        return operation({
+            attempt,
+            signal: parentSignal,
+            deadline: null,
+        });
+    }
+
+    const controller = new AbortController();
+    const onParentAbort = () => controller.abort(parentSignal.reason);
+    parentSignal.addEventListener('abort', onParentAbort, { once: true });
+    let timer = null;
+
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            const timeoutError = Object.assign(
+                new Error(`dependency attempt timed out after ${timeoutMs}ms`),
+                { code: 'ETIMEDOUT', transient: true },
+            );
+            controller.abort(timeoutError);
+            reject(timeoutError);
+        }, timeoutMs);
+    });
+
+    return Promise.race([
+        Promise.resolve().then(() => operation({
+            attempt,
+            signal: controller.signal,
+            deadline: Date.now() + timeoutMs,
+        })),
+        timeoutPromise,
+    ]).finally(() => {
+        if (timer) clearTimeout(timer);
+        parentSignal.removeEventListener('abort', onParentAbort);
+    });
+}
+
+function bounded(action, timeoutMs) {
+    let timer = null;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(
+            () => reject(Object.assign(new Error('shutdown step timed out'), { code: 'ETIMEDOUT' })),
+            timeoutMs,
+        );
+    });
+    return Promise.race([Promise.resolve().then(action), timeout]).finally(() => {
+        if (timer) clearTimeout(timer);
+    });
+}
+
+function createLifecycle({
+    service,
+    shutdownTimeoutMs = 25000,
+    exitOnFatal = true,
+} = {}) {
+    if (!service || typeof service !== 'string') {
+        throw new Error('lifecycle service is required');
+    }
+    setService(service);
+
+    const startedAt = Date.now();
+    const abortController = new AbortController();
+    const dependencyPromises = new Map();
+    const dependencyResults = new Map();
+    const dependencyStatus = new Map();
+    const shutdownSteps = new Map();
+    let phase = STATES.STARTING;
+    let bootstrapCompleted = false;
+    let bootstrapPromise = null;
+    let shutdownPromise = null;
+    let fatalStarted = false;
+    let signalsRegistered = false;
+    let fatalHandlersRegistered = false;
+
+    function emit(event, fields = {}) {
+        structuredEvent(event, {
+            phase,
+            ...fields,
+        });
+    }
+
+    function setPhase(nextPhase) {
+        phase = nextPhase;
+    }
+
+    function allEssentialDependenciesReady() {
+        for (const value of dependencyStatus.values()) {
+            if (value.essential && !value.ready) return false;
+        }
+        return true;
+    }
+
+    function markReady(reason = 'bootstrap_completed') {
+        if (!bootstrapCompleted || !allEssentialDependenciesReady() || phase === STATES.DRAINING) {
+            return;
+        }
+        if (phase !== STATES.READY && phase !== STATES.RUNNING) {
+            setPhase(STATES.READY);
+            emit('lifecycle.ready', { reason });
+        }
+        setPhase(STATES.RUNNING);
+    }
+
+    function markNotReady(reason, dependency = null) {
+        if (phase === STATES.DRAINING || phase === STATES.TERMINATED) return;
+        const wasReady = phase === STATES.READY || phase === STATES.RUNNING;
+        setPhase(STATES.INITIALIZING);
+        if (wasReady) {
+            emit('lifecycle.not_ready', {
+                severity: 'WARN',
+                reason: errorReason(reason),
+                dependency,
+            });
+        }
+    }
+
+    async function connect(dependency, operation, options = {}) {
+        if (!dependency || typeof operation !== 'function') {
+            throw new Error('dependency and operation are required');
+        }
+        if (dependencyResults.has(dependency)) {
+            return dependencyResults.get(dependency);
+        }
+        if (dependencyPromises.has(dependency)) {
+            return dependencyPromises.get(dependency);
+        }
+
+        const {
+            essential = true,
+            attemptTimeoutMs = 10000,
+            initialDelayMs = 1000,
+            maxDelayMs = 30000,
+            jitterRatio = 0.2,
+            classifyError = classifyDependencyError,
+            validate = (value) => value !== false && value !== null,
+        } = options;
+        dependencyStatus.set(dependency, {
+            essential,
+            ready: false,
+            outageStartedAt: Date.now(),
+        });
+
+        const promise = (async () => {
+            let attempt = 0;
+            while (!abortController.signal.aborted) {
+                attempt += 1;
+                const attemptStartedAt = Date.now();
+                emit('dependency.connect_started', { dependency, attempt });
+                try {
+                    const result = await withTimeout(
+                        operation,
+                        attemptTimeoutMs,
+                        abortController.signal,
+                        attempt,
+                    );
+                    if (!validate(result)) {
+                        const invalidResult = Object.assign(
+                            new Error(`${dependency} initialization returned an unusable result`),
+                            { permanent: true },
+                        );
+                        throw invalidResult;
+                    }
+                    const status = dependencyStatus.get(dependency);
+                    status.ready = true;
+                    const outageMs = Date.now() - status.outageStartedAt;
+                    emit('dependency.recovered', {
+                        dependency,
+                        attempt,
+                        durationMs: Date.now() - attemptStartedAt,
+                        outageMs,
+                    });
+                    markReady(`${dependency}_recovered`);
+                    dependencyResults.set(dependency, result);
+                    return result;
+                } catch (error) {
+                    if (abortController.signal.aborted || error?.name === 'AbortError') {
+                        throw error;
+                    }
+                    const classification = classifyError(error);
+                    emit('dependency.connect_failed', {
+                        severity: classification === 'permanent' ? 'ERROR' : 'WARN',
+                        dependency,
+                        attempt,
+                        durationMs: Date.now() - attemptStartedAt,
+                        reason: errorReason(error),
+                        errorCode: error?.code ?? null,
+                    });
+                    if (classification !== 'transient') {
+                        throw error;
+                    }
+                    const exponential = Math.min(
+                        maxDelayMs,
+                        initialDelayMs * (2 ** Math.max(0, attempt - 1)),
+                    );
+                    const jitter = Math.round(exponential * jitterRatio * ((Math.random() * 2) - 1));
+                    const nextRetryMs = Math.max(1, exponential + jitter);
+                    emit('dependency.retry_scheduled', {
+                        severity: 'WARN',
+                        dependency,
+                        attempt,
+                        nextRetryMs,
+                        outageMs: Date.now() - dependencyStatus.get(dependency).outageStartedAt,
+                        reason: errorReason(error),
+                        errorCode: error?.code ?? null,
+                    });
+                    await sleep(nextRetryMs, abortController.signal);
+                }
+            }
+            throw Object.assign(new Error('dependency recovery stopped'), { name: 'AbortError' });
+        })().finally(() => {
+            dependencyPromises.delete(dependency);
+        });
+
+        dependencyPromises.set(dependency, promise);
+        return promise;
+    }
+
+    function dependencyDisconnected(dependency, reason, { essential = true } = {}) {
+        const previous = dependencyStatus.get(dependency);
+        dependencyResults.delete(dependency);
+        dependencyStatus.set(dependency, {
+            essential: previous?.essential ?? essential,
+            ready: false,
+            outageStartedAt: Date.now(),
+        });
+        emit('dependency.disconnected', {
+            severity: 'WARN',
+            dependency,
+            reason: errorReason(reason),
+            errorCode: reason?.code ?? null,
+        });
+        markNotReady(reason, dependency);
+    }
+
+    function dependencyRecovered(dependency) {
+        const previous = dependencyStatus.get(dependency) || {
+            essential: true,
+            outageStartedAt: Date.now(),
+        };
+        dependencyStatus.set(dependency, { ...previous, ready: true });
+        emit('dependency.recovered', {
+            dependency,
+            attempt: null,
+            durationMs: null,
+            outageMs: Date.now() - previous.outageStartedAt,
+        });
+        markReady(`${dependency}_recovered`);
+    }
+
+    function registerShutdownStep(name, action, { order = 100, timeoutMs = 5000 } = {}) {
+        if (!name || typeof action !== 'function') {
+            throw new Error('shutdown step name and action are required');
+        }
+        shutdownSteps.set(name, { name, action, order, timeoutMs });
+    }
+
+    async function performShutdown(exitCode, reason) {
+        setPhase(STATES.DRAINING);
+        emit('lifecycle.shutdown_started', {
+            reason,
+            exitCode,
+        });
+        abortController.abort(new Error(reason));
+        const shutdownStartedAt = Date.now();
+        const deadline = shutdownStartedAt + shutdownTimeoutMs;
+        const steps = [...shutdownSteps.values()].sort((a, b) => a.order - b.order);
+
+        for (const step of steps) {
+            const remainingMs = deadline - Date.now();
+            if (remainingMs <= 0) break;
+            try {
+                await bounded(step.action, Math.min(step.timeoutMs, remainingMs));
+            } catch (error) {
+                emit('lifecycle.shutdown_step_failed', {
+                    severity: 'ERROR',
+                    dependency: step.name,
+                    reason: errorReason(error),
+                    errorCode: error?.code ?? null,
+                });
+            }
+        }
+
+        setPhase(STATES.TERMINATED);
+        emit('lifecycle.shutdown_completed', {
+            durationMs: Date.now() - shutdownStartedAt,
+            exitCode,
+        });
+        process.exitCode = exitCode;
+    }
+
+    function shutdown(exitCode = 0, reason = 'shutdown_requested') {
+        if (!shutdownPromise) {
+            shutdownPromise = performShutdown(exitCode, reason);
+        }
+        return shutdownPromise;
+    }
+
+    async function fatal(error, context = 'unexpected_fatal') {
+        if (fatalStarted) return shutdownPromise;
+        fatalStarted = true;
+        emit('lifecycle.fatal', {
+            severity: 'FATAL',
+            reason: errorReason(error),
+            errorCode: error?.code ?? null,
+            exitCode: 1,
+            context,
+        });
+        await shutdown(1, context);
+        if (exitOnFatal) process.exit(1);
+        return undefined;
+    }
+
+    function registerSignalHandlers() {
+        if (signalsRegistered) return;
+        signalsRegistered = true;
+        const onSignal = (signal) => {
+            void shutdown(0, signal).then(() => process.exit(0));
+        };
+        process.once('SIGTERM', () => onSignal('SIGTERM'));
+        process.once('SIGINT', () => onSignal('SIGINT'));
+    }
+
+    function registerFatalHandlers() {
+        if (fatalHandlersRegistered) return;
+        fatalHandlersRegistered = true;
+        process.once('uncaughtException', (error) => {
+            void fatal(error, 'uncaught_exception');
+        });
+        process.once('unhandledRejection', (reason) => {
+            void fatal(reason, 'unhandled_rejection');
+        });
+    }
+
+    function bootstrap(initializer) {
+        if (bootstrapPromise) return bootstrapPromise;
+        emit('lifecycle.start', {
+            phase: STATES.STARTING,
+            durationMs: 0,
+        });
+        setPhase(STATES.INITIALIZING);
+        emit('lifecycle.bootstrap_started', { durationMs: 0 });
+        bootstrapPromise = (async () => {
+            try {
+                const result = await initializer();
+                bootstrapCompleted = true;
+                emit('lifecycle.bootstrap_completed', {
+                    durationMs: Date.now() - startedAt,
+                });
+                markReady();
+                return result;
+            } catch (error) {
+                if (abortController.signal.aborted && !fatalStarted) return null;
+                await fatal(error, 'bootstrap_failed');
+                return null;
+            }
+        })();
+        return bootstrapPromise;
+    }
+
+    const lifecycle = {
+        bootstrap,
+        connect,
+        dependencyDisconnected,
+        dependencyRecovered,
+        emit,
+        getPhase: () => phase,
+        isReady: () => phase === STATES.READY || phase === STATES.RUNNING,
+        markNotReady,
+        registerFatalHandlers,
+        registerShutdownStep,
+        registerSignalHandlers,
+        shutdown,
+        signal: abortController.signal,
+    };
+    activeLifecycle = lifecycle;
+    return lifecycle;
+}
+
+function getActiveLifecycle() {
+    return activeLifecycle;
+}
+
+module.exports = {
+    STATES,
+    classifyDependencyError,
+    createLifecycle,
+    errorReason,
+    getActiveLifecycle,
+};

package/logger.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const crypto = require('node:crypto');
+
 /**
  * @module logger
  * @description
@@ -29,12 +31,16 @@ try {
  * This allows dynamic changes at runtime (if your cache updates).
  */
 function resolveContext() {
-    const env = cache.getValue('environment') || 'development';
+    const env = cache.getValue('environment') || process.env.ENVIRONMENT || process.env.NODE_ENV || 'development';
     const service = cache.getService ? cache.getService() : 'not_set_service';
     const isProd = env === 'production';
     return { env, service, isProd };
 }
 
+const processStartedAt = Date.now();
+const processInstanceId = process.env.INSTANCE_ID
+    || `${process.env.HOSTNAME || 'local'}:${process.pid}:${processStartedAt}:${crypto.randomUUID()}`;
+
 /**
  * Internal async writer using setImmediate to offload writes from the hot path.
  * @param {'stdout'|'stderr'} stream
@@ -93,6 +99,40 @@ function safeStringify(value) {
     );
 }
 
+/**
+ * Emit one machine-readable lifecycle or dependency event.
+ *
+ * @param {string} event
+ * @param {Record<string, any>} [fields]
+ */
+function structuredEvent(event, fields = {}) {
+    const { service } = resolveContext();
+    const severity = String(fields.severity || 'INFO').toUpperCase();
+    const payload = {
+        timestamp: new Date().toISOString(),
+        severity,
+        event,
+        service,
+        pod: process.env.HOSTNAME || null,
+        instanceId: processInstanceId,
+        deploymentVersion:
+            process.env.DEPLOYMENT_VERSION
+            || process.env.APP_VERSION
+            || process.env.npm_package_version
+            || null,
+        ...fields,
+    };
+    payload.timestamp = payload.timestamp || new Date().toISOString();
+    payload.severity = severity;
+    payload.event = event;
+    payload.service = service;
+    payload.instanceId = processInstanceId;
+    const stream = severity === 'ERROR' || severity === 'FATAL' || severity === 'WARN'
+        ? 'stderr'
+        : 'stdout';
+    process[stream].write(`${JSON.stringify(payload)}\n`);
+}
+
 /**
  * Flexible debug logger supporting (msg), (obj), (msg, obj), (obj, msg).
  *
@@ -175,5 +215,6 @@ module.exports = {
     debug,
     successNote,
     criticalNote,
-    warningNote
+    warningNote,
+    structuredEvent
 };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "b2b-platform-utils",
-  "version": "1.1.95",
+  "version": "1.1.96",
   "description": "Shared utilities for Node.js microservices: errors map, local cache, logger, numbers, dates, filesystem, media optimization, paginator, slugger, crypto wrapper, sanitize HTML, sorting.",
   "type": "commonjs",
   "license": "KingSizer",
   "private": false,
   "scripts": {
     "publish-update": "npm version patch --no-git-tag-version && npm publish",
-    "test": "node test/slugger.test.js"
+    "test": "node test/slugger.test.js && node test/lifecycle.test.js"
   },
   "files": [
     "*.js",