@effect-gql/core 0.1.0

package/src/server/sse-adapter.ts

@@ -0,0 +1,327 @@
+import { Effect, Layer, Stream } from "effect"
+import {
+  GraphQLSchema,
+  parse,
+  validate,
+  subscribe,
+  GraphQLError,
+  Kind,
+  type ExecutionResult,
+  type DocumentNode,
+  type OperationDefinitionNode,
+} from "graphql"
+import type { GraphQLEffectContext } from "../builder/types"
+import {
+  SSEError,
+  type GraphQLSSEOptions,
+  type SSEConnectionContext,
+  type SSESubscriptionRequest,
+  type SSEEvent,
+  formatNextEvent,
+  formatErrorEvent,
+  formatCompleteEvent,
+} from "./sse-types"
+import { validateComplexity, type FieldComplexityMap } from "./complexity"
+
+/**
+ * Create a subscription event stream for SSE.
+ *
+ * This function handles the GraphQL subscription lifecycle:
+ * 1. Parse and validate the query
+ * 2. Check complexity limits if configured
+ * 3. Execute the subscription
+ * 4. Stream results as SSE events
+ *
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param request - The subscription request (query, variables, operationName)
+ * @param headers - HTTP headers from the request (for auth)
+ * @param options - Optional lifecycle hooks and configuration
+ * @returns A Stream of SSE events to send to the client
+ *
+ * @example
+ * ```typescript
+ * const eventStream = makeSSESubscriptionStream(
+ *   schema,
+ *   serviceLayer,
+ *   { query: "subscription { tick { count } }" },
+ *   new Headers(),
+ *   { onConnect: (req, headers) => Effect.succeed({ user: "alice" }) }
+ * )
+ *
+ * // In platform-specific code, consume and send events:
+ * Stream.runForEach(eventStream, (event) =>
+ *   Effect.sync(() => res.write(formatSSEMessage(event)))
+ * )
+ * ```
+ */
+export const makeSSESubscriptionStream = <R>(
+  schema: GraphQLSchema,
+  layer: Layer.Layer<R>,
+  request: SSESubscriptionRequest,
+  headers: Headers,
+  options?: GraphQLSSEOptions<R>
+): Stream.Stream<SSEEvent, SSEError> => {
+  const complexityConfig = options?.complexity
+  const fieldComplexities: FieldComplexityMap = options?.fieldComplexities ?? new Map()
+
+  return Stream.unwrap(
+    Effect.gen(function* () {
+      // Create a runtime from the layer
+      const runtime = yield* Effect.provide(Effect.runtime<R>(), layer)
+
+      // Run onConnect hook if provided
+      let connectionContext: Record<string, unknown> = {}
+      if (options?.onConnect) {
+        try {
+          connectionContext = yield* Effect.provide(options.onConnect(request, headers), layer)
+        } catch {
+          // Connection rejected
+          return Stream.make(
+            formatErrorEvent([
+              new GraphQLError("Subscription connection rejected", {
+                extensions: { code: "CONNECTION_REJECTED" },
+              }),
+            ]),
+            formatCompleteEvent()
+          )
+        }
+      }
+
+      // Parse the query
+      let document: DocumentNode
+      try {
+        document = parse(request.query)
+      } catch (syntaxError) {
+        return Stream.make(formatErrorEvent([syntaxError]), formatCompleteEvent())
+      }
+
+      // Validate the query
+      const validationErrors = validate(schema, document)
+      if (validationErrors.length > 0) {
+        return Stream.make(formatErrorEvent(validationErrors), formatCompleteEvent())
+      }
+
+      // Find the subscription operation
+      const operations = document.definitions.filter(
+        (d): d is OperationDefinitionNode => d.kind === Kind.OPERATION_DEFINITION
+      )
+
+      const operation = request.operationName
+        ? operations.find((o) => o.name?.value === request.operationName)
+        : operations[0]
+
+      if (!operation) {
+        return Stream.make(
+          formatErrorEvent([new GraphQLError("No operation found in query")]),
+          formatCompleteEvent()
+        )
+      }
+
+      if (operation.operation !== "subscription") {
+        return Stream.make(
+          formatErrorEvent([
+            new GraphQLError(
+              `SSE endpoint only supports subscriptions, received: ${operation.operation}`,
+              { extensions: { code: "OPERATION_NOT_SUPPORTED" } }
+            ),
+          ]),
+          formatCompleteEvent()
+        )
+      }
+
+      // Validate complexity if configured
+      if (complexityConfig) {
+        const complexityResult = yield* validateComplexity(
+          request.query,
+          request.operationName,
+          request.variables,
+          schema,
+          fieldComplexities,
+          complexityConfig
+        ).pipe(
+          Effect.map(() => null),
+          Effect.catchAll((error) => {
+            if (error._tag === "ComplexityLimitExceededError") {
+              return Effect.succeed(
+                new GraphQLError(error.message, {
+                  extensions: {
+                    code: "COMPLEXITY_LIMIT_EXCEEDED",
+                    limitType: error.limitType,
+                    limit: error.limit,
+                    actual: error.actual,
+                  },
+                })
+              )
+            }
+            // Log analysis errors but don't block (fail open)
+            return Effect.logWarning("Complexity analysis failed for SSE subscription", error).pipe(
+              Effect.map(() => null)
+            )
+          })
+        )
+
+        if (complexityResult) {
+          return Stream.make(formatErrorEvent([complexityResult]), formatCompleteEvent())
+        }
+      }
+
+      // Build the context for the subscription
+      const ctx: SSEConnectionContext<R> = {
+        runtime,
+        request,
+        connectionContext,
+      }
+
+      // Call onSubscribe hook if provided
+      if (options?.onSubscribe) {
+        yield* Effect.provide(options.onSubscribe(ctx), layer).pipe(
+          Effect.catchAll(() => Effect.void)
+        )
+      }
+
+      // Execute the subscription
+      const graphqlContext: GraphQLEffectContext<R> & Record<string, unknown> = {
+        runtime,
+        ...connectionContext,
+      }
+
+      const subscriptionResult = yield* Effect.tryPromise({
+        try: () =>
+          subscribe({
+            schema,
+            document,
+            variableValues: request.variables,
+            operationName: request.operationName ?? undefined,
+            contextValue: graphqlContext,
+          }),
+        catch: (error) => new SSEError({ cause: error }),
+      })
+
+      // Check if subscribe returned an error result instead of async iterator
+      if (!isAsyncIterable(subscriptionResult)) {
+        // It's an ExecutionResult with errors
+        const result = subscriptionResult as ExecutionResult
+        if (result.errors) {
+          return Stream.make(formatErrorEvent(result.errors), formatCompleteEvent())
+        }
+        // Shouldn't happen, but handle gracefully
+        return Stream.make(formatNextEvent(result), formatCompleteEvent())
+      }
+
+      // Create a stream from the async iterator
+      const asyncIterator = subscriptionResult[Symbol.asyncIterator]()
+
+      const eventStream = Stream.async<SSEEvent, SSEError>((emit) => {
+        let done = false
+
+        const iterate = async () => {
+          try {
+            while (!done) {
+              const result = await asyncIterator.next()
+              if (result.done) {
+                emit.end()
+                break
+              }
+              emit.single(formatNextEvent(result.value))
+            }
+          } catch (error) {
+            if (!done) {
+              emit.single(
+                formatErrorEvent([
+                  error instanceof GraphQLError
+                    ? error
+                    : new GraphQLError(
+                        error instanceof Error ? error.message : "Subscription error",
+                        { extensions: { code: "SUBSCRIPTION_ERROR" } }
+                      ),
+                ])
+              )
+              emit.end()
+            }
+          }
+        }
+
+        iterate()
+
+        // Return cleanup function
+        return Effect.sync(() => {
+          done = true
+          asyncIterator.return?.()
+        })
+      })
+
+      // Add complete event at the end and handle cleanup
+      return eventStream.pipe(
+        Stream.onDone(() =>
+          Effect.gen(function* () {
+            yield* Effect.sync(() => {})
+          }).pipe(Effect.asVoid)
+        ),
+        Stream.concat(Stream.make(formatCompleteEvent())),
+        Stream.onDone(() => {
+          if (options?.onComplete) {
+            return Effect.provide(options.onComplete(ctx), layer).pipe(
+              Effect.catchAll(() => Effect.void)
+            )
+          }
+          return Effect.void
+        })
+      )
+    }).pipe(
+      Effect.catchAll((error) =>
+        Effect.succeed(
+          Stream.make(
+            formatErrorEvent([
+              new GraphQLError(error instanceof Error ? error.message : "Internal error", {
+                extensions: { code: "INTERNAL_ERROR" },
+              }),
+            ]),
+            formatCompleteEvent()
+          )
+        )
+      )
+    )
+  )
+}
+
+/**
+ * Create an SSE subscription handler that can be used with platform-specific servers.
+ *
+ * This is a higher-level API that returns a handler function. The handler
+ * takes a request and headers, and returns a Stream of SSE events.
+ *
+ * @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 handler function for SSE subscription requests
+ *
+ * @example
+ * ```typescript
+ * const handler = makeGraphQLSSEHandler(schema, serviceLayer, {
+ *   onConnect: (request, headers) => Effect.gen(function* () {
+ *     const token = headers.get("authorization")
+ *     const user = yield* AuthService.validateToken(token)
+ *     return { user }
+ *   }),
+ * })
+ *
+ * // In platform-specific code:
+ * const events = handler(request, headers)
+ * // Stream events to client...
+ * ```
+ */
+export const makeGraphQLSSEHandler = <R>(
+  schema: GraphQLSchema,
+  layer: Layer.Layer<R>,
+  options?: GraphQLSSEOptions<R>
+): ((request: SSESubscriptionRequest, headers: Headers) => Stream.Stream<SSEEvent, SSEError>) => {
+  return (request, headers) => makeSSESubscriptionStream(schema, layer, request, headers, options)
+}
+
+/**
+ * Type guard to check if a value is an AsyncIterable (subscription result)
+ */
+function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T> {
+  return typeof value === "object" && value !== null && Symbol.asyncIterator in value
+}

