service-bridge 1.8.1-dev.36 → 1.8.2-dev.39

package/README.md

@@ -99,7 +99,7 @@ const sb = servicebridge(
   process.env.SERVICEBRIDGE_SERVICE_KEY!,
 );
 
-sb.handleRpc("charge", async (payload: { orderId: string; amount: number }) => {
+sb.handleRpc("payment.charge", async (payload: { orderId: string; amount: number }) => {
   return { ok: true, txId: `tx_${Date.now()}`, orderId: payload.orderId };
 });
 
@@ -116,7 +116,7 @@ const sb = servicebridge(
   process.env.SERVICEBRIDGE_SERVICE_KEY!,
 );
 
-const result = await sb.rpc<{ ok: boolean; txId: string }>("payments/charge", {
+const result = await sb.rpc<{ ok: boolean; txId: string }>("payments", "payment.charge", {
   orderId: "ord_42",
   amount: 4990,
 });
@@ -153,7 +153,7 @@ import { servicebridge } from "service-bridge";
 
 const payments = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
 
-payments.handleRpc("charge", async (payload: { orderId: string; amount: number }, ctx) => {
+payments.handleRpc("payment.charge", async (payload: { orderId: string; amount: number }, ctx) => {
   await ctx?.stream.write({ status: "charging", orderId: payload.orderId }, "progress");
 
   // ... charge logic ...
@@ -171,7 +171,7 @@ await payments.serve({ host: "localhost" });
 const orders = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
 
 // Call payments, then publish event
-const charge = await orders.rpc<{ ok: boolean; txId: string }>("payments/charge", {
+const charge = await orders.rpc<{ ok: boolean; txId: string }>("payments", "payment.charge", {
   orderId: "ord_42",
   amount: 4990,
 });
@@ -203,8 +203,8 @@ await notifications.serve({ host: "localhost" });
 // --- Orchestrate as a workflow ---
 
 await orders.workflow("order.fulfillment", [
-  { id: "reserve",  type: "rpc",        ref: "inventory/reserve" },
-  { id: "charge",   type: "rpc",        ref: "payments/charge",      deps: ["reserve"] },
+  { id: "reserve",  type: "rpc",        ref: "inventory/inventory.reserve" },
+  { id: "charge",   type: "rpc",        ref: "payments/payment.charge",      deps: ["reserve"] },
   { id: "wait_dlv", type: "event_wait", ref: "shipping.delivered",   deps: ["charge"] },
   { id: "notify",   type: "event",      ref: "orders.fulfilled",     deps: ["wait_dlv"] },
 ]);
@@ -277,13 +277,12 @@ across all three SDKs. Parity differences are naming-only (language idioms):
 function servicebridge(
   url: string,
   serviceKey: string,
-  serviceOrOpts?: string | ServiceBridgeOpts,
-  maybeGlobalOpts?: ServiceBridgeOpts,
+  opts?: ServiceBridgeOpts,
 ): ServiceBridgeService
 ```
 
 Creates an SDK client instance.
-Service identity is resolved by the runtime from `serviceKey`; passing a third `service` argument is legacy-only.
+Service identity is resolved by the runtime from `serviceKey`.
 
 `ServiceBridgeOpts`:
 
@@ -318,22 +317,15 @@ type WorkerTLSOpts = {
 
 ---
 
-### `rpc(fn, payload?, opts?)`
+### `rpc(service, fn, payload?, opts?)`
 
 ```ts
-rpc<T = unknown>(fn: string, payload?: unknown, opts?: RpcOpts): Promise<T>
+rpc<T = unknown>(service: string, fn: string, payload?: unknown, opts?: RpcOpts): Promise<T>
 ```
 
 Calls a registered RPC handler on another service. Direct gRPC path, no proxy.
 
-**Function name formats** — `fn` accepts two formats:
-
-| Format | Example | When to use |
-|---|---|---|
-| Plain name | `"charge"` | Function name is globally unique across all services. Resolved automatically via service discovery. |
-| Canonical name | `"payments/charge"` | Multiple services expose a function with the same plain name, or you want to be explicit about the target service. |
-
-Both formats are interchangeable when the name is unique globally. Canonical format is recommended in production for clarity and to avoid ambiguity as your service count grows.
+**Arguments** — `service` is the callee’s logical name; `fn` is the name used in `handleRpc` (e.g. `payment.charge`). Use **dot notation** in `fn` to group methods. Do not put `/` in `fn`.
 
 `RpcOpts`:
 
@@ -347,11 +339,7 @@ Both formats are interchangeable when the name is unique globally. Canonical for
 | `mode` | `"direct" \| "proxy"` | Transport mode. `"direct"` (default) connects directly to the worker. `"proxy"` routes through the control plane when direct connection is unavailable. |
 
 ```ts
-// plain name — works when "get" is unique across services
-const user = await sb.rpc<{ id: string; name: string }>("get", { id: "u_1" });
-
-// canonical name — explicit service target, always unambiguous
-const user = await sb.rpc<{ id: string; name: string }>("users/get", { id: "u_1" }, {
+const user = await sb.rpc<{ id: string; name: string }>("users", "user.get", { id: "u_1" }, {
   timeout: 5000,
   retries: 2,
 });
@@ -421,7 +409,7 @@ Registers a scheduled or delayed job.
 | `retryPolicyJson` | `string` | Retry policy JSON string. |
 
 ```ts
-await sb.job("billing/collect", {
+await sb.job("billing/billing.collect", {
   cron: "0 * * * *",
   timezone: "UTC",
   via: "rpc",
@@ -466,8 +454,8 @@ interface WorkflowOpts {
 
 ```ts
 await sb.workflow("order.fulfillment", [
-  { id: "reserve", type: "rpc", ref: "inventory/reserve" },
-  { id: "charge", type: "rpc", ref: "payments/charge", deps: ["reserve"] },
+  { id: "reserve", type: "rpc", ref: "inventory/inventory.reserve" },
+  { id: "charge", type: "rpc", ref: "payments/payment.charge", deps: ["reserve"] },
   { id: "wait_5m", type: "sleep", durationMs: 300_000, deps: ["charge"] },
   { id: "notify", type: "event", ref: "orders.fulfilled", deps: ["wait_5m"] },
 ]);
@@ -554,7 +542,7 @@ Registers an RPC handler. Chainable.
 | `allowedCallers` | `string[]` | Allow-list of caller service names. |
 
 ```ts
-sb.handleRpc("ai/generate", async (payload: { prompt: string }, ctx) => {
+sb.handleRpc("ai.generate", async (payload: { prompt: string }, ctx) => {
   await ctx?.stream.write({ token: "Hello" }, "output");
   await ctx?.stream.write({ token: " world" }, "output");
   return { text: "Hello world" };
@@ -586,13 +574,12 @@ Registers an event consumer handler. Chainable.
 
 | Option | Type | Description |
 |---|---|---|
-| `groupName` | `string` | Consumer group name. Default: `<service-key-id>.<pattern>`. |
 | `concurrency` | `number` | Advisory concurrency hint (currently not hard-enforced). |
 | `prefetch` | `number` | Advisory prefetch hint (currently not hard-enforced). |
 | `retryPolicyJson` | `string` | Retry policy JSON string. |
 | `filterExpr` | `string` | Server-side filter expression. |
 
-Duplicate `groupName` registration throws an error.
+Duplicate pattern registration within the same service throws an error.
 
 **Delivery guarantee**: once a message is accepted by the runtime, delivery to each consumer group
 is guaranteed. If the consumer is offline, the message waits in the server-side queue and is
@@ -830,7 +817,7 @@ app.use(servicebridgeMiddleware({
 }));
 
 app.get("/users/:id", async (req, res) => {
-  const user = await req.servicebridge.rpc("users/get", { id: req.params.id });
+  const user = await req.servicebridge.rpc("users", "user.get", { id: req.params.id });
   res.json(user);
 });
 ```
@@ -886,7 +873,7 @@ await app.register(servicebridgePlugin, {
 });
 
 app.get("/users/:id", wrapHandler(async (request, reply) => {
-  const user = await request.servicebridge.rpc("users/get", {
+  const user = await request.servicebridge.rpc("users", "user.get", {
     id: (request.params as any).id,
   });
   return reply.send(user);
@@ -983,7 +970,7 @@ const sb = servicebridge(
 import { servicebridge, ServiceBridgeError } from "service-bridge";
 
 try {
-  await sb.rpc("payments/charge", { orderId: "ord_1" });
+  await sb.rpc("payments", "payment.charge", { orderId: "ord_1" });
 } catch (e) {
   if (e instanceof ServiceBridgeError) {
     console.error(e.component, e.operation, e.severity, e.retryable, e.code);
@@ -1055,7 +1042,6 @@ import { V2SessionClient, validateV2Config } from 'service-bridge';
 
 const cfg = {
   serverAddress: 'localhost:9090',
-  serviceName: 'my-worker',
   instanceId: 'worker-1',
   zone: 'us-east-1a',
   transportMode: 'direct' as const,

package/dist/index.js

@@ -177,7 +177,6 @@ class V2SessionClient {
   constructor(config) {
     this.config = {
       serverAddress: config.serverAddress,
-      serviceName: config.serviceName,
       instanceId: config.instanceId,
       zone: config.zone ?? "",
       transportMode: config.transportMode ?? "direct",
@@ -209,7 +208,6 @@ class V2SessionClient {
     const rs = this.position.getResumeState(this.resumeToken, this.epoch);
     return {
       identity: {
-        serviceName: this.config.serviceName,
         instanceId: this.config.instanceId,
         transport: this.config.transportMode
       },
@@ -309,8 +307,6 @@ class V2SessionClient {
 function validateV2Config(cfg) {
   if (!cfg.serverAddress)
     throw new Error("servicebridge: serverAddress is required");
-  if (!cfg.serviceName)
-    throw new Error("servicebridge: serviceName is required");
   if (!cfg.instanceId)
     throw new Error("servicebridge: instanceId is required");
   if (cfg.transportMode && cfg.transportMode !== "direct" && cfg.transportMode !== "proxy") {
@@ -632,7 +628,7 @@ function reportSDKError(operation, err, component = "sdk") {
   }
   return normalized;
 }
-function parseCanonicalFunctionName(target) {
+function parseRegistryCanonicalName(target) {
   const canonicalName = target.trim();
   if (!canonicalName)
     return null;
@@ -863,7 +859,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
   const service = typeof serviceOrOpts === "string" ? serviceOrOpts.trim() : "";
   const globalOpts = typeof serviceOrOpts === "string" ? maybeGlobalOpts : serviceOrOpts ?? {};
   const parsedServiceKey = parseServiceKeyV2(serviceKey);
-  const defaultConsumerPrefix = service || parsedServiceKey.keyId || "consumer";
+  const defaultConsumerPrefix = parsedServiceKey.keyId || "consumer";
   const meta = new grpc.Metadata;
   meta.add("x-service-key", serviceKey);
   const rawUrl = url.trim();
@@ -1065,7 +1061,6 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
   function pushLog(level, msg, attrs) {
     const tc = traceStorage.getStore();
     const entry = {
-      service_name: service,
       level,
       message: msg,
       timestamp_ns: String(Date.now() * 1e6),
@@ -1147,7 +1142,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
         const endpoints = parseEndpointsFromWire(res.endpoints);
         const isNewFunction = !functionMeta.has(canonicalName);
         if (isNewFunction) {
-          const parsed = parseCanonicalFunctionName(canonicalName);
+          const parsed = parseRegistryCanonicalName(canonicalName);
           if (parsed) {
             functionMeta.set(canonicalName, {
               canonicalName,
@@ -1401,7 +1396,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
                 headers: toWireStringMap(op.opts?.headers),
                 trace_id: op.opts?.traceId ?? "",
                 parent_span_id: op.opts?.parentSpanId ?? "",
-                producer_service: service,
+                producer_service: defaultConsumerPrefix,
                 idempotency_key: op.opts?.idempotencyKey ?? ""
               }, meta, unaryDeadlineOptions(), (err) => err ? rej(err) : res());
             });
@@ -1533,7 +1528,6 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       await new Promise((resolve, reject) => {
         stub.Reconcile({
           identity: {
-            service_name: service,
             instance_id: state.instanceId,
             endpoint: state.endpoint,
             transport: state.transport
@@ -1991,7 +1985,6 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
     if (!v2Session) {
       v2Session = new V2SessionClient({
         serverAddress: target,
-        serviceName: service,
         instanceId: serveState.instanceId,
         transportMode: "direct",
         maxInflight: serveState.maxInFlight,
@@ -2004,7 +1997,6 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
     stream.write({
       hello: {
         identity: {
-          service_name: hf.identity.serviceName,
           instance_id: hf.identity.instanceId,
           endpoint: serveState.endpoint,
           transport: serveState.transport
@@ -2120,35 +2112,40 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
     }
   }
   const svc = {
-    async rpc(fn, payload, opts) {
+    async rpc(targetService, fn, payload, opts) {
       try {
         await _controlReady;
       } catch (err) {
         throw normalizeServiceError(err, "control-plane");
       }
+      const svcName = targetService.trim();
+      const fname = fn.trim();
+      if (!svcName || !fname) {
+        throw new Error("rpc: service and fn are required");
+      }
+      const lookupKey = `${svcName}/${fname}`;
       const tc = traceStorage.getStore();
       const traceId = opts?.traceId ?? tc?.traceId ?? crypto.randomUUID();
       const maxRetries = normalizeNonNegativeInt(opts?.retries ?? globalOpts.retries ?? 3, 3);
       const baseDelay = normalizePositiveInt(opts?.retryDelay ?? globalOpts.retryDelay ?? 300, 300);
       const timeout = normalizePositiveInt(opts?.timeout ?? globalOpts.timeout ?? 30000, 30000);
-      let canonical = resolveCanonical(fn);
+      let canonical = resolveCanonical(lookupKey);
       if (!canonical) {
-        await doLookupFunction(fn);
-        canonical = resolveCanonical(fn);
+        await doLookupFunction(lookupKey);
+        canonical = resolveCanonical(lookupKey);
       }
       if (!canonical)
-        throw normalizeServiceError(new Error(`No endpoints available for RPC: ${fn}`), fn, "worker");
+        throw normalizeServiceError(new Error(`No endpoints available for RPC: ${lookupKey}`), lookupKey, "worker");
       const fmeta = functionMeta.get(canonical);
       if (fmeta && !containsOrAll(fmeta.allowedCallers, service)) {
-        throw new Error(`Service "${service}" is not allowed to call "${fn}". ` + `Permitted callers: ${fmeta.allowedCallers.join(", ")}`);
+        throw new Error(`Service "${service}" is not allowed to call "${lookupKey}". ` + `Permitted callers: ${fmeta.allowedCallers.join(", ")}`);
       }
       const inputSchema = fmeta?.inputSchema;
       const outputSchema = fmeta?.outputSchema;
       const inputBuf = inputSchema ? encodeWithSchema(inputSchema, payload) : toJsonBuffer(payload);
       const telemetryInputBuf = toJsonBuffer(payload);
-      const _parsedCanonical = parseCanonicalFunctionName(canonical);
-      const rpcFnName = _parsedCanonical?.fnName ?? canonical;
-      const rpcServiceName = _parsedCanonical?.serviceName ?? "";
+      const rpcFnName = fname;
+      const rpcServiceName = svcName;
       const rootSpanId = crypto.randomUUID();
       const parentSpanId = opts?.parentSpanId ?? tc?.spanId ?? "";
       const rootStartedAt = Date.now();
@@ -2166,12 +2163,12 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
             }, meta, { deadline: new Date(Date.now() + timeout) }, (err, res) => {
               if (err) {
                 reportCallAsync(traceId, rootSpanId, rpcFnName, rootStartedAt, telemetryInputBuf, false, 1, undefined, String(err), "rpc", parentSpanId, rpcServiceName);
-                return reject(normalizeServiceError(err, fn, "control-plane"));
+                return reject(normalizeServiceError(err, lookupKey, "control-plane"));
               }
               if (!res?.success) {
                 const errMsg = res?.error ?? "proxy call failed";
                 reportCallAsync(traceId, rootSpanId, rpcFnName, rootStartedAt, telemetryInputBuf, false, 1, undefined, errMsg, "rpc", parentSpanId, rpcServiceName);
-                return reject(normalizeServiceError(new Error(errMsg), fn, "worker"));
+                return reject(normalizeServiceError(new Error(errMsg), lookupKey, "worker"));
               }
               reportCallAsync(traceId, rootSpanId, rpcFnName, rootStartedAt, telemetryInputBuf, true, 1, res.output, "", "rpc", parentSpanId, rpcServiceName);
               try {
@@ -2197,8 +2194,8 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
           try {
             const attemptTimeoutMs = timeout;
             const deadline = new Date(Date.now() + attemptTimeoutMs);
-            const fn2 = fmeta?.fnName ?? canonical;
-            if (!fn2)
+            const workerFnName = fmeta?.fnName ?? fname;
+            if (!workerFnName)
               throw new Error("unreachable");
             const res = await new Promise((resolve, reject) => {
               let settled = false;
@@ -2225,7 +2222,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
               };
               try {
                 unaryCall = workerClient.Handle({
-                  function_name: fn2,
+                  function_name: workerFnName,
                   payload: inputBuf,
                   trace_id: traceId,
                   span_id: attemptSpanId,
@@ -2263,7 +2260,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
             }
           }
         }
-        throw normalizeServiceError(lastError, fn, "worker");
+        throw normalizeServiceError(lastError, lookupKey, "worker");
       });
     },
     event(topic, payload, opts) {
@@ -2279,7 +2276,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
           headers: toWireStringMap(opts?.headers),
           trace_id: opts?.traceId ?? tc?.traceId ?? "",
           parent_span_id: opts?.parentSpanId ?? tc?.spanId ?? "",
-          producer_service: service,
+          producer_service: defaultConsumerPrefix,
           idempotency_key: opts?.idempotencyKey ?? ""
         }, meta, unaryDeadlineOptions(), (err, res) => err ? reject(normalizeServiceError(err, `publish:${topic}`)) : resolve(res?.message_id ?? ""));
       });
@@ -2320,9 +2317,9 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
     },
     handleEvent(pattern, handler, opts) {
       const normalizedOpts = opts ?? {};
-      const groupName = normalizedOpts.groupName || `${defaultConsumerPrefix}.${pattern}`;
+      const groupName = `${defaultConsumerPrefix}.${pattern}`;
       if (eventHandlers.has(groupName)) {
-        throw new Error(`Duplicate event consumer group "${groupName}". ` + "Use a distinct groupName for each handleEvent() registration.");
+        throw new Error(`Duplicate event consumer group "${groupName}". ` + "Use handleEvent() with a unique topic pattern per handler.");
       }
       eventHandlers.set(groupName, {
         groupName,
@@ -2474,8 +2471,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       return new Promise((resolve, reject) => {
         stub.ExecuteWorkflow({
           workflow_name: name,
-          input: payload,
-          service_name: service
+          input: payload
         }, meta, unaryDeadlineOptions(), (err, res) => {
           if (err) {
             reject(normalizeServiceError(err, "execute-workflow"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "service-bridge",
-  "version": "1.8.1-dev.36",
+  "version": "1.8.2-dev.39",
   "type": "module",
   "description": "ServiceBridge SDK for Node.js — one self-hosted runtime for RPC, events, workflows, and jobs without a service mesh or sidecars. Direct gRPC between workers; durable events, jobs, tracing, auto mTLS. One Go runtime + PostgreSQL.",
   "keywords": [