[webkit-dev] Blog post "Announcing Remote Debugging Protocol v1.0"

[Pavel Feldman]

Hi guys,

I'd like to announce the remote debugging protocol v1 where we define
backward compatibility and commit to supporting it in a blog post. The
draft can be found here: http://www.webkit.org/blog/?p=1875&preview=true.
Pasting its content for the sake of accessibility below.

Regards
Pavel

Announcing Remote Debugging Protocol
v1.0<http://www.webkit.org/blog/?p=1875>Posted
by *Pavel Feldman* on Monday, April 2nd, 2012 at 2:13 am

It has been almost a year since we
announced<http://www.webkit.org/blog/1620/webkit-remote-debugging/>
the
support for WebKit remote debugging. It is now officially supported by
BlackBerry
PlayBook<http://devblog.blackberry.com/2011/06/debugging-blackberry-web-apps/>
and
in Chrome for Android<https://developers.google.com/chrome/mobile/docs/debugging>.
Latest
version of Chrome introduces new extensions
API<http://code.google.com/chrome/devtools/docs/remote-debugging.html>
that
exposes it to the in-browser clients as well.

We are happy to announce that remote debugging protocol version is now
v1.0, and we can commit to supporting it and maintain its backward
compatibility. Since we receive a lot of questions on the remote debugging
from the port owners, protocol clients and WebKit contributors, I’d like to
provide a brief remote debugging 101 here. It will provide answers to the
questions such as:

   - What is the structure of the remote debugging message?
   - Is there a documentation of the protocol?
   - Is remote debugging protocol versioned? How is backward compatibility
   defined?
   - What do I need to do in order to support remote debugging with
   standard Web Inspector front-end in my WebKit port?

Protocol definitionProtocol schema

WebKit is using JSON-RPC 2.0 <http://jsonrpc.org/specification> protocol
for the remote debugging. Clients send commands to the backend and receive
responses in return. Backend can generate notifications upon particular
events on its own. Commands, responses and notifications are all
JSON-serialized objects.

The remote debugging protocol schema is defined by the
Inspector.json<http://trac.webkit.org/browser/trunk/Source/WebCore/inspector/Inspector.json>.
Protocol documentation<http://code.google.com/chrome/devtools/docs/protocol/tot/index.html>
along
with parts of the inspector source code is generated from that file. We
group commands and events of a particular nature into domains such as
DOM<http://code.google.com/chrome/devtools/docs/protocol/1.0/dom.html>
, Debugger<http://code.google.com/chrome/devtools/docs/protocol/1.0/debugger.html>
, Network<http://code.google.com/chrome/devtools/docs/protocol/1.0/network.html>
for
the convenience.
Commands and notifications

Here is a sample command that is setting a breakpoint:

{
    "id": 10, // <-- command sequence number generated by the caller
    "method": "Debugger.setBreakpointByUrl", // <-- protocol method
    "params": { // <-- named parameters map
        "lineNumber": 23,
        "url": "http://www.webkit.org/index.html"
    }
}

Backend responds to all the commands either with the result of with the
error message. For the above command, the backend will generate the
following response:

{
    "id": 10, // <-- same id as in the command
    "result": { // <-- command result
        "breakpointId": "http://www.webkit.org/index.html:23",
        "locations": [
            {
                "lineNumber": 23,
                "columnNumber": 10
            }
        ]
    }
}

Notifications don’t have identifiers. For example, when JavaScript source
is evaluated in the virtual machine, following notification is sent to the
client:

{
    "method": "Debugger.scriptParsed", // <-- notification method
    "params": { // <--notification parameters
        "scriptId": "15",
        "url": "http://www.webkit.org/index.html",
        "startLine": 22,
        "startColumn": 12,
        "endLine": 33,
        "endColumn": 4
    }
}

Complete list of the protocol methods for the v1.0 of the protocol can be
found here<http://code.google.com/chrome/devtools/docs/protocol/1.0/index.html>
.
Hidden entities

If you look at the
Inspector.json<http://trac.webkit.org/browser/trunk/Source/WebCore/inspector/Inspector.json>
file
that defines the protocol schema, you will notice that some of the protocol
entities (domains, commands and parameters) are marked as “hidden”. We
don’t generate documentation for such entities. Although one can
technically use them, we are not yet ready to commit to maintaining their
backward compatibility. As the protocol matures, we will be polishing these
entities and making them public.
Protocol versioning and backward compatibility

