ti-debug

Server-side debugging engines using the WebKit remote debugger.

Prerequisites
-------------

At a minimum this requires node and npm to get started. I am currently
using:

$ node -v
v0.10.1
$ npm -v
1.2.15

For best results, use a recent WebKit-based browser like Google Chrome
or Apple Safari to connect to the ti-debug server.

Installation
------------

git clone https://github.com/dpb587/ti-debug
cd ti-debug/
npm install

Usage
-----

By default bin/ti-debug will start a web server on localhost:9222 for you to connect and get started debugging. When
a new debug session is available the page will redirect to the debugging tools for the session. To see a full list of
configuration options run bin/ti-debug --help.

$3

The DBGp service is enabled by default. Simple run bin/ti-debug, point your browser to localhost:9222, and configure
your DBGp engine to connect to the DBGp client at localhost:9000. If you need to support multiple developers, enable
the DBGp proxy server by adding the --dbgp-proxy option to the command - both browser-based and IDEs are supported.

#### PHP

You'll probably want to ensure the xdebug extension is installed and configured.

See Also:

* xdebug_break

#### Python

You'll probably want to ensure the komodo-remote-debugging
module is installed. Be sure to invoke scripts with the included pydbgp.

See Also:

* dbgp.client.brk

Functionality
-------------

✓ – full support
‡ – partial support
✕ – no support

Architecture
------------

The main purpose of ti-debug is to allow debugging protocols to be accessible through a browser interface. Currently
the WebKit Inspector powers the interface and communications occur:

frontend debugger <-- frontend protocol --> ti-debug <-- debugger protocol --> debugger engine

In the case of DBGp, a client is started to wait for connections from the DBGp server. When a connection is received, it
checks to see if there's a browser waiting to debug and creates a debug session for the browser to connect to. From
there, Inspector-friendly agents handle translating DBGp commands into WebKit
commands. For example:

      inspector > ti-debug: {
                                "method": "Debugger.stepOver",
                                "id": 43
                            }
    ti-debug > dbgp-engine: step_over -i 19
    dbgp-engine > ti-debug: <response ... command="step_over" transaction_id="19" status="break" reason="ok">
                                <xdebug:message filename="file:///home/vagrant/dist/public/wordpress/wp-blog-header.php" lineno="10"></xdebug:message>
                            </response>
    ti-debug > dbgp-engine: stack_get -i 20
    dbgp-engine > ti-debug: <response ... command="stack_get" transaction_id="20">
                                <stack where="require" level="0" type="file" filename="file:///home/vagrant/dist/public/wordpress/wp-blog-header.php" lineno="10"></stack>
                                <stack where="{main}" level="1" type="file" filename="file:///home/vagrant/dist/public/index.php" lineno="1"></stack>
                            </response>
    ti-debug > dbgp-engine: context_names -i 21 -d 0
    dbgp-engine > ti-debug: <response ... command="context_names" transaction_id="21">
                                <context name="Locals" id="0"></context>
                                <context name="Superglobals" id="1"></context>
                            </response>
    ti-debug > dbgp-engine: context_names -i 22 -d 1
    dbgp-engine > ti-debug: <response ... command="context_names" transaction_id="22">
                                <context name="Locals" id="0"></context>
                                <context name="Superglobals" id="1"></context>
                            </response>
      ti-debug > inspector: {
                                "method": "Debugger.paused",
                                "params": {
                                    "callFrames": [{
                                        "callFrameId": "0",
                                        "functionName": "require",
                                        "location": {
                                            "scriptId": "file:///home/vagrant/dist/public/wordpress/wp-blog-header.php",
                                            "lineNumber": 9,
                                            "columnNumber": 0
                                        },
                                        "scopeChain": [{
                                            "type": "local",
                                            "object": {
                                                "type": "object",
                                                "objectId": "|lvl0|ctx0"
                                            }
                                        }, {
                                            "type": "global",
                                            "object": {
                                                "type": "object",
                                                "objectId": "|lvl0|ctx1"
                                            }
                                        }],
                                        "this": null
                                    }, {
                                        "callFrameId": "1",
                                        "functionName": "{main}",
                                        "location": {
                                            "scriptId": "file:///home/vagrant/dist/public/index.php",
                                            "lineNumber": 0,
                                            "columnNumber": 0
                                        },
                                        "scopeChain": [{
                                            "type": "local",
                                            "object": {
                                                "type": "object",
                                                "objectId": "|lvl1|ctx0"
                                            }
                                        }, {
                                            "type": "global",
                                            "object": {
                                                "type": "object",
                                                "objectId": "|lvl1|ctx1"
                                            }
                                        }],
                                        "this": null
                                    }],
                                    "reason": "other"
                                }
                            }

References
----------

* DBGp Protocol
* Zend/PDT Protocol
* V8 Protocol
* WebKit Announcement

Credits
-------

* Created by Danny Berger
* WebKit - front-end (r149292, 2013-04-29 09:24:18)
* npm packages:
commander,
express,
mocha,
node-expat,
node-uuid,
socket.io,
xml2json

License
-------

MIT License