Web Console remoting

  • Revision slug: Tools/Web_Console/remoting
  • Revision title: Web Console remoting
  • Revision id: 318101
  • Created:
  • Creator: mihaisucan
  • Is current revision? No
  • Comment cleanup

Revision Content

Introduction

This document describes the way Web Console remoting works. The Web Console is split between a client with its user interface, and the server which has listeners for all the things that happen in the tab. For communication between the server and the client we use the Remote Debugging Protocol. This architecture allows you to connect a Web Console client instance to a server running on B2G, Fennec or some other Firefox instance.

To better understand the architecture of the Web Console we recommend learning about the debugger architecture.

The WebConsoleActor and the WebConsoleClient

The WebConsoleActor lives in dbg-webconsole-actors.js, in the toolkit/devtools/webconsole folder.

The WebConsoleClient lives in WebConsoleClient.jsm (in toolkit/devtools/webconsole) and it used by the Web Console when working with the Web Console actor.

To see how the debugger is used in the Web Console code, look in browser/devtools/webconsole/webconsole.js, search for WebConsoleConnectionProxy.

Do note that we created only one Web Console actor for the general needs of the Web Console. The new actors:

  • The WebConsoleActor allows JS evaluation, autocomplete, start/stop listeners, etc.
  • The WebConsoleObjectActor allows us to marshal content objects from the server to the client.
  • The NetworkEventActor is used for each new network request. The client can request further network event details - like response body or request headers.

To attach to the WebConsoleActor one follows these steps:

connectToServer() // the usual
listTabs()
pickTheTabYouWant()
debuggerClient.attachConsole(tab.consoleActor, listeners, onAttachConsole)

The listeners arguments tells which listeners you want to start in the web console. These can be: page errors, window.console API messages, network activity and file activity.

The onAttachConsole callback receives a new instance of the WebConsoleClient object. This object provides methods that abstract away protocol packets, things like startListeners(), stopListeners(), etc.

Protocol packets look as follows:

{
  "to": "root",
  "type": "listTabs"
}
{
  "from": "root",
  "consoleActor": "conn0.console9",
  "selected": 2,
  "tabs": [
    {
      "actor": "conn0.tab2",
      "consoleActor": "conn0.console7",
      "title": "",
      "url": "https://tbpl.mozilla.org/?tree=Fx-Team"
    },
// ...
  ]
}

Notice that the consoleActor is also available as a global actor. When you attach to the global consoleActor you receive all of the network requests, page errors, and all of the other events from all of the tabs and windows, including chrome errors and network events. This allows us to implement a Global Console or to debug remote Firefox/B2G instances.

startListeners(listeners, onResponse)

The new startListeners packet:

{
  "to": "conn0.console9",
  "type": "startListeners",
  "listeners": [
    "PageError",
    "ConsoleAPI",
    "NetworkActivity",
    "FileActivity",
    "LocationChange"
  ]
}

The idea with the startListeners packet is that you can start/stop listeners as needed. You do not need to attach and start all listeners at once. You get only what you need. The reply is:

{
  "startedListeners": [
    "PageError",
    "ConsoleAPI",
    "NetworkActivity",
    "FileActivity",
    "LocationChange"
  ],
  "nativeConsoleAPI": true,
  "from": "conn0.console9"
}

The reply tells which listeners were started and it includes a flag nativeConsoleAPI which tells if the window.console object was overridden by the scripts in the page or not.

getCachedMessages(types, onResponse)

One can do webConsoleClient.getCachedMessages(types, onResponse). This method sends the following packet to the server:

{
  "to": "conn0.console9",
  "type": "getCachedMessages",
  "messageTypes": [
    "PageError",
    "ConsoleAPI"
  ]
}

The getCachedMessages packet allows one to retrieve the cached messages from before the Web Console was open. You can only get cached messages for page errors and console API calls. The reply looks like this:

{
  "messages": [ ... ],
  "from": "conn0.console9"
}

Each message in the array is of the same type as when we send typical page errors and console API calls. These will be explained in the following sections of this document.

setPreferences(prefs, onResponse)

To allow the Web Console to configure logging options while it is running we have added the setPreferences packet:

{
  "to": "conn0.console9",
  "type": "setPreferences",
  "preferences": {
    "NetworkMonitor.saveRequestAndResponseBodies": false
  }
}

Reply:

