websocket

README

go-ws-transport

A libp2p transport implementation using WebSockets

go-ws-transport is an implementation of the libp2p transport interface that streams data over WebSockets, which are themselves layered over TCP/IP. It is included by default in the main go-libp2p "entry point" module.

Table of Contents

• go-ws-transport
  • Table of Contents
  • Install
  • Usage
  • Addresses
  • Security and Multiplexing
  • Contribute
    • Want to hack on IPFS?
  • License

Install

go-ws-transport is included as a dependency of go-libp2p, which is the most common libp2p entry point. If you depend on go-libp2p, there is generally no need to explicitly depend on this module.

go-ws-transport is a standard Go module which can be installed with:

> go get github.com/libp2p/go-ws-transport

This repo is gomod-compatible, and users of go 1.11 and later with modules enabled will automatically pull the latest tagged release by referencing this package. Upgrades to future releases can be managed using go get, or by editing your go.mod file as described by the gomod documentation.

Usage

WebSockets are one of the default transports enabled when constructing a standard libp2p Host, along with TCP.

Calling libp2p.New to construct a libp2p Host will enable the WebSocket transport, unless you override the default transports by passing in Options to libp2p.New.

To explicitly enable the WebSocket transport while constructing a host, use the libp2p.Transport option, passing in the ws.New constructor function:

import (
    "context"

    libp2p "github.com/libp2p/go-libp2p"
    ws "github.com/libp2p/go-ws-transport"
)

ctx := context.Background()

// WebSockets only:
h, err := libp2p.New(ctx,
    libp2p.Transport(ws.New)
)

The example above will replace the default transports with a single WebSocket transport. To add multiple tranports, use ChainOptions:

// WebSockets and QUIC:
h, err := libp2p.New(ctx,
    libp2p.ChainOptions(
        libp2p.Transport(ws.New),
        libp2p.Transport(quic.NewTransport)) // see https://github.com/libp2p/go-libp2p-quic-transport
)

Addresses

The WebSocket transport supports multiaddrs that contain a ws component, which is encapsulated within (or layered onto) another valid TCP multiaddr.

Examples:

addr	description
/ip4/1.2.3.4/tcp/1234/ws	IPv4: 1.2.3.4, TCP port 1234
/ip6/::1/tcp/1234/ws	IPv6 loopback, TCP port 1234
/dns4/example.com/tcp/80/ws	DNS over IPv4, hostname example.com, TCP port 80

Notice that the /ws multiaddr component contextualizes an existing TCP/IP multiaddr and does not require any additional addressing information.

Security and Multiplexing

While the WebSocket spec defines a wss URI scheme for encrypted WebSocket connections, support for wss URIs relies on TLS, which wraps the WebSocket connection in a similar manner to TLS-protected HTTP traffic.

As libp2p does not integrate with the TLS Certificate Authority infrastructure by design, security for WebSockets is provided by a transport upgrader. The transport upgrader negotiates transport security for each connection according to the protocols supported by each party.

The transport upgrader also negotiates a stream multiplexing protocol to allow many bidirectional streams to coexist on a single WebSocket connection.

Contribute

Feel free to join in. All welcome. Open an issue!

This repository falls under the libp2p Code of Conduct.

Want to hack on libp2p?

License

MIT

---

The last gx published version of this module was: 2.0.27: QmaSWc4ox6SZQF6DHZvDuM9sP1syNajkKuPXmKR1t5BAz5

Documentation

Overview

Package websocket implements a websocket based transport for go-libp2p.

Index

• Variables
• func ConvertWebsocketMultiaddrToNetAddr(maddr ma.Multiaddr) (net.Addr, error)
• func NewMux(mux *http.ServeMux, prefix string) func(u *tptu.Upgrader) *WebsocketTransport
• func ParseWebsocketNetAddr(a net.Addr) (ma.Multiaddr, error)
• type Addr
  • func NewAddr(host string) *Addr
  • func (addr *Addr) Network() string
