electron · nornagon · Mar 12, 2020 · Oct 25, 2019 · Feb 25, 2020 · Feb 25, 2020
diff --git a/docs/api/ipc-renderer.md b/docs/api/ipc-renderer.md
@@ -143,6 +143,35 @@ Sends a message to a window with `webContentsId` via `channel`.
 Like `ipcRenderer.send` but the event will be sent to the `<webview>` element in
 the host page instead of the main process.
 
+### `ipcRenderer.postMessage(channel, message, [options])`
+
+* `channel` String
+* `message` any
+* `options` MessagePort[] (optional)
+
+Send a message to the main process, optionally transferring ownership of zero
+or more [`MessagePort`][] objects.
+
+The transferred `MessagePort` objects will be available in the main process as
+[`MessagePortMain`](message-port-main.md) objects by accessing the `ports`
+property of the emitted event.
+
+For example:
+```js
+// Renderer process
+const { port1, port2 } = new MessageChannel
+ipcRenderer.postMessage('port', {message: "hello"}, [port1])
+
+// Main process
+ipcMain.on('port', (e, msg) => {
+  const [port] = e.ports
+  // ...
+})
+```
+
+For more information on using `MessagePort` and `MessageChannel`, see the [MDN
+documentation](https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel).
+
 ## Event object
 
 The documentation for the `event` object passed to the `callback` can be found
