@effect-gql/persisted-queries 0.1.0 → 1.0.0

package/src/persisted-queries-router.ts

@@ -1,421 +0,0 @@
-import { HttpRouter, HttpServerRequest, HttpServerResponse } from "@effect/platform"
-import { Effect, Layer, Option } from "effect"
-import {
-  GraphQLSchema,
-  parse,
-  validate,
-  specifiedRules,
-  NoSchemaIntrospectionCustomRule,
-  execute as graphqlExecute,
-  type DocumentNode,
-} from "graphql"
-import {
-  normalizeConfig,
-  graphiqlHtml,
-  validateComplexity,
-  ComplexityLimitExceededError,
-  type FieldComplexityMap,
-  type ErrorHandler,
-  defaultErrorHandler,
-} from "@effect-gql/core/server"
-import type { GraphQLEffectContext } from "@effect-gql/core"
-import {
-  ExtensionsService,
-  makeExtensionsService,
-  runParseHooks,
-  runValidateHooks,
-  runExecuteStartHooks,
-  runExecuteEndHooks,
-  type GraphQLExtension,
-} from "@effect-gql/core"
-import { PersistedQueryStore } from "./store"
-import { makeMemoryStore } from "./memory-store"
-import type { PersistedQueriesRouterOptions, PersistedQueryMode, HashAlgorithm } from "./config"
-import {
-  PersistedQueryNotFoundError,
-  PersistedQueryVersionError,
-  PersistedQueryHashMismatchError,
-  PersistedQueryNotAllowedError,
-} from "./errors"
-import {
-  computeHash,
-  parsePersistedQueryExtension,
-  parseGetRequestBody,
-  type GraphQLRequestBody,
-} from "./utils"
-
-/**
- * Create a GraphQL router with Apollo Persisted Queries support.
- *
- * This creates a complete GraphQL router that includes:
- * - Apollo Persisted Queries (APQ) support
- * - GET request support for CDN caching
- * - All standard GraphQL router features (validation, execution, extensions)
- *
- * ## Apollo APQ Protocol
- *
- * 1. Client sends request with `extensions.persistedQuery.sha256Hash`
- * 2. If hash found in store, execute the stored query
- * 3. If hash NOT found and query provided (APQ mode), store it and execute
- * 4. If hash NOT found and NO query, return `PERSISTED_QUERY_NOT_FOUND`
- * 5. Client retries with both hash and query
- *
- * ## Modes
- *
- * - **APQ mode** (`mode: "apq"`): Automatic runtime registration.
- *   Unknown queries trigger NOT_FOUND, prompting client retry with full query.
- *
- * - **Safelist mode** (`mode: "safelist"`): Pre-registered queries only.
- *   Unknown queries return NOT_ALLOWED error. Use with `makeSafelistStore()`.
- *
- * @example APQ Mode (default)
- * ```typescript
- * import { makePersistedQueriesRouter } from "@effect-gql/persisted-queries"
- *
- * const router = makePersistedQueriesRouter(schema, serviceLayer, {
- *   mode: "apq",
- *   enableGet: true,
- *   graphiql: { path: "/graphiql" },
- * })
- * ```
- *
- * @example Safelist Mode
- * ```typescript
- * import { makePersistedQueriesRouter, makeSafelistStore } from "@effect-gql/persisted-queries"
- *
- * const router = makePersistedQueriesRouter(schema, serviceLayer, {
- *   mode: "safelist",
- *   store: makeSafelistStore({
- *     "abc123...": "query GetUser($id: ID!) { user(id: $id) { name } }",
- *   }),
- * })
- * ```
- *
- * @param schema - The GraphQL schema
- * @param layer - Effect layer providing services required by resolvers
- * @param options - Router and persisted query configuration
- * @returns An HttpRouter with persisted query support
- */
-export const makePersistedQueriesRouter = <R>(
-  schema: GraphQLSchema,
-  layer: Layer.Layer<R>,
-  options: PersistedQueriesRouterOptions = {}
-): HttpRouter.HttpRouter<never, never> => {
-  const mode: PersistedQueryMode = options.mode ?? "apq"
-  const enableGet = options.enableGet ?? true
-  const validateHashOption = options.validateHash ?? true
-  const hashAlgorithm: HashAlgorithm = options.hashAlgorithm ?? "sha256"
-
-  // Core router config
-  const resolvedConfig = normalizeConfig(options)
-  const fieldComplexities: FieldComplexityMap = options.fieldComplexities ?? new Map()
-  const extensions: readonly GraphQLExtension<R>[] = options.extensions ?? []
-  const errorHandler: ErrorHandler = options.errorHandler ?? defaultErrorHandler
-
-  // Create the store layer (default to in-memory)
-  const baseStoreLayer = options.store ?? makeMemoryStore()
-
-  /**
-   * Resolve a persisted query from the store or register it.
-   * Returns the resolved request body with the query filled in.
-   */
-  const resolvePersistedQuery = (
-    body: GraphQLRequestBody
-  ): Effect.Effect<
-    GraphQLRequestBody,
-    | PersistedQueryNotFoundError
-    | PersistedQueryVersionError
-    | PersistedQueryHashMismatchError
-    | PersistedQueryNotAllowedError,
-    PersistedQueryStore
-  > =>
-    Effect.gen(function* () {
-      const persistedQuery = parsePersistedQueryExtension(body.extensions)
-
-      if (!persistedQuery) {
-        // No persisted query extension - pass through unchanged
-        return body
-      }
-
-      // Validate version
-      if (persistedQuery.version !== 1) {
-        return yield* Effect.fail(
-          new PersistedQueryVersionError({ version: persistedQuery.version })
-        )
-      }
-
-      const hash = persistedQuery.sha256Hash
-      const store = yield* PersistedQueryStore
-
-      // Check if we have the query stored
-      const storedQuery = yield* store.get(hash)
-
-      if (Option.isSome(storedQuery)) {
-        // Query found - use it
-        return {
-          ...body,
-          query: storedQuery.value,
-        }
-      }
-
-      // Query not found in store
-      if (!body.query) {
-        // No query provided - client needs to send it
-        return yield* Effect.fail(new PersistedQueryNotFoundError({ hash }))
-      }
-
-      // Query provided - check mode
-      if (mode === "safelist") {
-        // Safelist mode: reject unknown queries
-        return yield* Effect.fail(new PersistedQueryNotAllowedError({ hash }))
-      }
-
-      // APQ mode: validate hash and store
-      if (validateHashOption) {
-        const computed = yield* computeHash(body.query, hashAlgorithm)
-        if (computed !== hash) {
-          return yield* Effect.fail(
-            new PersistedQueryHashMismatchError({
-              providedHash: hash,
-              computedHash: computed,
-            })
-          )
-        }
-      }
-
-      // Store the query for future requests
-      yield* store.set(hash, body.query)
-
-      return body
-    })
-
-  /**
-   * Main GraphQL handler with APQ support
-   */
-  const createHandler = <RE>(parseBody: Effect.Effect<GraphQLRequestBody, Error, RE>) =>
-    Effect.gen(function* () {
-      // Parse request body
-      const rawBody = yield* parseBody.pipe(
-        Effect.catchAll((error) =>
-          Effect.succeed({
-            _parseError: true,
-            message: error.message,
-          } as any)
-        )
-      )
-
-      if ("_parseError" in rawBody) {
-        return yield* HttpServerResponse.json(
-          { errors: [{ message: rawBody.message }] },
-          { status: 400 }
-        )
-      }
-
-      // Resolve persisted query
-      const bodyResult = yield* resolvePersistedQuery(rawBody).pipe(
-        Effect.provide(baseStoreLayer),
-        Effect.either
-      )
-
-      if (bodyResult._tag === "Left") {
-        // APQ error - return appropriate GraphQL error response
-        const error = bodyResult.left
-        return yield* HttpServerResponse.json({
-          errors: [error.toGraphQLError()],
-        })
-      }
-
-      const body = bodyResult.right
-
-      // Check if we have a query to execute
-      if (!body.query) {
-        return yield* HttpServerResponse.json(
-          { errors: [{ message: "No query provided" }] },
-          { status: 400 }
-        )
-      }
-
-      // Create the ExtensionsService for this request
-      const extensionsService = yield* makeExtensionsService()
-
-      // Get the runtime from the layer
-      const runtime = yield* Effect.runtime<R>()
-
-      // Phase 1: Parse
-      let document: DocumentNode
-      try {
-        document = parse(body.query)
-      } catch (parseError) {
-        const extensionData = yield* extensionsService.get()
-        return yield* HttpServerResponse.json({
-          errors: [{ message: String(parseError) }],
-          extensions: Object.keys(extensionData).length > 0 ? extensionData : undefined,
-        })
-      }
-
-      // Run onParse hooks
-      yield* runParseHooks(extensions, body.query, document).pipe(
-        Effect.provideService(ExtensionsService, extensionsService)
-      )
-
-      // Phase 2: Validate
-      // Add NoSchemaIntrospectionCustomRule if introspection is disabled
-      const validationRules = resolvedConfig.introspection
-        ? undefined
-        : [...specifiedRules, NoSchemaIntrospectionCustomRule]
-      const validationErrors = validate(schema, document, validationRules)
-
-      // Run onValidate hooks
-      yield* runValidateHooks(extensions, document, validationErrors).pipe(
-        Effect.provideService(ExtensionsService, extensionsService)
-      )
-
-      // If validation failed, return errors without executing
-      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 }
-        )
-      }
-
-      // Validate query complexity if configured
-      if (resolvedConfig.complexity) {
-        yield* validateComplexity(
-          body.query,
-          body.operationName,
-          body.variables,
-          schema,
-          fieldComplexities,
-          resolvedConfig.complexity
-        ).pipe(
-          Effect.catchTag("ComplexityLimitExceededError", (error) => Effect.fail(error)),
-          Effect.catchTag("ComplexityAnalysisError", (error) =>
-            Effect.logWarning("Complexity analysis failed", error)
-          )
-        )
-      }
-
-      // Phase 3: Execute
-      const executionArgs = {
-        source: body.query,
-        document,
-        variableValues: body.variables,
-        operationName: body.operationName,
-        schema,
-        fieldComplexities,
-      }
-
-      // Run onExecuteStart hooks
-      yield* runExecuteStartHooks(extensions, executionArgs).pipe(
-        Effect.provideService(ExtensionsService, extensionsService)
-      )
-
-      // Execute GraphQL query
-      const executeResult = yield* Effect.try({
-        try: () =>
-          graphqlExecute({
-            schema,
-            document,
-            variableValues: body.variables,
-            operationName: body.operationName,
-            contextValue: { runtime } satisfies GraphQLEffectContext<R>,
-          }),
-        catch: (error) => new Error(String(error)),
-      })
-
-      // Await result if it's a promise
-      const resolvedResult: Awaited<typeof executeResult> =
-        executeResult && typeof executeResult === "object" && "then" in executeResult
-          ? yield* Effect.promise(() => executeResult)
-          : executeResult
-
-      // Run onExecuteEnd hooks
-      yield* runExecuteEndHooks(extensions, resolvedResult).pipe(
-        Effect.provideService(ExtensionsService, extensionsService)
-      )
-
-      // Merge extension data into result
-      const extensionData = yield* extensionsService.get()
-      const finalResult =
-        Object.keys(extensionData).length > 0
-          ? {
-              ...resolvedResult,
-              extensions: {
-                ...resolvedResult.extensions,
-                ...extensionData,
-              },
-            }
-          : resolvedResult
-
-      return yield* HttpServerResponse.json(finalResult)
-    }).pipe(
-      Effect.provide(layer),
-      Effect.catchAll((error) => {
-        if (error instanceof ComplexityLimitExceededError) {
-          return 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)
-        }
-        return Effect.fail(error)
-      }),
-      Effect.catchAllCause(errorHandler)
-    )
-
-  // POST handler
-  const postHandler = createHandler(
-    Effect.gen(function* () {
-      const request = yield* HttpServerRequest.HttpServerRequest
-      return yield* request.json as Effect.Effect<GraphQLRequestBody, Error>
-    })
-  )
-
-  // GET handler for CDN-cacheable persisted queries
-  const getHandler = createHandler(
-    Effect.gen(function* () {
-      const request = yield* HttpServerRequest.HttpServerRequest
-      const url = new URL(request.url, "http://localhost")
-      return yield* parseGetRequestBody(url.searchParams)
-    })
-  )
-
-  // Build router
-  let router = HttpRouter.empty.pipe(
-    HttpRouter.post(resolvedConfig.path as HttpRouter.PathInput, postHandler)
-  )
-
-  // Add GET handler if enabled
-  if (enableGet) {
-    router = router.pipe(HttpRouter.get(resolvedConfig.path as HttpRouter.PathInput, getHandler))
-  }
-
-  // Add GraphiQL route if enabled
-  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/store.ts

