orbit-bus 0.1.1

package/dist/src/commands/api.js

@@ -0,0 +1,226 @@
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import { closeBus, connectBus } from "../nats.js";
+import { actionFromApiPath, parseObjectPayload } from "../api_contract.js";
+import { executeOrbitAction } from "../orbit_actions.js";
+import { randomId } from "../util.js";
+import { ApiHttpError, normalizeApiError } from "../api_http.js";
+import { OrbitError } from "../errors.js";
+import { incCounter, observeHistogram, renderPrometheusMetrics, setGauge } from "../metrics.js";
+function writeJson(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("content-type", "application/json");
+    res.end(`${JSON.stringify(body)}\n`);
+}
+function writeError(res, id, error) {
+    writeJson(res, error.status, {
+        id,
+        ok: false,
+        error: {
+            type: "orbit_error",
+            code: error.code,
+            message: error.message,
+            ...(error.details === undefined ? {} : { details: error.details })
+        }
+    });
+}
+function extractBearerToken(req) {
+    const auth = req.headers.authorization;
+    if (typeof auth === "string" && auth.startsWith("Bearer ")) {
+        return auth.slice("Bearer ".length).trim();
+    }
+    const header = req.headers["x-orbit-token"];
+    if (typeof header === "string")
+        return header.trim();
+    return undefined;
+}
+function ensureAuthorized(req, config) {
+    const requiredToken = config.api.authToken;
+    if (requiredToken && extractBearerToken(req) !== requiredToken) {
+        throw new ApiHttpError(401, "UNAUTHORIZED", "missing or invalid API token");
+    }
+    if (config.api.tls.enabled && config.api.tls.requestClientCert && config.api.tls.requireClientCert) {
+        const maybeTls = req.socket;
+        if (!maybeTls.authorized) {
+            throw new ApiHttpError(401, "UNAUTHORIZED", "valid client TLS certificate is required");
+        }
+    }
+}
+async function readJsonBody(req, maxBytes) {
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        totalBytes += buf.length;
+        if (totalBytes > maxBytes) {
+            throw new ApiHttpError(413, "PAYLOAD_TOO_LARGE", `request exceeds max body size ${maxBytes} bytes`);
+        }
+        chunks.push(buf);
+    }
+    const text = Buffer.concat(chunks).toString("utf-8").trim();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new ApiHttpError(400, "BAD_JSON", "invalid JSON body");
+    }
+}
+function ensureBindHostAllowed(config, host) {
+    const allow = config.api.allowedHosts;
+    if (allow.includes("*") || allow.includes(host))
+        return;
+    throw new OrbitError("FORBIDDEN_BIND_HOST", `host ${host} is not in api.allowedHosts`, { allowedHosts: allow });
+}
+async function isNatsReady(nc) {
+    if (nc.isClosed())
+        return false;
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("readiness timeout")), 1000);
+        timer.unref?.();
+    });
+    try {
+        await Promise.race([nc.flush(), timeout]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function withTimeout(input, timeoutMs) {
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new ApiHttpError(408, "REQUEST_TIMEOUT", `request timed out after ${timeoutMs}ms`)), timeoutMs);
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([input, timeoutPromise]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function createServer(config, handler) {
+    if (!config.api.tls.enabled)
+        return http.createServer(handler);
+    if (!config.api.tls.keyFile || !config.api.tls.certFile) {
+        throw new OrbitError("BAD_ARGS", "api tls requires keyFile and certFile");
+    }
+    const key = fs.readFileSync(config.api.tls.keyFile, "utf-8");
+    const cert = fs.readFileSync(config.api.tls.certFile, "utf-8");
+    const ca = config.api.tls.caFile ? fs.readFileSync(config.api.tls.caFile, "utf-8") : undefined;
+    return https.createServer({
+        key,
+        cert,
+        ca,
+        requestCert: config.api.tls.requestClientCert,
+        rejectUnauthorized: config.api.tls.requireClientCert
+    }, handler);
+}
+export async function cmdApi(config, logger, opts) {
+    ensureBindHostAllowed(config, opts.host);
+    const nc = await connectBus(config.natsUrl);
+    let inFlight = 0;
+    setGauge("orbit_api_inflight", inFlight);
+    const server = createServer(config, (req, res) => {
+        void (async () => {
+            const started = Date.now();
+            const requestId = req.headers["x-request-id"]?.toString() || randomId();
+            let actionLabel = "unknown";
+            let entered = false;
+            let status = 500;
+            try {
+                if (req.method === "GET" && req.url === "/healthz") {
+                    status = 200;
+                    writeJson(res, 200, { ok: true, status: "up" });
+                    return;
+                }
+                if (req.method === "GET" && req.url === "/readyz") {
+                    const ready = await isNatsReady(nc);
+                    status = ready ? 200 : 503;
+                    writeJson(res, status, {
+                        ok: ready,
+                        status: ready ? "ready" : "degraded",
+                        dependencies: { nats: ready ? "up" : "down" }
+                    });
+                    return;
+                }
+                if (req.method === "GET" && req.url === "/metrics") {
+                    ensureAuthorized(req, config);
+                    status = 200;
+                    res.statusCode = 200;
+                    res.setHeader("content-type", "text/plain; version=0.0.4");
+                    res.end(renderPrometheusMetrics());
+                    return;
+                }
+                if (req.method !== "POST" || !req.url) {
+                    throw new ApiHttpError(405, "METHOD_NOT_ALLOWED", "use POST /v1/<action>");
+                }
+                ensureAuthorized(req, config);
+                if (inFlight >= config.runtime.apiMaxConcurrent) {
+                    throw new ApiHttpError(429, "API_OVERLOADED", "api concurrency limit reached");
+                }
+                inFlight += 1;
+                entered = true;
+                setGauge("orbit_api_inflight", inFlight);
+                const parsedAction = actionFromApiPath(req.url.split("?")[0]);
+                if (!parsedAction) {
+                    throw new ApiHttpError(404, "NOT_FOUND", "unknown endpoint");
+                }
+                actionLabel = parsedAction;
+                const payload = parseObjectPayload(await readJsonBody(req, config.runtime.apiMaxBodyBytes));
+                const out = await withTimeout(executeOrbitAction(config, nc, parsedAction, payload, "api"), config.runtime.apiRequestTimeoutMs);
+                status = 200;
+                writeJson(res, 200, { id: requestId, ok: true, payload: out });
+            }
+            catch (err) {
+                const apiErr = normalizeApiError(err);
+                status = apiErr.status;
+                writeError(res, requestId, apiErr);
+            }
+            finally {
+                const durationMs = Date.now() - started;
+                incCounter("orbit_api_requests_total", 1, { action: actionLabel, method: req.method ?? "UNKNOWN", status });
+                observeHistogram("orbit_api_request_duration_ms", durationMs, { action: actionLabel, status });
+                if (entered) {
+                    inFlight -= 1;
+                    setGauge("orbit_api_inflight", inFlight);
+                }
+            }
+        })();
+    });
+    server.requestTimeout = config.runtime.apiRequestTimeoutMs;
+    server.keepAliveTimeout = 5000;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port, opts.host, () => resolve());
+    });
+    logger.info("api online", {
+        host: opts.host,
+        port: opts.port,
+        nats_url: config.natsUrl,
+        tls_enabled: config.api.tls.enabled,
+        mtls_required: config.api.tls.requestClientCert && config.api.tls.requireClientCert,
+        token_auth_enabled: Boolean(config.api.authToken)
+    });
+    const shutdown = async () => {
+        await new Promise((resolve) => server.close(() => resolve()));
+        try {
+            await closeBus(config.natsUrl);
+        }
+        catch {
+            // ignore shutdown failures
+        }
+    };
+    process.once("SIGINT", () => void shutdown().finally(() => process.exit(0)));
+    process.once("SIGTERM", () => void shutdown().finally(() => process.exit(0)));
+    await nc.closed();
+}

