feat: Enhance WebSocket transport with advanced features

[yashksaini-coder]

Fixes: #938

Added WebSocket Transport Improvements

• Added WebSocketConnectionManager for better connection handling and lifecycle management
• Implemented WebSocketListenerConfig for flexible transport configuration
• Added SOCKS proxy support for WebSocket connections
• Enhanced connection tracking and statistics
• Improved error handling and connection cleanup

This PR improves the WebSocket transport implementation with better connection management,
configuration options, and monitoring capabilities.

[yashksaini-coder]

@acul71 I would like you to take the point on this PR I'm occupied next week, so I may not be able to put more work into it. I've raised the PR and implemented the WebSocket implementation.

[seetadev]

@yashksaini-coder : Great, thank you so much for sharing. Appreciate your wonderful efforts.

@acul71 will collaborate with you to get this PR to a production stage.

We need this PR ready for final review + merge before the next py-libp2p release in 2+ weeks.

@yashksaini-coder : Wish to share that I re-ran the CI/CD pipeline and found important issues and tests failing.

Please collaborate with @acul71 and @bomanaps to get this resolved.

[seetadev]

@yashksaini-coder : Thank you so much to you and @acul71 for your efforts. Appreciate it.

It took me sometime to reach this PR as there were close to 12+ PRs in the review queue. Did re-run the CI/CD pipeline and important test cases are passing. Did notice some good number of test cases are failing too.

Wish if you could collaborate with @acul71 and arrive at a good conclusion on this PR soon.

Lets try and complete this before the next release of py-libp2p planned in 1.5+ weeks.

[acul71]

@seetadev @yashksaini-coder

PR Review: #964 - Enhance WebSocket transport with advanced features

Reviewer: acul71
Date: October 16, 2025
PR: feat: Enhance WebSocket transport with advanced features #964
Author: @yashksaini-coder
Related Issue: #938 - WebSocket Transport Missing Features

Executive Summary

This PR attempts to enhance the WebSocket transport implementation with advanced features including connection management, SOCKS proxy support, and improved configuration options. However, the implementation has several critical issues that need to be addressed before it can be merged.

Current State Analysis

Existing WebSocket Transport Implementation

The current WebSocket transport in py-libp2p includes:

• Basic WebSocket transport with trio-websocket backend
• Support for both WS and WSS protocols
• TLS configuration support for WSS connections
• Multiaddr parsing for WebSocket addresses
• Integration with libp2p host and peer discovery
• Basic connection management and stream handling

