@webda/grpc 4.0.0-beta.3

package/src/grpc-stream.spec.ts

@@ -0,0 +1,417 @@
+import { suite, test } from "@webda/test";
+import * as assert from "assert";
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import { GrpcStream, GrpcStatus, GrpcMethodDef } from "./grpc-stream.js";
+
+/**
+ * Create a mock IncomingMessage-like object (EventEmitter + readable stream)
+ */
+function createMockRequest(): EventEmitter & { headers: Record<string, string> } {
+  const req = new PassThrough() as any;
+  req.headers = { "content-type": "application/grpc" };
+  return req;
+}
+
+/**
+ * Create a mock ServerResponse-like object that captures writes and trailers
+ */
+function createMockResponse(): {
+  res: any;
+  written: Buffer[];
+  headers: Record<string, string>;
+  trailers: Record<string, string> | null;
+  ended: boolean;
+} {
+  const state = {
+    written: [] as Buffer[],
+    headers: {} as Record<string, string>,
+    trailers: null as Record<string, string> | null,
+    ended: false,
+    res: null as any
+  };
+
+  state.res = {
+    setHeader(key: string, value: string) {
+      state.headers[key] = value;
+    },
+    write(data: Buffer) {
+      state.written.push(Buffer.from(data));
+    },
+    addTrailers(t: Record<string, string>) {
+      state.trailers = t;
+    },
+    end() {
+      state.ended = true;
+    }
+  };
+
+  return state;
+}
+
+/**
+ * Create a simple JSON-based method definition for testing
+ */
+function createJsonMethodDef(): GrpcMethodDef<any, any> {
+  return {
+    requestSerialize: (msg: any) => Buffer.from(JSON.stringify(msg)),
+    requestDeserialize: (buf: Buffer) => JSON.parse(buf.toString()),
+    responseSerialize: (msg: any) => Buffer.from(JSON.stringify(msg)),
+    responseDeserialize: (buf: Buffer) => JSON.parse(buf.toString()),
+    requestStream: false,
+    responseStream: false
+  };
+}
+
+/**
+ * Create a gRPC frame from a message buffer
+ * Format: 1 byte compressed flag + 4 bytes big-endian length + payload
+ */
+function createGrpcFrame(data: Buffer): Buffer {
+  const frame = Buffer.alloc(5 + data.length);
+  frame.writeUInt8(0, 0); // Not compressed
+  frame.writeUInt32BE(data.length, 1);
+  data.copy(frame, 5);
+  return frame;
+}
+
+@suite
+class GrpcStreamTest {
+  @test
+  constructorSetsHeaders() {
+    const req = createMockRequest();
+    const { res, headers } = createMockResponse();
+    const def = createJsonMethodDef();
+
+    new GrpcStream(req as any, res, def);
+
+    assert.strictEqual(headers["Content-Type"], "application/grpc");
+    assert.strictEqual(headers["Grpc-Accept-Encoding"], "identity");
+    assert.strictEqual(headers["Grpc-Encoding"], "identity");
+  }
+
+  @test
+  async onMessageReceivesDeserializedMessage() {
+    const req = createMockRequest();
+    const { res } = createMockResponse();
+    const def = createJsonMethodDef();
+
+    const stream = new GrpcStream(req as any, res, def);
+
+    const received: any[] = [];
+    stream.onMessage(msg => {
+      received.push(msg);
+    });
+
+    const payload = Buffer.from(JSON.stringify({ hello: "world" }));
+    const frame = createGrpcFrame(payload);
+    req.emit("data", frame);
+
+    assert.strictEqual(received.length, 1);
+    assert.deepStrictEqual(received[0], { hello: "world" });
+  }
+
+  @test
+  async sendCreatesProperGrpcFrame() {
+    const req = createMockRequest();
+    const { res, written } = createMockResponse();
+    const def = createJsonMethodDef();
+
+    const stream = new GrpcStream(req as any, res, def);
+
+    stream.send({ result: "ok" });
+
+    assert.strictEqual(written.length, 1);
+    const frame = written[0];
+
+    // Verify frame structure: 1 byte compression + 4 bytes length + payload
+    assert.strictEqual(frame.readUInt8(0), 0, "Compression flag should be 0");
+    const payloadLength = frame.readUInt32BE(1);
+    const payload = frame.subarray(5, 5 + payloadLength);
+    const decoded = JSON.parse(payload.toString());
+    assert.deepStrictEqual(decoded, { result: "ok" });
+  }
+
+  @test
+  async endWritesTrailersWithGrpcStatus() {
+    const req = createMockRequest();
+    const { res, trailers, ended } = createMockResponse();
+    const mock = createMockResponse();
+    const def = createJsonMethodDef();
+
+    const stream = new GrpcStream(req as any, mock.res, def);
+
+    stream.end(0);
+
+    assert.ok(mock.ended, "Response should be ended");
+    assert.ok(mock.trailers !== null, "Trailers should be set");
+    assert.strictEqual(mock.trailers!["grpc-status"], "0");
+    assert.strictEqual(mock.trailers!["grpc-message"], undefined, "No message for OK status");
+  }
+
+  @test
+  async endWithMessageEncodesURIComponent() {
+    const req = createMockRequest();
+    const mock = createMockResponse();
+    const def = createJsonMethodDef();
+
+    const stream = new GrpcStream(req as any, mock.res, def);
+
+    stream.end(13, "Internal server error");
+
+    assert.ok(mock.trailers !== null);
+    assert.strictEqual(mock.trailers!["grpc-status"], "13");
+    assert.strictEqual(mock.trailers!["grpc-message"], encodeURIComponent("Internal server error"));
+  }
+
+  @test
+  async endDefaultStatusIsZero() {
+    const req = createMockRequest();
+    const mock = createMockResponse();
+    const def = createJsonMethodDef();
+
+    const stream = new GrpcStream(req as any, mock.res, def);
+
+    stream.end(); // No arguments
+
+    assert.strictEqual(mock.trailers!["grpc-status"], "0");
+  }
+
+  @test
+  async sendUnarySendsMessageThenEnds() {
+    const req = createMockRequest();
+    const mock = createMockResponse();
+    const def = createJsonMethodDef();
+
+    const stream = new GrpcStream(req as any, mock.res, def);
+
+    stream.sendUnary({ data: "response" });
+
+    // Should have written one frame
+    assert.strictEqual(mock.written.length, 1);
+    const payload = mock.written[0].subarray(5);
+    assert.deepStrictEqual(JSON.parse(payload.toString()), { data: "response" });
+
+    // Should have ended with status 0
+    assert.ok(mock.ended);
+    assert.strictEqual(mock.trailers!["grpc-status"], "0");
+  }
+
+  @test
+  async sendErrorEndsWithErrorStatus() {
+    const req = createMockRequest();
+    const mock = createMockResponse();
+    const def = createJsonMethodDef();
+
+    const stream = new GrpcStream(req as any, mock.res, def);
+
+    stream.sendError(GrpcStatus.NOT_FOUND, "Resource not found");
+
+    assert.ok(mock.ended);
+    assert.strictEqual(mock.trailers!["grpc-status"], "5");
+    assert.strictEqual(mock.trailers!["grpc-message"], encodeURIComponent("Resource not found"));
+    // Should NOT have written any data frames
+    assert.strictEqual(mock.written.length, 0);
+  }
+
+  @test
+  async multipleMessagesInOneChunk() {
+    const req = createMockRequest();
+    const mock = createMockResponse();
+    const def = createJsonMethodDef();
+
+    const stream = new GrpcStream(req as any, mock.res, def);
+
+    const received: any[] = [];
+    stream.onMessage(msg => {
+      received.push(msg);
+    });
+
+    const payload1 = Buffer.from(JSON.stringify({ id: 1 }));
+    const payload2 = Buffer.from(JSON.stringify({ id: 2 }));
+    const frame1 = createGrpcFrame(payload1);
+    const frame2 = createGrpcFrame(payload2);
+
+    // Send both frames in a single data event
+    const combined = Buffer.concat([frame1, frame2]);
+    req.emit("data", combined);
+
+    assert.strictEqual(received.length, 2);
+    assert.deepStrictEqual(received[0], { id: 1 });
+    assert.deepStrictEqual(received[1], { id: 2 });
+  }
+
+  @test
+  async splitChunksPartialMessage() {
+    const req = createMockRequest();
+    const mock = createMockResponse();
+    const def = createJsonMethodDef();
+
+    const stream = new GrpcStream(req as any, mock.res, def);
+
+    const received: any[] = [];
+    stream.onMessage(msg => {
+      received.push(msg);
+    });
+
+    const payload = Buffer.from(JSON.stringify({ key: "value" }));
+    const frame = createGrpcFrame(payload);
+
+    // Split the frame at an arbitrary point (midway through the payload)
+    const splitPoint = 8; // After header + a few bytes of payload
+    const part1 = frame.subarray(0, splitPoint);
+    const part2 = frame.subarray(splitPoint);
+
+    // Emit first part — incomplete message
+    req.emit("data", part1);
+    assert.strictEqual(received.length, 0, "Should not deliver incomplete message");
+
+    // Emit second part — completes the message
+    req.emit("data", part2);
+    assert.strictEqual(received.length, 1, "Should deliver message after all parts arrive");
+    assert.deepStrictEqual(received[0], { key: "value" });
+  }
+
+  @test
+  async onEndHandlerCalledWhenRequestEnds() {
+    const req = createMockRequest();
+    const mock = createMockResponse();
+    const def = createJsonMethodDef();
+
+    const stream = new GrpcStream(req as any, mock.res, def);
+
+    let endCalled = false;
+    stream.onEnd(() => {
+      endCalled = true;
+    });
+
+    req.emit("end");
+
+    assert.ok(endCalled, "onEnd handler should be called");
+  }
+
+  @test
+  async onCancelHandlerCalledWhenRequestCloses() {
+    const req = createMockRequest();
+    const mock = createMockResponse();
+    const def = createJsonMethodDef();
+
+    const stream = new GrpcStream(req as any, mock.res, def);
+
+    let cancelCalled = false;
+    stream.onCancel(() => {
+      cancelCalled = true;
+    });
+
+    req.emit("close");
+
+    assert.ok(cancelCalled, "onCancel handler should be called");
+  }
+
+  @test
+  chainingReturnsSameInstance() {
+    const req = createMockRequest();
+    const mock = createMockResponse();
+    const def = createJsonMethodDef();
+
+    const stream = new GrpcStream(req as any, mock.res, def);
+
+    const result = stream
+      .onMessage(() => {})
+      .onEnd(() => {})
+      .onCancel(() => {});
+
+    assert.strictEqual(result, stream, "Chaining methods should return the same instance");
+  }
+
+  @test
+  async endHandlesResponseWithoutAddTrailers() {
+    const req = createMockRequest();
+    const def = createJsonMethodDef();
+
+    // Create a response that does NOT have addTrailers
+    const res = {
+      setHeader() {},
+      write() {},
+      end() {}
+      // no addTrailers
+    };
+
+    const stream = new GrpcStream(req as any, res as any, def);
+
+    // Should not throw even without addTrailers
+    stream.end(0);
+  }
+
+  @test
+  async noMessageHandlerDoesNotThrow() {
+    const req = createMockRequest();
+    const mock = createMockResponse();
+    const def = createJsonMethodDef();
+
+    // Create stream without registering onMessage
+    new GrpcStream(req as any, mock.res, def);
+
+    const payload = Buffer.from(JSON.stringify({ test: true }));
+    const frame = createGrpcFrame(payload);
+
+    // Should not throw when no handler is registered
+    req.emit("data", frame);
+  }
+
+  @test
+  async noEndHandlerDoesNotThrow() {
+    const req = createMockRequest();
+    const mock = createMockResponse();
+    const def = createJsonMethodDef();
+
+    // No onEnd registered
+    new GrpcStream(req as any, mock.res, def);
+
+    // Should not throw
+    req.emit("end");
+  }
+
+  @test
+  async noCancelHandlerDoesNotThrow() {
+    const req = createMockRequest();
+    const mock = createMockResponse();
+    const def = createJsonMethodDef();
+
+    // No onCancel registered
+    new GrpcStream(req as any, mock.res, def);
+
+    // Should not throw
+    req.emit("close");
+  }
+}
+
+@suite
+class GrpcStatusTest {
+  @test
+  statusCodeValues() {
+    assert.strictEqual(GrpcStatus.OK, 0);
+    assert.strictEqual(GrpcStatus.CANCELLED, 1);
+    assert.strictEqual(GrpcStatus.UNKNOWN, 2);
+    assert.strictEqual(GrpcStatus.INVALID_ARGUMENT, 3);
+    assert.strictEqual(GrpcStatus.DEADLINE_EXCEEDED, 4);
+    assert.strictEqual(GrpcStatus.NOT_FOUND, 5);
+    assert.strictEqual(GrpcStatus.ALREADY_EXISTS, 6);
+    assert.strictEqual(GrpcStatus.PERMISSION_DENIED, 7);
+    assert.strictEqual(GrpcStatus.RESOURCE_EXHAUSTED, 8);
+    assert.strictEqual(GrpcStatus.FAILED_PRECONDITION, 9);
+    assert.strictEqual(GrpcStatus.ABORTED, 10);
+    assert.strictEqual(GrpcStatus.OUT_OF_RANGE, 11);
+    assert.strictEqual(GrpcStatus.UNIMPLEMENTED, 12);
+    assert.strictEqual(GrpcStatus.INTERNAL, 13);
+    assert.strictEqual(GrpcStatus.UNAVAILABLE, 14);
+    assert.strictEqual(GrpcStatus.DATA_LOSS, 15);
+    assert.strictEqual(GrpcStatus.UNAUTHENTICATED, 16);
+  }
+
+  @test
+  okSymbol() {
+    assert.ok(typeof GrpcStream.OK === "symbol", "OK should be a symbol");
+    assert.strictEqual(GrpcStream.OK.toString(), "Symbol(OK)");
+  }
+}