package/dist/src/commands/bench.d.ts

@@ -0,0 +1,13 @@
+import { Logger } from "../logger.js";
+import { OrbitConfig } from "../types.js";
+export declare function cmdBench(config: OrbitConfig, _logger: Logger, opts: {
+    target: string;
+    body: unknown;
+    durationSec: number;
+    concurrency: number;
+    rampToConcurrency?: number;
+    rampStepSec?: number;
+    rampStepConcurrency?: number;
+    timeoutMs?: number;
+    retries?: number;
+}): Promise<void>;

package/dist/src/commands/bench.js

@@ -0,0 +1,125 @@
+import { createEnvelope, validateEnvelope } from "../envelope.js";
+import { OrbitError } from "../errors.js";
+import { closeBus, connectBus, decodeJson, encodeJson } from "../nats.js";
+import { withRetries } from "../retry.js";
+import { appendTraceEvent } from "../trace.js";
+import { randomId } from "../util.js";
+import { prefixedSubject } from "../subjects.js";
+function percentile(input, p) {
+    if (input.length === 0)
+        return 0;
+    const sorted = [...input].sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.floor((p / 100) * sorted.length)));
+    return sorted[idx];
+}
+export async function cmdBench(config, _logger, opts) {
+    const match = opts.target.match(/^([a-zA-Z0-9_-]+)\.([a-zA-Z0-9_-]+)$/);
+    if (!match)
+        throw new OrbitError("BAD_TARGET", "target must be <service>.<method>");
+    const [, svc, method] = match;
+    const subject = prefixedSubject(config, "rpc", svc, method);
+    const timeoutMs = opts.timeoutMs ?? config.requestTimeoutMs;
+    const retries = opts.retries ?? config.retries;
+    const durationMs = Math.max(1, Math.floor(opts.durationSec * 1000));
+    const baseConcurrency = Math.max(1, Math.floor(opts.concurrency));
+    const rampTo = opts.rampToConcurrency ? Math.max(baseConcurrency, Math.floor(opts.rampToConcurrency)) : baseConcurrency;
+    const maxWorkers = rampTo;
+    const rampStepSec = Math.max(1, Math.floor(opts.rampStepSec ?? 1));
+    const rampStepConcurrency = Math.max(1, Math.floor(opts.rampStepConcurrency ?? 1));
+    const nc = await connectBus(config.natsUrl);
+    const runId = randomId();
+    const start = Date.now();
+    const stopAt = start + durationMs;
+    let total = 0;
+    let success = 0;
+    let failed = 0;
+    const latencies = [];
+    appendTraceEvent(config, {
+        span_id: randomId(),
+        run_id: runId,
+        ts: new Date().toISOString(),
+        actor: "bench",
+        event: "bench_start",
+        svc,
+        method,
+        detail: `duration_ms=${durationMs},concurrency=${baseConcurrency},ramp_to=${rampTo}`
+    });
+    let activeWorkers = baseConcurrency;
+    if (rampTo > baseConcurrency) {
+        const rampTimer = setInterval(() => {
+            activeWorkers = Math.min(rampTo, activeWorkers + rampStepConcurrency);
+            if (activeWorkers >= rampTo)
+                clearInterval(rampTimer);
+        }, rampStepSec * 1000);
+        rampTimer.unref?.();
+    }
+    const worker = async (index) => {
+        while (Date.now() < stopAt) {
+            if (index >= activeWorkers) {
+                await new Promise((resolve) => setTimeout(resolve, 50));
+                continue;
+            }
+            const callStart = Date.now();
+            total += 1;
+            try {
+                const reqEnv = createEnvelope({
+                    kind: "request",
+                    runId,
+                    payload: opts.body,
+                    provenance: { caller: "orbit-bench", target: opts.target }
+                });
+                const { value } = await withRetries(async () => nc.request(subject, encodeJson(reqEnv), { timeout: timeoutMs }), { retries, timeoutMs });
+                const reply = validateEnvelope(decodeJson(value.data), { skipHashCheck: config.performance.trustedLocal });
+                const payload = reply.payload;
+                if (payload?.ok === false) {
+                    failed += 1;
+                }
+                else {
+                    success += 1;
+                    latencies.push(Date.now() - callStart);
+                }
+            }
+            catch {
+                failed += 1;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: maxWorkers }, (_v, idx) => worker(idx)));
+    await closeBus(config.natsUrl);
+    const elapsedMs = Math.max(1, Date.now() - start);
+    const result = {
+        ok: true,
+        target: opts.target,
+        duration_ms: elapsedMs,
+        concurrency: {
+            start: baseConcurrency,
+            max: rampTo,
+            ramp_step_sec: rampTo > baseConcurrency ? rampStepSec : null,
+            ramp_step_concurrency: rampTo > baseConcurrency ? rampStepConcurrency : null
+        },
+        total_requests: total,
+        success,
+        failed,
+        error_rate: total === 0 ? 0 : failed / total,
+        throughput_rps: Number(((total * 1000) / elapsedMs).toFixed(2)),
+        latency_ms: {
+            min: latencies.length ? Math.min(...latencies) : 0,
+            avg: latencies.length ? Number((latencies.reduce((a, b) => a + b, 0) / latencies.length).toFixed(2)) : 0,
+            p50: percentile(latencies, 50),
+            p95: percentile(latencies, 95),
+            p99: percentile(latencies, 99),
+            max: latencies.length ? Math.max(...latencies) : 0
+        }
+    };
+    appendTraceEvent(config, {
+        span_id: randomId(),
+        run_id: runId,
+        ts: new Date().toISOString(),
+        actor: "bench",
+        event: "bench_end",
+        svc,
+        method,
+        detail: JSON.stringify(result)
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}

package/dist/src/commands/bench_overhead.d.ts

@@ -0,0 +1,8 @@
+import { Logger } from "../logger.js";
+import { OrbitConfig } from "../types.js";
+export declare function cmdBenchOverhead(config: OrbitConfig, _logger: Logger, opts: {
+    target: string;
+    body: unknown;
+    iterations: number;
+    timeoutMs?: number;
+}): Promise<void>;

package/dist/src/commands/bench_overhead.js

@@ -0,0 +1,71 @@
+import { createEnvelope, validateEnvelope } from "../envelope.js";
+import { OrbitError } from "../errors.js";
+import { closeBus, connectBus, decodeJson, encodeJson } from "../nats.js";
+import { canUseAgent, requestAgent } from "../agent_ipc.js";
+import { prefixedSubject } from "../subjects.js";
+import { randomId } from "../util.js";
+function percentile(input, p) {
+    if (input.length === 0)
+        return 0;
+    const sorted = [...input].sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.floor((p / 100) * sorted.length)));
+    return sorted[idx];
+}
+export async function cmdBenchOverhead(config, _logger, opts) {
+    const m = opts.target.match(/^([a-zA-Z0-9_-]+)\.([a-zA-Z0-9_-]+)$/);
+    if (!m)
+        throw new OrbitError("BAD_TARGET", "target must be <service>.<method>");
+    if (!canUseAgent(config)) {
+        throw new OrbitError("AGENT_DISABLED", "bench-overhead requires local agent enabled");
+    }
+    const [, svc, method] = m;
+    const iterations = Math.max(1, Math.floor(opts.iterations));
+    const timeoutMs = opts.timeoutMs ?? config.requestTimeoutMs;
+    const subject = prefixedSubject(config, "rpc", svc, method);
+    const direct = [];
+    const viaAgent = [];
+    const nc = await connectBus(config.natsUrl);
+    try {
+        for (let i = 0; i < iterations; i += 1) {
+            const runId = randomId();
+            const reqEnv = createEnvelope({
+                kind: "request",
+                runId,
+                payload: opts.body,
+                provenance: { caller: "orbit-bench-overhead", target: opts.target }
+            });
+            const directStart = Date.now();
+            const directMsg = await nc.request(subject, encodeJson(reqEnv), { timeout: timeoutMs });
+            validateEnvelope(decodeJson(directMsg.data), { skipHashCheck: config.performance.trustedLocal });
+            direct.push(Date.now() - directStart);
+            const agentStart = Date.now();
+            await requestAgent(config, "call", { target: opts.target, body: opts.body, timeoutMs, runId: randomId() }, timeoutMs);
+            viaAgent.push(Date.now() - agentStart);
+        }
+    }
+    finally {
+        await closeBus(config.natsUrl);
+    }
+    const p95Direct = percentile(direct, 95);
+    const p95Agent = percentile(viaAgent, 95);
+    const result = {
+        ok: true,
+        target: opts.target,
+        iterations,
+        latency_ms: {
+            direct: {
+                p50: percentile(direct, 50),
+                p95: p95Direct
+            },
+            via_agent: {
+                p50: percentile(viaAgent, 50),
+                p95: p95Agent
+            }
+        },
+        orbit_overhead_ms: {
+            p50: Math.max(0, percentile(viaAgent, 50) - percentile(direct, 50)),
+            p95: Math.max(0, p95Agent - p95Direct)
+        }
+    };
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}

