@effect-gql/persisted-queries 0.1.0 → 1.0.0

package/index.d.ts

@@ -0,0 +1,403 @@
+import { HttpRouter } from '@effect/platform';
+import { Effect, Option, Context, Layer, Config } from 'effect';
+import { GraphQLSchema } from 'graphql';
+import { MakeGraphQLRouterOptions } from '@effect-gql/core/server';
+import * as effect_Cause from 'effect/Cause';
+import * as effect_Types from 'effect/Types';
+
+/**
+ * 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.
+ */
+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))
+ * ```
+ */
+declare const PersistedQueryStore: Context.Tag<PersistedQueryStore, PersistedQueryStore>;
+
+/**
+ * Operating mode for persisted queries.
+ *
+ * - `"apq"`: Automatic Persisted Queries - clients can register queries at runtime
+ * - `"safelist"`: Only pre-registered queries are allowed (security mode)
+ */
+type PersistedQueryMode = "apq" | "safelist";
+/**
+ * Hash algorithm used for query hashing.
+ * Must match what clients use - Apollo clients use SHA-256.
+ */
+type HashAlgorithm = "sha256" | "sha512";
+/**
+ * Configuration for the persisted queries feature.
+ */
+interface PersistedQueriesConfig {
+    /**
+     * Operating mode.
+     *
+     * - `"apq"`: Automatic Persisted Queries - clients can register queries at runtime.
+     *   Unknown hashes trigger PERSISTED_QUERY_NOT_FOUND, prompting clients to retry with query.
+     *
+     * - `"safelist"`: Only pre-registered queries are allowed.
+     *   Unknown hashes return PERSISTED_QUERY_NOT_ALLOWED error.
+     *   Use with `makeSafelistStore()` for production security.
+     *
+     * Default: `"apq"`
+     */
+    readonly mode?: PersistedQueryMode;
+    /**
+     * Layer providing the PersistedQueryStore service.
+     *
+     * Defaults to in-memory LRU store with 1000 entries.
+     * Use `makeMemoryStore()` for custom size or `makeSafelistStore()` for safelist mode.
+     *
+     * @example
+     * ```typescript
+     * // Custom memory store
+     * store: makeMemoryStore({ maxSize: 5000 })
+     *
+     * // Safelist store
+     * store: makeSafelistStore({ "hash1": "query {...}", "hash2": "query {...}" })
+     * ```
+     */
+    readonly store?: Layer.Layer<PersistedQueryStore>;
+    /**
+     * Whether to support GET requests with query parameters.
+     *
+     * When enabled, the router accepts:
+     * ```
+     * GET /graphql?extensions={"persistedQuery":{"version":1,"sha256Hash":"..."}}&variables={...}&operationName=...
+     * ```
+     *
+     * This enables CDN caching since the same hash always maps to the same URL.
+     *
+     * Default: `true`
+     */
+    readonly enableGet?: boolean;
+    /**
+     * Validate that the provided query matches its hash when storing.
+     *
+     * This prevents hash collision attacks where a malicious client could
+     * register a different query under someone else's hash.
+     *
+     * Has a slight performance overhead for computing the hash.
+     *
+     * Default: `true`
+     */
+    readonly validateHash?: boolean;
+    /**
+     * Hash algorithm to use for validation.
+     * Must match what clients use - Apollo clients use SHA-256.
+     *
+     * Default: `"sha256"`
+     */
+    readonly hashAlgorithm?: HashAlgorithm;
+}
+/**
+ * Options for the persisted queries router.
+ *
+ * Extends the standard GraphQL router options with persisted query configuration.
+ */
+interface PersistedQueriesRouterOptions extends MakeGraphQLRouterOptions, PersistedQueriesConfig {
+}
+/**
+ * Effect Config for loading persisted queries settings from environment variables.
+ *
+ * Environment variables:
+ * - `PERSISTED_QUERIES_MODE`: `"apq"` | `"safelist"` (default: `"apq"`)
+ * - `PERSISTED_QUERIES_ENABLE_GET`: boolean (default: `true`)
+ * - `PERSISTED_QUERIES_VALIDATE_HASH`: boolean (default: `true`)
+ *
+ * Note: The store must still be provided programmatically.
+ *
+ * @example
+ * ```typescript
+ * import { PersistedQueriesConfigFromEnv } from "@effect-gql/persisted-queries"
+ *
+ * const config = yield* Config.unwrap(PersistedQueriesConfigFromEnv)
+ * ```
+ */
+declare const PersistedQueriesConfigFromEnv: Config.Config<Omit<PersistedQueriesConfig, "store">>;
+
+/**
+ * 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
+ */
+declare const makePersistedQueriesRouter: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: PersistedQueriesRouterOptions) => HttpRouter.HttpRouter<never, never>;
+
+/**
+ * Configuration for the in-memory LRU store
+ */
+interface MemoryStoreConfig {
+    /**
+     * Maximum number of queries to cache.
+     * When exceeded, least recently used queries are evicted.
+     * Default: 1000
+     */
+    readonly maxSize?: number;
+}
+/**
+ * Create an in-memory LRU (Least Recently Used) store for persisted queries.
+ *
+ * This implementation uses Map's natural insertion order for O(1) LRU operations:
+ * - get: O(1) - delete and re-insert to move to end (most recently used)
+ * - set: O(1) - insert at end, evict from front if needed
+ * - eviction: O(1) - delete first entry (least recently used)
+ *
+ * This is the default store implementation suitable for single-instance servers.
+ * For multi-instance deployments, consider using a shared store like Redis.
+ *
+ * @param config - Optional configuration for cache size
+ * @returns A Layer providing the PersistedQueryStore service
+ *
+ * @example
+ * ```typescript
+ * import { makeMemoryStore, makePersistedQueriesRouter } from "@effect-gql/persisted-queries"
+ *
+ * // Default store with 1000 entry limit
+ * const router1 = makePersistedQueriesRouter(schema, serviceLayer)
+ *
+ * // Custom store with larger cache
+ * const router2 = makePersistedQueriesRouter(schema, serviceLayer, {
+ *   store: makeMemoryStore({ maxSize: 5000 })
+ * })
+ * ```
+ */
+declare const makeMemoryStore: (config?: MemoryStoreConfig) => Layer.Layer<PersistedQueryStore>;
+/**
+ * Create a pre-populated safelist store.
+ *
+ * This store only allows queries that were provided at creation time.
+ * Any attempt to store new queries is silently ignored.
+ * Use this for production security where you want to allowlist specific operations.
+ *
+ * @param queries - Record mapping SHA-256 hashes to query strings
+ * @returns A Layer providing the PersistedQueryStore service
+ *
+ * @example
+ * ```typescript
+ * import { makeSafelistStore, makePersistedQueriesRouter } from "@effect-gql/persisted-queries"
+ *
+ * // Pre-register allowed queries
+ * const router = makePersistedQueriesRouter(schema, serviceLayer, {
+ *   mode: "safelist",
+ *   store: makeSafelistStore({
+ *     "ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38": "query GetUser($id: ID!) { user(id: $id) { name email } }",
+ *     "a1b2c3d4...": "query GetPosts { posts { title } }",
+ *   }),
+ * })
+ * ```
+ */
+declare const makeSafelistStore: (queries: Record<string, string>) => Layer.Layer<PersistedQueryStore>;
+
+/**
+ * GraphQL error format for APQ responses.
+ * Compatible with Apollo Client's error handling.
+ */
+interface PersistedQueryGraphQLError {
+    readonly message: string;
+    readonly extensions: {
+        readonly code: string;
+        readonly [key: string]: unknown;
+    };
+}
+declare const PersistedQueryNotFoundError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "PersistedQueryNotFoundError";
+} & Readonly<A>;
+/**
+ * Error returned when a persisted query hash is not found in the store
+ * and no query body was provided.
+ *
+ * Apollo clients recognize this error and automatically retry with the full query.
+ * This is the expected flow for Automatic Persisted Queries (APQ).
+ */
+declare class PersistedQueryNotFoundError extends PersistedQueryNotFoundError_base<{
+    readonly hash: string;
+}> {
+    /**
+     * Convert to GraphQL error format compatible with Apollo protocol.
+     */
+    toGraphQLError(): PersistedQueryGraphQLError;
+}
+declare const PersistedQueryVersionError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "PersistedQueryVersionError";
+} & Readonly<A>;
+/**
+ * Error returned when the persisted query protocol version is not supported.
+ *
+ * Currently only version 1 is supported, which uses SHA-256 hashing.
+ */
+declare class PersistedQueryVersionError extends PersistedQueryVersionError_base<{
+    readonly version: number;
+}> {
+    toGraphQLError(): PersistedQueryGraphQLError;
+}
+declare const PersistedQueryHashMismatchError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "PersistedQueryHashMismatchError";
+} & Readonly<A>;
+/**
+ * Error returned when the provided query doesn't match its hash.
+ *
+ * This can indicate a client bug or a potential hash collision attack.
+ * Hash validation is enabled by default and can be disabled if needed.
+ */
+declare class PersistedQueryHashMismatchError extends PersistedQueryHashMismatchError_base<{
+    readonly providedHash: string;
+    readonly computedHash: string;
+}> {
+    toGraphQLError(): PersistedQueryGraphQLError;
+}
+declare const PersistedQueryNotAllowedError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "PersistedQueryNotAllowedError";
+} & Readonly<A>;
+/**
+ * Error returned when trying to execute a query that is not in the safelist.
+ *
+ * In safelist mode, only pre-registered queries are allowed.
+ * This error is returned when a client tries to register a new query.
+ */
+declare class PersistedQueryNotAllowedError extends PersistedQueryNotAllowedError_base<{
+    readonly hash: string;
+}> {
+    toGraphQLError(): PersistedQueryGraphQLError;
+}
+/**
+ * Union type of all APQ-related errors
+ */
+type PersistedQueryError = PersistedQueryNotFoundError | PersistedQueryVersionError | PersistedQueryHashMismatchError | PersistedQueryNotAllowedError;
+
+/**
+ * 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
+ */
+declare const computeHash: (query: string, algorithm?: HashAlgorithm) => Effect.Effect<string>;
+/**
+ * Structure of the persisted query extension in GraphQL requests.
+ * This follows the Apollo APQ protocol.
+ */
+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
+ */
+declare const parsePersistedQueryExtension: (extensions: unknown) => PersistedQueryExtension | null;
+/**
+ * GraphQL request body structure with optional persisted query extension.
+ */
+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
+ */
+declare const parseGetRequestBody: (searchParams: URLSearchParams) => Effect.Effect<GraphQLRequestBody, Error>;
+
+export { type GraphQLRequestBody, type HashAlgorithm, type MemoryStoreConfig, type PersistedQueriesConfig, PersistedQueriesConfigFromEnv, type PersistedQueriesRouterOptions, type PersistedQueryError, type PersistedQueryExtension, type PersistedQueryGraphQLError, PersistedQueryHashMismatchError, type PersistedQueryMode, PersistedQueryNotAllowedError, PersistedQueryNotFoundError, PersistedQueryStore, PersistedQueryStore as PersistedQueryStoreInterface, PersistedQueryVersionError, computeHash, makeMemoryStore, makePersistedQueriesRouter, makeSafelistStore, parseGetRequestBody, parsePersistedQueryExtension };