feat(js-sdk): circuit breaker and cdn mirror for CDN apis

.changeset/calm-mails-sneeze.md

@@ -0,0 +1,55 @@
+---
+'@graphql-hive/core': minor
+'@graphql-hive/apollo': minor
+'@graphql-hive/yoga': minor
+---
+
+**Persisted Documents Improvements**
+
+Persisted documents now support specifying a mirror endpoint that will be used in case the main CDN
+is unreachable. Provide an array of endpoints to the client configuration.
+
+```ts
+import { createClient } from '@graphql-hive/core'
+
+const client = createClient({
+  experimental__persistedDocuments: {
+    cdn: {
+      endpoint: [
+        'https://cdn.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688',
+        'https://cdn-mirror.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688'
+      ],
+      accessToken: ''
+    }
+  }
+})
+```
+
+In addition to that, the underlying logic for looking up documents now uses a circuit breaker. If a
+single endpoint is unreachable, further lookups on that endpoint are skipped.
+
+The behaviour of the circuit breaker can be customized via the `circuitBreaker` configuration.
+
+```ts
+import { createClient } from '@graphql-hive/core'
+
+const client = createClient({
+  experimental__persistedDocuments: {
+    cdn: {
+      endpoint: [
+        'https://cdn.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688',
+        'https://cdn-mirror.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688'
+      ],
+      accessToken: ''
+    },
+    circuitBreaker: {
+      // open circuit if 50 percent of request result in an error
+      errorThresholdPercentage: 50,
+      // start monitoring the circuit after 10 requests
+      volumeThreshold: 10,
+      // time before the backend is tried again after the circuit is open
+      resetTimeout: 30_000
+    }
+  }
+})
+```

.changeset/nine-worlds-slide.md

@@ -0,0 +1,43 @@
+---
+'@graphql-hive/apollo': minor
+---
+
+**Supergraph Manager Improvements**
+
+Persisted documents now support specifying a mirror endpoint that will be used in case the main CDN
+is unreachable. Provide an array of endpoints to the supergraph manager configuration.
+
+```ts
+import { createSupergraphManager } from '@graphql-hive/apollo'
+
+const supergraphManager = createSupergraphManager({
+  endpoint: [
+    'https://cdn.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688/supergraph',
+    'https://cdn-mirror.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688/supergraph'
+  ],
+  key: ''
+})
+```
+
+In addition to that, the underlying logic for looking up documents now uses a circuit breaker. If a
+single endpoint is unreachable, further lookups on that endpoint are skipped.
+
+```ts
+import { createSupergraphManager } from '@graphql-hive/apollo'
+
+const supergraphManager = createSupergraphManager({
+  endpoint: [
+    'https://cdn.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688/supergraph',
+    'https://cdn-mirror.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688/supergraph'
+  ],
+  key: '',
+  circuitBreaker: {
+    // open circuit if 50 percent of request result in an error
+    errorThresholdPercentage: 50,
+    // start monitoring the circuit after 10 requests
+    volumeThreshold: 10,
+    // time before the backend is tried again after the circuit is open
+    resetTimeout: 30_000
+  }
+})
+```

.changeset/upset-lemons-reply.md

@@ -0,0 +1,25 @@
+---
+'@graphql-hive/core': minor
+---
+
+**New CDN Artifact Fetcher**
+
+We have a new interface for fetching CDN artifacts (such as supergraph and services) with a cache
+from the CDN. This fetcher supports providing a mirror endpoint and comes with a circuit breaker
+under the hood.
+
+```ts
+const supergraphFetcher = createCDNArtifactFetcher({
+  endpoint: [
+    'https://cdn.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688',
+    'https://cdn-mirror.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688'
+  ],
+  accessKey: ''
+})
+
+supergraphFetcher.fetch()
+```
+
+---
+
+`createSupergraphSDLFetcher` is now deprecated. Please upgrade to use `createCDNArtifactFetcher`.

packages/libraries/apollo/package.json

