Add basic CDP support to inspector with Runtime and MyExample domains #121

Copilot · 2025-07-22T14:50:48Z

This PR implements basic Chrome DevTools Protocol (CDP) support for the JSAR Runtime inspector, enabling CDP clients (such as Chrome DevTools) to connect via WebSocket and interact with the runtime.

Key Changes

Core CDP Infrastructure

CdpHandler - Main coordinator for CDP message processing with domain registry
CdpMessage - Robust JSON parsing with validation and error handling
CdpResponse - Standardized response builder for success/error/event responses
CdpDomainHandler - Base class for extensible domain implementations

Sample Domain Implementations

CdpRuntimeDomain - Runtime domain with JavaScript runtime methods:
- Runtime.enable - Enable runtime domain
- Runtime.disable - Disable runtime domain
- Runtime.getVersion - Get JavaScript runtime version information
- Runtime.evaluate - Placeholder for script evaluation
CdpMyExampleDomain - Example domain for testing connectivity:
- MyExample.ping - Simple connectivity test returning "pong"
- MyExample.echo - Echo back provided parameters
- MyExample.getInfo - Get domain information and available methods

Enhanced Inspector Integration

Updated TrInspector::onMessage() to use CDP handler instead of simple echo
Enhanced /json/protocol endpoint with complete domain and method descriptions
Proper error handling with JSON-RPC 2.0 compliant error codes
Comprehensive logging for debugging CDP interactions

Testing & Documentation

Complete CDP documentation with usage examples and extensibility guide
Enhanced WebSocket test client with automatic CDP validation
Comprehensive test suite covering success cases, error handling, and edge cases
Updated example clients and documentation

Protocol Compliance

The implementation follows CDP and JSON-RPC 2.0 standards:

// Standard CDP message format
{
  "id": 1,
  "method": "Runtime.enable", 
  "params": {}
}

// Standard CDP response format
{
  "id": 1,
  "result": {}
}