@@ -1,54 +0,0 @@
-import { Context, Effect, Option } from "effect"
-
-/**
- * Interface for persisted query storage.
- *
- * Implementations can be in-memory LRU cache, Redis, database, etc.
- * The interface uses Effect for consistency with the rest of the framework.
- */
-export interface PersistedQueryStore {
-  /**
-   * Get a query by its hash.
-   * Returns Option.none() if not found.
-   */
-  readonly get: (hash: string) => Effect.Effect<Option.Option<string>>
-
-  /**
-   * Store a query with its hash.
-   * In safelist mode, this may be a no-op.
-   */
-  readonly set: (hash: string, query: string) => Effect.Effect<void>
-
-  /**
-   * Check if a hash exists in the store without retrieving the query.
-   * More efficient for large queries when you only need existence check.
-   */
-  readonly has: (hash: string) => Effect.Effect<boolean>
-}
-
-/**
- * Service tag for the PersistedQueryStore.
- *
- * Use this tag to provide a store implementation via Effect's dependency injection.
- *
- * @example
- * ```typescript
- * import { PersistedQueryStore, makeMemoryStore } from "@effect-gql/persisted-queries"
- *
- * // Create a layer with the memory store
- * const storeLayer = makeMemoryStore({ maxSize: 1000 })
- *
- * // Use in an Effect
- * const program = Effect.gen(function* () {
- *   const store = yield* PersistedQueryStore
- *   yield* store.set("abc123", "query { hello }")
- *   const query = yield* store.get("abc123")
- *   // query: Option.some("query { hello }")
- * })
- *
- * Effect.runPromise(Effect.provide(program, storeLayer))
- * ```
- */
-export const PersistedQueryStore = Context.GenericTag<PersistedQueryStore>(
-  "@effect-gql/persisted-queries/PersistedQueryStore"
-)

