fix(devframe): cancel pending relay handshakes when panels close

A panel could close before receiving its port while the relay kept retrying. A later grant then registered an unused peer indefinitely when heartbeat was disabled.

Send cancellation through the window handshake and validate its source and identity before closing the relay connection. Cover late page scripts, delayed grants, and cancellation isolation.

Author: SaKaNa-Y

docs/content/8.references/3.events.md

@@ -136,4 +136,4 @@ Pushed over each panel's [in-page channel](/guide/in-page-channel) port; the pai
 | Name | Posted by | Carries |
 |---|---|---|
 | `devframe:remote-assets-error` | the remote-assets fallback page, to `window.parent` | The failed package/version/reason, so an embedding hub UI provider can replace the 502 page. |
-| `devframe:in-page-channel` | both [in-page channel](/guide/in-page-channel) endpoints, across window boundaries | The versioned handshake envelope (panel hello, page-script port grant). |
+| `devframe:in-page-channel` | both [in-page channel](/guide/in-page-channel) endpoints, across window boundaries | The versioned handshake envelope (panel hello, page-script port grant, panel cancellation). |

packages/devframe/src/in-page-channel/panel.ts

@@ -201,29 +201,33 @@ export function connectPanelChannel<P extends InPageChannelProtocol>(
       warnOnce(`in-page channel "${name}": transport lost (${reason}) and the panel has no handshake targets, so it stays disconnected`)
   }
 
