@forwardimpact/librpc 0.1.87 → 0.1.89

package/package.json

@@ -1,14 +1,24 @@
 {
   "name": "@forwardimpact/librpc",
-  "version": "0.1.87",
+  "version": "0.1.89",
   "description": "gRPC framework and utilities for Guide",
   "license": "Apache-2.0",
   "author": "D. Olsson <hi@senzilla.io>",
   "type": "module",
-  "main": "index.js",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client.js": "./src/client.js",
+    "./base.js": "./src/base.js"
+  },
   "bin": {
     "fit-unary": "./bin/fit-unary.js"
   },
+  "files": [
+    "src/**/*.js",
+    "bin/**/*.js",
+    "README.md"
+  ],
   "engines": {
     "bun": ">=1.2.0",
     "node": ">=18.0.0"

package/src/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 → src/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/{server.js → src/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/auth.test.js

@@ -1,94 +0,0 @@
-import { test, describe, beforeEach } from "node:test";
-import assert from "node:assert";
-
-import { createAuth, HmacAuth } from "../index.js";
-
-describe("Auth", () => {
-  describe("HmacAuth", () => {
-    test("should throw if secret is missing or too short", () => {
-      assert.throws(() => new HmacAuth(), /Secret must be a non-empty string/);
-      assert.throws(
-        () => new HmacAuth("short"),
-        /Secret must be at least 32 characters long/,
-      );
-    });
-
-    test("should generate and verify valid tokens", () => {
-      const secret = "test-secret-that-is-at-least-32-characters-long";
-      const auth = new HmacAuth(secret);
-      const serviceId = "test-service";
-
-      const token = auth.generateToken(serviceId);
-      assert.ok(token);
-
-      const result = auth.verifyToken(token);
-      assert.strictEqual(result.isValid, true);
-      assert.strictEqual(result.serviceId, serviceId);
-    });
-
-    test("should reject expired tokens", async () => {
-      const secret = "test-secret-that-is-at-least-32-characters-long";
-      // 1 second lifetime
-      const auth = new HmacAuth(secret, 1);
-      const serviceId = "test-service";
-
-      const token = auth.generateToken(serviceId);
-
-      // Wait for token to expire (1.1 seconds)
-      await new Promise((resolve) => setTimeout(resolve, 1100));
-
-      const result = auth.verifyToken(token);
-      assert.strictEqual(result.isValid, false);
-      assert.match(result.error, /Token has expired/);
-    });
-
-    test("should reject invalid signatures", () => {
-      const secret = "test-secret-that-is-at-least-32-characters-long";
-      const auth = new HmacAuth(secret);
-      const serviceId = "test-service";
-
-      const token = auth.generateToken(serviceId);
-
-      // Tamper with the token (it's base64 encoded)
-      const decoded = Buffer.from(token, "base64").toString("utf8");
-      const parts = decoded.split(":");
-      // Change serviceId part
-      parts[0] = "other-service";
-      const tamperedToken = Buffer.from(parts.join(":")).toString("base64");
-
-      const result = auth.verifyToken(tamperedToken);
-      assert.strictEqual(result.isValid, false);
-      assert.match(result.error, /Invalid token signature/);
-    });
-  });
-
-  describe("createAuth", () => {
-    let originalEnv;
-
-    beforeEach(() => {
-      originalEnv = process.env.SERVICE_SECRET;
-    });
-
-    test("should throw if SERVICE_SECRET is missing", () => {
-      delete process.env.SERVICE_SECRET;
-      assert.throws(
-        () => createAuth("test"),
-        /SERVICE_SECRET environment variable is required/,
-      );
-    });
-
-    test("should create Interceptor with valid secret", () => {
-      process.env.SERVICE_SECRET =
-        "test-secret-that-is-at-least-32-characters-long";
-      const interceptor = createAuth("test");
-      assert.ok(interceptor);
-
-      // Cleanup
-      if (originalEnv) {
-        process.env.SERVICE_SECRET = originalEnv;
-      } else {
-        delete process.env.SERVICE_SECRET;
-      }
-    });
-  });
-});

package/test/client.test.js

@@ -1,138 +0,0 @@
-import { test, describe, beforeEach, mock } from "node:test";
-import assert from "node:assert";
-import { PassThrough } from "stream";
-
-import { Client } from "../index.js";
-import {
-  createMockGrpcFn,
-  createMockObserverFn,
-  createMockAuthFn,
-  createMockLogger,
-} from "@forwardimpact/libharness";
-
-describe("Client", () => {
-  let mockConfig;
-  let mockGrpcFn;
-  let mockAuthFn;
-  let mockLogFn;
-  let mockObserverFn;
-  let mockClientInstance;
-
-  beforeEach(() => {
-    mockConfig = {
-      name: "memory", // Use a valid service name that exists in definitions
-      host: "0.0.0.0",
-      port: 5000,
-    };
-
-    mockClientInstance = {
-      TestMethod: mock.fn((_req, _meta, cb) => cb(null, { result: "success" })),
-      StreamMethod: mock.fn((_req, _meta) => {
-        const stream = new PassThrough({ objectMode: true });
-        process.nextTick(() => {
-          stream.emit("metadata", {});
-          stream.write({ result: "chunk1" });
-          stream.write({ result: "chunk2" });
-          stream.end();
-        });
-        return stream;
-      }),
-    };
-
-    mockGrpcFn = createMockGrpcFn({
-      grpc: {
-        Metadata: class {},
-        makeGenericClientConstructor: mock.fn(() => {
-          return function () {
-            return mockClientInstance;
-          };
-        }),
-      },
-    });
-
-    mockAuthFn = createMockAuthFn();
-
-    mockLogFn = createMockLogger();
-
-    mockObserverFn = createMockObserverFn();
-  });
-
-  test("should require config parameter", () => {
-    assert.throws(
-      () =>
-        new Client(
-          null,
-          mockLogFn,
-          null,
-          mockObserverFn,
-          mockGrpcFn,
-          mockAuthFn,
-        ),
-      /config is required/,
-    );
-  });
-
-  test("should accept valid parameters", () => {
-    const client = new Client(
-      mockConfig,
-      mockLogFn,
-      null,
-      mockObserverFn,
-      mockGrpcFn,
-      mockAuthFn,
-    );
-
-    assert.ok(client);
-    assert.strictEqual(client.config, mockConfig);
-  });
-
-  test("callUnary should execute unary call", async () => {
-    const client = new Client(
-      mockConfig,
-      mockLogFn,
-      null,
-      mockObserverFn,
-      mockGrpcFn,
-      mockAuthFn,
-    );
-
-    const response = await client.callUnary("TestMethod", { some: "data" });
-    assert.deepStrictEqual(response, { result: "success" });
-    assert.strictEqual(mockClientInstance.TestMethod.mock.callCount(), 1);
-  });
-
-  test("callStream should execute streaming call", async () => {
-    const client = new Client(
-      mockConfig,
-      mockLogFn,
-      null,
-      mockObserverFn,
-      mockGrpcFn,
-      mockAuthFn,
-    );
-
-    const stream = client.callStream("StreamMethod", { some: "data" });
-
-    const chunks = [];
-    for await (const chunk of stream) {
-      chunks.push(chunk);
-    }
-
-    assert.strictEqual(chunks.length, 2);
-    assert.deepStrictEqual(chunks[0], { result: "chunk1" });
-    assert.deepStrictEqual(chunks[1], { result: "chunk2" });
-    assert.strictEqual(mockClientInstance.StreamMethod.mock.callCount(), 1);
-  });
-
-  test("should accept tracer parameter", () => {
-    const client = new Client(
-      mockConfig,
-      mockLogFn,
-      {}, // tracer
-      mockObserverFn,
-      mockGrpcFn,
-      mockAuthFn,
-    );
-    assert.ok(client);
-  });
-});

package/test/server.test.js

@@ -1,123 +0,0 @@
-import { test, describe, beforeEach, mock } from "node:test";
-import assert from "node:assert";
-
-import { Server } from "../index.js";
-import {
-  createMockConfig,
-  createMockGrpcFn,
-  createMockObserverFn,
-  createMockAuthFn,
-  createMockLogger,
-  createMockTracer,
-} from "@forwardimpact/libharness";
-
-describe("Server", () => {
-  let mockService;
-  let mockConfig;
-  let mockGrpcFn;
-  let mockAuthFn;
-  let mockLogFn;
-  let mockObserverFn;
-
-  beforeEach(() => {
-    mockService = {
-      getHandlers: () => ({
-        TestMethod: async (_call) => ({ result: "test" }),
-      }),
-    };
-
-    mockConfig = createMockConfig("memory", { host: "0.0.0.0", port: 5000 });
-    mockGrpcFn = createMockGrpcFn();
-    mockAuthFn = createMockAuthFn();
-    mockLogFn = createMockLogger();
-    mockObserverFn = createMockObserverFn(mockLogFn);
-  });
-
-  test("should require service parameter", () => {
-    assert.throws(
-      () =>
-        new Server(
-          null,
-          mockConfig,
-          mockLogFn,
-          null,
-          mockObserverFn,
-          mockGrpcFn,
-          mockAuthFn,
-        ),
-      /service is required/,
-    );
-  });
-
-  test("should require config parameter", () => {
-    assert.throws(
-      () =>
-        new Server(
-          mockService,
-          null,
-          mockLogFn,
-          null,
-          mockObserverFn,
-          mockGrpcFn,
-          mockAuthFn,
-        ),
-      /config is required/,
-    );
-  });
-
-  test("should accept valid parameters", () => {
-    const server = new Server(
-      mockService,
-      mockConfig,
-      mockLogFn,
-      null,
-      mockObserverFn,
-      mockGrpcFn,
-      mockAuthFn,
-    );
-
-    assert.ok(server);
-    assert.strictEqual(server.config, mockConfig);
-  });
-
-  test("should call service methods during setup", async () => {
-    const getHandlersSpy = mock.fn(() => ({
-      TestMethod: async () => ({ result: "test" }),
-    }));
-
-    const spiedService = {
-      getHandlers: getHandlersSpy,
-    };
-
-    const server = new Server(
-      spiedService,
-      mockConfig,
-      mockLogFn,
-      null,
-      mockObserverFn,
-      mockGrpcFn,
-      mockAuthFn,
-    );
-
-    // Start the server to trigger setup
-    await server.start();
-
-    assert.strictEqual(getHandlersSpy.mock.callCount(), 1);
-  });
-
-  test("should accept tracer parameter", () => {
-    const mockTracer = createMockTracer();
-
-    const server = new Server(
-      mockService,
-      mockConfig,
-      mockLogFn,
-      mockTracer,
-      mockObserverFn,
-      mockGrpcFn,
-      mockAuthFn,
-    );
-
-    assert.ok(server);
-  });
-});