@forwardimpact/librpc 0.1.77

package/client.js

@@ -0,0 +1,220 @@
+import { PassThrough } from "stream";
+import { createRetry } from "@forwardimpact/libutil";
+
+import {
+  Rpc,
+  createGrpc,
+  createAuth,
+  createObserver,
+  capitalizeFirstLetter,
+} from "./base.js";
+
+/**
+ * Creates a gRPC client with consistent API using pre-compiled definitions
+ */
+export class Client extends Rpc {
+  #client;
+  #retry;
+
+  /**
+   * Creates a new Client instance
+   * @param {object} config - Configuration object
+   * @param {object} [logger] - Optional logger instance
+   * @param {import("@forwardimpact/libtelemetry").Tracer} [tracer] - Optional tracer for distributed tracing
+   * @param {(serviceName: string, logger: object, tracer: object) => object} observerFn - Observer factory
+   * @param {() => {grpc: object}} grpcFn - gRPC factory
+   * @param {(serviceName: string) => object} authFn - Auth factory
+   * @param {import("@forwardimpact/libutil").Retry} [retry] - Optional retry instance for handling transient errors
+   */
+  constructor(
+    config,
+    logger = null,
+    tracer = null,
+    observerFn = createObserver,
+    grpcFn = createGrpc,
+    authFn = createAuth,
+    retry = null,
+  ) {
+    super(config, logger, tracer, observerFn, grpcFn, authFn);
+    this.#retry = retry || createRetry({ retries: 10, delay: 1000 });
+    this.#setupClient();
+  }
+
+  /**
+   * Sets up the gRPC client using 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
+    const host =
+      this.config.host === "0.0.0.0"
+        ? `${this.config.name}.guide.local`
+        : this.config.host;
+
+    const uri = `${host}:${this.config.port}`;
+    const options = {
+      interceptors: [this.auth().createClientInterceptor()],
+    };
+
+    // Configure 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
+      "grpc.keepalive_timeout_ms": 10000, // Wait 10 seconds for ping ack
+      "grpc.keepalive_permit_without_calls": 1, // Allow keepalive without active calls
+      "grpc.http2.min_time_between_pings_ms": 10000, // Minimum 10s between pings
+      "grpc.http2.max_pings_without_data": 0, // Unlimited pings without data
+    };
+    const clientCredentials = this.grpc().credentials.createInsecure();
+
+    // Create client using pre-compiled service definition
+    const ClientConstructor = this.grpc().makeGenericClientConstructor(
+      serviceDefinition,
+      serviceName,
+      channelOptions,
+    );
+    this.#client = new ClientConstructor(uri, clientCredentials, options);
+  }
+
+  /**
+   * Call a gRPC method with automatic CLIENT span tracing and observability.
+   * Supports unary calls.
+   * @param {string} methodName - The name of the gRPC method to call
+   * @param {object} request - The request object to send
+   * @param {Function} [mapper] - Optional mapper function to transform response
+   * @returns {Promise<object>} The response from the gRPC call
+   */
+  callUnary(methodName, request, mapper = null) {
+    if (!this.#client[methodName]) {
+      throw new Error(`Method ${methodName} not found on gRPC client`);
+    }
+
+    return this.observer()
+      .observeClientUnaryCall(methodName, request, async (metadata) => {
+        const m = metadata || new (this.grpc().Metadata)();
+        return await this.#performUnaryCall(methodName, request, m);
+      })
+      .then((response) => (mapper ? mapper(response) : response));
+  }
+
+  /**
+   * Call a gRPC method with automatic CLIENT span tracing and observability.
+   * Supports streaming calls.
+   * @param {string} methodName - The name of the gRPC method to call
+   * @param {object} request - The request object to send
+   * @param {Function} [mapper] - Optional mapper function to transform chunks
+   * @returns {object} The stream from the gRPC call
+   */
+  callStream(methodName, request, mapper = null) {
+    if (!this.#client[methodName]) {
+      throw new Error(`Method ${methodName} not found on gRPC client`);
+    }
+
+    const stream = this.observer().observeClientStreamingCall(
+      methodName,
+      request,
+      (metadata) => {
+        const m = metadata || new (this.grpc().Metadata)();
+        return this.#performStreamCall(methodName, request, m);
+      },
+    );
+
+    if (mapper) {
+      const mappedStream = new PassThrough({
+        objectMode: true,
+        transform(chunk, encoding, callback) {
+          try {
+            callback(null, mapper(chunk));
+          } catch (err) {
+            callback(err);
+          }
+        },
+      });
+
+      stream.on("error", (err) => mappedStream.emit("error", err));
+      stream.pipe(mappedStream);
+      return mappedStream;
+    }
+
+    return stream;
+  }
+
+  /**
+   * Internal streaming call handler
+   * @param {string} methodName - The name of the method
+   * @param {object} request - Request object
+   * @param {object} metadata - gRPC Metadata instance
+   * @returns {object} The gRPC stream
+   * @private
+   */
+  #performStreamCall(methodName, request, metadata) {
+    const outputStream = new PassThrough({ objectMode: true });
+
+    this.#retry
+      .execute(() => {
+        return new Promise((resolve, reject) => {
+          const stream = this.#client[methodName](request, metadata);
+          let isConnected = false;
+
+          const onSuccess = () => {
+            if (!isConnected) {
+              isConnected = true;
+              resolve();
+            }
+          };
+
+          stream.on("metadata", (meta) => {
+            outputStream.emit("metadata", meta);
+          });
+
+          stream.on("data", (chunk) => {
+            onSuccess();
+            outputStream.write(chunk);
+          });
+
+          stream.on("error", (err) => {
+            if (!isConnected) {
+              reject(err);
+            } else {
+              outputStream.emit("error", err);
+            }
+          });
+
+          stream.on("end", () => {
+            onSuccess();
+            outputStream.end();
+          });
+        });
+      })
+      .catch((err) => {
+        outputStream.emit("error", err);
+      });
+
+    return outputStream;
+  }
+
+  /**
+   * Internal unary call handler with retry logic
+   * @param {string} methodName - The name of the method
+   * @param {object} request - Request object
+   * @param {object} metadata - gRPC Metadata instance
+   * @returns {Promise<object>} Response object
+   * @private
+   */
+  async #performUnaryCall(methodName, request, metadata) {
+    return await this.#retry.execute(() => {
+      return new Promise((resolve, reject) => {
+        this.#client[methodName](request, metadata, (error, response) => {
+          if (error) {
+            reject(error);
+          } else {
+            resolve(response);
+          }
+        });
+      });
+    });
+  }
+}