{
  "updated": [
    "NetworkMonitor.saveRequestAndResponseBodies"
  ],
  "from": "conn0.console10"
}

For convenience you can use webConsoleClient.setPreferences(prefs, onResponse).

Page errors

Page errors come from the nsIConsoleService. Each allowed page error is an nsIScriptError object.

The new pageError packet is:

{
  "from": "conn0.console9",
  "type": "pageError",
  "pageError": {
    "message": "[JavaScript Error: \"ReferenceError: foo is not defined\" {file: \"http://localhost/~mihai/mozilla/test.js\" line: 6}]",
    "errorMessage": "ReferenceError: foo is not defined",
    "sourceName": "http://localhost/~mihai/mozilla/test.js",
    "lineText": "",
    "lineNumber": 6,
    "columnNumber": 0,
    "category": "content javascript",
    "timeStamp": 1347294508210,
    "error": false,
    "warning": false,
    "exception": true,
    "strict": false
  }
}

The packet is similar to nsIScriptError - for simplicity. We only removed several unneeded properties and changed how flags work.

Console API messages and JavaScript evaluation

The WebConsoleObjectActor

The actor grip looks as follows, for two different objects:

{
  "type": "object",
  "className": "HTMLDivElement",
  "displayString": "[object HTMLDivElement]",
  "inspectable": true,
  "actor": "conn0.consoleObj12"
}
{
  "type": "object",
  "className": "Object",
  "displayString": "({a:1, b:2, c:3})",
  "inspectable": true,
  "actor": "conn0.consoleObj16"
}

The above packet is the minimal information we send to the web console, such that the object can be displayed in the output and in the property panel. Unfortunately, we have some "weird" ways on how we display objects - and these are different in the property panel.

This is the actor grip for functions:

{
  "type": "function",
  "className": "function",
  "displayString": "function myOnPaste(e)\n{\n  console.log(\"onpaste!\");\n}",
  "inspectable": false,
  "functionName": "myOnPaste",
  "functionArguments": [
    "e"
  ],
  "actor": "conn0.consoleObj15"
}

This object actor does not need the debugger API, nor does it need the ThreadActor. It does not implement any of the request types from ObjectActor since they do not suit the needs of the Web Console client, except the release request which releases the object actor.

The inspectProperties request

The Web Console object actor implements the inspectProperties request type:

{
  "to": "conn0.consoleObj17",
  "type": "inspectProperties"
}

Example reply:

{
  "from": "conn0.consoleObj17",
  "properties": [
    {
      "name": "duron",
      "configurable": true,
      "enumerable": true,
      "writable": true,
      "value": {
        "type": "object",
        "className": "Object",
        "displayString": "({opteron:\"amd\", athlon:\"amd\", core2duo:\"intel\", nehalem:\"intel\"})",
        "inspectable": true,
        "actor": "conn0.consoleObj18"
      }
    },
    {
      "name": "foobar",
      "configurable": true,
      "enumerable": true,
      "writable": true,
      "value": "omg"
    },
    {
      "name": "zuzu",
      "configurable": true,
      "enumerable": true,
      "writable": true,
      "value": "boom"
    }
  ]
}

For each enumerable property on the object we send a property descriptor. The properties array is sorted by property name. In each descriptor, for set, get and value we create object actors, if needed.

Console API messages, the consoleAPICall packet

Console API messages come through the nsIObserverService - the console object implementation lives in dom/base/ConsoleAPI.js.

For each console message we receive in the server, we send something similar to the following packet to the client:

{
  "from": "conn0.console9",
  "type": "consoleAPICall",
  "message": {
    "level": "error",
    "filename": "http://localhost/~mihai/mozilla/test.html",
    "lineNumber": 149,
    "functionName": "",
    "timeStamp": 1347302713771,
    "arguments": [
      "error omg aloha ",
      {
        "type": "object",
        "className": "HTMLBodyElement",
        "displayString": "[object HTMLBodyElement]",
        "inspectable": true,
        "actor": "conn0.consoleObj20"
      },
      " 960 739 3.141592653589793 %a",
      "zuzu",
      {
        "type": "null"
      },
      {
        "type": "undefined"
      }
    ]
  }
}

Similar to how we send the page errors, here we send the actual console event received from the nsIObserverService. We change the arguments array - we create WebConsoleObjectActors for each object passed as an argument - and, lastly, we remove some unneeded properties (like window IDs). The Web Console can then inspect the arguments.

