Implement WebSocket Transport with IPv6 Support and Security Integration

[Copilot]

This PR implements a complete WebSocket transport for py-libp2p, enabling interoperability with js-libp2p and go-libp2p implementations that use /ws multiaddrs. The implementation includes comprehensive IPv6 support, security protocol integration, and automatic transport selection.

Key Features

WebSocket Transport Implementation

• Full /ws protocol support with proper multiaddr parsing and handling
• IPv6 address formatting - Automatically wraps IPv6 addresses in brackets for WebSocket URLs (e.g., ::1 → ws://[::1]:8080/)
• DNS address support - Handles dns4, dns6, and dnsaddr multiaddrs
• Connection lifecycle management with proper error handling and cleanup

Security Integration

The WebSocket transport seamlessly integrates with py-libp2p's existing security protocols:

from libp2p import new_host
from multiaddr import Multiaddr

# WebSocket with Noise encryption (default)
host = new_host(listen_addrs=[Multiaddr("/ip4/0.0.0.0/tcp/8080/ws")])

• Noise protocol encryption enabled by default for secure communication
• Multiple security protocol support (Noise, SECIO, Plaintext)
• Transport upgrader integration for security handshake over WebSocket

Automatic Transport Selection

Implements a transport registry system that automatically selects the correct transport based on multiaddr protocols:

# Automatically uses TCP transport
new_host(listen_addrs=[Multiaddr("/ip4/127.0.0.1/tcp/8080")])

# Automatically uses WebSocket transport  
new_host(listen_addrs=[Multiaddr("/ip4/127.0.0.1/tcp/8080/ws")])

IPv6 and Cross-Platform Support

Addresses the IPv6 support gap identified in the original PR discussion:

# IPv4 WebSocket
"/ip4/127.0.0.1/tcp/8080/ws" → ws://127.0.0.1:8080/

# IPv6 WebSocket (properly formatted)
"/ip6/::1/tcp/8080/ws" → ws://[::1]:8080/

# DNS WebSocket
"/dns4/example.com/tcp/443/ws" → ws://example.com:443/

Implementation Details

Core Components

• WebsocketTransport - Main transport class implementing dial and listener creation
• WebsocketListener - Handles incoming WebSocket connections with proper address binding
• P2PWebSocketConnection - Wraps WebSocket connections to provide the raw stream interface required by libp2p protocols
• TransportRegistry - Dynamic transport selection system based on multiaddr protocols

Error Handling

• Graceful handling of missing trio-websocket dependencies
• Comprehensive multiaddr validation with clear error messages
• Proper connection cleanup and resource management
• IPv6 address detection and formatting

Testing and Verification

Includes comprehensive test coverage:

• Unit tests for all WebSocket transport components
• IPv6 address formatting validation
• Security protocol integration tests
• Transport registry and factory function tests
• End-to-end integration tests

Usage Examples

Basic WebSocket Server

import trio
from libp2p import new_host
from multiaddr import Multiaddr

async def main():
    # Create WebSocket host with Noise encryption
    host = new_host(listen_addrs=[Multiaddr("/ip4/0.0.0.0/tcp/8080/ws")])
    
    async with host.run():
        print(f"WebSocket server running on {host.get_addrs()}")
        await trio.sleep_forever()

Cross-Implementation Interoperability

The implementation is fully compatible with js-libp2p:

// js-libp2p server
import { createLibp2p } from 'libp2p'
import { webSockets } from '@libp2p/websockets'
import { noise } from '@chainsafe/libp2p-noise'

const node = await createLibp2p({
  transports: [webSockets()],
  connectionEncryption: [noise()],
  addresses: { listen: ['/ip4/0.0.0.0/tcp/8080/ws'] }
})

# py-libp2p client can connect seamlessly
host = new_host()
await host.connect(peer_info)  # Works with js-libp2p WebSocket server

Backward Compatibility

The implementation maintains full backward compatibility:

• Existing TCP transport code continues to work unchanged
• No breaking changes to existing APIs
• Graceful fallback when WebSocket dependencies are not installed
• Transport selection is automatic and transparent

Dependencies

Adds trio-websocket>=0.11.0 as a new dependency for WebSocket functionality. The transport gracefully handles missing dependencies and provides clear error messages when WebSocket features are attempted without the required packages.

Status Update

Updates the README.md transport status from ❌ to ✅ for libp2p-websocket, reflecting the completed implementation.

This implementation provides a solid foundation for WebSocket connectivity in py-libp2p while maintaining the high standards of security and interoperability expected from the libp2p ecosystem.

---

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