@effect-gql/core 0.1.0

package/src/server/router.ts

@@ -0,0 +1,432 @@
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "@effect/platform"
+import { Cause, Context, Effect, Layer } from "effect"
+import {
+  GraphQLSchema,
+  parse,
+  validate,
+  specifiedRules,
+  NoSchemaIntrospectionCustomRule,
+  execute as graphqlExecute,
+  Kind,
+  type DocumentNode,
+  type OperationDefinitionNode,
+} from "graphql"
+import type { GraphQLEffectContext } from "../builder/types"
+import { graphiqlHtml } from "./graphiql"
+import { normalizeConfig, type GraphQLRouterConfigInput } from "./config"
+import {
+  validateComplexity,
+  ComplexityLimitExceededError,
+  type FieldComplexityMap,
+} from "./complexity"
+import { computeCachePolicy, toCacheControlHeader, type CacheHintMap } from "./cache-control"
+import {
+  type GraphQLExtension,
+  ExtensionsService,
+  makeExtensionsService,
+  runParseHooks,
+  runValidateHooks,
+  runExecuteStartHooks,
+  runExecuteEndHooks,
+} from "../extensions"
+
+/**
+ * Error handler function type for handling uncaught errors during GraphQL execution.
+ * Receives the error cause and should return an HTTP response.
+ */
+export type ErrorHandler = (
+  cause: Cause.Cause<unknown>
+) => Effect.Effect<HttpServerResponse.HttpServerResponse, never, never>
+
+/**
+ * Default error handler that returns a 500 Internal Server Error.
+ * In non-production environments, it logs the full error for debugging.
+ */
+export const defaultErrorHandler: ErrorHandler = (cause) =>
+  (process.env.NODE_ENV !== "production"
+    ? Effect.logError("GraphQL error", cause)
+    : Effect.void
+  ).pipe(
+    Effect.andThen(
+      HttpServerResponse.json(
+        {
+          errors: [
+            {
+              message: "An error occurred processing your request",
+            },
+          ],
+        },
+        { status: 500 }
+      ).pipe(Effect.orDie)
+    )
+  )
+
+/**
+ * Request body for GraphQL queries.
+ */
+interface GraphQLRequestBody {
+  query: string
+  variables?: Record<string, unknown>
+  operationName?: string
+}
+
+/**
+ * Parse a GraphQL query string into a DocumentNode.
+ * Returns the document or an error response if parsing fails.
+ */
+const parseGraphQLQuery = (
+  query: string,
+  extensionsService: Context.Tag.Service<typeof ExtensionsService>
+): Effect.Effect<
+  | { ok: true; document: DocumentNode }
+  | { ok: false; response: HttpServerResponse.HttpServerResponse },
+  never,
+  never
+> =>
+  Effect.gen(function* () {
+    try {
+      const document = parse(query)
+      return { ok: true as const, document }
+    } catch (parseError) {
+      const extensionData = yield* extensionsService.get()
+      const response = yield* HttpServerResponse.json({
+        errors: [{ message: String(parseError) }],
+        extensions: Object.keys(extensionData).length > 0 ? extensionData : undefined,
+      }).pipe(Effect.orDie)
+      return { ok: false as const, response }
+    }
+  })
+
+/**
+ * Run complexity validation if configured.
+ * Logs warnings for analysis errors but doesn't block execution.
+ */
+const runComplexityValidation = (
+  body: GraphQLRequestBody,
+  schema: GraphQLSchema,
+  fieldComplexities: FieldComplexityMap,
+  complexityConfig: { maxDepth?: number; maxComplexity?: number } | undefined
+): Effect.Effect<void, ComplexityLimitExceededError, never> => {
+  if (!complexityConfig) {
+    return Effect.void
+  }
+
+  return validateComplexity(
+    body.query,
+    body.operationName,
+    body.variables,
+    schema,
+    fieldComplexities,
+    complexityConfig
+  ).pipe(
+    Effect.catchTag("ComplexityLimitExceededError", (error) => Effect.fail(error)),
+    Effect.catchTag("ComplexityAnalysisError", (error) =>
+      Effect.logWarning("Complexity analysis failed", error)
+    )
+  )
+}
+
+/**
+ * Execute a GraphQL query and handle async results.
+ */
+const executeGraphQLQuery = <R>(
+  schema: GraphQLSchema,
+  document: DocumentNode,
+  variables: Record<string, unknown> | undefined,
+  operationName: string | undefined,
+  runtime: import("effect").Runtime.Runtime<R>
+): Effect.Effect<import("graphql").ExecutionResult, Error, never> =>
+  Effect.gen(function* () {
+    const executeResult = yield* Effect.try({
+      try: () =>
+        graphqlExecute({
+          schema,
+          document,
+          variableValues: variables,
+          operationName,
+          contextValue: { runtime } satisfies GraphQLEffectContext<R>,
+        }),
+      catch: (error) => new Error(String(error)),
+    })
+
+    // Await result if it's a promise
+    if (executeResult && typeof executeResult === "object" && "then" in executeResult) {
+      return yield* Effect.promise(
+        () => executeResult as Promise<import("graphql").ExecutionResult>
+      )
+    }
+    return executeResult as import("graphql").ExecutionResult
+  })
+
+/**
+ * Compute cache control header for the response if applicable.
+ */
+const computeCacheControlHeader = (
+  document: DocumentNode,
+  operationName: string | undefined,
+  schema: GraphQLSchema,
+  cacheHints: CacheHintMap,
+  cacheControlConfig:
+    | { enabled?: boolean; calculateHttpHeaders?: boolean; defaultMaxAge?: number }
+    | undefined
+): Effect.Effect<string | undefined, never, never> =>
+  Effect.gen(function* () {
+    if (
+      cacheControlConfig?.enabled === false ||
+      cacheControlConfig?.calculateHttpHeaders === false
+    ) {
+      return undefined
+    }
+
+    // Find the operation from the document
+    const operations = document.definitions.filter(
+      (d): d is OperationDefinitionNode => d.kind === Kind.OPERATION_DEFINITION
+    )
+    const operation = operationName
+      ? operations.find((o) => o.name?.value === operationName)
+      : operations[0]
+
+    if (!operation || operation.operation === "mutation") {
+      // Mutations should not be cached
+      return undefined
+    }
+
+    const cachePolicy = yield* computeCachePolicy({
+      document,
+      operation,
+      schema,
+      cacheHints,
+      config: cacheControlConfig ?? {},
+    })
+
+    return toCacheControlHeader(cachePolicy)
+  })
+
+/**
+ * Build the final GraphQL response with extensions merged in.
+ */
+const buildGraphQLResponse = (
+  result: import("graphql").ExecutionResult,
+  extensionData: Record<string, unknown>,
+  cacheControlHeader: string | undefined
+): Effect.Effect<HttpServerResponse.HttpServerResponse, never, never> => {
+  const finalResult =
+    Object.keys(extensionData).length > 0
+      ? {
+          ...result,
+          extensions: {
+            ...result.extensions,
+            ...extensionData,
+          },
+        }
+      : result
+
+  const responseHeaders = cacheControlHeader ? { "cache-control": cacheControlHeader } : undefined
+
+  return HttpServerResponse.json(finalResult, { headers: responseHeaders }).pipe(Effect.orDie)
+}
+
+/**
+ * Handle complexity limit exceeded error, returning appropriate response.
+ */
+const handleComplexityError = (
+  error: ComplexityLimitExceededError
+): Effect.Effect<HttpServerResponse.HttpServerResponse, never, never> =>
+  HttpServerResponse.json(
+    {
+      errors: [
+        {
+          message: error.message,
+          extensions: {
+            code: "COMPLEXITY_LIMIT_EXCEEDED",
+            limitType: error.limitType,
+            limit: error.limit,
+            actual: error.actual,
+          },
+        },
+      ],
+    },
+    { status: 400 }
+  ).pipe(Effect.orDie)
+
+/**
+ * Options for makeGraphQLRouter
+ */
+export interface MakeGraphQLRouterOptions extends GraphQLRouterConfigInput {
+  /**
+   * Field complexity definitions from the schema builder.
+   * If using toRouter(), this is automatically extracted from the builder.
+   * If using makeGraphQLRouter() directly, call builder.getFieldComplexities().
+   */
+  readonly fieldComplexities?: FieldComplexityMap
+
+  /**
+   * Cache hint definitions from the schema builder.
+   * If using toRouter(), this is automatically extracted from the builder.
+   * If using makeGraphQLRouter() directly, call builder.getCacheHints().
+   */
+  readonly cacheHints?: CacheHintMap
+
+  /**
+   * GraphQL extensions for lifecycle hooks.
+   * If using toRouter(), this is automatically extracted from the builder.
+   * If using makeGraphQLRouter() directly, call builder.getExtensions().
+   */
+  readonly extensions?: readonly GraphQLExtension<any>[]
+
+  /**
+   * Custom error handler for uncaught errors during GraphQL execution.
+   * Receives the error cause and should return an HTTP response.
+   * Defaults to returning a 500 Internal Server Error with a generic message.
+   */
+  readonly errorHandler?: ErrorHandler
+}
+
+/**
+ * Create an HttpRouter configured for GraphQL
+ *
+ * The router handles:
+ * - POST requests to the GraphQL endpoint
+ * - GET requests to the GraphiQL UI (if enabled)
+ * - Query complexity validation (if configured)
+ * - Extension lifecycle hooks (onParse, onValidate, onExecuteStart, onExecuteEnd)
+ *
+ * @param schema - The GraphQL schema
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional configuration for paths, GraphiQL, complexity, and extensions
+ * @returns An HttpRouter that can be composed with other routes
+ *
+ * @example
+ * ```typescript
+ * const router = makeGraphQLRouter(schema, Layer.empty, {
+ *   path: "/graphql",
+ *   graphiql: { path: "/graphiql" },
+ *   complexity: { maxDepth: 10, maxComplexity: 1000 },
+ *   fieldComplexities: builder.getFieldComplexities(),
+ *   extensions: builder.getExtensions()
+ * })
+ *
+ * // Compose with other routes
+ * const app = HttpRouter.empty.pipe(
+ *   HttpRouter.get("/health", HttpServerResponse.json({ status: "ok" })),
+ *   HttpRouter.concat(router)
+ * )
+ * ```
+ */
+export const makeGraphQLRouter = <R>(
+  schema: GraphQLSchema,
+  layer: Layer.Layer<R>,
+  options: MakeGraphQLRouterOptions = {}
+): HttpRouter.HttpRouter<never, never> => {
+  const resolvedConfig = normalizeConfig(options)
+  const fieldComplexities = options.fieldComplexities ?? new Map()
+  const cacheHints = options.cacheHints ?? new Map()
+  const extensions = options.extensions ?? []
+  const errorHandler = options.errorHandler ?? defaultErrorHandler
+
+  // GraphQL POST handler
+  const graphqlHandler = Effect.gen(function* () {
+    const extensionsService = yield* makeExtensionsService()
+    const runtime = yield* Effect.runtime<R>()
+
+    // Parse request body
+    const request = yield* HttpServerRequest.HttpServerRequest
+    const body = yield* request.json as Effect.Effect<GraphQLRequestBody>
+
+    // Phase 1: Parse
+    const parseResult = yield* parseGraphQLQuery(body.query, extensionsService)
+    if (!parseResult.ok) {
+      return parseResult.response
+    }
+    const document = parseResult.document
+
+    yield* runParseHooks(extensions, body.query, document).pipe(
+      Effect.provideService(ExtensionsService, extensionsService)
+    )
+
+    // Phase 2: Validate
+    const validationRules = resolvedConfig.introspection
+      ? undefined
+      : [...specifiedRules, NoSchemaIntrospectionCustomRule]
+    const validationErrors = validate(schema, document, validationRules)
+
+    yield* runValidateHooks(extensions, document, validationErrors).pipe(
+      Effect.provideService(ExtensionsService, extensionsService)
+    )
+
+    if (validationErrors.length > 0) {
+      const extensionData = yield* extensionsService.get()
+      return yield* HttpServerResponse.json(
+        {
+          errors: validationErrors.map((e) => ({
+            message: e.message,
+            locations: e.locations,
+            path: e.path,
+          })),
+          extensions: Object.keys(extensionData).length > 0 ? extensionData : undefined,
+        },
+        { status: 400 }
+      )
+    }
+
+    // Complexity validation
+    yield* runComplexityValidation(body, schema, fieldComplexities, resolvedConfig.complexity)
+
+    // Phase 3: Execute
+    yield* runExecuteStartHooks(extensions, {
+      source: body.query,
+      document,
+      variableValues: body.variables,
+      operationName: body.operationName,
+      schema,
+      fieldComplexities,
+    }).pipe(Effect.provideService(ExtensionsService, extensionsService))
+
+    const result = yield* executeGraphQLQuery(
+      schema,
+      document,
+      body.variables,
+      body.operationName,
+      runtime
+    )
+
+    yield* runExecuteEndHooks(extensions, result).pipe(
+      Effect.provideService(ExtensionsService, extensionsService)
+    )
+
+    // Build response
+    const extensionData = yield* extensionsService.get()
+    const cacheControlHeader = yield* computeCacheControlHeader(
+      document,
+      body.operationName,
+      schema,
+      cacheHints,
+      resolvedConfig.cacheControl
+    )
+
+    return yield* buildGraphQLResponse(result, extensionData, cacheControlHeader)
+  }).pipe(
+    Effect.provide(layer),
+    Effect.catchAll((error) => {
+      if (error instanceof ComplexityLimitExceededError) {
+        return handleComplexityError(error)
+      }
+      return Effect.fail(error)
+    }),
+    Effect.catchAllCause(errorHandler)
+  )
+
+  // Build router
+  let router = HttpRouter.empty.pipe(
+    HttpRouter.post(resolvedConfig.path as HttpRouter.PathInput, graphqlHandler)
+  )
+
+  if (resolvedConfig.graphiql) {
+    const { path, endpoint } = resolvedConfig.graphiql
+    router = router.pipe(
+      HttpRouter.get(path as HttpRouter.PathInput, HttpServerResponse.html(graphiqlHtml(endpoint)))
+    )
+  }
+
+  return router
+}

