@forwardimpact/librpc 0.1.85 → 0.1.88

package/bin/fit-unary.js

@@ -1,24 +1,44 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { createCli } from "@forwardimpact/libcli";
 import { createClient, createTracer } from "@forwardimpact/librpc";
 import { createLogger } from "@forwardimpact/libtelemetry";
 
+const { version: VERSION } = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+const definition = {
+  name: "fit-unary",
+  version: VERSION,
+  description: "Make a unary gRPC call to a service",
+  usage: "fit-unary <service> <method> [json-request]",
+  options: {
+    help: { type: "boolean", short: "h", description: "Show this help" },
+    version: { type: "boolean", description: "Show version" },
+    json: { type: "boolean", description: "Output help as JSON" },
+  },
+  examples: ['fit-unary memory GetWindow \'{"resource_id":"..."}\''],
+};
+
+const cli = createCli(definition);
+const logger = createLogger("cli");
+
 /**
  * Makes a unary gRPC call to a service
- * Usage: fit-unary <service> <method> [json-request]
  * @returns {Promise<void>}
  */
 async function main() {
-  const [service, method, requestJson] = process.argv.slice(2);
+  const parsed = cli.parse(process.argv.slice(2));
+  if (!parsed) process.exit(0);
+
+  const [service, method, requestJson] = parsed.positionals;
   if (!service || !method) {
-    console.error("Usage: fit-unary <service> <method> [json-request]");
-    console.error(
-      'Example: fit-unary memory GetWindow \'{"resource_id":"..."}\'',
-    );
-    process.exit(1);
+    cli.usageError("expected arguments: <service> <method> [json-request]");
+    process.exit(2);
   }
 
   const request = requestJson ? JSON.parse(requestJson) : {};
-  const logger = createLogger("cli");
   const tracer = await createTracer("cli");
   const client = await createClient(service, logger, tracer);
 
@@ -27,6 +47,7 @@ async function main() {
 }
 
 main().catch((error) => {
-  console.error(error.message);
+  logger.exception("main", error);
+  cli.error(error.message);
   process.exit(1);
 });

package/health.js

@@ -0,0 +1,93 @@
+/**
+ * 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).
+ */
+
+/** Serving status enum matching grpc.health.v1 */
+export const ServingStatus = {
+  UNKNOWN: 0,
+  SERVING: 1,
+  NOT_SERVING: 2,
+  SERVICE_UNKNOWN: 3,
+};
+
+/**
+ * Serialize a HealthCheckRequest to bytes.
+ * Proto: message HealthCheckRequest { string service = 1; }
+ */
+function serializeRequest(value) {
+  const service = value?.service || "";
+  if (service.length === 0) return Buffer.alloc(0);
+  const encoded = Buffer.from(service, "utf8");
+  // field 1, wire type 2 (length-delimited): tag = 0x0a
+  const header = Buffer.alloc(2);
+  header[0] = 0x0a;
+  header[1] = encoded.length; // works for lengths < 128
+  return Buffer.concat([header, encoded]);
+}
+
+/**
+ * Deserialize bytes to a HealthCheckRequest.
+ */
+function deserializeRequest(buffer) {
+  if (!buffer || buffer.length === 0) return { service: "" };
+  if (buffer[0] === 0x0a) {
+    const len = buffer[1];
+    return { service: buffer.subarray(2, 2 + len).toString("utf8") };
+  }
+  return { service: "" };
+}
+
+/**
+ * Serialize a HealthCheckResponse to bytes.
+ * Proto: message HealthCheckResponse { ServingStatus status = 1; }
+ */
+function serializeResponse(value) {
+  const status = value?.status ?? 0;
+  if (status === 0) return Buffer.alloc(0);
+  // field 1, wire type 0 (varint): tag = 0x08
+  return Buffer.from([0x08, status]);
+}
+
+/**
+ * Deserialize bytes to a HealthCheckResponse.
+ */
+function deserializeResponse(buffer) {
+  if (!buffer || buffer.length === 0) return { status: 0 };
+  if (buffer[0] === 0x08) return { status: buffer[1] };
+  return { status: 0 };
+}
+
+/** Service definition compatible with grpc.Server.addService */
+export const healthDefinition = {
+  Check: {
+    path: "/grpc.health.v1.Health/Check",
+    requestStream: false,
+    responseStream: false,
+    requestSerialize: serializeRequest,
+    requestDeserialize: deserializeRequest,
+    responseSerialize: serializeResponse,
+    responseDeserialize: deserializeResponse,
+  },
+};
+
+/**
+ * Creates health check handlers for the given service name.
+ * @param {string} serviceName - The application service name (e.g., "Graph")
+ * @returns {object} Handler map for the Health service definition
+ */
+export function createHealthHandlers(serviceName) {
+  return {
+    Check: (_call, callback) => {
+      const requestedService = _call.request?.service || "";
+
+      if (requestedService === "" || requestedService === serviceName) {
+        return callback(null, { status: ServingStatus.SERVING });
+      }
+      return callback(null, { status: ServingStatus.SERVICE_UNKNOWN });
+    },
+  };
+}

package/index.js

@@ -10,6 +10,11 @@ export { createGrpc, createAuth, Rpc } from "./base.js";
 export { Client } from "./client.js";
 export { Interceptor, HmacAuth } from "./auth.js";
 export { Server } from "./server.js";
+export {
+  healthDefinition,
+  createHealthHandlers,
+  ServingStatus,
+} from "./health.js";
 
 // Export services and clients objects for runtime access
 export const services = exports.services || {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/librpc",
-  "version": "0.1.85",
+  "version": "0.1.88",
   "description": "gRPC framework and utilities for Guide",
   "license": "Apache-2.0",
   "author": "D. Olsson <hi@senzilla.io>",
@@ -17,6 +17,7 @@
     "test": "bun run node --test test/*.test.js"
   },
   "dependencies": {
+    "@forwardimpact/libcli": "^0.1.0",
     "@forwardimpact/libconfig": "^0.1.58",
     "@forwardimpact/libtelemetry": "^0.1.22",
     "@forwardimpact/libutil": "^0.1.60",

package/server.js

@@ -5,6 +5,7 @@ import {
   createObserver,
   capitalizeFirstLetter,
 } from "./base.js";
+import { healthDefinition, createHealthHandlers } from "./health.js";
 
 /**
  * gRPC Server class using pre-compiled service definitions
@@ -63,6 +64,12 @@ export class Server extends Rpc {
 
     this.#server.addService(definition, wrappedHandlers);
 
+    // Register standard gRPC health check (no auth, no observer wrapping)
+    this.#server.addService(
+      healthDefinition,
+      createHealthHandlers(serviceName),
+    );
+
     const uri = `${this.config.host}:${this.config.port}`;
     await this.#bindServer(uri);
 

package/test/health.test.js

@@ -0,0 +1,170 @@
+import { test, describe } from "node:test";
+import assert from "node:assert";
+
+import {
+  healthDefinition,
+  createHealthHandlers,
+  ServingStatus,
+  Server,
+} from "../index.js";
+import {
+  createMockConfig,
+  createMockGrpcFn,
+  createMockObserverFn,
+  createMockAuthFn,
+  createMockLogger,
+} from "@forwardimpact/libharness";
+
+describe("healthDefinition", () => {
+  test("Check has the required service definition fields", () => {
+    const check = healthDefinition.Check;
+    assert.strictEqual(check.path, "/grpc.health.v1.Health/Check");
+    assert.strictEqual(check.requestStream, false);
+    assert.strictEqual(check.responseStream, false);
+    assert.strictEqual(typeof check.requestSerialize, "function");
+    assert.strictEqual(typeof check.requestDeserialize, "function");
+    assert.strictEqual(typeof check.responseSerialize, "function");
+    assert.strictEqual(typeof check.responseDeserialize, "function");
+  });
+
+  test("request serialization round-trip with service name", () => {
+    const original = { service: "Graph" };
+    const bytes = healthDefinition.Check.requestSerialize(original);
+    const decoded = healthDefinition.Check.requestDeserialize(bytes);
+    assert.strictEqual(decoded.service, "Graph");
+  });
+
+  test("request serialization round-trip with empty service", () => {
+    const original = { service: "" };
+    const bytes = healthDefinition.Check.requestSerialize(original);
+    const decoded = healthDefinition.Check.requestDeserialize(bytes);
+    assert.strictEqual(decoded.service, "");
+  });
+
+  test("response serialization round-trip SERVING", () => {
+    const original = { status: ServingStatus.SERVING };
+    const bytes = healthDefinition.Check.responseSerialize(original);
+    const decoded = healthDefinition.Check.responseDeserialize(bytes);
+    assert.strictEqual(decoded.status, ServingStatus.SERVING);
+  });
+
+  test("response serialization round-trip UNKNOWN (proto3 default)", () => {
+    const original = { status: ServingStatus.UNKNOWN };
+    const bytes = healthDefinition.Check.responseSerialize(original);
+    const decoded = healthDefinition.Check.responseDeserialize(bytes);
+    assert.strictEqual(decoded.status, ServingStatus.UNKNOWN);
+  });
+
+  test("response serialization round-trip SERVICE_UNKNOWN", () => {
+    const original = { status: ServingStatus.SERVICE_UNKNOWN };
+    const bytes = healthDefinition.Check.responseSerialize(original);
+    const decoded = healthDefinition.Check.responseDeserialize(bytes);
+    assert.strictEqual(decoded.status, ServingStatus.SERVICE_UNKNOWN);
+  });
+});
+
+describe("createHealthHandlers", () => {
+  test("empty service name returns SERVING", (_, done) => {
+    const handlers = createHealthHandlers("Graph");
+    handlers.Check({ request: { service: "" } }, (err, response) => {
+      assert.strictEqual(err, null);
+      assert.strictEqual(response.status, ServingStatus.SERVING);
+      done();
+    });
+  });
+
+  test("matching service name returns SERVING", (_, done) => {
+    const handlers = createHealthHandlers("Graph");
+    handlers.Check({ request: { service: "Graph" } }, (err, response) => {
+      assert.strictEqual(err, null);
+      assert.strictEqual(response.status, ServingStatus.SERVING);
+      done();
+    });
+  });
+
+  test("unknown service name returns SERVICE_UNKNOWN", (_, done) => {
+    const handlers = createHealthHandlers("Graph");
+    handlers.Check({ request: { service: "Nonexistent" } }, (err, response) => {
+      assert.strictEqual(err, null);
+      assert.strictEqual(response.status, ServingStatus.SERVICE_UNKNOWN);
+      done();
+    });
+  });
+});
+
+describe("Server health registration", () => {
+  test("start() registers health service alongside application service", async () => {
+    const mockService = {
+      getHandlers: () => ({
+        TestMethod: async () => ({ result: "test" }),
+      }),
+    };
+
+    const mockConfig = createMockConfig("memory", {
+      host: "0.0.0.0",
+      port: 5000,
+    });
+    const mockGrpcFn = createMockGrpcFn();
+    const mockAuthFn = createMockAuthFn();
+    const mockLogFn = createMockLogger();
+    const mockObserverFn = createMockObserverFn(mockLogFn);
+
+    const server = new Server(
+      mockService,
+      mockConfig,
+      mockLogFn,
+      null,
+      mockObserverFn,
+      mockGrpcFn,
+      mockAuthFn,
+    );
+
+    await server.start();
+    assert.ok(server);
+  });
+
+  test("health handlers bypass auth wrapping", async () => {
+    let authCallCount = 0;
+    const trackingAuthFn = () => ({
+      createClientInterceptor: () => () => {},
+      validateCall: () => {
+        authCallCount++;
+        return { isValid: true, serviceId: "test" };
+      },
+    });
+
+    const mockService = {
+      getHandlers: () => ({
+        TestMethod: async () => ({ result: "test" }),
+      }),
+    };
+
+    const mockConfig = createMockConfig("memory", {
+      host: "0.0.0.0",
+      port: 5000,
+    });
+    const mockGrpcFn = createMockGrpcFn();
+    const mockLogFn = createMockLogger();
+    const mockObserverFn = createMockObserverFn(mockLogFn);
+
+    const server = new Server(
+      mockService,
+      mockConfig,
+      mockLogFn,
+      null,
+      mockObserverFn,
+      mockGrpcFn,
+      trackingAuthFn,
+    );
+
+    await server.start();
+
+    const handlers = createHealthHandlers("Memory");
+    const initialCount = authCallCount;
+    handlers.Check({ request: { service: "" } }, (err, response) => {
+      assert.strictEqual(err, null);
+      assert.strictEqual(response.status, ServingStatus.SERVING);
+    });
+    assert.strictEqual(authCallCount, initialCount);
+  });
+});