package/index.js

@@ -0,0 +1,60 @@
+import grpc from "@grpc/grpc-js";
+
+import { createServiceConfig } from "@forwardimpact/libconfig";
+import { Tracer } from "@forwardimpact/libtelemetry/tracer.js";
+
+import { capitalizeFirstLetter } from "./base.js";
+import * as exports from "./generated/services/exports.js";
+
+export { createGrpc, createAuth, Rpc } from "./base.js";
+export { Client } from "./client.js";
+export { Interceptor, HmacAuth } from "./auth.js";
+export { Server } from "./server.js";
+
+// Export services and clients objects for runtime access
+export const services = exports.services || {};
+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
+ * @returns {Promise<Tracer>} Configured tracer instance
+ * @throws {Error} If trace service configuration cannot be loaded
+ */
+export async function createTracer(serviceName) {
+  const traceConfig = await createServiceConfig("trace");
+  const { TraceClient } = clients;
+  const traceClient = new TraceClient(traceConfig);
+  return new Tracer({
+    serviceName,
+    traceClient,
+    grpcMetadata: grpc.Metadata,
+  });
+}
+
+/**
+ * Factory function to create a client instance with optional logging and tracing
+ * @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
+ * @returns {Promise<object>} Initialized client instance
+ */
+export async function createClient(name, logger = null, tracer = null) {
+  // Build the client class name (e.g., "memory" -> "MemoryClient")
+  const className = capitalizeFirstLetter(name) + "Client";
+
+  // Get the client class from exports
+  const ClientClass = clients[className];
+  if (!ClientClass) {
+    throw new Error(
+      `Client ${className} not found. Available clients: ${Object.keys(clients).join(", ")}`,
+    );
+  }
+
+  // Create config for the service
+  const config = await createServiceConfig(name);
+
+  // Create and return the client instance with logger and tracer
+  return new ClientClass(config, logger, tracer);
+}

