feat(runtime): new cache related hooks (#743)

Author: ardatan

.changeset/tasty-actors-marry.md

@@ -0,0 +1,18 @@
+---
+'@graphql-hive/gateway-runtime': minor
+---
+
+New Cache related hooks;
+
+`onCacheGet`: invoked when a cache get operation is performed.
+`onCacheMiss`: invoked when the performed get operation does not find a cache entry.
+`onCacheHit`: invoked when the performed get operation finds a cache entry.
+`onCacheGetError`: invoked when an error occurs during a cache get operation.
+
+`onCacheSet`: invoked when a cache set operation is performed.
+`onCacheSetDone`: invoked when the performed set operation is completed.
+`onCacheSetError`: invoked when an error occurs during a cache set operation.
+
+`onCacheDelete`: invoked when a cache delete operation is performed.
+`onCacheDeleteDone`: invoked when the performed delete operation is completed.
+`onCacheDeleteError`: invoked when an error occurs during a cache delete operation.

packages/runtime/src/createGatewayRuntime.ts

@@ -24,7 +24,12 @@ import { useHmacUpstreamSignature } from '@graphql-mesh/hmac-upstream-signature'
 import useMeshHive from '@graphql-mesh/plugin-hive';
 import useMeshResponseCache from '@graphql-mesh/plugin-response-cache';
 import { TransportContext } from '@graphql-mesh/transport-common';
-import type { Logger, OnDelegateHook, OnFetchHook } from '@graphql-mesh/types';
+import type {
+  KeyValueCache,
+  Logger,
+  OnDelegateHook,
+  OnFetchHook,
+} from '@graphql-mesh/types';
 import {
   getHeadersObj,
   getInContextSDK,
@@ -85,6 +90,7 @@ import {
   UnifiedGraphSchema,
 } from './handleUnifiedGraphConfig';
 import landingPageHtml from './landing-page-html';
+import { useCacheDebug } from './plugins/useCacheDebug';
 import { useContentEncoding } from './plugins/useContentEncoding';
 import { useCustomAgent } from './plugins/useCustomAgent';
 import { useDelegationPlanDebug } from './plugins/useDelegationPlanDebug';
@@ -103,12 +109,16 @@ import type {
   GatewayContext,
   GatewayHiveCDNOptions,
   GatewayPlugin,
+  OnCacheDeleteHook,
+  OnCacheGetHook,
+  OnCacheSetHook,
   UnifiedGraphConfig,
 } from './types';
 import {
   checkIfDataSatisfiesSelectionSet,
   defaultQueryText,
   getExecuteFnFromExecutor,
+  wrapCacheWithHooks,
 } from './utils';
 
 // TODO: this type export is not properly accessible from graphql-yoga
@@ -152,13 +162,24 @@ export function createGatewayRuntime<
   }
 
   const onFetchHooks: OnFetchHook<GatewayContext>[] = [];
+  const onCacheGetHooks: OnCacheGetHook[] = [];
+  const onCacheSetHooks: OnCacheSetHook[] = [];
+  const onCacheDeleteHooks: OnCacheDeleteHook[] = [];
   const wrappedFetchFn = wrapFetchWithHooks(onFetchHooks);
+  const wrappedCache: KeyValueCache | undefined = config.cache
+    ? wrapCacheWithHooks({
+        cache: config.cache,
+        onCacheGet: onCacheGetHooks,
+        onCacheSet: onCacheSetHooks,
+        onCacheDelete: onCacheDeleteHooks,
+      })
+    : undefined;
 
   const configContext: GatewayConfigContext = {
     fetch: wrappedFetchFn,
     logger,
     cwd: config.cwd || (typeof process !== 'undefined' ? process.cwd() : ''),
-    cache: config.cache,
+    cache: wrappedCache,
     pubsub: config.pubsub,
   };
 
@@ -815,6 +836,15 @@ export function createGatewayRuntime<
         if (plugin.onDelegationStageExecute) {
           onDelegationStageExecuteHooks.push(plugin.onDelegationStageExecute);
         }
+        if (plugin.onCacheGet) {
+          onCacheGetHooks.push(plugin.onCacheGet);
+        }
+        if (plugin.onCacheSet) {
+          onCacheSetHooks.push(plugin.onCacheSet);
+        }
+        if (plugin.onCacheDelete) {
+          onCacheDeleteHooks.push(plugin.onCacheDelete);
+        }
       }
     },
   };
@@ -1022,6 +1052,7 @@ export function createGatewayRuntime<
       useSubgraphExecuteDebug(configContext),
       useFetchDebug(configContext),
       useDelegationPlanDebug(configContext),
