Limit and fix communication between frames

[esanzgar]

The client relies on an inter-frame communication between the host
frame, where the client was initially loaded, and a number of iframe
children. For the communication to work, every frame needs to be able to
discover the iframe that acts as a server by sending a
frame.postMessage. Currently, the sidebar iframe is the server.

The following frames must establish communication with the server
sidebar iframe:

• host frame (where the client was initially loaded)
• notebook iframe
• additional annotatable iframe(s) (each have an enable-annotation
  attribute) where the guest instance is injected.

This layout represents the current arrangement of frames:

host frame (client)
  |-> sidebar iframe (server)
  |-> notebook iframe (client)
  |-> annotatable iframe/s (client)

There are two problems with the current discoverability algorithm:

1. It relies on window.frames to list all the other frames. Because
   sidebar and notebook iframes are now wrapped on a shadow DOM they
   are not listed on window.frames.

2. It is very generic: the algorithm starts from the topmost frame in
   the hierarchy (window.top) and send messages to all the frame
   children recursively. If there are several clients initialised on
   individual frames, this algorithm causes all the host frames to
   be connected to all the sidebar iframes.

To solve both problems, I investigated swapping the server from the
sidebar to the host frame. All iframe children are able to find the
host frame (window.parent). In addition, this approach would have
the advantage that the server will be initialised first and ready to
listen for message before any of the iframe children is initialised.
This layout describes the intended arrangement:

host frame (server)
  |-> sidebar iframe (client)
  |-> notebook iframe (client)
  |-> annotatable iframe/s (client)

While this would have been a clean solution, I found that the server is
coupled to the store functionality in the sidebar. Decoupling both would
take some efforts.

Instead, in this PR I am suggesting a pragmatic approach based on (1)
saving a reference to the sidebar iframe on a global window variable
in the host frame and (2) the current parent-children frame
arrangement. While not as clean as the first approach, it would resolve
both problems:

1. No dependent on window.frames: when the host frame successfully
   establishes a communication with the sidebar iframe, it saves the
   reference to the sidebar iframe on a global reference.

2. Targeted discoverability: identify the sender of the initial
   postMessage message and direct it to the right frame:

   • if the sender is the sidebar iframe (server frame), the
     postMessage is sent only to the host frame using
     window.parent.
   • if the sender is the notebook or an annotatable iframe(s), we
     try send the postMessage to the sibling sidebar iframe, if a
     reference is known, otherwise we retry later.

[robertknight]

The approach implemented here relies on the child frame of the host frame being able to read properties on the Window global of the parent frame. This is possible if the host-frame is same origin but that is not true for the notebook or for guest frames in general. I mentioned a way that you can simulate this different-originness by using the sandbox attribute on an iframe.

I'm not aware of a way that a frame (eg. the host) can directly send a child frame a reference to another child so that they can directly communicate via postMessage. If you can find such a mechanism, let me know! A mechanism that I do know of which should work, is for a parent frame which has a reference to two other frames (eg. host having a reference to a child guest and the sidebar), to create a MessageChannel and send the two ends ("ports") of that channel to the respective child frames via the transfer argument to window.postMessage. The frames can then communicate directly with one another via the ports.

[robertknight]

Properties added to Window objects are not accessible from different-origin iframes, because the JavaScript worlds are completely separated and all communication has to be done via message ports. To simulate this locally in a development server where all the iframes are from the same origin, you can apply the sandbox attribute to the iframe without the allow-same-origin token. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe. A sandboxed iframe without this token behaves as if it is from a different origin.

[robertknight]

In my testing this code path is never invoked for the notebook app because the notebook never invokes the discovery process by calling Discovery#connect.

[robertknight]

Hi @esanzgar - I think we can close this PR now, since we've determined that we'll need to take a different approach to setting up inter-frame communication?

[esanzgar]

I will proposed an intermediate step to partially remediate the current situation elsewhere. Then, I will come out with a plan to readdress the current communication issues between the frames.