@@ -151,3 +180,4 @@ in the [`ipc-renderer-event`](structures/ipc-renderer-event.md) structure docs.
 [event-emitter]: https://nodejs.org/api/events.html#events_class_eventemitter
 [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
+[`MessagePort`]: https://developer.mozilla.org/en-US/docs/Web/API/MessagePort
diff --git a/docs/api/message-channel.md b/docs/api/message-channel.md
@@ -0,0 +1,26 @@
+# MessageChannelMain
+
+`MessageChannelMain` is the main-process-side equivalent of the DOM
+[`MessageChannel`][] object. Its singular function is to create a pair of
+connected [`MessagePortMain`](message-port-main.md) objects.
+
+## Class: MessageChannelMain
+
+Example:
+```js
+const { port1, port2 } = new MessageChannelMain
+w.webContents.postMessage('port', null, [port2])
+port1.postMessage({ some: 'message' })
+```
+
+### Instance Properties
+
+#### `channel.port1`
+
+A [`MessagePortMain`](message-port-main.md) property.
+
+#### `channel.port2`
+
+A [`MessagePortMain`](message-port-main.md) property.
+
+[`MessageChannel`]: https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel
diff --git a/docs/api/message-port-main.md b/docs/api/message-port-main.md
@@ -0,0 +1,45 @@
+# MessagePortMain
+
+`MessagePortMain` is the main-process-side equivalent of the DOM
+[`MessagePort`][] object. It behaves similarly to the DOM version, with the
+exception that it uses the Node.js `EventEmitter` event system, instead of the
+DOM `EventTarget` system. This means you should use `port.on('message', ...)`
+to listen for events, instead of `port.onmessage = ...` or
+`port.addEventListener('message', ...)`
+
+`MessagePortMain` is an [EventEmitter][event-emitter].
+
+## Class: MessagePortMain
+
+### Instance Methods
+
+#### `port.postMessage(message, [transfer])`
+
+* `message` any
+* `transfer` MessagePortMain[] (optional)
+
+Sends a message from the port, and optionally, transfers ownership of objects
+to other browsing contexts.
+
+#### `port.start()`
+
+Starts the sending of messages queued on the port. Messages will be queued
+until this method is called.
+
+#### `port.close()`
+
+Disconnects the port, so it is no longer active.
+
+### Instance Events
+
+#### Event: 'message'
+
+Returns:
+
+* `event` Object
+  * `data` any
+  * `ports` MessagePortMain[]
+
+Emitted when a MessagePortMain object receives a message.
+
+[`MessagePort`]: https://developer.mozilla.org/en-US/docs/Web/API/MessagePort
diff --git a/docs/api/structures/ipc-main-event.md b/docs/api/structures/ipc-main-event.md
@@ -3,6 +3,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 - Returns the `webContents` that sent the message
+* `ports` MessagePortMain[] - 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
   * `...args` any[]
diff --git a/docs/api/structures/ipc-renderer-event.md b/docs/api/structures/ipc-renderer-event.md
@@ -2,5 +2,6 @@
 
 * `sender` IpcRenderer - The `IpcRenderer` instance that emitted the event originally
 * `senderId` Integer - The `webContents.id` that sent the message, you can call `event.sender.sendTo(event.senderId, ...)` to reply to the message, see [ipcRenderer.sendTo][ipc-renderer-sendto] for more information. This only applies to messages sent from a different renderer. Messages sent directly from the main process set `event.senderId` to `0`.
+* `ports` MessagePort[] - A list of MessagePorts that were transferred with this message
 
 [ipc-renderer-sendto]: #ipcrenderersendtowindowid-channel--arg1-arg2-
diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md
@@ -1593,6 +1593,32 @@ ipcMain.on('ping', (event) => {
 })
 ```
 
+#### `contents.postMessage(channel, message, [options])`
+
+* `channel` String
+* `message` any
+* `options` MessagePortMain[] (optional)
+
+Send a message to the renderer process, optionally transferring ownership of
+zero or more [`MessagePortMain`][] objects.
+
+The transferred `MessagePortMain` objects will be available in the renderer
+process by accessing the `ports` property of the emitted event. When they
+arrive in the renderer, they will be native DOM `MessagePort` objects.
+
+For example:
+```js
+// Main process
+const { port1, port2 } = new MessageChannel
+webContents.postMessage('port', {message: 'hello'}, [port1])
+
+// Renderer process
+ipcRenderer.on('port', (e, msg) => {
+  const [port] = e.ports
+  // ...
+})
+```
+
 #### `contents.enableDeviceEmulation(parameters)`
 
 * `parameters` Object

diff --git a/filenames.auto.gni b/filenames.auto.gni
@@ -32,6 +32,8 @@ auto_filenames = {
     "docs/api/locales.md",
     "docs/api/menu-item.md",
     "docs/api/menu.md",
+    "docs/api/message-channel.md",
+    "docs/api/message-port-main.md",
     "docs/api/modernization",
     "docs/api/native-image.md",
     "docs/api/native-theme.md",
@@ -224,6 +226,7 @@ auto_filenames = {
     "lib/browser/api/menu-item.js",
     "lib/browser/api/menu-utils.js",
     "lib/browser/api/menu.js",
+    "lib/browser/api/message-channel.ts",
     "lib/browser/api/module-list.ts",
     "lib/browser/api/native-theme.ts",
     "lib/browser/api/net-log.js",
@@ -260,6 +263,7 @@ auto_filenames = {
     "lib/browser/ipc-main-impl.ts",
     "lib/browser/ipc-main-internal-utils.ts",
     "lib/browser/ipc-main-internal.ts",
+    "lib/browser/message-port-main.ts",
     "lib/browser/navigation-controller.js",
     "lib/browser/remote/objects-registry.ts",
     "lib/browser/remote/server.ts",

diff --git a/filenames.gni b/filenames.gni
@@ -121,6 +121,8 @@ filenames = {
     "shell/browser/api/gpu_info_enumerator.h",
     "shell/browser/api/gpuinfo_manager.cc",
     "shell/browser/api/gpuinfo_manager.h",
+    "shell/browser/api/message_port.cc",
+    "shell/browser/api/message_port.h",
     "shell/browser/api/process_metric.cc",
     "shell/browser/api/process_metric.h",
     "shell/browser/api/save_page_handler.cc",
@@ -558,6 +560,8 @@ filenames = {
     "shell/common/skia_util.h",
     "shell/common/v8_value_converter.cc",
     "shell/common/v8_value_converter.h",
+    "shell/common/v8_value_serializer.cc",
+    "shell/common/v8_value_serializer.h",
     "shell/common/world_ids.h",
     "shell/renderer/api/context_bridge/render_frame_context_bridge_store.cc",
     "shell/renderer/api/context_bridge/render_frame_context_bridge_store.h",

diff --git a/lib/browser/api/message-channel.ts b/lib/browser/api/message-channel.ts
@@ -0,0 +1,12 @@
+import { MessagePortMain } from '@electron/internal/browser/message-port-main'
+const { createPair } = process.electronBinding('message_port')
+
+export default class MessageChannelMain {
+  port1: MessagePortMain;
+  port2: MessagePortMain;
+  constructor () {
+    const { port1, port2 } = createPair()
+    this.port1 = new MessagePortMain(port1)
+    this.port2 = new MessagePortMain(port2)
+  }
+}
diff --git a/lib/browser/api/module-keys.js b/lib/browser/api/module-keys.js
@@ -24,6 +24,7 @@ module.exports = [
   { name: 'nativeTheme' },
   { name: 'net' },
   { name: 'netLog' },
+  { name: 'MessageChannelMain' },
   { name: 'Notification' },
   { name: 'powerMonitor' },
   { name: 'powerSaveBlocker' },

diff --git a/lib/browser/api/module-list.ts b/lib/browser/api/module-list.ts
@@ -16,6 +16,7 @@ export const browserModuleList: ElectronInternal.ModuleEntry[] = [
   { name: 'inAppPurchase', loader: () => require('./in-app-purchase') },
   { name: 'Menu', loader: () => require('./menu') },
   { name: 'MenuItem', loader: () => require('./menu-item') },
+  { name: 'MessageChannelMain', loader: () => require('./message-channel') },
   { name: 'nativeTheme', loader: () => require('./native-theme') },
   { name: 'net', loader: () => require('./net') },
   { name: 'netLog', loader: () => require('./net-log') },

diff --git a/lib/browser/api/web-contents.js b/lib/browser/api/web-contents.js
@@ -11,6 +11,7 @@ const { internalWindowOpen } = require('@electron/internal/browser/guest-window-
 const NavigationController = require('@electron/internal/browser/navigation-controller')
 const { ipcMainInternal } = require('@electron/internal/browser/ipc-main-internal')
 const ipcMainUtils = require('@electron/internal/browser/ipc-main-internal-utils')
+const { MessagePortMain } = require('@electron/internal/browser/message-port-main')
 
 // session is not used here, the purpose is to make sure session is initalized
 // before the webContents module.
@@ -115,6 +116,13 @@ WebContents.prototype.send = function (channel, ...args) {
   return this._send(internal, sendToAll, channel, args)
 }
 
+WebContents.prototype.postMessage = function (...args) {
+  if (Array.isArray(args[2])) {
+    args[2] = args[2].map(o => o instanceof MessagePortMain ? o._internalPort : o)
+  }
+  this._postMessage(...args)
+}
+
 WebContents.prototype.sendToAll = function (channel, ...args) {
   if (typeof channel !== 'string') {
     throw new Error('Missing required channel argument')
@@ -472,6 +480,11 @@ WebContents.prototype._init = function () {
     }
   })
 
+  this.on('-ipc-ports', function (event, internal, channel, message, ports) {
+    event.ports = ports.map(p => new MessagePortMain(p))
+    ipcMain.emit(channel, event, message)
+  })
+
   // Handle context menu action request from pepper plugin.
   this.on('pepper-context-menu', function (event, params, callback) {
     // Access Menu via electron.Menu to prevent circular require.

diff --git a/lib/browser/message-port-main.ts b/lib/browser/message-port-main.ts
@@ -0,0 +1,25 @@
+import { EventEmitter } from 'events'
+
+export class MessagePortMain extends EventEmitter {
+  _internalPort: any
+  constructor (internalPort: any) {
+    super()
+    this._internalPort = internalPort
+    this._internalPort.emit = (channel: string, event: {ports: any[]}) => {
+      if (channel === 'message') { event = { ...event, ports: event.ports.map(p => new MessagePortMain(p)) } }
+      this.emit(channel, event)
+    }
+  }
+  start () {
+    return this._internalPort.start()
+  }
+  close () {
+    return this._internalPort.close()
+  }
+  postMessage (...args: any[]) {
+    if (Array.isArray(args[1])) {
+      args[1] = args[1].map((o: any) => o instanceof MessagePortMain ? o._internalPort : o)
+    }
+    return this._internalPort.postMessage(...args)
+  }
+}
diff --git a/lib/renderer/api/ipc-renderer.ts b/lib/renderer/api/ipc-renderer.ts
@@ -29,4 +29,8 @@ ipcRenderer.invoke = async function (channel, ...args) {
   return result
 }
 
+ipcRenderer.postMessage = function (channel: string, message: any, transferables: any) {
+  return ipc.postMessage(channel, message, transferables)
+}
+
 export default ipcRenderer
diff --git a/lib/renderer/init.ts b/lib/renderer/init.ts
@@ -45,9 +45,9 @@ v8Util.setHiddenValue(global, 'ipc', ipcEmitter)
 v8Util.setHiddenValue(global, 'ipc-internal', ipcInternalEmitter)
 
 v8Util.setHiddenValue(global, 'ipcNative', {
-  onMessage (internal: boolean, channel: string, args: any[], senderId: number) {
+  onMessage (internal: boolean, channel: string, ports: any[], args: any[], senderId: number) {
     const sender = internal ? ipcInternalEmitter : ipcEmitter
-    sender.emit(channel, { sender, senderId }, ...args)
+    sender.emit(channel, { sender, senderId, ports }, ...args)
   }
 })
 

diff --git a/lib/sandboxed_renderer/init.js b/lib/sandboxed_renderer/init.js
@@ -54,9 +54,9 @@ const loadedModules = new Map([
 // ElectronApiServiceImpl will look for the "ipcNative" hidden object when
 // invoking the 'onMessage' callback.
 v8Util.setHiddenValue(global, 'ipcNative', {
-  onMessage (internal, channel, args, senderId) {
+  onMessage (internal, channel, ports, args, senderId) {
     const sender = internal ? ipcRendererInternal : electron.ipcRenderer
-    sender.emit(channel, { sender, senderId }, ...args)
+    sender.emit(channel, { sender, senderId, ports }, ...args)
   }
 })
 

diff --git a/patches/chromium/.patches b/patches/chromium/.patches
@@ -73,6 +73,7 @@ expose_setuseragent_on_networkcontext.patch
 feat_add_set_theme_source_to_allow_apps_to.patch
 revert_cleanup_remove_menu_subtitles_sublabels.patch
 export_fetchapi_mojo_traits_to_fix_component_build.patch
+add_webmessageportconverter_entangleandinjectmessageportchannel.patch
 revert_remove_contentrendererclient_shouldfork.patch
 ignore_rc_check.patch
 remove_usage_of_incognito_apis_in_the_spellchecker.patch

diff --git a/patches/chromium/add_webmessageportconverter_entangleandinjectmessageportchannel.patch b/patches/chromium/add_webmessageportconverter_entangleandinjectmessageportchannel.patch
@@ -0,0 +1,51 @@
+From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
+From: Jeremy Apthorp <nornagon@nornagon.net>
+Date: Fri, 25 Oct 2019 11:23:03 -0700
+Subject: add WebMessagePortConverter::EntangleAndInjectMessagePortChannel
+
+This adds a method to the public Blink API that would otherwise require
+accessing Blink internals. Its inverse, which already exists, is used in
+Android WebView.
+
+diff --git a/third_party/blink/public/web/web_message_port_converter.h b/third_party/blink/public/web/web_message_port_converter.h
+index ad603aa7c557bfd4f571a541d70e2edf9ae757d9..d4b0bf8f5e8f3af9328b0099b65d9963414dfcc1 100644
+--- a/third_party/blink/public/web/web_message_port_converter.h
++++ b/third_party/blink/public/web/web_message_port_converter.h
+@@ -13,6 +13,7 @@ class Isolate;
+ template <class T>
+ class Local;
+ class Value;
++class Context;
+ }  // namespace v8
+
+ namespace blink {
+@@ -25,6 +26,9 @@ class WebMessagePortConverter {
+   // neutered, it will return nullopt.
+   BLINK_EXPORT static base::Optional<MessagePortChannel>
+   DisentangleAndExtractMessagePortChannel(v8::Isolate*, v8::Local<v8::Value>);
++
++  BLINK_EXPORT static v8::Local<v8::Value>
++  EntangleAndInjectMessagePortChannel(v8::Local<v8::Context>, MessagePortChannel);
+ };
+
+ }  // namespace blink
+diff --git a/third_party/blink/renderer/core/exported/web_message_port_converter.cc b/third_party/blink/renderer/core/exported/web_message_port_converter.cc
+index 333760d667f6b98b3e7674bf9082f999743dadfa..fc2f517de1951380482fbfa92c038041e15d9c3e 100644
+--- a/third_party/blink/renderer/core/exported/web_message_port_converter.cc
++++ b/third_party/blink/renderer/core/exported/web_message_port_converter.cc
+@@ -21,4 +21,15 @@ WebMessagePortConverter::DisentangleAndExtractMessagePortChannel(
+   return port->Disentangle();
+ }
+
++v8::Local<v8::Value>
++WebMessagePortConverter::EntangleAndInjectMessagePortChannel(
++    v8::Local<v8::Context> context,
++    MessagePortChannel port_channel) {
++  auto* execution_context = ToExecutionContext(context);
++  CHECK(execution_context);
++  auto* port = MakeGarbageCollected<MessagePort>(*execution_context);
++  port->Entangle(std::move(port_channel));
++  return ToV8(port, context->Global(), context->GetIsolate());
++}
++
+ }  // namespace blink