package/interceptor.js

@@ -0,0 +1,130 @@
+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
+ */
+export class Interceptor {
+  #authenticator;
+  #serviceId;
+
+  /**
+   * Creates a new authentication interceptor
+   * @param {import('./auth.js').HmacAuth} authenticator - HMAC authenticator instance
+   * @param {string} serviceId - Identifier of the current service
+   * @throws {Error} When parameters are invalid
+   */
+  constructor(authenticator, serviceId) {
+    if (!authenticator) {
+      throw new Error("Authenticator is required");
+    }
+    if (!serviceId || typeof serviceId !== "string") {
+      throw new Error("Service ID must be a non-empty string");
+    }
+
+    this.#authenticator = authenticator;
+    this.#serviceId = serviceId;
+  }
+
+  /**
+   * Creates a client interceptor that adds authentication tokens to outgoing requests
+   * @returns {Function} gRPC client interceptor function
+   */
+  createClientInterceptor() {
+    return (options, nextCall) => {
+      return new grpc.InterceptingCall(nextCall(options), {
+        start: (metadata, listener, next) => {
+          // Generate and add auth token to metadata
+          try {
+            const token = this.#authenticator.generateToken(this.#serviceId);
+            metadata.set("authorization", `Bearer ${token}`);
+          } catch (error) {
+            console.error("Failed to generate auth token:", error);
+          }
+          next(metadata, listener);
+        },
+      });
+    };
+  }
+
+  /**
+   * Creates a server interceptor that validates authentication tokens from incoming requests
+   * @returns {Function} gRPC server interceptor function
+   */
+  createServerInterceptor() {
+    return (call, metadata) => {
+      // Extract and verify auth token from metadata
+      const authHeader = metadata.get("authorization")[0];
+
+      if (!authHeader) {
+        throw {
+          code: grpc.status.UNAUTHENTICATED,
+          message: "Missing authentication token",
+        };
+      }
+
+      // Extract token from "Bearer <token>" format
+      const tokenMatch = authHeader.match(/^Bearer\s+(.+)$/);
+      if (!tokenMatch) {
+        throw {
+          code: grpc.status.UNAUTHENTICATED,
+          message: "Invalid authentication header format",
+        };
+      }
+
+      const token = tokenMatch[1];
+      const verification = this.#authenticator.verifyToken(token);
+
+      if (!verification.isValid) {
+        throw {
+          code: grpc.status.UNAUTHENTICATED,
+          message: `Authentication failed: ${verification.error}`,
+        };
+      }
+
+      // Add service ID to call context for potential use by handlers
+      call.serviceId = verification.serviceId;
+    };
+  }
+
+  /**
+   * Validates an incoming gRPC call's authentication
+   * This is a helper method for manual authentication validation
+   * @param {object} call - gRPC call object
+   * @returns {object} Verification result with isValid, serviceId, and error properties
+   */
+  validateCall(call) {
+    try {
+      const metadata = call.metadata;
+      const authHeaders = metadata.get("authorization");
+
+      if (!authHeaders || authHeaders.length === 0) {
+        return {
+          isValid: false,
+          serviceId: null,
+          error: "Missing authentication token",
+        };
+      }
+
+      const authHeader = authHeaders[0];
+      const tokenMatch = authHeader.match(/^Bearer\s+(.+)$/);
+
+      if (!tokenMatch) {
+        return {
+          isValid: false,
+          serviceId: null,
+          error: "Invalid authentication header format",
+        };
+      }
+
+      const token = tokenMatch[1];
+      return this.#authenticator.verifyToken(token);
+    } catch (error) {
+      return {
+        isValid: false,
+        serviceId: null,
+        error: `Authentication validation failed: ${error.message}`,
+      };
+    }
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@forwardimpact/librpc",
+  "version": "0.1.77",
+  "description": "gRPC framework and utilities for Guide",
+  "license": "Apache-2.0",
+  "author": "D. Olsson <hi@senzilla.io>",
+  "type": "module",
+  "main": "index.js",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@forwardimpact/libconfig": "^0.1.58",
+    "@forwardimpact/libtelemetry": "^0.1.22",
+    "@forwardimpact/libutil": "^0.1.60",
+    "@grpc/grpc-js": "^1.14.3"
+  },
+  "devDependencies": {
+    "@forwardimpact/libharness": "^0.1.5"
+  }
+}

