github.com/keltia/go-ipfs@v0.3.8-0.20150909044612-210793031c63/p2p/net/interface.go (about)

     1  package net
     2  
     3  import (
     4  	"io"
     5  
     6  	conn "github.com/ipfs/go-ipfs/p2p/net/conn"
     7  	peer "github.com/ipfs/go-ipfs/p2p/peer"
     8  
     9  	ma "github.com/ipfs/go-ipfs/Godeps/_workspace/src/github.com/jbenet/go-multiaddr"
    10  	"github.com/ipfs/go-ipfs/Godeps/_workspace/src/github.com/jbenet/goprocess"
    11  	context "github.com/ipfs/go-ipfs/Godeps/_workspace/src/golang.org/x/net/context"
    12  )
    13  
    14  // MessageSizeMax is a soft (recommended) maximum for network messages.
    15  // One can write more, as the interface is a stream. But it is useful
    16  // to bunch it up into multiple read/writes when the whole message is
    17  // a single, large serialized object.
    18  const MessageSizeMax = 2 << 22 // 4MB
    19  
    20  // Stream represents a bidirectional channel between two agents in
    21  // the IPFS network. "agent" is as granular as desired, potentially
    22  // being a "request -> reply" pair, or whole protocols.
    23  // Streams are backed by SPDY streams underneath the hood.
    24  type Stream interface {
    25  	io.Reader
    26  	io.Writer
    27  	io.Closer
    28  
    29  	// Conn returns the connection this stream is part of.
    30  	Conn() Conn
    31  }
    32  
    33  // StreamHandler is the type of function used to listen for
    34  // streams opened by the remote side.
    35  type StreamHandler func(Stream)
    36  
    37  // Conn is a connection to a remote peer. It multiplexes streams.
    38  // Usually there is no need to use a Conn directly, but it may
    39  // be useful to get information about the peer on the other side:
    40  //  stream.Conn().RemotePeer()
    41  type Conn interface {
    42  	conn.PeerConn
    43  
    44  	// NewStream constructs a new Stream over this conn.
    45  	NewStream() (Stream, error)
    46  }
    47  
    48  // ConnHandler is the type of function used to listen for
    49  // connections opened by the remote side.
    50  type ConnHandler func(Conn)
    51  
    52  // Network is the interface used to connect to the outside world.
    53  // It dials and listens for connections. it uses a Swarm to pool
    54  // connnections (see swarm pkg, and peerstream.Swarm). Connections
    55  // are encrypted with a TLS-like protocol.
    56  type Network interface {
    57  	Dialer
    58  	io.Closer
    59  
    60  	// SetStreamHandler sets the handler for new streams opened by the
    61  	// remote side. This operation is threadsafe.
    62  	SetStreamHandler(StreamHandler)
    63  
    64  	// SetConnHandler sets the handler for new connections opened by the
    65  	// remote side. This operation is threadsafe.
    66  	SetConnHandler(ConnHandler)
    67  
    68  	// NewStream returns a new stream to given peer p.
    69  	// If there is no connection to p, attempts to create one.
    70  	NewStream(peer.ID) (Stream, error)
    71  
    72  	// Listen tells the network to start listening on given multiaddrs.
    73  	Listen(...ma.Multiaddr) error
    74  
    75  	// ListenAddresses returns a list of addresses at which this network listens.
    76  	ListenAddresses() []ma.Multiaddr
    77  
    78  	// InterfaceListenAddresses returns a list of addresses at which this network
    79  	// listens. It expands "any interface" addresses (/ip4/0.0.0.0, /ip6/::) to
    80  	// use the known local interfaces.
    81  	InterfaceListenAddresses() ([]ma.Multiaddr, error)
    82  
    83  	// Process returns the network's Process
    84  	Process() goprocess.Process
    85  }
    86  
    87  // Dialer represents a service that can dial out to peers
    88  // (this is usually just a Network, but other services may not need the whole
    89  // stack, and thus it becomes easier to mock)
    90  type Dialer interface {
    91  
    92  	// Peerstore returns the internal peerstore
    93  	// This is useful to tell the dialer about a new address for a peer.
    94  	// Or use one of the public keys found out over the network.
    95  	Peerstore() peer.Peerstore
    96  
    97  	// LocalPeer returns the local peer associated with this network
    98  	LocalPeer() peer.ID
    99  
   100  	// DialPeer establishes a connection to a given peer
   101  	DialPeer(context.Context, peer.ID) (Conn, error)
   102  
   103  	// ClosePeer closes the connection to a given peer
   104  	ClosePeer(peer.ID) error
   105  
   106  	// Connectedness returns a state signaling connection capabilities
   107  	Connectedness(peer.ID) Connectedness
   108  
   109  	// Peers returns the peers connected
   110  	Peers() []peer.ID
   111  
   112  	// Conns returns the connections in this Netowrk
   113  	Conns() []Conn
   114  
   115  	// ConnsToPeer returns the connections in this Netowrk for given peer.
   116  	ConnsToPeer(p peer.ID) []Conn
   117  
   118  	// Notify/StopNotify register and unregister a notifiee for signals
   119  	Notify(Notifiee)
   120  	StopNotify(Notifiee)
   121  }
   122  
   123  // Connectedness signals the capacity for a connection with a given node.
   124  // It is used to signal to services and other peers whether a node is reachable.
   125  type Connectedness int
   126  
   127  const (
   128  	// NotConnected means no connection to peer, and no extra information (default)
   129  	NotConnected Connectedness = iota
   130  
   131  	// Connected means has an open, live connection to peer
   132  	Connected
   133  
   134  	// CanConnect means recently connected to peer, terminated gracefully
   135  	CanConnect
   136  
   137  	// CannotConnect means recently attempted connecting but failed to connect.
   138  	// (should signal "made effort, failed")
   139  	CannotConnect
   140  )
   141  
   142  // Notifiee is an interface for an object wishing to receive
   143  // notifications from a Network.
   144  type Notifiee interface {
   145  	Listen(Network, ma.Multiaddr)      // called when network starts listening on an addr
   146  	ListenClose(Network, ma.Multiaddr) // called when network starts listening on an addr
   147  	Connected(Network, Conn)           // called when a connection opened
   148  	Disconnected(Network, Conn)        // called when a connection closed
   149  	OpenedStream(Network, Stream)      // called when a stream opened
   150  	ClosedStream(Network, Stream)      // called when a stream closed
   151  
   152  	// TODO
   153  	// PeerConnected(Network, peer.ID)    // called when a peer connected
   154  	// PeerDisconnected(Network, peer.ID) // called when a peer disconnected
   155  }