• type Conn
  • func NewConn(raw *ws.Conn) *Conn
  • func (c *Conn) Close() error
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) Read(b []byte) (int, error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Write(b []byte) (n int, err error)
• type WebsocketTransport
  • func New(u *tptu.Upgrader) *WebsocketTransport
  • func (t *WebsocketTransport) CanDial(a ma.Multiaddr) bool
  • func (t *WebsocketTransport) Dial(ctx context.Context, raddr ma.Multiaddr, p peer.ID) (transport.CapableConn, error)
  • func (t *WebsocketTransport) Listen(a ma.Multiaddr) (transport.Listener, error)
  • func (t *WebsocketTransport) Protocols() []int
  • func (t *WebsocketTransport) Proxy() bool

Variables

var GracefulCloseTimeout = 100 * time.Millisecond

GracefulCloseTimeout is the time to wait trying to gracefully close a connection before simply cutting it.

var WsCodec = &manet.NetCodec{
	NetAddrNetworks:  []string{"websocket"},
	ProtocolName:     "ws",
	ConvertMultiaddr: ConvertWebsocketMultiaddrToNetAddr,
	ParseNetAddr:     ParseWebsocketNetAddr,
}

WsCodec is the multiaddr-net codec definition for the websocket transport

var WsFmt = mafmt.And(mafmt.TCP, mafmt.Base(ma.P_WS))

WsFmt is multiaddr formatter for WsProtocol

var WsProtocol = ma.ProtocolWithCode(ma.P_WS)

WsProtocol is the multiaddr protocol definition for this transport.

Deprecated: use `ma.ProtocolWithCode(ma.P_WS)

Functions

func ConvertWebsocketMultiaddrToNetAddr

func ConvertWebsocketMultiaddrToNetAddr(maddr ma.Multiaddr) (net.Addr, error)

func NewMux

func NewMux(mux *http.ServeMux, prefix string) func(u *tptu.Upgrader) *WebsocketTransport

NewMux will use an existing mux and prefix to register instead of directly listening. The ip address will be ignored.

func ParseWebsocketNetAddr

func ParseWebsocketNetAddr(a net.Addr) (ma.Multiaddr, error)

Types

type Addr

type Addr struct {
	*url.URL
}

Addr is an implementation of net.Addr for WebSocket.

func NewAddr

func NewAddr(host string) *Addr

NewAddr creates a new Addr using the given host string

func (*Addr) Network

func (addr *Addr) Network() string

Network returns the network type for a WebSocket, "websocket".

type Conn

type Conn struct {
	*ws.Conn
	DefaultMessageType int
	// contains filtered or unexported fields
}

Conn implements net.Conn interface for gorilla/websocket.

func NewConn

func NewConn(raw *ws.Conn) *Conn

NewConn creates a Conn given a regular gorilla/websocket Conn.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection. Only the first call to Close will receive the close error, subsequent and concurrent calls will return nil. This method is thread-safe.

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

func (*Conn) Read

func (c *Conn) Read(b []byte) (int, error)

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

func (*Conn) Write

func (c *Conn) Write(b []byte) (n int, err error)

type WebsocketTransport

type WebsocketTransport struct {
	Upgrader *tptu.Upgrader
	Prefix   string
	Mux      *http.ServeMux
}

WebsocketTransport is the actual go-libp2p transport

func New

func New(u *tptu.Upgrader) *WebsocketTransport

func (*WebsocketTransport) CanDial

func (t *WebsocketTransport) CanDial(a ma.Multiaddr) bool

func (*WebsocketTransport) Dial

func (t *WebsocketTransport) Dial(ctx context.Context, raddr ma.Multiaddr, p peer.ID) (transport.CapableConn, error)

func (*WebsocketTransport) Listen

func (t *WebsocketTransport) Listen(a ma.Multiaddr) (transport.Listener, error)

func (*WebsocketTransport) Protocols

func (t *WebsocketTransport) Protocols() []int

func (*WebsocketTransport) Proxy

func (t *WebsocketTransport) Proxy() bool