@forwardimpact/librpc 0.1.110 → 0.1.112

package/README.md

@@ -13,11 +13,24 @@ transport.
 import { Server, Client, createClient, createTracer } from '@forwardimpact/librpc';
 ```
 
+## Unary deadlines
+
+Every unary call carries one absolute gRPC deadline. The deadline spans
+all retry attempts. The default is 60s. That default matches the slowest
+unary in practice (embedding model inference). A hung connection fails
+with `DEADLINE_EXCEEDED`. Retryable errors (UNAVAILABLE and friends)
+cycle only until the call spends its budget. The first attempt past the
+deadline fails immediately. `DEADLINE_EXCEEDED` gets no retry. Override
+the deadline per service with the `deadline` config key (milliseconds)
+in the service's config block. Once the key exists there, the
+`SERVICE_{NAME}_DEADLINE` env var overrides it. Streaming calls are
+exempt. Keepalive bounds them, and long-lived streams are legitimate.
+
 ## Documentation
 
 - [Ship a Service Endpoint](https://www.forwardimpact.team/docs/libraries/typed-contracts/ship-endpoint/index.md)
   — ship and consume a gRPC service with typed contracts, authentication,
-  retries, and health checks; `fit-unary` is the command-line client for it.
+  retries, and health checks. `fit-unary` is the command-line client for it.
 - [Keep Types Synced with Proto Definitions](https://www.forwardimpact.team/docs/libraries/typed-contracts/index.md)
-  — the full workflow for defining proto contracts and generating typed base
+  — the full workflow to define proto contracts and generate typed base
   classes and clients.

package/bin/fit-unary.js

@@ -23,13 +23,13 @@ const definition = {
       title: "Ship a Service Endpoint",
       url: "https://www.forwardimpact.team/docs/libraries/typed-contracts/ship-endpoint/index.md",
       description:
-        "Ship and consume a gRPC service with typed contracts, authentication, retries, and health checks; fit-unary is the command-line client for it.",
+        "Ship and consume a gRPC service with typed contracts, authentication, retries, and health checks. fit-unary is the command-line client for it.",
     },
     {
       title: "Keep Types Synced with Proto Definitions",
       url: "https://www.forwardimpact.team/docs/libraries/typed-contracts/index.md",
       description:
-        "The full workflow for defining proto contracts and generating typed base classes and clients.",
+        "The full workflow to define proto contracts and generate typed base classes and clients.",
     },
   ],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/librpc",
-  "version": "0.1.110",
+  "version": "0.1.112",
   "description": "gRPC server and client framework — ship service endpoints without reimplementing transport.",
   "keywords": [
     "grpc",

package/src/auth.js

@@ -12,7 +12,7 @@ export class HmacAuth {
 
   /**
    * Creates a new HMAC authenticator instance
-   * @param {string} secret - Shared secret key for HMAC generation (minimum 32 characters)
+   * @param {string} secret - Shared secret key to generate the HMAC (minimum 32 characters)
    * @param {number} tokenLifetimeSeconds - Token lifetime in seconds (default: 60)
    * @param {object} [options] - Optional collaborators
    * @param {() => number} [options.now] - Injectable clock (default: Date.now)
@@ -36,7 +36,7 @@ export class HmacAuth {
 
   /**
    * Generates an HMAC token for the specified service
-   * @param {string} serviceId - Identifier of the service requesting authentication
+   * @param {string} serviceId - Identifier of the service that requests authentication
    * @returns {string} Base64 encoded HMAC token
    * @throws {Error} When serviceId is invalid
    */
@@ -59,7 +59,7 @@ export class HmacAuth {
   /**
    * Verifies an HMAC token and extracts service information
    * @param {string} token - Base64 encoded HMAC token to verify
-   * @returns {object} Verification result containing serviceId and isValid
+   * @returns {object} Verification result with serviceId and isValid
    * @throws {Error} When token format is invalid
    */
   verifyToken(token) {
@@ -95,7 +95,7 @@ export class HmacAuth {
         };
       }
 
-      // Check token expiration
+      // Check whether the token expired
       const now = this.#now();
       if (now - timestamp > this.#tokenLifetimeMs) {
         return {
@@ -152,7 +152,8 @@ export class HmacAuth {
 
 /**
  * gRPC interceptor for HMAC-based service authentication
- * Handles automatic token attachment for outgoing requests and validation for incoming requests
+ * Adds a token to each outgoing request automatically and validates each
+ * incoming request
  */
 export class Interceptor {
   #authenticator;
@@ -232,14 +233,14 @@ export class Interceptor {
         };
       }
 
-      // Add service ID to call context for potential use by handlers
+      // Add the service ID to the call context so handlers can use it
       call.serviceId = verification.serviceId;
     };
   }
 
   /**
    * Validates an incoming gRPC call's authentication
-   * This is a helper method for manual authentication validation
+   * This helper method validates the authentication manually
    * @param {object} call - gRPC call object
    * @returns {object} Verification result with isValid, serviceId, and error properties
    */

package/src/base.js

@@ -6,7 +6,7 @@ import { Interceptor, HmacAuth } from "./auth.js";
 import { definitions } from "./generated/definitions/exports.js";
 
 /**
- * Capitalize first letter of a string
+ * Capitalize the first letter of a string
  * @param {string} str - String to capitalize
  * @returns {string} Capitalized string
  */
@@ -16,18 +16,18 @@ export function capitalizeFirstLetter(str) {
 
 /**
  * Default grpc factory that creates gRPC dependencies
- * @returns {object} Object containing grpc
+ * @returns {object} Object with grpc
  */
 export function createGrpc() {
   return { grpc };
 }
 
 /**
- * Default auth factory that creates an authentication interceptor. Reads
- * `SERVICE_SECRET` from the injected `runtime.proc.env` rather than
- * constructing its own process collaborator — the runtime is threaded from the
- * entry point through `Server`/`Client` (no leaf-collaborator construction in
- * src, Success Criterion 9).
+ * Default auth factory that creates an authentication interceptor. It reads
+ * `SERVICE_SECRET` from the injected `runtime.proc.env`. It does not construct
+ * its own process collaborator. The entry point threads the runtime through
+ * `Server`/`Client` (no leaf-collaborator construction in src, Success
+ * Criterion 9).
  * @param {string} serviceName - Name of the service for the interceptor
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime - Injected runtime bag
  * @returns {Interceptor} Configured interceptor instance
@@ -91,8 +91,8 @@ export class Rpc {
     const { grpc } = grpcFn();
     this.#grpc = grpc;
 
-    // Setup authentication (the default factory reads SERVICE_SECRET off the
-    // injected runtime; a mock authFn ignores it)
+    // Set up authentication. The default factory reads SERVICE_SECRET off the
+    // injected runtime. A mock authFn ignores it.
     this.#auth = authFn(this.config.name, runtime);
 
     // Create observer with logger and tracer
@@ -124,7 +124,7 @@ export class Rpc {
   tracer = () => this.#observer.tracer();
 
   /**
-   * Get pre-compiled service definition
+   * Get the pre-compiled service definition
    * @param {string} serviceName - Service name (e.g., "Agent", "Vector")
    * @returns {object} Pre-compiled service definition
    */

package/src/client.js

@@ -9,12 +9,22 @@ import {
   capitalizeFirstLetter,
 } from "./base.js";
 
+// No unary call waits forever. Every call carries one absolute gRPC
+// deadline that spans all retry attempts. So a hung connection fails with
+// DEADLINE_EXCEEDED, and so does a retryable-error grind (exponential
+// backoff on UNAVAILABLE). Neither one blocks the caller forever. The
+// default fits the slowest unary in practice (embedding model inference).
+// Override it per service with the `deadline` config key.
+const DEFAULT_UNARY_DEADLINE_MS = 60_000;
+
 /**
- * Creates a gRPC client with consistent API using pre-compiled definitions
+ * Creates a gRPC client with a consistent API from pre-compiled definitions
  */
 export class Client extends Rpc {
   #client;
   #retry;
+  #clock;
+  #deadlineMs;
 
   /**
    * Creates a new Client instance
@@ -25,7 +35,7 @@ export class Client extends Rpc {
    * @param {(serviceName: string, logger: object, tracer: object) => object} observerFn - Observer factory
    * @param {() => {grpc: object}} grpcFn - gRPC factory
    * @param {(serviceName: string, runtime: object) => object} authFn - Auth factory
-   * @param {import("@forwardimpact/libutil").Retry} [retry] - Optional retry instance for handling transient errors
+   * @param {import("@forwardimpact/libutil").Retry} [retry] - Optional retry instance that handles transient errors
    */
   constructor(
     config,
@@ -39,18 +49,20 @@ export class Client extends Rpc {
   ) {
     super(config, runtime, logger, tracer, observerFn, grpcFn, authFn);
     this.#retry = retry || createRetry({ retries: 10, delay: 1000 });
+    this.#clock = runtime.clock;
+    this.#deadlineMs = Number(config.deadline) || DEFAULT_UNARY_DEADLINE_MS;
     this.#setupClient();
   }
 
   /**
-   * Sets up the gRPC client using pre-compiled definition
+   * Sets up the gRPC client from the pre-compiled definition
    * @private
    */
   #setupClient() {
     const serviceName = capitalizeFirstLetter(this.config.name);
     const serviceDefinition = this.getServiceDefinition(serviceName);
 
-    // In case default host is used, resort to a well-known service name
+    // If the config uses the default host, resort to a well-known service name
     const host =
       this.config.host === "0.0.0.0"
         ? `${this.config.name}.guide.local`
@@ -61,7 +73,7 @@ export class Client extends Rpc {
       interceptors: [this.auth().createClientInterceptor()],
     };
 
-    // Configure client with keepalive for long-running streams
+    // Configure the client with keepalive for long-running streams
     // https://github.com/grpc/grpc-node/blob/master/doc/keepalive.md
     const channelOptions = {
       "grpc.keepalive_time_ms": 30000, // Send keepalive ping every 30 seconds
@@ -72,7 +84,7 @@ export class Client extends Rpc {
     };
     const clientCredentials = this.grpc().credentials.createInsecure();
 
-    // Create client using pre-compiled service definition
+    // Create the client from the pre-compiled service definition
     const ClientConstructor = this.grpc().makeGenericClientConstructor(
       serviceDefinition,
       serviceName,
@@ -81,6 +93,15 @@ export class Client extends Rpc {
     this.#client = new ClientConstructor(uri, clientCredentials, options);
   }
 
+  /**
+   * Close the underlying gRPC channel. This releases its sockets and timers
+   * so short-lived processes (CLIs, tests) can exit promptly.
+   * @returns {void}
+   */
+  close() {
+    this.#client.close();
+  }
+
   /**
    * Call a gRPC method with automatic CLIENT span tracing and observability.
    * Supports unary calls.
@@ -199,7 +220,12 @@ export class Client extends Rpc {
   }
 
   /**
-   * Internal unary call handler with retry logic
+   * Internal unary call handler with retry logic. The handler computes the
+   * absolute deadline once and shares it with every retry attempt. So
+   * retryable errors repeat only until the call spends its budget. The
+   * first attempt past the deadline fails at once with DEADLINE_EXCEEDED,
+   * which is deliberately not retryable. Streaming calls are exempt.
+   * Keepalive bounds them, and long-lived streams are legitimate.
    * @param {string} methodName - The name of the method
    * @param {object} request - Request object
    * @param {object} metadata - gRPC Metadata instance
@@ -207,15 +233,21 @@ export class Client extends Rpc {
    * @private
    */
   async #performUnaryCall(methodName, request, metadata) {
+    const options = { deadline: this.#clock.now() + this.#deadlineMs };
     return await this.#retry.execute(() => {
       return new Promise((resolve, reject) => {
-        this.#client[methodName](request, metadata, (error, response) => {
-          if (error) {
-            reject(error);
-          } else {
-            resolve(response);
-          }
-        });
+        this.#client[methodName](
+          request,
+          metadata,
+          options,
+          (error, response) => {
+            if (error) {
+              reject(error);
+            } else {
+              resolve(response);
+            }
+          },
+        );
       });
     });
   }

package/src/generated/definitions/exports.js

@@ -9,8 +9,8 @@ export { GhuserServiceDefinition } from "./ghuser.js";
 export { GraphServiceDefinition } from "./graph.js";
 export { MapServiceDefinition } from "./map.js";
 export { PathwayServiceDefinition } from "./pathway.js";
+export { SpanServiceDefinition } from "./span.js";
 export { TenancyServiceDefinition } from "./tenancy.js";
-export { TraceServiceDefinition } from "./trace.js";
 export { VectorServiceDefinition } from "./vector.js";
 
 // Import service definitions to make them available for aggregation
@@ -21,8 +21,8 @@ import { GhuserServiceDefinition } from "./ghuser.js";
 import { GraphServiceDefinition } from "./graph.js";
 import { MapServiceDefinition } from "./map.js";
 import { PathwayServiceDefinition } from "./pathway.js";
+import { SpanServiceDefinition } from "./span.js";
 import { TenancyServiceDefinition } from "./tenancy.js";
-import { TraceServiceDefinition } from "./trace.js";
 import { VectorServiceDefinition } from "./vector.js";
 
 // Aggregate exports for convenience
@@ -34,8 +34,8 @@ export const definitions = {
   graph: GraphServiceDefinition,
   map: MapServiceDefinition,
   pathway: PathwayServiceDefinition,
+  span: SpanServiceDefinition,
   tenancy: TenancyServiceDefinition,
-  trace: TraceServiceDefinition,
   vector: VectorServiceDefinition,
 };
 

package/src/generated/definitions/span.js

@@ -0,0 +1,50 @@
+import { span } from "@forwardimpact/libtype";
+
+/**
+ * Pre-compiled gRPC service definition for Span
+ * Generated at build time
+ */
+export const SpanServiceDefinition = {
+  RecordSpan: {
+    path: '/span.Span/RecordSpan',
+    requestStream: false,
+    responseStream: false,
+    requestSerialize: (value) => {
+      return Buffer.from(span.SpanItem.encode(value).finish());
+    },
+    requestDeserialize: (value) => {
+      return span.SpanItem.toObject(
+        span.SpanItem.decode(value)
+      );
+    },
+    responseSerialize: (value) => {
+      return Buffer.from(span.RecordResponse.encode(value).finish());
+    },
+    responseDeserialize: (value) => {
+      return span.RecordResponse.toObject(
+        span.RecordResponse.decode(value)
+      );
+    },
+  },
+  QuerySpans: {
+    path: '/span.Span/QuerySpans',
+    requestStream: false,
+    responseStream: false,
+    requestSerialize: (value) => {
+      return Buffer.from(span.QueryRequest.encode(value).finish());
+    },
+    requestDeserialize: (value) => {
+      return span.QueryRequest.toObject(
+        span.QueryRequest.decode(value)
+      );
+    },
+    responseSerialize: (value) => {
+      return Buffer.from(span.QueryResponse.encode(value).finish());
+    },
+    responseDeserialize: (value) => {
+      return span.QueryResponse.toObject(
+        span.QueryResponse.decode(value)
+      );
+    },
+  },
+};

package/src/generated/services/exports.js

@@ -9,8 +9,8 @@ export { GhuserBase } from "./ghuser/service.js";
 export { GraphBase } from "./graph/service.js";
 export { MapBase } from "./map/service.js";
 export { PathwayBase } from "./pathway/service.js";
+export { SpanBase } from "./span/service.js";
 export { TenancyBase } from "./tenancy/service.js";
-export { TraceBase } from "./trace/service.js";
 export { VectorBase } from "./vector/service.js";
 
 // Client Classes
@@ -21,8 +21,8 @@ export { GhuserClient } from "./ghuser/client.js";
 export { GraphClient } from "./graph/client.js";
 export { MapClient } from "./map/client.js";
 export { PathwayClient } from "./pathway/client.js";
+export { SpanClient } from "./span/client.js";
 export { TenancyClient } from "./tenancy/client.js";
-export { TraceClient } from "./trace/client.js";
 export { VectorClient } from "./vector/client.js";
 
 // Import service base classes to make them available for aggregation
@@ -33,8 +33,8 @@ import { GhuserBase } from "./ghuser/service.js";
 import { GraphBase } from "./graph/service.js";
 import { MapBase } from "./map/service.js";
 import { PathwayBase } from "./pathway/service.js";
+import { SpanBase } from "./span/service.js";
 import { TenancyBase } from "./tenancy/service.js";
-import { TraceBase } from "./trace/service.js";
 import { VectorBase } from "./vector/service.js";
 
 // Import client classes to make them available for aggregation
@@ -45,8 +45,8 @@ import { GhuserClient } from "./ghuser/client.js";
 import { GraphClient } from "./graph/client.js";
 import { MapClient } from "./map/client.js";
 import { PathwayClient } from "./pathway/client.js";
+import { SpanClient } from "./span/client.js";
 import { TenancyClient } from "./tenancy/client.js";
-import { TraceClient } from "./trace/client.js";
 import { VectorClient } from "./vector/client.js";
 
 // Aggregate exports for convenience
@@ -58,8 +58,8 @@ export const services = {
   GraphBase,
   MapBase,
   PathwayBase,
+  SpanBase,
   TenancyBase,
-  TraceBase,
   VectorBase,
 };
 
@@ -71,8 +71,8 @@ export const clients = {
   GraphClient,
   MapClient,
   PathwayClient,
+  SpanClient,
   TenancyClient,
-  TraceClient,
   VectorClient,
 };
 
@@ -87,8 +87,8 @@ export default {
   GraphBase,
   MapBase,
   PathwayBase,
+  SpanBase,
   TenancyBase,
-  TraceBase,
   VectorBase,
   BridgeClient,
   EmbeddingClient,
@@ -97,7 +97,7 @@ export default {
   GraphClient,
   MapClient,
   PathwayClient,
+  SpanClient,
   TenancyClient,
-  TraceClient,
   VectorClient,
 };

package/src/generated/services/{trace → span}/client.js

@@ -3,15 +3,15 @@
 import { Client } from "@forwardimpact/librpc/client.js";
 import { createAuth, createGrpc } from "@forwardimpact/librpc/base.js";
 import { createObserver } from "@forwardimpact/libtelemetry";
-import { trace } from "@forwardimpact/libtype";
+import { span } from "@forwardimpact/libtype";
 
 /**
- * Typed client for the Trace gRPC service.
+ * Typed client for the Span gRPC service.
  * Extends the `Client` class for shared gRPC client functionality.
  */
-export class TraceClient extends Client {
+export class SpanClient extends Client {
   /**
-   * Creates a new Trace client instance
+   * Creates a new Span client instance
    * @param {object} config - Service configuration
    * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime - Injected runtime bag (required; the default auth factory reads SERVICE_SECRET from it)
    * @param {import("@forwardimpact/libtelemetry").Logger} [logger] - Optional logger instance
@@ -24,35 +24,35 @@ export class TraceClient extends Client {
 
   /**
    * Call the `RecordSpan` RPC with request/response type conversion.
-   * @param { trace.Span } req - Typed request message.
-   * @returns { Promise<trace.RecordResponse> } Typed response message.
+   * @param { span.SpanItem } req - Typed request message.
+   * @returns { Promise<span.RecordResponse> } Typed response message.
    */
   async RecordSpan(req) {
     // Accept a typed message or a plain init object (coerced to the typed type).
     const message =
-      req instanceof trace.Span
+      req instanceof span.SpanItem
         ? req
-        : new trace.Span(req);
-    const request = trace.Span.toObject(message);
+        : new span.SpanItem(req);
+    const request = span.SpanItem.toObject(message);
     
     // Make gRPC call (tracing handled by base Client class)
-    return this.callUnary("RecordSpan", request, (res) => trace.RecordResponse.fromObject(res));
+    return this.callUnary("RecordSpan", request, (res) => span.RecordResponse.fromObject(res));
   }
 
   /**
    * Call the `QuerySpans` RPC with request/response type conversion.
-   * @param { trace.QueryRequest } req - Typed request message.
-   * @returns { Promise<trace.QueryResponse> } Typed response message.
+   * @param { span.QueryRequest } req - Typed request message.
+   * @returns { Promise<span.QueryResponse> } Typed response message.
    */
   async QuerySpans(req) {
     // Accept a typed message or a plain init object (coerced to the typed type).
     const message =
-      req instanceof trace.QueryRequest
+      req instanceof span.QueryRequest
         ? req
-        : new trace.QueryRequest(req);
-    const request = trace.QueryRequest.toObject(message);
+        : new span.QueryRequest(req);
+    const request = span.QueryRequest.toObject(message);
     
     // Make gRPC call (tracing handled by base Client class)
-    return this.callUnary("QuerySpans", request, (res) => trace.QueryResponse.fromObject(res));
+    return this.callUnary("QuerySpans", request, (res) => span.QueryResponse.fromObject(res));
   }
 }

package/src/generated/services/{trace → span}/service.js

@@ -1,15 +1,15 @@
 /* eslint no-unused-vars: "off" */
 
-import { trace } from "@forwardimpact/libtype";
+import { span } from "@forwardimpact/libtype";
 
 /**
- * Base class for Trace service implementation
+ * Base class for Span service implementation
  */
-export class TraceBase {
+export class SpanBase {
   config;
 
   /**
-   * Creates a new Trace service instance
+   * Creates a new Span service instance
    * @param {object} config - Service configuration
    */
   constructor(config) {
@@ -19,8 +19,8 @@ export class TraceBase {
 
   /**
    * Must be implemented by subclass
-   * @param { trace.Span } req - Request parameters
-   * @returns { Promise<trace.RecordResponse> } Response object
+   * @param { span.SpanItem } req - Request parameters
+   * @returns { Promise<span.RecordResponse> } Response object
    */
   async RecordSpan(req) {
     throw new Error("RecordSpan not implemented");
@@ -28,8 +28,8 @@ export class TraceBase {
 
   /**
    * Must be implemented by subclass
-   * @param { trace.QueryRequest } req - Request parameters
-   * @returns { Promise<trace.QueryResponse> } Response object
+   * @param { span.QueryRequest } req - Request parameters
+   * @returns { Promise<span.QueryResponse> } Response object
    */
   async QuerySpans(req) {
     throw new Error("QuerySpans not implemented");
@@ -43,18 +43,18 @@ export class TraceBase {
     return {
       RecordSpan: async (call) => {
         // Validate and convert request
-        const error = trace.Span.verify(call.request);
+        const error = span.SpanItem.verify(call.request);
         if (error) throw new Error(`RecordSpan: ${error}`);
-        const req = trace.Span.fromObject(call.request);
+        const req = span.SpanItem.fromObject(call.request);
         
         // Call implementation
         return await this.RecordSpan(req);
       },
       QuerySpans: async (call) => {
         // Validate and convert request
-        const error = trace.QueryRequest.verify(call.request);
+        const error = span.QueryRequest.verify(call.request);
         if (error) throw new Error(`QuerySpans: ${error}`);
-        const req = trace.QueryRequest.fromObject(call.request);
+        const req = span.QueryRequest.fromObject(call.request);
         
         // Call implementation
         return await this.QuerySpans(req);