Improve code comments (#293)

* wip

* lots of documentation for the sandbox code

* update docs

Author: YousefED

packages/editor/src/runtime/executor/executionHosts/ExecutionHost.ts

@@ -2,9 +2,33 @@ import React from "react";
 import { lifecycle } from "vscode-lib";
 import { TypeCellCodeModel } from "../../../models/TypeCellCodeModel";
 
+/**
+ * The ExecutionHost is responsible for rendering the output of a notebook/code cell.
+ * The abstraction is introduced to support the Iframe Sandbox
+ *
+ * There are two types of ExecutionHosts:
+ * - Local
+ * - Sandboxed
+ *
+ * The LocalExecutionHost just renders output in the same document as the container, and can be used for testing
+ * The SandboxExecutionHost renders an iframe and evaluates end-user code in there, to isolate the code execution in a different domain.
+ *
+ * ExecutionHosts are called from NotebookRenderer (which renders the monaco editors for cells)
+ */
 export type ExecutionHost = lifecycle.IDisposable & {
+  /**
+   * Render the container of the execution host:
+   * - the LocalExecutionHost doesn't use this
+   * - the Sandbox uses this to render the <iframe>
+   */
   renderContainer(): React.ReactElement;
 
+  /**
+   * Render the cell output:
+   * - the LocalExecutionHost renders the Cell Output directly
+   * - the Sandbox renders a "fake" div (OutputShadow) that has the same size as the actual output.
+   *   The actual output is rendered in the <iframe> which is rendered in renderContainer()
+   */
   renderOutput(
     model: TypeCellCodeModel,
     setHovering?: (hover: boolean) => void

packages/editor/src/runtime/executor/executionHosts/local/LocalExecutionHost.tsx

@@ -13,15 +13,16 @@ import { TypeCellModuleCompiler } from "../../resolver/typecell/TypeCellModuleCo
 import { VisualizerExtension } from "../../../extensions/visualizer/VisualizerExtension";
 
 let ENGINE_ID = 0;
-export default class LocalExecutionHost extends lifecycle.Disposable implements ExecutionHost {
+
+export default class LocalExecutionHost
+  extends lifecycle.Disposable
+  implements ExecutionHost
+{
   private disposed: boolean = false;
 
-  private readonly outputs = observable.map<string, ModelOutput>(
-    undefined,
-    {
-      deep: false,
-    }
-  );
+  private readonly outputs = observable.map<string, ModelOutput>(undefined, {
+    deep: false,
+  });
 
   private readonly engine: Engine<CompiledCodeModel>;
   private readonly id = ENGINE_ID++;
@@ -34,32 +35,35 @@ export default class LocalExecutionHost extends lifecycle.Disposable implements
     super();
     this.engine = new Engine(
       getTypeCellResolver(documentId, "LEH-" + this.id, (moduleName) => {
-        return new TypeCellModuleCompiler(moduleName, monacoInstance)
+        return new TypeCellModuleCompiler(moduleName, monacoInstance);
       })
     );
     this.engine.registerModelProvider(compileEngine);
 
-    const visualizerExtension = this._register(new VisualizerExtension(compileEngine, documentId, monacoInstance));
+    const visualizerExtension = this._register(
+      new VisualizerExtension(compileEngine, documentId, monacoInstance)
+    );
 
-    this._register(visualizerExtension.onUpdateVisualizers(e => {
-      for (let [path, visualizers] of Object.entries(e)) {
-        this.outputs.get(path)!.updateVisualizers(visualizers);
-      }
-    }));
+    this._register(
+      visualizerExtension.onUpdateVisualizers((e) => {
+        for (let [path, visualizers] of Object.entries(e)) {
+          this.outputs.get(path)!.updateVisualizers(visualizers);
+        }
+      })
+    );
 
     this._register(
       this.engine.onOutput(({ model, output }) => {
         let modelOutput = this.outputs.get(model.path);
         if (!modelOutput) {
           modelOutput = this._register(
-            new ModelOutput(
-              this.engine.observableContext.context
-            )
+            new ModelOutput(this.engine.observableContext.context)
           );
           this.outputs.set(model.path, modelOutput);
         }
         modelOutput.updateValue(output);
-      }));
+      })
+    );
   }
 
   public renderContainer() {

packages/editor/src/runtime/executor/executionHosts/sandboxed/FreezeAlert.tsx

@@ -2,35 +2,39 @@ import * as React from "react";
 import Flag from "@atlaskit/flag";
 import { VscWarning } from "react-icons/vsc";
 
+/**
+ * A popup that is shown when we haven't received a "pong" message for a while.
+ * There might be an infinite loop or other error in the user code.
+ */
 export const FreezeAlert = (props: {
-    // onDismiss: () => void;
-    onReload: () => void;
+  // onDismiss: () => void;
+  onReload: () => void;
 }) => {
-    return (
-        <Flag
-            css={{
-                zIndex: 2000,
-                backgroundColor: "rgb(222, 53, 11)",
-            }}
-            appearance="error"
-            icon={
-                <VscWarning
-                    css={{
-                        width: "24px",
-                        height: "24px",
-                        padding: "2px",
-                    }}
-                />
-            }
-            id="error"
-            key="error"
-            title="The document is not responding"
-            description="It seems like your document has frozen. Perhaps there is an infinite loop in the code?
-      Fix any code errors and click Reload to retry."
-            actions={[
-                // { content: "Dismiss", onClick: props.onDismiss },
-                { content: "Reload", onClick: props.onReload },
-            ]}
+  return (
+    <Flag
+      css={{
+        zIndex: 2000,
+        backgroundColor: "rgb(222, 53, 11)",
+      }}
+      appearance="error"
+      icon={
+        <VscWarning
+          css={{
+            width: "24px",
+            height: "24px",
+            padding: "2px",
+          }}
         />
-    );
-}
+      }
+      id="error"
+      key="error"
+      title="The document is not responding"
+      description="It seems like your document has frozen. Perhaps there is an infinite loop in the code?
+      Fix any code errors and click Reload to retry."
+      actions={[
+        // { content: "Dismiss", onClick: props.onDismiss },
+        { content: "Reload", onClick: props.onReload },
+      ]}
+    />
+  );
+};

packages/editor/src/runtime/executor/executionHosts/sandboxed/HostBridgeMethods.ts

@@ -0,0 +1,28 @@
+/**
+ * The methods the host exposes that are callable by the iframe (from iframesandbox/FrameConnection)
+ */
+export type HostBridgeMethods = {
+  /**
+   * This is used to resolve imported TypeCell modules. When the Javascript evaluated in the import,
+   * it can require another TypeCell notebook using `import * as nb from "!@username/notebook"`.
+   *
+   * The host then needs to fetch this module (!@username/notebook) from TypeCell, compile it, and
+   * send the compiled javascript back to the iframe. It also keeps watching the TypeCell module for changes
+   * and sends changes across the bridge.
+   */
+  registerTypeCellModuleCompiler: (moduleName: string) => Promise<void>;
+  unregisterTypeCellModuleCompiler: (moduleName: string) => Promise<void>;
+
+  /**
+   * Call when the mouse exits the output of a cell
+   */
+  mouseLeave: () => Promise<void>;
+
+  /**
+   * Call when dimensenions of the output of cell `id` have changed.
+   */
+  setDimensions: (
+    id: string,
+    dimensions: { width: number; height: number }
+  ) => Promise<void>;
+};

packages/editor/src/runtime/executor/executionHosts/sandboxed/ModelForwarder.ts

@@ -1,31 +1,24 @@
 import { CompiledCodeModel } from "../../../../models/CompiledCodeModel";
 import { event, lifecycle } from "vscode-lib";
+import { IframeBridgeMethods } from "./iframesandbox/IframeBridgeMethods";
 
 type ModelProvider = {
   onDidCreateCompiledModel: event.Event<CompiledCodeModel>;
   compiledModels: CompiledCodeModel[];
 };
 
-export type MessageBridge = {
-  updateModels: (
-    bridgeId: string,
-    models: {
-      modelId: string;
-      model: {
-        value: string;
-      };
-    }[]
-  ) => Promise<void>;
-  updateModel: (
-    bridgeId: string,
-    modelId: string,
-    model: {
-      value: string;
-    }
-  ) => Promise<void>;
-  deleteModel: (bridgeId: string, modelId: string) => Promise<void>;
-};
+export type MessageBridge = Pick<
+  IframeBridgeMethods,
+  "updateModels" | "updateModel" | "deleteModel"
+>;
 
+/**
+ * The ModelForwarder bridges a ModelProvider and the MessageBridge.
+ *
+ * It:
+ * - listens to changes in the ModelProvider...
+ * - ...and forwards these changes over the MessageBridge
+ */
 export class ModelForwarder extends lifecycle.Disposable {
   private disposed = false;
   constructor(

packages/editor/src/runtime/executor/executionHosts/sandboxed/OutputShadow.tsx

@@ -2,6 +2,16 @@ import { runInAction } from "mobx";
 import { observer } from "mobx-react-lite";
 import { useEffect, useRef } from "react";
 
+/**
+ * The OutputShadow is a "fake" empty div which the SandboxedExecutionHost renders
+ * in the position of the cell output.
+ * However, the actual cell output is rendered by the Iframe (iframe/Frame.tsx).
+ *
+ * The dimensions of the OutputShadow are passed in from the iframe (via the bridge),
+ *  so the iframe knows where to render the actual output.
+ *
+ * The position of the OutputShadow are passed to the iframe over the bridge (by the host).
+ */
 export const OutputShadow = observer(
   (props: {
     dimensions: { width: number; height: number };
@@ -11,6 +21,9 @@ export const OutputShadow = observer(
   }) => {
     const divRef = useRef<HTMLDivElement>(null);
 
+    // Monitor the position of the OutputShadow so we can pass
+    // updates to the iframe. The iframe then knows at which x, y position
+    // it needs to render the output
     useEffect(() => {
       const updatePositions = () => {
         if (!divRef.current) {
@@ -28,7 +41,9 @@ export const OutputShadow = observer(
           }
         });
       };
-      const handle = setInterval(updatePositions, 20); // TODO: replace with MutationObserver?
+      // We use setInterval to monitor the positions.
+      // TODO: can we use MutationObserver or something else for this?
+      const handle = setInterval(updatePositions, 20);
       return () => {
         clearInterval(handle);
       };

packages/editor/src/runtime/executor/executionHosts/sandboxed/README.md

@@ -0,0 +1,40 @@
+# Iframe sandbox architecture
+
+The actual end-user code that users can enter in TypeCell code cells, gets executed in an iframe that runs on a different domain.
+
+## Why?
+
+End-user code should not be able to access the TypeCell application javascript. Otherwise, it could delete / create / modify Notebooks by the user without the user's permission. Or for example, steal authentication cookies and send them to a third party using `fetch`.
+
+## Architecture
+
+`NotebookRenderer` calls `SandboxedExecutionHost.renderContainer()`. This creates an Iframe where the end-user code is evaluated and the outputs are rendered.
+
+`NotebookRenderer` calls `SandboxedExecutionHost.renderOutput()` whereever the output of cells should be rendered. `SandboxedExecutionHost` renders a so-called `OutputShadow` div in the location. This div is used for two reasons:
+
+- We keep track of it's location (x,y position), so that in the Iframe, we know at which location we need to render the cell output
+- We update its dimensions with the actual dimensions of the output. This is done so that the rest of the document flows accordingly (i.e.: other cells / content below the cell are moved down when the output gets larger).
+
+## Bridge
+
+We use PostMessage communication to communicate between the Host and the Iframe. This is done using the [Penpal](https://github.com/Aaronius/penpal) library.
+
+The interfaces are:
+
+- [IframeBridgeMethods](./iframesandbox/IframeBridgeMethods.ts): methods the host can call on the iframe
+- [HostBridgeMethods](./HostBridgeMethods.ts): methods the iframe can call on the host
+
+The main data that's being communicated across the bridge:
+
+- The host sends javascript code of the code cells (code models) to the iframe
+- The host sends the position of code cell outputs (OutputShadow (x, y) positions) to the iframe
+- The iframe sends dimensions of rendered output to the host (so that it can change the dimensions of OutputShadow)
+- When the user mouse-outs an Output, the iframe sends a mouseleave event to the host. The host then re-acquires mouse pointer events by setting pointerEvents:none on the iframe.
+
+## Files
+
+- [iframesandbox](./iframesandbox) directory contains the files that are used in the iframe
+
+## Modules
+
+An extra complexity is when client code imports a TypeCell module (e.g.: `import * as nb from "@user/notebook"`). The iframe signals this required module import to the Host, upon which the host starts watching and compiling the notebook. It then sends the compiled javascript code back to the iframe across the bridge.