Announcing Remote Debugging Protocol v1.0

转自：http://www.tuicool.com/articles/UBbMBb

Announcing Remote Debugging Protocol v1.0

It has been almost a year since we announced the support for WebKit remote debugging. It is now officially supported by BlackBerry PlayBook and in Chrome for Android . Latest version of Chrome introduces new  extensions API  that exposes it to the in-browser clients as well.

Today we are happy to announce the v1.0 of the remote debugging protocol. We commit to supporting it and maintain its backward compatibility from now on. 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 messages?
• 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 definition

Protocol schema

WebKit is using JSON-RPC 2.0 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 . Protocoldocumentation , 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 ,Debugger , Network for the user’s 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 a result or with an 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 .

Hidden entities

If you look at the 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 , we updated the protocol version to v1.0 . 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 .

Enabling remote debugging on your WebKit port

By default, remote debugging is using WebSocket transport for the protocol messages. That’s the transport you need to support in your WebKit port if you want Web Inspector front-end to be able to attach to the running pages. In this mode WebSocket frames are carrying the serialized protocol messages. Note that WebSocket connection is dedicated, there can only be one client attached to the WebKit page at a time.

Using Web Inspector front-end as a remote debugging client

Under the hood, Web Inspector front-end is a web app that can function in a stand-alone mode. It supports ws= query parameter that points to the WebSocket wired to the WebKit backend (it also supports host= and page= parameters that are now deprecated). Some browsers (such as Chrome or Safari) bundle Web Inspector front-end with their distributives, others (Chrome for Android) upload it to the web and point to it.

To see how it works, you can run the Chrome Canary with the following command line flag:

chrome --remote-debugging-port=9222

Then open any other WebKit-based browser and navigate tohttp://localhost:9222 . You will see that initiating the remote debugging session loads the front-end files from the browser. This is possible because Chrome implements a small HTTP server for serving bundled front-end files. But since Web Inspector front-end is just a web app, it can be loaded from any location. 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 source for front-end files. See how entire Web Inspector front-end loads from the source code repository when you inspect one of the tabs. You could have manually navigated to thehttp://trac.webkit.org/export/head/trunk/Source/WebCore/inspector/front-end/inspector.html?ws=localhost:9222/devtools/page/<tab-id>and that would also initiate the debugging session.

Chrome for Android team uses similar approach and uploads a  version of Web Inspector front-end to appspot.com with each public build. But now you know, that 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 the default Web Inspector front-end for the remote debugging of your WebKit port, you need to implement a small web server supporting the 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 inspected WebKit instance. 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.

Here is what your WebSocket server needs to do:

• Upon accepting the WebSocket connection, it should start a debugging session via calling the InspectorController::connectFrontend() method.
• Upon connection termination, it should callInspectorController::disconnectFrontend() .
• For each incoming WebSocket frame, it should callInspectorController::dispatchMessageFromFrontend(message) with the frame content passed as message .
• It should send WebSocket frame over the connection for eachInspectorClient::sendMessageToFrontend() callback that it receives from the inspector.

See Chrome  light http server  and  devtools handler for reference.

WebKit2 currently also includes a generic WebSocket server for the inspector. To use it with your port you need to:

• Define ENABLE_INSPECTOR_SERVER=1 in Source/WebKit2/config.h and add Source/WebKit2/UIProcess/InspectorServer/* to your build system
• Provide an implementation for WebSocketServer::platform*
• Start the server by calling WebInspectorServer::listen in the UI process

The server could also be modified to be used without WebKit2, but you would have to tear WebInspectorProxy out of WebInspectorServer and connect InspectorController and InspectorClient yourself to WebInspectorServer.