remote/parent

Enables you to load modules, and privileged parts of your add-on in general, into child processes.

Usage

In multiprocess Firefox:

• the browser UI runs in one process, sometimes called the chrome process or the parent process
• web content runs in one or more other processes, sometimes called content processes or remote processes or child processes.

By default, add-ons run in the chrome process and can't directly access web content. In the SDK, content scripts run in the child process, and, of course, can access web content. But content scripts don't have many more capabilities than untrusted web content.

The sdk/remote/parent module enables you to load SDK modules into the child process to give them direct access to content frames. These SDK modules have higher privileges than content scripts, and have their own module loader so they can load other SDK modules.

Its primary purpose is to help build APIs. If you just need to access a web page, use sdk/page-mod to load a content script instead.

Terms

Process

Every application has at least one process running, the main process that displays the UI. Multiprocess applications can have other remote processes where untrusted content like webpages are loaded. Each process can contain many frames.

Frame

Every DOM page loaded as a part of the application is loaded in a content frame. This includes the content of every tab in an application like Firefox and also some other UI elements. Each frame loads in a process but sometimes the application may choose to switch from loading a tab in one process to another. In this case the frame for that tab changes.

Loading modules into the child process

To load a module into the child process, use remoteRequire():

const { remoteRequire } = require("sdk/remote/parent");
remoteRequire("./my-module.js", module);

Inter-process communication

A module loaded into a different process cannot directly communicate or share state with the module that loaded it. Instead, the two sides communicate using port objects like those used for communication with content scripts.

The sdk/remote/parent module provides port objects for the parent's end of the conversation, and the sdk/remote/child module provides port objects for the child's end.

// remote.js
const { process } = require("sdk/remote/child");
process.port.emit("message-from-remote", "hello from remote");
process.port.on("message-from-main", function(process, message) {
  console.log("Main says: " + message);
});

// main.js
const { processes, remoteRequire } = require("sdk/remote/parent");
remoteRequire("./remote.js", module);
processes.port.emit("message-from-main", "hello from main");
processes.port.on("message-from-remote", function(process, message) {
  console.log("Remote says: " + message);
});

Child process privileges

A module loaded into a child process can't do everything that the same module loaded into the parent process can. Multiprocess Firefox restricts the things that code running in child processes is allowed to do. For example, when the child process is sandboxed, modules won't be able to access the file system.

We don't yet have a full list of all the modules that a module in the child process can't load, but the sorts of things listed in Limitations of Frame Scripts broadly apply.

Examples

Property retrieval

This first example shows fetching a simple property from every existing and future process. remote.js runs in all child processes.

// remote.js
const { process } = require("sdk/remote/child");
const { processID } = require("sdk/system/runtime");
process.port.on("fetchID", () => {
  process.port.emit("ID", processID);
});

// main.js
const { processes, remoteRequire } = require("sdk/remote/parent");
// Load "remote.js" into every current and future process
remoteRequire("./remote.js", module);
// For every current and future process
processes.forEvery(process => {
  // Ask for the process ID
  process.port.emit("fetchID");
  // First argument is always the process, then the message payload
  process.port.once("ID", (process, id) => {
    console.log("child process is remote:" + process.isRemote);
    console.log("child process ID:" + id);
  });
});

Content frame manipulation

This demonstrates telling every current frame to link to a specific anchor element:

// remote.js
const { frames } = require("sdk/remote/child");
// Listeners receive the frame the event was for as the first argument
frames.port.on("changeLocation", (frame, ref) => {
  frame.content.location += "#" + ref;
});

// main.js
const { frames, remoteRequire } = require("sdk/remote/parent");
remoteRequire("./remote.js", module);
frames.port.emit("changeLocation", "foo");

Tab information

This shows sending a message when a tab loads; this is similar to how the sdk/tabs module currently works.

// remote.js
const { frames } = require("sdk/remote/child");
frames.addEventListener("pageshow", function() {
  // `this` is bound to the frame the event came from
  let frame = this;
  frame.port.emit("pageshow");
}, true);

// main.js
const { frames, remoteRequire } = require("sdk/remote/parent");
remoteRequire("./remote.js", module);
// The first argument is the frame the message came from
frames.port.on("pageshow", (frame) => {
  console.log(frame.frameElement.currentURI.host + ": pageshow");
});

Globals

Functions

remoteRequire(id, module = null)

Loads a module in any existing and future child processes. The module loads asynchronously but you can start sending messages to the module immediately.

You can use an absolute path to the module or a relative path. If you use a relative path, you must use the module parameter.

const { remoteRequire } = require("sdk/remote/parent");
remoteRequire("./my-module.js", module);

Note that even single-process applications have a process that contains content frames. For consistency and to make writing multiprocess compatible code easier, remoteRequire() will also create a new module loader and load modules in the main process.

Parameters

id : String
The module to load. To use a relative path you must pass the module parameter.

module : Object
The module to resolve the relative module ID against. To resolve relative to the loading module, pass module here.

Properties

processes

A Processes object.

frames

A Frames object.

Processes

The Processes object lets you interact with the processes currently running. You can use it as a simple list of all running processes:

const { processes } = require("sdk/remote/parent");
for (var p of processes) {
  console.log(p.isRemote);
}

Each element in this list is a Process. There will always be at least one process in this list, the main process. A multiprocess application will usually have at least one more process. Listen to attach and detach events to hear as processes are started and stopped:

const { processes } = require("sdk/remote/parent");
processes.on("attach", function(process) {
  console.log("new process is remote: " + process.isRemote);
});

Methods

forEvery(callback)

Calls the callback for every existing process and any new processes created in the future. This is a shortcut for enumerating existing processes and then listening for attach events.

Properties

port

An event emitter that sends messages to and receives messages from all processes.

Events

attach

Event emitted when a new process is started. The event handler is called with a Process representing the new process.

detach

Event emitted when a process disconnects from the application. It may have been closed normally or it may have crashed. The event handler is called with the Process that detached.

Frames

A list of the content frames across all processes. Each element in this list is a Frame. Listen to attach and detach events to hear as frames are created and destroyed.

const { frames } = require("sdk/remote/parent");
frames.on("attach", function(frame) {
  console.log("frame is attached: " + frame.frameElement);
});

Methods

forEvery(callback)

Calls the callback for every existing frame and any new frames created in the future. This is a shortcut for enumerating existing frames and then listening for attach events.

Properties

port

An event emitter that sends messages to and receives messages from all frames.

Events

attach

Event emitted when a new frame is created. The event handler is called with a Frame representing the new frame.

detach

Event emitted when a frame is removed. For example, the user might have closed a content tab. The event handler is called with the Frame that detached.

Process

A Process provides a way to communicate with code running in one of the application's processes.

Properties

port

An event emitter that can be used to send and receive events to and from code running in the process.

isRemote

A boolean property that indicates whether the attached process is remote from the main process.

Events

detach

Event emitted when this process disconnects from the application. It may have been closed normally or it may have crashed.

Frame

A Frame provides a way to pass frame specific messages to code in other processes. The frame this relates to may be in any of the application's processes.

Properties

port

An event emitter that can be used to send and receive frame specific events to and from code running in any process.

frameElement

The DOM element that displays this frame in the main process. For example, this may be a XUL <browser> element.

isTab

A boolean property indicating if this frame displays in one of the application's main browser tabs.

Events

detach

Event emitted when this frame is detached: for example, because the user closed its corresponding tab.