Add callback when fetching a supergraph from Apollo Uplink fails

[benweatherman]

When polling Uplink fails, it's nice to have a fallback to load the supergraph from somewhere else.

This change exposes UplinkSupergraphManager (the artist formerly known as UplinkFetcher). It also adds config options for onFailureToFetchSupergraphSdlDuringInit and onFailureToFetchSupergraphSdlAfterInit that will be called if fetching from Uplink fails. It can return a string that will be used to update the supergraph schema. onFailureToFetchSupergraphSdlAfterInit can return null to signal the gateway should continue to use the existing schema.

Basic usage looks like the following:

import { promises } from 'fs';
import * as path from 'path';
import { ApolloServer } from 'apollo-server';
import { ApolloGateway, UplinkSupergraphManager } from '@apollo/gateway';

const gateway = new ApolloGateway({
  debug: true,
  supergraphSdl: new UplinkSupergraphManager({
    apiKey: process.env.APOLLO_KEY + "x", // Adding a "x" to artificially ensure we have an invalid key
    graphRef: process.env.APOLLO_GRAPH_REF,
    initialMaxRetries: 0, // Don't retry during initialization phase, so fallback is called sooner
    async onFailureToFetchSupergraphSdlDuringInit({ error, graphRef, logger }) {
      const filePath = path.resolve(__dirname, 'supergraph.graphql');
      logger.info(`Falling back to cached graph for ${graphRef} during init due to ${error}, loading from ${filePath}`);
      return promises.readFile(filePath, {encoding: 'utf8'});
    },
    async onFailureToFetchSupergraphSdlAfterInit({ error, graphRef, logger, fetchCount }) {
      const filePath = path.resolve(__dirname, 'supergraph.graphql');
      logger.info(`Falling back to cached graph for ${graphRef} after init due to ${error}, loading from ${filePath} (fetch count: ${fetchCount})`);
      return null;
    }
  }),
});
const server = new ApolloServer({ gateway });

server
  .listen()
  .then(({ url }) => {
    console.log(`🚀 Gateway ready at ${url}`);
  })
  .catch((err) => {
    console.error(err);
  });

Fixes #1801

TODO

• Unit tests
• Ensure good errors if callback provides invalid schema
• Make it easier to use UplinkSupergraphManager defaults

Things that aren't here

1. I started refactoring UplinkSupergraphManager into its own package so we could make big changes without needing to make a major version bump in the gateway. That requires making another package that holds just the types, so it can be used by the new uplink supergraph manager package and the gateway. That complicates the release slightly because we'd potentially want to version those separately (since the whole reason for breaking it out is to have the option of making breaking changes). It doesn't seem like the benefit is worth the effort and ongoing maintenance.
2. I thought about making onFailureToUpdateSupergraphSdl a function on gateway (in line with onSchemaLoadOrUpdate), but that seemed like a larger refactor and can still be added in the future. That also has a slightly different mechanism than onFailureToFetchSupergraphSdl.

[netlify]

✅ Deploy Preview for apollo-federation-docs canceled.

Name	Link
🔨 Latest commit	0434ecd
🔍 Latest deploy log	https://app.netlify.com/sites/apollo-federation-docs/deploys/62aa37cd18d21100099fec15

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

[benweatherman]

Moved this back to a draft while I add some unit tests

[lennyburdette]

What do you think about also providing a function for generating the default config values? All that code lives within the ApolloGateway constructor right now. Something like:

const gateway = new ApolloGateway({
  debug: true,
  supergraphSdl: new UplinkFetcher({
    ...uplinkFetcherDefaults(),
    async updateSupergraphSdlFailureCallback(this: UplinkFetcher, { error }: {error: Error}): Promise<string> {
      // ...
    },
  }),
});

[benweatherman]

@lennyburdette great suggestion! I'll incorporate that as well.

[lennyburdette]

any progress on this? i'd love to update the fallback demos to use this approach!

[benweatherman]

@lennyburdette Thanks for the ping! I just finished up some tests and refactoring how the config works. I started down the path of adding a uplinkFetcherDefaults function, but it seemed better for everyone to implement better defaults in the UplinkFetcher constructor. Thoughts on that approach?

Also, the idea came up of publishing UplinkFetcher as a separate package so we can iterate on features a bit faster if folks are gonna be using it directly. Any idea how useful that will be?

Finally, I could see this callback on failure being useful across other supergraph managers, so I'm wondering if we want a more generic mechanism than adding it to UplinkFetcher. This would probably be something similar to onSchemaLoadOrUpdate (possibly onSchemaLoadOrUpdateError).

[lennyburdette]

Moving the default values to the UplinkFetcher itself makes sense! Hopefully makes the ApolloGateway class a little simpler too.

[lleadbet]

As a small comment/request- would it be possible to get the timestamp of the cachedSDL's last update for the onFailureToFetchSupergraphSdlAfterInit? To @lennyburdette's earlier point, serving outdated schemas would be bad, but if users could detect when it was last updated, they may be able to then confirm a new schema may be available via fallback.

[benweatherman]

@lleadbet Thanks for the suggestion! I added a mostRecentSuccessfulFetchAt param. Does that give you the info you're looking for?

[glasser]

Was it intentional that this PR changed the default log level to DEBUG?

[benweatherman]

Nope, good catch! Documented and fixed as part of this issue #2047