+      useCacheDebug(configContext),
     );
     return 'Debug mode enabled';
   });

packages/runtime/src/plugins/useCacheDebug.ts

@@ -0,0 +1,50 @@
+import { Logger } from '@graphql-mesh/types';
+import { GatewayPlugin } from '../types';
+
+export function useCacheDebug<TContext extends Record<string, any>>(opts: {
+  logger: Logger;
+}): GatewayPlugin<TContext> {
+  return {
+    onCacheGet({ key }) {
+      return {
+        onCacheGetError({ error }) {
+          const cacheGetErrorLogger = opts.logger.child('cache-get-error');
+          cacheGetErrorLogger.error({ key, error });
+        },
+        onCacheHit({ value }) {
+          const cacheHitLogger = opts.logger.child('cache-hit');
+          cacheHitLogger.debug({ key, value });
+        },
+        onCacheMiss() {
+          const cacheMissLogger = opts.logger.child('cache-miss');
+          cacheMissLogger.debug({ key });
+        },
+      };
+    },
+    onCacheSet({ key, value, ttl }) {
+      return {
+        onCacheSetError({ error }) {
+          const cacheSetErrorLogger = opts.logger.child('cache-set-error');
+          cacheSetErrorLogger.error({ key, value, ttl, error });
+        },
+        onCacheSetDone() {
+          const cacheSetDoneLogger = opts.logger.child('cache-set-done');
+          cacheSetDoneLogger.debug({ key, value, ttl });
+        },
+      };
+    },
+    onCacheDelete({ key }) {
+      return {
+        onCacheDeleteError({ error }) {
+          const cacheDeleteErrorLogger =
+            opts.logger.child('cache-delete-error');
+          cacheDeleteErrorLogger.error({ key, error });
+        },
+        onCacheDeleteDone() {
+          const cacheDeleteDoneLogger = opts.logger.child('cache-delete-done');
+          cacheDeleteDoneLogger.debug({ key });
+        },
+      };
+    },
+  };
+}

packages/runtime/src/types.ts

@@ -92,8 +92,69 @@ export type GatewayPlugin<
 > = YogaPlugin<Partial<TPluginContext> & GatewayContext & TContext> &
   UnifiedGraphPlugin<Partial<TPluginContext> & GatewayContext & TContext> & {
     onFetch?: OnFetchHook<Partial<TPluginContext> & GatewayContext & TContext>;
+    onCacheGet?: OnCacheGetHook;
+    onCacheSet?: OnCacheSetHook;
+    onCacheDelete?: OnCacheDeleteHook;
   } & Partial<Disposable | AsyncDisposable>;
 
+export type OnCacheGetHook = (
+  payload: OnCacheGetHookEventPayload,
+) => MaybePromise<OnCacheGetHookResult | void>;
+
+export interface OnCacheGetHookEventPayload {
+  cache: KeyValueCache;
+  key: string;
+  ttl?: number;
+}
+
+export interface OnCacheGetHookResult {
+  onCacheHit?: OnCacheHitHook;
+  onCacheMiss?: OnCacheMissHook;
+  onCacheGetError?: OnCacheErrorHook;
+}
+
+export type OnCacheErrorHook = (payload: OnCacheErrorHookPayload) => void;
+
+export interface OnCacheErrorHookPayload {
+  error: Error;
+}
+
+export type OnCacheHitHook = (payload: OnCacheHitHookEventPayload) => void;
+export interface OnCacheHitHookEventPayload {
+  value: any;
+}
+export type OnCacheMissHook = () => void;
+
+export type OnCacheSetHook = (
+  payload: OnCacheSetHookEventPayload,
+) => MaybePromise<OnCacheSetHookResult | void>;
+
+export interface OnCacheSetHookResult {
+  onCacheSetDone?: () => void;
+  onCacheSetError?: OnCacheErrorHook;
+}
+
+export interface OnCacheSetHookEventPayload {
+  cache: KeyValueCache;
+  key: string;
+  value: any;
+  ttl?: number;
+}
+
+export type OnCacheDeleteHook = (
+  payload: OnCacheDeleteHookEventPayload,
+) => MaybePromise<OnCacheDeleteHookResult | void>;
+
+export interface OnCacheDeleteHookResult {
+  onCacheDeleteDone?: () => void;
+  onCacheDeleteError?: OnCacheErrorHook;
+}
+
+export interface OnCacheDeleteHookEventPayload {
+  cache: KeyValueCache;
+  key: string;
+}
+
 export interface GatewayConfigSupergraph<
   TContext extends Record<string, any> = Record<string, any>,
 > extends GatewayConfigSchemaBase<TContext> {