Overview

The Rhino Debug Wire Protocol (RDWP) is an adapted version of the v8 protocol using JSON to communicate with the remote Rhino interpreter executing in debug mode.

The RDWP was chosen to be JSON-based for a few reasons:

It can be more easily extended to add new events, requests or responses.

It is easier to understand by consumers

It follows the de-facto JSON standard, which could allow it to communicate with other JSON-based efforts. Note that name:value paris in a JSON packet are not necessarily ordered but that values within an array value are ordered.

Packets

The RDWP performs all communication with the remote interpreter using packets over a socket. The payload of each packet is the JSON string describing the event, request or response with a preamble containing the content length and a line terminator.

All packets follow the general form shown below. Every packet contains a unique sequence number based on its origin - client or remote interpreter. Sequence numbers begin at zero and increment by one for each packet sent. Request sequence numbers will overlap with event and response sequence numbers generated by the remote interpreter. However, each response packet contains the sequence number of its associated request packet in the request_seq argument such that responses can be matched up with requests.

vmdeath

The vmdeath event is sent when the remote interpreter is about to die / disconnect. This event is sent on a best-effort basis, meaning it is not guaranteed the event can be received, if for example, the communication channel has been interrupted before the event has been sent. The event will be sent only if a VMDeathRequest has been registered.

The body of this event is not necessarily present and is always empty when present.

example

A real life example of the vmdeath event is:

52
\r\n
{"type":"event",
"seq":7,
"event":"vmdeath",
"body":{}}

Requests

breakpoint

The breakpoint request is sent from the client to the remote interpreter to retrieve a specific breakpoint. If communication is successful a corresponding breakpointresponse is sent back from the remote interpreter.

breakpoints

The breakpoints request is sent from the client to the remote interpreter to retrieve all breakpoints set in the remote interpreter. If communication is successful a corresponding breakpointsresponse is sent back from the remote interpreter.

clearbreakpoint

The clearbreakpoint request is sent from the client to the remote interpreter to remove a specific breakpoint. If communication is successful a corresponding clearbreakpointresponse is sent back from the remote interpreter.

connect

The connect request is made from the client to the remoter interpreter to establish a connection. If communication was successful a corresponding connectresponse is sent back from the remote interpreter.

context

The context request is sent from the client to the remote interpreter to ask for the context of a specified thread. If communication is successful a corresponding contextresponse is sent back from the remote interpreter.

continue

The continue request is sent from the client to the remote interpreter to indicate that the interpreter should resume execution of a step, thread, or entire interpreter. This request has no effect if the remote interpreter is not currently in a suspended state. If communication is successful a corresponding continueresponse is sent back from the remote interpreter.

dispose

The dispose request is sent from the client to the remote interpreter to shut down the interpreter. If communication is successful a corresponding disposeresponse is sent back from the remote interpreter.

evaluate

The evaluate request is sent from the client to the remote interpreter to evaluate a given script snippet. If communication is successful a corresponding evaluateresponse is sent back from the remote interpreter.

frame

The frame request is sent from the client to the remoter interpreter to ask for a specific stack frame. If communication is successful a corresponding frameresponse is sent back from the remote interpreter.

frames

The frames request is sent from the client to the remote interpreter to retrieve stack frames for a thread. If communication is successful a corresponding framesresponse is sent back from the remote interpreter.

lookup

The lookup request is sent from the client to the remote interpreter to look up a given id - which could be any valid element id (frame id, script id, etc). If communication is successful a corresponding lookupresponse is sent back from the remoter interpreter.

scripts

The scripts request is sent from the client to the remoter interpreter to retrieve the complete listing of scripts loaded in the interpreter. If communication was successful a corresponding scriptsresponse is sent back from the remote interpreter.

setbreakpoint

The setbreakpoint request is sent from the client to the remote interpreter to set a breakpoint at a given location. If communication is successful a corresponding setbreakpointresponse is sent back from the remote interpreter.

suspend

The suspend request is sent from the client to the remote interpreter to suspend execution of a thread. The request has no effect if the thread is not in a running state. If communication is successful a corresponding suspendresponse is sent back from the remote interpreter.

threads

The threads request is sent from the client to the remote interpreter to retrieve all threads that currently exist in the interpreter. If communication is successful a corresponding threadsresponse is sent back from the remote interpreter.

version

The version request is sent from the client to the remote interpreter to retrieve the version of the Rhino interpreter. If communication was successful a corresponding versionresponse is sent back from the remote interpreter.

If the request is successful, the response body will contain a single element:

scripts

the complete listing of the ids of all of the scripts loaded in the VM.

These ids are unique for each script that is loaded in the VM and can be used to subsequently look up a script in the VM. A script id is guaranteed to be unique during the lifecycle of the VM - if the VM is restarted any held script ids cannot be guaranteed to be unique.