We have small variations for the object, depending on the console API call method - just like there are small differences in the console event object received from the observer service.

JavaScript evaluation

The evaluateJS request and response packets

The Web Console client provides the evaluateJS(requestId, string, onResponse) method which sends the following packet:

{
  "to": "conn0.console9",
  "type": "evaluateJS",
  "text": "document"
}

Response packet:

{
  "from": "conn0.console9",
  "input": "document",
  "result": {
    "type": "object",
    "className": "HTMLDocument",
    "displayString": "[object HTMLDocument]",
    "inspectable": true,
    "actor": "conn0.consoleObj20"
  },
  "timestamp": 1347306273605,
  "error": null,
  "errorMessage": null,
  "helperResult": null
}
  • error holds the JSON-ification of the exception thrown during evaluation;
  • errorMessage holds the error.toString() result.
  • result has the result object actor.
  • helperResult is anything that might come from a JSTerm helper result, JSON stuff (not content objects!).

Autocomplete and more

The autocomplete request packet:

{
  "to": "conn0.console9",
  "type": "autocomplete",
  "text": "d",
  "cursor": 1
}

The response packet:

{
  "from": "conn0.console9",
  "matches": [
    "decodeURI",
    "decodeURIComponent",
    "defaultStatus",
    "devicePixelRatio",
    "disableExternalCapture",
    "dispatchEvent",
    "doMyXHR",
    "document",
    "dump"
  ],
  "matchProp": "d"
}

There's also the clearMessagesCache request packet that has no response. This clears the console API calls cache and should clear the page errors cache - see bug 717611.

Network logging

The networkEvent packet

Whenever a new network request starts being logged the networkEvent packet is sent:

{
  "from": "conn0.console10",
  "type": "networkEvent",
  "eventActor": {
    "actor": "conn0.netEvent14",
    "startedDateTime": "2012-09-17T19:50:03.699Z",
    "url": "http://localhost/~mihai/mozilla/test2.css",
    "method": "GET"
  }
}

This packet is used to inform the Web Console of a new network event. For each request a new NetworkEventActor instance is created.

The NetworkEventActor

The new network event actor stores further request and response information.

The networkEventUpdate packet

The Web Console UI needs to be kept up-to-date when changes happen, when new stuff is added. The new networkEventUpdate packet is sent for this purpose. Examples:

{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "requestHeaders",
  "headers": 10,
  "headersSize": 425
}
{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "requestCookies",
  "cookies": 0
}
{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "responseStart",
  "response": {
    "httpVersion": "HTTP/1.1",
    "status": "304",
    "statusText": "Not Modified",
    "headersSize": 194,
    "discardResponseBody": true
  }
}
{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "eventTimings",
  "totalTime": 1
}
{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "responseHeaders",
  "headers": 6,
  "headersSize": 194
}
{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "responseCookies",
  "cookies": 0
}
{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "responseContent",
  "mimeType": "text/css",
  "contentSize": 0,
  "discardResponseBody": true
}

Actual headers, cookies and bodies are not sent.

The getRequestHeaders and other packets

To get more details about a network event you can use the following packet requests (and replies).

The getRequestHeaders packet:

{
  "to": "conn0.netEvent15",
  "type": "getRequestHeaders"
}
{
  "from": "conn0.netEvent15",
  "headers": [
    {
      "name": "Host",
      "value": "localhost"
    }, ...
  ],
  "headersSize": 350
}

The getRequestCookies packet:

{
  "to": "conn0.netEvent15",
  "type": "getRequestCookies"
}
{
  "from": "conn0.netEvent15",
  "cookies": []
}

The getResponseHeaders packet:

{
  "to": "conn0.netEvent15",
  "type": "getResponseHeaders"
}
{
  "from": "conn0.netEvent15",
  "headers": [
    {
      "name": "Date",
      "value": "Mon, 17 Sep 2012 20:05:27 GMT"
    }, ...
  ],
  "headersSize": 320
}

The getResponseCookies packet:

{
  "to": "conn0.netEvent15",
  "type": "getResponseCookies"
}
{
  "from": "conn0.netEvent15",
  "cookies": []
}

The getRequestPostData packet:

