@depup/apollo__server 5.5.0-depup.0

package/src/plugin/inlineTrace/index.ts

@@ -0,0 +1,156 @@
+import { Trace } from '@apollo/usage-reporting-protobuf';
+import { TraceTreeBuilder } from '../traceTreeBuilder.js';
+import type { SendErrorsOptions } from '../usageReporting/index.js';
+import { internalPlugin } from '../../internalPlugin.js';
+import { schemaIsSubgraph } from '../schemaIsSubgraph.js';
+import type { ApolloServerPlugin } from '../../externalTypes/index.js';
+
+export interface ApolloServerPluginInlineTraceOptions {
+  /**
+   * By default, if a trace contains errors, the errors are included in the
+   * trace with the message `<masked>`. The errors are associated with specific
+   * paths in the operation, but do not include the original error message or
+   * any extensions such as the error `code`, as those details may contain your
+   * users' private data. The extension `maskedBy:
+   * 'ApolloServerPluginInlineTrace'` is added.
+   *
+   * If you'd like details about the error included in traces, set this option.
+   * This option can take several forms:
+   *
+   * - { masked: true }: mask error messages and omit extensions (DEFAULT)
+   * - { unmodified: true }: include all error messages and extensions
+   * - { transform: ... }: a custom function for transforming errors. This
+   *   function receives a `GraphQLError` and may return a `GraphQLError`
+   *   (either a new error, or its potentially-modified argument) or `null`.
+   *   This error is used in the trace; if `null`, the error is not included in
+   *   traces or error statistics.
+   */
+  includeErrors?: SendErrorsOptions;
+  /**
+   * This option is for internal use by `@apollo/server` only.
+   *
+   * By default we want to enable this plugin for subgraph schemas only, but we
+   * need to come up with our list of plugins before we have necessarily loaded
+   * the schema. So (unless the user installs this plugin or
+   * ApolloServerPluginInlineTraceDisabled themselves), `@apollo/server` always
+   * installs this plugin and uses this option to make sure traces are only
+   * included if the schema appears to be a subgraph.
+   */
+  __onlyIfSchemaIsSubgraph?: boolean;
+}
+
+// This ftv1 plugin produces a base64'd Trace protobuf containing only the
+// durationNs, startTime, endTime, and root fields.  This output is placed
+// on the `extensions`.`ftv1` property of the response.  The Apollo Gateway
+// utilizes this data to construct the full trace and submit it to Apollo's
+// usage reporting ingress.
+export function ApolloServerPluginInlineTrace(
+  options: ApolloServerPluginInlineTraceOptions = Object.create(null),
+): ApolloServerPlugin {
+  let enabled: boolean | null = options.__onlyIfSchemaIsSubgraph ? null : true;
+  return internalPlugin({
+    __internal_plugin_id__: 'InlineTrace',
+    __is_disabled_plugin__: false,
+    async serverWillStart({ schema, logger }) {
+      // Handle the case that the plugin was implicitly installed. We only want it
+      // to actually be active if the schema appears to be federated. If you don't
+      // like the log line, just install `ApolloServerPluginInlineTrace()` in
+      // `plugins` yourself.
+      if (enabled === null) {
+        enabled = schemaIsSubgraph(schema);
+        if (enabled) {
+          logger.info(
+            'Enabling inline tracing for this subgraph. To disable, use ' +
+              'ApolloServerPluginInlineTraceDisabled.',
+          );
+        }
+      }
+    },
+    async requestDidStart({ request: { http }, metrics }) {
+      if (!enabled) {
+        return;
+      }
+
+      const treeBuilder = new TraceTreeBuilder({
+        maskedBy: 'ApolloServerPluginInlineTrace',
+        sendErrors: options.includeErrors,
+      });
+
+      // XXX Provide a mechanism to customize this logic.
+      if (http?.headers.get('apollo-federation-include-trace') !== 'ftv1') {
+        return;
+      }
+
+      // If some other (user-written?) plugin already decided that we are not
+      // capturing traces, then we should not capture traces.
+      if (metrics.captureTraces === false) {
+        return;
+      }
+
+      // Note that this will override any `fieldLevelInstrumentation` parameter
+      // to the usage reporting plugin for requests with the
+      // `apollo-federation-include-trace` header set.
+      metrics.captureTraces = true;
+
+      treeBuilder.startTiming();
+
+      return {
+        async executionDidStart() {
+          return {
+            willResolveField({ info }) {
+              return treeBuilder.willResolveField(info);
+            },
+          };
+        },
+
+        async didEncounterErrors({ errors }) {
+          treeBuilder.didEncounterErrors(errors);
+        },
+
+        async willSendResponse({ response }) {
+          // We record the end time at the latest possible time: right before serializing the trace.
+          // If we wait any longer, the time we record won't actually be sent anywhere!
+          treeBuilder.stopTiming();
+
+          // For now, we don't support inline traces on incremental delivery
+          // responses. (We could perhaps place the trace on the final chunk, or
+          // even deliver it bit by bit. For now, since Gateway does not support
+          // incremental delivery and Router does not pass through defers to
+          // subgraphs, this doesn't affect the "federated tracing" use case,
+          // though it does affect the ability to look at inline traces in other
+          // tools like Explorer.
+          if (response.body.kind === 'incremental') {
+            return;
+          }
+
+          // If we're in a gateway, include the query plan (and subgraph traces)
+          // in the inline trace. This is designed more for manually querying
+          // your graph while running locally to see what the query planner is
+          // doing rather than for running in production.
+          if (metrics.queryPlanTrace) {
+            treeBuilder.trace.queryPlan = metrics.queryPlanTrace;
+          }
+
+          const encodedUint8Array = Trace.encode(treeBuilder.trace).finish();
+          const encodedBuffer = Buffer.from(
+            encodedUint8Array,
+            encodedUint8Array.byteOffset,
+            encodedUint8Array.byteLength,
+          );
+
+          const extensions =
+            response.body.singleResult.extensions ||
+            (response.body.singleResult.extensions = Object.create(null));
+
+          // This should only happen if another plugin is using the same name-
+          // space within the `extensions` object and got to it before us.
+          if (typeof extensions.ftv1 !== 'undefined') {
+            throw new Error('The `ftv1` extension was already present.');
+          }
+
+          extensions.ftv1 = encodedBuffer.toString('base64');
+        },
+      };
+    },
+  });
+}

