@effect-gql/node 0.1.0

package/dist/ws.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachWebSocketToServer = exports.createGraphQLWSServer = exports.toEffectWebSocket = void 0;
+const effect_1 = require("effect");
+const ws_1 = require("ws");
+const core_1 = require("@effect-gql/core");
+/**
+ * Convert a Node.js WebSocket (from 'ws' library) to an EffectWebSocket.
+ *
+ * This creates an Effect-based wrapper around the ws WebSocket instance,
+ * providing a Stream for incoming messages and Effect-based send/close operations.
+ *
+ * @param ws - The WebSocket instance from the 'ws' library
+ * @returns An EffectWebSocket that can be used with makeGraphQLWSHandler
+ *
+ * @example
+ * ```typescript
+ * wss.on("connection", (ws, req) => {
+ *   const effectSocket = toEffectWebSocket(ws)
+ *   Effect.runPromise(handler(effectSocket))
+ * })
+ * ```
+ */
+const toEffectWebSocket = (ws) => (0, core_1.toEffectWebSocketFromWs)(ws);
+exports.toEffectWebSocket = toEffectWebSocket;
+/**
+ * Create a WebSocket server that handles GraphQL subscriptions.
+ *
+ * This function creates a WebSocketServer and returns utilities for
+ * integrating it with an HTTP server via the upgrade event.
+ *
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional configuration and lifecycle hooks
+ * @returns Object containing the WebSocketServer and handlers
+ *
+ * @example
+ * ```typescript
+ * const httpServer = createServer(requestHandler)
+ * const { wss, handleUpgrade } = createGraphQLWSServer(schema, serviceLayer)
+ *
+ * httpServer.on("upgrade", (request, socket, head) => {
+ *   if (request.url === "/graphql") {
+ *     handleUpgrade(request, socket, head)
+ *   }
+ * })
+ *
+ * httpServer.listen(4000)
+ * ```
+ */
+const createGraphQLWSServer = (schema, layer, options) => {
+    const wss = new ws_1.WebSocketServer({ noServer: true });
+    const path = options?.path ?? "/graphql";
+    // Create the handler from core
+    const handler = (0, core_1.makeGraphQLWSHandler)(schema, layer, options);
+    // Track active connections for cleanup
+    const activeConnections = new Set();
+    wss.on("connection", (ws, _request) => {
+        activeConnections.add(ws);
+        const effectSocket = (0, exports.toEffectWebSocket)(ws);
+        // Run the handler
+        effect_1.Effect.runPromise(handler(effectSocket).pipe(effect_1.Effect.catchAll((error) => effect_1.Effect.logError("GraphQL WebSocket handler error", error)))).finally(() => {
+            activeConnections.delete(ws);
+        });
+    });
+    const handleUpgrade = (request, socket, head) => {
+        // Check if this is the GraphQL WebSocket path
+        const url = new URL(request.url ?? "/", `http://${request.headers.host}`);
+        if (url.pathname !== path) {
+            socket.destroy();
+            return;
+        }
+        // Check for correct WebSocket subprotocol
+        const protocol = request.headers["sec-websocket-protocol"];
+        if (!protocol?.includes("graphql-transport-ws")) {
+            socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(request, socket, head, (ws) => {
+            wss.emit("connection", ws, request);
+        });
+    };
+    const close = async () => {
+        // Close all active connections
+        for (const ws of activeConnections) {
+            ws.close(1001, "Server shutting down");
+        }
+        activeConnections.clear();
+        // Close the WebSocket server
+        return new Promise((resolve, reject) => {
+            wss.close((error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
+    };
+    return { wss, handleUpgrade, close };
+};
+exports.createGraphQLWSServer = createGraphQLWSServer;
+/**
+ * Attach WebSocket subscription support to an existing HTTP server.
+ *
+ * This is a convenience function that creates a GraphQL WebSocket server
+ * and attaches it to an HTTP server's upgrade event.
+ *
+ * @param server - The HTTP server to attach to
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional configuration and lifecycle hooks
+ * @returns Cleanup function to close the WebSocket server
+ *
+ * @example
+ * ```typescript
+ * const httpServer = createServer(requestHandler)
+ *
+ * const cleanup = attachWebSocketToServer(httpServer, schema, serviceLayer, {
+ *   path: "/graphql",
+ * })
+ *
+ * httpServer.listen(4000)
+ *
+ * // Later, to cleanup:
+ * await cleanup()
+ * ```
+ */
+const attachWebSocketToServer = (server, schema, layer, options) => {
+    const { handleUpgrade, close } = (0, exports.createGraphQLWSServer)(schema, layer, options);
+    server.on("upgrade", (request, socket, head) => {
+        handleUpgrade(request, socket, head);
+    });
+    return { close };
+};
+exports.attachWebSocketToServer = attachWebSocketToServer;
+//# sourceMappingURL=ws.js.map

package/dist/ws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.js","sourceRoot":"","sources":["../src/ws.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@effect-gql/node",
+  "version": "0.1.0",
+  "description": "Node.js HTTP server integration for @effect-gql/core",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "@effect-gql/core": "^0.1.0",
+    "@effect/platform": "^0.94.0",
+    "@effect/platform-node": "^0.104.0",
+    "effect": "^3.19.0",
+    "graphql": "^16.0.0",
+    "ws": "^8.14.0"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@effect-gql/core": "*",
+    "@effect/platform": "^0.94.0",
+    "@effect/platform-node": "^0.104.0",
+    "effect": "^3.19.13",
+    "graphql": "^16.0.0",
+    "graphql-ws": "^6.0.6",
+    "ws": "^8.18.0",
+    "@types/ws": "^8.5.0"
+  },
+  "keywords": [
+    "effect",
+    "graphql",
+    "node",
+    "http",
+    "server"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration",
+    "test:watch": "vitest"
+  }
+}

package/src/http-utils.ts

@@ -0,0 +1,32 @@
+import type { IncomingHttpHeaders } from "node:http"
+
+/**
+ * Convert Node.js IncomingHttpHeaders to web standard Headers.
+ *
+ * This handles the difference between Node.js headers (which can be
+ * string | string[] | undefined) and web Headers (which are always strings).
+ *
+ * @param nodeHeaders - Headers from IncomingMessage.headers
+ * @returns A web standard Headers object
+ *
+ * @example
+ * ```typescript
+ * import { toWebHeaders } from "@effect-gql/node"
+ *
+ * const webHeaders = toWebHeaders(req.headers)
+ * const auth = webHeaders.get("authorization")
+ * ```
+ */
+export const toWebHeaders = (nodeHeaders: IncomingHttpHeaders): Headers => {
+  const headers = new Headers()
+  for (const [key, value] of Object.entries(nodeHeaders)) {
+    if (value) {
+      if (Array.isArray(value)) {
+        value.forEach((v) => headers.append(key, v))
+      } else {
+        headers.set(key, value)
+      }
+    }
+  }
+  return headers
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export { serve, type ServeOptions } from "./serve"
+
+// HTTP utilities
+export { toWebHeaders } from "./http-utils"
+
+// WebSocket subscription support
+export {
+  toEffectWebSocket,
+  createGraphQLWSServer,
+  attachWebSocketToServer,
+  type NodeWSOptions,
+} from "./ws"
+
+// SSE (Server-Sent Events) subscription support
+export { createSSEHandler, createSSEServer, type NodeSSEOptions } from "./sse"

package/src/serve.ts

@@ -0,0 +1,217 @@
+import { Effect, Layer } from "effect"
+import { HttpApp, HttpRouter, HttpServer } from "@effect/platform"
+import { NodeHttpServer, NodeRuntime } from "@effect/platform-node"
+import { createServer } from "node:http"
+import type { GraphQLSchema } from "graphql"
+import type { GraphQLWSOptions } from "@effect-gql/core"
+import { toWebHeaders } from "./http-utils"
+
+/**
+ * Configuration for WebSocket subscriptions
+ */
+export interface SubscriptionsConfig<R> extends GraphQLWSOptions<R> {
+  /**
+   * The GraphQL schema (required for subscriptions).
+   * Must be the same schema used to create the router.
+   */
+  readonly schema: GraphQLSchema
+  /**
+   * Path for WebSocket connections.
+   * @default "/graphql"
+   */
+  readonly path?: string
+}
+
+/**
+ * Options for the Node.js GraphQL server
+ */
+export interface ServeOptions<R = never> {
+  /** Port to listen on (default: 4000) */
+  readonly port?: number
+  /** Hostname to bind to (default: "0.0.0.0") */
+  readonly host?: string
+  /** Callback when server starts */
+  readonly onStart?: (url: string) => void
+  /**
+   * Enable WebSocket subscriptions.
+   * When provided, the server will handle WebSocket upgrade requests
+   * for GraphQL subscriptions using the graphql-ws protocol.
+   */
+  readonly subscriptions?: SubscriptionsConfig<R>
+}
+
+/**
+ * Start a Node.js HTTP server with the given router.
+ *
+ * This is the main entry point for running a GraphQL server on Node.js.
+ * It handles all the Effect runtime setup and server lifecycle.
+ *
+ * @param router - The HttpRouter to serve (typically from makeGraphQLRouter or toRouter)
+ * @param layer - Layer providing the router's service dependencies
+ * @param options - Server configuration options
+ *
+ * @example
+ * ```typescript
+ * import { makeGraphQLRouter } from "@effect-gql/core"
+ * import { serve } from "@effect-gql/node"
+ *
+ * const schema = GraphQLSchemaBuilder.empty
+ *   .query("hello", { type: S.String, resolve: () => Effect.succeed("world") })
+ *   .buildSchema()
+ *
+ * const router = makeGraphQLRouter(schema, Layer.empty, { graphiql: true })
+ *
+ * // Without subscriptions
+ * serve(router, serviceLayer, {
+ *   port: 4000,
+ *   onStart: (url) => console.log(`Server running at ${url}`)
+ * })
+ *
+ * // With subscriptions
+ * serve(router, serviceLayer, {
+ *   port: 4000,
+ *   subscriptions: { schema },
+ *   onStart: (url) => console.log(`Server running at ${url}`)
+ * })
+ * ```
+ */
+export const serve = <E, R, RE>(
+  router: HttpRouter.HttpRouter<E, R>,
+  layer: Layer.Layer<R, RE>,
+  options: ServeOptions<R> = {}
+): void => {
+  const { port = 4000, host = "0.0.0.0", onStart, subscriptions } = options
+
+  if (subscriptions) {
+    // With WebSocket subscriptions - we need to manage the HTTP server ourselves
+    serveWithSubscriptions(router, layer, port, host, subscriptions, onStart)
+  } else {
+    // Without subscriptions - use the standard Effect approach
+    const app = router.pipe(
+      Effect.catchAllCause((cause) => Effect.die(cause)),
+      HttpServer.serve()
+    )
+
+    const serverLayer = NodeHttpServer.layer(() => createServer(), { port })
+    const fullLayer = Layer.merge(serverLayer, layer)
+
+    if (onStart) {
+      onStart(`http://${host === "0.0.0.0" ? "localhost" : host}:${port}`)
+    }
+
+    NodeRuntime.runMain(Layer.launch(Layer.provide(app, fullLayer)))
+  }
+}
+
+/**
+ * Internal implementation for serving with WebSocket subscriptions.
+ * Uses a custom HTTP server setup to enable WebSocket upgrade handling.
+ */
+function serveWithSubscriptions<E, R, RE>(
+  router: HttpRouter.HttpRouter<E, R>,
+  layer: Layer.Layer<R, RE>,
+  port: number,
+  host: string,
+  subscriptions: SubscriptionsConfig<R>,
+  onStart?: (url: string) => void
+): void {
+  // Dynamically import ws module to keep it optional
+  const importWs = Effect.tryPromise({
+    try: () => import("./ws"),
+    catch: (error) => error as Error,
+  })
+
+  Effect.runPromise(
+    importWs.pipe(
+      Effect.catchAll((error) =>
+        Effect.logError("Failed to load WebSocket support", error).pipe(
+          Effect.andThen(Effect.logError("Make sure 'ws' package is installed: npm install ws")),
+          Effect.andThen(Effect.sync(() => process.exit(1))),
+          Effect.andThen(Effect.fail(error))
+        )
+      )
+    )
+  ).then(({ createGraphQLWSServer }) => {
+    // Create the web handler from the Effect router
+    const { handler } = HttpApp.toWebHandlerLayer(router, layer)
+
+    // Create the HTTP server
+    const httpServer = createServer(async (req, res) => {
+      try {
+        // Collect request body
+        const chunks: Buffer[] = []
+        for await (const chunk of req) {
+          chunks.push(chunk as Buffer)
+        }
+        const body = Buffer.concat(chunks).toString()
+
+        // Convert Node.js request to web standard Request
+        // Use URL constructor for safe URL parsing (avoids injection via req.url)
+        const baseUrl = `http://${host === "0.0.0.0" ? "localhost" : host}:${port}`
+        const url = new URL(req.url || "/", baseUrl).href
+        const headers = toWebHeaders(req.headers)
+
+        const webRequest = new Request(url, {
+          method: req.method,
+          headers,
+          body: ["GET", "HEAD"].includes(req.method!) ? undefined : body,
+        })
+
+        // Process through Effect handler
+        const webResponse = await handler(webRequest)
+
+        // Write response
+        res.statusCode = webResponse.status
+        webResponse.headers.forEach((value, key) => {
+          res.setHeader(key, value)
+        })
+        const responseBody = await webResponse.text()
+        res.end(responseBody)
+      } catch (error) {
+        res.statusCode = 500
+        res.end(JSON.stringify({ error: String(error) }))
+      }
+    })
+
+    // Create WebSocket server for subscriptions
+    const { handleUpgrade, close: closeWS } = createGraphQLWSServer(
+      subscriptions.schema,
+      layer as Layer.Layer<R>,
+      {
+        path: subscriptions.path,
+        complexity: subscriptions.complexity,
+        fieldComplexities: subscriptions.fieldComplexities,
+        onConnect: subscriptions.onConnect,
+        onDisconnect: subscriptions.onDisconnect,
+        onSubscribe: subscriptions.onSubscribe,
+        onComplete: subscriptions.onComplete,
+        onError: subscriptions.onError,
+      }
+    )
+
+    // Attach WebSocket upgrade handler
+    httpServer.on("upgrade", (request, socket, head) => {
+      handleUpgrade(request, socket, head)
+    })
+
+    // Handle shutdown
+    process.on("SIGINT", async () => {
+      await closeWS()
+      httpServer.close()
+      process.exit(0)
+    })
+
+    process.on("SIGTERM", async () => {
+      await closeWS()
+      httpServer.close()
+      process.exit(0)
+    })
+
+    // Start listening
+    httpServer.listen(port, host, () => {
+      if (onStart) {
+        onStart(`http://${host === "0.0.0.0" ? "localhost" : host}:${port}`)
+      }
+    })
+  })
+}

package/src/sse.ts

@@ -0,0 +1,234 @@
+import { Effect, Layer, Stream, Deferred } from "effect"
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { GraphQLSchema } from "graphql"
+import {
+  makeGraphQLSSEHandler,
+  formatSSEMessage,
+  SSE_HEADERS,
+  type GraphQLSSEOptions,
+  type SSESubscriptionRequest,
+  SSEError,
+} from "@effect-gql/core"
+import { toWebHeaders } from "./http-utils"
+
+/**
+ * Options for Node.js SSE handler
+ */
+export interface NodeSSEOptions<R> extends GraphQLSSEOptions<R> {
+  /**
+   * Path for SSE connections.
+   * @default "/graphql/stream"
+   */
+  readonly path?: string
+}
+
+/**
+ * Create an SSE handler for Node.js HTTP server.
+ *
+ * This function creates a handler that can process SSE subscription requests.
+ * It handles:
+ * - Parsing the GraphQL subscription request from the HTTP body
+ * - Setting up the SSE connection with proper headers
+ * - Streaming subscription events to the client
+ * - Detecting client disconnection and cleaning up
+ *
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional lifecycle hooks and configuration
+ * @returns A request handler function
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from "node:http"
+ * import { createSSEHandler } from "@effect-gql/node"
+ *
+ * const sseHandler = createSSEHandler(schema, serviceLayer, {
+ *   path: "/graphql/stream",
+ *   onConnect: (request, headers) => Effect.gen(function* () {
+ *     const user = yield* AuthService.validateToken(headers.get("authorization"))
+ *     return { user }
+ *   }),
+ * })
+ *
+ * const server = createServer((req, res) => {
+ *   const url = new URL(req.url, `http://${req.headers.host}`)
+ *   if (url.pathname === "/graphql/stream" && req.method === "POST") {
+ *     sseHandler(req, res)
+ *   } else {
+ *     // Handle other requests...
+ *   }
+ * })
+ *
+ * server.listen(4000)
+ * ```
+ */
+export const createSSEHandler = <R>(
+  schema: GraphQLSchema,
+  layer: Layer.Layer<R>,
+  options?: NodeSSEOptions<R>
+): ((req: IncomingMessage, res: ServerResponse) => Promise<void>) => {
+  const sseHandler = makeGraphQLSSEHandler(schema, layer, options)
+
+  return async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    // Check Accept header for SSE support
+    const accept = req.headers.accept ?? ""
+    if (!accept.includes("text/event-stream") && !accept.includes("*/*")) {
+      res.statusCode = 406
+      res.end(
+        JSON.stringify({
+          errors: [{ message: "Client must accept text/event-stream" }],
+        })
+      )
+      return
+    }
+
+    // Read the request body
+    let body: string
+    try {
+      body = await readBody(req)
+    } catch {
+      res.statusCode = 400
+      res.end(
+        JSON.stringify({
+          errors: [{ message: "Failed to read request body" }],
+        })
+      )
+      return
+    }
+
+    // Parse the GraphQL request
+    let request: SSESubscriptionRequest
+    try {
+      const parsed = JSON.parse(body)
+      if (typeof parsed.query !== "string") {
+        throw new Error("Missing query")
+      }
+      request = {
+        query: parsed.query,
+        variables: parsed.variables,
+        operationName: parsed.operationName,
+        extensions: parsed.extensions,
+      }
+    } catch {
+      res.statusCode = 400
+      res.end(
+        JSON.stringify({
+          errors: [{ message: "Invalid GraphQL request body" }],
+        })
+      )
+      return
+    }
+
+    // Convert Node.js headers to web Headers
+    const headers = toWebHeaders(req.headers)
+
+    // Set SSE headers
+    res.writeHead(200, SSE_HEADERS)
+
+    // Get the event stream
+    const eventStream = sseHandler(request, headers)
+
+    // Create the streaming effect
+    const streamEffect = Effect.gen(function* () {
+      // Track client disconnection
+      const clientDisconnected = yield* Deferred.make<void, SSEError>()
+
+      req.on("close", () => {
+        Effect.runPromise(Deferred.succeed(clientDisconnected, undefined)).catch(() => {})
+      })
+
+      req.on("error", (error) => {
+        Effect.runPromise(Deferred.fail(clientDisconnected, new SSEError({ cause: error }))).catch(
+          () => {}
+        )
+      })
+
+      // Stream events to the client
+      const runStream = Stream.runForEach(eventStream, (event) =>
+        Effect.async<void, SSEError>((resume) => {
+          const message = formatSSEMessage(event)
+          res.write(message, (error) => {
+            if (error) {
+              resume(Effect.fail(new SSEError({ cause: error })))
+            } else {
+              resume(Effect.succeed(undefined))
+            }
+          })
+        })
+      )
+
+      // Race between stream completion and client disconnection
+      yield* Effect.race(
+        runStream.pipe(Effect.catchAll((error) => Effect.logWarning("SSE stream error", error))),
+        Deferred.await(clientDisconnected)
+      )
+    })
+
+    await Effect.runPromise(
+      streamEffect.pipe(
+        Effect.ensuring(Effect.sync(() => res.end())),
+        Effect.catchAll(() => Effect.void)
+      )
+    )
+  }
+}
+
+/**
+ * Read the request body as a string.
+ */
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    req.on("data", (chunk: Buffer) => chunks.push(chunk))
+    req.on("end", () => resolve(Buffer.concat(chunks).toString()))
+    req.on("error", reject)
+  })
+}
+
+/**
+ * Create SSE middleware that can be used with the serve() function.
+ *
+ * This returns an object that can be used to integrate SSE subscriptions
+ * with the HTTP server when using the custom subscription mode.
+ *
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional lifecycle hooks and configuration
+ *
+ * @example
+ * ```typescript
+ * // In serve.ts with custom HTTP server setup
+ * const sseServer = createSSEServer(schema, layer, { path: "/graphql/stream" })
+ *
+ * httpServer.on("request", (req, res) => {
+ *   if (sseServer.shouldHandle(req)) {
+ *     sseServer.handle(req, res)
+ *   }
+ * })
+ * ```
+ */
+export const createSSEServer = <R>(
+  schema: GraphQLSchema,
+  layer: Layer.Layer<R>,
+  options?: NodeSSEOptions<R>
+): {
+  /** Path this SSE server handles */
+  readonly path: string
+  /** Check if a request should be handled by this SSE server */
+  shouldHandle: (req: IncomingMessage) => boolean
+  /** Handle an SSE request */
+  handle: (req: IncomingMessage, res: ServerResponse) => Promise<void>
+} => {
+  const path = options?.path ?? "/graphql/stream"
+  const handler = createSSEHandler(schema, layer, options)
+
+  return {
+    path,
+    shouldHandle: (req: IncomingMessage) => {
+      if (req.method !== "POST") return false
+      const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`)
+      return url.pathname === path
+    },
+    handle: handler,
+  }
+}