index.rst (20044B)
1 ==================== 2 Web Console remoting 3 ==================== 4 5 Introduction 6 ************ 7 8 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 <https://wiki.mozilla.org/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. 9 10 To better understand the architecture of the Web Console we recommend learning about the `debugger architecture <https://wiki.mozilla.org/Debugger_Architecture>`_. 11 12 13 The ``WebConsoleActor`` and the ``WebConsoleClient`` 14 **************************************************** 15 16 The ``WebConsoleActor`` lives in `dbg-webconsole-actors.js <http://mxr.mozilla.org/mozilla-central/source/toolkit/devtools/webconsole/dbg-webconsole-actors.js>`_, in the `toolkit/devtools/webconsole <http://mxr.mozilla.org/mozilla-central/source/toolkit/devtools/webconsole/>`_ folder. 17 18 The ``WebConsoleClient`` lives in `WebConsoleClient.jsm <http://mxr.mozilla.org/mozilla-central/source/toolkit/devtools/webconsole/WebConsoleClient.jsm/>`_ (in `toolkit/devtools/webconsole <http://mxr.mozilla.org/mozilla-central/source/toolkit/devtools/webconsole/>`_) and it is used by the Web Console when working with the Web Console actor. 19 20 To see how the debugger is used in the Web Console code, look in `browser/devtools/webconsole/webconsole.js <http://mxr.mozilla.org/mozilla-central/source/browser/devtools/webconsole/webconsole.js/>`_, and search for ``WebConsoleConnectionProxy``. 21 22 The new Web Console actors are: 23 24 - The ``WebConsoleActor`` allows JS evaluation, autocomplete, start/stop listeners, etc. 25 - The ``NetworkEventActor`` is used for each new network request. The client can request further network event details - like response body or request headers. 26 27 28 To attach to the ``WebConsoleActor``, follow these steps: 29 30 .. code-block:: javascript 31 32 connectToServer() // the usual 33 listTabs() 34 pickTheTabYouWant() 35 debuggerClient.attachConsole(tab.consoleActor, listeners, onAttachConsole) 36 37 38 The ``listeners`` argument is an array which specifies listeners you want to start in the web console. These can be: page errors, ``window.console`` API messages, network activity, and file activity. For example: 39 40 .. code-block:: javascript 41 42 ["PageError", "ConsoleAPI", "FileActivity"] 43 44 45 .. note:: 46 The Web Console actor does not start any listeners by default. The client has the option to start each listener when needed. This approach allows for lower resource usage on the server - this is a potential issue if the server runs on devices with fewer resources. 47 48 49 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. 50 51 Protocol packets look as follows: 52 53 .. code-block:: javascript 54 55 { 56 "to": "root", 57 "type": "listTabs" 58 } 59 { 60 "from": "root", 61 "consoleActor": "conn0.console9", 62 "selected": 2, 63 "tabs": [ 64 { 65 "actor": "conn0.tab2", 66 "consoleActor": "conn0.console7", 67 "title": "", 68 "url": "https://tbpl.mozilla.org/?tree=Fx-Team" 69 }, 70 // ... 71 ] 72 } 73 74 75 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 the other events from all of the tabs and windows, including chrome errors and network events. This actor is used for the Browser Console implementation and for debugging remote Firefox/B2G instances. 76 77 78 ``startListeners(listeners, onResponse)`` 79 ----------------------------------------- 80 81 The new ``startListeners`` packet: 82 83 .. code-block:: javascript 84 85 { 86 "to": "conn0.console9", 87 "type": "startListeners", 88 "listeners": [ 89 "PageError", 90 "ConsoleAPI", 91 "FileActivity" 92 ] 93 } 94 95 The reply is: 96 97 .. code-block:: javascript 98 99 { 100 "startedListeners": [ 101 "PageError", 102 "ConsoleAPI", 103 "FileActivity" 104 ], 105 "from": "conn0.console9" 106 } 107 108 109 The reply tells which listeners were started. 110 111 112 Tab navigation 113 -------------- 114 115 To listen to the tab navigation events you also need to attach to the tab actor for the given tab. The ``tabNavigated`` notification comes from tab actors. 116 117 When page navigation starts the following packet is sent from the tab actor: 118 119 .. code-block:: 120 121 { 122 "from": tabActor, 123 "type": "tabNavigated", 124 "state": "start", 125 "url": newURL, 126 } 127 128 129 When navigation stops the following packet is sent: 130 131 .. code-block:: 132 133 { 134 "from": tabActor, 135 "type": "tabNavigated", 136 "state": "stop", 137 "url": newURL, 138 "title": newTitle, 139 } 140 141 142 ``getCachedMessages(types, onResponse)`` 143 ---------------------------------------- 144 145 The ``webConsoleClient.getCachedMessages(types, onResponse)`` method sends the following packet to the server: 146 147 .. code-block:: json 148 149 { 150 "to": "conn0.console9", 151 "type": "getCachedMessages", 152 "messageTypes": [ 153 "PageError", 154 "ConsoleAPI" 155 ] 156 } 157 158 159 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: 160 161 .. code-block:: 162 163 { 164 "messages": [ ... ], 165 "from": "conn0.console9" 166 } 167 168 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. 169 170 Page errors 171 *********** 172 173 Page errors come from the ``nsIConsoleService``. Each allowed page error is an ``nsIScriptError`` object. 174 175 The ``pageError`` packet is: 176 177 .. code-block:: json 178 179 { 180 "from": "conn0.console9", 181 "type": "pageError", 182 "pageError": { 183 "errorMessage": "ReferenceError: foo is not defined", 184 "sourceName": "http://localhost/~mihai/mozilla/test.js", 185 "lineText": "", 186 "lineNumber": 6, 187 "columnNumber": 0, 188 "category": "content javascript", 189 "timeStamp": 1347294508210, 190 "error": false, 191 "warning": false, 192 "exception": true, 193 "strict": false, 194 "private": false, 195 } 196 } 197 198 199 The packet is similar to ``nsIScriptError`` - for simplicity. We only removed several unneeded properties and changed how flags work. 200 201 The ``private`` flag tells if the error comes from a private window/tab. 202 203 The ``errorMessage`` and ``lineText`` properties can be long string actor grips if the string is very long. 204 205 206 Console API messages 207 ******************** 208 209 The `window.console API <https://developer.mozilla.org/en-US/docs/Web/API/console>`_ calls send internal messages throughout Gecko which allow us to do whatever we want for each call. The Web Console actor sends these messages to the remote debugging client. 210 211 We use the ``ObjectActor`` from `dbg-script-actors.js <https://mxr.mozilla.org/mozilla-central/source/toolkit/devtools/debugger/server/dbg-script-actors.js>`_ without a ``ThreadActor``, to avoid slowing down the page scripts - the debugger deoptimizes JavaScript execution in the target page. The `lifetime of object actors <https://wiki.mozilla.org/Remote_Debugging_Protocol#Grip_Lifetimes>`_ in the Web Console is different than the lifetime of these objects in the debugger - which is usually per pause or per thread. The Web Console manages the lifetime of ``ObjectActors`` manually. 212 213 214 Console API messages come through the ``nsIObserverService`` - the console object implementation lives in `dom/base/ConsoleAPI.js <http://mxr.mozilla.org/mozilla-central/source/dom/base/ConsoleAPI.js>`_. 215 216 For each console message we receive in the server, we send the following ``consoleAPICall`` packet to the client: 217 218 .. code-block:: json 219 220 { 221 "from": "conn0.console9", 222 "type": "consoleAPICall", 223 "message": { 224 "level": "error", 225 "filename": "http://localhost/~mihai/mozilla/test.html", 226 "lineNumber": 149, 227 "functionName": "", 228 "timeStamp": 1347302713771, 229 "private": false, 230 "arguments": [ 231 "error omg aloha ", 232 { 233 "type": "object", 234 "className": "HTMLBodyElement", 235 "actor": "conn0.consoleObj20" 236 }, 237 " 960 739 3.141592653589793 %a", 238 "zuzu", 239 { "type": "null" }, 240 { "type": "undefined" } 241 ] 242 } 243 } 244 245 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 ``ObjectActor`` instances for each object passed as an argument - and, lastly, we remove some unneeded properties (like window IDs). In the case of long strings we use the ``LongStringActor``. The Web Console can then inspect the arguments. 246 247 The ``private`` flag tells if the console API call comes from a private window/tab. 248 249 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. To see these differences please look in the Console API implementation: `dom/base/ConsoleAPI.js <http://mxr.mozilla.org/mozilla-central/source/dom/base/ConsoleAPI.js>`_. 250 251 252 JavaScript evaluation 253 --------------------- 254 255 The ``evaluateJS`` request and response packets 256 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 257 258 The Web Console client provides the ``evaluateJS(requestId, string, onResponse)`` method which sends the following packet: 259 260 .. code-block:: json 261 262 { 263 "to": "conn0.console9", 264 "type": "evaluateJS", 265 "text": "document", 266 "bindObjectActor": null, 267 "frameActor": null, 268 "url": null, 269 "selectedNodeActor": null, 270 } 271 272 273 The ``bindObjectActor`` property is an optional ``ObjectActor`` ID that points to a ``Debugger.Object``. This option allows you to bind ``_self`` to the ``Debugger.Object`` of the given object actor, during string evaluation. See ``evalInGlobalWithBindings()`` for information about bindings. 274 275 .. note:: 276 The variable view needs to update objects and it does so by binding ``_self`` to the ``Debugger.Object`` of the ``ObjectActor`` that is being viewed. As such, variable view sends strings like these for evaluation: 277 278 .. code-block:: javascript 279 280 _self["prop"] = value; 281 282 The ``frameActor`` property is an optional ``FrameActor`` ID. The FA holds a reference to a ``Debugger.Frame``. This option allows you to evaluate the string in the frame of the given FA. 283 284 The ``url`` property is an optional URL to evaluate the script as. The default source URL for evaluation is "debugger eval code". 285 286 The ``selectedNodeActor`` property is an optional ``NodeActor`` ID, which is used to indicate which node is currently selected in the Inspector, if any. This ``NodeActor`` can then be referred to by the ``$0`` JSTerm helper. 287 288 The response packet: 289 290 .. code-block:: json 291 292 { 293 "from": "conn0.console9", 294 "input": "document", 295 "result": { 296 "type": "object", 297 "className": "HTMLDocument", 298 "actor": "conn0.consoleObj20" 299 "extensible": true, 300 "frozen": false, 301 "sealed": false 302 }, 303 "timestamp": 1347306273605, 304 "exception": null, 305 "exceptionMessage": null, 306 "helperResult": null 307 } 308 309 310 - ``exception`` holds the JSON-ification of the exception thrown during evaluation. 311 - ``exceptionMessage`` holds the ``exception.toString()`` result. 312 - ``result`` has the result ``ObjectActor`` instance. 313 - ``helperResult`` is anything that might come from a JSTerm helper result, JSON stuff (not content objects!). 314 315 316 Autocomplete and more 317 --------------------- 318 319 The ``autocomplete`` request packet: 320 321 .. code-block:: json 322 323 { 324 "to": "conn0.console9", 325 "type": "autocomplete", 326 "text": "d", 327 "cursor": 1 328 } 329 330 331 The response packet: 332 333 .. code-block:: json 334 335 { 336 "from": "conn0.console9", 337 "matches": [ 338 "decodeURI", 339 "decodeURIComponent", 340 "defaultStatus", 341 "devicePixelRatio", 342 "disableExternalCapture", 343 "dispatchEvent", 344 "doMyXHR", 345 "document", 346 "dump" 347 ], 348 "matchProp": "d" 349 } 350 351 352 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 <https://bugzilla.mozilla.org/show_bug.cgi?id=717611>`_. 353 An alternate version is ``clearMessagesCacheAsync``, which does exactly the same thing but resolves when the cache was actually cleared. 354 355 356 Network logging 357 *************** 358 359 The ``networkEvent`` packet 360 --------------------------- 361 362 Whenever a new network request starts being logged the ``networkEvent`` packet is sent: 363 364 .. code-block:: json 365 366 { 367 "from": "conn0.console10", 368 "type": "networkEvent", 369 "eventActor": { 370 "actor": "conn0.netEvent14", 371 "startedDateTime": "2012-09-17T19:50:03.699Z", 372 "url": "http://localhost/~mihai/mozilla/test2.css", 373 "method": "GET" 374 "isXHR": false, 375 "private": false 376 } 377 } 378 379 380 This packet is used to inform the Web Console of a new network event. For each request a new ``NetworkEventActor`` instance is created. The ``isXHR`` flag indicates if the request was initiated via an `XMLHttpRequest <https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest>`_ instance, that is: the ``nsIHttpChannel``'s notification is of an ``nsIXMLHttpRequest`` interface. 381 382 The ``private`` flag tells if the network request comes from a private window/tab. 383 384 385 The ``NetworkEventActor`` 386 ------------------------- 387 388 The new network event actor stores further request and response information. 389 390 The ``networkEventUpdate`` packet 391 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 392 393 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: 394 395 .. code-block:: 396 397 { 398 "from": "conn0.netEvent14", 399 "type": "networkEventUpdate", 400 "updateType": "requestHeaders", 401 "headers": 10, 402 "headersSize": 425 403 }, 404 { 405 "from": "conn0.netEvent14", 406 "type": "networkEventUpdate", 407 "updateType": "requestCookies", 408 "cookies": 0 409 }, 410 { 411 "from": "conn0.netEvent14", 412 "type": "networkEventUpdate", 413 "updateType": "requestPostData", 414 "dataSize": 1024, 415 "discardRequestBody": false 416 }, 417 { 418 "from": "conn0.netEvent14", 419 "type": "networkEventUpdate", 420 "updateType": "responseStart", 421 "response": { 422 "httpVersion": "HTTP/1.1", 423 "status": "304", 424 "statusText": "Not Modified", 425 "headersSize": 194, 426 "discardResponseBody": true 427 } 428 }, 429 { 430 "from": "conn0.netEvent14", 431 "type": "networkEventUpdate", 432 "updateType": "eventTimings", 433 "totalTime": 1 434 }, 435 { 436 "from": "conn0.netEvent14", 437 "type": "networkEventUpdate", 438 "updateType": "responseHeaders", 439 "headers": 6, 440 "headersSize": 194 441 }, 442 { 443 "from": "conn0.netEvent14", 444 "type": "networkEventUpdate", 445 "updateType": "responseCookies", 446 "cookies": 0 447 }, 448 { 449 "from": "conn0.netEvent14", 450 "type": "networkEventUpdate", 451 "updateType": "responseContent", 452 "mimeType": "text/css", 453 "contentSize": 0, 454 "discardResponseBody": true 455 } 456 457 458 Actual headers, cookies, and bodies are not sent. 459 460 461 The ``getRequestHeaders`` and other packets 462 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 463 464 To get more details about a network event you can use the following packet requests (and replies). 465 466 The ``getRequestHeaders`` packet: 467 468 .. code-block:: 469 470 { 471 "to": "conn0.netEvent15", 472 "type": "getRequestHeaders" 473 } 474 { 475 "from": "conn0.netEvent15", 476 "headers": [ 477 { 478 "name": "Host", 479 "value": "localhost" 480 }, ... 481 ], 482 "headersSize": 350 483 } 484 485 486 The ``getRequestCookies`` packet: 487 488 .. code-block:: json 489 490 { 491 "to": "conn0.netEvent15", 492 "type": "getRequestCookies" 493 } 494 { 495 "from": "conn0.netEvent15", 496 "cookies": [] 497 } 498 499 500 The ``getResponseHeaders`` packet: 501 502 .. code-block:: 503 504 { 505 "to": "conn0.netEvent15", 506 "type": "getResponseHeaders" 507 } 508 { 509 "from": "conn0.netEvent15", 510 "headers": [ 511 { 512 "name": "Date", 513 "value": "Mon, 17 Sep 2012 20:05:27 GMT" 514 }, ... 515 ], 516 "headersSize": 320 517 } 518 519 520 The ``getResponseCookies`` packet: 521 522 .. code-block:: json 523 524 { 525 "to": "conn0.netEvent15", 526 "type": "getResponseCookies" 527 } 528 { 529 "from": "conn0.netEvent15", 530 "cookies": [] 531 } 532 533 534 .. note:: 535 For all of the header and cookie values in the above packets we use `LongStringActor grips <https://wiki.mozilla.org/Remote_Debugging_Protocol#Objects>`_ when the value is very long. This helps us avoid using too much of the network bandwidth. 536 537 538 The ``getRequestPostData`` packet: 539 540 .. code-block:: 541 542 { 543 "to": "conn0.netEvent15", 544 "type": "getRequestPostData" 545 } 546 { 547 "from": "conn0.netEvent15", 548 "postData": { text: "foobar" }, 549 "postDataDiscarded": false 550 } 551 552 The ``getResponseContent`` packet: 553 554 .. code-block:: json 555 556 { 557 "to": "conn0.netEvent15", 558 "type": "getResponseContent" 559 } 560 { 561 "from": "conn0.netEvent15", 562 "content": { 563 "mimeType": "text/css", 564 "text": "\n@import \"test.css\";\n\n.foobar { color: green }\n\n" 565 }, 566 "contentDiscarded": false 567 } 568 569 570 The request and response content text value is most commonly sent using a ``LongStringActor`` grip. For very short request/response bodies we send the raw text. 571 572 .. note:: 573 For non-text response types we send the content in base64 encoding (again, most likely a ``LongStringActor`` grip). To tell the difference just check if ``response.content.encoding == "base64"``. 574 575 576 The ``getEventTimings`` packet: 577 578 .. code-block:: json 579 580 { 581 "to": "conn0.netEvent15", 582 "type": "getEventTimings" 583 } 584 { 585 "from": "conn0.netEvent15", 586 "timings": { 587 "blocked": 0, 588 "dns": 0, 589 "connect": 0, 590 "send": 0, 591 "wait": 16, 592 "receive": 0 593 }, 594 "totalTime": 16 595 } 596 597 598 The ``fileActivity`` packet 599 --------------------------- 600 601 When a file load is observed the following ``fileActivity`` packet is sent to the client: 602 603 .. code-block:: json 604 605 { 606 "from": "conn0.console9", 607 "type": "fileActivity", 608 "uri": "file:///home/mihai/public_html/mozilla/test2.css" 609 } 610 611 612 History 613 ******* 614 615 Protocol changes by Firefox version: 616 617 - Firefox 18: initial version. 618 - Firefox 19: `bug <https://bugzilla.mozilla.org/show_bug.cgi?id=787981>`_ - added ``LongStringActor`` usage in several places. 619 - Firefox 20: `bug <https://bugzilla.mozilla.org/show_bug.cgi?id=792062>`_ - removed ``locationChanged`` packet and updated the ``tabNavigated`` packet for tab actors. 620 - Firefox 23: `bug <https://bugzilla.mozilla.org/show_bug.cgi?id=783499>`_ - removed the ``WebConsoleObjectActor``. Now the Web Console uses the JavaScript debugger API and the ``ObjectActor``. 621 - Firefox 23: added the ``bindObjectActor`` and ``frameActor`` options to the ``evaluateJS`` request packet. 622 - Firefox 24: new ``private`` flags for the console actor notifications, `bug <https://bugzilla.mozilla.org/show_bug.cgi?id=874061>`_. Also added the ``lastPrivateContextExited`` notification for the global console actor. 623 - Firefox 24: new ``isXHR`` flag for the ``networkEvent`` notification, `bug <https://bugzilla.mozilla.org/show_bug.cgi?id=859046>`_. 624 - Firefox 24: removed the ``message`` property from the ``pageError`` packet notification, `bug <https://bugzilla.mozilla.org/show_bug.cgi?id=877773>`_. The ``lineText`` and ``errorMessage`` properties can be long string actors now. 625 - Firefox 25: added the ``url`` option to the ``evaluateJS`` request packet. 626 627 628 Conclusions 629 *********** 630 631 As of this writing, this document is a dense summary of the work we did in `bug 768096 <https://bugzilla.mozilla.org/show_bug.cgi?id=768096>`_ and subsequent changes. We try to keep this document up-to-date. We hope this is helpful for you. 632 633 If you make changes to the Web Console server please update this document. Thank you!