// Standard error format with JSON-RPC codes
{
  "id": 2,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

Extensibility

The design enables easy addition of new domains:

// Create new domain handler
class CdpCustomDomain : public CdpDomainHandler {
  std::string handleMethod(const std::string& method, const CdpMessage& message) override {
    // Implement custom methods
  }
};

// Register in TrInspector::initialize()
cdpHandler_->registerDomain("Custom", std::make_unique<CdpCustomDomain>());

Verification

To test the implementation:

Build with inspector: make darwin INSPECTOR=yes
Run the enhanced test client: node fixtures/inspector-client/inspector_cdp_test_client.js
Check protocol discovery: curl http://localhost:9423/json/protocol
Connect with Chrome DevTools using URLs from: curl http://localhost:9423/json/list

The implementation maintains backward compatibility while adding robust CDP support for modern debugging workflows.

Fixes #120.

Warning

Firewall rules blocked me from connecting to one or more addresses

I tried to connect to the following addresses, but was blocked by firewall rules:

registry.npmmirror.com
- Triggering command: npm install (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to my firewall allow list

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

…amples Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

yorkie

Move cdp files to a separate directory: src/runtime/inspector/, also move the inspector_server and inspector_client to that directory, too.

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot · 2025-07-22T15:23:45Z

Move cdp files to a separate directory: src/runtime/inspector/, also move the inspector_server and inspector_client to that directory, too.

Done! I've moved all CDP and inspector files to src/runtime/inspector/ directory as requested. The reorganization includes:

Created src/runtime/inspector/ directory
Moved all CDP files: cdp_handler.{cpp,hpp}, cdp_myexample_domain.{cpp,hpp}, cdp_runtime_domain.{cpp,hpp}
Moved inspector server/client files: inspector_server.{cpp,hpp}, inspector_client.{cpp,hpp}
Updated all include paths and build system accordingly

Changes committed in ddf322a.

yorkie

Use 2 spaces

yorkie · 2025-07-22T15:31:19Z

src/runtime/inspector/cdp_handler.cpp

@@ -0,0 +1,157 @@
+#include "./cdp_handler.hpp"
+#include "../common/debug.hpp"


Suggested change

#include "../common/debug.hpp"

#include <common/debug.hpp>

yorkie · 2025-07-22T15:32:10Z

src/runtime/inspector/cdp_handler.cpp

+using namespace std;
+
+// CdpMessage implementation
+std::unique_ptr<CdpMessage> CdpMessage::parse(const std::string& json) {


Suggested change

std::unique_ptr<CdpMessage> CdpMessage::parse(const std::string& json) {

unique_ptr<CdpMessage> CdpMessage::parse(const string& json) {

std should be removed if the namespace is using.

Fixed! Removed std:: prefixes where using namespace std; is present. Changed std::unique_ptr to unique_ptr and std::string to string in function implementations. bcef284

… namespace std Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot · 2025-07-22T15:47:56Z

Use 2 spaces

Fixed! Applied 2-space indentation throughout all CDP files using clang-format to match the project's coding standard. bcef284

Warning

Firewall rules blocked me from connecting to one or more addresses

I tried to connect to the following addresses, but was blocked by firewall rules:

registry.npmmirror.com
- Triggering command: npm install (dns block)
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to my firewall allow list

yorkie · 2025-07-22T17:13:29Z

fixtures/inspector-client/inspector_cdp_test_client.js

Please use 2 spaces

Fixed! Applied 2-space indentation throughout the JavaScript test client file. 58e567d

yorkie · 2025-07-22T17:14:13Z

src/runtime/inspector.cpp

+
+  // Register CDP domains
+  cdpHandler_->registerDomain("Runtime", make_unique<CdpRuntimeDomain>(constellation));
+  cdpHandler_->registerDomain("MyExample", make_unique<CdpMyExampleDomain>());


Suggested change

cdpHandler_->registerDomain("MyExample", make_unique<CdpMyExampleDomain>());

cdpHandler_->registerDomain("Example", make_unique<CdpExampleDomain>());

Done! Changed "MyExample" to "Example" for cleaner domain naming. 58e567d

src/runtime/inspector.cpp

…actor protocol definition Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

yorkie

Only support upgrade the connection via /devtools/inspector/:client
Example in fixtures should provide HTML instead of Node.js script, thus we can use browser to test the cdp implementation

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot · 2025-07-23T04:38:00Z

Only support upgrade the connection via /devtools/inspector/:client

Example in fixtures should provide HTML instead of Node.js script, thus we can use browser to test the cdp implementation

Implemented both requirements!

WebSocket path validation: Now only supports upgrades via /devtools/inspector/:client - invalid paths get 404 responses with clear error messages
HTML test client: Replaced the Node.js script with a comprehensive browser-based CDP test client featuring automated test suites, real-time statistics, and an intuitive interface

The enhanced HTML client provides complete CDP testing capabilities including domain-specific tests, custom message sending, and detailed validation - all accessible directly in the browser without Node.js dependencies.

Changes in 508d6fb.

src/runtime/inspector/inspector_client.cpp

yorkie · 2025-07-23T04:58:02Z

fixtures/inspector-client/inspector_websocket_test.html

The latest message should be inserted at the top of the list.

Fixed! The HTML test client now shows the latest messages at the top of the list using insertBefore() instead of appendChild(). This provides better usability as users can immediately see new activity without scrolling. Changes in e955247.

yorkie · 2025-07-23T04:58:45Z

docs/cdp_support.md

Move this document to the docs/internals

Done! Moved the CDP support documentation from docs/cdp_support.md to docs/internals/cdp_support.md to better organize internal documentation. Changes in e955247.

yorkie · 2025-07-23T05:04:34Z

src/runtime/inspector/cdp_myexample_domain.cpp

+  return CdpResponse::success(message.id, result);
+}
+
+void CdpMyExampleDomain::addProtocolDefinition(rapidjson::Value &domains, rapidjson::Document::AllocatorType &allocator)


The domain name, description and commands could be declared in base class CdpDomainHandler thus the CdpHandler::addProtocolDefinitions could serialize the domain to JSON by itself.

At the specific domain handler such as CdpMyExampleDomain, it only needs to set the name, description and register commands only.

Excellent suggestion! Refactored the domain system to be more declarative. Domain handlers now implement simple methods (getDomainName(), getDomainDescription(), getCommands()) instead of manually building JSON. The CdpHandler::addProtocolDefinitions() method automatically serializes domain metadata to JSON, eliminating boilerplate code and improving maintainability. Changes in e955247.

…D support Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

yorkie · 2025-07-23T05:29:49Z

src/runtime/inspector/cdp_handler.cpp

+
+CdpHandler::~CdpHandler() = default;
+
+string CdpHandler::processMessage(const string &message, const string &clientId)


This clientId parameter should be accessed at the each specific-domain message handler.

Done! Modified the CdpDomainHandler base class and all domain implementations to pass the clientId parameter to the handleMethod() function. Domain handlers now receive the client ID extracted from the WebSocket path, enabling client-specific behavior and different handling for "server" vs specific client IDs. Changes committed in 3b478ec.

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot · 2025-07-23T05:42:25Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses

I tried to connect to the following addresses, but was blocked by firewall rules:

registry.npmmirror.com
- Triggering command: npm install (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to my firewall allow list

Initial plan

d8cb4d6

Copilot AI assigned Copilot and yorkie Jul 22, 2025

Copilot started work on behalf of yorkie July 22, 2025 14:50 View session

Copilot AI and others added 2 commits July 22, 2025 15:06

Implement basic CDP support with Runtime and MyExample domains

26890cf

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Complete CDP implementation with tests, documentation and enhanced ex…

cd215f4

…amples Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add basic CDP support to inspector with a sample domain~~ Add basic CDP support to inspector with Runtime and MyExample domains Jul 22, 2025

Copilot AI requested a review from yorkie July 22, 2025 15:11

Copilot finished work on behalf of yorkie July 22, 2025 15:11

yorkie requested changes Jul 22, 2025

View reviewed changes

Copilot started work on behalf of yorkie July 22, 2025 15:12 View session

Move CDP and inspector files to src/runtime/inspector/ directory

ddf322a

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot AI requested a review from yorkie July 22, 2025 15:24

Copilot finished work on behalf of yorkie July 22, 2025 15:24

yorkie requested changes Jul 22, 2025

View reviewed changes

Copilot started work on behalf of yorkie July 22, 2025 15:33 View session

Fix indentation to use 2 spaces and remove std:: prefixes where using…

bcef284

… namespace std Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot finished work on behalf of yorkie July 22, 2025 15:49

Copilot AI requested a review from yorkie July 22, 2025 15:49

yorkie requested changes Jul 22, 2025

View reviewed changes

Copilot started work on behalf of yorkie July 22, 2025 17:16 View session

Address code review comments: fix indentation, rename domain, and ref…

58e567d

…actor protocol definition Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot AI requested a review from yorkie July 22, 2025 17:30

Copilot finished work on behalf of yorkie July 22, 2025 17:30

yorkie requested changes Jul 23, 2025

View reviewed changes

Copilot started work on behalf of yorkie July 23, 2025 04:26 View session

Implement WebSocket path validation and enhanced HTML test client

508d6fb

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot AI requested a review from yorkie July 23, 2025 04:38

Copilot finished work on behalf of yorkie July 23, 2025 04:38

fixup

0d0badd

yorkie requested changes Jul 23, 2025

View reviewed changes

Copilot started work on behalf of yorkie July 23, 2025 05:04 View session

Address code review feedback: refactor domain system and add client I…

e955247

…D support Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot AI requested a review from yorkie July 23, 2025 05:19

Copilot finished work on behalf of yorkie July 23, 2025 05:19

fixup

3932341

yorkie requested changes Jul 23, 2025

View reviewed changes

Copilot started work on behalf of yorkie July 23, 2025 05:30 View session

Pass clientId parameter to domain handlers for client-specific behavior

3b478ec

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot finished work on behalf of yorkie July 23, 2025 05:42

Copilot AI requested a review from yorkie July 23, 2025 05:42

yorkie added 5 commits July 23, 2025 14:54

update

3698b6b

update

32c67df

fix lint errors

b8facaf

fix lint errors

a0bf2ea

fix lint errors

b680295

yorkie approved these changes Jul 23, 2025

View reviewed changes

yorkie marked this pull request as ready for review July 23, 2025 07:14

yorkie merged commit 86fa63f into main Jul 23, 2025
2 checks passed

yorkie deleted the copilot/fix-120 branch July 23, 2025 07:14

Copilot AI mentioned this pull request Aug 4, 2025

Release 0.9.0: Core technical improvements and feature additions #188

Merged

		@@ -0,0 +1,157 @@
		#include "./cdp_handler.hpp"
		#include "../common/debug.hpp"

	std::unique_ptr<CdpMessage> CdpMessage::parse(const std::string& json) {
	unique_ptr<CdpMessage> CdpMessage::parse(const string& json) {

	cdpHandler_->registerDomain("MyExample", make_unique<CdpMyExampleDomain>());
	cdpHandler_->registerDomain("Example", make_unique<CdpExampleDomain>());


		CdpHandler::~CdpHandler() = default;

		string CdpHandler::processMessage(const string &message, const string &clientId)

Add basic CDP support to inspector with Runtime and MyExample domains #121

Add basic CDP support to inspector with Runtime and MyExample domains #121

Uh oh!

Conversation

Copilot AI commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Changes

Core CDP Infrastructure

Sample Domain Implementations

Enhanced Inspector Integration

Testing & Documentation

Protocol Compliance

Extensibility

Verification

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

yorkie left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jul 22, 2025

Uh oh!

yorkie left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yorkie left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jul 23, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jul 23, 2025

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Copilot AI commented Jul 22, 2025 •

edited

Loading

Copilot AI commented Jul 22, 2025 •

edited

Loading