Merge pull request #4236 from apollographql/sachin/remove-experimenta…

…l-from-schema-reporting

schema-reporting: Options renaming + remove experimental_ prefix

CHANGELOG.md

@@ -18,6 +18,7 @@ The version headers in this history reflect the versions of Apollo Server itself
 - `apollo-engine-reporting`: The schema reporting URL has been changed to use the new dedicated sub-domain `https://edge-server-reporting.api.apollographql.com`. [PR #4232](https://github.com/apollographql/apollo-server/pull/4232)
 - `apollo-server-core`: Though Apollo Server **is not affected** due to the way it is integrated, in response to [an upstream security advisory for GraphQL Playground](https://github.com/prisma-labs/graphql-playground/security/advisories/GHSA-4852-vrh7-28rf) we have published [the same patch](https://github.com/prisma-labs/graphql-playground/commit/bf1883db538c97b076801a60677733816cb3cfb7) on our `@apollographql/graphql-playground-html` fork and bumped Apollo Server to use it.  Again, this was done out of an **abundance of caution** since the way that Apollo Server utilizes `renderPlaygroundPage` is _not_ vulnerable as it does not allow per-request Playground configuration that could allow interpolation of user-input. [PR #4231](https://github.com/apollographql/apollo-server/pull/4231)
 - `apollo-engine-reporting`: Make Apollo Server throw if schema reporting is enabled for a gateway or federated service. [PR #4246](https://github.com/apollographql/apollo-server/pull/4246)
+- `apollo-engine-reporting`: Remove the `experimental_` prefix from schema reporting options, and specifically rename `experimental_schemaReporting` option name to `reportSchema`. (The old option names remain functional, but are deprecated.) [PR #4236](https://github.com/apollographql/apollo-server/pull/4236)
 
 ### v2.14.3
 

docs/source/api/apollo-server.md

@@ -512,3 +512,30 @@ addMockFunctionsToSchema({
    > [WARNING] If you specify a `clientReferenceId`, Graph Manager will treat the
    > `clientName` as a secondary lookup, so changing a `clientName` may result
    > in an unwanted experience.
+
+* `reportSchema`: boolean
+
+   Enables the automatic schema reporting feature of Apollo Server, which will
+   cause it to periodically report the server's schema (when changes are
+   detected) along with details about the runtime environment to Apollo Graph
+   Manager. This feature removes the need to register schemas manually via
+   `apollo service:push` in CI/CD pipelines.
+
+* `overrideReportedSchema`: string
+
+   By default, the schema reported to Apollo Graph Manager will be normalized,
+   which may shift ordering and comments and remove whitespace. This option can
+   be used to override the default schema. Any schema provided will not undergo
+   normalization, which can be helpful to preserve details that normalization
+   removes.
+
+* `schemaReportingInitialDelayMaxMs`: number
+
+   By default, the schema reporter will wait a random amount of time between 0
+   and 10 seconds before making its first report at reporter startup. A longer
+   range of times leads to more staggered starts, which reduces bandwidth
+   since it makes it less likely that multiple servers will get asked to upload
+   the same schema. However, in certain constrained environments (e.g. AWS
+   Lambda), this wait time may be less desirable. This option can be used to
+   change the maximum amount of time that the reporter will wait until it starts
+   sending reports.

packages/apollo-engine-reporting/src/__tests__/plugin.test.ts

@@ -108,7 +108,7 @@ describe('schema reporting', () => {
   it('uses the override schema', async () => {
     const pluginInstance = plugin(
       {
-        experimental_overrideReportedSchema: typeDefs,
+        overrideReportedSchema: typeDefs,
       },
       addTrace,
       {

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

@@ -329,10 +329,9 @@ export interface EngineReportingOptions<TContext> {
   generateClientInfo?: GenerateClientInfo<TContext>;
 
   /**
-   * **(Experimental)** Enable schema reporting from this server with
-   * Apollo Graph Manager.
+   * Enable schema reporting from this server with Apollo Graph Manager.
    *
-   * The use of this option avoids the need to rgister schemas manually within
+   * The use of this option avoids the need to register schemas manually within
    * CI deployment pipelines using `apollo schema:push` by periodically
    * reporting this server's schema (when changes are detected) along with
    * additional details about its runtime environment to Apollo Graph Manager.
@@ -341,14 +340,14 @@ export interface EngineReportingOptions<TContext> {
    * documentation_](https://github.com/apollographql/apollo-schema-reporting-preview-docs)
    * for more information.
    */
-  experimental_schemaReporting?: boolean;
+  reportSchema?: boolean;
 
   /**
    * Override the reported schema that is reported to AGM.
    * This schema does not go through any normalizations and the string is directly sent to Apollo Graph Manager.
    * This would be useful for comments or other ordering and whitespace changes that get stripped when generating a `GraphQLSchema`
    */
-  experimental_overrideReportedSchema?: string;
+  overrideReportedSchema?: string;
 
   /**
    * The schema reporter waits before starting reporting.
@@ -362,7 +361,7 @@ export interface EngineReportingOptions<TContext> {
    * This number will be the max for the range in ms that the schema reporter will
    * wait before starting to report.
    */
-  experimental_schemaReportingInitialDelayMaxMs?: number;
+  schemaReportingInitialDelayMaxMs?: number;
 
   /**
    * The URL to use for reporting schemas.
@@ -375,6 +374,21 @@ export interface EngineReportingOptions<TContext> {
    * `console` when that is not available.
    */
   logger?: Logger;
+
+  /**
+   * @deprecated use {@link reportSchema} instead
+   */
+  experimental_schemaReporting?: boolean;
+
+  /**
+   * @deprecated use {@link overrideReportedSchema} instead
+   */
+  experimental_overrideReportedSchema?: string;
+
+  /**
+   * @deprecated use {@link schemaReportingInitialDelayMaxMs} instead
+   */
+  experimental_schemaReportingInitialDelayMaxMs?: number;
 }
 
 export interface AddTraceArgs {
@@ -460,9 +474,44 @@ export class EngineReportingAgent<TContext = any> {
       );
     }
 
-
     if (options.experimental_schemaReporting !== undefined) {
-      this.schemaReport = options.experimental_schemaReporting;
+      this.logger.warn(
+        [
+          '[deprecated] The "experimental_schemaReporting" option has been',
+          'renamed to "reportSchema"'
+        ].join(' ')
+      );
+      if (options.reportSchema === undefined) {
+        options.reportSchema = options.experimental_schemaReporting;
+      }
+    }
+
+    if (options.experimental_overrideReportedSchema !== undefined) {
+      this.logger.warn(
+        [
+          '[deprecated] The "experimental_overrideReportedSchema" option has',
+          'been renamed to "overrideReportedSchema"'
+        ].join(' ')
+      );
+      if (options.overrideReportedSchema === undefined) {
+        options.overrideReportedSchema = options.experimental_overrideReportedSchema;
+      }
+    }
+
+    if (options.experimental_schemaReportingInitialDelayMaxMs !== undefined) {
+      this.logger.warn(
+        [
+          '[deprecated] The "experimental_schemaReportingInitialDelayMaxMs"',
+          'option has been renamed to "schemaReportingInitialDelayMaxMs"'
+        ].join(' ')
+      );
+      if (options.schemaReportingInitialDelayMaxMs === undefined) {
+        options.schemaReportingInitialDelayMaxMs = options.experimental_schemaReportingInitialDelayMaxMs;
+      }
+    }
+
+    if (options.reportSchema !== undefined) {
+      this.schemaReport = options.reportSchema;
     } else {
       this.schemaReport = process.env.APOLLO_SCHEMA_REPORTING === "true"
     }
@@ -730,12 +779,12 @@ export class EngineReportingAgent<TContext = any> {
     executableSchema: string;
   }) {
     this.logger.info('Starting schema reporter...');
-    if (this.options.experimental_overrideReportedSchema !== undefined) {
+    if (this.options.overrideReportedSchema !== undefined) {
       this.logger.info('Schema to report has been overridden');
     }
-    if (this.options.experimental_schemaReportingInitialDelayMaxMs !== undefined) {
+    if (this.options.schemaReportingInitialDelayMaxMs !== undefined) {
       this.logger.info(`Schema reporting max initial delay override: ${
-        this.options.experimental_schemaReportingInitialDelayMaxMs
+        this.options.schemaReportingInitialDelayMaxMs
       } ms`);
     }
     if (this.options.schemaReportingUrl !== undefined) {
@@ -773,7 +822,7 @@ export class EngineReportingAgent<TContext = any> {
     // Jitter the startup between 0 and 10 seconds
     const delay = Math.floor(
       Math.random() *
-        (this.options.experimental_schemaReportingInitialDelayMaxMs || 10_000),
+        (this.options.schemaReportingInitialDelayMaxMs || 10_000),
     );
 
     const schemaReporter = new SchemaReporter(

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

@@ -63,9 +63,9 @@ export const plugin = <TContext>(
       if (!schemaReport) return;
       startSchemaReporting({
         executableSchema:
-          options.experimental_overrideReportedSchema || printSchema(schema),
+          options.overrideReportedSchema || printSchema(schema),
         executableSchemaId: executableSchemaIdGenerator(
-          options.experimental_overrideReportedSchema || schema,
+          options.overrideReportedSchema || schema,
         ),
       });
     },
@@ -234,7 +234,7 @@ export const plugin = <TContext>(
           source: requestContext.source,
           trace: treeBuilder.trace,
           executableSchemaId: executableSchemaIdGenerator(
-            options.experimental_overrideReportedSchema || schema,
+            options.overrideReportedSchema || schema,
           ),
           logger,
         }).catch(logger.error);