package/src/server/schema-builder-extensions.ts

@@ -0,0 +1,51 @@
+import { Layer } from "effect"
+import { HttpRouter } from "@effect/platform"
+import { GraphQLSchemaBuilder } from "../builder/schema-builder"
+import { makeGraphQLRouter, type MakeGraphQLRouterOptions } from "./router"
+
+/**
+ * Convert a GraphQLSchemaBuilder to an HttpRouter.
+ *
+ * This bridges the GraphQL schema builder with the @effect/platform HTTP server.
+ * Field complexities and cache hints are automatically extracted from the builder.
+ *
+ * @param builder - The GraphQL schema builder
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional configuration for paths, GraphiQL, complexity, and caching
+ * @returns An HttpRouter that can be composed with other routes
+ *
+ * @example
+ * ```typescript
+ * import { GraphQLSchemaBuilder, query, toRouter } from "@effect-gql/core"
+ * import { Layer, Effect } from "effect"
+ * import * as S from "effect/Schema"
+ *
+ * const builder = GraphQLSchemaBuilder.empty.pipe(
+ *   query("hello", { type: S.String, resolve: () => Effect.succeed("world") })
+ * )
+ *
+ * // Basic usage
+ * const router = toRouter(builder, Layer.empty, { graphiql: true })
+ *
+ * // With complexity limiting
+ * const routerWithLimits = toRouter(builder, Layer.empty, {
+ *   graphiql: true,
+ *   complexity: { maxDepth: 10, maxComplexity: 1000 }
+ * })
+ *
+ * // With cache control
+ * const routerWithCaching = toRouter(builder, Layer.empty, {
+ *   cacheControl: { enabled: true, defaultMaxAge: 0 }
+ * })
+ * ```
+ */
+export const toRouter = <R, R2>(
+  builder: GraphQLSchemaBuilder<R>,
+  layer: Layer.Layer<R2>,
+  options?: Omit<MakeGraphQLRouterOptions, "fieldComplexities" | "cacheHints">
+): HttpRouter.HttpRouter<never, never> => {
+  const schema = builder.buildSchema()
+  const fieldComplexities = builder.getFieldComplexities()
+  const cacheHints = builder.getCacheHints()
+  return makeGraphQLRouter(schema, layer, { ...options, fieldComplexities, cacheHints })
+}