feat: add WebContents.ipc

[nornagon]

Description of Change

This adds a new API, WebContents.ipc, which works like ipcMain but is
scoped to only IPC messages sent from a single WebContents.

This allows a developer to more ergonomically communicate with a specific
WebContents, replacing either "source checks" or "channel checks" with a
"declarative" source/channel check.

e.g. without:

const w = new BrowserWindow
w.loadURL('app://window')
w.webContents.on('ipc-message', (event, channel, ...args) => {
  if (channel === 'test') {
    // ...
  }
})

// Or, for `invoke`:
ipcMain.handle('some-message', (event, ...args) => {
  if (event.sender === w.webContents) {
    // ...
  }
})

refactored to use the new WebContents.ipc API introduced in this PR:

const w = new BrowserWindow
w.loadURL('app://window')
w.webContents.ipc.on('test', (event, ...args) => {
  // ...
})

w.webContents.ipc.handle('some-message', (event, ...args) => {
  // event.sender is guaranteed to be === w.webContents
  // ...
})

I believe this is clearer and less error-prone than the existing methods for
accomplishing the same result.

Also adds an analogous API to WebFrameMain.ipc.

Checklist

• PR description included and stakeholders cc'd
• npm test passes
• tests are changed or added
• relevant documentation is changed or added
• PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes: Added new WebContents.ipc and WebFrameMain.ipc APIs.

[erickzhao]

In the API's current form, I find it a bit confusing for users without historical perspective that the win.webContents.ipc object would be separate from the existing win.webContents.send API.

My initial thought was to alias the IPC command to win.webContents.ipc.send, but then the object description gains a new dimension of complexity (e.g. can't be reduced to a one-line "an IpcMain instance").

[nornagon]

Yeah, it seems reasonable to expect webContents.ipc.send to exist. We could clone the existing IpcMain docs over to IpcWebContents or something.

[miniak]

We should deprecated ipc-message and ipc-message-sync

[nornagon]

@miniak I don't see any particular reason to deprecate them, they're minimal overhead and deprecating/removing them would break apps for no particular reason.

I'd be fine adding a note in the docs about the new ipc object though.

[miniak]

btw I tried doing this before in #16420 and it got rejected :)

[miniak]

@miniak I don't see any particular reason to deprecate them, they're minimal overhead and deprecating/removing them would break apps for no particular reason.

I'd be fine adding a note in the docs about the new ipc object though.

ok, makes sense

[nornagon]

@miniak yeah, i remember that! thanks for the link. i now think i was wrong 😅

[miniak]

any plans to backport, at least to 20-x-y?

[nornagon]

I don't think this is worth backporting. It's easily polyfillable.

[miniak]

In the API's current form, I find it a bit confusing for users without historical perspective that the win.webContents.ipc object would be separate from the existing win.webContents.send API.

My initial thought was to alias the IPC command to win.webContents.ipc.send, but then the object description gains a new dimension of complexity (e.g. can't be reduced to a one-line "an IpcMain instance").

win.webContents.send is just a shortcut for win.webContents.mainFrame.send :)

[miniak]

shouldn't the ipc property on webContents be also read-only? it is on the webFrameMain

[nornagon]

I feel a little awkward about adding the ipc.send family of methods, because it adds to the already somewhat bewildering set of IPC methods available.

• webContents.send
• webContents.sendToFrame
• webContents.postMessage
• webFrameMain.send
• webFrameMain.postMessage

and this would add:

• webContents.ipc.send
• webContents.ipc.postMessage
• webContents.ipc.sendToFrame (maybe we want to elide this one as it's covered by webFrameMain.send now?)
• webFrameMain.ipc.send
• webFrameMain.ipc.postMessage

all of which would be duplicating functionality.

Does this seem worth it @erickzhao? I do agree that webContents.ipc.send makes sense given webContents.ipc.on('message') exists. But I'm not sure if it's so much better that it outweighs the awkwardness of a bunch of duplicated methods. WDYT?

[miniak]

@nornagon I don't think it's worth adding those methods. Moreover ipcMain also does not have send / postMessage

[miniak]

It's easily polyfillable.

are you sure? basic on, etc. could be, but not handle IMO

[nornagon]

@miniak yeah i guess it's not super trivial to do handle. I started writing out a polyfill, and it involved patching WebContents.prototype._init, so probably a bit overcomplicated :)

that said, Electron 20 will be going stable in about 2 weeks, and I don't feel super great about that short of a runway for this feature.

given this is just ergonomic and doesn't add any new functionality, I'm erring on the side of not backporting.

[miniak]

API LGTM

[codebytere]

API LGTM

i'm in agreement that #34959 (comment) is a case where drawbacks outweigh benefits, and that we shouldn't backport here.

[release-clerk]

Release Notes Persisted

Added new WebContents.ipc and WebFrameMain.ipc APIs.

[miniak]

/trop run backport-to 21-x-y

[trop]

The backport process for this PR has been manually initiated - sending your PR to 21-x-y!

[trop]

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