orbit-bus 0.1.1

package/dist/src/api_contract.js

@@ -0,0 +1,81 @@
+import { OrbitError } from "./errors.js";
+import { assertJsonSchema } from "./json_schema.js";
+const ACTIONS = new Set(["call", "publish", "inspect", "ping"]);
+export function isOrbitApiAction(value) {
+    return ACTIONS.has(value);
+}
+export function actionFromApiPath(pathname) {
+    const parts = pathname.split("/").filter(Boolean);
+    if (parts.length !== 2)
+        return null;
+    if (parts[0] !== "v1")
+        return null;
+    const action = parts[1];
+    if (!isOrbitApiAction(action))
+        return null;
+    return action;
+}
+export function parseObjectPayload(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        throw new OrbitError("BAD_ARGS", "payload must be a JSON object");
+    }
+    return input;
+}
+const ACTION_PAYLOAD_SCHEMAS = {
+    ping: {
+        type: "object",
+        additionalProperties: false
+    },
+    call: {
+        type: "object",
+        required: ["target", "body"],
+        additionalProperties: false,
+        properties: {
+            target: { type: "string", minLength: 3, pattern: "^[a-zA-Z0-9_-]+\\.[a-zA-Z0-9_-]+$" },
+            body: {},
+            timeoutMs: { type: "integer", minimum: 1 },
+            retries: { type: "integer", minimum: 0 },
+            runId: { type: "string", minLength: 1 },
+            packFile: { type: "string", minLength: 1 },
+            taskId: { type: "string", minLength: 1 },
+            threadId: { type: "string", minLength: 1 },
+            parentMessageId: { type: "string", minLength: 1 },
+            capabilities: { type: "array", items: { type: "string", minLength: 1 } },
+            traceparent: { type: "string", minLength: 1 },
+            dedupeKey: { type: "string", minLength: 1 }
+        }
+    },
+    publish: {
+        type: "object",
+        required: ["topic", "body"],
+        additionalProperties: false,
+        properties: {
+            topic: { type: "string", minLength: 1 },
+            body: {},
+            runId: { type: "string", minLength: 1 },
+            packFile: { type: "string", minLength: 1 },
+            durable: { type: "boolean" },
+            dedupeKey: { type: "string", minLength: 1 },
+            taskId: { type: "string", minLength: 1 },
+            threadId: { type: "string", minLength: 1 },
+            parentMessageId: { type: "string", minLength: 1 },
+            capabilities: { type: "array", items: { type: "string", minLength: 1 } },
+            traceparent: { type: "string", minLength: 1 }
+        }
+    },
+    inspect: {
+        type: "object",
+        required: ["service"],
+        additionalProperties: false,
+        properties: {
+            service: { type: "string", minLength: 1 },
+            timeoutMs: { type: "integer", minimum: 1 }
+        }
+    }
+};
+export function validateActionPayload(action, payload) {
+    const schema = ACTION_PAYLOAD_SCHEMAS[action];
+    if (!schema)
+        throw new OrbitError("BAD_ARGS", `unsupported action ${action}`);
+    assertJsonSchema(payload, schema, `action payload (${action})`);
+}

package/dist/src/api_http.d.ts

