feat(laboratory/preflight-script): set request headers (#6378)

Author: jasonkuhrt

.changeset/empty-rockets-smell.md

@@ -0,0 +1,18 @@
+---
+'hive': minor
+---
+
+You can now set HTTP headers in your [Laboratory Preflight Script](https://the-guild.dev/graphql/hive/docs/dashboard/laboratory/preflight-scripts). Every time you run a request from Laboratory, your preflight headers, if any, will be merged into the request before it is sent.
+
+You achieve this by interacting with the [`Headers`](https://developer.mozilla.org/docs/web/api/headers) instance newly available at `lab.request.headers`. For example, this script would would add a `foo` header with the value `bar` to every Laboratory request.
+
+```ts
+lab.request.headers.set('foo', 'bar')
+```
+
+A few notes about how headers are merged:
+
+1. Unlike static headers, preflight headers do not receive environment variable substitutions on their values.
+2. Preflight headers take precedence, overwriting any same-named headers already in the Laboratory request.
+
+Documentation for this new feature is available at https://the-guild.dev/graphql/hive/docs/dashboard/laboratory/preflight-scripts#http-headers.

cypress/e2e/laboratory-preflight-script.cy.ts

@@ -1,5 +1,21 @@
 import { dedent } from '../support/testkit';
 
+const selectors = {
+  buttonModalCy: 'preflight-script-modal-button',
+  buttonToggleCy: 'toggle-preflight-script',
+  buttonHeaders: '[data-name="headers"]',
+  headersEditor: {
+    textArea: '.graphiql-editor-tool .graphiql-editor:last-child textarea',
+  },
+  graphiql: {
+    buttonExecute: '.graphiql-execute-button',
+  },
+
+  modal: {
+    buttonSubmitCy: 'preflight-script-modal-submit',
+  },
+};
+
 beforeEach(() => {
   cy.clearLocalStorage().then(async () => {
     cy.task('seedTarget').then(({ slug, refreshToken }: any) => {
@@ -186,6 +202,81 @@ throw new TypeError('Test')`,
 });
 
 describe('Execution', () => {
+  it('result.request.headers are added to the graphiql request base headers', () => {
+    // Setup Preflight Script
+    const preflightHeaders = {
+      foo: 'bar',
+    };
+    cy.dataCy(selectors.buttonToggleCy).click();
+    cy.dataCy(selectors.buttonModalCy).click();
+    setEditorScript(`lab.request.headers.append('foo', '${preflightHeaders.foo}')`);
+    cy.dataCy(selectors.modal.buttonSubmitCy).click();
+    // Run GraphiQL
+    cy.intercept({ headers: preflightHeaders }).as('request');
+    cy.get(selectors.graphiql.buttonExecute).click();
+    cy.wait('@request');
+  });
+
+  it('result.request.headers take precedence over graphiql request base headers', () => {
+    // Integrity Check: Ensure the header we think we're overriding is actually there to override.
+    // We achieve this by asserting a sent GraphiQL request includes the certain header and assume
+    // if its there once its there every time.
+    const baseHeaders = {
+      accept: 'application/json, multipart/mixed',
+    };
+    cy.intercept({ headers: baseHeaders }).as('integrityCheck');
+    cy.get(selectors.graphiql.buttonExecute).click();
+    cy.wait('@integrityCheck');
+    // Setup Preflight Script
+    const preflightHeaders = {
+      accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8',
+    };
+    cy.dataCy(selectors.buttonToggleCy).click();
+    cy.dataCy(selectors.buttonModalCy).click();
+    setEditorScript(`lab.request.headers.append('accept', '${preflightHeaders.accept}')`);
+    cy.dataCy(selectors.modal.buttonSubmitCy).click();
+    // Run GraphiQL
+    cy.intercept({ headers: preflightHeaders }).as('request');
+    cy.get(selectors.graphiql.buttonExecute).click();
+    cy.wait('@request');
+  });
+
+  it('result.request.headers are NOT substituted with environment variables', () => {
+    const barEnVarInterpolation = '{{bar}}';
+    // Setup Static Headers
+    const staticHeaders = {
+      foo_static: barEnVarInterpolation,
+    };
+    cy.get(selectors.buttonHeaders).click();
+    cy.get(selectors.headersEditor.textArea).type(JSON.stringify(staticHeaders), {
+      force: true,
+      parseSpecialCharSequences: false,
+    });
+    // Setup Preflight Script
+    const environmentVariables = {
+      bar: 'BAR_VALUE',
+    };
+    const preflightHeaders = {
+      foo_preflight: barEnVarInterpolation,
+    };
+    cy.dataCy(selectors.buttonToggleCy).click();
+    cy.dataCy(selectors.buttonModalCy).click();
+    setEditorScript(`
+      lab.environment.set('bar', '${environmentVariables.bar}')
+      lab.request.headers.append('foo_preflight', '${preflightHeaders.foo_preflight}')
+    `);
+    cy.dataCy(selectors.modal.buttonSubmitCy).click();
+    // Run GraphiQL
+    cy.intercept({
+      headers: {
+        ...preflightHeaders,
+        foo_static: environmentVariables.bar,
+      },
+    }).as('request');
+    cy.get(selectors.graphiql.buttonExecute).click();
+    cy.wait('@request');
+  });
+
   it('header placeholders are substituted with environment variables', () => {
     cy.dataCy('toggle-preflight-script').click();
     cy.get('[data-name="headers"]').click();

packages/web/app/src/lib/kit/helpers.ts

@@ -0,0 +1,10 @@
+export const tryOr = <$PrimaryResult, $FallbackResult>(
+  fn: () => $PrimaryResult,
+  fallback: () => $FallbackResult,
+): $PrimaryResult | $FallbackResult => {
+  try {
+    return fn();
+  } catch {
+    return fallback();
+  }
+};

packages/web/app/src/lib/kit/index.ts

@@ -0,0 +1,6 @@
+// eslint-disable-next-line import/no-self-import
+export * as Kit from './index';
+
+export * from './never';
+export * from './types/headers';
+export * from './helpers';

packages/web/app/src/lib/kit/never.ts

@@ -0,0 +1,15 @@
+/**
+ * This case is impossible.
+ * If it happens, then that means there is a bug in our code.
+ */
+export const neverCase = (value: never): never => {
+  never({ type: 'case', value });
+};
+
+/**
+ * This code cannot be reached.
+ * If it is reached, then that means there is a bug in our code.
+ */
+export const never: (context?: object) => never = context => {
+  throw new Error('Something that should be impossible happened', { cause: context });
+};

packages/web/app/src/lib/kit/types/headers.ts

@@ -0,0 +1,4 @@
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace Headers {
+  export type Encoded = [name: string, value: string][];
+}

packages/web/app/src/lib/preflight-sandbox/graphiql-plugin.tsx

@@ -32,10 +32,16 @@ import { Editor as MonacoEditor, OnMount, type Monaco } from '@monaco-editor/rea
 import { Cross2Icon, InfoCircledIcon, Pencil1Icon, TriangleRightIcon } from '@radix-ui/react-icons';
 import { captureException } from '@sentry/react';
 import { useParams } from '@tanstack/react-router';
+import { Kit } from '../kit';
 import { cn } from '../utils';
 import labApiDefinitionRaw from './lab-api-declaration?raw';
 import { IFrameEvents, LogMessage } from './shared-types';
 
+export type PreflightScriptResultData = Omit<
+  IFrameEvents.Outgoing.EventData.Result,
+  'type' | 'runId'
+>;
+
 export const preflightScriptPlugin: GraphiQLPlugin = {
   icon: () => (
     <svg
@@ -135,14 +141,6 @@ const PreflightScript_TargetFragment = graphql(`
 
 export type LogRecord = LogMessage | { type: 'separator' };
 
-function safeParseJSON(str: string): Record<string, unknown> | null {
-  try {
-    return JSON.parse(str);
-  } catch {
-    return null;
-  }
-}
-
 export const enum PreflightWorkerState {
   running,
   ready,
@@ -173,9 +171,24 @@ export function usePreflightScript(args: {
 
   const currentRun = useRef<null | Function>(null);
 
-  async function execute(script = target?.preflightScript?.sourceCode ?? '', isPreview = false) {
+  async function execute(
+    script = target?.preflightScript?.sourceCode ?? '',
+    isPreview = false,
+  ): Promise<PreflightScriptResultData> {
+    const resultEnvironmentVariablesDecoded: PreflightScriptResultData['environmentVariables'] =
+      Kit.tryOr(
+        () => JSON.parse(latestEnvironmentVariablesRef.current),
+        () => ({}),
+      );
+    const result: PreflightScriptResultData = {
+      request: {
+        headers: [],
+      },
+      environmentVariables: resultEnvironmentVariablesDecoded,
+    };
+
     if (isPreview === false && !isPreflightScriptEnabled) {
-      return safeParseJSON(latestEnvironmentVariablesRef.current);
+      return result;
     }
 
     const id = crypto.randomUUID();
@@ -201,7 +214,8 @@ export function usePreflightScript(args: {
           type: IFrameEvents.Incoming.Event.run,
           id,
           script,
-          environmentVariables: (environmentVariables && safeParseJSON(environmentVariables)) || {},
+          // Preflight Script has read/write relationship with environment variables.
+          environmentVariables: result.environmentVariables,
         } satisfies IFrameEvents.Incoming.EventData,
         '*',
       );
@@ -257,16 +271,23 @@ export function usePreflightScript(args: {
         }
 
         if (ev.data.type === IFrameEvents.Outgoing.Event.result) {
-          const mergedEnvironmentVariables = JSON.stringify(
-            {
-              ...safeParseJSON(latestEnvironmentVariablesRef.current),
-              ...ev.data.environmentVariables,
-            },
+          const mergedEnvironmentVariables = {
+            ...result.environmentVariables,
+            ...ev.data.environmentVariables,
+          };
+          result.environmentVariables = mergedEnvironmentVariables;
+          result.request.headers = ev.data.request.headers;
+
+          // Cause the new state of environment variables to be
+          // written back to local storage.
+          const mergedEnvironmentVariablesEncoded = JSON.stringify(
+            result.environmentVariables,
             null,
             2,
           );
-          setEnvironmentVariables(mergedEnvironmentVariables);
-          latestEnvironmentVariablesRef.current = mergedEnvironmentVariables;
+          setEnvironmentVariables(mergedEnvironmentVariablesEncoded);
+          latestEnvironmentVariablesRef.current = mergedEnvironmentVariablesEncoded;
+
           setLogs(logs => [
             ...logs,
             {
@@ -301,7 +322,6 @@ export function usePreflightScript(args: {
           ]);
           setFinished();
           closedOpenedPrompts();
-
           return;
         }
 
@@ -310,6 +330,27 @@ export function usePreflightScript(args: {
           setLogs(logs => [...logs, log]);
           return;
         }
+
+        if (ev.data.type === IFrameEvents.Outgoing.Event.ready) {
+          console.debug('preflight sandbox graphiql plugin: noop iframe event:', ev.data);
+          return;
+        }
+
+        if (ev.data.type === IFrameEvents.Outgoing.Event.start) {
+          console.debug('preflight sandbox graphiql plugin: noop iframe event:', ev.data);
+          return;
+        }
+
+        // Window message events can be emitted from unknowable sources.
+        // For example when our e2e tests runs within Cypress GUI, we see a `MessageEvent` with `.data` of `{ vscodeScheduleAsyncWork: 3 }`.
+        // Since we cannot know if the event source is Preflight Script, we cannot perform an exhaustive check.
+        //
+        // Kit.neverCase(ev.data);
+        //
+        console.debug(
+          'preflight sandbox graphiql plugin: An unknown window message event received. Ignoring.',
+          ev,
+        );
       }
 
       window.addEventListener('message', eventHandler);
@@ -328,7 +369,8 @@ export function usePreflightScript(args: {
       window.removeEventListener('message', eventHandler);
 
       setState(PreflightWorkerState.ready);
-      return safeParseJSON(latestEnvironmentVariablesRef.current);
+
+      return result;
     } catch (err) {
       if (err instanceof Error) {
         setLogs(prev => [
@@ -346,7 +388,7 @@ export function usePreflightScript(args: {
           },
         ]);
         setState(PreflightWorkerState.ready);
-        return safeParseJSON(latestEnvironmentVariablesRef.current);
+        return result;
       }
       throw err;
     }

packages/web/app/src/lib/preflight-sandbox/lab-api-declaration.ts

@@ -8,6 +8,22 @@
 // and use Prettier to format it, have syntax highlighting, etc.
 
 interface LabAPI {
+  /**
+   * Contains aspects of the request that you can manipulate before it is sent.
+   */
+  request: {
+    /**
+     * Headers that will be added to the request. They are merged
+     * using the following rules:
+     *
+     * 1. Do *not* interpolate environment variables.
+     *
+     * 2. Upon a collision with a base header, this header takes precedence.
+     *    This means that if the base headers contain "foo: bar" and you've added
+     *    "foo: qux" here, the final headers become "foo: qux" (*not* "foo: bar, qux").
+     */
+    headers: Headers;
+  };
   /**
    * [CryptoJS](https://cryptojs.gitbook.io/docs) library.
    */