feat(response-cache): add extras property to get scope and its metadata from buildResponseCacheKey

Author: k-i-k-s

.changeset/sour-cars-hang.md

@@ -0,0 +1,5 @@
+---
+'@envelop/response-cache': minor
+---
+
+Added `getScope` callback in `buildResponseCacheKey` params

packages/plugins/response-cache/README.md

@@ -863,3 +863,55 @@ mutation SetNameMutation {
   }
 }
 ```
+
+#### Get scope of the query
+
+Useful for building a cache key that is shared across all sessions when `PUBLIC`.
+
+```ts
+import jsonStableStringify from 'fast-json-stable-stringify'
+import { execute, parse, subscribe, validate } from 'graphql'
+import { envelop } from '@envelop/core'
+import { hashSHA256, useResponseCache } from '@envelop/response-cache'
+
+const getEnveloped = envelop({
+  parse,
+  validate,
+  execute,
+  subscribe,
+  plugins: [
+    // ... other plugins ...
+    useResponseCache({
+      ttl: 2000,
+      session: request => getSessionId(request),
+      buildResponseCacheKey: ({
+        getScope,
+        sessionId,
+        documentString,
+        operationName,
+        variableValues
+      }) =>
+        // Use `getScope()` to put a unique key for every session when `PUBLIC`
+        hashSHA256(
+          [
+            getScope() === 'PUBLIC' ? 'PUBLIC' : sessionId,
+            documentString,
+            operationName ?? '',
+            jsonStableStringify(variableValues ?? {})
+          ].join('|')
+        ),
+      scopePerSchemaCoordinate: {
+        // Set scope for an entire query
+        'Query.getProfile': 'PRIVATE',
+        // Set scope for an entire type
+        PrivateProfile: 'PRIVATE',
+        // Set scope for a single field
+        'Profile.privateData': 'PRIVATE'
+      }
+    })
+  ]
+})
+```
+
+> Note: The use of this callback will increase the ram usage since it memoizes the scope for each
+> query in a weak map.

packages/plugins/response-cache/src/get-scope.ts

@@ -0,0 +1,115 @@
+import {
+  FieldNode,
+  GraphQLList,
+  GraphQLNonNull,
+  GraphQLObjectType,
+  GraphQLOutputType,
+  GraphQLSchema,
+  Kind,
+  parse,
+  SelectionNode,
+  visit,
+} from 'graphql';
+import { memoize1 } from '@graphql-tools/utils';
+import { isPrivate, type CacheControlDirective } from './plugin';
+
+/** Parse the selected query fields */
+function parseSelections(selections: readonly SelectionNode[] = [], record: Record<string, any>) {
+  for (const selection of selections) {
+    if (selection.kind === Kind.FIELD) {
+      record[selection.name.value] = {};
+      parseSelections(selection.selectionSet?.selections, record[selection.name.value]);
+    }
+  }
+}
+
+/** Iterate over record and parse its fields with schema type */
+function parseRecordWithSchemaType(
+  type: GraphQLOutputType,
+  record: Record<string, any>,
+  prefix?: string,
+): Set<string> {
+  let fields = new Set<string>();
+  if (type instanceof GraphQLNonNull || type instanceof GraphQLList) {
+    fields = new Set([...fields, ...parseRecordWithSchemaType(type.ofType, record, prefix)]);
+  }
+
+  if (type instanceof GraphQLObjectType) {
+    const newPrefixes = [...(prefix ?? []), type.name];
+    fields.add(newPrefixes.join('.'));
+
+    const typeFields = type.getFields();
+    for (const key of Object.keys(record)) {
+      const field = typeFields[key];
+      if (!field) {
+        continue;
+      }
+
+      fields.add([...newPrefixes, field.name].join('.'));
+      if (Object.keys(record[key]).length > 0) {
+        fields = new Set([...fields, ...parseRecordWithSchemaType(field.type, record[key])]);
+      }
+    }
+  }
+
+  return fields;
+}
+
+function getSchemaCoordinatesFromQuery(schema: GraphQLSchema, query: string): Set<string> {
+  const ast = parse(query);
+  let fields = new Set<string>();
+
+  // Launch the field visitor
+  visit(ast, {
+    // Parse the fields of the root of query
+    Field: node => {
+      const record: Record<string, any> = {};
+      const queryFields = schema.getQueryType()?.getFields()[node.name.value];
+
+      if (queryFields) {
+        record[node.name.value] = {};
+        parseSelections(node.selectionSet?.selections, record[node.name.value]);
+
+        fields.add(`Query.${node.name.value}`);
+        fields = new Set([
+          ...fields,
+          ...parseRecordWithSchemaType(queryFields.type, record[node.name.value]),
+        ]);
+      }
+    },
+    // And each fragment
+    FragmentDefinition: fragment => {
+      const type = fragment.typeCondition.name.value;
+      fields = new Set([
+        ...fields,
+        ...(
+          fragment.selectionSet.selections.filter(({ kind }) => kind === Kind.FIELD) as FieldNode[]
+        ).map(({ name: { value } }) => `${type}.${value}`),
+      ]);
+    },
+  });
+
+  return fields;
+}
+
+export const getScopeFromQuery = (
+  schema: GraphQLSchema,
+  query: string,
+): {
+  scope: NonNullable<CacheControlDirective['scope']>;
+  metadata: { privateProperty?: string };
+} => {
+  const fn = memoize1(({ query }: { query: string }) => {
+    const schemaCoordinates = getSchemaCoordinatesFromQuery(schema, query);
+
+    for (const coordinate of schemaCoordinates) {
+      if (isPrivate(coordinate)) {
+        return { scope: 'PRIVATE' as const, metadata: { privateProperty: coordinate } };
+      }
+    }
+
+    return { scope: 'PUBLIC' as const, metadata: {} };
+  });
+
+  return fn({ query });
+};

packages/plugins/response-cache/src/index.ts

@@ -2,3 +2,4 @@ export * from './in-memory-cache.js';
 export * from './plugin.js';
 export * from './cache.js';
 export * from './hash-sha256.js';
+export * from './get-scope.js';

packages/plugins/response-cache/src/plugin.ts

@@ -5,6 +5,7 @@ import {
   ExecutionArgs,
   getOperationAST,
   GraphQLDirective,
+  GraphQLSchema,
   GraphQLType,
   isListType,
   isNonNullType,
@@ -35,6 +36,7 @@ import {
 } from '@graphql-tools/utils';
 import { handleMaybePromise, MaybePromise } from '@whatwg-node/promise-helpers';
 import type { Cache, CacheEntityRecord } from './cache.js';
+import { getScopeFromQuery } from './get-scope.js';
 import { hashSHA256 } from './hash-sha256.js';
 import { createInMemoryCache } from './in-memory-cache.js';
 
@@ -52,6 +54,13 @@ export type BuildResponseCacheKeyFunction = (params: {
   sessionId: Maybe<string>;
   /** GraphQL Context */
   context: ExecutionArgs['contextValue'];
+  /** Extras of the query (won't be computed if not requested) */
+  extras: {
+    scope: NonNullable<CacheControlDirective['scope']>;
+    metadata: {
+      privateProperty?: string;
+    };
+  };
 }) => MaybePromise<string>;
 
 export type GetDocumentStringFunction = (executionArgs: ExecutionArgs) => string;
@@ -295,20 +304,38 @@ const getDocumentWithMetadataAndTTL = memoize4(function addTypeNameToDocument(
   return [visit(document, visitWithTypeInfo(typeInfo, visitor)), ttl];
 });
 
-type CacheControlDirective = {
+export type CacheControlDirective = {
   maxAge?: number;
   scope?: 'PUBLIC' | 'PRIVATE';
 };
 
+export let schema: GraphQLSchema;
+let ttlPerSchemaCoordinate: Record<string, CacheControlDirective['maxAge']> = {};
+let scopePerSchemaCoordinate: Record<string, CacheControlDirective['scope']> = {};
+
+export function isPrivate(
+  typeName: string,
+  data?: Record<string, NonNullable<CacheControlDirective['scope']>>,
+): boolean {
+  if (scopePerSchemaCoordinate[typeName] === 'PRIVATE') {
+    return true;
+  }
+  return data
+    ? Object.keys(data).some(
+        fieldName => scopePerSchemaCoordinate[`${typeName}.${fieldName}`] === 'PRIVATE',
+      )
+    : false;
+}
+
 export function useResponseCache<PluginContext extends Record<string, any> = {}>({
   cache = createInMemoryCache(),
   ttl: globalTtl = Infinity,
   session,
   enabled,
   ignoredTypes = [],
   ttlPerType,
-  ttlPerSchemaCoordinate = {},
-  scopePerSchemaCoordinate = {},
+  ttlPerSchemaCoordinate: localTtlPerSchemaCoordinate = {},
+  scopePerSchemaCoordinate: localScopePerSchemaCoordinate = {},
   idFields = ['id'],
   invalidateViaMutation = true,
   buildResponseCacheKey = defaultBuildResponseCacheKey,
@@ -326,7 +353,7 @@ export function useResponseCache<PluginContext extends Record<string, any> = {}>
   enabled = enabled ? memoize1(enabled) : enabled;
 
   // never cache Introspections
-  ttlPerSchemaCoordinate = { 'Query.__schema': 0, ...ttlPerSchemaCoordinate };
+  ttlPerSchemaCoordinate = { 'Query.__schema': 0, ...localTtlPerSchemaCoordinate };
   if (ttlPerType) {
     // eslint-disable-next-line no-console
     console.warn(
@@ -341,8 +368,8 @@ export function useResponseCache<PluginContext extends Record<string, any> = {}>
     queries: { invalidateViaMutation, ttlPerSchemaCoordinate },
     mutations: { invalidateViaMutation }, // remove ttlPerSchemaCoordinate for mutations to skip TTL calculation
   };
+  scopePerSchemaCoordinate = { ...localScopePerSchemaCoordinate };
   const idFieldByTypeName = new Map<string, string>();
-  let schema: any;
 
   function isPrivate(typeName: string, data: Record<string, unknown>): boolean {
     if (scopePerSchemaCoordinate[typeName] === 'PRIVATE') {
@@ -558,13 +585,26 @@ export function useResponseCache<PluginContext extends Record<string, any> = {}>
 
       return handleMaybePromise(
         () =>
-          buildResponseCacheKey({
-            documentString: getDocumentString(onExecuteParams.args),
-            variableValues: onExecuteParams.args.variableValues,
-            operationName: onExecuteParams.args.operationName,
-            sessionId,
-            context: onExecuteParams.args.contextValue,
-          }),
+          buildResponseCacheKey(
+            new Proxy(
+              {
+                documentString: getDocumentString(onExecuteParams.args),
+                variableValues: onExecuteParams.args.variableValues,
+                operationName: onExecuteParams.args.operationName,
+                sessionId,
+                context: onExecuteParams.args.contextValue,
+                extras: undefined as any,
+              },
+              {
+                get: (obj, prop) => {
+                  if (prop === 'extras') {
+                    return getScopeFromQuery(schema, onExecuteParams.args.document.loc.source.body);
+                  }
+                  return obj[prop as keyof typeof obj];
+                },
+              },
+            ),
+          ),
         cacheKey => {
           const cacheInstance = cacheFactory(onExecuteParams.args.contextValue);
           if (cacheInstance == null) {