@depup/apollo__server 5.5.0-depup.0

package/src/plugin/usageReporting/operationDerivedDataCache.ts

@@ -0,0 +1,61 @@
+import type { Logger } from '@apollo/utils.logger';
+import type { ReferencedFieldsByType } from '@apollo/utils.usagereporting';
+import { LRUCache } from 'lru-cache';
+
+export interface OperationDerivedData {
+  signature: string;
+  referencedFieldsByType: ReferencedFieldsByType;
+}
+
+export function createOperationDerivedDataCache({
+  logger,
+}: {
+  logger: Logger;
+}): LRUCache<string, OperationDerivedData> {
+  let lastWarn: Date;
+  let lastDisposals = 0;
+  return new LRUCache<string, OperationDerivedData>({
+    // Calculate the length of cache objects by the JSON.stringify byteLength.
+    sizeCalculation(obj) {
+      return Buffer.byteLength(JSON.stringify(obj), 'utf8');
+    },
+    // 10MiB limit, very much approximately since we can't be sure how V8 might
+    // be storing this data internally. Though this should be enough to store a
+    // fair amount of operation data, depending on their overall complexity. A
+    // future version of this might expose some configuration option to grow the
+    // cache, but ideally, we could do that dynamically based on the resources
+    // available to the server, and not add more configuration surface area.
+    // Hopefully the warning message will allow us to evaluate the need with
+    // more validated input from those that receive it.
+    maxSize: Math.pow(2, 20) * 10,
+    dispose() {
+      // Count the number of disposals between warning messages.
+      lastDisposals++;
+
+      // Only show a message warning about the high turnover every 60 seconds.
+      if (!lastWarn || new Date().getTime() - lastWarn.getTime() > 60000) {
+        // Log the time that we last displayed the message.
+        lastWarn = new Date();
+        logger.warn(
+          [
+            'This server is processing a high number of unique operations.  ',
+            `A total of ${lastDisposals} records have been `,
+            'ejected from the ApolloServerPluginUsageReporting signature cache in the past ',
+            'interval.  If you see this warning frequently, please open an ',
+            'issue on the Apollo Server repository.',
+          ].join(''),
+        );
+
+        // Reset the disposal counter for the next message interval.
+        lastDisposals = 0;
+      }
+    },
+  });
+}
+
+export function operationDerivedDataCacheKey(
+  queryHash: string,
+  operationName: string,
+) {
+  return `${queryHash}${operationName && ':' + operationName}`;
+}

package/src/plugin/usageReporting/options.ts

