Confirm
496
edits
Changes
First draft.
The [[Remote_Debugging_Protocol|Mozilla debugging protocol]] is specified in terms of packets exchanged between a client and server, where each packet is either a JSON text or a block of bytes (a "bulk data" packet). The protocol does not specify any particular mechanism for carrying packets from one party to the other. Implementations may choose whatever transport they like, as long as packets arrive reliably, undamaged, and in order.
This page describes the <b>Mozilla Remote Debugging Protocol Stream Transport</b>, a transport layer suitable for carrying Mozilla debugging protocol packets over a reliable, ordered byte stream, like a TCP/IP stream or a pipe. Debugger user interfaces can use it to exchange packets with debuggees in other processes (say, for debugging Firefox chrome code), or on other machines (say, for debugging Firefox OS apps running on a phone or tablet).
(The Stream Transport is not the only transport used by Mozilla. For example, when using Firefox's built-in script debugger, the client and server are in the same process, so for efficiency they use a transport that simply exchanges the JavaScript objects corresponding to the JSON texts specified by the protocol, and avoid serializing packets altogether.)
== Packets ==
Once the underlying byte stream is established, transport participants may immediately begin sending packets, using the forms described here. The transport requires no initial handshake or setup, and no shutdown exchange: the first bytes on the stream in each direction are those of the first packet, if any; the last bytes on the stream in each direction are the final bytes of the last packet sent, if any.
The transport defines two types of packets: JSON and bulk data.
=== JSON Packets ===
A JSON packet has the form:
<i>length</i>:<i>JSON</i>
where <i>length</i> is a series of decimal ASCII digits, <i>JSON</i> is a well-formed JSON text (as defined in [http://www.ietf.org/rfc/rfc4627.txt RFC 4627]) encoded in UTF-8, and <i>length</i>, interpreted as a number, is the length of <i>JSON</i> in bytes.
=== Bulk Data Packets ===
A bulk data packet has the form:
bulk <i>actor</i> <i>length</i>:<i>data</i>
where:
<ul>
<li><code>bulk</code> is the four ASCII characters 'b', 'u', 'l', and 'k';
<li>there is exactly one space character (the single byte 0x20) between <code>bulk</code> and <i>actor</i>, and between <i>actor</i> and <i>length</i>;
<li><i>actor</i> is a sequence of Unicode characters, encoded in UTF-8, containing no spaces or colons;
<li><i>length</i> is a sequence of decimal ASCII digits; and
<li><i>data</i> is a sequence of bytes whose length is <i>length</i> interpreted as a number.
</ul>
The <i>actor</i> field is the name of the actor sending or receiving the packet. (Actors are server-side entities, so if the packet was sent by the client, <i>actor</i> names the recipient; and if the packet was sent by the server, <i>actor</i> names the sender.) The protocol imposes the same syntactic restrictions on actor names that we require here.
Which actor names are valid at any given point in an exchange is established by the remote debugging protocol.
The content of a bulk data packet is exactly the sequence of bytes appearing as <i>data</i>. <i>Data</i> is not UTF-8 text.
== Stream Requirements ==
The Stream Transport requires the underlying stream to have the following properties:
<ul>
<li>It must be <b>transparent</b>: each transmitted byte is carried to the recipient without modification. Bytes whose values are ASCII control characters or fall outside the range of ASCII altogether must be carried unchanged; line terminators are left alone.
<li>It must be <b>reliable</b>: every transmitted byte makes it to the recipient, or else the connection is dropped altogether. Errors introduced by hardware, say, must be detected and corrected, or at least reported (and the connection dropped). The Stream Transport includes no checksums of its own; those are the stream's responsibility. (So, for example, a plain serial line is not suitable for use as an underlying stream.)
<li>It must be <b>ordered</b>: bytes are received in the same order they are transmitted, and bytes are not duplicated. (UDP packets, for example, may be duplicated or arrive out of order.)
</ul>
TCP/IP streams and USB streams meet these requirements.
<!-- Local Variables: -->
<!-- eval: (visual-line-mode) -->
<!-- End: -->
This page describes the <b>Mozilla Remote Debugging Protocol Stream Transport</b>, a transport layer suitable for carrying Mozilla debugging protocol packets over a reliable, ordered byte stream, like a TCP/IP stream or a pipe. Debugger user interfaces can use it to exchange packets with debuggees in other processes (say, for debugging Firefox chrome code), or on other machines (say, for debugging Firefox OS apps running on a phone or tablet).
(The Stream Transport is not the only transport used by Mozilla. For example, when using Firefox's built-in script debugger, the client and server are in the same process, so for efficiency they use a transport that simply exchanges the JavaScript objects corresponding to the JSON texts specified by the protocol, and avoid serializing packets altogether.)
== Packets ==
Once the underlying byte stream is established, transport participants may immediately begin sending packets, using the forms described here. The transport requires no initial handshake or setup, and no shutdown exchange: the first bytes on the stream in each direction are those of the first packet, if any; the last bytes on the stream in each direction are the final bytes of the last packet sent, if any.
The transport defines two types of packets: JSON and bulk data.
=== JSON Packets ===
A JSON packet has the form:
<i>length</i>:<i>JSON</i>
where <i>length</i> is a series of decimal ASCII digits, <i>JSON</i> is a well-formed JSON text (as defined in [http://www.ietf.org/rfc/rfc4627.txt RFC 4627]) encoded in UTF-8, and <i>length</i>, interpreted as a number, is the length of <i>JSON</i> in bytes.
=== Bulk Data Packets ===
A bulk data packet has the form:
bulk <i>actor</i> <i>length</i>:<i>data</i>
where:
<ul>
<li><code>bulk</code> is the four ASCII characters 'b', 'u', 'l', and 'k';
<li>there is exactly one space character (the single byte 0x20) between <code>bulk</code> and <i>actor</i>, and between <i>actor</i> and <i>length</i>;
<li><i>actor</i> is a sequence of Unicode characters, encoded in UTF-8, containing no spaces or colons;
<li><i>length</i> is a sequence of decimal ASCII digits; and
<li><i>data</i> is a sequence of bytes whose length is <i>length</i> interpreted as a number.
</ul>
The <i>actor</i> field is the name of the actor sending or receiving the packet. (Actors are server-side entities, so if the packet was sent by the client, <i>actor</i> names the recipient; and if the packet was sent by the server, <i>actor</i> names the sender.) The protocol imposes the same syntactic restrictions on actor names that we require here.
Which actor names are valid at any given point in an exchange is established by the remote debugging protocol.
The content of a bulk data packet is exactly the sequence of bytes appearing as <i>data</i>. <i>Data</i> is not UTF-8 text.
== Stream Requirements ==
The Stream Transport requires the underlying stream to have the following properties:
<ul>
<li>It must be <b>transparent</b>: each transmitted byte is carried to the recipient without modification. Bytes whose values are ASCII control characters or fall outside the range of ASCII altogether must be carried unchanged; line terminators are left alone.
<li>It must be <b>reliable</b>: every transmitted byte makes it to the recipient, or else the connection is dropped altogether. Errors introduced by hardware, say, must be detected and corrected, or at least reported (and the connection dropped). The Stream Transport includes no checksums of its own; those are the stream's responsibility. (So, for example, a plain serial line is not suitable for use as an underlying stream.)
<li>It must be <b>ordered</b>: bytes are received in the same order they are transmitted, and bytes are not duplicated. (UDP packets, for example, may be duplicated or arrive out of order.)
</ul>
TCP/IP streams and USB streams meet these requirements.
<!-- Local Variables: -->
<!-- eval: (visual-line-mode) -->
<!-- End: -->