package/src/plugin/landingPage/default/getEmbeddedHTML.ts

@@ -0,0 +1,204 @@
+import type {
+  ApolloServerPluginEmbeddedLandingPageLocalDefaultOptions,
+  ApolloServerPluginEmbeddedLandingPageProductionDefaultOptions,
+} from './types';
+
+// This function turns an object into a string and replaces
+// <, >, &, ' with their unicode chars to avoid adding html tags to
+// the landing page html that might be passed from the config.
+// The only place these characters can appear in the output of
+// JSON.stringify is within string literals, where they can equally
+// well appear \u-escaped. This specifically means that
+// `</script>` won't terminate the script block early.
+// (Perhaps we should have done this instead of the triple-encoding
+// of encodeConfig for the main landing page.)
+function getConfigStringForHtml(config: object) {
+  return JSON.stringify(config)
+    .replace('<', '\\u003c')
+    .replace('>', '\\u003e')
+    .replace('&', '\\u0026')
+    .replace("'", '\\u0027');
+}
+
+export const getEmbeddedExplorerHTML = (
+  explorerCdnVersion: string,
+  config: ApolloServerPluginEmbeddedLandingPageProductionDefaultOptions,
+  apolloServerVersion: string,
+  nonce: string,
+) => {
+  interface EmbeddableExplorerOptions {
+    graphRef: string;
+    target: string;
+
+    initialState?: {
+      document?: string;
+      variables?: Record<string, any>;
+      headers?: Record<string, string>;
+      collectionId?: string;
+      operationId?: string;
+      displayOptions: {
+        docsPanelState?: 'open' | 'closed'; // default to 'open',
+        showHeadersAndEnvVars?: boolean; // default to `false`
+        theme?: 'dark' | 'light';
+      };
+    };
+    persistExplorerState?: boolean; // defaults to 'false'
+
+    endpointUrl: string;
+
+    includeCookies?: boolean; // defaults to 'false'
+
+    runTelemetry?: boolean;
+
+    allowDynamicStyles?: boolean; // defaults to 'true'
+  }
+  const productionLandingPageEmbedConfigOrDefault = {
+    displayOptions: {},
+    persistExplorerState: false,
+    runTelemetry: true,
+    ...(typeof config.embed === 'boolean' ? {} : config.embed),
+  };
+  const embeddedExplorerParams: Omit<
+    EmbeddableExplorerOptions,
+    'endpointUrl'
+  > & { runtime: string } = {
+    graphRef: config.graphRef,
+    target: '#embeddableExplorer',
+    initialState: {
+      ...('document' in config || 'headers' in config || 'variables' in config
+        ? {
+            document: config.document,
+            headers: config.headers,
+            variables: config.variables,
+          }
+        : {}),
+      ...('collectionId' in config
+        ? {
+            collectionId: config.collectionId,
+            operationId: config.operationId,
+          }
+        : {}),
+      displayOptions: {
+        ...productionLandingPageEmbedConfigOrDefault.displayOptions,
+      },
+    },
+    persistExplorerState:
+      productionLandingPageEmbedConfigOrDefault.persistExplorerState,
+    includeCookies: config.includeCookies,
+    runtime: apolloServerVersion,
+    runTelemetry: productionLandingPageEmbedConfigOrDefault.runTelemetry,
+    allowDynamicStyles: false, // disabled for CSP - we add the iframe styles ourselves instead
+  };
+
+  return `
+<div class="fallback">
+  <h1>Welcome to Apollo Server</h1>
+  <p>Apollo Explorer cannot be loaded; it appears that you might be offline.</p>
+</div>
+<style nonce=${nonce}>
+  iframe {
+    background-color: white;
+    height: 100%;
+    width: 100%;
+    border: none;
+  }
+  #embeddableExplorer {
+    width: 100vw;
+    height: 100vh;
+    position: absolute;
+    top: 0;
+  }
+</style>
+<div id="embeddableExplorer"></div>
+<script nonce="${nonce}" src="https://embeddable-explorer.cdn.apollographql.com/${encodeURIComponent(
+    explorerCdnVersion,
+  )}/embeddable-explorer.umd.production.min.js?runtime=${encodeURIComponent(
+    apolloServerVersion,
+  )}"></script>
+<script nonce="${nonce}">
+  var endpointUrl = window.location.href;
+  var embeddedExplorerConfig = ${getConfigStringForHtml(
+    embeddedExplorerParams,
+  )};
+  new window.EmbeddedExplorer({
+    ...embeddedExplorerConfig,
+    endpointUrl,
+  });
+</script>
+`;
+};
+
+export const getEmbeddedSandboxHTML = (
+  sandboxCdnVersion: string,
+  config: ApolloServerPluginEmbeddedLandingPageLocalDefaultOptions,
+  apolloServerVersion: string,
+  nonce: string,
+) => {
+  const localDevelopmentEmbedConfigOrDefault = {
+    runTelemetry: true,
+    endpointIsEditable: false,
+    initialState: {},
+    ...(typeof config.embed === 'boolean' ? {} : (config.embed ?? {})),
+  };
+  const embeddedSandboxConfig = {
+    target: '#embeddableSandbox',
+    initialState: {
+      ...('document' in config || 'headers' in config || 'variables' in config
+        ? {
+            document: config.document,
+            variables: config.variables,
+            headers: config.headers,
+          }
+        : {}),
+      ...('collectionId' in config
+        ? {
+            collectionId: config.collectionId,
+            operationId: config.operationId,
+          }
+        : {}),
+      includeCookies: config.includeCookies,
+      ...localDevelopmentEmbedConfigOrDefault.initialState,
+    },
+    hideCookieToggle: false,
+    endpointIsEditable: localDevelopmentEmbedConfigOrDefault.endpointIsEditable,
+    runtime: apolloServerVersion,
+    runTelemetry: localDevelopmentEmbedConfigOrDefault.runTelemetry,
+    allowDynamicStyles: false, // disabled for CSP - we add the iframe styles ourselves instead
+  };
+  return `
+<div class="fallback">
+  <h1>Welcome to Apollo Server</h1>
+  <p>Apollo Sandbox cannot be loaded; it appears that you might be offline.</p>
+</div>
+<style nonce=${nonce}>
+  iframe {
+    background-color: white;
+    height: 100%;
+    width: 100%;
+    border: none;
+  }
+  #embeddableSandbox {
+    width: 100vw;
+    height: 100vh;
+    position: absolute;
+    top: 0;
+  }
+</style>
+<div id="embeddableSandbox"></div>
+<script nonce="${nonce}" src="https://embeddable-sandbox.cdn.apollographql.com/${encodeURIComponent(
+    sandboxCdnVersion,
+  )}/embeddable-sandbox.umd.production.min.js?runtime=${encodeURIComponent(
+    apolloServerVersion,
+  )}"></script>
+<script nonce="${nonce}">
+  var initialEndpoint = window.location.href;
+  var embeddedSandboxConfig = ${getConfigStringForHtml(embeddedSandboxConfig)};
+  new window.EmbeddedSandbox(
+    {
+      ...embeddedSandboxConfig,
+      initialEndpoint,
+    }
+  );
+</script>
+`;
+};

