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

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

@@ -0,0 +1,14 @@
+export namespace Headers {
+  /**
+   * Take given HeadersInit and append it (mutating) into given Headers.
+   *
+   * @param headers - The Headers object to append to.
+   * @param headersInit - The HeadersInit object to append from.
+   */
+  export const appendInit = (headers: Headers, headersInit: HeadersInit): void => {
+    const newHeaders = new globalThis.Headers(headersInit);
+    newHeaders.forEach((value, key) => {
+      headers.append(key, value);
+    });
+  };
+}

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

@@ -0,0 +1,5 @@
+export * as Kit from './index';
+
+export * from './never';
+export * from './headers';
+export * from './types/json';

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

@@ -0,0 +1,16 @@
+/**
+ * This case is impossible.
+ * If it is, then there is a bug in our code.
+ */
+export const neverCase = (value: never): never => {
+  never(`Unhandled case: ${String(value)}`);
+};
+
+/**
+ * This code cannot be reached.
+ * If it can be, then there is a bug in our code.
+ */
+export const never: (contextMessage?: string) => never = contextMessage => {
+  contextMessage = contextMessage ?? '(no additional context provided)';
+  throw new Error(`Something that should be impossible happened: ${contextMessage}`);
+};

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

@@ -0,0 +1,19 @@
+export namespace JSON {
+  export const encode = <value extends Value>(value: value): string => {
+    return globalThis.JSON.stringify(value);
+  };
+
+  export const encodePretty = <value extends Value>(value: value): string => {
+    return globalThis.JSON.stringify(value, null, 2);
+  };
+
+  export const decode = (value: string): Value => {
+    return globalThis.JSON.parse(value);
+  };
+
+  export type Value = PrimitiveValue | NonPrimitiveValue;
+
+  export type NonPrimitiveValue = { [key: string]: Value } | Array<Value>;
+
+  export type PrimitiveValue = string | number | boolean | null;
+}

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

@@ -38,10 +38,13 @@ import {
   TriangleRightIcon,
 } from '@radix-ui/react-icons';
 import { useParams } from '@tanstack/react-router';
+import { Kit } from '../kit';
 import { cn } from '../utils';
 import type { LogMessage } from './preflight-script-worker';
 import { IFrameEvents } from './shared-types';
 
