npm - mercury-composable - Versions diffs - 4.12.1 - Mend

mercury-composable 4.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (34) hide show

package/LICENSE +202 -0
package/README.md +195 -0
package/dist/src/actuator.d.ts +36 -0
package/dist/src/actuator.js +295 -0
package/dist/src/bus.d.ts +110 -0
package/dist/src/bus.js +386 -0
package/dist/src/cli.d.ts +2 -0
package/dist/src/cli.js +72 -0
package/dist/src/client.d.ts +48 -0
package/dist/src/client.js +433 -0
package/dist/src/config.d.ts +27 -0
package/dist/src/config.js +161 -0
package/dist/src/default-log-context.yaml +19 -0
package/dist/src/envelope.d.ts +44 -0
package/dist/src/envelope.js +227 -0
package/dist/src/event-stream.d.ts +120 -0
package/dist/src/event-stream.js +359 -0
package/dist/src/exceptions.d.ts +18 -0
package/dist/src/exceptions.js +25 -0
package/dist/src/index.d.ts +24 -0
package/dist/src/index.js +21 -0
package/dist/src/log-context.d.ts +24 -0
package/dist/src/log-context.js +172 -0
package/dist/src/log.d.ts +14 -0
package/dist/src/log.js +113 -0
package/dist/src/registry.d.ts +64 -0
package/dist/src/registry.js +80 -0
package/dist/src/server.d.ts +43 -0
package/dist/src/server.js +343 -0
package/dist/src/trace.d.ts +39 -0
package/dist/src/trace.js +73 -0
package/dist/src/version.d.ts +2 -0
package/dist/src/version.js +2 -0
package/package.json +55 -0

package/dist/src/actuator.js ADDED Viewed