+  function postHandshake(kind: 'hello' | 'cancel'): void {
+    const message = {
+      channel: IN_PAGE_CHANNEL_TAG,
+      v: IN_PAGE_CHANNEL_VERSION,
+      kind,
+      name,
+      panelId,
+      instanceId: options.instanceId,
+    }
+    for (const target of targets) {
+      for (const origin of allowedOrigins) {
+        try {
+          target.postMessage(message, origin)
+        }
+        catch {
+          // An unreachable target must not block the remaining targets.
+        }
+      }
+    }
+  }
+
   function startHelloLoop(): void {
     if (helloTimer || !canHandshake || status !== 'connecting')
       return
     let delay = options.helloIntervalMs ?? DEFAULT_HELLO_INTERVAL_MS
     const tick = (): void => {
-      const hello = {
-        channel: IN_PAGE_CHANNEL_TAG,
-        v: IN_PAGE_CHANNEL_VERSION,
-        kind: 'hello' as const,
-        name,
-        panelId,
-        instanceId: options.instanceId,
-      }
-      for (const target of targets) {
-        for (const origin of allowedOrigins) {
-          try {
-            target.postMessage(hello, origin)
-          }
-          catch {
-            // Unreachable target/origin pair; the loop keeps retrying.
-          }
-        }
-      }
+      postHandshake('hello')
       delay = Math.min(delay * 1.5, HELLO_INTERVAL_CAP_MS)
       helloTimer = setTimeout(tick, delay)
     }
@@ -302,6 +306,9 @@ export function connectPanelChannel<P extends InPageChannelProtocol>(
       setStatus('closed')
       disposeAgentTools()
       stopTimers()
+      // Pending relays have no port on which to receive the graceful bye yet.
+      if (canHandshake)
+        postHandshake('cancel')
       win?.removeEventListener('message', onWindowMessage)
       attached?.dispose({ bye: true, reason: 'the panel closed the channel' })
       attached = undefined

packages/devframe/src/in-page-channel/protocol.ts

@@ -18,12 +18,13 @@ export const IN_PAGE_CHANNEL_VERSION = 2
 /**
  * The handshake envelope. A panel posts a `hello` ("grant me a port for
  * channel `name`"); the page script answers with a `grant`, the dedicated
- * `MessagePort` transferred alongside.
+ * `MessagePort` transferred alongside. A closing panel posts `cancel` so
+ * relays can release pending handshakes before a port has been granted.
  */
 export interface InPageChannelHandshakeMessage {
   channel: typeof IN_PAGE_CHANNEL_TAG
   v: number
-  kind: 'hello' | 'grant'
+  kind: 'hello' | 'grant' | 'cancel'
   /** User channel name (e.g. `devframes:plugin:a11y`). */
   name: string
   /** The asking panel's id (grants echo it, so a panel matches its own hello). */
@@ -52,7 +53,7 @@ export function isHandshakeMessage(data: unknown): data is InPageChannelHandshak
   return message.channel === IN_PAGE_CHANNEL_TAG
     && typeof message.name === 'string'
     && typeof message.panelId === 'string'
-    && (message.kind === 'hello' || message.kind === 'grant')
+    && (message.kind === 'hello' || message.kind === 'grant' || message.kind === 'cancel')
 }
 
 const INSTANCE_STORAGE_KEY = 'devframe:in-page-channel:instance'

packages/devframe/src/in-page-channel/relay.test.ts

@@ -308,3 +308,80 @@ it('leaves direct in-page grants available to their own panel', async () => {
   await expect(direct.call('highlight', '#direct')).resolves.toBe('/:#direct')
   expect(s.pageScript.panels).toHaveLength(2)
 })
+
+it('stops pending handshakes when the panel closes before the page script loads', async () => {
+  const s = session('/')
+  s.pageScript.close()
+  const post = vi.spyOn(s.page.win, 'postMessage')
+  await vi.waitFor(() => expect(post).toHaveBeenCalled())
+  expect(s.panel.status).toBe('connecting')
+  s.panel.close()
+  await new Promise(resolve => setTimeout(resolve, 0))
+  post.mockClear()
+
+  const pageScript = createPageScriptChannel<Protocol>({
+    name: 'devframes:relay-test',
+    window: s.page.window,
+    heartbeat: false,
+    functions: { highlight: { handler: s.highlight } },
+  })
+  cleanup.push(() => pageScript.close())
+  await new Promise(resolve => setTimeout(resolve, 1200))
+  expect(s.panel.status).toBe('closed')
+  expect(pageScript.panels).toHaveLength(0)
+  expect(post).not.toHaveBeenCalled()
+})
+
+it.each(['page', 'transport'] as const)('cleans a pending %s grant when only the panel closes', async (boundary) => {
+  const s = session('/')
+  let release!: () => void
+  if (boundary === 'page') {
+    const post = s.page.win.postMessage
+    s.page.win.postMessage = (data, origin, ports) => {
+      if ((data as { kind: string }).kind === 'grant')
+        release = () => post(data, origin, ports)
+      else
+        post(data, origin, ports)
+    }
+  }
+  else {
+    const send = s.transport.page.postMessage
+    s.transport.page.postMessage = (data) => {
+      if ((data as { kind: string }).kind === 'grant')
+        release = () => send(data)
+      else
+        send(data)
+    }
+  }
+  await vi.waitFor(() => expect(release).toBeTypeOf('function'))
+  expect(s.panel.status).toBe('connecting')
+  s.panel.close()
+  await new Promise(resolve => setTimeout(resolve, 0))
+  release()
+  await vi.waitFor(() => expect(s.pageScript.panels).toHaveLength(0))
+})
+
+it('only cancels a handshake from its owning window and matching identity', async () => {
+  const s = session('/')
+  s.pageScript.close()
+  const send = vi.spyOn(s.transport.panel, 'postMessage')
+  await vi.waitFor(() => expect(send).toHaveBeenCalled())
+  const open = send.mock.calls[0]![0] as { id: string, handshake: object }
+  const cancel = { ...open.handshake, kind: 'cancel' }
+  const sibling = fakeWindow()
+  sibling.win.parent = s.viewer.window
+  const dispatch = (data: object, source = s.panelWindow.window, origin = 'https://app.test') => {
+    s.viewer.win.dispatch({ data, source, origin })
+  }
+  dispatch(cancel, sibling.window)
+  dispatch(cancel, s.panelWindow.window, 'https://other.test')
+  dispatch({ ...cancel, v: 99 })
+  dispatch({ ...cancel, name: 'another-channel' })
+  dispatch({ ...cancel, panelId: 'another-panel' })
+  dispatch({ ...cancel, instanceId: 'another-instance' })
+  await new Promise(resolve => setTimeout(resolve, 0))
+  expect(send.mock.calls.some(([data]) => (data as { kind: string }).kind === 'close')).toBe(false)
+
+  s.panel.close()
+  await vi.waitFor(() => expect(send).toHaveBeenCalledWith(expect.objectContaining({ id: open.id, kind: 'close' })))
+})

packages/devframe/src/in-page-channel/relay.ts

@@ -33,7 +33,7 @@ interface RelayConnection {
   retryTimer?: ReturnType<typeof setTimeout>
 }
 
-function validHandshake(data: unknown, kind: 'hello' | 'grant'): data is InPageChannelHandshakeMessage {
+function validHandshake(data: unknown, kind: InPageChannelHandshakeMessage['kind']): data is InPageChannelHandshakeMessage {
   return isHandshakeMessage(data)
     && data.v === IN_PAGE_CHANNEL_VERSION
     && data.kind === kind
@@ -137,8 +137,8 @@ export function createInPageChannelRelay(options: InPageChannelRelayOptions): ()
       && (!hello.instanceId || grant.instanceId === hello.instanceId)
   }
 
-  function onPanelHello(event: MessageEvent): void {
-    if (!validHandshake(event.data, 'hello') || !event.source
+  function onPanelHandshake(event: MessageEvent): void {
+    if ((!validHandshake(event.data, 'hello') && !validHandshake(event.data, 'cancel')) || !event.source
       || !isDescendant(event.source as Window, win)) {
       return
     }
@@ -147,12 +147,18 @@ export function createInPageChannelRelay(options: InPageChannelRelayOptions): ()
     for (const [key, connection] of connections) {
       if (connection.source === event.source && connection.hello.panelId === hello.panelId
         && connection.hello.name === hello.name && connection.hello.instanceId === hello.instanceId) {
+        if (hello.kind === 'cancel') {
+          close(key)
+          return
+        }
         if (connection.port)
           return
         id = key
         break
       }
     }
+    if (hello.kind === 'cancel')
+      return
     id ??= nanoid()
     connections.set(id, { hello, source: event.source as Window })
     send({ id, kind: 'open', handshake: hello })
@@ -187,7 +193,7 @@ export function createInPageChannelRelay(options: InPageChannelRelayOptions): ()
     if (disposed || event.origin !== origin)
       return
     if (options.role === 'panel')
-      onPanelHello(event)
+      onPanelHandshake(event)
     else
       onPageGrant(event)
   }