@forwardimpact/librpc 0.1.110 → 0.1.112

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,30 +23,30 @@ 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 trace service configuration cannot be loaded
+ * @throws {Error} If the factory cannot load the span service configuration
  */
 export async function createTracer(serviceName) {
-  const traceConfig = await createServiceConfig("trace");
-  const { TraceClient } = clients;
-  // createTracer is a composition-root factory; it builds the production
-  // runtime as its DI root, threads it into the TraceClient (so the client's
-  // auth reads SERVICE_SECRET off the bag) and into the Tracer (and thus every
-  // Span) via its clock.
+  const spanConfig = await createServiceConfig("span");
+  const { SpanClient } = clients;
+  // 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 traceClient = new TraceClient(traceConfig, runtime);
+  const spanClient = new SpanClient(spanConfig, runtime);
   return new Tracer({
     serviceName,
-    traceClient,
+    spanClient,
     grpcMetadata: grpc.Metadata,
     clock: runtime.clock,
   });
 }
 
 /**
- * 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();
       }

package/src/generated/definitions/trace.js

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