package/server.js

@@ -0,0 +1,212 @@
+import {
+  Rpc,
+  createGrpc,
+  createAuth,
+  createObserver,
+  capitalizeFirstLetter,
+} from "./base.js";
+
+/**
+ * gRPC Server class using pre-compiled service definitions
+ * Takes a service instance and creates a gRPC server around it
+ */
+export class Server extends Rpc {
+  #server;
+  #service;
+
+  /**
+   * Creates a gRPC server for a service
+   * @param {object} service - Service instance with business logic
+   * @param {object} config - Server configuration
+   * @param {object} [logger] - Optional logger instance
+   * @param {import("@forwardimpact/libtelemetry").Tracer} [tracer] - Optional tracer for distributed tracing
+   * @param {(serviceName: string, logger: object, tracer: object) => object} observerFn - Observer factory
+   * @param {() => {grpc: object}} grpcFn - gRPC factory
+   * @param {(serviceName: string) => object} authFn - Auth factory
+   */
+  constructor(
+    service,
+    config,
+    logger = null,
+    tracer = null,
+    observerFn = createObserver,
+    grpcFn = createGrpc,
+    authFn = createAuth,
+  ) {
+    if (!service) throw new Error("service is required");
+
+    super(config, logger, tracer, observerFn, grpcFn, authFn);
+    this.#service = service;
+  }
+
+  /** Starts the gRPC server */
+  async start() {
+    // Configure 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
+      "grpc.keepalive_timeout_ms": 10000, // Wait 10 seconds for ping ack
+      "grpc.keepalive_permit_without_calls": 1, // Allow keepalive without active calls
+      "grpc.http2.min_time_between_pings_ms": 10000, // Minimum 10s between pings
+      "grpc.http2.max_pings_without_data": 0, // Unlimited pings without data
+    });
+
+    // Get pre-compiled service definition
+    const serviceName = capitalizeFirstLetter(this.config.name);
+    const definition = this.getServiceDefinition(serviceName);
+
+    // Get handlers from the service instance
+    const handlers = this.#service.getHandlers();
+
+    // Wrap handlers with auth/error handling
+    const wrappedHandlers = this.#wrapHandlers(handlers, definition);
+
+    this.#server.addService(definition, wrappedHandlers);
+
+    const uri = `${this.config.host}:${this.config.port}`;
+    await this.#bindServer(uri);
+
+    this.#setupShutdown();
+  }
+
+  /**
+   * Wraps handlers with auth and error handling
+   * @param {object} handlers - Service method handlers
+   * @param {object} definition - Service definition
+   * @returns {object} Wrapped handlers
+   */
+  #wrapHandlers(handlers, definition) {
+    const wrapped = {};
+    for (const [method, handler] of Object.entries(handlers)) {
+      const methodDef = definition[method];
+      if (methodDef?.responseStream) {
+        wrapped[method] = this.#wrapStreaming(method, handler);
+      } else {
+        wrapped[method] = this.#wrapUnary(method, handler);
+      }
+    }
+    return wrapped;
+  }
+
+  /**
+   * Wraps a streaming handler with tracing, authentication, and error handling via Observer
+   * @param {string} methodName - Method name for tracing
+   * @param {Function} handler - Streaming handler function
+   * @returns {Function} Wrapped handler
+   */
+  #wrapStreaming(methodName, handler) {
+    return async (call) => {
+      const emitError = (code, message) =>
+        call.emit("error", { code, message });
+
+      // Validate call.request exists (for server streaming)
+      if (!call?.request) {
+        return emitError(
+          this.grpc().status.INVALID_ARGUMENT,
+          "Invalid request: call.request is missing",
+        );
+      }
+
+      // Authenticate
+      const validation = this.auth().validateCall(call);
+      if (!validation.isValid) {
+        return emitError(
+          this.grpc().status.UNAUTHENTICATED,
+          `Authentication failed: ${validation.error}`,
+        );
+      }
+
+      // Observer handles everything: spans, events, metadata, logging
+      try {
+        await this.observer().observeServerStreamingCall(
+          methodName,
+          call,
+          handler,
+        );
+      } catch (error) {
+        emitError(this.grpc().status.INTERNAL, error?.message || String(error));
+      }
+    };
+  }
+
+  /**
+   * Wraps a unary handler with tracing, authentication, and error handling via Observer
+   * @param {string} methodName - Method name for tracing
+   * @param {Function} handler - Unary handler function
+   * @returns {Function} Wrapped handler
+   */
+  #wrapUnary(methodName, handler) {
+    return async (call, callback) => {
+      // Validate call.request exists
+      if (!call?.request) {
+        return callback({
+          code: this.grpc().status.INVALID_ARGUMENT,
+          message: "Invalid request: call.request is missing",
+        });
+      }
+
+      // Authenticate
+      const validation = this.auth().validateCall(call);
+      if (!validation.isValid) {
+        return callback({
+          code: this.grpc().status.UNAUTHENTICATED,
+          message: `Authentication failed: ${validation.error}`,
+        });
+      }
+
+      // Observer handles everything: spans, events, metadata, logging
+      try {
+        const response = await this.observer().observeServerUnaryCall(
+          methodName,
+          call,
+          async (call) => await handler(call),
+        );
+        callback(null, response);
+      } catch (error) {
+        callback({
+          code: this.grpc().status.INTERNAL,
+          message: error?.message || String(error),
+        });
+      }
+    };
+  }
+
+  /**
+   * Binds server to the specified URI
+   * @param {string} uri - Server URI to bind to
+   * @returns {Promise<number>} Bound port number
+   */
+  async #bindServer(uri) {
+    return new Promise((resolve, reject) => {
+      this.#server.bindAsync(
+        uri,
+        this.grpc().ServerCredentials.createInsecure(),
+        (error, port) => {
+          if (error) {
+            this.observer().logger()?.error("Server", error);
+            reject(error);
+          } else {
+            this.observer().logger()?.info("Server", "Listening", { uri });
+            resolve(port);
+          }
+        },
+      );
+    });
+  }
+
+  /** Sets up graceful shutdown handlers */
+  #setupShutdown() {
+    const shutdown = async () => {
+      this.observer().logger()?.info("Server", "Shutting down...");
+
+      // Call service shutdown if it exists
+      if (typeof this.#service.shutdown === "function") {
+        await this.#service.shutdown();
+      }
+
+      this.#server.tryShutdown(() => process.exit(0));
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  }
+}