@@ -0,0 +1,414 @@
+import type { GraphQLError, DocumentNode } from 'graphql';
+import type {
+  GraphQLRequestContextDidResolveOperation,
+  GraphQLRequestContext,
+  GraphQLRequestContextWillSendResponse,
+  BaseContext,
+} from '../../externalTypes/index.js';
+import type { Logger } from '@apollo/utils.logger';
+import type { Trace } from '@apollo/usage-reporting-protobuf';
+import type { Fetcher } from '@apollo/utils.fetcher';
+
+export interface ApolloServerPluginUsageReportingOptions<
+  TContext extends BaseContext,
+> {
+  //#region Configure exactly which data should be sent to Apollo.
+  /**
+   * Apollo Server's usage reports describe each individual request in one of
+   * two ways: as a "trace" (a detailed description of the specific request,
+   * including a query plan and resolver tree with timings and errors, as well
+   * as optional details like variable values and HTTP headers), or as part of
+   * aggregated "stats" (where invocations of the same operation from the same
+   * client program are aggregated together rather than described individually).
+   * Apollo Server uses an heuristic to decide which operations to describe as
+   * traces and which to aggregate as stats.
+   *
+   * By setting the `sendTraces` option to `false`, Apollo Server will describe
+   * *all* operations as stats; individual requests will never be broken out
+   * into separate traces. If you set `sendTraces: false`, then Apollo Studio's
+   * Traces view won't show any traces (other Studio functionality will be
+   * unaffected).
+   *
+   * Note that the values of `sendVariableValues`, `sendHeaders`, and
+   *  `sendUnexecutableOperationDocuments` are irrelevant if you set
+   *  `sendTraces: false`, because those options control data that is contained
+   *  only in traces (not in stats).
+   *
+   * Setting `sendTraces: false` does *NOT* imply `fieldLevelInstrumentation:
+   * 0`. Apollo Server can still take advantage of field-level instrumentation
+   * (either directly for monolith servers, or via federated tracing for
+   * Gateways) in order to accurately report field execution usage in "stats".
+   * This option only controls whether data is sent to Apollo's servers as
+   * traces, not whether traces are internally used to learn about usage.
+   */
+  sendTraces?: boolean;
+
+  /**
+   * By default, Apollo Server does not send the values of any GraphQL variables
+   * to Apollo's servers, because variable values often contain the private data
+   * of your app's users. If you'd like variable values to be included in
+   * traces, set this option. This option can take several forms:
+   * - { none: true }: don't send any variable values (DEFAULT)
+   * - { all: true}: send all variable values
+   * - { transform: ... }: a custom function for modifying variable values. The
+   *    function receives `variables` and `operationString` and should return a
+   *    record of `variables` with the same keys as the `variables` it receives
+   *    (added variables will be ignored and removed variables will be reported
+   *    with an empty value). For security reasons, if an error occurs within
+   *    this function, all variable values will be replaced with
+   *    `[PREDICATE_FUNCTION_ERROR]`.
+   * - { exceptNames: ... }: a case-sensitive list of names of variables whose
+   *   values should not be sent to Apollo servers
+   * - { onlyNames: ... }: A case-sensitive list of names of variables whose
+   *   values will be sent to Apollo servers
+   *
+   * Defaults to not sending any variable values if both this parameter and the
+   * deprecated `privateVariables` are not set. The report will indicate each
+   * private variable key whose value was redacted by { none: true } or {
+   * exceptNames: [...] }.
+   *
+   * The value of this option is not relevant if you set `sendTraces: false`,
+   * because variable values only appear in traces.
+   */
+  sendVariableValues?: VariableValueOptions;
+  /**
+   * By default, Apollo Server does not send the HTTP request headers and values
+   * to Apollo's servers, as these headers may contain your users' private data.
+   * If you'd like this information included in traces, set this option. This
+   * option can take several forms:
+   *
+   * - { none: true } to drop all HTTP request headers (DEFAULT)
+   * - { all: true } to send the values of all HTTP request headers
+   * - { exceptNames: Array<String> } A case-insensitive list of names of HTTP
+   *     headers whose values should not be sent to Apollo servers
+   * - { onlyNames: Array<String> }: A case-insensitive list of names of HTTP
+   *   headers whose values will be sent to Apollo servers
+   *
+   * Unlike with sendVariableValues, names of dropped headers are not reported.
+   * The headers 'authorization', 'cookie', and 'set-cookie' are never reported.
+   *
+   * The value of this option is not relevant if you set `sendTraces: false`,
+   * because request headers only appear in traces.
+   */
+  sendHeaders?: SendValuesBaseOptions;
+  /**
+   * By default, if a trace contains errors, the errors are reported to Apollo
+   * servers 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:
+   * 'ApolloServerPluginUsageReporting'` 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 }: send all error messages and extensions to Apollo
+   *   servers
+   * - { 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 report to Apollo servers; if `null`, the error
+   *   is not included in traces or error statistics.
+   *
+   * If you set `sendTraces: false`, then the only relevant aspect of this
+   * option is whether you return `null` from a `transform` function or not
+   * (which affects aggregated error statistics).
+   */
+  sendErrors?: SendErrorsOptions;
+
+  /**
+   * This option allows you to choose if Apollo Server should calculate detailed
+   * per-field statistics for a particular request. It is only called for
+   * executable operations: operations which parse and validate properly and
+   * which do not have an unknown operation name. It is not called if an
+   * `includeRequest` hook is provided and returns false.
+   *
+   * You can either pass an async function or a number. The function receives a
+   * `GraphQLRequestContext`. (The effect of passing a number is described
+   * later.) Your function can return a boolean or a number; returning false is
+   * equivalent to returning 0 and returning true is equivalent to returning 1.
+   *
+   * Returning false (or 0) means that Apollo Server will only pay attention to
+   * overall properties of the operation, like what GraphQL operation is
+   * executing and how long the entire operation takes to execute, and not
+   * anything about field-by-field execution.
+   *
+   * If you return false (or 0), this operation *will* still contribute to most
+   * features of Studio, such as schema checks, the Operations page, and the
+   * "referencing operations" statistic on the Fields page, etc.
+   *
+   * If you return false (or 0), this operation will *not* contribute to the
+   * "field executions" statistic on the Fields page or to the execution timing
+   * hints optionally displayed in Studio Explorer or in vscode-graphql.
+   * Additionally, this operation will not produce a trace that can be viewed on
+   * the Traces section of the Operations page.
+   *
+   * Returning false (or 0) for some or all operations can improve your server's
+   * performance, as the overhead of calculating complete traces is not always
+   * negligible. This is especially the case if this server is an Apollo
+   * Gateway, as captured traces are transmitted from the subgraph to the
+   * Gateway in-band inside the actual GraphQL response.
+   *
+   * Returning a positive number means that Apollo Server will track each field
+   * execution and send Apollo Studio statistics on how many times each field
+   * was executed and what the per-field performance was. Apollo Server sends
+   * both a precise observed execution count and an estimated execution count.
+   * The former is calculated by counting each field execution as 1, and the
+   * latter is calculated by counting each field execution as the number
+   * returned from this hook, which can be thought of as a weight.
+   *
+   * Passing a number `x` (which should be between 0 and 1 inclusive) for
+   * `fieldLevelInstrumentation` is equivalent to passing the function `async ()
+   * => Math.random() < x ? 1/x : 0`.  For example, if you pass 0.01, then 99%
+   * of the time this function will return 0, and 1% of the time this function
+   * will return 100. So 99% of the time Apollo Server will not track field
+   * executions, and 1% of the time Apollo Server will track field executions
+   * and send them to Apollo Studio both as an exact observed count and as an
+   * "estimated" count which is 100 times higher.  Generally, the weights you
+   * return should be roughly the reciprocal of the probability that the
+   * function returns non-zero; however, you're welcome to craft a more
+   * sophisticated function, such as one that uses a higher probability for
+   * rarer operations and a lower probability for more common operations.
+   *
+   * (Note that returning true here does *not* mean that the data derived from
+   * field-level instrumentation must be transmitted to Apollo Studio's servers
+   * in the form of a trace; it may still be aggregated locally to statistics.
+   * Similarly, setting `sendTraces: false` does not affect
+   * `fieldLevelInstrumentation`. But either way this operation will contribute
+   * to the "field executions" statistic and timing hints.)
+   *
+   * The default `fieldLevelInstrumentation` is a function that always returns
+   * true.
+   */
+  fieldLevelInstrumentation?:
+    | number
+    | ((
+        request: GraphQLRequestContextDidResolveOperation<TContext>,
+      ) => Promise<number | boolean>);
+
+  /**
+   * This option allows you to choose if a particular request should be
+   * represented in the usage reporting sent to Apollo servers. By default, all
+   * requests are included. If this async predicate function is specified, its
+   * return value will determine whether a given request is included.
+   *
+   * Note that returning false here means that the operation will be completely
+   * ignored by all Apollo Studio features. If you merely want to improve
+   * performance by skipping the field-level execution trace, set the
+   * `fieldLevelInstrumentation` option instead of this one.
+   *
+   * The predicate function receives the request context. If validation and
+   * parsing of the request succeeds, the function will receive the request
+   * context in the
+   * [`GraphQLRequestContextDidResolveOperation`](https://www.apollographql.com/docs/apollo-server/integrations/plugins/#didresolveoperation)
+   * phase, which permits tracing based on dynamic properties, e.g., HTTP
+   * headers or the `operationName` (when available). Otherwise it will receive
+   * the request context in the
+   * [`GraphQLRequestContextWillSendResponse`](https://www.apollographql.com/docs/apollo-server/integrations/plugins/#willsendresponse)
+   * phase:
+   *
+   * (If you don't want any usage reporting at all, don't use this option:
+   * instead, either avoid specifying an Apollo API key, or use
+   * ApolloServerPluginUsageReportingDisabled to prevent this plugin from being
+   * created by default.)
+   *
+   * **Example:**
+   *
+   * ```js
+   * includeRequest(requestContext) {
+   *   // Always include `query HomeQuery { ... }`.
+   *   if (requestContext.operationName === "HomeQuery") return true;
+   *
+   *   // Omit if the "report-to-apollo" header is set to "false".
+   *   if (requestContext.request.http?.headers?.get("report-to-apollo") === "false") {
+   *     return false;
+   *   }
+   *
+   *   // Otherwise include.
+   *   return true;
+   * },
+   * ```
+   *
+   */
+  includeRequest?: (
+    request:
+      | GraphQLRequestContextDidResolveOperation<TContext>
+      | GraphQLRequestContextWillSendResponse<TContext>,
+  ) => Promise<boolean>;
+  /**
+   * By default, this plugin associates client information such as name
+   * and version with user requests based on HTTP headers starting with
+   * `apollographql-client-`. If you have another way of communicating
+   * client information to your server, tell the plugin how it works
+   * with this option.
+   */
+  generateClientInfo?: GenerateClientInfo<TContext>;
+  /**
+   * If you are using the `overrideReportedSchema` option to the schema
+   * reporting plugin (`ApolloServerPluginSchemaReporting`), you should
+   * pass the same value here as well, so that the schema ID associated
+   * with requests in this plugin's usage reports matches the schema
+   * ID that the other plugin reports.
+   */
+  overrideReportedSchema?: string;
+  /**
+   * Whether to include the entire document in the trace if the operation
+   * was a GraphQL parse or validation error (i.e. failed the GraphQL parse or
+   * validation phases). This will be included as a separate field on the trace
+   * and the operation name and signature will always be reported with a constant
+   * identifier. Whether the operation was a parse failure or a validation
+   * failure will be embedded within the stats report key itself.
+   *
+   * The value of this option is not relevant if you set `sendTraces: false`,
+   * because unexecutable operation documents only appear in traces.
+   */
+  sendUnexecutableOperationDocuments?: boolean;
+
+  /**
+   * This plugin sends information about operations to Apollo's servers in two
+   * forms: as detailed operation traces of single operations and as summarized
+   * statistics of many operations. Each individual operation is described in
+   * exactly one of those ways. This hook lets you select which operations are
+   * sent as traces and which are sent as statistics. The default is a heuristic
+   * that tries to send one trace for each rough duration bucket for each
+   * operation each minute, plus more if the operations have errors. (Note that
+   * Apollo's servers perform their own sampling on received traces; not all
+   * traces sent to Apollo's servers can be later retrieved via the trace UI.)
+   *
+   * If you just want to send all operations as stats, set `sendTraces: false`
+   * instead of using this experimental hook.
+   *
+   * This option is highly experimental and may change or be removed in future
+   * versions.
+   */
+  experimental_sendOperationAsTrace?: (
+    trace: Trace,
+    statsReportKey: string,
+  ) => boolean;
+  //#endregion
+
+  //#region Configure the mechanics of communicating with Apollo's servers.
+  /**
+   * Sends a usage report after every request. This options is useful for
+   * stateless environments like Amazon Lambda where processes handle only a
+   * small number of requests before terminating. It defaults to true when the
+   * ApolloServer was started in the background with
+   * `startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests`
+   * (generally used with serverless frameworks), or false otherwise. (Note that
+   * "immediately" does not mean synchronously with completing the response, but
+   * "very soon", such as after a setImmediate call.)
+   */
+  sendReportsImmediately?: boolean;
+  /**
+   * Specifies which Fetch API implementation to use when sending usage reports.
+   */
+  fetcher?: Fetcher;
+  /**
+   * How often to send reports to Apollo. We'll also send reports when the
+   * report gets big; see maxUncompressedReportSize.
+   */
+  reportIntervalMs?: number;
+  /**
+   * We send a report when the report size will become bigger than this size in
+   * bytes (default: 4MB).  (This is a rough limit --- we ignore the size of the
+   * report header and some other top level bytes. We just add up the lengths of
+   * the serialized traces and signatures.)
+   */
+  maxUncompressedReportSize?: number;
+  /**
+   * Reporting is retried with exponential backoff up to this many times
+   * (including the original request). Defaults to 5.
+   */
+  maxAttempts?: number;
+  /**
+   * Minimum back-off for retries. Defaults to 100ms.
+   */
+  minimumRetryDelayMs?: number;
+  /**
+   * Timeout for each individual attempt to send a report to Apollo. (This is
+   * for each HTTP POST, not for all potential retries.) Defaults to 30 seconds
+   * (30000ms).
+   */
+  requestTimeoutMs?: number;
+  /**
+   * A logger interface to be used for output and errors.  When not provided
+   * it will default to the server's own `logger` implementation and use
+   * `console` when that is not available.
+   */
+  logger?: Logger;
+  /**
+   * By default, if an error occurs when sending trace reports to Apollo
+   * servers, its message will be sent to the `error` method on the logger
+   * specified with the `logger` option to this plugin or to ApolloServer (or to
+   * `console.error` by default). Specify this function to process errors in a
+   * different way. (The difference between using this option and using a logger
+   * is that this option receives the actual Error object whereas `logger.error`
+   * only receives its message.)
+   */
+  reportErrorFunction?: (err: Error) => void;
+  //#endregion
+
+  //#region Internal and non-recommended options
+  /**
+   * The URL base that we send reports to (not including the path). This option
+   * only needs to be set for testing and Apollo-internal uses.
+   */
+  endpointUrl?: string;
+  /**
+   * If set, prints all reports as JSON when they are sent. (Note that for
+   * technical reasons, traces embedded in a report are printed separately when
+   * they are added to a report.) Reports are sent through `logger.info`.
+   */
+  debugPrintReports?: boolean;
+  /**
+   * Specify the function for creating a signature for a query. See signature.ts
+   * for details. This option is not recommended, as Apollo's servers make assumptions
+   * about how the signature relates to the operation you executed.
+   */
+  calculateSignature?: (ast: DocumentNode, operationName: string) => string;
+  /**
+   * This option is for internal use by `@apollo/server` only.
+   *
+   * By default we want to enable this plugin for non-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
+   * ApolloServerPluginUsageReportingDisabled themselves), `@apollo/server`
+   * always installs this plugin (if API key and graph ref are provided) and
+   * uses this option to disable usage reporting if the schema is a subgraph.
+   */
+  __onlyIfSchemaIsNotSubgraph?: boolean;
+  //#endregion
+}
+
+export type SendValuesBaseOptions =
+  | { onlyNames: Array<string> }
+  | { exceptNames: Array<string> }
+  | { all: true }
+  | { none: true };
+
+type VariableValueTransformOptions = {
+  variables: Record<string, any>;
+  operationString?: string;
+};
+
+export type VariableValueOptions =
+  | {
+      transform: (
+        options: VariableValueTransformOptions,
+      ) => Record<string, any>;
+    }
+  | SendValuesBaseOptions;
+
+export type SendErrorsOptions =
+  | { unmodified: true }
+  | { masked: true }
+  | { transform: (err: GraphQLError) => GraphQLError | null };
+
+export interface ClientInfo {
+  clientName?: string;
+  clientVersion?: string;
+}
+export type GenerateClientInfo<TContext extends BaseContext> = (
+  requestContext: GraphQLRequestContext<TContext>,
+) => ClientInfo;