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.
_______________________________________________ webkit-dev mailing list [email protected] http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