package/src/server/sse-types.ts

@@ -0,0 +1,234 @@
+import { Data, Effect, Runtime, Stream } from "effect"
+import type { ExecutionResult } from "graphql"
+import type { ComplexityConfig, FieldComplexityMap } from "./complexity"
+
+/**
+ * Standard SSE response headers following the graphql-sse protocol.
+ * Use these headers when writing SSE responses in platform adapters.
+ */
+export const SSE_HEADERS: Record<string, string> = {
+  "Content-Type": "text/event-stream",
+  "Cache-Control": "no-cache",
+  Connection: "keep-alive",
+  "X-Accel-Buffering": "no", // Disable nginx buffering
+} as const
+
+/**
+ * Error type for SSE operations
+ */
+export class SSEError extends Data.TaggedError("SSEError")<{
+  readonly cause: unknown
+}> {}
+
+/**
+ * SSE event types following the graphql-sse protocol (distinct connections mode).
+ * @see https://github.com/enisdenjo/graphql-sse/blob/master/PROTOCOL.md
+ */
+export type SSEEventType = "next" | "error" | "complete"
+
+/**
+ * An SSE event to be sent to the client.
+ */
+export interface SSEEvent {
+  readonly event: SSEEventType
+  readonly data: string
+}
+
+/**
+ * Platform-neutral SSE response interface using Effect types.
+ *
+ * This interface abstracts SSE operations across different platforms
+ * (Node.js, Bun, Deno, Workers). Platform packages implement this
+ * interface to bridge their specific HTTP response implementations.
+ *
+ * Unlike WebSocket which is bidirectional, SSE is unidirectional
+ * (server to client only). The subscription query is provided
+ * upfront when creating the SSE connection.
+ */
+export interface EffectSSE {
+  /**
+   * Send an SSE event to the client.
+   * The platform adapter formats this as proper SSE format:
+   * ```
+   * event: next
+   * data: {"data":{"field":"value"}}
+   *
+   * ```
+   */
+  readonly sendEvent: (event: SSEEvent) => Effect.Effect<void, SSEError>
+
+  /**
+   * Effect that completes when the client disconnects.
+   * Use this to detect client disconnection and cleanup.
+   */
+  readonly closed: Effect.Effect<void, SSEError>
+}
+
+/**
+ * The GraphQL request payload for SSE subscriptions.
+ * Same as a regular GraphQL HTTP request.
+ */
+export interface SSESubscriptionRequest {
+  readonly query: string
+  readonly variables?: Record<string, unknown>
+  readonly operationName?: string
+  readonly extensions?: Record<string, unknown>
+}
+
+/**
+ * Context available during an SSE subscription.
+ * This is passed to lifecycle hooks.
+ */
+export interface SSEConnectionContext<R> {
+  /**
+   * The Effect runtime for this connection.
+   * Use this to run Effects within the connection scope.
+   */
+  readonly runtime: Runtime.Runtime<R>
+
+  /**
+   * The original subscription request.
+   */
+  readonly request: SSESubscriptionRequest
+
+  /**
+   * Optional authentication/authorization context.
+   * Populated by the onConnect hook.
+   */
+  readonly connectionContext: Record<string, unknown>
+}
+
+/**
+ * Options for configuring the GraphQL SSE handler.
+ *
+ * @template R - Service requirements for lifecycle hooks
+ */
+export interface GraphQLSSEOptions<R> {
+  /**
+   * Query complexity limiting configuration.
+   * When provided, subscriptions are validated against complexity limits
+   * before execution begins.
+   */
+  readonly complexity?: ComplexityConfig
+
+  /**
+   * Field complexity definitions from the schema builder.
+   * If using the platform serve() functions, this is typically
+   * passed automatically.
+   */
+  readonly fieldComplexities?: FieldComplexityMap
+
+  /**
+   * Called before a subscription starts.
+   *
+   * Use this for authentication/authorization. Return:
+   * - A context object to accept the subscription
+   * - Throw/fail to reject the subscription
+   *
+   * The returned object is available in the GraphQL context.
+   *
+   * @example
+   * ```typescript
+   * onConnect: (request, headers) => Effect.gen(function* () {
+   *   const token = headers.get("authorization")
+   *   const user = yield* AuthService.validateToken(token)
+   *   return { user } // Available in GraphQL context
+   * })
+   * ```
+   */
+  readonly onConnect?: (
+    request: SSESubscriptionRequest,
+    headers: Headers
+  ) => Effect.Effect<Record<string, unknown>, unknown, R>
+
+  /**
+   * Called when the subscription starts streaming.
+   */
+  readonly onSubscribe?: (ctx: SSEConnectionContext<R>) => Effect.Effect<void, never, R>
+
+  /**
+   * Called when the subscription completes (normally or due to error).
+   */
+  readonly onComplete?: (ctx: SSEConnectionContext<R>) => Effect.Effect<void, never, R>
+
+  /**
+   * Called when the client disconnects.
+   */
+  readonly onDisconnect?: (ctx: SSEConnectionContext<R>) => Effect.Effect<void, never, R>
+
+  /**
+   * Called when an error occurs during subscription execution.
+   */
+  readonly onError?: (ctx: SSEConnectionContext<R>, error: unknown) => Effect.Effect<void, never, R>
+}
+
+/**
+ * Configuration for the SSE endpoint
+ */
+export interface GraphQLSSEConfig {
+  /**
+   * Path for SSE connections.
+   * @default "/graphql/stream"
+   */
+  readonly path?: string
+}
+
+/**
+ * Result of SSE subscription handler creation.
+ * This is used by platform packages to implement their SSE response.
+ */
+export interface SSESubscriptionResult {
+  /**
+   * Stream of SSE events to send to the client.
+   * The platform adapter should consume this stream and send events.
+   */
+  readonly events: Stream.Stream<SSEEvent, SSEError>
+
+  /**
+   * Effect that should be run when client disconnects.
+   * This allows cleanup of resources.
+   */
+  readonly cleanup: Effect.Effect<void, never, never>
+}
+
+/**
+ * Format an ExecutionResult as an SSE "next" event.
+ */
+export const formatNextEvent = (result: ExecutionResult): SSEEvent => ({
+  event: "next",
+  data: JSON.stringify(result),
+})
+
+/**
+ * Format errors as an SSE "error" event.
+ */
+export const formatErrorEvent = (errors: readonly unknown[]): SSEEvent => ({
+  event: "error",
+  data: JSON.stringify({ errors }),
+})
+
+/**
+ * Format a "complete" event.
+ */
+export const formatCompleteEvent = (): SSEEvent => ({
+  event: "complete",
+  data: "",
+})
+
+/**
+ * Format an SSE event to the wire format.
+ * Each event is formatted as:
+ * ```
+ * event: <type>
+ * data: <json>
+ *
+ * ```
+ */
+export const formatSSEMessage = (event: SSEEvent): string => {
+  const lines = [`event: ${event.event}`]
+  if (event.data) {
+    lines.push(`data: ${event.data}`)
+  }
+  lines.push("", "") // Two newlines to end the event
+  return lines.join("\n")
+}