Add performance hints support (#309)

Co-authored-by: James Rodewig <[email protected]>
fauna · Dec 2, 2024 · fa87bfb · fa87bfb
1 parent a7ffe6d
commit fa87bfb
Show file tree

Hide file tree

Showing 5 changed files with 412 additions and 11 deletions.
diff --git a/__tests__/functional/client-configuration.test.ts b/__tests__/functional/client-configuration.test.ts
@@ -101,13 +101,35 @@ an environmental variable named FAUNA_SECRET or pass it to the Client constructo
     expectedHeader: { key: string; value: string };
   };
 
+  it("defaults performance_hints to not setting the x-performance-hints header", async () => {
+    expect.assertions(1);
+    const httpClient: HTTPClient = {
+      async request(req) {
+        expect(req.headers["x-performance-hints"]).toBeUndefined();
+        return getDefaultHTTPClient(getDefaultHTTPClientOptions()).request(req);
+      },
+
+      close() {},
+    };
+
+    const client = getClient(
+      {
+        query_timeout_ms: 5000,
+      },
+      httpClient,
+    );
+    await client.query<number>(fql`"taco".length`);
+    client.close();
+  });
+
   it.each`
     fieldName                   | fieldValue                                                   | expectedHeader
     ${"linearized"}             | ${true}                                                      | ${{ key: "x-linearized", value: "true" }}
     ${"max_contention_retries"} | ${3}                                                         | ${{ key: "x-max-contention-retries", value: "3" }}
     ${"query_tags"}             | ${{ t1: "v1", t2: "v2" }}                                    | ${{ key: "x-query-tags", value: "t1=v1,t2=v2" }}
     ${"traceparent"}            | ${"00-750efa5fb6a131eb2cf4db39f28366cb-5669e71839eca76b-00"} | ${{ key: "traceparent", value: "00-750efa5fb6a131eb2cf4db39f28366cb-5669e71839eca76b-00" }}
     ${"typecheck"}              | ${false}                                                     | ${{ key: "x-typecheck", value: "false" }}
+    ${"performance_hints"}      | ${true}                                                      | ${{ key: "x-performance-hints", value: "true" }}
   `(
     "Setting clientConfiguration $fieldName leads to it being sent in headers",
     async ({ fieldName, fieldValue, expectedHeader }: HeaderTestInput) => {

diff --git a/src/client-configuration.ts b/src/client-configuration.ts
@@ -120,6 +120,13 @@ export interface ClientConfiguration {
    */
   typecheck?: boolean;
 
+  /**
+   * Enable or disable performance hints. Defaults to disabled.
+   * The QueryInfo object includes performance hints in the `summary` field, which is a
+   * top-level field in the response object.
+   */
+  performance_hints?: boolean;
+
   /**
    * Max attempts for retryable exceptions. Default is 3.
    */

diff --git a/src/client.ts b/src/client.ts
@@ -1,6 +1,6 @@
 import {
-  FeedClientConfiguration,
   ClientConfiguration,
+  FeedClientConfiguration,
   StreamClientConfiguration,
   endpoints,
 } from "./client-configuration";
@@ -15,41 +15,41 @@ import {
   getServiceError,
 } from "./errors";
 import {
+  FaunaAPIPaths,
+  HTTPRequest,
   HTTPStreamClient,
   StreamAdapter,
   getDefaultHTTPClient,
-  isStreamClient,
   isHTTPResponse,
+  isStreamClient,
   type HTTPClient,
-  HTTPRequest,
-  FaunaAPIPaths,
 } from "./http-client";
 import { Query } from "./query-builder";
 import { TaggedTypeFormat } from "./tagged-type";
 import { getDriverEnv } from "./util/environment";
 import { withRetries } from "./util/retryable";
 import {
-  FeedPage,
   EmbeddedSet,
+  EventSource,
+  FeedPage,
   Page,
   SetIterator,
-  EventSource,
   isEventSource,
 } from "./values";
 import {
+  EncodedObject,
+  FeedError,
   FeedRequest,
   FeedSuccess,
-  EncodedObject,
-  isQueryFailure,
-  isQuerySuccess,
   QueryOptions,
   QueryRequest,
   StreamEvent,
   StreamEventData,
   StreamEventStatus,
+  isQueryFailure,
+  isQuerySuccess,
   type QuerySuccess,
   type QueryValue,
-  FeedError,
 } from "./wire-protocol";
 
 type RequiredClientConfig = ClientConfiguration &
@@ -649,6 +649,7 @@ in an environmental variable named FAUNA_SECRET or pass it to the Client\
 
     setHeader("x-format", fromObject.format);
     setHeader("x-typecheck", fromObject.typecheck);
+    setHeader("x-performance-hints", fromObject.performance_hints);
     setHeader("x-query-timeout-ms", fromObject.query_timeout_ms);
     setHeader("x-linearized", fromObject.linearized);
     setHeader("x-max-contention-retries", fromObject.max_contention_retries);

diff --git a/src/wire-protocol.ts b/src/wire-protocol.ts
@@ -96,6 +96,14 @@ export interface QueryOptions {
    */
   typecheck?: boolean;
 
+  /**
+   * Enable or disable performance hints. Defaults to disabled.
+   * The QueryInfo object includes performance hints in the `summary` field, which is a
+   * top-level field in the response object.
+   * Overrides the optional setting on the {@link ClientConfiguration}.
+   */
+  performance_hints?: boolean;
+
   /**
    * Secret to use instead of the client's secret.
    */