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 to observe set of events and get all 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 following terminology to describe the logic.

• Client - This is usually the front-end consumed by the user (e.g. the Toolbox in Firefox desktop browser).
• Backend - The debuggee the client is connected to (can also be called the server).
• Connection - Ensuring paring of the client and backend. It's responsible for data exchange. There can be more clients to one backend at the same time.
• Packet - RDP communication is based on data messages called packets. 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).

API goals:

• Get list of existing connections
• Track creation of new connections
• Observe connection close
• Intercept all sent/received packets for specific connection
• Access full packet data (including the payload)

There are couple of event group.

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 represents a client for the remote debugging protocol server. This client provides the means to communicate with the server and exchange the packets required by the protocol in a traditional JavaScript API.

• connected - Emitted when 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.).

• 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.

• New Toolbox has been opened by the user. RDPi is handles toolbox-created event
• RDPi access the transport object as follows:

this.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.