Missing Features (Issue #938)

Based on the release notes and issue #938, the missing features include:

• Advanced features like proxy support
• Interop testing capabilities
• Production examples
• Connection pooling and management
• Enhanced error handling and monitoring
• SOCKS proxy support

PR Analysis

✅ Strengths

1. Comprehensive Feature Set: The PR successfully implements multiple missing features:

   • WebsocketConfig: New configuration dataclass with validation
   • WebsocketListenerConfig: Flexible listener configuration
   • SOCKSConnectionManager: Full SOCKS4/5 proxy support
   • Enhanced connection tracking: Statistics and monitoring
   • Improved error handling: Custom exception classes
   • Production-ready features: Connection limits, timeouts, flow control

2. Well-Structured Implementation: The code is well-organized with:

   • Clear separation of concerns
   • Proper dataclass usage for configuration
   • Comprehensive error handling with custom exceptions
   • Statistics tracking and monitoring
   • Optional dependency handling

3. Production Focus: The implementation includes production-ready features:

   • Connection limits and rate limiting
   • Proper error handling and cleanup
   • Statistics tracking and monitoring
   • Configuration validation
   • SOCKS proxy support
   • Enhanced connection management

4. Backward Compatibility: The implementation maintains backward compatibility while adding new features.

✅ Implementation Quality

1. Configuration Management:

   • WebsocketConfig dataclass with validation
   • WebsocketListenerConfig for listener-specific settings
   • Proper validation of configuration parameters

2. Connection Management:

   • Connection tracking with locks
   • Statistics collection
   • Proper cleanup and error handling

3. SOCKS Proxy Support:

   • Full SOCKS4/5 implementation
   • Authentication support
   • Proper error handling for missing dependencies

4. Enhanced Connection Class:

   • Statistics tracking with WebSocketStats
   • Custom exception hierarchy
   • Improved error handling and recovery
   • Activity monitoring

⚠️ Areas for Improvement

1. Connection Upgrading: The implementation has TODO comments for proper connection upgrading:

   # TODO: Implement proper connection upgrading

2. Keepalive Implementation: The keepalive functionality is partially implemented but not fully integrated.

3. Error Handling: While comprehensive, some error cases could be handled more gracefully.

4. Testing: While tests exist, they could be more comprehensive for the new features.

🔍 Technical Analysis

The implementation demonstrates good architectural design with comprehensive configuration management, SOCKS proxy support, and enhanced connection tracking. However, critical integration issues prevent the WebSocket transport from working properly with the libp2p security layer.

Key Issues Identified

1. Connection Upgrade Failures: WebSocket connections fail during security upgrade phase
2. Listener Address Issues: WebSocket listeners not properly exposing listen addresses
3. Integration Problems: WebSocket transport not properly integrated with libp2p security layer
4. Missing Test Coverage: New features lack comprehensive testing
5. JavaScript Interop Issues: JS libp2p dependencies not properly configured

Conclusion

The PR implements comprehensive WebSocket transport enhancements, but critical bugs prevent the implementation from working properly. While the new features are well-structured and address the requirements from issue #938, the WebSocket transport has fundamental issues that prevent successful connections.

Key Achievements:

• ✅ WebsocketConfig: Comprehensive configuration management with validation
• ✅ SOCKS Proxy Support: Full SOCKS4/5 implementation with authentication
• ✅ Enhanced Connection Management: Statistics tracking, monitoring, and proper cleanup
• ✅ Production Features: Connection limits, timeouts, flow control, error handling
• ✅ Backward Compatibility: Maintains existing API while adding new features

Critical Issues:

• ❌ Connection Upgrade Failures: WebSocket connections fail during security upgrade
• ❌ Listener Address Issues: WebSocket listeners not properly exposing addresses
• ❌ Integration Problems: WebSocket transport not properly integrated with libp2p security layer
• ❌ Missing Test Coverage: New features lack comprehensive testing

Recommendation: Request for Fixes - The implementation needs critical bug fixes before it can be merged.

Required Changes Before Merge

1. Fix Connection Upgrade Issues: Resolve WebSocket security upgrade failures
2. Fix Listener Address Exposure: Ensure WebSocket listeners properly expose listen addresses
3. Fix libp2p Integration: Properly integrate WebSocket transport with libp2p security layer
4. Add Comprehensive Testing: Test all new features (WebsocketConfig, SOCKS proxy, statistics)
5. Fix JavaScript Interop: Resolve JS libp2p dependency issues
6. Complete Implementation: Remove TODO comments and finish incomplete features

Next Steps

1. Fix Critical Bugs: Resolve connection upgrade and listener address issues
2. Add Missing Tests: Test WebsocketConfig, SOCKS proxy, and statistics features
3. Fix Integration: Ensure WebSocket transport works with libp2p security layer
4. Fix JavaScript Dependencies: Resolve JS libp2p interop issues
5. Complete Implementation: Finish incomplete features and remove TODO comments

---

Status: ❌ Implementation Broken - Critical bugs prevent WebSocket connections from working
Priority: 🔴 High - Critical for next release

Critical Finding: Test Failures and Missing Coverage

❌ Failing Tests Analysis

The PR includes comprehensive WebSocket tests, but 6 out of 6 WebSocket P2P tests are failing:

1. test_websocket_p2p_plaintext - Connection upgrade failure

   • Issue: failed to upgrade security for peer at /ip4/127.0.0.1/tcp/0/ws
   • Root Cause: WebSocket connection establishes but security upgrade fails
   • Error: SwarmException: unable to connect to peer, no addresses established a successful connection

2. test_websocket_p2p_noise - No WebSocket address found

   • Issue: AssertionError: No WebSocket listen address found
   • Root Cause: WebSocket listener not properly exposing listen addresses
   • Error: assert None is not None

3. test_websocket_p2p_libp2p_ping - Connection upgrade failure

   • Issue: Same as plaintext test - security upgrade fails
   • Root Cause: WebSocket transport not properly integrated with libp2p security layer

4. test_websocket_p2p_multiple_streams - Connection upgrade failure

   • Issue: Same connection upgrade pattern
   • Root Cause: Multiple streams fail due to underlying connection issues

5. test_websocket_p2p_connection_state - Connection upgrade failure

   • Issue: Same connection upgrade pattern
   • Root Cause: Connection state tracking fails due to connection issues

6. test_ping_with_js_node - JavaScript interop failure

   • Issue: SyntaxError: The requested module '@chainsafe/libp2p-noise' does not provide an export named 'noise'
   • Root Cause: JavaScript dependencies not properly configured
   • Error: JS libp2p node fails to start due to import issues

❌ Missing Test Coverage for New Features

• WebsocketConfig: No tests found
• WebsocketListenerConfig: No tests found
• SOCKSConnectionManager: No tests found
• Connection Statistics: No tests found
• Enhanced Connection Management: No tests found

Recommendation: Request for Fixes - The implementation has critical bugs preventing WebSocket connections from working properly.

[acul71]

@asmit27rai Thanks for the commit.
How is the interop test architecture, or an example how to use ?
I've been trying to test this, I see that package.json is missing (only package-lock.json)

Is this summary correct?
Can you tell me about the HTTP libp2p streams how it works (supposing the summary is correct)

Summary: Python Server vs JavaScript Server

✅ JavaScript Server

• Type: HTTP server (responds to HTTP POST requests)
• Protocol: HTTP
• Usage: node js_websocket_node.js server 8002 false 30000
• Test: Works with curl and HTTP clients

❌ Python Server

• Type: libp2p stream server (expects libp2p protocol)
• Protocol: libp2p streams (not HTTP)
• Usage: python py_websocket_node.py server 8001 false 30
• Test: Does NOT respond to HTTP requests

The Problem

The interop tests have a protocol mismatch:

• JavaScript server uses HTTP
• Python server uses libp2p streams
• The test_js_to_py.js tries to make HTTP requests to the Python server, which fails

What Actually Works

1. Python → JavaScript: ✅ Works (Python makes HTTP requests to JS server)
2. JavaScript → Python: ❌ Fails (JS makes HTTP requests to Python libp2p server)
3. Bidirectional: ✅ Works (Python acts as client, JS as server)

##########################

I'll show you the actual working sections with real logs. Let me run the tests that actually work and capture their output:

[1 tool called]

1. JavaScript Server Working (HTTP-based)

[3 tools called]

2. Python Client → JavaScript Server Communication

[4 tools called]

3. Bidirectional Test (Most Comprehensive)

[2 tools called]

4. JavaScript Client Test (Shows the Limitation)

[2 tools called]

📋 Summary: What Actually Works - Real Logs

✅ 1. JavaScript Server (HTTP-based)

=== Testing JavaScript Server with HTTP requests ===
Echo: Hello from curl
=== Testing with different message ===
Echo: Test message 2

Status: ✅ WORKING - Responds to HTTP POST requests with echo

✅ 2. Python Client → JavaScript Server

=== Python Client to JavaScript Server Test ===
✅ Python to JS test completed successfully

Status: ✅ WORKING - Python makes HTTP requests to JS server

✅ 3. Bidirectional Test (Most Comprehensive)

=== Bidirectional Communication Test ===
2025-10-16 15:43:10,658 [INFO] [py_node.py_websocket_node] libp2p not available; using mock node behavior
2025-10-16 15:43:10,694 [DEBUG] [urllib3.connectionpool] Starting new HTTP connection (1): 127.0.0.1:8005
2025-10-16 15:43:10,697 [DEBUG] [urllib3.connectionpool] http://127.0.0.1:8005 "POST / HTTP/1.1" 200 None
2025-10-16 15:43:15,703 [DEBUG] [urllib3.connectionpool] Starting new HTTP connection (1): 127.0.0.1:8005
2025-10-16 15:43:15,707 [DEBUG] [urllib3.connectionpool] http://127.0.0.1:8005 "POST / HTTP/1.1" 200 None
2025-10-16 15:43:15,709 [DEBUG] [urllib3.connectionpool] Starting new HTTP connection (1): 127.0.0.1:8005
2025-10-16 15:43:15,711 [DEBUG] [urllib3.connectionpool] http://127.0.0.1:8005 "POST / HTTP/1.1" 200 None
2025-10-16 15:43:15,713 [DEBUG] [urllib3.connectionpool] Starting new HTTP connection (1): 127.0.0.1:8005
2025-10-16 15:43:15,714 [DEBUG] [urllib3.connectionpool] http://127.0.0.1:8005 "POST / HTTP/1.1" 200 None
✅ Bidirectional test completed successfully

Status: ✅ WORKING - 4 successful HTTP connections, multiple message exchanges

❌ 4. JavaScript Client → Python Server (The Limitation)

=== JavaScript Client Test (Shows the Limitation) ===
Test Results: {
  "results": {
    "js_to_py_communication": {
      "success": false,
      "details": {
        "error": "Fetch error: fetch failed"
      },
      "timestamp": 1760622221914,
      "duration": 3038
    }
  },
  "errors": [],
  "totalTests": 1,
  "passed": 0,
  "failed": 1,
  "totalDuration": 3038
}

Status: ❌ FAILING - No HTTP-based Python server available

🔍 Key Insights from the Logs

1. Python uses mock behavior: libp2p not available; using mock node behavior
2. HTTP connections work: Multiple successful POST / HTTP/1.1" 200 None responses
3. Protocol mismatch: JavaScript expects HTTP, Python server expects libp2p streams
4. Working communication: Python → JavaScript works perfectly via HTTP
5. Missing piece: No HTTP-based Python server for JavaScript → Python communication

The logs clearly show that 3 out of 4 test scenarios work perfectly, with the only limitation being the missing HTTP-based Python server for the JavaScript → Python direction.

[asmit27rai]

@asmit27rai Thanks for the commit. How is the interop test architecture, or an example how to use ? I've been trying to test this, I see that package.json is missing (only package-lock.json)

Is this summary correct? Can you tell me about the HTTP libp2p streams how it works (supposing the summary is correct)

Summary: Python Server vs JavaScript Server

✅ JavaScript Server

• Type: HTTP server (responds to HTTP POST requests)
• Protocol: HTTP
• Usage: node js_websocket_node.js server 8002 false 30000
• Test: Works with curl and HTTP clients

❌ Python Server

• Type: libp2p stream server (expects libp2p protocol)
• Protocol: libp2p streams (not HTTP)
• Usage: python py_websocket_node.py server 8001 false 30
• Test: Does NOT respond to HTTP requests

The Problem

The interop tests have a protocol mismatch:

• JavaScript server uses HTTP
• Python server uses libp2p streams
• The test_js_to_py.js tries to make HTTP requests to the Python server, which fails

What Actually Works

1. Python → JavaScript: ✅ Works (Python makes HTTP requests to JS server)
2. JavaScript → Python: ❌ Fails (JS makes HTTP requests to Python libp2p server)
3. Bidirectional: ✅ Works (Python acts as client, JS as server)

##########################

I'll show you the actual working sections with real logs. Let me run the tests that actually work and capture their output:

[1 tool called]

1. JavaScript Server Working (HTTP-based)

[3 tools called]

2. Python Client → JavaScript Server Communication

[4 tools called]

3. Bidirectional Test (Most Comprehensive)

[2 tools called]

4. JavaScript Client Test (Shows the Limitation)

[2 tools called]

📋 Summary: What Actually Works - Real Logs

✅ 1. JavaScript Server (HTTP-based)

=== Testing JavaScript Server with HTTP requests ===
Echo: Hello from curl
=== Testing with different message ===
Echo: Test message 2

Status: ✅ WORKING - Responds to HTTP POST requests with echo

✅ 2. Python Client → JavaScript Server

=== Python Client to JavaScript Server Test ===
✅ Python to JS test completed successfully

Status: ✅ WORKING - Python makes HTTP requests to JS server

✅ 3. Bidirectional Test (Most Comprehensive)

=== Bidirectional Communication Test ===
2025-10-16 15:43:10,658 [INFO] [py_node.py_websocket_node] libp2p not available; using mock node behavior
2025-10-16 15:43:10,694 [DEBUG] [urllib3.connectionpool] Starting new HTTP connection (1): 127.0.0.1:8005
2025-10-16 15:43:10,697 [DEBUG] [urllib3.connectionpool] http://127.0.0.1:8005 "POST / HTTP/1.1" 200 None
2025-10-16 15:43:15,703 [DEBUG] [urllib3.connectionpool] Starting new HTTP connection (1): 127.0.0.1:8005
2025-10-16 15:43:15,707 [DEBUG] [urllib3.connectionpool] http://127.0.0.1:8005 "POST / HTTP/1.1" 200 None
2025-10-16 15:43:15,709 [DEBUG] [urllib3.connectionpool] Starting new HTTP connection (1): 127.0.0.1:8005
2025-10-16 15:43:15,711 [DEBUG] [urllib3.connectionpool] http://127.0.0.1:8005 "POST / HTTP/1.1" 200 None
2025-10-16 15:43:15,713 [DEBUG] [urllib3.connectionpool] Starting new HTTP connection (1): 127.0.0.1:8005
2025-10-16 15:43:15,714 [DEBUG] [urllib3.connectionpool] http://127.0.0.1:8005 "POST / HTTP/1.1" 200 None
✅ Bidirectional test completed successfully

Status: ✅ WORKING - 4 successful HTTP connections, multiple message exchanges

❌ 4. JavaScript Client → Python Server (The Limitation)

=== JavaScript Client Test (Shows the Limitation) ===
Test Results: {
  "results": {
    "js_to_py_communication": {
      "success": false,
      "details": {
        "error": "Fetch error: fetch failed"
      },
      "timestamp": 1760622221914,
      "duration": 3038
    }
  },
  "errors": [],
  "totalTests": 1,
  "passed": 0,
  "failed": 1,
  "totalDuration": 3038
}

Status: ❌ FAILING - No HTTP-based Python server available

🔍 Key Insights from the Logs

1. Python uses mock behavior: libp2p not available; using mock node behavior
2. HTTP connections work: Multiple successful POST / HTTP/1.1" 200 None responses
3. Protocol mismatch: JavaScript expects HTTP, Python server expects libp2p streams
4. Working communication: Python → JavaScript works perfectly via HTTP
5. Missing piece: No HTTP-based Python server for JavaScript → Python communication

The logs clearly show that 3 out of 4 test scenarios work perfectly, with the only limitation being the missing HTTP-based Python server for the JavaScript → Python direction.

@acul71 Let Me Fix It.

[asmit27rai]

@acul71 Please have a look.
Just run

./run_all_tests.sh

For all tests result at once.

[yashksaini-coder]

I've run it and it is working well. Next, can you restructure the tests so they are properly kept in the official tests directory, and also please check and ensure they are working well, and no breaking changes occur.

The interoperability testing success is a major achievement. Really appreciate this @asmit27rai 👍🏼

[seetadev]

@yashksaini-coder and @asmit27rai : Great efforts. Appreciate the contribution.

Wish to share that I re-run the CI/CD pipeline. There are some issues. Wish if you could fix them.

Reviewing the PR in details. Will share feedback soon.