chrome-remote-multiplex

Proxy Server application which allows multiple Chrome DevTools Clients to simultaneously connect to a single Remote Debugger
(ie Chrome Headless) instance.

Google Chrome Headless (or any other Devtools Protocol implementation) only allows one client to control
it at any particular time; this means that if you have an application which uses
chrome-remote-interface
to operate the web page, you cannot debug that web page while it is being controlled by your application.

By using chrome-remote-multiplex you can work
around this restriction, by connecting your app and your debugger(s) to chrome-remote-multiplex and allowing
it to handle the single connection to Chrome Headless.

Getting started

``
google-chrome-canary --headless --remote-debugging-port=9222 --disable-gpu https://chromium.org

npm install -g chrome-remote-multiplex
chrome-remote-multiplex
`

And then open a browser and go to http://localhost:9223.

You can change the ports that chrome-remote-multiplex uses via the command line, this command line has exactly the same effect as above:

`
chrome-remote-multiplex --connect-to=localhost:9222 server-port=9223
`




Managing Lifecycle - automatically closing Chrome Tabs

When instrumenting Chrome Headless, you will often create and close instances - for example, chrome-remote-interface
has this example use of the command line to create a instance (i.e. a tab or window) and then close it again:

`
$ chrome-remote-interface new 'http://example.com'
{
"description": "",
"devtoolsFrontendUrl": "/devtools/inspector.html?ws=localhost:9222/devtools/page/b049bb56-de7d-424c-a331-6ae44cf7ae01",
"id": "b049bb56-de7d-424c-a331-6ae44cf7ae01",
"thumbnailUrl": "/thumb/b049bb56-de7d-424c-a331-6ae44cf7ae01",
"title": "",
"type": "page",
"url": "http://example.com/",
"webSocketDebuggerUrl": "ws://localhost:9222/devtools/page/b049bb56-de7d-424c-a331-6ae44cf7ae01"
}
$ chrome-remote-interface close 'b049bb56-de7d-424c-a331-6ae44cf7ae01'
`

Or as http requests, try this in your browser:
- localhost:9222/json/new -- output the new instance information
- localhost:9222/json/close/{id} -- where {id} is taken from the output of /json/new

If your application is running in a server environment, you obviously need to make sure that you keep track of all of the
instances that you create via the new command and make sure that you close them when they're no longer needed.

While this is straightforward to do in ideal circumstances, in a complex server application it can become tricky to manage
those instances, especially if you want to recover gracefully from application crashes or occasionally want to sneak in
with a separate connection and keep the the instance open while you debug it.

chrome-remote-multiplex adds an automatic close function that
tracks connections and when the last one has disconnected from an instance, the instance itself is closed down. This means
that even if your application crashes, the tab is cleaned up properly because the operating system will close the socket which
will disconnect from the MultiplexServer and then cause the tab to be removed also - this is garbage collection for your browser tabs.

To make a tab automatically close, use the new /json/auto-close/{id} API, for example:

`
$ chrome-remote-interface -p 9223 new 'http://www.google.co.uk'
# Let's say the output from the above command has an "id" of "b049bb56-de7d-424c-a331-6ae44cf7ae01"

$ # use the REST API to make the new tab auto-close
$ wget -O- http://localhost:9223/json/auto-close/b049bb56-de7d-424c-a331-6ae44cf7ae01
`

Now browse to http://localhost:9223 and click on the link to start debugging your new tab; when you close that debugger and
go back to the http://localhost:9223 you will see that the tab you just finished debugging has gone.

Note that if the instance has never been connected to, then it will only be closed once you have connected a DevTools client(s) to it
and the last client has disconnected; if you have previously connected and closed a DevTools client, the instance will close immmediately.




Embedding in your application

You can embed the multiplex proxy server in your own application:

`
var MultiplexServer = require("chrome-remote-multiplex").MultiplexServer;
var ChromeRemoteInterface = require('chrome-remote-interface');

var server = new MultiplexServer({
logging: "debug"
});

server.listen()
.then(() => {
// Use chrome-remote-interface to connect back to the server we've just created
return ChromeRemoteInterface({ port: server.options.listenPort });
});
``

There is a full example in example/embed.js

Contributing

Please feel free to raise issues, pull requests, and questions.