package/src/plugin/landingPage/default/index.ts

@@ -0,0 +1,219 @@
+import type {
+  ApolloServerPlugin,
+  BaseContext,
+} from '../../../externalTypes/index.js';
+import type { ImplicitlyInstallablePlugin } from '../../../ApolloServer.js';
+import type {
+  ApolloServerPluginLandingPageLocalDefaultOptions,
+  ApolloServerPluginLandingPageProductionDefaultOptions,
+  LandingPageConfig,
+} from './types.js';
+import {
+  getEmbeddedExplorerHTML,
+  getEmbeddedSandboxHTML,
+} from './getEmbeddedHTML.js';
+import { packageVersion } from '../../../generated/packageVersion.js';
+import { createHash } from '@apollo/utils.createhash';
+import { v4 as uuidv4 } from 'uuid';
+
+export type {
+  ApolloServerPluginLandingPageLocalDefaultOptions,
+  ApolloServerPluginLandingPageProductionDefaultOptions,
+};
+
+export function ApolloServerPluginLandingPageLocalDefault(
+  options: ApolloServerPluginLandingPageLocalDefaultOptions = {},
+): ApolloServerPlugin {
+  const { version, __internal_apolloStudioEnv__, ...rest } = {
+    // we default to Sandbox unless embed is specified as false
+    embed: true as const,
+    ...options,
+  };
+  return ApolloServerPluginLandingPageDefault(version, {
+    isProd: false,
+    apolloStudioEnv: __internal_apolloStudioEnv__,
+    ...rest,
+  });
+}
+
+export function ApolloServerPluginLandingPageProductionDefault(
+  options: ApolloServerPluginLandingPageProductionDefaultOptions = {},
+): ApolloServerPlugin {
+  const { version, __internal_apolloStudioEnv__, ...rest } = options;
+  return ApolloServerPluginLandingPageDefault(version, {
+    isProd: true,
+    apolloStudioEnv: __internal_apolloStudioEnv__,
+    ...rest,
+  });
+}
+
+// A triple encoding! Wow! First we use JSON.stringify to turn our object into a
+// string. Then we encodeURIComponent so we don't have to stress about what
+// would happen if the config contained `</script>`. Finally, we JSON.stringify
+// it again, which in practice just wraps it in a pair of double quotes (since
+// there shouldn't be any backslashes left after encodeURIComponent). The
+// consumer of this needs to decodeURIComponent and then JSON.parse; there's
+// only one JSON.parse because the outermost JSON string is parsed by the JS
+// parser itself.
+function encodeConfig(config: LandingPageConfig): string {
+  return JSON.stringify(encodeURIComponent(JSON.stringify(config)));
+}
+
+const getNonEmbeddedLandingPageHTML = (
+  cdnVersion: string,
+  config: LandingPageConfig,
+  apolloServerVersion: string,
+  nonce: string,
+) => {
+  const encodedConfig = encodeConfig(config);
+
+  return `
+ <div class="fallback">
+  <h1>Welcome to Apollo Server</h1>
+  <p>The full landing page cannot be loaded; it appears that you might be offline.</p>
+</div>
+<script nonce="${nonce}">window.landingPage = ${encodedConfig};</script>
+<script nonce="${nonce}" src="https://apollo-server-landing-page.cdn.apollographql.com/${encodeURIComponent(
+    cdnVersion,
+  )}/static/js/main.js?runtime=${apolloServerVersion}"></script>`;
+};
+
+export const DEFAULT_EMBEDDED_EXPLORER_VERSION = 'v3';
+export const DEFAULT_EMBEDDED_SANDBOX_VERSION = 'v2';
+export const DEFAULT_APOLLO_SERVER_LANDING_PAGE_VERSION = '_latest';
+
+// Helper for the two actual plugin functions.
+function ApolloServerPluginLandingPageDefault<TContext extends BaseContext>(
+  maybeVersion: string | undefined,
+  config: LandingPageConfig & {
+    isProd: boolean;
+    apolloStudioEnv: 'staging' | 'prod' | undefined;
+  },
+): ImplicitlyInstallablePlugin<TContext> {
+  const explorerVersion = maybeVersion ?? DEFAULT_EMBEDDED_EXPLORER_VERSION;
+  const sandboxVersion = maybeVersion ?? DEFAULT_EMBEDDED_SANDBOX_VERSION;
+  const apolloServerLandingPageVersion =
+    maybeVersion ?? DEFAULT_APOLLO_SERVER_LANDING_PAGE_VERSION;
+  const apolloServerVersion = `@apollo/server@${packageVersion}`;
+
+  const scriptSafeList = [
+    'https://apollo-server-landing-page.cdn.apollographql.com',
+    'https://embeddable-sandbox.cdn.apollographql.com',
+    'https://embeddable-explorer.cdn.apollographql.com',
+  ].join(' ');
+  const styleSafeList = [
+    'https://apollo-server-landing-page.cdn.apollographql.com',
+    'https://embeddable-sandbox.cdn.apollographql.com',
+    'https://embeddable-explorer.cdn.apollographql.com',
+    'https://fonts.googleapis.com',
+  ].join(' ');
+  const iframeSafeList = [
+    'https://explorer.embed.apollographql.com',
+    'https://sandbox.embed.apollographql.com',
+    'https://embed.apollo.local:3000',
+  ].join(' ');
+
+  return {
+    __internal_installed_implicitly__: false,
+    async serverWillStart() {
+      return {
+        async renderLandingPage() {
+          const encodedASLandingPageVersion = encodeURIComponent(
+            apolloServerLandingPageVersion,
+          );
+          async function html() {
+            const nonce = createHash('sha256').update(uuidv4()).digest('hex');
+            const scriptCsp = `script-src 'self' 'nonce-${nonce}' ${scriptSafeList}`;
+            const styleCsp = `style-src 'nonce-${nonce}' ${styleSafeList}`;
+            const imageCsp = `img-src https://apollo-server-landing-page.cdn.apollographql.com`;
+            const manifestCsp = `manifest-src https://apollo-server-landing-page.cdn.apollographql.com`;
+            const frameCsp = `frame-src ${iframeSafeList}`;
+            return `
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="Content-Security-Policy" content="${scriptCsp}; ${styleCsp}; ${imageCsp}; ${manifestCsp}; ${frameCsp}" />
+    <link
+      rel="icon"
+      href="https://apollo-server-landing-page.cdn.apollographql.com/${encodedASLandingPageVersion}/assets/favicon.png"
+    />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Source+Sans+Pro&display=swap"
+      rel="stylesheet"
+    />
+    <meta name="theme-color" content="#000000" />
+    <meta name="description" content="Apollo server landing page" />
+    <link
+      rel="apple-touch-icon"
+      href="https://apollo-server-landing-page.cdn.apollographql.com/${encodedASLandingPageVersion}/assets/favicon.png"
+    />
+    <link
+      rel="manifest"
+      href="https://apollo-server-landing-page.cdn.apollographql.com/${encodedASLandingPageVersion}/manifest.json"
+    />
+    <title>Apollo Server</title>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="react-root">
+      <style nonce=${nonce}>
+        body {
+          margin: 0;
+          overflow-x: hidden;
+          overflow-y: hidden;
+        }
+        .fallback {
+          opacity: 0;
+          animation: fadeIn 1s 1s;
+          animation-iteration-count: 1;
+          animation-fill-mode: forwards;
+          padding: 1em;
+        }
+        @keyframes fadeIn {
+          0% {opacity:0;}
+          100% {opacity:1; }
+        }
+      </style>
+    ${
+      config.embed
+        ? 'graphRef' in config && config.graphRef
+          ? getEmbeddedExplorerHTML(
+              explorerVersion,
+              config,
+              apolloServerVersion,
+              nonce,
+            )
+          : !('graphRef' in config)
+            ? getEmbeddedSandboxHTML(
+                sandboxVersion,
+                config,
+                apolloServerVersion,
+                nonce,
+              )
+            : getNonEmbeddedLandingPageHTML(
+                apolloServerLandingPageVersion,
+                config,
+                apolloServerVersion,
+                nonce,
+              )
+        : getNonEmbeddedLandingPageHTML(
+            apolloServerLandingPageVersion,
+            config,
+            apolloServerVersion,
+            nonce,
+          )
+    }
+    </div>
+  </body>
+</html>
+          `;
+          }
+          return { html };
+        },
+      };
+    },
+  };
+}