package/dist/src/commands/call.d.ts

@@ -0,0 +1,10 @@
+import { Logger } from "../logger.js";
+import { OrbitConfig } from "../types.js";
+export declare function cmdCall(config: OrbitConfig, logger: Logger, opts: {
+    target: string;
+    body: unknown;
+    timeoutMs?: number;
+    retries?: number;
+    runId?: string;
+    packFile?: string;
+}): Promise<void>;

package/dist/src/commands/call.js

@@ -0,0 +1,45 @@
+import { OrbitError } from "../errors.js";
+import { closeBus, connectBus } from "../nats.js";
+import { canUseAgent, requestAgent } from "../agent_ipc.js";
+import { executeRpcCall } from "../rpc_call.js";
+export async function cmdCall(config, logger, opts) {
+    const m = opts.target.match(/^([a-zA-Z0-9_-]+)\.([a-zA-Z0-9_-]+)$/);
+    if (!m)
+        throw new OrbitError("BAD_TARGET", "target must be <service>.<method>");
+    if (canUseAgent(config)) {
+        try {
+            const payload = await requestAgent(config, "call", {
+                target: opts.target,
+                body: opts.body,
+                timeoutMs: opts.timeoutMs ?? config.requestTimeoutMs,
+                retries: opts.retries ?? config.retries,
+                runId: opts.runId,
+                packFile: opts.packFile
+            }, opts.timeoutMs ?? config.requestTimeoutMs);
+            process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+            return;
+        }
+        catch (err) {
+            logger.warn("agent call failed, falling back to direct NATS path", { err: String(err) });
+        }
+    }
+    const nc = await connectBus(config.natsUrl);
+    const payload = (await executeRpcCall(config, nc, {
+        target: opts.target,
+        body: opts.body,
+        timeoutMs: opts.timeoutMs,
+        retries: opts.retries,
+        runId: opts.runId,
+        packFile: opts.packFile,
+        actor: "cli"
+    }));
+    if (payload?.ok === false) {
+        logger.error("service returned error", { code: payload.error?.code, message: payload.error?.message });
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        process.exitCode = 2;
+    }
+    else {
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    }
+    await closeBus(config.natsUrl);
+}

package/dist/src/commands/cell.d.ts

@@ -0,0 +1,3 @@
+import { Logger } from "../logger.js";
+import { OrbitConfig } from "../types.js";
+export declare function cmdCell(config: OrbitConfig, logger: Logger, args: string[]): Promise<void>;