@@ -0,0 +1,295 @@
+/**
+ * Actuator endpoints for operations and Kubernetes deployment.
+ *
+ * The same operational surface as the engines (the Java ActuatorServices and
+ * its Rust port), so a polyglot installation monitors every app one way:
+ *
+ * - GET /info - application identity (name, version, description), runtime,
+ *   origin id, start/current time and uptime.
+ * - GET /info/routes - the local routing table split by visibility
+ *   (routing.public / routing.private, route -> instance count).
+ * - GET /env - selected environment variables (show.env.variables) and
+ *   selected configuration parameters (show.application.properties) -
+ *   opt-in lists, so secrets are never dumped wholesale (engine parity).
+ * - GET /health - runs the health check functions listed in
+ *   mandatory.health.dependencies / optional.health.dependencies. All
+ *   mandatory up -> UP (HTTP 200); any mandatory down -> DOWN (HTTP 400,
+ *   engine parity). The outcome feeds the liveness state.
+ * - GET /livenessprobe - "OK" (text) while the last health outcome is good,
+ *   else HTTP 400 "Unhealthy. Please check '/health' endpoint."
+ *
+ * A health check function is a normal registered function (usually private)
+ * speaking the engines' interface contract - called through the same event
+ * bus that serves PostOffice, first with header type=info (an advisory
+ * identity map merged into its dependency entry), then with type=health (a
+ * status text or map; a non-200 reply marks the dependency down):
+ *
+ *   preload('demo.health', { isPrivate: true }, async (headers, _body) => {
+ *     if (headers.type === 'info') {
+ *       return { service: 'demo.service', href: 'http://127.0.0.1' };
+ *     }
+ *     return 'demo.service is running fine';
+ *   });
+ *
+ * Engine deltas (deliberate, wrapper-scale): no /info/lib (a wrapper app has
+ * no runtime dependency manifest - deferred on the Rust port too), no XML
+ * responses, and no 5-second info cache (dependencies are in-process
+ * functions, so the type=info lookup costs nothing).
+ */
+import { randomUUID } from 'node:crypto';
+import { DeliveryTimeout } from './bus.js';
+import { appConfig } from './config.js';
+import { asText, isoUtc } from './envelope.js';
+import { getLogger } from './log.js';
+import { VERSION } from './version.js';
+const log = getLogger('mercury.actuator');
+const INFO_TIMEOUT_MS = 3000; // engine value for the advisory type=info lookup
+const HEALTH_TIMEOUT_MS = 10000; // engine value for the type=health probe
+const UNHEALTHY = "Unhealthy. Please check '/health' endpoint.";
+// The engines' minimal landing page (platform-core public/index.html style);
+// the wrappers embed it - no static file service by design.
+const INDEX_HTML = `<!DOCTYPE html>
+<html>
+<body>
+<h2>Welcome</h2>
+<p><a href="/info">INFO endpoint</a></p>
+<p><a href="/info/routes">Service list</a></p>
+<p><a href="/env">Environment endpoint</a></p>
+<p><a href="/health">Health endpoint</a></p>
+<p><a href="/livenessprobe">Liveness probe</a></p>
+</body>
+</html>`;
+let origin;
+/**
+ * Unique instance id, minted once per process (the Java reference engine's
+ * format: UTC yyyyMMdd date prefix + 32-hex uuid).
+ */
+export function appOrigin() {
+    if (!origin) {
+        const date = isoUtc(new Date()).slice(0, 10).replaceAll('-', '');
+        origin = date + randomUUID().replaceAll('-', '');
+    }
+    return origin;
+}
+/**
+ * Human-readable duration matching the engines' rendering (including their
+ * strict boundary behavior, kept verbatim for parity).
+ */
+export function elapsedTime(milliseconds) {
+    const ONE_SECOND = 1000;
+    const ONE_MINUTE = 60 * ONE_SECOND;
+    const ONE_HOUR = 60 * ONE_MINUTE;
+    const ONE_DAY = 24 * ONE_HOUR;
+    let remaining = Math.trunc(milliseconds);
+    const parts = [];
+    if (remaining > ONE_DAY) {
+        const days = Math.trunc(remaining / ONE_DAY);
+        parts.push(`${days} day${days === 1 ? '' : 's'}`);
+        remaining -= days * ONE_DAY;
+    }
+    if (remaining > ONE_HOUR) {
+        const hours = Math.trunc(remaining / ONE_HOUR);
+        parts.push(`${hours} hour${hours === 1 ? '' : 's'}`);
+        remaining -= hours * ONE_HOUR;
+    }
+    if (remaining > ONE_MINUTE) {
+        const minutes = Math.trunc(remaining / ONE_MINUTE);
+        parts.push(`${minutes} minute${minutes === 1 ? '' : 's'}`);
+        remaining -= minutes * ONE_MINUTE;
+    }
+    if (remaining >= ONE_SECOND) {
+        const seconds = Math.trunc(remaining / ONE_SECOND);
+        parts.push(`${seconds} second${seconds === 1 ? '' : 's'}`);
+    }
+    return parts.length ? parts.join(' ') : `${remaining} ms`;
+}
+/** A comma/space-separated string (engine syntax) or a YAML list. */
+function asList(value) {
+    const items = Array.isArray(value)
+        ? value.map((item) => asText(item).trim())
+        : asText(value ?? '').split(/[,\s]+/);
+    return items.filter((item) => item.length > 0);
+}
+function isMessageShape(body) {
+    // the engines accept only text or map dependency messages
+    return typeof body === 'string' ||
+        (body !== null && typeof body === 'object' && !Array.isArray(body));
+}
+function sendText(res, status, text) {
+    res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end(text);
+}
+function sendJson(res, status, body) {
+    // the engines' default serializer presentation: pretty-printed JSON
+    const bytes = Buffer.from(JSON.stringify(body, null, 2));
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'content-length': bytes.length });
+    res.end(bytes);
+}
+/** The engines' host-level error shape (SimpleHttpUtility signature). */
+export function sendError(res, status, message) {
+    sendJson(res, status, { status, message, type: 'error' });
+}
+function sendHtml(res, page) {
+    const bytes = Buffer.from(page);
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'content-length': bytes.length });
+    res.end(bytes);
+}
+/** HTTP handlers for the actuator endpoints (wired by EventApiServer). */
+export class Actuator {
+    registry;
+    start = new Date();
+    healthy = true; // liveness follows the most recent /health outcome
+    appName;
+    appVersion;
+    description;
+    required;
+    optional;
+    constructor(registry) {
+        const config = appConfig();
+        this.registry = registry;
+        this.appName = config.getProperty('application.name', 'application') || 'application';
+        this.appVersion = config.getProperty('info.app.version', VERSION) || VERSION;
+        this.description = config.getProperty('info.app.description', this.appName) || this.appName;
+        this.required = asList(config.get('mandatory.health.dependencies'));
+        this.optional = asList(config.get('optional.health.dependencies'));
+        if (this.required.length) {
+            log.info(`Mandatory service dependencies - ${JSON.stringify(this.required)}`);
+        }
+        if (this.optional.length) {
+            log.info(`Optional services dependencies - ${JSON.stringify(this.optional)}`);
+        }
+    }
+    /** Route a GET to its actuator endpoint; false when the path is not ours. */
+    async handle(pathname, res) {
+        switch (pathname) {
+            case '/':
+                sendHtml(res, INDEX_HTML);
+                return true;
+            case '/info':
+                sendJson(res, 200, this.info());
+                return true;
+            case '/info/routes':
+                sendJson(res, 200, this.routes());
+                return true;
+            case '/env':
+                sendJson(res, 200, this.env());
+                return true;
+            case '/health': {
+                const [status, body] = await this.health();
+                sendJson(res, status, body);
+                return true;
+            }
+            case '/livenessprobe':
+                if (this.healthy) {
+                    sendText(res, 200, 'OK');
+                }
+                else {
+                    sendText(res, 400, UNHEALTHY);
+                }
+                return true;
+            default:
+                return false;
+        }
+    }
+    appBlock() {
+        return { name: this.appName, version: this.appVersion, description: this.description };
+    }
+    info() {
+        const now = new Date();
+        return {
+            app: this.appBlock(),
+            runtime: { language: 'node.js', node: process.version, mercury_composable: VERSION },
+            origin: appOrigin(),
+            time: { start: isoUtc(this.start), current: isoUtc(now) },
+            up_time: elapsedTime(now.getTime() - this.start.getTime())
+        };
+    }
+    routes() {
+        const publicRoutes = {};
+        const privateRoutes = {};
+        for (const service of this.registry.routes()) { // already route-sorted
+            (service.isPrivate ? privateRoutes : publicRoutes)[service.route] = service.instances;
+        }
+        return { app: this.appBlock(), routing: { public: publicRoutes, private: privateRoutes } };
+    }
+    env() {
+        const config = appConfig();
+        const environment = {};
+        for (const name of asList(config.get('show.env.variables'))) {
+            environment[name] = process.env[name] ?? '';
+        }
+        const properties = {};
+        for (const name of asList(config.get('show.application.properties'))) {
+            properties[name] = config.getProperty(name) ?? '';
+        }
+        return { app: this.appBlock(), env: { environment, properties } };
+    }
+    async health() {
+        const dependency = [];
+        // optional services never affect the overall status (engine semantics)
+        await this.checkServices(this.optional, false, dependency);
+        const up = await this.checkServices(this.required, true, dependency);
+        this.healthy = up;
+        const result = {};
+        if (!dependency.length) {
+            result.message = 'Did you forget to define mandatory.health.dependencies ' +
+                'or optional.health.dependencies';
+        }
+        result.dependency = dependency;
+        result.status = up ? 'UP' : 'DOWN';
+        result.origin = appOrigin();
+        result.name = this.appName;
+        return [up ? 200 : 400, result];
+    }
+    async checkServices(services, required, dependency) {
+        let allUp = true;
+        for (const route of services) {
+            const entry = { route, required };
+            dependency.push(entry);
+            if (!await this.checkService(route, entry)) {
+                allUp = false;
+            }
+        }
+        return allUp;
+    }
+    /** Probe one health-check function; false when it is missing or down. */
+    async checkService(route, entry) {
+        const service = this.registry.get(route);
+        if (!service) {
+            entry.status_code = 404;
+            entry.message = `Please check - Route ${route} not found`;
+            return false;
+        }
+        const bus = this.registry.bus;
+        // info is advisory - merge whatever the service reports about itself;
+        // the health probe below decides the status
+        try {
+            const info = await bus.deliver(service, { type: 'info' }, null, INFO_TIMEOUT_MS);
+            if (info.body !== null && typeof info.body === 'object' && !Array.isArray(info.body)) {
+                Object.assign(entry, info.body);
+            }
+        }
+        catch (e) {
+            if (!(e instanceof DeliveryTimeout))
+                throw e;
+        }
+        try {
+            const reply = await bus.deliver(service, { type: 'health' }, null, HEALTH_TIMEOUT_MS);
+            entry.status_code = reply.getStatus();
+            if (isMessageShape(reply.body)) {
+                entry.message = reply.body;
+            }
+            return !reply.hasError();
+        }
+        catch (e) {
+            if (!(e instanceof DeliveryTimeout))
+                throw e;
+            entry.status_code = 408;
+            entry.message = `Please check - ${e.message}`;
+            return false;
+        }
+    }
+}

