{"_id":"54fa1d5de7a0ba2f0030630e","parentDoc":null,"version":{"_id":"54d5635532d98b0d00384afb","project":"54d53c7b23010a0d001aca0c","__v":10,"forked_from":"54d53c7c23010a0d001aca0f","createdAt":"2015-02-07T00:59:01.934Z","releaseDate":"2015-02-07T00:59:01.934Z","categories":["54d5635632d98b0d00384afc","54d5635632d98b0d00384afd","54d5635632d98b0d00384afe","54d5635632d98b0d00384aff","54d5635632d98b0d00384b00","54d5635632d98b0d00384b01","54d5635632d98b0d00384b02","54d652097e05890d006f153e","54dd1315ca1e5219007e9daa","54e21e2b22de1c230094b147","54e68e62a43fe13500db3879","54fa1d3fe7a0ba2f00306309","551c453a23a1ee190034d19a","551df586e52a0b23000c62b6","551f39be6886f8230055f02a","55a6720751457325000e4d97"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.1.0","version":"0.1"},"__v":66,"project":"54d53c7b23010a0d001aca0c","user":"54cfa8e1a8a4fd0d00b7fd1d","category":{"_id":"54fa1d3fe7a0ba2f00306309","project":"54d53c7b23010a0d001aca0c","version":"54d5635532d98b0d00384afb","__v":5,"pages":["54fa1d54e7a0ba2f0030630c","54fa1d5de7a0ba2f0030630e","54fa1d65961fea210092064f","54fa1dcff63cf9210041c4c0","551f404b6886f8230055f02f"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-03-06T21:33:51.375Z","from_sync":false,"order":6,"slug":"runners-debuggers","title":"Runners & Debuggers"},"updates":["54ff5f46bedb1a2100ecdc1b"],"next":{"pages":[],"description":""},"createdAt":"2015-03-06T21:34:21.679Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"The debugger socket is a plugin that instantiates a [customizable debugger proxy](doc:debugger-proxy) and creates a persistent bi-directional connection between the [debugger](doc:debugger-plugin) and the [running process](doc:runners). \n\nThis article discusses the API of the debug socket plugin and how to use it in your debugger implementation plugin. This is what the overall debugger architecture looks like.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ECu81cnQR7eKBEzS6iX6_debugger%20architecture%20(1).png\",\n        \"debugger architecture (1).png\",\n        \"818\",\n        \"256\",\n        \"#7c6454\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n# Setting Up a Connection\n\nThe socket starts by trying to connect (via TCP) to a port determined by adding one to the debug port that is specified by the runner. If a connection is made the connection process is done and the `connect` event is fired.\n\nIf the port is not open, the socket assumes the proxy process is not yet running. The socket will start a node process that runs the source code provided by your debugger implementation plugin's [getProxySource()](http://cloud9-sdk.readme.io/v0.1/docs/debugger-plugin#getproxysource) function. Once the proxy process is started the socket will once again try to connect to the specified port. This *must* not fail. If it does fail, the `end` event is fired and the socket will attempt to connect, *ad infinitum*. When the connection succeeds the `connect` event is fired.\n\nThe debugger implementation is responsible for calling `connect()` to initiate the connection to the proxy.\n\n```\nsocket.connect();\n\nsocket.once(\"connect\", function(){\n    console.log(\"Connected\");\n});\nsocket.on(\"data\", function(chunk){\n    console.log(\"Received\", chunk);\n});\n```\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"\",\n  \"body\": \"Note that the v8 debugger doesn't listen to the `connect` event but only listens to the `data` event as the `v8` debugger always sends data first on connect. When reconnecting the socket will emit the data event with an empty message.\"\n}\n[/block]\n## Connection Cycle\n\nThere are five events that indicate a change in the connection state; `connect`, `away`, `beforeBack`, `back` and `end`.\n\nThe `away` and `back` events are fired when the connection is temporarily lost and then regained, respectively. There can be a considerable time between the two events and a debugger implementation *must* sync the debugger's state again after this happens (see also the [sync() function](http://cloud9-sdk.readme.io/v0.1/docs/debugger-plugin#attach)).\n\nThe `end` event is fired when a connection failed which implies that any debug session is destroyed. A debugger implementation *must* keep track of all the debug commands it has sent and *must* call the callbacks with an error object in the `end` event.\n\n```\nsocket.on(\"end\", function(){\n    pendingQueue.forEach(function(item) {\n        item.callback(new Error(\"Debug Session Ended\"));\n    });\n});\n```\n\nThe `beforeBack` event fires prior to the `back` event and *must* be used by a debugger to retry those commands that have not yet been confirmed to have been received by the debugger.\n\n```   \nsocket.on(\"beforeBack\", function(){\n    pendingQueue.forEach(function(item) {\n        retry(item);\n    });\n});\n```\n\n## Reconnecting\n\nManaging reconnects to an existing debug process is the primary reason for the socket and proxy. The proxy will survive a user's session; when a user disconnects (even for hours) and later returns, the debugger proxy is still running and the client can connect to it via the connection logic as described above.\n\n## Connection State\n\nThere are three connection states that are available as constants on the socket.\n\n```\nsocket.DISCONNECTED\nsocket.CONNECTED\nsocket.CONNECTING\n```\n\nTest for the current state of the socket using the `attached` property.\n\n```\nsocket.connected == socket.CONNECTING\n```\n\n# Getting a Reference to the Socket\n\nYou'll get a reference to the socket in the [attach() function](http://cloud9-sdk.readme.io/v0.1/docs/debugger-plugin#attach) of your debugger plugin.\n\n```\nvar socket;\nfunction attach(_socket, reconnect, callback) {\n    socket = _socket;\n```\n\nIn this example we store the socket reference in a variable that is local to the plugin. This allows you to reference the socket outside of the `attach()` function as well. You'll most likely need the reference in the `detach()` function.\n\n# Sending Data\n\nSend any `utf-8` data via the socket using the `send()` method.\n\n```\nsocket.send(\"{ json: true }\");\n```","excerpt":"","slug":"debugger-socket","type":"basic","title":"Debugger Socket"}
The debugger socket is a plugin that instantiates a [customizable debugger proxy](doc:debugger-proxy) and creates a persistent bi-directional connection between the [debugger](doc:debugger-plugin) and the [running process](doc:runners). This article discusses the API of the debug socket plugin and how to use it in your debugger implementation plugin. This is what the overall debugger architecture looks like. [block:image] { "images": [ { "image": [ "https://files.readme.io/ECu81cnQR7eKBEzS6iX6_debugger%20architecture%20(1).png", "debugger architecture (1).png", "818", "256", "#7c6454", "" ] } ] } [/block] # Setting Up a Connection The socket starts by trying to connect (via TCP) to a port determined by adding one to the debug port that is specified by the runner. If a connection is made the connection process is done and the `connect` event is fired. If the port is not open, the socket assumes the proxy process is not yet running. The socket will start a node process that runs the source code provided by your debugger implementation plugin's [getProxySource()](http://cloud9-sdk.readme.io/v0.1/docs/debugger-plugin#getproxysource) function. Once the proxy process is started the socket will once again try to connect to the specified port. This *must* not fail. If it does fail, the `end` event is fired and the socket will attempt to connect, *ad infinitum*. When the connection succeeds the `connect` event is fired. The debugger implementation is responsible for calling `connect()` to initiate the connection to the proxy. ``` socket.connect(); socket.once("connect", function(){ console.log("Connected"); }); socket.on("data", function(chunk){ console.log("Received", chunk); }); ``` [block:callout] { "type": "warning", "title": "", "body": "Note that the v8 debugger doesn't listen to the `connect` event but only listens to the `data` event as the `v8` debugger always sends data first on connect. When reconnecting the socket will emit the data event with an empty message." } [/block] ## Connection Cycle There are five events that indicate a change in the connection state; `connect`, `away`, `beforeBack`, `back` and `end`. The `away` and `back` events are fired when the connection is temporarily lost and then regained, respectively. There can be a considerable time between the two events and a debugger implementation *must* sync the debugger's state again after this happens (see also the [sync() function](http://cloud9-sdk.readme.io/v0.1/docs/debugger-plugin#attach)). The `end` event is fired when a connection failed which implies that any debug session is destroyed. A debugger implementation *must* keep track of all the debug commands it has sent and *must* call the callbacks with an error object in the `end` event. ``` socket.on("end", function(){ pendingQueue.forEach(function(item) { item.callback(new Error("Debug Session Ended")); }); }); ``` The `beforeBack` event fires prior to the `back` event and *must* be used by a debugger to retry those commands that have not yet been confirmed to have been received by the debugger. ``` socket.on("beforeBack", function(){ pendingQueue.forEach(function(item) { retry(item); }); }); ``` ## Reconnecting Managing reconnects to an existing debug process is the primary reason for the socket and proxy. The proxy will survive a user's session; when a user disconnects (even for hours) and later returns, the debugger proxy is still running and the client can connect to it via the connection logic as described above. ## Connection State There are three connection states that are available as constants on the socket. ``` socket.DISCONNECTED socket.CONNECTED socket.CONNECTING ``` Test for the current state of the socket using the `attached` property. ``` socket.connected == socket.CONNECTING ``` # Getting a Reference to the Socket You'll get a reference to the socket in the [attach() function](http://cloud9-sdk.readme.io/v0.1/docs/debugger-plugin#attach) of your debugger plugin. ``` var socket; function attach(_socket, reconnect, callback) { socket = _socket; ``` In this example we store the socket reference in a variable that is local to the plugin. This allows you to reference the socket outside of the `attach()` function as well. You'll most likely need the reference in the `detach()` function. # Sending Data Send any `utf-8` data via the socket using the `send()` method. ``` socket.send("{ json: true }"); ```