@spikard/node 0.11.0 → 0.13.0

package/dist/index.mjs

@@ -548,6 +548,8 @@ var Spikard = class {
   handlers = {};
   websocketRoutes = [];
   websocketHandlers = {};
+  grpcMethods = [];
+  grpcHandlers = {};
   lifecycleHooks = {
     onRequest: [],
     preValidation: [],
@@ -591,13 +593,111 @@ var Spikard = class {
     this.websocketRoutes.push(route2);
     this.websocketHandlers[handlerName] = handlerWrapper;
   }
+  /**
+   * Register a unary gRPC method on the application.
+   *
+   * @param serviceName - Fully-qualified service name
+   * @param methodName - gRPC method name
+   * @param handler - gRPC handler implementation
+   * @returns The application for chaining
+   */
+  addGrpcUnary(serviceName, methodName, handler) {
+    if (typeof handler?.handleRequest !== "function") {
+      throw new TypeError("Unary handler must implement handleRequest(request)");
+    }
+    return this.registerGrpcMethod(serviceName, methodName, "unary", {
+      handleRequest: (request) => handler.handleRequest(request)
+    });
+  }
+  addGrpcServerStreaming(serviceName, methodName, handler) {
+    if (typeof handler?.handleServerStream !== "function") {
+      throw new TypeError("Server-streaming handler must implement handleServerStream(request)");
+    }
+    return this.registerGrpcMethod(serviceName, methodName, "serverStreaming", {
+      handleServerStream: (request) => handler.handleServerStream(request)
+    });
+  }
+  addGrpcClientStreaming(serviceName, methodName, handler) {
+    if (typeof handler?.handleClientStream !== "function") {
+      throw new TypeError("Client-streaming handler must implement handleClientStream(request)");
+    }
+    return this.registerGrpcMethod(serviceName, methodName, "clientStreaming", {
+      handleClientStream: (request) => handler.handleClientStream(request)
+    });
+  }
+  addGrpcBidirectionalStreaming(serviceName, methodName, handler) {
+    if (typeof handler?.handleBidiStream !== "function") {
+      throw new TypeError("Bidirectional-streaming handler must implement handleBidiStream(request)");
+    }
+    return this.registerGrpcMethod(serviceName, methodName, "bidirectionalStreaming", {
+      handleBidiStream: (request) => handler.handleBidiStream(request)
+    });
+  }
+  registerGrpcMethod(serviceName, methodName, rpcMode, handlerWrapper) {
+    if (!serviceName) {
+      throw new Error("Service name cannot be empty");
+    }
+    if (!methodName) {
+      throw new Error("Method name cannot be empty");
+    }
+    const previous = this.grpcMethods.find(
+      (entry) => entry.serviceName === serviceName && entry.methodName === methodName
+    );
+    if (previous) {
+      delete this.grpcHandlers[previous.handlerName];
+    }
+    const handlerName = `grpc_${this.grpcMethods.length}_${serviceName}_${methodName}`.replace(/[^a-zA-Z0-9_]/g, "_");
+    this.grpcHandlers[handlerName] = handlerWrapper;
+    this.grpcMethods = this.grpcMethods.filter(
+      (entry) => !(entry.serviceName === serviceName && entry.methodName === methodName)
+    );
+    this.grpcMethods.push({ serviceName, methodName, rpcMode, handlerName });
+    return this;
+  }
+  /**
+   * Mount all handlers from a gRPC service registry on the application.
+   *
+   * @param service - Registry containing one or more service methods
+   * @returns The application for chaining
+   */
+  useGrpc(service) {
+    for (const method of service.entries()) {
+      switch (method.rpcMode) {
+        case "unary":
+          this.addGrpcUnary(method.serviceName, method.methodName, method.handler);
+          break;
+        case "serverStreaming":
+          this.addGrpcServerStreaming(
+            method.serviceName,
+            method.methodName,
+            method.handler
+          );
+          break;
+        case "clientStreaming":
+          this.addGrpcClientStreaming(
+            method.serviceName,
+            method.methodName,
+            method.handler
+          );
+          break;
+        case "bidirectionalStreaming":
+          this.addGrpcBidirectionalStreaming(
+            method.serviceName,
+            method.methodName,
+            method.handler
+          );
+          break;
+      }
+    }
+    return this;
+  }
   /**
    * Run the server
    *
-   * @param options - Server configuration
+   * @param config - Server configuration
    */
-  run(options = {}) {
-    runServer(this, options);
+  run(config = {}) {
+    runServer(this, config);
   }
   /**
    * Register an onRequest lifecycle hook
@@ -823,6 +923,135 @@ var GrpcError = class extends Error {
     this.name = "GrpcError";
   }
 };
+var GrpcService = class {
+  methods = /* @__PURE__ */ new Map();
+  methodKey(serviceName, methodName) {
+    return `${serviceName}/${methodName}`;
+  }
+  registerMethod(config) {
+    if (!config.serviceName) {
+      throw new Error("Service name cannot be empty");
+    }
+    if (!config.methodName) {
+      throw new Error("Method name cannot be empty");
+    }
+    switch (config.rpcMode) {
+      case "unary":
+        if (typeof config.handler?.handleRequest !== "function") {
+          throw new TypeError("Unary handler must implement handleRequest(request)");
+        }
+        break;
+      case "serverStreaming":
+        if (typeof config.handler?.handleServerStream !== "function") {
+          throw new TypeError("Server-streaming handler must implement handleServerStream(request)");
+        }
+        break;
+      case "clientStreaming":
+        if (typeof config.handler?.handleClientStream !== "function") {
+          throw new TypeError("Client-streaming handler must implement handleClientStream(request)");
+        }
+        break;
+      case "bidirectionalStreaming":
+        if (typeof config.handler?.handleBidiStream !== "function") {
+          throw new TypeError("Bidirectional-streaming handler must implement handleBidiStream(request)");
+        }
+        break;
+    }
+    this.methods.set(this.methodKey(config.serviceName, config.methodName), config);
+    return this;
+  }
+  /**
+   * Register a unary handler for a fully-qualified service method.
+   *
+   * @param serviceName - Service name such as `mypackage.UserService`
+   * @param methodName - Method name such as `GetUser`
+   * @param handler - Handler implementation for that method
+   * @returns The registry for chaining
+   */
+  registerUnary(serviceName, methodName, handler) {
+    return this.registerMethod({ serviceName, methodName, rpcMode: "unary", handler });
+  }
+  registerServerStreaming(serviceName, methodName, handler) {
+    return this.registerMethod({ serviceName, methodName, rpcMode: "serverStreaming", handler });
+  }
+  registerClientStreaming(serviceName, methodName, handler) {
+    return this.registerMethod({ serviceName, methodName, rpcMode: "clientStreaming", handler });
+  }
+  registerBidirectionalStreaming(serviceName, methodName, handler) {
+    return this.registerMethod({ serviceName, methodName, rpcMode: "bidirectionalStreaming", handler });
+  }
+  /**
+   * Remove a handler from the registry.
+   *
+   * @param serviceName - Fully-qualified service name
+   * @param methodName - Method name
+   */
+  unregister(serviceName, methodName) {
+    if (!this.methods.delete(this.methodKey(serviceName, methodName))) {
+      throw new Error(`No handler registered for method: ${serviceName}/${methodName}`);
+    }
+  }
+  /**
+   * Get the registration for a service method.
+   *
+   * @param serviceName - Fully-qualified service name
+   * @param methodName - Method name
+   * @returns The registered method configuration, if present
+   */
+  getMethod(serviceName, methodName) {
+    return this.methods.get(this.methodKey(serviceName, methodName));
+  }
+  /**
+   * List all registered service names.
+   *
+   * @returns Fully-qualified service names
+   */
+  serviceNames() {
+    return Array.from(new Set(Array.from(this.methods.values(), (entry) => entry.serviceName)));
+  }
+  methodNames(serviceName) {
+    return Array.from(this.methods.values()).filter((entry) => entry.serviceName === serviceName).map((entry) => entry.methodName);
+  }
+  /**
+   * Check whether a specific service method is registered.
+   *
+   * @param serviceName - Fully-qualified service name
+   * @param methodName - Method name
+   * @returns True when a handler is registered for the method
+   */
+  hasMethod(serviceName, methodName) {
+    return this.methods.has(this.methodKey(serviceName, methodName));
+  }
+  /**
+   * Return registered method entries.
+   */
+  entries() {
+    return Array.from(this.methods.values());
+  }
+  /**
+   * Route a unary request to the registered method handler.
+   *
+   * @param request - Incoming gRPC request
+   * @returns Promise resolving to the handler response
+   * @throws GrpcError when no service is registered
+   */
+  async handleRequest(request) {
+    const method = this.getMethod(request.serviceName, request.methodName);
+    if (!method) {
+      throw new GrpcError(
+        12 /* UNIMPLEMENTED */,
+        `No handler registered for method: ${request.serviceName}/${request.methodName}`
+      );
+    }
+    if (method.rpcMode !== "unary") {
+      throw new GrpcError(
+        12 /* UNIMPLEMENTED */,
+        `Method ${request.serviceName}/${request.methodName} is registered as ${method.rpcMode}`
+      );
+    }
+    return method.handler.handleRequest(request);
+  }
+};
 function createUnaryHandler(methodName, handler, requestType, responseType) {
   return {
     async handleRequest(request) {
@@ -903,6 +1132,36 @@ import fs from "fs/promises";
 import { createRequire as createRequire3 } from "module";
 import path from "path";
 import { gunzipSync, gzipSync } from "zlib";
+var GRAPHQL_WS_TIMEOUT_MS = 2e3;
+var GRAPHQL_WS_MAX_CONTROL_MESSAGES = 32;
+var withTimeout = async (promise, timeoutMs, context) => {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`Timed out waiting for ${context}`)), timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+};
+var decodeGraphqlWsMessage = (value) => {
+  if (typeof value === "string") {
+    const parsed = JSON.parse(value);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    throw new Error("Expected GraphQL WebSocket JSON object message");
+  }
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  throw new Error("Expected GraphQL WebSocket message object");
+};
 var MockWebSocketConnection = class {
   handler;
   queue = [];
@@ -1616,6 +1875,107 @@ var TestClient = class {
       bodyText: response.text()
     };
   }
+  /**
+   * Send a GraphQL subscription over WebSocket and return the first event payload.
+   */
+  async graphqlSubscription(query, variables, operationName, path2 = "/graphql") {
+    const operationId = "spikard-subscription-1";
+    const subscriptionPayload = { query };
+    if (variables !== null && variables !== void 0) {
+      subscriptionPayload.variables = variables;
+    }
+    if (operationName !== null && operationName !== void 0) {
+      subscriptionPayload.operationName = operationName;
+    }
+    const ws = await this.websocketConnect(path2);
+    try {
+      await ws.sendJson({ type: "connection_init" });
+      let acknowledged = false;
+      for (let i = 0; i < GRAPHQL_WS_MAX_CONTROL_MESSAGES; i++) {
+        const message = decodeGraphqlWsMessage(
+          await withTimeout(ws.receiveJson(), GRAPHQL_WS_TIMEOUT_MS, "GraphQL connection_ack")
+        );
+        const messageType = typeof message.type === "string" ? message.type : "";
+        if (messageType === "connection_ack") {
+          acknowledged = true;
+          break;
+        }
+        if (messageType === "ping") {
+          const pong = { type: "pong" };
+          if ("payload" in message) {
+            pong.payload = message.payload;
+          }
+          await ws.sendJson(pong);
+          continue;
+        }
+        if (messageType === "connection_error" || messageType === "error") {
+          throw new Error(`GraphQL subscription rejected during init: ${JSON.stringify(message)}`);
+        }
+      }
+      if (!acknowledged) {
+        throw new Error("No GraphQL connection_ack received");
+      }
+      await ws.sendJson({
+        id: operationId,
+        type: "subscribe",
+        payload: subscriptionPayload
+      });
+      let event = null;
+      const errors = [];
+      let completeReceived = false;
+      for (let i = 0; i < GRAPHQL_WS_MAX_CONTROL_MESSAGES; i++) {
+        const message = decodeGraphqlWsMessage(
+          await withTimeout(ws.receiveJson(), GRAPHQL_WS_TIMEOUT_MS, "GraphQL subscription message")
+        );
+        const messageType = typeof message.type === "string" ? message.type : "";
+        const messageId = typeof message.id === "string" ? message.id : void 0;
+        const idMatches = messageId === void 0 || messageId === operationId;
+        if (messageType === "next" && idMatches) {
+          event = "payload" in message ? message.payload : null;
+          await ws.sendJson({ id: operationId, type: "complete" });
+          try {
+            const maybeComplete = decodeGraphqlWsMessage(
+              await withTimeout(ws.receiveJson(), GRAPHQL_WS_TIMEOUT_MS, "GraphQL complete message")
+            );
+            const completeType = typeof maybeComplete.type === "string" ? maybeComplete.type : "";
+            const completeId = typeof maybeComplete.id === "string" ? maybeComplete.id : void 0;
+            if (completeType === "complete" && (completeId === void 0 || completeId === operationId)) {
+              completeReceived = true;
+            }
+          } catch {
+          }
+          break;
+        }
+        if (messageType === "error") {
+          errors.push("payload" in message ? message.payload : message);
+          break;
+        }
+        if (messageType === "complete" && idMatches) {
+          completeReceived = true;
+          break;
+        }
+        if (messageType === "ping") {
+          const pong = { type: "pong" };
+          if ("payload" in message) {
+            pong.payload = message.payload;
+          }
+          await ws.sendJson(pong);
+        }
+      }
+      if (event === null && errors.length === 0 && !completeReceived) {
+        throw new Error("No GraphQL subscription event received before timeout");
+      }
+      return {
+        operationId,
+        acknowledged,
+        event,
+        errors,
+        completeReceived
+      };
+    } finally {
+      await ws.close();
+    }
+  }
   /**
    * Cleanup resources when test client is done
    */
@@ -1624,6 +1984,7 @@ var TestClient = class {
 };
 export {
   GrpcError,
+  GrpcService,
   GrpcStatusCode,
   Spikard,
   StreamingResponse,