@forwardimpact/librpc 0.1.111 → 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.111",
+  "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/health.js

@@ -1,12 +1,12 @@
 /**
  * gRPC Health Check protocol (grpc.health.v1.Health/Check)
  *
- * Manual service definition — no .proto file or proto-loader needed.
- * Messages use raw protobuf wire encoding (trivial: one string field,
- * one enum/varint field).
+ * This is a manual service definition. It needs no .proto file and no
+ * proto-loader. Messages use raw protobuf wire encoding. The encoding is
+ * trivial: one string field and one enum/varint field.
  */
 
-/** Serving status enum matching grpc.health.v1 */
+/** Serving status enum that matches grpc.health.v1 */
 export const ServingStatus = {
   UNKNOWN: 0,
   SERVING: 1,

package/src/index.js

@@ -23,18 +23,18 @@ export const clients = exports.clients || {};
 
 /**
  * Creates a tracer instance for a service
- * This factory should be called at startup in server.js files or when creating clients
- * @param {string} serviceName - Name of the service being traced
+ * Call this factory at startup in server.js files or when you create clients
+ * @param {string} serviceName - Name of the service to trace
  * @returns {Promise<Tracer>} Configured tracer instance
- * @throws {Error} If span service configuration cannot be loaded
+ * @throws {Error} If the factory cannot load the span service configuration
  */
 export async function createTracer(serviceName) {
   const spanConfig = await createServiceConfig("span");
   const { SpanClient } = clients;
-  // createTracer is a composition-root factory; it builds the production
-  // runtime as its DI root, threads it into the SpanClient (so the client's
-  // auth reads SERVICE_SECRET off the bag) and into the Tracer (and thus every
-  // Span) via its clock.
+  // createTracer is a composition-root factory. It builds the production
+  // runtime as its DI root. It threads the runtime into the SpanClient, so the
+  // client's auth reads SERVICE_SECRET off the bag. It also threads the runtime
+  // clock into the Tracer, and so into every Span.
   const runtime = createDefaultRuntime();
   const spanClient = new SpanClient(spanConfig, runtime);
   return new Tracer({
@@ -46,7 +46,7 @@ export async function createTracer(serviceName) {
 }
 
 /**
- * Factory function to create a client instance with optional logging and tracing
+ * Factory function to create a client instance with an optional logger and tracer
  * @param {string} name - Service name (e.g., "memory", "llm", "tool")
  * @param {object} [logger] - Optional logger instance
  * @param {import("@forwardimpact/libtelemetry").Tracer} [tracer] - Optional tracer instance for distributed tracing
@@ -64,10 +64,10 @@ export async function createClient(name, logger = null, tracer = null) {
     );
   }
 
-  // Create config for the service
+  // Create the config for the service
   const config = await createServiceConfig(name);
 
-  // createClient is a composition-root factory; build the production runtime
+  // createClient is a composition-root factory. Build the production runtime
   // here and thread it so the client's auth reads SERVICE_SECRET off the bag.
   const runtime = createDefaultRuntime();
 

package/src/interceptor.js

@@ -2,7 +2,8 @@ import grpc from "@grpc/grpc-js";
 
 /**
  * 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;
@@ -82,14 +83,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/server.js

@@ -8,7 +8,7 @@ import {
 import { healthDefinition, createHealthHandlers } from "./health.js";
 
 /**
- * gRPC Server class using pre-compiled service definitions
+ * gRPC Server class that uses pre-compiled service definitions
  * Takes a service instance and creates a gRPC server around it
  */
 export class Server extends Rpc {
@@ -47,7 +47,7 @@ export class Server extends Rpc {
 
   /** Starts the gRPC server */
   async start() {
-    // Configure server with keepalive for long-running streams
+    // Configure the server with keepalive for long-running streams
     // https://github.com/grpc/grpc-node/blob/master/doc/keepalive.md
     this.#server = new (this.grpc().Server)({
       "grpc.keepalive_time_ms": 30000, // Send keepalive ping every 30 seconds
@@ -57,19 +57,19 @@ export class Server extends Rpc {
       "grpc.http2.max_pings_without_data": 0, // Unlimited pings without data
     });
 
-    // Get pre-compiled service definition
+    // Get the pre-compiled service definition
     const serviceName = capitalizeFirstLetter(this.config.name);
     const definition = this.getServiceDefinition(serviceName);
 
-    // Get handlers from the service instance
+    // Get the handlers from the service instance
     const handlers = this.#service.getHandlers();
 
-    // Wrap handlers with auth/error handling
+    // Wrap the handlers so they authenticate and handle errors
     const wrappedHandlers = this.#wrapHandlers(handlers, definition);
 
     this.#server.addService(definition, wrappedHandlers);
 
-    // Register standard gRPC health check (no auth, no observer wrapping)
+    // Register the standard gRPC health check (no auth, no observer wrap)
     this.#server.addService(
       healthDefinition,
       createHealthHandlers(serviceName),
@@ -82,7 +82,7 @@ export class Server extends Rpc {
   }
 
   /**
-   * Wraps handlers with auth and error handling
+   * Wraps the handlers so they authenticate and handle errors
    * @param {object} handlers - Service method handlers
    * @param {object} definition - Service definition
    * @returns {object} Wrapped handlers
@@ -101,7 +101,8 @@ export class Server extends Rpc {
   }
 
   /**
-   * Wraps a streaming handler with tracing, authentication, and error handling via Observer
+   * Wraps a streaming handler with tracing, authentication, and error
+   * handling through Observer
    * @param {string} methodName - Method name for tracing
    * @param {Function} handler - Streaming handler function
    * @returns {Function} Wrapped handler
@@ -142,7 +143,8 @@ export class Server extends Rpc {
   }
 
   /**
-   * Wraps a unary handler with tracing, authentication, and error handling via Observer
+   * Wraps a unary handler with tracing, authentication, and error handling
+   * through Observer
    * @param {string} methodName - Method name for tracing
    * @param {Function} handler - Unary handler function
    * @returns {Function} Wrapped handler
@@ -185,7 +187,7 @@ export class Server extends Rpc {
   }
 
   /**
-   * Binds server to the specified URI
+   * Binds the server to the specified URI
    * @param {string} uri - Server URI to bind to
    * @returns {Promise<number>} Bound port number
    */
@@ -213,7 +215,7 @@ export class Server extends Rpc {
     const shutdown = async () => {
       this.observer().logger()?.info("Server", "Shutting down...");
 
-      // Call service shutdown if it exists
+      // Call the service shutdown if it exists
       if (typeof this.#service.shutdown === "function") {
         await this.#service.shutdown();
       }