Remote Debugging Protocol: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(→‎Interrupting a Thread: Add "Exiting Threads" section.)
(bold)
 
(94 intermediate revisions by 9 users not shown)
Line 1: Line 1:
<i>(Note: this page is a draft design of work not yet completed. It is written in the present tense to be easily promoted to documentation when implemented, and also to simplify the grammar.)</i>
This page moved to the mozilla-central repository with [https://bugzilla.mozilla.org/show_bug.cgi?id=1354587 bug 1354587].


The Mozilla debugging protocol allows a debugger to connect to a browser, discover what sorts of things are present to debug or inspect, select JavaScript threads to watch, and observe and modify their execution. The protocol provides a unified view of JavaScript, DOM nodes, CSS rules, and the other technologies used in client-side web applications. The protocol is meant to be sufficiently general to be extended for use with other sorts of clients (profilers, say) and servers (mail readers; random XULrunner applications).
Read it now at '''https://docs.firefox-dev.tools/backend/protocol.html'''.


All communication between debugger (client) and browser (server) is in the form of JSON objects. This makes the protocol directly readable by humans, capable of graceful evolution, and easy to implement using stock libraries. In particular, it should be easy to create mock implementations for testing and experimentation.
Source code, at http://searchfox.org/mozilla-central/source/devtools/docs/backend/protocol.md
 
The protocol operates at the JavaScript level, not at the C++ or machine level, and assumes that the JavaScript implementation itself is healthy and responsive. The JavaScript program being executed may well have gone wrong, but the JavaScript implementation's internal state must not be corrupt. Bugs in the implementation may cause the debugger to fail; bugs in the interpreted program must not.
 
= Actors =
 
An "actor" is something on the server that receives and replies to JSON packets from the client. Every packet from the client specifies the actor to which it is directed, and every packet from the server indicates which actor sent it.
 
Each server has a root actor, with which the client first interacts. The root actor can explain what sort of thing the server represents (browser; mail reader; etc.), and enumerate things available to debug: tabs, chrome, and so on. Each of these, in turn, is an actor to which requests can be addressed.
 
For example, a debugger might connect to a browser, ask the root actor to list the browser's tabs, and present this list to the developer. If the developer chooses some tabs to debug, then the debugger sends "attach" requests to the actors representing those tabs, to begin debugging. Both artifacts of the program being debugged, like JavaScript objects and stack frames, and artifacts of the debugging machinery, like breakpoints and watchpoints, are actors to which packets can be addressed.
 
Each actor (other than the root) has a parent actor; closing communications with the parent closes communications with all its descendants. This establishes automatic limits on lifetimes for actor names, and allows the server to free associated storage, remove breakpoints, and so on. The root actor has no owner, and lives as long as the underlying connection to the client does. When the underlying connection is closed, all actor names are closed.
 
<i>(We are stealing the "actor" terminology from Mozilla's [[IPDL]], to mean, roughly, "things participating in the protocol". However, IPDL does much more with the idea than we do: it treats both client and server as collections of actors, and uses that detail to statically verify properties of the protocol. In contrast, the debugging protocol simply wants a consistent way to indicate the entities to which packets are directed.)</i>
 
= Packets =
 
The protocol is carried by a reliable, bi-directional byte stream; data sent in both directions consists of JSON objects, called packets. A packet is a top-level JSON object, not contained inside any other value.
 
Every packet sent from the client has the form:
 
  { "to": <i>actor</i>, "type": <i>type</i>, ... }
 
where <i>actor</i> is the actor to whom the packet is directed&mdash;actor names are always JSON integers&mdash;and <i>type</i> is a string specifying what sort of packet it is. Additional properties may be present, depending on <i>type</i>.
 
Every packet sent from the server has the form:
 
  { "from": <i>actor</i>, ... }
 
where <i>actor</i> is the name of the actor that sent it. Additional properties may be present, depending on the situation.
 
We expect that, as the protocol evolves, we will specify new properties that can appear in existing packets, and experimental implementations will do the same. Clients should be written to silently ignore properties they do not recognize.
 
= Requests and Replies =
 
In this protocol description, a "request" is a packet sent from the client which always elicits a single packet from the recipient, the "reply". These terms indicate a simple pattern of communication: at any given time, either the client or actor is permitted to send a packet, but never both.
 
The client's communication with each actor is treated separately: a client may send a request to one actor, and then send a request to a different actor before receiving a reply from the first.
 
Packets not described as "requests" or "replies" are part of some more complicated interaction, which should be spelled out in more detail.
 
= The Root Actor =
 
When the connection to the server is opened, the root actor opens the conversation with the following packet:
 
  { "from":0, "application-type":<i>app-type</i>, "traits":<i>traits</i>, ...}
 
The root actor's name is always zero. <i>app-type</i> is a JSON string indicating what sort of program the server represents. There may be more properties present, depending on <i>app-type</i>.
 
<i>traits</i> is a JSON object describing protocol variants this server supports that are not convenient for the client to detect otherwise. The property names present indicate what traits the server has; the properties' values depend on their names. This version of the protocol defines no traits, so <i>traits</i> must be a JSON object with no properties, {}.
 
For web browsers, the introductory packet should have the following form:
 
  { "from":0, "application-type":"browser", "traits":<i>traits</i> }
 
== Listing Top-Level Browsing Contexts ==
 
To get a list of the top-level browsing contexts present in a browser, a client should send a packet like the following to the root actor:
 
  { "to":0, "type":"list-contexts" }
 
The response should have the form:
 
  { "from":0, "contexts":[<i>context</i>...] }
 
The <tt>contexts</tt> property is a list with one element for each top-level browsing context present in the browser. Each <i>context</i> has the following form:
 
  { "actor":<i>actor</i>, "title":<i>title</i>, "url":<i>url</i> }
 
<i>actor</i> is the actor representing that top-level browsing context; <i>title</i> is the context's document's title, and <i>url</i> is the context's document's URL.
 
Clients should send "list-contexts" requests only to root actors that have identified themselves as browsers.
 
Actor names given in a list-contexts reply have the root actor as their parent. They remain valid at least until the next list-contexts request is received. If the client attaches to a context actor, its name is valid until the client detaches from the context and receives a "detached" packet from the context, or until the client sends a "release" packet to the context. See "Interacting with Thread-Like Actors" for details.
 
For example, upon connection to a web browser visiting two pages at example.com, the root actor's introductory packet might look like this:
 
  { "from":0, "application-type":"browser",
    "contexts": [ { "actor":1, "title":"Fruits",
                    "url":"http://www.example.com/fruits/" },
                  { "actor":2, "title":"Bats",
                    "url":"http://www.example.com/bats/" }]}
 
<i>(The point here is to give the debugger enough information to select which context it would like to debug without having to do too many round trips. Round trips are bad for UI responsiveness, but large packets are probably not a problem, so whatever would help to add, we should add.)</i>
 
= Interacting with Thread-Like Actors =
 
Actors representing independent threads of JavaScript execution, like browsing contexts and web workers, are collectively known as "threads". Interactions with actors representing threads follow a more complication communication pattern.
 
A thread is always in one of the following states:
 
* <b>Detached</b>: the thread is running freely, and not presently interacting with the debugger. Detached threads run, encounter errors, and exit without exchanging any sort of messages with the debugger. A debugger can attach to a thread, putting it in the "Running" state. Or, a detached thread may exit on its own, entering the "Exited" state.
 
* <b>Running</b>: the thread is running under the debugger's observation, executing JavaScript code or possibly blocked waiting for input. It will report exceptions, breakpoint hits, watchpoint hits, and other interesting events to the client, and enter the "paused" state. The debugger can also interrupt a running thread; this elicits a response and puts the thread in the "paused" state. A running thread may also exit, entering the "exited" state.
 
* <b>Paused</b>: the thread has reported a pause to the client and is awaiting further instructions. In this state, a thread can accept requests and send replies. If the client asks the thread to continue or step, it returns to the "running" state.
 
* <b>Exited</b>: the thread has ceased execution, and will disappear. The resources of the underlying thread may have been freed; this state really indicates that the actor's name is not yet available for reuse. When the actor receives a "release" packet, the name may be reused.
 
[[File:thread-states.png]]
 
These interactions are meant to have certain properties:
 
* At no point may either client or server send an unbounded number of packets without receiving a packet from its counterpart. This avoids deadlock without requiring either side to buffer an arbitrary number of packets per actor.
 
* In states where a transition can be initiated by either the debugger or the thread, it is always clear to the debugger which state the thread actually entered, and for what reason.<p>For example, if the debugger interrupts a running thread, it cannot be sure whether the thread stopped because of the interruption, paused of its own accord (to report a watchpoint hit, say), or exited. However, the next packet the debugger receives will either be "interrupted", "paused", or "exited", resolving the ambiguity.</p><p>Similarly, when the debugger attaches to a thread, it cannot be sure whether it has succeeded in attaching to the thread, or whether the thread exited before the attachment request arrived. However, in either case the debugger can expect a disambiguating response: if the attach suceeded, it receives an "attached" packet; and in the second case, it receives an "exit" packet.</p><p>To support this property, the thread ignores certain debugger packets in some states (the "interrupt" packet in the "Paused" and "Exited" states, for exmple). These cases all handle situations where the ignored packet was preempted by some thread action.</p>
 
Note that the rules here apply to the client's interactions with each thread agent separately. A client may send an "interrupt" to one thread agent while awaiting a reply to a request sent to a different thread agent.
 
== Attaching To a Thread ==
 
To attach to a thread, the client sends a packet of the form:
 
  { "to":<i>thread</i>, "type":"attach", "pause-for":<i>events</i> }
 
This tells the thread to continue to run, but asks it to pause if any of
the event described by <i>events</i> occurs. The form of <i>events</i> is
described in [[#Events]].
 
The thread responds in one of two ways:
 
  { "from":<i>thread</i>, "type":"attached" }
 
This indicates that the thread received the <tt>attach</tt> packet, and
will continue to run, reporting events of interest to the debugger. The
thread is now in the <b>Running</b> state. The actor name <i>thread</i> remains
valid until the client detaches from the thread or acknowledges a thread
exit.
 
  { "from":<i>thread</i>, "type":"exited" }
 
This indicates that the thread exited before receiving the <tt>attach</tt>
packet. The thread is now in the <b>Exited</b> state. The client must
respond to this with a packet of the form:
 
  { "to":<i>thread</i>, "type":"release" }
 
At this point, the actor name <i>thread</i> is released and available for
reuse, so the last trace of the thread's existence is gone.
 
== Detaching From a Thread ==
 
To detach from a thread, the client sends a packet of the form:
 
  { "to":<i>thread</i>, "type":"detach" }
 
The thread responds in one of three ways:
 
  { "from":<i>thread</i>, "type":"detached" }
 
This indicates that the client has detached from the thread. The thread is
now in the <b>Detached</b> state: it can run freely, and no longer reports
events to the client. The actor name <i>thread</i> is released and
available for reuse.
 
  { "from":<i>thread</i>, "type":"paused", ... }
  { "from":<i>thread</i>, "type":"detached" }
 
This series of packets indicates that the thread paused of its own accord
(for the reason given by the additional properties of the "paused" packet),
and only then received the "detach" packet. As above, this indicates that
the thread is in the <b>Detached</b> state, and the actor name is available
for reuse.
 
  { "from":<i>thread</i>, "type":"exited" }
 
This indicates that the thread exited on its own before receiving the
"detach" packet. The client should follow by sending a "release" packet, as
described above.
 
== Running Threads ==
 
Once the client has attached to a thread, it is in the <b>Running</b>
state. In this state, four things can happen:
 
* The thread can hit a breakpoint or watchpoint, or encounter some other condition of interest to the client.
* The thread can exit.
* The client can detach from the thread.
* The client can interrupt the running thread.
 
Note that a client action can occur simultaneously with a thread action.
The protocol is designed to avoid ambiguities when both client and thread
act simultaneously.
 
== Thread Pauses ==
 
If the thread pauses to report an interesting event to the client, it sends
a packet of the form:
 
  { "from":<i>thread</i>, "type":"paused", "frame":<i>frame</i>, "reason":<i>reason</i> }
 
This indicates that the thread is in the <b>Paused</b> state. The
<i>frame</i> value describes the top frame on the JavaScript stack; see
[[#Frames|frames]], below. The <i>reason</i> value describes why the thread
paused. It has one of the following forms:
 
  { "type":"breakpoint", "actor":<i>actor</i> }
 
The thread stopped at the breakpoint represented by the actor named
<i>actor</i>.
 
  { "type":"watchpoint", "actor":<i>watchpoint</i> }
 
The thread stopped at the breakpoint represented by the actor named
<i>actor</i>.
 
  { "type":"stepped" }
 
The client had asked the thread to step to the next statement, and the
thread completed that step.
 
  { "type":"pre-call" }
 
The client had asked the thread to pause before making each function call,
and the thread is about to call a function. Single-stepping the thread will
place it at the head of the function's code, with all arguments, local
variables, and local functions bound.
 
  { "type":"pre-return" }
 
The client had asked the thread to pause before returning from functions,
and the thread is about to return from a function. Single-stepping the
thread will return the thread to the calling frame.
 
  { "type":"pre-throw", "exception":<i>grip</i> }
 
The client had asked the thread to pause before throwing an exception;
<i>grip</i> is the name of an actor representing the exception value being
thrown. Control is still at the point of the throw; it has not yet passed
to a catch clause. Single-stepping this thread will report either a
"caught" or "uncaught" pause.
 
  { "type":"caught", "exception":<i>grip</i> }
 
The client stepped the thread from a "pre-throw" pause, and a catch clause
has been found for the exception referred to by <i>grip</i>; control is
stopped at the head of the catch clause, with catch variable bindings made.
If the catch is conditional, control is at the beginning of the condition.
 
  { "type":uncaught", "exception":<i>grip</i> }
 
The client stepped the thread from a "pre-throw" pause, and no catch clause
was found for the exception. <i>(I'm not sure which code the thread is
executing at this point; we might as well reveal SpiderMonkey's natural
behavior.)</i>
 
  { "type":"pre-throw-by-guard", "exception":<i>grip</i> }
 
The thread had been stopped in a conditional guard, and the client asked
the thread to continue but pause before throwing an exception. The guard
condition evaluated to false, and the thread is about to re-throw the
exception value, <i>grip</i>.
 
== Resuming a Thread ==
 
If a thread is in the <b>Paused</b> state, the client can resume it by
sending a packet of the following form:
 
  { "to":<i>thread</i>, "type":"attach", "pause-for":<i>events</i> }
 
This puts the thread in the <b>Running</b> state, but asks it to pause if
any of the event described by <i>events</i> occurs. The form of
<i>events</i> is described in [[#Events]].
 
== Interrupting a Thread ==
 
If a thread is in the <b>Running</b> state, the client can cause it to
pause where it is by sending a packet of the following form:
 
  { "to":<i>thread</i>, "type":"interrupt" }
 
The thread responds in one of three ways:
 
  { "from":<i>thread</i>, "type":"interrupted" }
 
This indicates that the thread stopped due to the client's
<tt>interrupt</tt> packet, and is now in the <b>Paused</b> state.
 
  { "from":<i>thread</i>, "type":"paused", "frame":<i>frame</i>, "reason":<i>reason</i> }
 
This indicates that the thread stopped of its own accord before receiving
the client's <tt>interrupt</tt> packet, and is now in the <b>Paused</b>
state. The meanings of the thread's packet's properties are as for an
ordinary pause. The thread will ignore the client's interrupt packet when
it receives it.
 
  { "from":<i>thread</i>, "type":"exited" }
 
This indicates that the thread exited before receiving the client's
<tt>interrupt</tt> packet, and is now in the <b>Exited</b> state. See
[[#Exiting_Threads|Exiting Threads]], below.
 
== Exiting Threads ==
 
When a thread in the <b>Running</b> state exits, it sends a packet of the following form:
 
  { "from":<i>thread</i>, "type":"exited" }
 
At this point, the thread can no longer be manipulated by the client, and most of the thread's resources may be freed; however, the thread actor name must remain alive, to handle stray <tt>interrupt</tt> and <tt>detach</tt> packets. To allow the last trace of the thread to be freed, the client should send a packet of the following form:
 
  { "to":<i>thread</i>, "type":"release" }
 
This allows the thread actor name, <i>thread</i>, to be reused for other actors.
 
= Events =
 
= Grips =
 
= Frames =

Latest revision as of 05:22, 12 January 2019

This page moved to the mozilla-central repository with bug 1354587.

Read it now at https://docs.firefox-dev.tools/backend/protocol.html.

Source code, at http://searchfox.org/mozilla-central/source/devtools/docs/backend/protocol.md

Retrieved from "https://wiki.allizom.org/index.php?title=Remote_Debugging_Protocol&oldid=1206107"