Reminder todo for me: mainFrame.ipc.on should receive the detached frame messages. This can be looked up via FrameTreeNode ID when dispatching the emitters.

I don't love introducing APIs that could throw under "normal usage". I think I made this point before but ensuring we attach the correct pinned WebFrameMain information should be doable even after the navigation. We just need to stash the information.

Personally I think the much better end-state is to align on things like our new permission handler API which will just expose an origin, then we suggest folks validate the origin instead of the frame and move on with our lives 🤔

I don't love introducing APIs that could throw under "normal usage". I think I made this point before but ensuring we attach the correct pinned WebFrameMain information should be doable even after the navigation. We just need to stash the information.

We currently stash the process and routing IDs associated with the RenderFrameHost. This effectively pins all frame property access.

The current design throws if accessed asynchronously. Previously it returned null (undocumented).

ipcMain.on('unload-event', async (event) => {
  await crossOriginNavigationPromise;
  event.senderFrame; // ❌ likely throws due to initial RFH destroyed
});

An alternate design could be to create an "empty" WebFrameMain which is initialized in a destroyed state.

ipcMain.on('unload-event', async (event) => {
  await crossOriginNavigationPromise;
  event.senderFrame; // ✅ object exists
  event.senderFrame.isDestroyed(); // ✅ true because pinned frame info no longer points to valid RFH
  event.senderFrame.url; // ❌ throws as RFH has been destroyed/uninitialized
});

The only thing I don't like about this design is that it's somewhat misleading since the frame could have swapped. Throwing outright will encourage developers to always access synchronously. Throwing also follows the behavior seen in property access such as frame.url of a destroyed frame.

Personally I think the much better end-state is to align on things like our new permission handler API which will just expose an origin, then we suggest folks validate the origin instead of the frame and move on with our lives 🤔

I agree on the security side of things, we should prefer exposing the origin directly. That's the approach I intend to follow with the permissions changes once I get to proposing the permissions-v2 branch.

This PR is addressing the edge case with unloaded frames which applies to IPCs, permissions, and anywhere else we expose frames as property.

The frame property is pinned to a specific RenderFrameHost. When accessed immediately upon emitting an event, the frame is expected to exist. If the property is accessed too late, we can't return the expected frame if it has navigated or been destroyed.

Here are some options we can go with for addressing late access.

Option A: Throw upon access

ipcMain.on('unload-event', async (event) => {
  await crossOriginNavigationPromise;
  event.senderFrame; // ❌ throws due to RFH destroyed
});

• Matches existing behavior of throwing when accessing properties of destroyed frames (e.g. frame.url).
• Doesn't require any breaking changes to types.

Option B: Return destroyed/empty WebFrameMain

ipcMain.on('unload-event', async (event) => {
  await crossOriginNavigationPromise;
  event.senderFrame; // ✅ object exists
  event.senderFrame.isDestroyed(); // ✅ true because pinned frame info no longer points to valid RFH
  event.senderFrame.url; // ❌ throws as RFH has been destroyed/uninitialized
});

• Doesn't require any breaking changes to types.

✅ Option C: Return null

ipcMain.on('unload-event', async (event) => {
  await crossOriginNavigationPromise;
  event.senderFrame; // ✅ returns `null` without throwing
  event.senderFrame.url; // ❌ throws due to indexing null
});

• This is the current, undocumented behavior.
• If we document this, it will be a breaking change to the types.

Option D: Eagerly initialize frame property

ipcMain.on('unload-event', async (event) => {
  await crossOriginNavigationPromise;
  event.senderFrame; // ✅ object exists
  event.senderFrame.url; // URL points to navigated page
});

Frame properties are lazily evaluated which led us to this problem. We can have the WebFrameMain instance always be created with events instead of being done lazily. This has the drawback of allocations for each unique WebFrameMain instance emitted.

The frame will also continue to follow navigation which we may want to guide folks away from in cases such as IPCs.

With any of the lazily evaluated designs, we can detect when late access occurs and log a warning/error.

Warning: Frame property was accessed after it navigated or was destroyed. Frames should be accessed immediately upon receiving an event.

API LGTM

some color to my approval:

1. we've thought about this a long time. this is addressing a security issue, and I think we need to bias towards landing something here. we've gone through a lot of designs and this one seems pretty minimal in terms of what it adds and what it breaks.
2. as for checking origin vs checking frame, i agree we should recommend checking origin vs checking frame as it's simpler, and 99% of the time people are just checking the url of the frame anyway :)

Is it worth adding a short note to the breaking changes doc to mention that a bunch of APIs can now have a null value for the frame property?

@itsananderson I've added a notice about the change of behavior which mentions the possibility of the frame being null 09e9fba

Is there any existing behavior where this could break handling event.senderFrame, where a developer is assuming it won’t return null? I think the answer is no, as we’re handling an edge case here, just asking in case any other existing documentation should be updated with the updated types.

@VerteDinde the existing behavior is also to return null, albeit undocumented, so it's only new in the case of late-access after navigations.

Release Notes Persisted

• Added WebFrameMain.detached for frames in an unloading state.
• Added WebFrameMain.isDestroyed() to determine if a frame has been destroyed.
• Fixed webFrameMain.fromId(processId, frameId) returning a WebFrameMain instance which doesn't match the given parameters when the frame is unloading.

I have automatically backported this PR to "33-x-y", please check out #44209