Overview

The wsport project provides a robust implementation of a WebSocket-based transport for the go-libp2p ecosystem doc.go1-2 It bridges the gap between traditional web protocols and peer-to-peer networking by allowing libp2p nodes to communicate over standard WebSocket (ws://) and Secure WebSocket (wss://) connections.

The project is split into two primary areas:

1. Core Library: A Go package that implements the transport.Transport interface, enabling libp2p hosts to use WebSockets for dialing and listening.
2. CLI Tools: A suite of utilities located in the cmd/ directory that demonstrate practical applications, such as DHT bootstrapping, circuit relays, and proxying.

System Architecture

wsport functions as a transport layer that upgrades standard network connections into libp2p-compatible streams. It supports various multiaddr formats, including the x-parity-ws and x-parity-wss protocols for handling WebSockets with custom paths websocket.go50-56

From Web Protocols to libp2p

The following diagram illustrates how standard web components map to the internal WebsocketTransport entities.

Sources: websocket.go18-41 websocket.go72-78 websocket.go81-87

Core Components

The WebsocketTransport

The heart of the library is the WebsocketTransport struct websocket.go81-87 It implements the transport.Transport interface from go-libp2p, providing the necessary logic to:

• Match Protocols: Determine if a multiaddr is dialable using CanDial websocket.go108-110
• Dial Peers: Establish outbound connections via Dial websocket.go156-167
• Listen: Accept inbound WebSocket connections via Listen websocket.go211-217

For a deep dive into the transport implementation and multiaddr matching, see Core Library (wsport package).

Transport Layer Stack

The transport stack moves from raw TCP through WebSocket upgrades into the libp2p upgrader.

Sources: websocket.go169-179 websocket.go181-200

Command-Line Utilities

The cmd/ sub-module contains several tools that leverage wsport for various network tasks. These tools share common patterns for identity management and host construction.

• Identity: Tools like pid_seed and peerid handle persistent peer identities.
• Connectivity: dial and reconnect manage active and self-healing peer connections.
• Infrastructure: circuit_relay_hop and bootstrap provide the backbone for p2p networks.
• Applications: http and proxy demonstrate high-level protocols like file sharing and SOCKS5 proxying over libp2p.

For details on building and using these tools, see Getting Started and Command-Line Tools (cmd/ sub-module).

Child Pages

• Getting Started: Instructions on building the project, module layout, and configuration via environment variables (e.g., RELAY, PID_SEED).
• Architecture Overview: A detailed look at the transport stack, the relay model, and how wsport integrates with libp2p.

Sources: go.mod1-15 cmd/go.mod1-16 websocket.go1-16