Support engine.graphVariant and APOLLO_GRAPH_VARIANT. (#3924)

Co-authored-by: Adam Zionts <adam@meteor.com>

Author: zionts

CHANGELOG.md

@@ -6,9 +6,9 @@ The version headers in this history reflect the versions of Apollo Server itself
 - [__CHANGELOG for `@apollo/federation`__](https://github.com/apollographql/apollo-server/blob/master/packages/apollo-federation/CHANGELOG.md)
 
 ### vNEXT
-
 > The changes noted within this `vNEXT` section have not been released yet.  New PRs and commits which introduce changes should include an entry in this `vNEXT` section as part of their development.  When a release is being prepared, a new header will be (manually) created below and the the appropriate changes within that release will be moved into the new section.
 
+- `apollo-engine-reporting`: Deprecated the `APOLLO_SCHEMA_TAG` environment variable in favor of its new name, `APOLLO_GRAPH_VARIANT`.  Similarly, within the `engine` configuration object, the `schemaTag` property has been renamed `graphVariant`.  The functionality remains otherwise unchanged, but their new names mirror the name used within Apollo Graph Manager.  Continued use of the now-deprecated names will result in deprecation warnings and support will be dropped completely in the next "major" update.  To avoid misconfiguration, a runtime error will be thrown if _both_ new and deprecated names are set. [PR #3855](https://github.com/apollographql/apollo-server/pull/3855)
 - Allow passing a `WebSocket.Server` to `ApolloServer.installSubscriptionHandlers`. [PR #2314](https://github.com/apollographql/apollo-server/pull/2314)
 
 ### v2.12.0

docs/source/federation/metrics.md

@@ -20,7 +20,7 @@ Ensure that all dependencies on `apollo-server` are at version `2.7.0` or higher
 
 These options will cause the Apollo gateway to collect tracing information from the underlying federated services and pass them on, along with the query plan, to the Apollo metrics ingress. Currently, only Apollo Server supports detailed metrics insights as an implementing service, but we would love to work with you to implement the protocol in other languages!
 
-> NOTE: By default, metrics will be reported to the `current` variant. To change the variant for reporting, set the `ENGINE_GRAPH_VARIANT` environment variable.
+> NOTE: By default, metrics will be reported to the `current` variant. To change the variant for reporting, set the `APOLLO_GRAPH_VARIANT` environment variable.
 
 ## How tracing data is exposed from a federated service
 

packages/apollo-engine-reporting/src/agent.ts

@@ -45,6 +45,29 @@ export type GenerateClientInfo<TContext> = (
   requestContext: GraphQLRequestContext<TContext>,
 ) => ClientInfo;
 
+// AS3: Drop support for deprecated bits.
+export function getEngineGraphVariant(engine: EngineReportingOptions<any> | boolean | undefined, logger: Logger = console): string | undefined {
+  if (engine === false) {
+    return;
+  } else if (typeof engine === 'object' && (engine.graphVariant || engine.schemaTag)) {
+    if (engine.graphVariant && engine.schemaTag) {
+      throw new Error('Cannot set both engine.graphVariant and engine.schemaTag. Please use engine.graphVariant.');
+    }
+    if (engine.schemaTag) {
+      logger.warn('[Deprecation warning] Usage of engine.schemaTag is deprecated. Please use engine.graphVariant instead.');
+    }
+    return engine.graphVariant || engine.schemaTag;
+  } else {
+    if (process.env.ENGINE_SCHEMA_TAG) {
+      logger.warn('[Deprecation warning] Usage of ENGINE_SCHEMA_TAG is deprecated. Please use APOLLO_GRAPH_VARIANT instead.');
+    }
+    if (process.env.ENGINE_SCHEMA_TAG && process.env.APOLLO_GRAPH_VARIANT) {
+      throw new Error('Cannot set both ENGINE_SCHEMA_TAG and APOLLO_GRAPH_VARIANT. Please use APOLLO_GRAPH_VARIANT.')
+    }
+    return process.env.APOLLO_GRAPH_VARIANT || process.env.ENGINE_SCHEMA_TAG;
+  }
+}
+
 export interface EngineReportingOptions<TContext> {
   /**
    * API key for the service. Get this from
@@ -222,6 +245,7 @@ export class EngineReportingAgent<TContext = any> {
   private options: EngineReportingOptions<TContext>;
   private logger: Logger = console;
   private apiKey: string;
+  private graphVariant: string;
   private reports: { [schemaHash: string]: FullTracesReport } = Object.create(
     null,
   );
@@ -240,6 +264,7 @@ export class EngineReportingAgent<TContext = any> {
     this.options = options;
     if (options.logger) this.logger = options.logger;
     this.apiKey = options.apiKey || process.env.ENGINE_API_KEY || '';
+    this.graphVariant = getEngineGraphVariant(options, this.logger) || '';
     if (!this.apiKey) {
       throw new Error(
         'To use EngineReportingAgent, you must specify an API key via the apiKey option or the ENGINE_API_KEY environment variable.',
@@ -303,12 +328,7 @@ export class EngineReportingAgent<TContext = any> {
       this.reportHeaders[schemaHash] = new ReportHeader({
         ...serviceHeaderDefaults,
         schemaHash,
-        schemaTag:
-          this.options.graphVariant
-          || this.options.schemaTag
-          || process.env.APOLLO_GRAPH_VARIANT
-          || process.env.ENGINE_SCHEMA_TAG
-          || '',
+        schemaTag: this.graphVariant,
       });
       // initializes this.reports[reportHash]
       this.resetReport(schemaHash);

packages/apollo-gateway/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 > The changes noted within this `vNEXT` section have not been released yet.  New PRs and commits which introduce changes should include an entry in this `vNEXT` section as part of their development.  When a release is being prepared, a new header will be (manually) created below and the the appropriate changes within that release will be moved into the new section.
 
+- Deprecated the `APOLLO_SCHEMA_TAG` environment variable in favor of its new name, `APOLLO_GRAPH_VARIANT`.  The functionality remains otherwise identical, but the new name mirrors the name used within Apollo Graph Manager.  Use of the now-deprecated name will result in a deprecation warning and support will be dropped completely in a future "major" update.  To avoid misconfiguration, runtime errors will be thrown if the new and deprecated name are _both_ set. [#3855](https://github.com/apollographql/apollo-server/pull/3855)
 - Cache stringified representations of downstream query bodies within the query plan to address performance implications incurred by repeatedly `print`ing the same`DocumentNode`s with the `graphql` printer.  This improvement is more pronounced on larger documents.  [PR #4018](https://github.com/apollographql/apollo-server/pull/4018)
 - Add inadvertently excluded `apollo-server-errors` runtime dependency. [#3927](https://github.com/apollographql/apollo-server/pull/3927)
 

packages/apollo-server-core/src/ApolloServer.ts

@@ -71,6 +71,7 @@ import {
 
 import { Headers } from 'apollo-server-env';
 import { buildServiceDefinition } from '@apollographql/apollo-tools';
+import {getEngineGraphVariant} from "apollo-engine-reporting/dist/agent";
 import { Logger } from "apollo-server-types";
 
 const NoIntrospection = (context: ValidationContext) => ({
@@ -98,22 +99,6 @@ function getEngineApiKey(engine: Config['engine']): string | undefined {
   return;
 }
 
-function getEngineGraphVariant(engine: Config['engine']): string | undefined {
-  if (engine === false) {
-    return;
-  } else if (typeof engine === 'object' && (engine.graphVariant || engine.schemaTag)) {
-    return engine.graphVariant || engine.schemaTag;
-  } else {
-    if (process.env.ENGINE_SCHEMA_TAG) {
-      console.warn('[Deprecation warning] Usage of ENGINE_SCHEMA_TAG is deprecated. Please use APOLLO_GRAPH_VARIANT instead.');
-    }
-    if (process.env.ENGINE_SCHEMA_TAG && process.env.APOLLO_GRAPH_VARIANT) {
-      throw new Error('Cannot set both ENGINE_SCHEMA_TAG and APOLLO_GRAPH_VARIANT. Please use APOLLO_GRAPH_VARIANT.')
-    }
-    return process.env.APOLLO_GRAPH_VARIANT || process.env.ENGINE_SCHEMA_TAG;
-  }
-}
-
 function getEngineServiceId(engine: Config['engine']): string | undefined {
   const engineApiKey = getEngineApiKey(engine);
   if (engineApiKey) {
@@ -446,7 +431,7 @@ export class ApolloServerBase {
         ),
       );
 
-      const graphVariant = getEngineGraphVariant(engine);
+      const graphVariant = getEngineGraphVariant(engine, this.logger);
       const engineConfig =
         this.engineApiKeyHash && this.engineServiceId
           ? {

packages/apollo-server-core/src/__tests__/ApolloServerBase.test.ts

@@ -30,6 +30,52 @@ describe('ApolloServerBase construction', () => {
     ).not.toThrow();
   });
 
+  it('succeeds when passed a graphVariant in construction', () => {
+    let serverBase;
+    expect(
+      () =>
+        new ApolloServerBase({
+          typeDefs,
+          resolvers,
+          engine: {
+            graphVariant: 'foo',
+            apiKey: 'not:real:key',
+          },
+        }).stop()
+    ).not.toThrow();
+  });
+
+  it('spits out a deprecation warning when passed a schemaTag in construction', () => {
+    const spyConsoleWarn = jest.spyOn(console, 'warn').mockImplementation();
+    expect(
+      () =>
+        new ApolloServerBase({
+          typeDefs,
+          resolvers,
+          engine: {
+            schemaTag: 'foo',
+            apiKey: 'not:real:key',
+          },
+        }).stop()
+    ).not.toThrow();
+    expect(spyConsoleWarn).toBeCalled();
+    spyConsoleWarn.mockRestore();
+  });
+
+  it('throws when passed a schemaTag and graphVariant in construction', () => {
+    expect(
+      () =>
+        new ApolloServerBase({
+          schema: buildServiceDefinition([{ typeDefs, resolvers }]).schema,
+          engine: {
+            schemaTag: 'foo',
+            graphVariant: 'heck',
+            apiKey: 'not:real:key',
+          },
+        }),
+    ).toThrow();
+  });
+
   it('throws when a GraphQLSchema is not provided to the schema configuration option', () => {
     expect(() => {
       new ApolloServerBase({