package/src/grpc-stream.ts

@@ -0,0 +1,192 @@
+import type { Http2ServerRequest, Http2ServerResponse } from "node:http2";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+/**
+ * Parsed gRPC method definition with serializer/deserializer functions.
+ */
+export interface GrpcMethodDef<Req = any, Res = any> {
+  requestSerialize: (msg: Req) => Buffer;
+  requestDeserialize: (buf: Buffer) => Req;
+  responseSerialize: (msg: Res) => Buffer;
+  responseDeserialize: (buf: Buffer) => Res;
+  requestStream: boolean;
+  responseStream: boolean;
+}
+
+/**
+ * gRPC bidirectional stream handler.
+ *
+ * Manages frame parsing (5-byte header: compressed flag + 4-byte big-endian length),
+ * message deserialization, and response framing for HTTP/2 gRPC streams.
+ *
+ * Supports all four gRPC patterns:
+ * - Unary (single request, single response)
+ * - Server streaming (single request, stream of responses)
+ * - Client streaming (stream of requests, single response)
+ * - Bidirectional streaming (stream of requests, stream of responses)
+ */
+export class GrpcStream<RequestType = any, ResponseType = any> {
+  /** Sentinel value indicating successful stream setup */
+  static OK = Symbol("OK");
+
+  private onMessageHandler: (message: RequestType) => void | Promise<void>;
+  private onEndHandler?: () => void;
+  private onCancelHandler?: () => void;
+  private chunk: Buffer | null = null;
+  private messageLength = 0;
+  private request: IncomingMessage | Http2ServerRequest;
+  private response: ServerResponse | Http2ServerResponse;
+  private definition: GrpcMethodDef<RequestType, ResponseType>;
+
+  /**
+   * Create a new GrpcStream to handle a single gRPC request/response lifecycle.
+   * @param req - the incoming HTTP/2 request carrying the gRPC frames
+   * @param res - the HTTP/2 response used to write gRPC frames and trailers
+   * @param definition - protobuf method definition providing serialize/deserialize functions
+   */
+  constructor(
+    req: IncomingMessage | Http2ServerRequest,
+    res: ServerResponse | Http2ServerResponse,
+    definition: GrpcMethodDef<RequestType, ResponseType>
+  ) {
+    this.request = req;
+    this.response = res;
+    this.definition = definition;
+
+    // Set gRPC response headers
+    this.response.setHeader("Content-Type", "application/grpc");
+    this.response.setHeader("Grpc-Accept-Encoding", "identity");
+    this.response.setHeader("Grpc-Encoding", "identity");
+
+    // Parse incoming gRPC frames
+    req.on("data", (data: Buffer) => {
+      if (this.chunk === null) {
+        this.messageLength = data.readUInt32BE(1);
+        this.chunk = data;
+      } else {
+        this.chunk = Buffer.concat([this.chunk, data]);
+      }
+      // Check if we have a complete message
+      while (this.chunk && this.chunk.length >= 5 + this.messageLength) {
+        const message = this.chunk.subarray(5, 5 + this.messageLength);
+        const deserialized = this.definition.requestDeserialize(message);
+        this.onMessageHandler?.(deserialized);
+        // Advance to next frame
+        this.chunk = this.chunk.subarray(5 + this.messageLength);
+        if (this.chunk.length >= 5) {
+          this.messageLength = this.chunk.readUInt32BE(1);
+        } else if (this.chunk.length === 0) {
+          this.chunk = null;
+        }
+      }
+    });
+
+    req.on("end", () => {
+      this.onEndHandler?.();
+    });
+
+    req.on("close", () => {
+      this.onCancelHandler?.();
+    });
+  }
+
+  /**
+   * Register handler for incoming messages
+   * @param handler - callback invoked with each deserialized request message
+   * @returns this instance for chaining
+   */
+  onMessage(handler: (message: RequestType) => void | Promise<void>): this {
+    this.onMessageHandler = handler;
+    return this;
+  }
+
+  /**
+   * Register handler for stream end (client finished sending)
+   * @param handler - callback invoked when the client closes the send side of the stream
+   * @returns this instance for chaining
+   */
+  onEnd(handler: () => void): this {
+    this.onEndHandler = handler;
+    return this;
+  }
+
+  /**
+   * Register handler for stream cancellation (client disconnected)
+   * @param handler - callback invoked when the underlying connection is closed by the client
+   * @returns this instance for chaining
+   */
+  onCancel(handler: () => void): this {
+    this.onCancelHandler = handler;
+    return this;
+  }
+
+  /**
+   * Send a response message with gRPC framing.
+   * @param message - the response message to serialize and send
+   * @returns void
+   */
+  send(message: ResponseType): void {
+    const responseBuffer = this.definition.responseSerialize(message);
+    const frame = Buffer.alloc(5 + responseBuffer.length);
+    frame.writeUInt8(0, 0); // Not compressed
+    frame.writeUInt32BE(responseBuffer.length, 1);
+    responseBuffer.copy(frame, 5);
+    this.response.write(frame);
+  }
+
+  /**
+   * End the response with gRPC status trailers.
+   * @param status - gRPC status code (0 = OK)
+   * @param message - optional status message included in grpc-message trailer
+   * @returns void
+   */
+  end(status: number = 0, message?: string): void {
+    const trailers: Record<string, string> = { "grpc-status": String(status) };
+    if (message) {
+      trailers["grpc-message"] = encodeURIComponent(message);
+    }
+    (this.response as any).addTrailers?.(trailers);
+    this.response.end();
+  }
+
+  /**
+   * Send a single unary response and close the stream.
+   * @param message - the response message to serialize and send before closing
+   * @returns void
+   */
+  sendUnary(message: ResponseType): void {
+    this.send(message);
+    this.end(0);
+  }
+
+  /**
+   * Send an error response and close the stream.
+   * @param status - gRPC status code indicating the error type
+   * @param message - human-readable error message included in grpc-message trailer
+   * @returns void
+   */
+  sendError(status: number, message: string): void {
+    this.end(status, message);
+  }
+}
+
+/** gRPC status codes */
+export const GrpcStatus = {
+  OK: 0,
+  CANCELLED: 1,
+  UNKNOWN: 2,
+  INVALID_ARGUMENT: 3,
+  DEADLINE_EXCEEDED: 4,
+  NOT_FOUND: 5,
+  ALREADY_EXISTS: 6,
+  PERMISSION_DENIED: 7,
+  RESOURCE_EXHAUSTED: 8,
+  FAILED_PRECONDITION: 9,
+  ABORTED: 10,
+  OUT_OF_RANGE: 11,
+  UNIMPLEMENTED: 12,
+  INTERNAL: 13,
+  UNAVAILABLE: 14,
+  DATA_LOSS: 15,
+  UNAUTHENTICATED: 16
+} as const;