net

README

go-libp2p-net

Network interfaces for go-libp2p

The IPFS Network package handles all of the peer-to-peer networking. It connects to other hosts, it encrypts communications, it muxes messages between the network's client services and target hosts. It has multiple subcomponents:

• Conn - a connection to a single Peer
  • MultiConn - a set of connections to a single Peer
  • SecureConn - an encrypted (tls-like) connection
• Swarm - holds connections to Peers, multiplexes from/to each MultiConn
• Muxer - multiplexes between Services and Swarm. Handles Request/Reply.
  • Service - connects between an outside client service and Network.
  • Handler - the client service part that handles requests

It looks a bit like this:

[]

Install

go get libp2p/go-libp2p-net

Contribute

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

Check out our contributing document for more information on how we work, and about contributing in general. Please be aware that all interactions related to libp2p are subject to the IPFS Code of Conduct.

Small note: If editing the README, please conform to the standard-readme specification.

Want to hack on IPFS?

License

MIT © 2016 Jeromy Johnson

Documentation

Index

• Constants
• Variables
• func AwaitEOF(s Stream) error
• func FullClose(s Stream) error
• func GetDialPeerTimeout(ctx context.Context) time.Duration
• func WithDialPeerTimeout(ctx context.Context, timeout time.Duration) context.Context
• type Conn
• type ConnHandler
• type ConnMultiaddrs
• type ConnSecurity
• type Connectedness
• type Dialer
• type Direction
• type Network
• type Notifiee
• type NotifyBundle
  • func (nb *NotifyBundle) ClosedStream(n Network, s Stream)
  • func (nb *NotifyBundle) Connected(n Network, c Conn)
  • func (nb *NotifyBundle) Disconnected(n Network, c Conn)
  • func (nb *NotifyBundle) Listen(n Network, a ma.Multiaddr)
  • func (nb *NotifyBundle) ListenClose(n Network, a ma.Multiaddr)
  • func (nb *NotifyBundle) OpenedStream(n Network, s Stream)
• type Stat
• type Stream
• type StreamHandler

Constants

const MessageSizeMax = 1 << 22 // 4 MB

MessageSizeMax is a soft (recommended) maximum for network messages. One can write more, as the interface is a stream. But it is useful to bunch it up into multiple read/writes when the whole message is a single, large serialized object.

Variables

var DialPeerTimeout = 60 * time.Second

DialPeerTimeout is the default timeout for a single call to `DialPeer`. When there are multiple concurrent calls to `DialPeer`, this timeout will apply to each independently.

var EOFTimeout = time.Second * 60

EOFTimeout is the maximum amount of time to wait to successfully observe an EOF on the stream. Defaults to 60 seconds.

var ErrExpectedEOF = errors.New("read data when expecting EOF")

ErrExpectedEOF is returned when we read data while expecting an EOF.

Functions

func AwaitEOF

func AwaitEOF(s Stream) error

AwaitEOF waits for an EOF on the given stream, returning an error if that fails. It waits at most EOFTimeout (defaults to 1 minute) after which it resets the stream.

func FullClose

func FullClose(s Stream) error

FullClose closes the stream and waits to read an EOF from the other side.

* If it reads any data *before* the EOF, it resets the stream. * If it doesn't read an EOF within EOFTimeout, it resets the stream.

You'll likely want to invoke this as `go FullClose(stream)` to close the stream in the background.

func GetDialPeerTimeout

func GetDialPeerTimeout(ctx context.Context) time.Duration

GetDialPeerTimeout returns the current DialPeer timeout (or the default).

func WithDialPeerTimeout

func WithDialPeerTimeout(ctx context.Context, timeout time.Duration) context.Context

WithDialPeerTimeout returns a new context with the DialPeer timeout applied.

This timeout overrides the default DialPeerTimeout and applies per-dial independently.

Types

type Conn

type Conn interface {
	io.Closer

	ConnSecurity
	ConnMultiaddrs

	// NewStream constructs a new Stream over this conn.
	NewStream() (Stream, error)

	// GetStreams returns all open streams over this conn.
	GetStreams() []Stream

	// Stat stores metadata pertaining to this conn.
	Stat() Stat
}

Conn is a connection to a remote peer. It multiplexes streams. Usually there is no need to use a Conn directly, but it may be useful to get information about the peer on the other side:

stream.Conn().RemotePeer()

type ConnHandler

type ConnHandler func(Conn)

ConnHandler is the type of function used to listen for connections opened by the remote side.

type ConnMultiaddrs

type ConnMultiaddrs interface {
	// LocalMultiaddr returns the local Multiaddr associated
	// with this connection
	LocalMultiaddr() ma.Multiaddr

	// RemoteMultiaddr returns the remote Multiaddr associated
	// with this connection
	RemoteMultiaddr() ma.Multiaddr
}

ConnMultiaddrs is an interface mixin for connection types that provide multiaddr addresses for the endpoints.

type ConnSecurity

type ConnSecurity interface {
	// LocalPeer returns our peer ID
	LocalPeer() peer.ID

	// LocalPrivateKey returns our private key
	LocalPrivateKey() ic.PrivKey

	// RemotePeer returns the peer ID of the remote peer.
	RemotePeer() peer.ID

	// RemotePublicKey returns the public key of the remote peer.
	RemotePublicKey() ic.PubKey
}

ConnSecurity is the interface that one can mix into a connection interface to give it the security methods.

type Connectedness

type Connectedness int

Connectedness signals the capacity for a connection with a given node. It is used to signal to services and other peers whether a node is reachable.

