feat: add WebFrameMain detached property (#43473)

* feat: add WebFrameMain detached property

fix: throw instead of returning null senderFrame

test: detached frames

fix: ensure IPCs of pending deletion RFHs are dispatched

fix: lookup WFM by FTN ID to dispatch IPCs

feat: add frame.isDestroyed()

return null

fix: return undefined

docs: add null to all frame properties

refactor: option c, return null and emit warning

refactor: add routingId & processId to navigation events

test: null frame property

docs: clarify warning message

better wording

clarify null frame

fix: browserwindow spec

* maybe fix 🤷

* fix: use updated util #43722

* docs: add notice for frame change of behavior

* docs: clarify why frame properties may be null

* lint

* wip

* fix: content::FrameTreeNodeId lookup and converter

* refactor: avoid holey array deoptimization

---------

Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>
This commit is contained in:
Sam Maddock 2024-10-11 18:33:53 -04:00 committed by GitHub
parent 527efc01a4
commit 8b3d70a2a3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
20 changed files with 410 additions and 126 deletions

View file

@ -268,7 +268,8 @@ Returns:
* `event` Event
* `details` Object
* `deviceList` [HIDDevice[]](structures/hid-device.md)
* `frame` [WebFrameMain](web-frame-main.md)
* `frame` [WebFrameMain](web-frame-main.md) | null - The frame initiating this event.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `callback` Function
* `deviceId` string | null (optional)
@ -332,7 +333,8 @@ Returns:
* `event` Event
* `details` Object
* `device` [HIDDevice](structures/hid-device.md)
* `frame` [WebFrameMain](web-frame-main.md)
* `frame` [WebFrameMain](web-frame-main.md) | null - The frame initiating this event.
May be `null` if accessed after the frame has either navigated or been destroyed.
Emitted after `navigator.hid.requestDevice` has been called and
`select-hid-device` has fired if a new device becomes available before
@ -347,7 +349,8 @@ Returns:
* `event` Event
* `details` Object
* `device` [HIDDevice](structures/hid-device.md)
* `frame` [WebFrameMain](web-frame-main.md)
* `frame` [WebFrameMain](web-frame-main.md) | null - The frame initiating this event.
May be `null` if accessed after the frame has either navigated or been destroyed.
Emitted after `navigator.hid.requestDevice` has been called and
`select-hid-device` has fired if a device has been removed before the callback
@ -473,7 +476,8 @@ Returns:
* `event` Event
* `details` Object
* `port` [SerialPort](structures/serial-port.md)
* `frame` [WebFrameMain](web-frame-main.md)
* `frame` [WebFrameMain](web-frame-main.md) | null - The frame initiating this event.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `origin` string - The origin that the device has been revoked from.
Emitted after `SerialPort.forget()` has been called. This event can be used
@ -517,7 +521,8 @@ Returns:
* `event` Event
* `details` Object
* `deviceList` [USBDevice[]](structures/usb-device.md)
* `frame` [WebFrameMain](web-frame-main.md)
* `frame` [WebFrameMain](web-frame-main.md) | null - The frame initiating this event.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `callback` Function
* `deviceId` string (optional)
@ -957,7 +962,8 @@ session.fromPartition('some-partition').setPermissionCheckHandler((webContents,
* `handler` Function | null
* `request` Object
* `frame` [WebFrameMain](web-frame-main.md) - Frame that is requesting access to media.
* `frame` [WebFrameMain](web-frame-main.md) | null - Frame that is requesting access to media.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `securityOrigin` String - Origin of the page making the request.
* `videoRequested` Boolean - true if the web content requested a video stream.
* `audioRequested` Boolean - true if the web content requested an audio stream.
@ -1158,7 +1164,8 @@ app.whenReady().then(() => {
pin displayed on the device.
* `providePin`
This prompt is requesting that a pin be provided for the device.
* `frame` [WebFrameMain](web-frame-main.md)
* `frame` [WebFrameMain](web-frame-main.md) | null - The frame initiating this handler.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `pin` string (optional) - The pin value to verify if `pairingKind` is `confirmPin`.
* `callback` Function
* `response` Object

View file

@ -4,7 +4,7 @@
* `frameId` Integer - The ID of the renderer frame that sent this message
* `returnValue` any - Set this to the value to be returned in a synchronous message
* `sender` [WebContents](../web-contents.md) - Returns the `webContents` that sent the message
* `senderFrame` [WebFrameMain](../web-frame-main.md) _Readonly_ - The frame that sent this message
* `senderFrame` [WebFrameMain](../web-frame-main.md) | null _Readonly_ - The frame that sent this message. May be `null` if accessed after the frame has either navigated or been destroyed.
* `ports` [MessagePortMain](../message-port-main.md)[] - A list of MessagePorts that were transferred with this message
* `reply` Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to "reply" to the sent message in order to guarantee the reply will go to the correct process and frame.
* `channel` string

View file

@ -3,4 +3,4 @@
* `processId` Integer - The internal ID of the renderer process that sent this message
* `frameId` Integer - The ID of the renderer frame that sent this message
* `sender` [WebContents](../web-contents.md) - Returns the `webContents` that sent the message
* `senderFrame` [WebFrameMain](../web-frame-main.md) _Readonly_ - The frame that sent this message
* `senderFrame` [WebFrameMain](../web-frame-main.md) | null _Readonly_ - The frame that sent this message. May be `null` if accessed after the frame has either navigated or been destroyed.

View file

@ -242,8 +242,9 @@ Returns:
* `isSameDocument` boolean - This event does not fire for same document navigations using window.history api and reference fragment navigations.
This property is always set to `false` for this event.
* `isMainFrame` boolean - True if the navigation is taking place in a main frame.
* `frame` WebFrameMain - The frame to be navigated.
* `initiator` WebFrameMain (optional) - The frame which initiated the
* `frame` WebFrameMain | null - The frame to be navigated.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `initiator` WebFrameMain | null (optional) - The frame which initiated the
navigation, which can be a parent frame (e.g. via `window.open` with a
frame's name), or null if the navigation was not initiated by a frame. This
can also be null if the initiating frame was deleted before the event was
@ -275,8 +276,9 @@ Returns:
* `isSameDocument` boolean - This event does not fire for same document navigations using window.history api and reference fragment navigations.
This property is always set to `false` for this event.
* `isMainFrame` boolean - True if the navigation is taking place in a main frame.
* `frame` WebFrameMain - The frame to be navigated.
* `initiator` WebFrameMain (optional) - The frame which initiated the
* `frame` WebFrameMain | null - The frame to be navigated.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `initiator` WebFrameMain | null (optional) - The frame which initiated the
navigation, which can be a parent frame (e.g. via `window.open` with a
frame's name), or null if the navigation was not initiated by a frame. This
can also be null if the initiating frame was deleted before the event was
@ -306,8 +308,9 @@ Returns:
document. Examples of same document navigations are reference fragment
navigations, pushState/replaceState, and same page history navigation.
* `isMainFrame` boolean - True if the navigation is taking place in a main frame.
* `frame` WebFrameMain - The frame to be navigated.
* `initiator` WebFrameMain (optional) - The frame which initiated the
* `frame` WebFrameMain | null - The frame to be navigated.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `initiator` WebFrameMain | null (optional) - The frame which initiated the
navigation, which can be a parent frame (e.g. via `window.open` with a
frame's name), or null if the navigation was not initiated by a frame. This
can also be null if the initiating frame was deleted before the event was
@ -330,8 +333,9 @@ Returns:
document. Examples of same document navigations are reference fragment
navigations, pushState/replaceState, and same page history navigation.
* `isMainFrame` boolean - True if the navigation is taking place in a main frame.
* `frame` WebFrameMain - The frame to be navigated.
* `initiator` WebFrameMain (optional) - The frame which initiated the
* `frame` WebFrameMain | null - The frame to be navigated.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `initiator` WebFrameMain | null (optional) - The frame which initiated the
navigation, which can be a parent frame (e.g. via `window.open` with a
frame's name), or null if the navigation was not initiated by a frame. This
can also be null if the initiating frame was deleted before the event was
@ -361,8 +365,9 @@ Returns:
document. Examples of same document navigations are reference fragment
navigations, pushState/replaceState, and same page history navigation.
* `isMainFrame` boolean - True if the navigation is taking place in a main frame.
* `frame` WebFrameMain - The frame to be navigated.
* `initiator` WebFrameMain (optional) - The frame which initiated the
* `frame` WebFrameMain | null - The frame to be navigated.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `initiator` WebFrameMain | null (optional) - The frame which initiated the
navigation, which can be a parent frame (e.g. via `window.open` with a
frame's name), or null if the navigation was not initiated by a frame. This
can also be null if the initiating frame was deleted before the event was
@ -743,7 +748,8 @@ Returns:
* `params` Object
* `x` Integer - x coordinate.
* `y` Integer - y coordinate.
* `frame` WebFrameMain - Frame from which the context menu was invoked.
* `frame` WebFrameMain | null - Frame from which the context menu was invoked.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `linkURL` string - URL of the link that encloses the node the context menu
was invoked on.
* `linkText` string - Text associated with the link. May be an empty
@ -1010,7 +1016,8 @@ Returns:
* `event` Event
* `details` Object
* `frame` WebFrameMain
* `frame` WebFrameMain | null - The created frame.
May be `null` if accessed after the frame has either navigated or been destroyed.
Emitted when the [mainFrame](web-contents.md#contentsmainframe-readonly), an `<iframe>`, or a nested `<iframe>` is loaded within the page.

View file

@ -97,6 +97,10 @@ this limitation.
Returns `boolean` - Whether the reload was initiated successfully. Only results in `false` when the frame has no history.
#### `frame.isDestroyed()`
Returns `boolean` - Whether the frame is destroyed.
#### `frame.send(channel, ...args)`
* `channel` string
@ -231,6 +235,13 @@ A `string` representing the [visibility state](https://developer.mozilla.org/en-
See also how the [Page Visibility API](browser-window.md#page-visibility) is affected by other Electron APIs.
#### `frame.detached` _Readonly_
A `Boolean` representing whether the frame is detached from the frame tree. If a frame is accessed
while the corresponding page is running any [unload][] listeners, it may become detached as the
newly navigated page replaced it in the frame tree.
[SCA]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
[`postMessage`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
[`MessagePortMain`]: message-port-main.md
[unload]: https://developer.mozilla.org/en-US/docs/Web/API/Window/unload_event

View file

@ -51,7 +51,8 @@ The following methods are available on instances of `WebRequest`:
* `method` string
* `webContentsId` Integer (optional)
* `webContents` WebContents (optional)
* `frame` WebFrameMain (optional)
* `frame` WebFrameMain | null (optional) - Requesting frame.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
* `referrer` string
* `timestamp` Double
@ -94,7 +95,8 @@ Some examples of valid `urls`:
* `method` string
* `webContentsId` Integer (optional)
* `webContents` WebContents (optional)
* `frame` WebFrameMain (optional)
* `frame` WebFrameMain | null (optional) - Requesting frame.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
* `referrer` string
* `timestamp` Double
@ -122,7 +124,8 @@ The `callback` has to be called with a `response` object.
* `method` string
* `webContentsId` Integer (optional)
* `webContents` WebContents (optional)
* `frame` WebFrameMain (optional)
* `frame` WebFrameMain | null (optional) - Requesting frame.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
* `referrer` string
* `timestamp` Double
@ -142,7 +145,8 @@ response are visible by the time this listener is fired.
* `method` string
* `webContentsId` Integer (optional)
* `webContents` WebContents (optional)
* `frame` WebFrameMain (optional)
* `frame` WebFrameMain | null (optional) - Requesting frame.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
* `referrer` string
* `timestamp` Double
@ -173,7 +177,8 @@ The `callback` has to be called with a `response` object.
* `method` string
* `webContentsId` Integer (optional)
* `webContents` WebContents (optional)
* `frame` WebFrameMain (optional)
* `frame` WebFrameMain | null (optional) - Requesting frame.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
* `referrer` string
* `timestamp` Double
@ -197,7 +202,8 @@ and response headers are available.
* `method` string
* `webContentsId` Integer (optional)
* `webContents` WebContents (optional)
* `frame` WebFrameMain (optional)
* `frame` WebFrameMain | null (optional) - Requesting frame.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
* `referrer` string
* `timestamp` Double
@ -222,7 +228,8 @@ redirect is about to occur.
* `method` string
* `webContentsId` Integer (optional)
* `webContents` WebContents (optional)
* `frame` WebFrameMain (optional)
* `frame` WebFrameMain | null (optional) - Requesting frame.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
* `referrer` string
* `timestamp` Double
@ -245,7 +252,8 @@ completed.
* `method` string
* `webContentsId` Integer (optional)
* `webContents` WebContents (optional)
* `frame` WebFrameMain (optional)
* `frame` WebFrameMain | null (optional) - Requesting frame.
May be `null` if accessed after the frame has either navigated or been destroyed.
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
* `referrer` string
* `timestamp` Double

View file

@ -14,6 +14,34 @@ This document uses the following convention to categorize breaking changes:
## Planned Breaking API Changes (33.0)
### Behavior Changed: frame properties may retrieve detached WebFrameMain instances or none at all
APIs which provide access to a `WebFrameMain` instance may return an instance
with `frame.detached` set to `true`, or possibly return `null`.
When a frame performs a cross-origin navigation, it enters into a detached state
in which it's no longer attached to the page. In this state, it may be running
[unload](https://developer.mozilla.org/en-US/docs/Web/API/Window/unload_event)
handlers prior to being deleted. In the event of an IPC sent during this state,
`frame.detached` will be set to `true` with the frame being destroyed shortly
thereafter.
When receiving an event, it's important to access WebFrameMain properties
immediately upon being received. Otherwise, it's not guaranteed to point to the
same webpage as when received. To avoid misaligned expectations, Electron will
return `null` in the case of late access where the webpage has changed.
```ts
ipcMain.on('unload-event', (event) => {
event.senderFrame; // ✅ accessed immediately
});
ipcMain.on('unload-event', async (event) => {
await crossOriginNavigationPromise;
event.senderFrame; // ❌ returns `null` due to late access
});
```
### Behavior Changed: custom protocol URL handling on Windows
Due to changes made in Chromium to support [Non-Special Scheme URLs](http://bit.ly/url-non-special), custom protocol URLs that use Windows file paths will no longer work correctly with the deprecated `protocol.registerFileProtocol` and the `baseURLForDataURL` property on `BrowserWindow.loadURL`, `WebContents.loadURL`, and `<webview>.loadURL`. `protocol.handle` will also not work with these types of URLs but this is not a change since it has always worked that way.