service-bridge 0.1.4

package/sdk/dist/grpc-client.d.ts

@@ -0,0 +1,344 @@
+export interface TraceCtx {
+    traceId: string;
+    spanId: string;
+}
+export declare function getTraceContext(): TraceCtx | undefined;
+export declare function runWithTraceContext<T>(ctx: TraceCtx, fn: () => T): T;
+/** Тип поля Protobuf-сообщения */
+export type RpcFieldType = "string" | "int32" | "int64" | "uint32" | "uint64" | "float" | "double" | "bool" | "bytes";
+/** Определение одного поля схемы */
+export interface RpcFieldDef {
+    /** Тип поля */
+    type: RpcFieldType;
+    /** Уникальный номер поля (field number в proto) */
+    id: number;
+    /** Повторяющееся поле (массив) */
+    repeated?: boolean;
+}
+/** Схема сообщения: имя поля → определение */
+export type RpcSchema = Record<string, RpcFieldDef>;
+/** Входная и выходная схемы для RPC-функции */
+export interface RpcSchemaOpts {
+    input?: RpcSchema;
+    output?: RpcSchema;
+}
+export interface RetryPolicy {
+    retries?: number;
+    retryDelay?: number;
+}
+export type WorkerTransport = "tls";
+export interface WorkerTLSOpts {
+    caCert?: string | Buffer;
+    cert?: string | Buffer;
+    key?: string | Buffer;
+    serverName?: string;
+}
+export interface ServiceBridgeOpts extends RetryPolicy {
+    timeout?: number;
+    /** @deprecated No longer used — discovery is now lazy via LookupFunction. */
+    discoveryTimeout?: number;
+    /**
+     * How often (ms) each SbResolver re-polls LookupFunction to discover new replicas.
+     * Dead replicas are detected instantly by gRPC subchannel health monitoring.
+     * Default: 10 000 ms.
+     */
+    discoveryRefreshMs?: number;
+    queueMaxSize?: number;
+    queueOverflow?: "drop-oldest" | "drop-newest" | "error";
+    heartbeatIntervalMs?: number;
+    workerTransport?: WorkerTransport;
+    /**
+     * Explicit mTLS cert materials for the worker gRPC server.
+     * When omitted, they are provisioned automatically from the server on `serve()`:
+     * the SDK generates a key pair locally and posts the public key to
+     * `POST /api/tls/provision` — the private key never leaves the process.
+     */
+    workerTLS?: WorkerTLSOpts;
+    /**
+     * Base URL for the HTTP admin API used for auto-provisioning and management.
+     * Defaults to the gRPC host on port 14444 (e.g. "http://127.0.0.1:14444").
+     */
+    adminUrl?: string;
+    /**
+     * Optional admin session cookie for browser-authenticated HTTP API endpoints
+     * (for example, DELETE /api/workflow-runs/:id).
+     */
+    adminSessionCookie?: string;
+    /**
+     * Optional CSRF token paired with adminSessionCookie for unsafe HTTP methods.
+     */
+    adminCsrfToken?: string;
+    /**
+     * Optional Origin header value required by CSRF/origin checks on admin endpoints.
+     */
+    adminOrigin?: string;
+    /**
+     * When `true` (default), automatically patches `console.log / .info / .warn / .error / .debug`
+     * so that all console output is also shipped to ServiceBridge as structured log entries.
+     * Original console output is preserved (pass-through).
+     * Set to `false` to opt out.
+     */
+    captureLogs?: boolean;
+}
+export interface RpcOpts extends RetryPolicy {
+    timeout?: number;
+    traceId?: string;
+    parentSpanId?: string;
+}
+export interface EventOpts {
+    traceId?: string;
+    parentSpanId?: string;
+    idempotencyKey?: string;
+    headers?: Record<string, string>;
+}
+export interface HandleEventOpts {
+    /** Maximum number of concurrent event deliveries to process simultaneously. */
+    concurrency?: number;
+    /** Number of messages to prefetch from the server ahead of processing. */
+    prefetch?: number;
+    groupName?: string;
+    retryPolicyJson?: string;
+    /** Server-side filter expression. Syntax: comma-separated AND conditions.
+     * Examples: "status=paid", "amount>100", "status=paid,amount>100", "region!=us-east" */
+    filterExpr?: string;
+}
+export interface HandleRpcOpts {
+    timeout?: number;
+    retryable?: boolean;
+    concurrency?: number;
+    /** Схема для авто-валидации и бинарного кодирования payload */
+    schema?: RpcSchemaOpts;
+    /**
+     * Whitelist of service names allowed to call this function.
+     * When set, the worker rejects Handle requests from services not in this list.
+     * Corresponds to the allowed_callers field on the service key.
+     * When mTLS is used, the x-caller-service header is cryptographically backed by the cert CN.
+     */
+    allowedCallers?: string[];
+}
+export interface ServeOpts {
+    host?: string;
+    instanceId?: string;
+    weight?: number;
+    transport?: WorkerTransport;
+    tls?: WorkerTLSOpts;
+}
+export interface ScheduleOpts {
+    cron?: string;
+    delay?: number;
+    timezone?: string;
+    misfire?: "fire_now" | "skip";
+    via?: "event" | "rpc" | "workflow";
+    retryPolicyJson?: string;
+}
+/** StreamWriter allows handlers to push incremental chunks during execution. */
+export interface StreamWriter {
+    /**
+     * Append a chunk to the run's named stream.
+     * @param data   - any JSON-serializable value
+     * @param key    - stream key (default: "default"). Use named keys for multiple streams
+     *                 (e.g. "output", "log", "progress").
+     */
+    write(data: unknown, key?: string): Promise<void>;
+    /** Node.js only. No-op placeholder for API symmetry; the stream lifecycle is managed by the runtime. */
+    end(key?: string): Promise<void>;
+}
+export interface EventContext {
+    traceId: string;
+    spanId: string;
+    refs: {
+        topic: string;
+        groupName: string;
+        messageId: string;
+        attempt: number;
+        headers: Record<string, string>;
+    };
+    retry(delayMs?: number): void;
+    reject(reason: string): void;
+    /** Real-time stream writer. Use ctx.stream.write(data) to push chunks to subscribers. */
+    stream: StreamWriter;
+}
+/** Context passed as optional second argument to RPC handlers. */
+export interface RpcContext {
+    traceId: string;
+    spanId: string;
+    /** Real-time stream writer. Use ctx.stream.write(data) to push chunks to subscribers. */
+    stream: StreamWriter;
+}
+type EventHandler = (payload: unknown, ctx: EventContext) => void | Promise<void>;
+type FnHandler = (payload: unknown, ctx?: RpcContext) => unknown | Promise<unknown>;
+export interface HttpSpan {
+    traceId: string;
+    spanId: string;
+    end(opts: {
+        statusCode?: number;
+        success?: boolean;
+        error?: string;
+    }): void;
+}
+export interface RunStreamEvent {
+    type: "chunk" | "run_complete";
+    runId: string;
+    key: string;
+    sequence: number;
+    data: unknown;
+    runStatus?: string;
+}
+export interface RunWorkflowResult {
+    runId: string;
+    traceId: string;
+}
+export interface RunWorkflowOpts {
+    /** Override the trace ID for this workflow run. */
+    traceId?: string;
+}
+export interface WorkflowOpts {
+    /** Maximum serialized state size in bytes. Defaults to 262144 (256 KB). */
+    stateLimitBytes?: number;
+    /** Default per-step timeout in milliseconds. Defaults to 30000 (30 s). */
+    stepTimeoutMs?: number;
+}
+export interface WatchRunOpts {
+    /** Filter by stream key. Empty = all keys. */
+    key?: string;
+    /** Replay chunks with sequence strictly greater than this value. 0 = full replay. */
+    fromSequence?: number;
+}
+export type ServiceBridgeErrorSeverity = "fatal" | "retriable" | "ignorable";
+export declare class ServiceBridgeError extends Error {
+    code?: number;
+    component: string;
+    operation: string;
+    severity: ServiceBridgeErrorSeverity;
+    retryable: boolean;
+    cause?: unknown;
+    constructor(opts: {
+        message: string;
+        code?: number;
+        component: string;
+        operation: string;
+        severity: ServiceBridgeErrorSeverity;
+        cause?: unknown;
+    });
+}
+/**
+ * A single node in a workflow DAG.
+ *
+ * - `id`    — unique step identifier; used in `deps` of other steps.
+ * - `deps`  — IDs of steps that must succeed before this step runs.
+ *             Empty array (default) = root step; receives the workflow input directly.
+ * - `if`    — optional filter expression (same syntax as event filters).
+ *             If it evaluates to false the step is skipped.
+ */
+export type WorkflowStep = {
+    id: string;
+    type: "rpc";
+    ref: string;
+    deps?: string[];
+    if?: string;
+    timeoutMs?: number;
+} | {
+    id: string;
+    type: "event";
+    ref: string;
+    deps?: string[];
+    if?: string;
+} | {
+    id: string;
+    type: "event_wait";
+    ref: string;
+    deps?: string[];
+    if?: string;
+    timeoutMs?: number;
+} | {
+    id: string;
+    type: "sleep";
+    durationMs: number;
+    deps?: string[];
+    if?: string;
+} | {
+    id: string;
+    type: "workflow";
+    ref: string;
+    deps?: string[];
+    if?: string;
+};
+export interface ServiceBridgeService {
+    rpc<T = unknown>(fn: string, payload?: unknown, opts?: RpcOpts): Promise<T>;
+    event(topic: string, payload?: unknown, opts?: EventOpts): Promise<string>;
+    job(target: string, opts: ScheduleOpts): Promise<string>;
+    workflow(name: string, steps: WorkflowStep[], opts?: WorkflowOpts): Promise<string>;
+    runWorkflow(name: string, input?: unknown, opts?: RunWorkflowOpts): Promise<RunWorkflowResult>;
+    cancelWorkflowRun(runId: string): Promise<void>;
+    /**
+     * Регистрирует обработчик RPC-функции.
+     * Если передан `opts.schema`, payload автоматически валидируется и
+     * кодируется/декодируется в бинарный Protobuf-формат вместо JSON.
+     * Схема также публикуется в server registry и используется вызывающей стороной.
+     */
+    handleRpc(fn: string, handler: FnHandler, opts?: HandleRpcOpts): ServiceBridgeService;
+    handleEvent(pattern: string, handler: EventHandler, opts?: HandleEventOpts): ServiceBridgeService;
+    serve(opts?: ServeOpts): Promise<void>;
+    stop(): void;
+    startHttpSpan(opts: {
+        method: string;
+        path: string;
+        traceId?: string;
+        parentSpanId?: string;
+    }): HttpSpan;
+    /**
+     * Register an HTTP endpoint in the ServiceBridge catalog.
+     * Call this once per route after your HTTP server is configured.
+     * The Express and Fastify adapters call this automatically — you only need
+     * this when integrating a different HTTP framework.
+     *
+     * @example
+     * await sb.registerHttpEndpoint({ method: 'GET', route: '/users/:id' });
+     */
+    registerHttpEndpoint(opts: {
+        /** HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS */
+        method: string;
+        /** Route pattern including parameter placeholders, e.g. "/users/:id" */
+        route: string;
+        /** Stable identifier for this process instance. Defaults to a per-SDK UUID. */
+        instanceId?: string;
+        /** Address where this service can be reached, e.g. "http://10.0.0.1:3000" */
+        endpoint?: string;
+        /** Service names allowed to call this endpoint (RBAC). Default: [] (all allowed) */
+        allowedCallers?: string[];
+        /** Optional JSON schema string for request validation metadata. */
+        requestSchemaJson?: string;
+        /** Optional JSON schema string for response validation metadata. */
+        responseSchemaJson?: string;
+        /** Optional transport label for the endpoint instance (e.g. "http", "https"). */
+        transport?: string;
+    }): Promise<void>;
+    /**
+     * Subscribe to a run's real-time stream.
+     * Replays existing chunks then forwards new ones until the run completes or the caller breaks.
+     *
+     * @example
+     * const stream = sb.watchRun(runId, { key: "output" });
+     * for await (const chunk of stream) {
+     *   process.stdout.write(chunk.data.token);
+     * }
+     */
+    watchRun(runId: string, opts?: WatchRunOpts): AsyncIterable<RunStreamEvent>;
+    /** @internal Used by captureConsole to forward intercepted log lines. */
+    readonly _log: (level: string, msg: string, attrs?: Record<string, string>) => void;
+}
+export declare function servicebridge(url: string, serviceKey: string, service?: string, globalOpts?: ServiceBridgeOpts): ServiceBridgeService;
+/**
+ * Intercepts `console.log / .info / .warn / .error / .debug` so that every
+ * call is **also** shipped to ServiceBridge as a structured log entry.
+ *
+ * Original console output is preserved (pass-through) — nothing changes on
+ * the terminal side. Trace correlation works automatically via AsyncLocalStorage.
+ *
+ * @example
+ * const svc = servicebridge("localhost:14445", "my-key", "orders");
+ * captureConsole(svc); // call once at startup
+ * console.log("order created"); // appears on stdout AND in ServiceBridge
+ */
+export declare function captureConsole(svc: ServiceBridgeService): void;
+export {};

