This file documents the CDP sharing mechanism in js-debug. It can be useful for advanced extensions and plugins. The original feature request can be found in #892.
js-debug can be asked to share its CDP connection by running the extension.js-debug.requestCDPProxy command with the debug session ID you wish to connect to. js-debug will respond with an object containing a WebSocket server address in the form { host: string, port: string }. You can see a sample extension that requests this information here.
Note that the server will always be running in the workspace. If you have a UI extension, you may need to forward the port. We also recommend using permessage-deflate on the WebSocket for better performance over remote connections.
The protocol spoken over the WebSocket is, unsurprisingly, CDP. Over the websocket, the sessionId will never be used and will always be ignored. This is because a single js-debug debug session corresponds to exactly one CDP session. Other targets--like iframes, workers, and subprocesses--are represented as separate debug sessions which you can connect to separately.
Additionally, by default, you will not receive any CDP events on the socket. This is because the underlying CDP connection is shared between js-debug and consumers of the mechanism, and we want to avoid doing extra work to send events you don't care about. To listen to events, you can use the JsDebug domain:
js-debug exposes a JsDebug CDP domain for meta-communication. For example, you would call the method JsDebug.subscribe to subscribe to evetns.
- The TypeScript definition of the available methods can be found here.
- The PDL definition can be found here.
These definitions will be published in an npm package soon.