Add jsdoc, and move iframe contract comment

ampproject · Apr 2, 2021 · 16f75d3 · 16f75d3
1 parent 43d2b70
commit 16f75d3
Show file tree

Hide file tree

Showing 3 changed files with 25 additions and 10 deletions.
diff --git a/demo/sandboxed/sandbox-iframe.html b/demo/sandboxed/sandbox-iframe.html
@@ -1,10 +1,8 @@
 <html>
   <script>
-    // The IframeWorker contract is that it must:
-    // 1. Send a ready message.
-    // 2. Listen for the Worker code to initialize it with.
-    // 3. Proxy all messages between the Worker and Parent, including errors.
-
+    /**
+     * See `iframe-worker.ts` for the iframe proxy contract.
+     */
     let parentOrigin = '*';
     const MESSAGE_TYPES = {
       ready: 'iframe-ready',

diff --git a/src/main-thread/iframe-worker.ts b/src/main-thread/iframe-worker.ts
@@ -24,6 +24,12 @@ export type MessageToIframe = { type: 'terminate' } | { type: 'init-worker'; cod
 /**
  * An almost drop-in replacement for a standard Web Worker, although this one
  * within a sandboxed cross-origin iframe for a heightened security boundary.
+ * For more details on Worker, see: https://developer.mozilla.org/en-US/docs/Web/API/Worker
+ *
+ * The iframe used for sandboxing must follow a specific contract. It:
+ *   1. Must send a ready message to the main-thread.
+ *   2. Must listen for a message from main-thread with the code to initialize a Worker with.
+ *   3. Must proxy all messages between the Worker and Parent, including errors.
  */
 class IframeWorker {
   // Public Worker API
@@ -33,9 +39,12 @@ class IframeWorker {
 
   // Internal variables.
   private iframe: HTMLIFrameElement;
-  private url: string | URL;
 
-  constructor(url: string | URL, iframeUrl: string) {
+  /**
+   * @param url The URL to initiate the worker from.
+   * @param iframeUrl The URL of the iframe to use as the worker proxy.
+   */
+  constructor(private url: string | URL, iframeUrl: string) {
     this.iframe = window.document.createElement('iframe');
     this.iframe.setAttribute('sandbox', 'allow-scripts');
     this.iframe.setAttribute('style', 'display:none');
@@ -80,16 +89,24 @@ class IframeWorker {
     });
   }
 
+  /**
+   * See https://developer.mozilla.org/en-US/docs/Web/API/Worker/postMessage
+   * @param message
+   * @param transferables
+   */
   postMessage(message: any, transferables?: Array<Transferable>) {
     const msg: MessageToIframe = { type: 'postMessage', message };
     this.iframe.contentWindow!.postMessage(msg, '*', transferables);
   }
 
+  /**
+   * See https://developer.mozilla.org/en-US/docs/Web/API/Worker/terminate
+   */
   terminate() {
     const msg: MessageToIframe = { type: 'terminate' };
     this.iframe.contentWindow!.postMessage(msg, '*');
     this.iframe.remove();
-  } 
+  }
 }
 
 export { IframeWorker };
diff --git a/src/main-thread/worker.ts b/src/main-thread/worker.ts
@@ -20,7 +20,7 @@ import { createHydrateableRootNode } from './serialize';
 import { readableHydrateableRootNode, readableMessageToWorker } from './debugging';
 import { NodeContext } from './nodes';
 import { TransferrableKeys } from '../transfer/TransferrableKeys';
-import { StorageLocation } from '../transfer/TransferrableStorage'; 
+import { StorageLocation } from '../transfer/TransferrableStorage';
 import { IframeWorker } from './iframe-worker';
 
 // TODO: Sanitizer storage init is likely broken, since the code currently
@@ -83,7 +83,7 @@ export class WorkerContext {
       //# sourceURL=${encodeURI(config.authorURL)}`;
     if (!config.sandbox) {
       this[TransferrableKeys.worker] = new Worker(URL.createObjectURL(new Blob([code])));
-    } else if (IS_AMP){
+    } else if (IS_AMP) {
       this[TransferrableKeys.worker] = new IframeWorker(URL.createObjectURL(new Blob([code])), config.sandbox.iframeUrl);
     }
     if (WORKER_DOM_DEBUG) {