Use MessagePort `close` event if available

Use MessagePort's built-in `close` event to detect when the sending frame goes
away, instead of the sending window's `unload` event, which is being deprecated.

Currently only beta/dev versions of Chrome support the MessagePort `close`
event.

Fixes https://github.com/hypothesis/client/issues/5621

src/shared/messaging/port-rpc.ts

@@ -50,6 +50,20 @@ type ResponseMessage = {
 
 type Message = RequestMessage | ResponseMessage;
 
+function makeRequestMessage(
+  method: string,
+  args: unknown[] = [],
+  sequence = -1,
+): RequestMessage {
+  return {
+    protocol: PROTOCOL,
+    version: VERSION,
+    arguments: args,
+    method,
+    sequence,
+  };
+}
+
 /**
  * Send a PortRPC method call.
  *
@@ -61,13 +75,7 @@ function sendCall(
   args: unknown[] = [],
   sequence = -1,
 ) {
-  port.postMessage({
-    protocol: PROTOCOL,
-    version: VERSION,
-    arguments: args,
-    method,
-    sequence,
-  } satisfies RequestMessage);
+  port.postMessage(makeRequestMessage(method, args, sequence));
 }
 
 /**
@@ -187,13 +195,27 @@ export class PortRPC<OnMethod extends string, CallMethod extends string>
   constructor({
     userAgent = navigator.userAgent,
     currentWindow = window,
-  }: { userAgent?: string; currentWindow?: Window } = {}) {
+    forceUnloadListener = false,
+  }: {
+    userAgent?: string;
+    currentWindow?: Window;
+
+    // Test seam. Force the use of a Window "unload" listener even if the
+    // browser supports "close" events for MessagePort.
+    forceUnloadListener?: boolean;
+  } = {}) {
     this._port = null;
     this._methods = new Map();
     this._sequence = 1;
     this._callbacks = new Map();
 
     this._listeners = new ListenerCollection();
+
+    // In browsers that emit a "close" event when the other end of a MessagePort
+    // goes away, we can listen for that directly. In other browsers, we have to
+    // send the "close" event through the message channel when the window
+    // containing the sending port is unloaded.
+    if (!('onclose' in MessagePort.prototype) || forceUnloadListener) {
       this._listeners.add(currentWindow, 'unload', () => {
         if (this._port) {
           // Send "close" notification directly. This works in Chrome, Firefox and
@@ -215,6 +237,7 @@ export class PortRPC<OnMethod extends string, CallMethod extends string>
           }
         }
       });
+    }
 
     this._pendingCalls = [];
 
@@ -249,6 +272,19 @@ export class PortRPC<OnMethod extends string, CallMethod extends string>
   connect(port: MessagePort) {
     this._port = port;
     this._listeners.add(port, 'message', event => this._handle(event));
+
+    // For browsers that support a `close` event for MessagePort, we use that
+    // to identify when the other end disconnects. This is translated into a
+    // message event that is similar to what we receive in older browsers
+    // which use a Window unload handler instead.
+    this._listeners.add(port, 'close', () => {
+      port.dispatchEvent(
+        new MessageEvent('message', {
+          data: makeRequestMessage('close'),
+        }),
+      );
+    });
+
     port.start();
     sendCall(port, 'connect');
 

src/shared/messaging/test/port-rpc-test.js

@@ -243,7 +243,7 @@ describe('PortRPC', () => {
 
   it('should send "close" event when window is unloaded', async () => {
     const { port1, port2 } = new MessageChannel();
-    const sender = new PortRPC();
+    const sender = new PortRPC({ forceUnloadListener: true });
     const receiver = new PortRPC();
     const closeHandler = sinon.stub();
 
@@ -260,6 +260,26 @@ describe('PortRPC', () => {
     assert.calledWith(closeHandler);
   });
 
+  it('should send "close" event when MessagePort emits "close" event', async () => {
+    const { port1, port2 } = new MessageChannel();
+    const sender = new PortRPC();
+    const receiver = new PortRPC();
+    const closeHandler = sinon.stub();
+
+    receiver.on('close', closeHandler);
+    receiver.connect(port2);
+    sender.connect(port1);
+    await waitForMessageDelivery();
+
+    assert.notCalled(closeHandler);
+    const closed = waitForMessage(port2, 'close');
+    port2.dispatchEvent(new Event('close'));
+    await closed;
+
+    assert.calledOnce(closeHandler);
+    assert.calledWith(closeHandler);
+  });
+
   it('should only invoke "close" handler once', async () => {
     const { port1, port2 } = new MessageChannel();
     const sender = new PortRPC();
@@ -322,6 +342,7 @@ describe('PortRPC', () => {
       const sender = new PortRPC({
         userAgent: safariUserAgent,
         currentWindow: childFrame.contentWindow,
+        forceUnloadListener: true,
       });
       const receiver = new PortRPC();
       const closeHandler = sinon.stub();