+type Result = Omit<IFrameEvents.Outgoing.ResultEventData, 'type' | 'runId'>;
+
 export const preflightScriptPlugin: GraphiQLPlugin = {
   icon: () => (
     <svg
@@ -141,9 +144,11 @@ const PreflightScript_TargetFragment = graphql(`
 
 type LogRecord = LogMessage | { type: 'separator' };
 
-function safeParseJSON(str: string): Record<string, unknown> | null {
+function safeParseJSON<$UnsafeCast extends Kit.JSON.Value = Kit.JSON.Value>(
+  str: string,
+): $UnsafeCast | null {
   try {
-    return JSON.parse(str);
+    return Kit.JSON.decode(str) as $UnsafeCast;
   } catch {
     return null;
   }
@@ -165,23 +170,47 @@ export function usePreflightScript(args: {
     'hive:laboratory:isPreflightScriptEnabled',
     false,
   );
-  const [environmentVariables, setEnvironmentVariables] = useLocalStorage(
-    'hive:laboratory:environment',
-    '',
-  );
+
+  // ------------
+  // Result State
+  // ------------
+  //
+  // todo: Probably better to store the result as a single JSON object value.
+  // Use a proper versioned schema with codecs for coercing, defaults, validation, etc.
+  //
+  // todo: Improve `useLocalStorage` by allowing passing a codec? Then we can co-locate
+  // the codec with the data and have it applied transparently, use a decoded value
+  // for the default, etc. ?
+
+  const [environmentVariables, setEnvironmentVariables] = useLocalStorage('hive:laboratory:environment', '{}'); // prettier-ignore
   const latestEnvironmentVariablesRef = useRef(environmentVariables);
-  useEffect(() => {
-    latestEnvironmentVariablesRef.current = environmentVariables;
-  });
+  useEffect(() => { latestEnvironmentVariablesRef.current = environmentVariables; }); // prettier-ignore
+  const decodeEnvironmentVariables = (encoded: string) => safeParseJSON<Result['environmentVariables']>(encoded) ?? {}; // prettier-ignore
+
+  const [headers, setHeaders] = useLocalStorage('hive:laboratory:headers', '[]');
+  const latestHeadersRef = useRef(headers);
+  useEffect(() => { latestHeadersRef.current = headers; }); // prettier-ignore
+  const decodeHeaders = (encoded: string) => safeParseJSON<Result['headers']>(encoded) ?? [];
+
+  const decodeResult = (): Result => {
+    return {
+      environmentVariables: decodeEnvironmentVariables(latestEnvironmentVariablesRef.current), // prettier-ignore
+      headers: decodeHeaders(latestHeadersRef.current),
+    };
+  };
+  // -----------
 
   const [state, setState] = useState<PreflightWorkerState>(PreflightWorkerState.ready);
   const [logs, setLogs] = useState<LogRecord[]>([]);
 
   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<Result> {
     if (isPreview === false && !isPreflightScriptEnabled) {
-      return safeParseJSON(latestEnvironmentVariablesRef.current);
+      return decodeResult();
     }
 
     const id = crypto.randomUUID();
@@ -201,7 +230,7 @@ export function usePreflightScript(args: {
           type: IFrameEvents.Incoming.Event.run,
           id,
           script,
-          environmentVariables: (environmentVariables && safeParseJSON(environmentVariables)) || {},
+          environmentVariables: decodeEnvironmentVariables(environmentVariables),
         } satisfies IFrameEvents.Incoming.EventData,
         '*',
       );
@@ -257,16 +286,20 @@ export function usePreflightScript(args: {
         }
 
         if (ev.data.type === IFrameEvents.Outgoing.Event.result) {
-          const mergedEnvironmentVariables = JSON.stringify(
-            {
-              ...safeParseJSON(latestEnvironmentVariablesRef.current),
-              ...ev.data.environmentVariables,
-            },
-            null,
-            2,
-          );
-          setEnvironmentVariables(mergedEnvironmentVariables);
-          latestEnvironmentVariablesRef.current = mergedEnvironmentVariables;
+          const mergedEnvironmentVariablesEncoded = Kit.JSON.encodePretty({
+            ...decodeEnvironmentVariables(latestEnvironmentVariablesRef.current),
+            ...ev.data.environmentVariables,
+          });
+          setEnvironmentVariables(mergedEnvironmentVariablesEncoded);
+          latestEnvironmentVariablesRef.current = mergedEnvironmentVariablesEncoded;
+
+          const mergedHeadersEncoded = Kit.JSON.encodePretty([
+            ...decodeHeaders(latestHeadersRef.current),
+            ...ev.data.headers,
+          ]);
+          setHeaders(mergedHeadersEncoded);
+          latestHeadersRef.current = mergedHeadersEncoded;
+
           setLogs(logs => [
             ...logs,
             `> End running script. Done in ${(Date.now() - now) / 1000}s`,
@@ -299,6 +332,16 @@ export function usePreflightScript(args: {
           setLogs(logs => [...logs, log]);
           return;
         }
+
+        if (ev.data.type === IFrameEvents.Outgoing.Event.ready) {
+          return;
+        }
+
+        if (ev.data.type === IFrameEvents.Outgoing.Event.start) {
+          return;
+        }
+
+        Kit.neverCase(ev.data);
       }
 
       window.addEventListener('message', eventHandler);
@@ -317,7 +360,7 @@ export function usePreflightScript(args: {
       window.removeEventListener('message', eventHandler);
 
       setState(PreflightWorkerState.ready);
-      return safeParseJSON(latestEnvironmentVariablesRef.current);
+      return decodeResult();
     } catch (err) {
       if (err instanceof Error) {
         setLogs(prev => [
@@ -329,7 +372,7 @@ export function usePreflightScript(args: {
           },
         ]);
         setState(PreflightWorkerState.ready);
-        return safeParseJSON(latestEnvironmentVariablesRef.current);
+        return decodeResult();
       }
       throw err;
     }

packages/web/app/src/lib/preflight-sandbox/preflight-script-worker.ts

@@ -1,9 +1,15 @@
 import CryptoJS from 'crypto-js';
 import CryptoJSPackageJson from 'crypto-js/package.json';
+import { Kit } from '../kit';
 import { ALLOWED_GLOBALS } from './allowed-globals';
 import { isJSONPrimitive } from './json';
 import { WorkerEvents } from './shared-types';
 
+interface WorkerData {
+  headers: Headers;
+  environmentVariables: Record<string, unknown>;
+}
+
 export type LogMessage = string | Error;
 
 /**
@@ -47,11 +53,14 @@ async function execute(args: WorkerEvents.Incoming.EventData): Promise<void> {
     return;
   }
 
-  const { environmentVariables, script } = args;
+  const { script } = args;
 
-  // When running in worker `environmentVariables` will not be a reference to the main thread value
-  // but sometimes this will be tested outside the worker, so we don't want to mutate the input in that case
-  const workingEnvironmentVariables = { ...environmentVariables };
+  const workerData: WorkerData = {
+    headers: new Headers(),
+    // When running in worker `environmentVariables` will not be a reference to the main thread value
+    // but sometimes this will be tested outside the worker, so we don't want to mutate the input in that case
+    environmentVariables: { ...args.environmentVariables },
+  };
 
   // generate list of all in scope variables, we do getOwnPropertyNames and `for in` because each contain slightly different sets of keys
   const allGlobalKeys = Object.getOwnPropertyNames(globalThis);
@@ -116,17 +125,44 @@ async function execute(args: WorkerEvents.Incoming.EventData): Promise<void> {
     },
     environment: {
       get(key: string) {
-        return Object.freeze(workingEnvironmentVariables[key]);
+        return Object.freeze(workerData.environmentVariables[key]);
       },
       set(key: string, value: unknown) {
         const validValue = getValidEnvVariable(value);
         if (validValue === undefined) {
-          delete workingEnvironmentVariables[key];
+          delete workerData.environmentVariables[key];
         } else {
-          workingEnvironmentVariables[key] = validValue;
+          workerData.environmentVariables[key] = validValue;
         }
       },
     },
+    /**
+     * Helpers for manipulating the request before it is sent.
+     */
+    request: {
+      /**
+       * Helpers for manipulating the request headers.
+       */
+      headers: {
+        /**
+         * Add one header to the request.
+         *
+         * @param header - The name of the header.
+         * @param value - The value of the header.
+         */
+        add: (header: string, value: string) => {
+          workerData.headers.append(header, value);
+        },
+        /**
+         * Add multiple headers to the request.
+         *
+         * @param headersInit - The {@link HeadersInit} to add.
+         */
+        addMany: (headersInit: HeadersInit) => {
+          Kit.Headers.appendInit(workerData.headers, headersInit);
+        },
+      },
+    },
     /**
      * Mimics the `prompt` function in the browser, by sending a message to the main thread
      * and waiting for a response.
@@ -167,9 +203,12 @@ ${script}})()`;
     sendMessage({ type: WorkerEvents.Outgoing.Event.error, error: error as Error });
     return;
   }
+
   sendMessage({
     type: WorkerEvents.Outgoing.Event.result,
-    environmentVariables: workingEnvironmentVariables,
+    // todo: We need to more precisely type environment value. Currently unknown. Why?
+    environmentVariables: workerData.environmentVariables as any,
+    headers: Array.from(workerData.headers.entries()),
   });
 }
 

packages/web/app/src/lib/preflight-sandbox/preflight-worker-embed.ts

@@ -1,3 +1,4 @@
+import { Kit } from '../kit';
 import PreflightWorker from './preflight-script-worker?worker&inline';
 import { IFrameEvents, WorkerEvents } from './shared-types';
 
@@ -103,9 +104,9 @@ function handleEvent(data: IFrameEvents.Incoming.EventData) {
 
         if (ev.data.type === WorkerEvents.Outgoing.Event.result) {
           postMessage({
+            ...ev.data,
             type: IFrameEvents.Outgoing.Event.result,
             runId,
-            environmentVariables: ev.data.environmentVariables,
           });
           terminate();
           return;
@@ -129,6 +130,8 @@ function handleEvent(data: IFrameEvents.Incoming.EventData) {
           terminate();
           return;
         }
+
+        Kit.neverCase(ev.data);
       },
     );