{
  "to": "conn0.netEvent15",
  "type": "getRequestPostData"
}
{
  "from": "conn0.netEvent15",
  "postData": { text: "foobar" },
  "postDataDiscarded": false
}

The getResponseContent packet:

{
  "to": "conn0.netEvent15",
  "type": "getResponseContent"
}
{
  "from": "conn0.netEvent15",
  "content": {
    "mimeType": "text/css",
    "text": "\n@import \"test.css\";\n\n.foobar { color: green }\n\n"
  },
  "contentDiscarded": false
}

The getEventTimings packet:

{
  "to": "conn0.netEvent15",
  "type": "getEventTimings"
}
{
  "from": "conn0.netEvent15",
  "timings": {
    "blocked": 0,
    "dns": 0,
    "connect": 0,
    "send": 0,
    "wait": 16,
    "receive": 0
  },
  "totalTime": 16
}

The fileActivity packet

When a file load is observed the following fileActivity packet is sent to the client:

{
  "from": "conn0.console9",
  "type": "fileActivity",
  "uri": "file:///home/mihai/public_html/mozilla/test2.css"
}

The locationChange packet

The locationChange packets:

{
  "from": "conn0.console9",
  "type": "locationChange",
  "uri": "http://localhost/~mihai/mozilla/test.html",
  "title": "",
  "state": "start",
  "nativeConsoleAPI": true
}

{
  "from": "conn0.console9",
  "type": "locationChange",
  "uri": "http://localhost/~mihai/mozilla/test.html",
  "title": "foobar",
  "state": "stop",
  "nativeConsoleAPI": true
}

The nativeConsoleAPI API flag is included such that the user is correctly informed if the window.console API is overridden on the new page.

Conclusions

As of this writing, this document is a dense summary of the work we did in bug 768096. We hope this is helpful for you.

If you make changes to the Web Console server please update this document. Thank you!

Revision Source

<h1 id="Introduction">Introduction</h1>
<p>This document describes the way Web Console remoting works. The Web Console is split between a client with its user interface, and the server which has listeners for all the things that happen in the tab. For communication between the server and the client we use the <a href="https://wiki.mozilla.org/Remote_Debugging_Protocol" title="https://wiki.mozilla.org/Remote_Debugging_Protocol">Remote Debugging Protocol</a>. This architecture allows you to connect a Web Console client instance to a server running on B2G, Fennec or some other Firefox instance.</p>
<p>To better understand the architecture of the Web Console we recommend learning about the <a href="https://wiki.mozilla.org/Debugger_Architecture" title="https://wiki.mozilla.org/Debugger_Architecture">debugger architecture</a>.</p>
<h1 id="The_WebConsoleActor_and_the_WebConsoleClient">The <code>WebConsoleActor</code> and the <code>WebConsoleClient</code></h1>
<p>The <code>WebConsoleActor</code> lives in <code>dbg-webconsole-actors.js</code>, in the <code>toolkit/devtools/webconsole</code> folder.</p>
<p>The <code>WebConsoleClient</code> lives in <code>WebConsoleClient.jsm</code> (in <code>toolkit/devtools/webconsole</code>) and it used by the Web Console when working with the Web Console actor.</p>
<p>To see how the debugger is used in the Web Console code, look in <code>browser/devtools/webconsole/webconsole.js</code>, search for <code>WebConsoleConnectionProxy</code>.</p>
<p>Do note that we created only one Web Console actor for the general needs of the Web Console. The new actors:</p>
<ul>
  <li>The <code>WebConsoleActor</code> allows JS evaluation, autocomplete, start/stop listeners, etc.</li>
  <li>The <code>WebConsoleObjectActor</code> allows us to marshal content objects from the server to the client.</li>
  <li>The <code>NetworkEventActor</code> is used for each new network request. The client can request further network event details - like response body or request headers.</li>