package/dist/src/bus.d.ts ADDED Viewed

@@ -0,0 +1,110 @@
+/**
+ * The primitive in-process event bus - the single dispatch pipeline.
+ *
+ * Every invocation reaches a function the same way: through a per-route FIFO
+ * mailbox consumed by `instances` worker loops (the engines' semantics - the
+ * parameter is faithful). The HTTP host and the local side of PostOffice are
+ * thin ingress adapters over this bus; neither has its own invocation path.
+ *
+ * Deliberately primitive, riding the runtime's native event loop:
+ * - Two operations only: deliver (RPC - ttl-bounded, with a dead-work skip
+ *   for queued calls whose caller already timed out) and publish
+ *   (drop-n-forget - returns the 202-shape acknowledgement).
+ * - No spill tier and no queue cap: back-pressure belongs to the tier that
+ *   owns recovery - the engines' flows and graphs. A leaf host fails fast by
+ *   deadline (the 408 envelope) instead of hoarding work.
+ * - In-memory only; no orchestration, no flows, no persistence, no broadcast.
+ *
+ * Why a hand-built Mailbox instead of Node's EventEmitter: this contract is
+ * an ANYCAST WORK QUEUE - each delivery goes to exactly one of N workers and
+ * waits its FIFO turn while all are busy. EventEmitter is a broadcast
+ * notifier - emit() invokes every listener synchronously and buffers
+ * nothing - so a bounded-concurrency bus would still need this queue in
+ * front of it (the emitter demoted to a wake-up bell), and once()-based
+ * bridging re-registers a listener per iteration, can drop emissions
+ * between iterations, and trips MaxListenersExceededWarning right at the
+ * default instances=10. Bare promise waiters also hold no event-loop
+ * handles, which is what makes the lifecycle contract exactly true (an idle
+ * bus lets the process exit; only an in-flight RPC's deadline timer holds
+ * it). The Mailbox is node's missing asyncio.Queue, keeping the python and
+ * node twins structurally identical.
+ *
+ * The bus is internal: application code uses preload() and PostOffice, never
+ * this module - the same way engine developers never touch the engine bus.
+ */
+import { EventEnvelope } from './envelope.js';
+import type { ServiceDef } from './registry.js';
+/** An RPC delivery missed its deadline; adapters shape the 408 for their protocol. */
+export declare class DeliveryTimeout extends Error {
+    readonly ttlMs: number;
+    constructor(ttlMs: number);
+}
+/** The 202 drop-n-forget acknowledgement (EventApiService shape). */
+export declare function asyncAck(): EventEnvelope;
+interface TraceFields {
+    traceId?: string;
+    tracePath?: string;
+    cid?: string;
+    envelope?: EventEnvelope;
+}
+/** Unbounded FIFO handing items to awaiting consumers (node's missing asyncio.Queue). */
+export declare class Mailbox<T> {
+    private readonly items;
+    private readonly waiters;
+    push(item: T): void;
+    next(): Promise<T>;
+}
+/**
+ * Race one PENDING promise against a timeout; null on expiry. The pending
+ * promise survives a lost race (a bare promise cannot be cancelled), so a
+ * caller that keeps waiting must keep reusing THE SAME promise until it
+ * resolves - a fresh queue.next() per cycle would leave an abandoned waiter
+ * in the mailbox that steals and drops the next item. A caller that
+ * terminates on expiry may race a fresh promise each time.
+ */
+export declare function raceMs<T>(pending: Promise<T>, timeoutMs: number): Promise<T | null>;
+/** Route an envelope to a local target - wired by the registry (backref). */
+export type EnvelopeRouter = (event: EventEnvelope) => boolean;
+/** Per-registry bus: one FIFO mailbox and N workers per registered route. */
+export declare class EventBus {
+    private readonly mailboxes;
+    private readonly sinks;
+    private router;
+    private sinkSequence;
+    bindRouter(router: EnvelopeRouter): void;
+    /** Open a per-request reply sink under a generated local route name. */
+    openSink(): [string, Mailbox<EventEnvelope>];
+    closeSink(route: string): void;
+    /**
+     * Deliver an envelope to a reply sink; false when the sink is gone (a
+     * completed, timed-out or disconnected request) - late segments are no-op
+     * drops, the engines' semantics.
+     */
+    offerSink(route: string, event: EventEnvelope): boolean;
+    private mailbox;
+    /** RPC: enqueue and await the reply envelope within the ttl. */
+    deliver(service: ServiceDef, headers: Record<string, string>, body: unknown, ttlMs: number, trace?: TraceFields): Promise<EventEnvelope>;
+    /** Drop-n-forget: enqueue and return the 202-shape acknowledgement. */
+    publish(service: ServiceDef, headers: Record<string, string>, body: unknown, trace?: TraceFields): EventEnvelope;
+    /**
+     * Route one envelope to a local function (the reply_to mechanism):
+     * drop-n-forget delivery carrying the raw envelope, so an interceptor
+     * handler receives reply_to and the correlation id the engines' way.
+     */
+    publishEnvelope(service: ServiceDef, event: EventEnvelope): void;
+    /** Stop all workers (orderly shutdown; worker promises hold no OS handle). */
+    close(): void;
+    private runWorker;
+    /** Run the handler under its trace context and shape the outcome as a reply. */
+    private static execute;
+    /**
+     * Run an interceptor handler: it receives the raw envelope, replies
+     * manually through reply_to (the engines' EventInterceptor contract), and
+     * its return value is discarded. An uncaught exception becomes an error
+     * envelope to the delivery's reply_to - so a caller waiting on a reply
+     * sink sees it - and a streaming host renders it in-band.
+     */
+    private executeInterceptor;
+    private replyInterceptorError;
+}
+export {};