feat: circuit breaker for supergraph fetcher

Author: n1ru4l

packages/libraries/apollo/src/index.ts

@@ -2,12 +2,14 @@ import { GraphQLError, type DocumentNode } from 'graphql';
 import type { ApolloServerPlugin, HTTPGraphQLRequest } from '@apollo/server';
 import {
   autoDisposeSymbol,
+  CDNArtifactFetcherCircuitBreakerConfiguration,
+  createCDNArtifactFetcher,
   createHive as createHiveClient,
-  createSupergraphSDLFetcher,
   HiveClient,
   HivePluginOptions,
   isHiveClient,
-  SupergraphSDLFetcherOptions,
+  joinUrl,
+  Logger,
 } from '@graphql-hive/core';
 import { version } from './version.js';
 
@@ -17,14 +19,62 @@ export {
   createServicesFetcher,
   createSupergraphSDLFetcher,
 } from '@graphql-hive/core';
+
+/** @deprecated Use {CreateSupergraphManagerArgs} instead */
 export type { SupergraphSDLFetcherOptions } from '@graphql-hive/core';
 
-export function createSupergraphManager({
-  pollIntervalInMs,
-  ...superGraphFetcherOptions
-}: { pollIntervalInMs?: number } & SupergraphSDLFetcherOptions) {
-  pollIntervalInMs = pollIntervalInMs ?? 30_000;
-  const fetchSupergraph = createSupergraphSDLFetcher(superGraphFetcherOptions);
+/**
+ * Configuration for {createSupergraphManager}.
+ */
+export type CreateSupergraphManagerArgs = {
+  /**
+   * The artifact endpoint to poll.
+   * E.g. `https://cdn.graphql-hive.com/<uuid>/supergraph`
+   */
+  endpoint: string;
+  /**
+   * The CDN access key for fetching artifact.
+   */
+  key: string;
+  logger?: Logger;
+  /**
+   * The supergraph poll interval in milliseconds
+   * Default: 30_000
+   */
+  pollIntervalInMs?: number;
+  /** Circuit breaker configuration override. */
+  circuitBreaker?: CDNArtifactFetcherCircuitBreakerConfiguration;
+  fetchImplementation?: typeof fetch;
+  /**
+   * Client name override
+   * Default: `@graphql-hive/apollo`
+   */
+  name?: string;
+  /**
+   * Client version override
+   * Default: currents package version
+   */
+  version?: string;
+};
+
+export function createSupergraphManager(args: CreateSupergraphManagerArgs) {
+  const pollIntervalInMs = args.pollIntervalInMs ?? 30_000;
+  const endpoint = args.endpoint.endsWith('/supergraph')
+    ? args.endpoint
+    : joinUrl(args.endpoint, 'supergraph');
+
+  const fetchSupergraph = createCDNArtifactFetcher({
+    endpoint,
+    accessKey: args.key,
+    client: {
+      name: args.name ?? '@graphql-hive/apollo',
+      version: args.version ?? version,
+    },
+    logger: args.logger,
+    fetch: args.fetchImplementation,
+    circuitBreaker: args.circuitBreaker,
+  });
+
   let timer: ReturnType<typeof setTimeout> | null = null;
 
   return {
@@ -38,8 +88,8 @@ export function createSupergraphManager({
         timer = setTimeout(async () => {
           try {
             const result = await fetchSupergraph();
-            if (result.supergraphSdl) {
-              hooks.update?.(result.supergraphSdl);
+            if (result.contents) {
+              hooks.update?.(result.contents);
             }
           } catch (error) {
             console.error(
@@ -53,7 +103,7 @@ export function createSupergraphManager({
       poll();
 
       return {
-        supergraphSdl: initialResult.supergraphSdl,
+        supergraphSdl: initialResult.contents,
         cleanup: async () => {
           if (timer) {
             clearTimeout(timer);

packages/libraries/core/src/client/artifacts.ts

@@ -0,0 +1,144 @@
+import CircuitBreaker from '../circuit-breaker/circuit.js';
+import { version } from '../version.js';
+import { http } from './http-client.js';
+import type { Logger } from './types.js';
+import { createHash, createHiveLogger } from './utils.js';
+
+export type CDNArtifactFetcherCircuitBreakerConfiguration = {
+  /**
+   * Percentage after what the circuit breaker should kick in.
+   * Default: 50
+   */
+  errorThresholdPercentage: number;
+  /**
+   * Count of requests before starting evaluating.
+   * Default: 5
+   */
+  volumeThreshold: number;
+  /**
+   * After what time the circuit breaker is attempting to retry sending requests in milliseconds
+   * Default: 30_000
+   */
+  resetTimeout: number;
+};
+
+const defaultCircuitBreakerConfiguration: CDNArtifactFetcherCircuitBreakerConfiguration = {
+  errorThresholdPercentage: 50,
+  volumeThreshold: 10,
+  resetTimeout: 30_000,
+};
+
+type CreateCDNArtifactFetcherArgs = {
+  endpoint: string;
+  accessKey: string;
+  /** client meta data */
+  client?: {
+    name: string;
+    version: string;
+  };
+  circuitBreaker?: CDNArtifactFetcherCircuitBreakerConfiguration;
+  logger?: Logger;
+  fetch?: typeof fetch;
+};
+
+type CDNFetcherArgs = {
+  logger?: Logger;
+  fetch?: typeof fetch;
+};
+
+type CDNFetchResult = {
+  /** Text contents of the artifact */
+  contents: string;
+  /** SHA-256 Hash */
+  hash: string;
+  /** Schema Version ID as on Hive Console (optional) */
+  schemaVersionId: null | string;
+};
+
+function isRequestOk(response: Response) {
+  return response.status === 304 || response.ok;
+}
+
+/**
+ * Create a handler for fetching a CDN artifact with built-in cache and circuit breaker.
+ * It is intended for polling supergraph, schema sdl or services.
+ */
+export function createCDNArtifactFetcher(args: CreateCDNArtifactFetcherArgs) {
+  let cacheETag: string | null = null;
+  let cached: CDNFetchResult | null = null;
+  const clientInfo = args.client ?? { name: 'hive-client', version };
+  const circuitBreakerConfig = args.circuitBreaker ?? defaultCircuitBreakerConfiguration;
+
+  const circuitBreaker = new CircuitBreaker(
+    function runFetch(fetchArgs?: CDNFetcherArgs) {
+      const signal = circuitBreaker.getSignal();
+      const logger = createHiveLogger(fetchArgs?.logger ?? args.logger ?? console, '');
+      const fetchImplementation = fetchArgs?.fetch ?? args.fetch;
+
+      const headers: {
+        [key: string]: string;
+      } = {
+        'X-Hive-CDN-Key': args.accessKey,
+        'User-Agent': `${clientInfo.name}/${clientInfo.version}`,
+      };
+
+      if (cacheETag) {
+        headers['If-None-Match'] = cacheETag;
+      }
+
+      return http.get(args.endpoint, {
+        headers,
+        isRequestOk,
+        retry: {
+          retries: 10,
+          maxTimeout: 200,
+          minTimeout: 1,
+        },
+        logger,
+        fetchImplementation,
+        signal,
+      });
+    },
+    {
+      ...circuitBreakerConfig,
+      timeout: false,
+      autoRenewAbortController: true,
+    },
+  );
+
+  return async function fetchArtifact(fetchArgs?: CDNFetcherArgs): Promise<CDNFetchResult> {
+    try {
+      const response = await circuitBreaker.fire(fetchArgs);
+
+      if (response.status === 304) {
+        if (cached !== null) {
+          return cached;
+        }
+        throw new Error('This should never happen.');
+      }
+
+      const contents = await response.text();
+      const result: CDNFetchResult = {
+        hash: await createHash('SHA-256').update(contents).digest('base64'),
+        contents,
+        schemaVersionId: response.headers.get('x-hive-schema-version-id') || null,
+      };
+
+      const etag = response.headers.get('etag');
+      if (etag) {
+        cached = result;
+        cacheETag = etag;
+      }
+
+      return result;
+    } catch (err) {
+      if (err instanceof Error && 'code' in err && err.code === 'EOPENBREAKER') {
+        if (cached) {
+          return cached;
+        }
+      }
+
+      throw err;
+    }
+  };
+}

packages/libraries/core/src/client/supergraph.ts

@@ -3,6 +3,9 @@ import { http } from './http-client.js';
 import type { Logger } from './types.js';
 import { createHash, joinUrl } from './utils.js';
 
+/**
+ * @deprecated Please use {createCDNArtifactFetcher} instead of createSupergraphSDLFetcher.
+ */
 export interface SupergraphSDLFetcherOptions {
   endpoint: string;
   key: string;
@@ -12,6 +15,9 @@ export interface SupergraphSDLFetcherOptions {
   version?: string;
 }
 
+/**
+ * @deprecated Please use {createCDNArtifactFetcher} instead.
+ */
 export function createSupergraphSDLFetcher(options: SupergraphSDLFetcherOptions) {
   let cacheETag: string | null = null;
   let cached: {

packages/libraries/core/src/index.ts

@@ -13,3 +13,7 @@ export { isHiveClient, isAsyncIterable, createHash, joinUrl } from './client/uti
 export { http, URL } from './client/http-client.js';
 export { createSupergraphSDLFetcher } from './client/supergraph.js';
 export type { SupergraphSDLFetcherOptions } from './client/supergraph.js';
+export {
+  createCDNArtifactFetcher,
+  type CDNArtifactFetcherCircuitBreakerConfiguration,
+} from './client/artifacts.js';