orbit-bus 0.1.1

package/dist/src/spec.js

@@ -0,0 +1,30 @@
+import { OrbitError } from "./errors.js";
+import { readJsonFile } from "./util.js";
+export function loadServiceSpec(specPath) {
+    const spec = readJsonFile(specPath);
+    if (!spec || typeof spec !== "object" || !spec.methods || typeof spec.methods !== "object") {
+        throw new OrbitError("INVALID_SPEC", "spec must include methods object");
+    }
+    if (typeof spec.version === "string" && spec.version.trim().length === 0) {
+        throw new OrbitError("INVALID_SPEC", "spec version cannot be empty");
+    }
+    for (const [method, conf] of Object.entries(spec.methods)) {
+        const transport = conf.transport ?? "worker";
+        if (conf.request_schema !== undefined && (!conf.request_schema || typeof conf.request_schema !== "object" || Array.isArray(conf.request_schema))) {
+            throw new OrbitError("INVALID_SPEC", `method ${method} request_schema must be an object`);
+        }
+        if (conf.response_schema !== undefined && (!conf.response_schema || typeof conf.response_schema !== "object" || Array.isArray(conf.response_schema))) {
+            throw new OrbitError("INVALID_SPEC", `method ${method} response_schema must be an object`);
+        }
+        if (transport === "http") {
+            if (!conf.http_endpoint || typeof conf.http_endpoint !== "string") {
+                throw new OrbitError("INVALID_SPEC", `method ${method} missing http_endpoint for http transport`);
+            }
+            continue;
+        }
+        if (!conf.command || typeof conf.command !== "string") {
+            throw new OrbitError("INVALID_SPEC", `method ${method} missing command`);
+        }
+    }
+    return spec;
+}

package/dist/src/subjects.d.ts

@@ -0,0 +1,2 @@
+import { OrbitConfig } from "./types.js";
+export declare function prefixedSubject(config: OrbitConfig, ...parts: string[]): string;

package/dist/src/subjects.js

@@ -0,0 +1,4 @@
+export function prefixedSubject(config, ...parts) {
+    const clean = parts.map((p) => p.replace(/^\.+|\.+$/g, "")).filter(Boolean);
+    return [config.routing.subjectPrefix, ...clean].join(".");
+}

package/dist/src/trace.d.ts

@@ -0,0 +1,4 @@
+import { OrbitConfig, TraceEvent } from "./types.js";
+export declare function flushTraceWritesSync(): void;
+export declare function appendTraceEvent(config: OrbitConfig, event: TraceEvent): void;
+export declare function readTraceTimeline(config: OrbitConfig, runId: string): TraceEvent[];

package/dist/src/trace.js

@@ -0,0 +1,86 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir } from "./util.js";
+import { exportTraceEvent } from "./otel.js";
+const pendingWrites = new Map();
+let flushScheduled = false;
+let exitHooksInstalled = false;
+let traceDirEnsured = false;
+let pendingEventCount = 0;
+function flushPendingAsync() {
+    flushScheduled = false;
+    for (const [filePath, lines] of pendingWrites.entries()) {
+        if (lines.length === 0)
+            continue;
+        pendingEventCount -= lines.length;
+        if (pendingEventCount < 0)
+            pendingEventCount = 0;
+        pendingWrites.set(filePath, []);
+        const chunk = lines.join("");
+        fs.promises.appendFile(filePath, chunk, "utf-8").catch(() => {
+            // best effort trace write; tracing should never break request flow
+        });
+    }
+}
+export function flushTraceWritesSync() {
+    flushScheduled = false;
+    for (const [filePath, lines] of pendingWrites.entries()) {
+        if (lines.length === 0)
+            continue;
+        pendingEventCount -= lines.length;
+        if (pendingEventCount < 0)
+            pendingEventCount = 0;
+        pendingWrites.set(filePath, []);
+        fs.appendFileSync(filePath, lines.join(""), "utf-8");
+    }
+}
+function scheduleFlush(delayMs) {
+    if (flushScheduled)
+        return;
+    flushScheduled = true;
+    const timer = setTimeout(flushPendingAsync, delayMs);
+    timer.unref?.();
+}
+function installExitHooks() {
+    if (exitHooksInstalled)
+        return;
+    exitHooksInstalled = true;
+    process.once("beforeExit", flushTraceWritesSync);
+    process.once("exit", flushTraceWritesSync);
+}
+export function appendTraceEvent(config, event) {
+    if (config.performance.traceSampleRate <= 0)
+        return;
+    if (config.performance.traceSampleRate < 1 && Math.random() > config.performance.traceSampleRate)
+        return;
+    installExitHooks();
+    if (!traceDirEnsured) {
+        ensureDir(config.traceDir);
+        traceDirEnsured = true;
+    }
+    if (pendingEventCount >= config.performance.traceBufferMaxEvents) {
+        return;
+    }
+    const filePath = path.join(config.traceDir, `${event.run_id}.jsonl`);
+    const existing = pendingWrites.get(filePath) ?? [];
+    existing.push(`${JSON.stringify(event)}\n`);
+    pendingEventCount += 1;
+    pendingWrites.set(filePath, existing);
+    if (existing.length >= 32) {
+        flushPendingAsync();
+    }
+    else {
+        scheduleFlush(config.performance.traceFlushIntervalMs);
+    }
+    void exportTraceEvent(config, event);
+}
+export function readTraceTimeline(config, runId) {
+    flushTraceWritesSync();
+    const filePath = path.join(config.traceDir, `${runId}.jsonl`);
+    if (!fs.existsSync(filePath))
+        return [];
+    const lines = fs.readFileSync(filePath, "utf-8").split("\n").filter(Boolean);
+    return lines
+        .map((line) => JSON.parse(line))
+        .sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts));
+}