@@ -47,7 +47,8 @@
     "graphql": "^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0"
   },
   "dependencies": {
-    "@graphql-hive/core": "workspace:*"
+    "@graphql-hive/core": "workspace:*",
+    "@graphql-hive/logger": "^1.0.9"
   },
   "devDependencies": {
     "@apollo/server": "5.0.0",

packages/libraries/apollo/src/index.ts

@@ -2,13 +2,15 @@ import { GraphQLError, type DocumentNode } from 'graphql';
 import type { ApolloServerPlugin, HTTPGraphQLRequest } from '@apollo/server';
 import {
   autoDisposeSymbol,
+  createCDNArtifactFetcher,
   createHive as createHiveClient,
-  createSupergraphSDLFetcher,
   HiveClient,
   HivePluginOptions,
   isHiveClient,
-  SupergraphSDLFetcherOptions,
+  joinUrl,
+  type CircuitBreakerConfiguration,
 } from '@graphql-hive/core';
+import { Logger } from '@graphql-hive/logger';
 import { version } from './version.js';
 
 export {
@@ -17,34 +19,83 @@ 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 | [string, 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?: CircuitBreakerConfiguration;
+  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 logger = args.logger ?? new Logger({ level: false });
+  const pollIntervalInMs = args.pollIntervalInMs ?? 30_000;
+  let endpoints = Array.isArray(args.endpoint) ? args.endpoint : [args.endpoint];
+
+  const endpoint = endpoints.map(endpoint =>
+    endpoint.endsWith('/supergraph') ? endpoint : joinUrl(endpoint, 'supergraph'),
+  );
+
+  const artifactsFetcher = createCDNArtifactFetcher({
+    endpoint: endpoint as [string, string],
+    accessKey: args.key,
+    client: {
+      name: args.name ?? '@graphql-hive/apollo',
+      version: args.version ?? version,
+    },
+    logger,
+    fetch: args.fetchImplementation,
+    circuitBreaker: args.circuitBreaker,
+  });
+
   let timer: ReturnType<typeof setTimeout> | null = null;
 
   return {
     async initialize(hooks: { update(supergraphSdl: string): void }): Promise<{
       supergraphSdl: string;
       cleanup?: () => Promise<void>;
     }> {
-      const initialResult = await fetchSupergraph();
+      const initialResult = await artifactsFetcher.fetch();
 
       function poll() {
         timer = setTimeout(async () => {
           try {
-            const result = await fetchSupergraph();
-            if (result.supergraphSdl) {
-              hooks.update?.(result.supergraphSdl);
+            const result = await artifactsFetcher.fetch();
+            if (result.contents) {
+              hooks.update?.(result.contents);
             }
           } catch (error) {
-            console.error(
-              `Failed to update supergraph: ${error instanceof Error ? error.message : error}`,
-            );
+            logger.error({ error }, `Failed to update supergraph.`);
           }
           poll();
         }, pollIntervalInMs);
@@ -53,11 +104,12 @@ export function createSupergraphManager({
       poll();
 
       return {
-        supergraphSdl: initialResult.supergraphSdl,
+        supergraphSdl: initialResult.contents,
         cleanup: async () => {
           if (timer) {
             clearTimeout(timer);
           }
+          artifactsFetcher.dispose();
         },
       };
     },

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

@@ -1,35 +1,15 @@
 import CircuitBreaker from '../circuit-breaker/circuit.js';
 import { version } from '../version.js';
+import {
+  CircuitBreakerConfiguration,
+  defaultCircuitBreakerConfiguration,
+} from './circuit-breaker.js';
 import { http } from './http-client.js';
 import type { LegacyLogger } from './types.js';
 import { chooseLogger } from './utils.js';
 
 type ReadOnlyResponse = Pick<Response, 'status' | 'text' | 'json' | 'statusText'>;
 
-export type AgentCircuitBreakerConfiguration = {
-  /**
-   * 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: AgentCircuitBreakerConfiguration = {
-  errorThresholdPercentage: 50,
-  volumeThreshold: 10,
-  resetTimeout: 30_000,
-};
-
 export interface AgentOptions {
   enabled?: boolean;
   name?: string;
@@ -80,7 +60,7 @@ export interface AgentOptions {
    * false -> Disable
    * object -> use custom configuration see {AgentCircuitBreakerConfiguration}
    */
-  circuitBreaker?: boolean | AgentCircuitBreakerConfiguration;
+  circuitBreaker?: boolean | CircuitBreakerConfiguration;
   /**
    * WHATWG Compatible fetch implementation
    * used by the agent to send reports
@@ -105,7 +85,7 @@ export function createAgent<TEvent>(
   },
 ) {
   const options: Required<Omit<AgentOptions, 'fetch' | 'debug' | 'logger' | 'circuitBreaker'>> & {
-    circuitBreaker: AgentCircuitBreakerConfiguration | null;
+    circuitBreaker: CircuitBreakerConfiguration | null;
   } = {
     timeout: 30_000,
     enabled: true,