package/src/utils.ts

@@ -1,111 +0,0 @@
-import { Effect } from "effect"
-import { createHash } from "crypto"
-import type { HashAlgorithm } from "./config"
-
-/**
- * Compute the hash of a query string.
- *
- * @param query - The GraphQL query string to hash
- * @param algorithm - Hash algorithm to use (default: sha256)
- * @returns Effect that resolves to the hex-encoded hash
- */
-export const computeHash = (
-  query: string,
-  algorithm: HashAlgorithm = "sha256"
-): Effect.Effect<string> => Effect.sync(() => createHash(algorithm).update(query).digest("hex"))
-
-/**
- * Structure of the persisted query extension in GraphQL requests.
- * This follows the Apollo APQ protocol.
- */
-export interface PersistedQueryExtension {
-  readonly version: number
-  readonly sha256Hash: string
-}
-
-/**
- * Parse and validate the persisted query extension from request extensions.
- *
- * @param extensions - The extensions object from the GraphQL request
- * @returns The parsed persisted query extension, or null if not present/invalid
- */
-export const parsePersistedQueryExtension = (
-  extensions: unknown
-): PersistedQueryExtension | null => {
-  if (typeof extensions !== "object" || extensions === null || !("persistedQuery" in extensions)) {
-    return null
-  }
-
-  const pq = (extensions as Record<string, unknown>).persistedQuery
-
-  if (typeof pq !== "object" || pq === null || !("version" in pq) || !("sha256Hash" in pq)) {
-    return null
-  }
-
-  const version = (pq as Record<string, unknown>).version
-  const sha256Hash = (pq as Record<string, unknown>).sha256Hash
-
-  if (typeof version !== "number" || typeof sha256Hash !== "string") {
-    return null
-  }
-
-  return { version, sha256Hash }
-}
-
-/**
- * GraphQL request body structure with optional persisted query extension.
- */
-export interface GraphQLRequestBody {
-  query?: string
-  variables?: Record<string, unknown>
-  operationName?: string
-  extensions?: {
-    persistedQuery?: PersistedQueryExtension
-    [key: string]: unknown
-  }
-}
-
-/**
- * Parse a GET request's query parameters into a GraphQL request body.
- *
- * Supports the following query parameters:
- * - `query`: The GraphQL query string (optional with persisted queries)
- * - `variables`: JSON-encoded variables object
- * - `operationName`: Name of the operation to execute
- * - `extensions`: JSON-encoded extensions object containing persistedQuery
- *
- * @param searchParams - URLSearchParams from the request URL
- * @returns Effect that resolves to the parsed request body or fails with parse error
- */
-export const parseGetRequestBody = (
-  searchParams: URLSearchParams
-): Effect.Effect<GraphQLRequestBody, Error> =>
-  Effect.try({
-    try: () => {
-      const extensionsRaw = searchParams.get("extensions")
-      const variablesRaw = searchParams.get("variables")
-
-      const result: GraphQLRequestBody = {}
-
-      const query = searchParams.get("query")
-      if (query) {
-        result.query = query
-      }
-
-      const operationName = searchParams.get("operationName")
-      if (operationName) {
-        result.operationName = operationName
-      }
-
-      if (variablesRaw) {
-        result.variables = JSON.parse(variablesRaw)
-      }
-
-      if (extensionsRaw) {
-        result.extensions = JSON.parse(extensionsRaw)
-      }
-
-      return result
-    },
-    catch: (e) => new Error(`Failed to parse query parameters: ${e}`),
-  })