const (
	// NotConnected means no connection to peer, and no extra information (default)
	NotConnected Connectedness = iota

	// Connected means has an open, live connection to peer
	Connected

	// CanConnect means recently connected to peer, terminated gracefully
	CanConnect

	// CannotConnect means recently attempted connecting but failed to connect.
	// (should signal "made effort, failed")
	CannotConnect
)

type Dialer

type Dialer interface {

	// Peerstore returns the internal peerstore
	// This is useful to tell the dialer about a new address for a peer.
	// Or use one of the public keys found out over the network.
	Peerstore() pstore.Peerstore

	// LocalPeer returns the local peer associated with this network
	LocalPeer() peer.ID

	// DialPeer establishes a connection to a given peer
	DialPeer(context.Context, peer.ID) (Conn, error)

	// ClosePeer closes the connection to a given peer
	ClosePeer(peer.ID) error

	// Connectedness returns a state signaling connection capabilities
	Connectedness(peer.ID) Connectedness

	// Peers returns the peers connected
	Peers() []peer.ID

	// Conns returns the connections in this Netowrk
	Conns() []Conn

	// ConnsToPeer returns the connections in this Netowrk for given peer.
	ConnsToPeer(p peer.ID) []Conn

	// Notify/StopNotify register and unregister a notifiee for signals
	Notify(Notifiee)
	StopNotify(Notifiee)
}

Dialer represents a service that can dial out to peers (this is usually just a Network, but other services may not need the whole stack, and thus it becomes easier to mock)

type Direction

type Direction int

Direction represents which peer in a stream initiated a connection.

const (
	// DirUnknown is the default direction.
	DirUnknown Direction = iota
	// DirInbound is for when the remote peer initiated a connection.
	DirInbound
	// DirOutbound is for when the local peer initiated a connection.
	DirOutbound
)

type Network

type Network interface {
	Dialer
	io.Closer

	// SetStreamHandler sets the handler for new streams opened by the
	// remote side. This operation is threadsafe.
	SetStreamHandler(StreamHandler)

	// SetConnHandler sets the handler for new connections opened by the
	// remote side. This operation is threadsafe.
	SetConnHandler(ConnHandler)

	// NewStream returns a new stream to given peer p.
	// If there is no connection to p, attempts to create one.
	NewStream(context.Context, peer.ID) (Stream, error)

	// Listen tells the network to start listening on given multiaddrs.
	Listen(...ma.Multiaddr) error

	// ListenAddresses returns a list of addresses at which this network listens.
	ListenAddresses() []ma.Multiaddr

	// InterfaceListenAddresses returns a list of addresses at which this network
	// listens. It expands "any interface" addresses (/ip4/0.0.0.0, /ip6/::) to
	// use the known local interfaces.
	InterfaceListenAddresses() ([]ma.Multiaddr, error)

	// Process returns the network's Process
	Process() goprocess.Process
}

Network is the interface used to connect to the outside world. It dials and listens for connections. it uses a Swarm to pool connnections (see swarm pkg, and peerstream.Swarm). Connections are encrypted with a TLS-like protocol.

type Notifiee

type Notifiee interface {
	Listen(Network, ma.Multiaddr)      // called when network starts listening on an addr
	ListenClose(Network, ma.Multiaddr) // called when network stops listening on an addr
	Connected(Network, Conn)           // called when a connection opened
	Disconnected(Network, Conn)        // called when a connection closed
	OpenedStream(Network, Stream)      // called when a stream opened
	ClosedStream(Network, Stream)      // called when a stream closed

}

Notifiee is an interface for an object wishing to receive notifications from a Network.

type NotifyBundle

type NotifyBundle struct {
	ListenF      func(Network, ma.Multiaddr)
	ListenCloseF func(Network, ma.Multiaddr)

	ConnectedF    func(Network, Conn)
	DisconnectedF func(Network, Conn)

	OpenedStreamF func(Network, Stream)
	ClosedStreamF func(Network, Stream)
}

NotifyBundle implements Notifiee by calling any of the functions set on it, and nop'ing if they are unset. This is the easy way to register for notifications.

func (*NotifyBundle) ClosedStream

func (nb *NotifyBundle) ClosedStream(n Network, s Stream)

ClosedStream calls ClosedStreamF if it is not null.

func (*NotifyBundle) Connected

func (nb *NotifyBundle) Connected(n Network, c Conn)

Connected calls ConnectedF if it is not null.

func (*NotifyBundle) Disconnected

func (nb *NotifyBundle) Disconnected(n Network, c Conn)

Disconnected calls DisconnectedF if it is not null.

func (*NotifyBundle) Listen

func (nb *NotifyBundle) Listen(n Network, a ma.Multiaddr)

Listen calls ListenF if it is not null.

func (*NotifyBundle) ListenClose

func (nb *NotifyBundle) ListenClose(n Network, a ma.Multiaddr)

ListenClose calls ListenCloseF if it is not null.

func (*NotifyBundle) OpenedStream

func (nb *NotifyBundle) OpenedStream(n Network, s Stream)

OpenedStream calls OpenedStreamF if it is not null.

type Stat

type Stat struct {
	Direction Direction
	Extra     map[interface{}]interface{}
}

Stat stores metadata pertaining to a given Stream/Conn.

type Stream

type Stream interface {
	smux.Stream

	Protocol() protocol.ID
	SetProtocol(protocol.ID)

	// Stat returns metadata pertaining to this stream.
	Stat() Stat

	// Conn returns the connection this stream is part of.
	Conn() Conn
}

Stream represents a bidirectional channel between two agents in the IPFS network. "agent" is as granular as desired, potentially being a "request -> reply" pair, or whole protocols. Streams are backed by stream-muxer streams underneath the hood.

type StreamHandler

type StreamHandler func(Stream)

StreamHandler is the type of function used to listen for streams opened by the remote side.