</ul>
<p>To attach to the <code>WebConsoleActor</code> one follows these steps:</p>
<pre class="brush:js;">
connectToServer() // the usual
listTabs()
pickTheTabYouWant()
debuggerClient.attachConsole(tab.consoleActor, listeners, onAttachConsole)
</pre>
<p>The <code>listeners</code> arguments tells which listeners you want to start in the web console. These can be: page errors, <code>window.console</code> API messages, network activity and file activity.</p>
<p>The <code>onAttachConsole</code> callback receives a new instance of the <code>WebConsoleClient</code> object. This object provides methods that abstract away protocol packets, things like <code>startListeners(), stopListeners()</code>, etc.</p>
<p>Protocol packets look as follows:</p>
<pre class="brush:js;">
{
  "to": "root",
  "type": "listTabs"
}
{
  "from": "root",
  "consoleActor": "conn0.console9",
  "selected": 2,
  "tabs": [
    {
      "actor": "conn0.tab2",
      "consoleActor": "conn0.console7",
      "title": "",
      "url": "https://tbpl.mozilla.org/?tree=Fx-Team"
    },
// ...
  ]
}
</pre>
<p>Notice that the <code>consoleActor</code> is also available as a <strong>global actor</strong>. When you attach to the global <code>consoleActor</code> you receive all of the network requests, page errors, and all of the other events from all of the tabs and windows, including chrome errors and network events. This allows us to implement a Global Console or to debug remote Firefox/B2G instances.</p>
<h2 id="startListeners(listeners.2C_onResponse)"><code>startListeners(listeners, onResponse)</code></h2>
<p>The new <code>startListeners</code> packet:</p>
<pre class="brush:js;">
{
  "to": "conn0.console9",
  "type": "startListeners",
  "listeners": [
    "PageError",
    "ConsoleAPI",
    "NetworkActivity",
    "FileActivity",
    "LocationChange"
  ]
}
</pre>
<p>The idea with the <code>startListeners</code> packet is that you can start/stop listeners as needed. You do not need to attach and start all listeners at once. You get only what you need. The reply is:</p>
<pre class="brush:js;">
{
  "startedListeners": [
    "PageError",
    "ConsoleAPI",
    "NetworkActivity",
    "FileActivity",
    "LocationChange"
  ],
  "nativeConsoleAPI": true,
  "from": "conn0.console9"
}
</pre>
<p>The reply tells which listeners were started and it includes a flag <code>nativeConsoleAPI</code> which tells if the <code>window.console</code> object was overridden by the scripts in the page or not.</p>
<h2 id="getCachedMessages(types.2C_onResponse)"><code>getCachedMessages(types, onResponse)</code></h2>
<p>One can do <code>webConsoleClient.getCachedMessages(types, onResponse)</code>. This method sends the following packet to the server:</p>
<pre class="brush:js;">
{
  "to": "conn0.console9",
  "type": "getCachedMessages",
  "messageTypes": [
    "PageError",
    "ConsoleAPI"
  ]
}
</pre>
<p>The <code>getCachedMessages</code> packet allows one to retrieve the cached messages from before the Web Console was open. You can only get cached messages for page errors and console API calls. The reply looks like this:</p>
<pre class="brush:js;">
{
  "messages": [ ... ],
  "from": "conn0.console9"
}
</pre>
<p>Each message in the array is of the same type as when we send typical page errors and console API calls. These will be explained in the following sections of this document.</p>
<h2 id="setPreferences(prefs.2C_onResponse)"><code>setPreferences(prefs, onResponse)</code></h2>
<p>To allow the Web Console to configure logging options while it is running we have added the <code>setPreferences</code> packet:</p>
<pre class="brush:js;">
{
  "to": "conn0.console9",
  "type": "setPreferences",
  "preferences": {
    "NetworkMonitor.saveRequestAndResponseBodies": false
  }
}
</pre>
<p>Reply:</p>
<pre class="brush:js;">
{
  "updated": [
    "NetworkMonitor.saveRequestAndResponseBodies"
  ],
  "from": "conn0.console10"
}
</pre>
<p>For convenience you can use <code>webConsoleClient.setPreferences(prefs, onResponse)</code>.</p>
<h1 id="Patch_1.3A_page_errors">Page errors</h1>
<p>Page errors come from the <code>nsIConsoleService</code>. Each allowed page error is an <code>nsIScriptError</code> object.</p>
<p>The new <code>pageError</code> packet is:</p>
<pre class="brush:js;">
{
  "from": "conn0.console9",
  "type": "pageError",
  "pageError": {
    "message": "[JavaScript Error: \"ReferenceError: foo is not defined\" {file: \"http://localhost/~mihai/mozilla/test.js\" line: 6}]",
    "errorMessage": "ReferenceError: foo is not defined",
    "sourceName": "http://localhost/~mihai/mozilla/test.js",
    "lineText": "",
    "lineNumber": 6,
    "columnNumber": 0,
    "category": "content javascript",
    "timeStamp": 1347294508210,
    "error": false,
    "warning": false,
    "exception": true,
    "strict": false
  }
}
</pre>
<p>The packet is similar to <code>nsIScriptError</code> - for simplicity. We only removed several unneeded properties and changed how flags work.</p>
<h1 id="Patch_2.3A_Console_API_messages_and_JavaScript_evaluation">Console API messages and JavaScript evaluation</h1>
<h2 id="The_WebConsoleObjectActor">The <code>WebConsoleObjectActor</code></h2>
<p>The actor grip looks as follows, for two different objects:</p>
<pre class="brush:js;">
{
  "type": "object",
  "className": "HTMLDivElement",
  "displayString": "[object HTMLDivElement]",
  "inspectable": true,
  "actor": "conn0.consoleObj12"
}
{
  "type": "object",
  "className": "Object",
  "displayString": "({a:1, b:2, c:3})",
  "inspectable": true,
  "actor": "conn0.consoleObj16"
}
</pre>
<p>The above packet is the minimal information we send to the web console, such that the object can be displayed in the output and in the property panel. Unfortunately, we have some "weird" ways on how we display objects - and these are different in the property panel.</p>
<p>This is the actor grip for functions:</p>
<pre class="brush:js;">
{
  "type": "function",
  "className": "function",
  "displayString": "function myOnPaste(e)\n{\n  console.log(\"onpaste!\");\n}",
  "inspectable": false,
  "functionName": "myOnPaste",
  "functionArguments": [
    "e"
  ],
  "actor": "conn0.consoleObj15"
}
</pre>
<p>This object actor does not need the debugger API, nor does it need the <code>ThreadActor</code>. It does not implement any of the request types from <code>ObjectActor</code> since they do not suit the needs of the Web Console client, except the <code>release</code> request which releases the object actor.</p>
<h3 id="The_inspectProperties_request">The <code>inspectProperties</code> request</h3>
<p>The Web Console object actor implements the <code>inspectProperties</code> request type:</p>
<pre class="brush:js;">
{
  "to": "conn0.consoleObj17",
  "type": "inspectProperties"
}
</pre>
<p>Example reply:</p>
<pre class="brush:js;">
{
  "from": "conn0.consoleObj17",
  "properties": [
    {
      "name": "duron",
      "configurable": true,
      "enumerable": true,
      "writable": true,
      "value": {
        "type": "object",
        "className": "Object",
        "displayString": "({opteron:\"amd\", athlon:\"amd\", core2duo:\"intel\", nehalem:\"intel\"})",
        "inspectable": true,
        "actor": "conn0.consoleObj18"
      }
    },
    {
      "name": "foobar",
      "configurable": true,
      "enumerable": true,
      "writable": true,
      "value": "omg"
    },
    {
      "name": "zuzu",
      "configurable": true,
      "enumerable": true,
      "writable": true,
      "value": "boom"
    }
  ]
}
</pre>
<p>For each enumerable property on the object we send a property descriptor. The <code>properties</code> array is sorted by property name. In each descriptor, for <code>set</code>, <code>get</code> and <code>value</code> we create object actors, if needed.</p>
<h2 id="Console_API_messages.2C_the_consoleAPICall_packet">Console API messages, the <code>consoleAPICall</code> packet</h2>
<p>Console API messages come through the <code>nsIObserverService</code> - the console object implementation lives in <code>dom/base/ConsoleAPI.js</code>.</p>
<p>For each console message we receive in the server, we send something similar to the following packet to the client:</p>
<pre class="brush:js;">
{
  "from": "conn0.console9",
  "type": "consoleAPICall",
  "message": {
    "level": "error",
    "filename": "http://localhost/~mihai/mozilla/test.html",
    "lineNumber": 149,
    "functionName": "",
    "timeStamp": 1347302713771,
    "arguments": [
      "error omg aloha ",
      {
        "type": "object",
        "className": "HTMLBodyElement",
        "displayString": "[object HTMLBodyElement]",
        "inspectable": true,
        "actor": "conn0.consoleObj20"
      },
      " 960 739 3.141592653589793 %a",
      "zuzu",
      {
        "type": "null"
      },
      {
        "type": "undefined"
      }
    ]
  }
}
</pre>
<p>Similar to how we send the page errors, here we send the actual console event received from the <code>nsIObserverService</code>. We change the <code>arguments</code> array - we create <code>WebConsoleObjectActors</code> for each object passed as an argument - and, lastly, we remove some unneeded properties (like window IDs). The Web Console can then inspect the arguments.</p>
<p>We have small variations for the object, depending on the console API call method - just like there are small differences in the console event object received from the observer service.</p>
<h2 id="JavaScript_evaluation">JavaScript evaluation</h2>
<h3 id="The_evaluateJS_request_and_response_packets">The <code>evaluateJS</code> request and response packets</h3>
<p>The Web Console client provides the <code>evaluateJS(requestId, string, onResponse)</code> method which sends the following packet:</p>
<pre class="brush:js;">
{
  "to": "conn0.console9",
  "type": "evaluateJS",
  "text": "document"
}
</pre>
<p>Response packet:</p>
<pre class="brush:js;">
{
  "from": "conn0.console9",
  "input": "document",
  "result": {
    "type": "object",
    "className": "HTMLDocument",
    "displayString": "[object HTMLDocument]",
    "inspectable": true,
    "actor": "conn0.consoleObj20"
  },
  "timestamp": 1347306273605,
  "error": null,
  "errorMessage": null,
  "helperResult": null
}
</pre>
<ul>
  <li><code>error</code> holds the JSON-ification of the exception thrown during evaluation;</li>
  <li><code>errorMessage</code> holds the <code>error.toString()</code> result.</li>
  <li><code>result</code> has the result object actor.</li>
  <li><code>helperResult</code> is anything that might come from a JSTerm helper result, JSON stuff (not content objects!).</li>