@@ -0,0 +1,23 @@
+export interface ApiErrorBody {
+    type: "orbit_error";
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export interface ApiErrorResponse {
+    id: string;
+    ok: false;
+    error: ApiErrorBody;
+}
+export interface ApiSuccessResponse {
+    id: string;
+    ok: true;
+    payload: unknown;
+}
+export declare class ApiHttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+export declare function normalizeApiError(err: unknown): ApiHttpError;

package/dist/src/api_http.js

@@ -0,0 +1,62 @@
+import { OrbitError } from "./errors.js";
+export class ApiHttpError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+function isOrbitError(err) {
+    return err instanceof OrbitError;
+}
+function statusForCode(code) {
+    switch (code) {
+        case "UNAUTHORIZED":
+            return 401;
+        case "FORBIDDEN":
+        case "FORBIDDEN_BIND_HOST":
+            return 403;
+        case "NOT_FOUND":
+            return 404;
+        case "REQUEST_TIMEOUT":
+        case "TIMEOUT":
+        case "METHOD_TIMEOUT":
+            return 408;
+        case "PAYLOAD_TOO_LARGE":
+        case "REQUEST_TOO_LARGE":
+        case "AGENT_PAYLOAD_TOO_LARGE":
+            return 413;
+        case "RATE_LIMITED":
+        case "CIRCUIT_OPEN":
+        case "OVERLOADED":
+        case "API_OVERLOADED":
+        case "AGENT_OVERLOADED":
+            return 429;
+        case "METHOD_NOT_ALLOWED":
+            return 405;
+        case "BAD_ARGS":
+        case "BAD_TARGET":
+        case "BAD_JSON":
+        case "BAD_JSON_INPUT":
+        case "INVALID_SPEC":
+        case "SCHEMA_VALIDATION_FAILED":
+            return 400;
+        default:
+            return 500;
+    }
+}
+export function normalizeApiError(err) {
+    if (err instanceof ApiHttpError)
+        return err;
+    if (isOrbitError(err)) {
+        return new ApiHttpError(statusForCode(err.code), err.code, err.message, err.details);
+    }
+    const maybe = err;
+    const code = typeof maybe.code === "string" ? maybe.code : "API_ERROR";
+    const message = typeof maybe.message === "string" && maybe.message.length > 0 ? maybe.message : "internal API error";
+    return new ApiHttpError(statusForCode(code), code, message, maybe.details);
+}

package/dist/src/call_protection.d.ts

@@ -0,0 +1,5 @@
+import { OrbitConfig } from "./types.js";
+export declare function beforeCall(config: OrbitConfig, target: string): void;
+export declare function onCallSuccess(target: string): void;
+export declare function onCallFailure(config: OrbitConfig, target: string): void;
+export declare function afterCallAttempt(target: string): void;

package/dist/src/call_protection.js

@@ -0,0 +1,83 @@
+import { OrbitError } from "./errors.js";
+const rateBuckets = new Map();
+const circuits = new Map();
+function nowMs() {
+    return Date.now();
+}
+export function beforeCall(config, target) {
+    enforceRateLimit(config, target);
+    enforceCircuit(config, target);
+}
+export function onCallSuccess(target) {
+    const state = circuits.get(target);
+    if (!state)
+        return;
+    state.failures = 0;
+    state.mode = "closed";
+    state.halfOpenInFlight = 0;
+}
+export function onCallFailure(config, target) {
+    const state = circuits.get(target) ?? { mode: "closed", failures: 0, openedAtMs: 0, halfOpenInFlight: 0 };
+    state.failures += 1;
+    if (state.mode === "half_open") {
+        state.mode = "open";
+        state.openedAtMs = nowMs();
+        state.halfOpenInFlight = 0;
+        circuits.set(target, state);
+        return;
+    }
+    if (state.failures >= config.runtime.circuitBreakerFailureThreshold) {
+        state.mode = "open";
+        state.openedAtMs = nowMs();
+        state.halfOpenInFlight = 0;
+    }
+    circuits.set(target, state);
+}
+export function afterCallAttempt(target) {
+    const state = circuits.get(target);
+    if (!state)
+        return;
+    if (state.mode === "half_open" && state.halfOpenInFlight > 0) {
+        state.halfOpenInFlight -= 1;
+    }
+}
+function enforceRateLimit(config, target) {
+    const rate = config.runtime.callRateLimitPerSec;
+    if (rate <= 0)
+        return;
+    const now = nowMs();
+    const bucket = rateBuckets.get(target) ?? { tokens: rate, lastRefillMs: now };
+    const elapsedSec = Math.max(0, (now - bucket.lastRefillMs) / 1000);
+    bucket.tokens = Math.min(rate, bucket.tokens + elapsedSec * rate);
+    bucket.lastRefillMs = now;
+    if (bucket.tokens < 1) {
+        rateBuckets.set(target, bucket);
+        throw new OrbitError("RATE_LIMITED", `rate limited target ${target}`);
+    }
+    bucket.tokens -= 1;
+    rateBuckets.set(target, bucket);
+}
+function enforceCircuit(config, target) {
+    const cooldownMs = config.runtime.circuitBreakerCooldownMs;
+    const halfOpenMax = config.runtime.circuitBreakerHalfOpenMax;
+    const now = nowMs();
+    const state = circuits.get(target) ?? { mode: "closed", failures: 0, openedAtMs: 0, halfOpenInFlight: 0 };
+    if (state.mode === "open") {
+        if (now - state.openedAtMs >= cooldownMs) {
+            state.mode = "half_open";
+            state.halfOpenInFlight = 0;
+        }
+        else {
+            circuits.set(target, state);
+            throw new OrbitError("CIRCUIT_OPEN", `circuit open for target ${target}`);
+        }
+    }
+    if (state.mode === "half_open") {
+        if (state.halfOpenInFlight >= halfOpenMax) {
+            circuits.set(target, state);
+            throw new OrbitError("CIRCUIT_OPEN", `circuit half-open limit reached for ${target}`);
+        }
+        state.halfOpenInFlight += 1;
+    }
+    circuits.set(target, state);
+}

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

@@ -0,0 +1,13 @@
+import { Logger } from "../logger.js";
+import { OrbitConfig } from "../types.js";
+import { CellRoute } from "./routing.js";
+interface GatewayOptions {
+    socketPath?: string;
+    host?: string;
+    port?: number;
+    cellId: string;
+    routes: CellRoute[];
+    fromLatest?: boolean;
+}
+export declare function runCellGateway(config: OrbitConfig, logger: Logger, opts: GatewayOptions): Promise<void>;
+export {};

package/dist/src/cell/gateway.js

@@ -0,0 +1,171 @@
+import crypto from "node:crypto";
+import { connectEchoClient } from "../echo/client.js";
+import { closeBus, connectBus, decodeJson, encodeJson } from "../nats.js";
+class RecentHashCache {
+    entries = [];
+    has(hash) {
+        this.prune();
+        return this.entries.some((entry) => entry.hash === hash);
+    }
+    add(hash, ttlMs) {
+        this.prune();
+        this.entries.push({ hash, expiresAt: Date.now() + ttlMs });
+        if (this.entries.length > 4096)
+            this.entries.splice(0, this.entries.length - 4096);
+    }
+    prune() {
+        const now = Date.now();
+        while (this.entries.length > 0 && this.entries[0].expiresAt <= now) {
+            this.entries.shift();
+        }
+    }
+}
+class EchoPublisher {
+    client;
+    pending = [];
+    closed = false;
+    constructor(client) {
+        this.client = client;
+        this.client.onLine((line) => {
+            const wait = this.pending.shift();
+            if (!wait)
+                return;
+            try {
+                const msg = JSON.parse(line);
+                if (msg.ok)
+                    wait.resolve();
+                else
+                    wait.reject(new Error(msg.error ?? "echo publish failed"));
+            }
+            catch (err) {
+                wait.reject(err);
+            }
+        });
+    }
+    publish(channel, payloadBase64) {
+        if (this.closed)
+            return Promise.reject(new Error("echo publisher closed"));
+        return new Promise((resolve, reject) => {
+            this.pending.push({ resolve, reject });
+            this.client.send({ type: "publish", channel, payloadBase64 });
+        });
+    }
+    close() {
+        this.closed = true;
+        this.client.close();
+        while (this.pending.length > 0) {
+            const wait = this.pending.shift();
+            wait?.reject(new Error("echo publisher closed"));
+        }
+    }
+}
+function sha256Base64(payloadBase64) {
+    return crypto.createHash("sha256").update(payloadBase64).digest("hex");
+}
+export async function runCellGateway(config, logger, opts) {
+    const endpoint = {
+        socketPath: opts.socketPath,
+        host: opts.host,
+        port: opts.port
+    };
+    const nc = await connectBus(config.natsUrl);
+    const ingressPublisher = new EchoPublisher(await connectEchoClient(endpoint));
+    const localSubs = [];
+    const recentIngress = new RecentHashCache();
+    const stopLocalLoops = [];
+    const stopNetworkLoops = [];
+    for (const route of opts.routes) {
+        if (route.localToNetwork) {
+            const client = await connectEchoClient(endpoint);
+            client.onLine((line) => {
+                const msg = JSON.parse(line);
+                if (!msg.ok || msg.type !== "event" || !msg.payloadBase64)
+                    return;
+                const hash = sha256Base64(msg.payloadBase64);
+                if (recentIngress.has(hash))
+                    return;
+                const payloadText = Buffer.from(msg.payloadBase64, "base64").toString("utf-8");
+                let payload;
+                try {
+                    payload = JSON.parse(payloadText);
+                }
+                catch {
+                    payload = { raw_base64: msg.payloadBase64 };
+                }
+                const envelope = {
+                    channel: route.channel,
+                    payload,
+                    meta: { cell_id: opts.cellId, ts: new Date().toISOString() }
+                };
+                nc.publish(route.subject, encodeJson(envelope));
+            });
+            client.send({ type: "subscribe", channel: route.channel, fromLatest: opts.fromLatest ?? true });
+            localSubs.push(client);
+            stopLocalLoops.push(() => client.close());
+        }
+        if (route.networkToLocal) {
+            const sub = nc.subscribe(route.subject);
+            const stop = { active: true };
+            stopNetworkLoops.push(() => {
+                stop.active = false;
+                sub.unsubscribe();
+            });
+            void (async () => {
+                for await (const msg of sub) {
+                    if (!stop.active)
+                        break;
+                    let envelope;
+                    try {
+                        envelope = decodeJson(msg.data);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (envelope.meta?.cell_id === opts.cellId)
+                        continue;
+                    const payload = "payload" in envelope ? envelope.payload : envelope;
+                    const payloadBase64 = Buffer.from(JSON.stringify(payload)).toString("base64");
+                    recentIngress.add(sha256Base64(payloadBase64), 5000);
+                    try {
+                        await ingressPublisher.publish(route.channel, payloadBase64);
+                    }
+                    catch (err) {
+                        logger.warn("cell ingress publish failed", {
+                            channel: route.channel,
+                            subject: route.subject,
+                            err: err.message
+                        });
+                    }
+                }
+            })().catch((err) => {
+                logger.error("network->local loop crashed", {
+                    channel: route.channel,
+                    subject: route.subject,
+                    err: err.message
+                });
+            });
+        }
+    }
+    logger.info("cell gateway online", {
+        cell_id: opts.cellId,
+        routes: opts.routes.map((route) => ({
+            channel: route.channel,
+            mode: route.mode,
+            subject: route.subject
+        }))
+    });
+    const shutdown = async () => {
+        stopLocalLoops.forEach((fn) => fn());
+        stopNetworkLoops.forEach((fn) => fn());
+        localSubs.forEach((client) => client.close());
+        ingressPublisher.close();
+        await closeBus(config.natsUrl);
+    };
+    process.once("SIGINT", () => {
+        void shutdown().finally(() => process.exit(0));
+    });
+    process.once("SIGTERM", () => {
+        void shutdown().finally(() => process.exit(0));
+    });
+    await nc.closed();
+}

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

@@ -0,0 +1,18 @@
+import { OrbitConfig } from "../types.js";
+export type CellRouteMode = "local_only" | "replicate" | "global_only";
+export interface CellRoute {
+    channel: string;
+    mode: CellRouteMode;
+    subject: string;
+    localToNetwork: boolean;
+    networkToLocal: boolean;
+}
+export interface CellRoutingPlan {
+    routes: CellRoute[];
+    source?: string;
+}
+export declare function resolveCellRoutingPlan(config: OrbitConfig, opts: {
+    routesFile?: string;
+    channels?: string[];
+    defaultMode?: CellRouteMode;
+}): CellRoutingPlan;

package/dist/src/cell/routing.js

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+function defaultSubject(config, channel) {
+    return `${config.routing.subjectPrefix}.cell.channels.${channel}`;
+}
+function isValidChannel(channel) {
+    return /^[A-Za-z0-9._-]+$/.test(channel);
+}
+function parseMode(value) {
+    if (value === "local_only" || value === "replicate" || value === "global_only")
+        return value;
+    return undefined;
+}
+function toRoute(config, channel, mode, subject) {
+    if (!isValidChannel(channel)) {
+        throw new Error(`invalid channel '${channel}': use [A-Za-z0-9._-]`);
+    }
+    const outSubject = (subject ?? defaultSubject(config, channel)).trim();
+    if (!outSubject || outSubject.includes(" ")) {
+        throw new Error(`invalid subject for channel '${channel}'`);
+    }
+    return {
+        channel,
+        mode,
+        subject: outSubject,
+        localToNetwork: mode === "replicate" || mode === "global_only",
+        networkToLocal: mode === "replicate"
+    };
+}
+export function resolveCellRoutingPlan(config, opts) {
+    const defaultMode = opts.defaultMode ?? "replicate";
+    if (opts.routesFile) {
+        const raw = JSON.parse(fs.readFileSync(opts.routesFile, "utf-8"));
+        const routes = Object.entries(raw).map(([channel, value]) => {
+            if (typeof value === "string") {
+                const mode = parseMode(value);
+                if (!mode)
+                    throw new Error(`invalid mode '${value}' for channel '${channel}'`);
+                return toRoute(config, channel, mode);
+            }
+            const mode = parseMode(value?.mode) ?? defaultMode;
+            return toRoute(config, channel, mode, value?.subject);
+        });
+        return { routes, source: opts.routesFile };
+    }
+    const channels = opts.channels && opts.channels.length > 0 ? opts.channels : ["agent.loop"];
+    const routes = channels.map((channel) => toRoute(config, channel, defaultMode));
+    return { routes };
+}

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

@@ -0,0 +1,7 @@
+export interface CellRouteTemplateEntry {
+    mode: "local_only" | "replicate" | "global_only";
+    subject: string;
+}
+export type CellRoutesTemplate = Record<string, CellRouteTemplateEntry>;
+export type CellProfile = "production" | "high_throughput";
+export declare function buildCellRoutesTemplate(profile: CellProfile, subjectPrefix: string): CellRoutesTemplate;

package/dist/src/cell/template.js

@@ -0,0 +1,24 @@
+function subject(subjectPrefix, tail) {
+    return `${subjectPrefix}.${tail}`;
+}
+export function buildCellRoutesTemplate(profile, subjectPrefix) {
+    const cleanPrefix = (subjectPrefix || "orbit").trim();
+    if (!cleanPrefix || cleanPrefix.includes(" ")) {
+        throw new Error("invalid subject prefix");
+    }
+    if (profile === "high_throughput") {
+        return {
+            "agent.loop": { mode: "replicate", subject: subject(cleanPrefix, "cell.channels.agent.loop") },
+            "agent.audit": { mode: "global_only", subject: subject(cleanPrefix, "cell.audit.events") },
+            "agent.metrics": { mode: "global_only", subject: subject(cleanPrefix, "cell.metrics.events") },
+            "agent.trace": { mode: "global_only", subject: subject(cleanPrefix, "cell.trace.events") },
+            "agent.debug": { mode: "local_only", subject: subject(cleanPrefix, "cell.debug.events") }
+        };
+    }
+    return {
+        "agent.loop": { mode: "replicate", subject: subject(cleanPrefix, "cell.channels.agent.loop") },
+        "agent.audit": { mode: "global_only", subject: subject(cleanPrefix, "cell.audit.events") },
+        "agent.metrics": { mode: "global_only", subject: subject(cleanPrefix, "cell.metrics.events") },
+        "agent.debug": { mode: "local_only", subject: subject(cleanPrefix, "cell.debug.events") }
+    };
+}

package/dist/src/cli.d.ts

@@ -0,0 +1 @@
+export declare function run(argv: string[], cwd: string): Promise<void>;