@graphql-yoga/plugin-apollo-usage-report 0.8.5 → 0.9.0-alpha-20250515114730-227992730df06d592514265ec4b8d341a03c3f88

package/esm/index.js

@@ -1,17 +1,14 @@
-import { getOperationAST, Kind, printSchema, stripIgnoredCharacters } from 'graphql';
+import { getOperationAST, Kind, printSchema } from 'graphql';
 import { isAsyncIterable, } from 'graphql-yoga';
-import { Report } from '@apollo/usage-reporting-protobuf';
+import { calculateReferencedFieldsByType, usageReportingSignature, } from '@apollo/utils.usagereporting';
 import { useApolloInstrumentation, } from '@graphql-yoga/plugin-apollo-inline-trace';
-import { handleMaybePromise } from '@whatwg-node/promise-helpers';
-function getEnvVar(name, defaultValue) {
-    return globalThis.process?.env?.[name] || defaultValue || undefined;
-}
-const DEFAULT_REPORTING_ENDPOINT = 'https://usage-reporting.api.apollographql.com/api/ingress/traces';
+import { getEnvVar, Reporter } from './reporter.js';
 export function useApolloUsageReport(options = {}) {
     const [instrumentation, ctxForReq] = useApolloInstrumentation(options);
     let schemaIdSet$;
-    let schemaId;
+    let schema;
     let yoga;
+    let reporter;
     const logger = Object.fromEntries(['error', 'warn', 'info', 'debug'].map(level => [
         level,
         (...messages) => yoga.logger[level]('[ApolloUsageReport]', ...messages),
@@ -30,6 +27,7 @@ export function useApolloUsageReport(options = {}) {
             addPlugin({
                 onYogaInit(args) {
                     yoga = args.yoga;
+                    reporter = new Reporter(options, yoga, logger);
                     if (!getEnvVar('APOLLO_KEY', options.apiKey)) {
                         throw new Error(`[ApolloUsageReport] Missing API key. Please provide one in plugin options or with 'APOLLO_KEY' environment variable.`);
                     }
@@ -39,9 +37,13 @@ export function useApolloUsageReport(options = {}) {
                 },
                 onSchemaChange({ schema }) {
                     if (schema) {
-                        schemaIdSet$ = handleMaybePromise(() => hashSHA256(printSchema(schema), yoga.fetchAPI), id => {
-                            schemaId = id;
+                        schemaIdSet$ = hashSHA256(printSchema(schema), yoga.fetchAPI)
+                            .then(id => {
+                            schema = { id, schema };
                             schemaIdSet$ = undefined;
+                        })
+                            .catch(error => {
+                            logger.error('Failed to calculate schema hash: ', error);
                         });
                     }
                 },
@@ -50,6 +52,9 @@ export function useApolloUsageReport(options = {}) {
                 },
                 onParse() {
                     return function onParseEnd({ result, context }) {
+                        if (!schema) {
+                            throw new Error("should not happen: schema doesn't exists");
+                        }
                         const ctx = ctxForReq.get(context.request)?.traces.get(context);
                         if (!ctx) {
                             logger.debug('operation tracing context not found, this operation will not be traced.');
@@ -57,11 +62,16 @@ export function useApolloUsageReport(options = {}) {
                         }
                         const operationName = context.params.operationName ??
                             (isDocumentNode(result) ? getOperationAST(result)?.name?.value : undefined);
-                        const signature = context.params.query
-                            ? stripIgnoredCharacters(context.params.query)
-                            : '';
+                        const signature = operationName
+                            ? usageReportingSignature(result, operationName)
+                            : (context.params.query ?? '');
+                        ctx.referencedFieldsByType = calculateReferencedFieldsByType({
+                            document: result,
+                            schema: schema.schema,
+                            resolvedOperationName: operationName ?? null,
+                        });
                         ctx.operationKey = `# ${operationName || '-'}\n${signature}`;
-                        ctx.schemaId = schemaId;
+                        ctx.schemaId = schema.id;
                     };
                 },
                 onResultProcess({ request, result, serverContext }) {
@@ -75,9 +85,6 @@ export function useApolloUsageReport(options = {}) {
                         logger.debug('operation tracing context not found, this operation will not be traced.');
                         return;
                     }
-                    // Each operation in a batched request can belongs to a different schema.
-                    // Apollo doesn't allow to send batch queries for multiple schemas in the same batch
-                    const tracesPerSchema = {};
                     for (const trace of reqCtx.traces.values()) {
                         if (!trace.schemaId || !trace.operationKey) {
                             logger.debug('Misformed trace, missing operation key or schema id');
@@ -91,62 +98,33 @@ export function useApolloUsageReport(options = {}) {
                         if (clientVersion) {
                             trace.trace.clientVersion = clientVersion;
                         }
-                        tracesPerSchema[trace.schemaId] ||= {};
-                        tracesPerSchema[trace.schemaId][trace.operationKey] ||= { trace: [] };
-                        tracesPerSchema[trace.schemaId][trace.operationKey].trace?.push(trace.trace);
-                    }
-                    for (const schemaId in tracesPerSchema) {
-                        const tracesPerQuery = tracesPerSchema[schemaId];
-                        const agentVersion = options.agentVersion || `graphql-yoga@${yoga.version}`;
-                        serverContext.waitUntil(sendTrace(options, logger, yoga.fetchAPI.fetch, schemaId, tracesPerQuery, agentVersion));
+                        serverContext.waitUntil(reporter.addTrace(schema.id, {
+                            statsReportKey: trace.operationKey,
+                            trace: trace.trace,
+                            referencedFieldsByType: trace.referencedFieldsByType,
+                            asTrace: true, // TODO: allow to not always send traces
+                            nonFtv1ErrorPaths: [],
+                            maxTraceBytes: options.maxTraceSize,
+                        }));
                     }
                 },
+                async onDispose() {
+                    await reporter?.flush();
+                },
             });
         },
     };
 }
-export function hashSHA256(text, api = globalThis) {
+export async function hashSHA256(text, api = globalThis) {
     const inputUint8Array = new api.TextEncoder().encode(text);
-    return handleMaybePromise(() => api.crypto.subtle.digest({ name: 'SHA-256' }, inputUint8Array), arrayBuf => {
-        const outputUint8Array = new Uint8Array(arrayBuf);
-        let hash = '';
-        for (const byte of outputUint8Array) {
-            const hex = byte.toString(16);
-            hash += '00'.slice(0, Math.max(0, 2 - hex.length)) + hex;
-        }
-        return hash;
-    });
-}
-function sendTrace(options, logger, fetch, schemaId, tracesPerQuery, agentVersion) {
-    const { graphRef = getEnvVar('APOLLO_GRAPH_REF'), apiKey = getEnvVar('APOLLO_KEY'), endpoint = DEFAULT_REPORTING_ENDPOINT, } = options;
-    const body = Report.encode({
-        header: {
-            agentVersion,
-            graphRef,
-            executableSchemaId: schemaId,
-        },
-        operationCount: 1,
-        tracesPerQuery,
-    }).finish();
-    return handleMaybePromise(() => fetch(endpoint, {
-        method: 'POST',
-        headers: {
-            'content-type': 'application/protobuf',
-            // The presence of the api key is already checked at Yoga initialization time
-            'x-api-key': apiKey,
-            accept: 'application/json',
-        },
-        body,
-    }), response => handleMaybePromise(() => response.text(), responseText => {
-        if (response.ok) {
-            logger.debug('Traces sent:', responseText);
-        }
-        else {
-            logger.error('Failed to send trace:', responseText);
-        }
-    }), err => {
-        logger.error('Failed to send trace:', err);
-    });
+    const arrayBuf = await api.crypto.subtle.digest({ name: 'SHA-256' }, inputUint8Array);
+    const outputUint8Array = new Uint8Array(arrayBuf);
+    let hash = '';
+    for (const byte of outputUint8Array) {
+        const hex = byte.toString(16);
+        hash += '00'.slice(0, Math.max(0, 2 - hex.length)) + hex;
+    }
+    return hash;
 }
 function isDocumentNode(data) {
     const isObject = (data) => !!data && typeof data === 'object';

package/esm/reporter.js

@@ -0,0 +1,136 @@
+import { google, Report, ReportHeader } from '@apollo/usage-reporting-protobuf';
+import { OurReport } from './stats.js';
+const DEFAULT_REPORTING_ENDPOINT = 'https://usage-reporting.api.apollographql.com/api/ingress/traces';
+export class Reporter {
+    #yoga;
+    #logger = console;
+    #reportHeaders;
+    #options;
+    #reportsBySchema = {};
+    #nextSendAfterDelay;
+    #sending = [];
+    constructor(options, yoga, logger) {
+        this.#logger = logger;
+        this.#yoga = yoga;
+        this.#options = {
+            ...options,
+            maxBatchDelay: options.maxBatchDelay ?? 20 * 60 * 1000, // 20min
+            maxBatchUncompressedSize: options.maxBatchUncompressedSize ?? 4 * 1024 * 1024, // 4mb
+            maxTraceSize: options.maxTraceSize ?? 10 * 1024 * 1024, // 10mb
+            exportTimeout: options.exportTimeout ?? 30 * 1000, // 60s
+        };
+        this.#reportHeaders = {
+            graphRef: getGraphRef(options),
+            hostname: options.hostname ?? getEnvVar('HOSTNAME') ?? '',
+            uname: options.uname ?? '', // TODO: find a cross-platform way to get the uname
+            runtimeVersion: options.runtimeVersion ?? '',
+            agentVersion: options.agentVersion || `graphql-yoga@${yoga.version}`,
+        };
+    }
+    addTrace(schemaId, options) {
+        const report = this.#getReport(schemaId);
+        report.addTrace(options);
+        if (this.#options.alwaysSend ||
+            report.sizeEstimator.bytes >= this.#options.maxBatchUncompressedSize) {
+            return this.sendReport(schemaId);
+        }
+        this.#nextSendAfterDelay ||= setTimeout(() => this.flush(), this.#options.maxBatchDelay);
+        return;
+    }
+    async flush() {
+        return Promise.allSettled([
+            ...this.#sending, // When flushing, we want to also wait for previous traces to be sent, because it's mostly used for clean up
+            ...Object.keys(this.#reportsBySchema).map(schemaId => this.sendReport(schemaId)),
+        ]);
+    }
+    async sendReport(schemaId) {
+        const sending = this.#sendReport(schemaId);
+        this.#sending.push(sending);
+        sending.finally(() => this.#sending?.filter(p => p !== sending));
+        return sending;
+    }
+    async #sendReport(schemaId) {
+        const { fetchAPI: { fetch, CompressionStream, ReadableStream }, } = this.#yoga;
+        const report = this.#reportsBySchema[schemaId];
+        if (!report) {
+            throw new Error(`No report to send for schema ${schemaId}`);
+        }
+        if (this.#nextSendAfterDelay != null) {
+            clearTimeout(this.#nextSendAfterDelay);
+        }
+        delete this.#reportsBySchema[schemaId];
+        report.endTime = dateToProtoTimestamp(new Date());
+        report.ensureCountsAreIntegers();
+        const validationError = Report.verify(report);
+        if (!validationError) {
+            throw new TypeError(`Invalid report: ${validationError}`);
+        }
+        const encodedReport = Report.encode(report).finish();
+        const compressedReport = new ReadableStream({
+            start(controller) {
+                controller.enqueue(encodedReport);
+                controller.close();
+            },
+        }).pipeThrough(new CompressionStream('gzip'));
+        const { apiKey = getEnvVar('APOLLO_KEY'), endpoint = DEFAULT_REPORTING_ENDPOINT } = this.#options;
+        for (let tries = 0; tries < 5; tries++) {
+            try {
+                const abortCtl = new AbortController();
+                this.#logger?.debug(`Sending report (try ${tries}/5)`);
+                const timeout = setTimeout(() => abortCtl.abort(), this.#options.exportTimeout);
+                const response = await fetch(endpoint, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/protobuf',
+                        'content-encoding': 'gzip',
+                        // The presence of the api key is already checked at Yoga initialization time
+                        'x-api-key': apiKey,
+                        accept: 'application/json',
+                    },
+                    body: compressedReport,
+                    signal: abortCtl.signal,
+                });
+                clearTimeout(timeout);
+                const result = await response.text();
+                if (response.ok) {
+                    this.#logger?.debug('Report sent:', result);
+                    return;
+                }
+                throw result;
+            }
+            catch (err) {
+                this.#logger?.error('Failed to send report:', err);
+            }
+        }
+        throw new Error('Failed to send traces after 5 tries');
+    }
+    #getReport(schemaId) {
+        const report = this.#reportsBySchema[schemaId];
+        if (report) {
+            return report;
+        }
+        return (this.#reportsBySchema[schemaId] = new OurReport(new ReportHeader({
+            ...this.#reportHeaders,
+            executableSchemaId: schemaId,
+        })));
+    }
+}
+function getGraphRef(options) {
+    const graphRef = options.graphRef || getEnvVar('APOLLO_GRAPH_REF');
+    if (!graphRef) {
+        throw new Error('Missing GraphRef. Either provide `graphRef` option or `APOLLO_GRAPH_REF` environment variable');
+    }
+    return graphRef;
+}
+export function getEnvVar(name, defaultValue) {
+    return globalThis.process?.env?.[name] || defaultValue || undefined;
+}
+// Converts a JS Date into a Timestamp.
+export function dateToProtoTimestamp(date) {
+    const totalMillis = date.getTime();
+    const millis = totalMillis % 1000;
+    return new google.protobuf.Timestamp({
+        seconds: (totalMillis - millis) / 1000,
+        nanos: millis * 1e6,
+    });
+}