</ul>
<h2 id="Autocomplete_and_more">Autocomplete and more</h2>
<p>The <code>autocomplete</code> request packet:</p>
<pre class="brush:js;">
{
  "to": "conn0.console9",
  "type": "autocomplete",
  "text": "d",
  "cursor": 1
}
</pre>
<p>The response packet:</p>
<pre class="brush:js;">
{
  "from": "conn0.console9",
  "matches": [
    "decodeURI",
    "decodeURIComponent",
    "defaultStatus",
    "devicePixelRatio",
    "disableExternalCapture",
    "dispatchEvent",
    "doMyXHR",
    "document",
    "dump"
  ],
  "matchProp": "d"
}
</pre>
<p>There's also the <code>clearMessagesCache</code> request packet that has no response. This clears the console API calls cache and should clear the page errors cache - see <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=717611">bug 717611</a>.</p>
<h1 id="Patch_3.3A_network_logging">Network logging</h1>
<h2 id="The_networkEvent_packet">The <code>networkEvent</code> packet</h2>
<p>Whenever a new network request starts being logged the <code>networkEvent</code> packet is sent:</p>
<pre class="brush:js;">
{
  "from": "conn0.console10",
  "type": "networkEvent",
  "eventActor": {
    "actor": "conn0.netEvent14",
    "startedDateTime": "2012-09-17T19:50:03.699Z",
    "url": "http://localhost/~mihai/mozilla/test2.css",
    "method": "GET"
  }
}
</pre>
<p>This packet is used to inform the Web Console of a new network event. For each request a new <code>NetworkEventActor</code> instance is created.</p>
<h2 id="The_NetworkEventActor">The <code>NetworkEventActor</code></h2>
<p>The new network event actor stores further request and response information.</p>
<h3 id="The_networkEventUpdate_packet">The <code>networkEventUpdate</code> packet</h3>
<p>The Web Console UI needs to be kept up-to-date when changes happen, when new stuff is added. The new <code>networkEventUpdate</code> packet is sent for this purpose. Examples:</p>
<pre class="brush:js;">
{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "requestHeaders",
  "headers": 10,
  "headersSize": 425
}
{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "requestCookies",
  "cookies": 0
}
{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "responseStart",
  "response": {
    "httpVersion": "HTTP/1.1",
    "status": "304",
    "statusText": "Not Modified",
    "headersSize": 194,
    "discardResponseBody": true
  }
}
{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "eventTimings",
  "totalTime": 1
}
{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "responseHeaders",
  "headers": 6,
  "headersSize": 194
}
{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "responseCookies",
  "cookies": 0
}
{
  "from": "conn0.netEvent14",
  "type": "networkEventUpdate",
  "updateType": "responseContent",
  "mimeType": "text/css",
  "contentSize": 0,
  "discardResponseBody": true
}
</pre>
<p>Actual headers, cookies and bodies are not sent.</p>
<h3 id="The_getRequestHeaders_and_other_packets">The <code>getRequestHeaders</code> and other packets</h3>
<p>To get more details about a network event you can use the following packet requests (and replies).</p>
<p>The <code>getRequestHeaders</code> packet:</p>
<pre class="brush:js;">
{
  "to": "conn0.netEvent15",
  "type": "getRequestHeaders"
}
{
  "from": "conn0.netEvent15",
  "headers": [
    {
      "name": "Host",
      "value": "localhost"
    }, ...
  ],
  "headersSize": 350
}
</pre>
<p>The <code>getRequestCookies</code> packet:</p>
<pre class="brush:js;">
{
  "to": "conn0.netEvent15",
  "type": "getRequestCookies"
}
{
  "from": "conn0.netEvent15",
  "cookies": []
}
</pre>
<p>The <code>getResponseHeaders</code> packet:</p>
<pre class="brush:js;">
{
  "to": "conn0.netEvent15",
  "type": "getResponseHeaders"
}
{
  "from": "conn0.netEvent15",
  "headers": [
    {
      "name": "Date",
      "value": "Mon, 17 Sep 2012 20:05:27 GMT"
    }, ...
  ],
  "headersSize": 320
}
</pre>
<p>The <code>getResponseCookies</code> packet:</p>
<pre class="brush:js;">
{
  "to": "conn0.netEvent15",
  "type": "getResponseCookies"
}
{
  "from": "conn0.netEvent15",
  "cookies": []
}
</pre>
<p>The <code>getRequestPostData</code> packet:</p>
<pre class="brush:js;">
{
  "to": "conn0.netEvent15",
  "type": "getRequestPostData"
}
{
  "from": "conn0.netEvent15",
  "postData": { text: "foobar" },
  "postDataDiscarded": false
}</pre>
<p>The <code>getResponseContent</code> packet:</p>
<pre class="brush:js;">
{
  "to": "conn0.netEvent15",
  "type": "getResponseContent"
}
{
  "from": "conn0.netEvent15",
  "content": {
    "mimeType": "text/css",
    "text": "\n@import \"test.css\";\n\n.foobar { color: green }\n\n"
  },
  "contentDiscarded": false
}
</pre>
<p>The <code>getEventTimings</code> packet:</p>
<pre class="brush:js;">
{
  "to": "conn0.netEvent15",
  "type": "getEventTimings"
}
{
  "from": "conn0.netEvent15",
  "timings": {
    "blocked": 0,
    "dns": 0,
    "connect": 0,
    "send": 0,
    "wait": 16,
    "receive": 0
  },
  "totalTime": 16
}
</pre>
<h2 id="The_fileActivity_packet">The <code>fileActivity</code> packet</h2>
<p>When a file load is observed the following <code>fileActivity</code> packet is sent to the client:</p>
<pre class="brush:js;">
{
  "from": "conn0.console9",
  "type": "fileActivity",
  "uri": "file:///home/mihai/public_html/mozilla/test2.css"
}
</pre>
<h2 id="The_locationChange_packet">The <code>locationChange</code> packet</h2>
<p>The <code>locationChange</code> packets:</p>
<pre class="brush:js;">
{
  "from": "conn0.console9",
  "type": "locationChange",
  "uri": "http://localhost/~mihai/mozilla/test.html",
  "title": "",
  "state": "start",
  "nativeConsoleAPI": true
}

{
  "from": "conn0.console9",
  "type": "locationChange",
  "uri": "http://localhost/~mihai/mozilla/test.html",
  "title": "foobar",
  "state": "stop",
  "nativeConsoleAPI": true
}
</pre>
<p>The <code>nativeConsoleAPI</code> API flag is included such that the user is correctly informed if the <code>window.console</code> API is overridden on the new page.</p>
<h1 id="Other_changes">Conclusions</h1>
<p>As of this writing, this document is a dense summary of the work we did in <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=768096" title="https://bugzilla.mozilla.org/show_bug.cgi?id=768096">bug 768096</a>. We hope this is helpful for you.</p>
<p>If you make changes to the Web Console server please update this document. Thank you!</p>
Revert to this revision