package/dist/src/types.d.ts

@@ -0,0 +1,133 @@
+export type EnvelopeKind = "request" | "response" | "event" | "capability" | "trace";
+export interface Envelope {
+    id: string;
+    run_id: string;
+    ts: string;
+    kind: EnvelopeKind;
+    schema_version: string;
+    payload: unknown;
+    data_pack?: {
+        bucket: string;
+        key: string;
+        bytes?: number;
+        content_type?: string;
+    };
+    provenance?: Record<string, unknown>;
+    cost?: Record<string, number>;
+    a2a?: {
+        task_id?: string;
+        thread_id?: string;
+        parent_message_id?: string;
+        capabilities?: string[];
+        traceparent?: string;
+        dedupe_key?: string;
+    };
+    hash: string;
+}
+export interface ServiceMethodSpec {
+    description?: string;
+    request_schema?: Record<string, unknown>;
+    response_schema?: Record<string, unknown>;
+    command?: string;
+    args?: string[];
+    timeout_ms?: number;
+    transport?: "spawn" | "worker" | "http";
+    http_method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    http_endpoint?: string;
+    headers?: Record<string, string>;
+}
+export interface ServiceSpec {
+    service?: string;
+    version?: string;
+    description?: string;
+    methods: Record<string, ServiceMethodSpec>;
+}
+export interface OrbitConfig {
+    natsUrl: string;
+    requestTimeoutMs: number;
+    retries: number;
+    logLevel: "debug" | "info" | "warn" | "error";
+    dataDir: string;
+    traceDir: string;
+    servicesDir: string;
+    activeContext: string;
+    kvBucket: string;
+    objectStoreBucket: string;
+    otel: {
+        endpoint?: string;
+        serviceName: string;
+    };
+    performance: {
+        mode: "balanced" | "hyper";
+        traceSampleRate: number;
+        trustedLocal: boolean;
+        traceBufferMaxEvents: number;
+        traceFlushIntervalMs: number;
+    };
+    routing: {
+        subjectPrefix: string;
+    };
+    runtime: {
+        serveMaxInflightGlobal: number;
+        serveMaxInflightPerMethod: number;
+        serveMaxQueueDepth: number;
+        workerPoolSize: number;
+        workerMaxPendingPerWorker: number;
+        apiMaxConcurrent: number;
+        apiMaxBodyBytes: number;
+        apiRequestTimeoutMs: number;
+        agentMaxConcurrent: number;
+        agentMaxRequestBytes: number;
+        publishDurableEnabled: boolean;
+        publishDurableTimeoutMs: number;
+        callRateLimitPerSec: number;
+        circuitBreakerFailureThreshold: number;
+        circuitBreakerCooldownMs: number;
+        circuitBreakerHalfOpenMax: number;
+        monitorMaxParallel: number;
+        monitorJitterMs: number;
+        monitorDownBackoffFactor: number;
+        monitorDownBackoffMaxMs: number;
+    };
+    api: {
+        authToken?: string;
+        allowedHosts: string[];
+        tls: {
+            enabled: boolean;
+            certFile?: string;
+            keyFile?: string;
+            caFile?: string;
+            requestClientCert: boolean;
+            requireClientCert: boolean;
+        };
+    };
+    agent: {
+        enabled: boolean;
+        socketPath: string;
+    };
+    broker: {
+        host: string;
+        port: number;
+        dockerImage: string;
+        containerName: string;
+    };
+}
+export interface TraceEvent {
+    span_id: string;
+    parent_span_id?: string;
+    run_id: string;
+    ts: string;
+    actor: string;
+    event: string;
+    svc?: string;
+    method?: string;
+    latency_ms?: number;
+    retry?: number;
+    error_code?: string;
+    detail?: string;
+}
+export interface OrbitContext {
+    natsUrl: string;
+    requestTimeoutMs: number;
+    retries: number;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/util.d.ts

@@ -0,0 +1,10 @@
+export declare function randomId(): string;
+export declare function sha256(input: string): string;
+export declare function stableStringify(value: unknown): string;
+export declare function expandHome(p: string): string;
+export declare function ensureDir(p: string): void;
+export declare function readJsonFile<T>(filePath: string): T;
+export declare function writeJsonFile(filePath: string, value: unknown): void;
+export declare function parseJsonInput(arg: string): unknown;
+export declare function argValue(args: string[], flag: string): string | undefined;
+export declare function hasFlag(args: string[], flag: string): boolean;

package/dist/src/util.js

@@ -0,0 +1,63 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { OrbitError } from "./errors.js";
+export function randomId() {
+    return crypto.randomUUID();
+}
+export function sha256(input) {
+    return crypto.createHash("sha256").update(input).digest("hex");
+}
+export function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        const rec = value;
+        const keys = Object.keys(rec).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(rec[k])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+export function expandHome(p) {
+    if (p.startsWith("~/"))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+export function ensureDir(p) {
+    fs.mkdirSync(p, { recursive: true });
+}
+export function readJsonFile(filePath) {
+    const text = fs.readFileSync(filePath, "utf-8");
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new OrbitError("BAD_JSON", `Invalid JSON in ${filePath}`, { err });
+    }
+}
+export function writeJsonFile(filePath, value) {
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+}
+export function parseJsonInput(arg) {
+    try {
+        if (arg.startsWith("@")) {
+            return readJsonFile(arg.slice(1));
+        }
+        return JSON.parse(arg);
+    }
+    catch (err) {
+        throw new OrbitError("BAD_JSON_INPUT", `Failed to parse JSON from ${arg}`, { err });
+    }
+}
+export function argValue(args, flag) {
+    const i = args.indexOf(flag);
+    if (i >= 0 && i + 1 < args.length)
+        return args[i + 1];
+    return undefined;
+}
+export function hasFlag(args, flag) {
+    return args.includes(flag);
+}

package/dist/src/worker_pool.d.ts

@@ -0,0 +1,9 @@
+interface WorkerExecutionOptions {
+    poolSize: number;
+    maxPendingPerWorker: number;
+}
+export declare class WorkerPool {
+    private readonly groups;
+    execute(command: string, args: string[], payload: unknown, timeoutMs: number, options: WorkerExecutionOptions): Promise<unknown>;
+}
+export {};

package/dist/src/worker_pool.js

@@ -0,0 +1,163 @@
+import { spawn } from "node:child_process";
+import readline from "node:readline";
+import { OrbitError } from "./errors.js";
+import { randomId } from "./util.js";
+class PersistentWorker {
+    command;
+    args;
+    child = null;
+    lines = null;
+    pending = new Map();
+    stderrTail = [];
+    idleTimer = null;
+    constructor(command, args) {
+        this.command = command;
+        this.args = args;
+    }
+    get pendingCount() {
+        return this.pending.size;
+    }
+    ensureStarted() {
+        if (this.child && !this.child.killed)
+            return this.child;
+        const child = spawn(this.command, this.args, { stdio: ["pipe", "pipe", "pipe"] });
+        this.child = child;
+        this.clearIdleTimer();
+        this.lines = readline.createInterface({ input: child.stdout });
+        this.lines.on("line", (line) => {
+            if (!line.trim())
+                return;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (!parsed.id)
+                return;
+            const pending = this.pending.get(parsed.id);
+            if (!pending)
+                return;
+            this.pending.delete(parsed.id);
+            clearTimeout(pending.timer);
+            if (parsed.ok === false) {
+                const msg = typeof parsed.error === "string" ? parsed.error : parsed.error?.message ?? "worker returned error";
+                pending.reject(new OrbitError(typeof parsed.error === "string" ? "WORKER_ERROR" : (parsed.error?.code ?? "WORKER_ERROR"), msg));
+                return;
+            }
+            pending.resolve(parsed.result);
+        });
+        child.stderr.on("data", (chunk) => {
+            const text = String(chunk).trim();
+            if (!text)
+                return;
+            this.stderrTail.push(text);
+            if (this.stderrTail.length > 20)
+                this.stderrTail.shift();
+        });
+        child.on("exit", () => {
+            this.child = null;
+            this.lines?.close();
+            this.lines = null;
+            this.clearIdleTimer();
+            const err = new OrbitError("WORKER_EXITED", `worker exited unexpectedly: ${this.command}`, {
+                command: this.command,
+                args: this.args,
+                stderr: this.stderrTail.join("\n")
+            });
+            for (const [id, pending] of this.pending.entries()) {
+                this.pending.delete(id);
+                clearTimeout(pending.timer);
+                pending.reject(err);
+            }
+        });
+        child.on("error", (err) => {
+            const wrapped = new OrbitError("WORKER_SPAWN_ERROR", "failed to spawn persistent worker", {
+                command: this.command,
+                args: this.args,
+                err
+            });
+            for (const [id, pending] of this.pending.entries()) {
+                this.pending.delete(id);
+                clearTimeout(pending.timer);
+                pending.reject(wrapped);
+            }
+        });
+        return child;
+    }
+    async request(payload, timeoutMs) {
+        const child = this.ensureStarted();
+        const requestId = randomId();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(requestId);
+                this.scheduleIdleShutdown();
+                reject(new OrbitError("WORKER_TIMEOUT", `worker request timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            timer.unref?.();
+            this.pending.set(requestId, { resolve, reject, timer });
+            const row = JSON.stringify({ id: requestId, payload });
+            child.stdin.write(`${row}\n`, "utf-8", (err) => {
+                if (!err)
+                    return;
+                this.pending.delete(requestId);
+                clearTimeout(timer);
+                this.scheduleIdleShutdown();
+                reject(new OrbitError("WORKER_WRITE_ERROR", "failed to write request to worker stdin", { err }));
+            });
+        });
+    }
+    onSettledRequest() {
+        if (this.pending.size > 0)
+            return;
+        this.scheduleIdleShutdown();
+    }
+    scheduleIdleShutdown() {
+        this.clearIdleTimer();
+        this.idleTimer = setTimeout(() => {
+            if (this.pending.size > 0)
+                return;
+            if (!this.child || this.child.killed)
+                return;
+            this.child.kill("SIGTERM");
+        }, 1000);
+        this.idleTimer.unref?.();
+    }
+    clearIdleTimer() {
+        if (!this.idleTimer)
+            return;
+        clearTimeout(this.idleTimer);
+        this.idleTimer = null;
+    }
+}
+export class WorkerPool {
+    groups = new Map();
+    async execute(command, args, payload, timeoutMs, options) {
+        const key = JSON.stringify({ command, args });
+        let group = this.groups.get(key);
+        if (!group) {
+            group = {
+                workers: Array.from({ length: options.poolSize }, () => new PersistentWorker(command, args)),
+                maxPendingPerWorker: options.maxPendingPerWorker
+            };
+            this.groups.set(key, group);
+        }
+        const sorted = [...group.workers].sort((a, b) => a.pendingCount - b.pendingCount);
+        const selected = sorted.find((w) => w.pendingCount < group.maxPendingPerWorker);
+        if (!selected) {
+            throw new OrbitError("WORKER_OVERLOADED", "all workers at max pending capacity", {
+                command,
+                args,
+                pool_size: group.workers.length,
+                max_pending_per_worker: group.maxPendingPerWorker
+            });
+        }
+        try {
+            return await selected.request(payload, timeoutMs);
+        }
+        finally {
+            selected.onSettledRequest();
+        }
+    }
+}