Platform API

RDP Inspector (RDPi) is intended to intercept Remote Debugging Protocol (RDP) and show all data sent and received. Implementation of this extension is based on platform API that allows observing set of events and get precise data sent through the wire. Let's see how these API are designed.

Terminology

RDP communication is based on simple packet exchange and this docs is using the following terminology to describe the logic.

• Client - This object represents a client for the RDP server. This client provides the means to communicate with the server and exchange the packets required by the protocol in a traditional JavaScript API.
• Server - The debuggee (or the back-end) the client is connected to.
• Connection - Pairing of the client and server. There can be more connections to the server at the same time.
• Packet - RDP communication message unit. The packet is the entity sent or received and responsible for carrying an optional payload.

Platform Support

API for RDP monitoring has been introduced in Firefox 38 (see also bug 1126274).

Goals:

• Get list of existing connections
• Track creation of new connections
• Observe connection close
• Intercept all sent/received data for specific connection
• Access full packet data

There are following events supported by the platform and fulfilling the goals.

Global events, mostly used to track new connections.

• toolbox-created - Emitted by global gDevTools object when a new Toolbox is opened. The event allows accessing the client and consequently the protocol object that fires other events related to packet exchange. Can be used to track connections created by the Toolbox.
• connect- Emitted by DebuggerClient object (not on the instance) when a new connection (instance) is about to be connected. This event can be used to track all created connections (created by Toolbox, WebIDE, or any other RDP client).

Client events emitted by DebuggerClient. This object is the client for the remote debugging protocol server.

• connected - Emitted when a connection with the server has been established (a greeting packet from the server received). The traits object, as given in the root actor's greeting packet is available.
• closed - Emitted when the underlying protocol stream is closed.

Transport events emitted by a transport object. This object handles data transfers between the debugger client and server. There are various implementations of this object depending on the specific connection (in-process, remote, etc.), but internal details are transparent to the event consumer.

• send - Emitted when a new packet is about to send. Packet object with full data is available. The packet is not transferred to the server at this moment yet.
• onPacket - Emitted when we have received a complete packet from the server. Packet object with full data is available.
• onBulkPacket - Emitted when we have switched to bulk packet receiving mode (binary data). Packet object contains additional API for binary transfer support.
• startBulkSend - Emitted when the bulk (binary) process has started.
• onClosed - Emitted when the underlying stream has been closed. A reason argument is available.

Example Scenario

Here is an example scenario describing how RDPi is utilizing the platform API.

• When a new Toolbox is opened by the user, RDPi handles toolbox-created event:

const { gDevTools } =
  Cu.import("resource:///modules/devtools/gDevTools.jsm", {});
gDevTools.on("toolbox-created", toolbox => { ... });

• RDPi access the transport object as follows:

toolbox.target.makeRemote();
let client = this.toolbox.target.client;
let transport = client._transport;

• RDPi adds listeners for packet exchange and connection close:

transport.on("send", this.send);
transport.on("onPacket", this.onPacket);
transport.on("onClosed", this.onClosed);

• RDPi console window has been closed, all registered listeners must be removed.