With the revision r106352 <http://trac.webkit.org/changeset/106352>, we
updated the protocol version to
v1.0<http://code.google.com/chrome/devtools/docs/protocol/1.0/index.html>.
All subsequent v1.* versions of the protocol are going to be backward
compatible with v1.0. Protocol backward compatibility is defined as follows:

   - No commands or notifications are removed from the protocol.
   - No required parameters are added to the commands.
   - No required parameters are removed from command responses or
   notifications.

We do not anticipate any breaking changes to the protocol any time soon
(years), but we leave this possibility to ourselves. We will flip the major
version component when such change comes. You can find documentation of all
of the versions of the protocol including the tip-of-tree version
here<http://code.google.com/chrome/devtools/docs/remote-debugging.html>
.
Enabling remote debugging on your WebKit portUsing Web Inspector front-end
for remote debugging

You can either come up with an alternate remote debugging client or use the
default Web Inspector front-end. Web Inspector front-end is capable of
interacting with the backend over the WebSocket transport layer. In the
remote mode, WebSocket frames will be carrying the protocol messages.
WebSocket connection is dedicated, there can only be one client attached to
the WebKit page at a time. To see how that works, you can run the Chrome
Canary <http://tools.google.com/dlpage/chromesxs> with the following
command line flag:

chrome --remote-debugging-port=9222

Then open any WebKit-based browser and navigate to http://localhost:9222.
You will see that initiating the remote debugging sessions loads the
front-end from the browser. This is possible because Chrome bundles the Web
Inspector front-end and implemented a small HTTP server for serving these
files. This is not always possible in case of embedded solutions, but since
Web Inspector front-end is just a web app, can be loaded it from any
server. Try running Chrome Canary as

chrome --remote-debugging-port=9222 --remote-debugging-frontend="
http://trac.webkit.org/export/head/trunk/Source/WebCore/inspector/front-end/inspector.html
".

It will tell Chrome to use trac.webkit.org as a front-end app. Chrome for
Android team uploads a
version<http://chrome-devtools-frontend.appspot.com/static/18.0.1025.74/devtools.html>
of
Web Inspector front-end to appspot.com with each public build and points to
it from the remote debugging page. You can download that site, change the
front-end URL to the local one and do remote debugging with no internet
connection at all.
Running WebSocket server in your port

In order to use default Web Inspector front-end for the remote debugging of
your WebKit port, you need to implement a small web server supporting
WebSocket specification. We did not make this server code a part of the
WebCore because it is up to the embedder to be listening for external
connections and discover the inspectable pages. In some cases, socket
should operate in a different process than the WebKit is operating in. For
example, in Chrome, the socket is opened by the browser process, and
browser dispatches protocol messages to the corresponding WebKit instances
running in the renderer processes. I’ll list a number of WebSocket server
implementations below.

   - To start debugging session, call
InspectorController::connectFrontend(). In
   case of WebSocket implementation, it is typically done upon accepting
   WebSocket connection.
   - To end debugging session, call
   InspectorController::disconnectFrontend().  This should be done upon
   WebSocket connection termination.
   - Call InspectorController::dispatchMessageFromFrontend(message) for
   each WebSocket frame you receive.
   - Issue WebSocket frame for each InspectorClient::sendMessageToFrontend call
   you get from the WebCore

See Chrome light http
server<http://src.chromium.org/viewvc/chrome/trunk/src/net/server/http_server.h?view=markup>
 and devtools handler<http://src.chromium.org/viewvc/chrome/trunk/src/content/browser/debugger/devtools_http_handler_impl.cc?view=markup>
for
reference. There is an effort that adds generic WebSocket server for
inspector to WebKit2. You can
track<https://bugs.webkit.org/show_bug.cgi?id=73092>
 these <https://bugs.webkit.org/show_bug.cgi?id=73093>
bugs<https://bugs.webkit.org/show_bug.cgi?id=73094> to
follow the discussion or borrow the code for your own port.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20120402/306e2aa6/attachment.html>