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 }