package/sdk/dist/grpc-client.test.d.ts

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

package/sdk/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { EventContext, EventOpts, HandleEventOpts, HandleRpcOpts, HttpSpan, RetryPolicy, RpcContext, RpcFieldDef, RpcFieldType, RpcOpts, RpcSchema, RpcSchemaOpts, RunStreamEvent, RunWorkflowOpts, ScheduleOpts, ServeOpts, ServiceBridgeErrorSeverity, ServiceBridgeOpts, ServiceBridgeService, StreamWriter, TraceCtx, WatchRunOpts, WorkflowOpts, } from "./grpc-client";
+export { getTraceContext, runWithTraceContext, ServiceBridgeError, servicebridge, } from "./grpc-client";

package/sdk/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@servicebridge/sdk-node",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "generate:proto": "bun run scripts/generate-proto.ts",
+    "build": "bun run generate:proto && bun build src/index.ts --outdir=dist --target=node",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.9.0",
+    "@grpc/proto-loader": "^0.7.10",
+    "protobufjs": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.3.0"
+  }
+}

package/sdk/scripts/generate-proto.ts

@@ -0,0 +1,65 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as protoLoader from "@grpc/proto-loader";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, "..");
+const sdkRepoRoot = join(rootDir, "..", "..");
+const protoPath = join(sdkRepoRoot, "proto", "servicebridge.proto");
+const outPath = join(
+  rootDir,
+  "src",
+  "generated",
+  "servicebridge-package-definition.ts",
+);
+
+const packageDefinition = protoLoader.loadSync(protoPath, {
+  keepCase: true,
+  longs: String,
+  enums: String,
+  defaults: true,
+  oneofs: true,
+});
+
+function serialize(value: unknown): string {
+  if (Buffer.isBuffer(value)) {
+    return `Buffer.from([${Array.from(value).join(", ")}])`;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return "[]";
+    }
+    return `[\n${value.map((item) => indent(serialize(item))).join(",\n")}\n]`;
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+      return "{}";
+    }
+    return `{\n${entries
+      .map(
+        ([key, item]) => `${indent(JSON.stringify(key))}: ${serialize(item)}`,
+      )
+      .join(",\n")}\n}`;
+  }
+  return JSON.stringify(value);
+}
+
+function indent(value: string): string {
+  return value
+    .split("\n")
+    .map((line) => `  ${line}`)
+    .join("\n");
+}
+
+await mkdir(dirname(outPath), { recursive: true });
+await writeFile(
+  outPath,
+  `/* eslint-disable */
+/* auto-generated by packages/sdk/scripts/generate-proto.ts */
+
+export const servicebridgePackageDefinition = ${serialize(packageDefinition)} as const;
+`,
+  "utf8",
+);