Documentation
¶
Index ¶
- Constants
- Variables
- func GlobalBind(address string) (string, error)
- func LocalReset()
- func RegisterMessage(id MessageID, msg Message)
- type Address
- type BlockingDispatcher
- type Conn
- type ConnType
- type Dispatcher
- type Encoder
- type EventDown
- type EventUp
- type Host
- type Listener
- type LocalConn
- func (lc *LocalConn) Close() error
- func (lc *LocalConn) Local() Address
- func (lc *LocalConn) Receive() (Message, error)
- func (lc *LocalConn) Remote() Address
- func (c *LocalConn) Rx() uint64
- func (lc *LocalConn) Send(msg Message) error
- func (c *LocalConn) Tx() uint64
- func (lc *LocalConn) Type() ConnType
- type LocalHost
- type LocalListener
- type LocalManager
- type Message
- type MessageID
- type MultiProtoEncoder
- type Processor
- type Router
- type RoutineDispatcher
- type SingleProtoEncoder
- type Size
- type TCPConn
- type TCPHost
- type TCPListener
Constants ¶
const ( // PlainTCP is an unencrypted TCP connection. PlainTCP ConnType = "tcp" // TLS is a TLS encrypted connection over TCP. TLS = "tls" // PURB is a PURB encryption connection over TCP. PURB = "purb" // Local is a channel based connection type. Local = "local" // InvalidConnType is an invalid connection type. InvalidConnType = "invalid" )
const EventConnDown = "EventConnDown"
const EventConnUp = "EventConnUp"
const LocalMaxBuffer = 200
LocalMaxBuffer is the number of packets that can be sent simultaneously to the same address.
const MaxIdentityExchange = 5 * time.Second
MaxIdentityExchange is the timeout for an identityExchange.
const MaxRetryConnect = 5
MaxRetryConnect defines how many times we should try to connect.
const WaitRetry = 20 * time.Millisecond
WaitRetry is the timeout on connection-setups.
Variables ¶
var ErrCanceled = errors.New("Operation Canceled")
ErrCanceled means something went wrong in the sending or receiving part.
var ErrClosed = errors.New("Connection Closed")
ErrClosed is when a connection has been closed.
var ErrEOF = errors.New("EOF")
ErrEOF is when the connection sends an EOF signal (mostly because it has been shut down).
var ErrTimeout = errors.New("Timeout Error")
ErrTimeout is raised if the timeout has been reached.
var ErrUnknown = errors.New("Unknown Error")
ErrUnknown is an unknown error.
var Suite = edwards25519.NewAES128SHA256Ed25519()
Suite used globally by this network library. For the moment, this will stay,as our focus is not on having the possibility to use any suite we want (the decoding stuff is much harder then, because we don't want to send the suite in the wire). It will surely change in futur releases so we can permit this behavior.
Functions ¶
func GlobalBind ¶
GlobalBind returns the global-binding address. Given any IP:PORT combination, it will return 0.0.0.0:PORT.
func LocalReset ¶
func LocalReset()
LocalReset resets the map of connections + listeners for the defaultLocalManager.
func RegisterMessage ¶
Types ¶
type Address ¶
type Address string
Address contains the ConnType and the actual network address. It is used to connect to a remote host with a Conn and to listen by a Listener. A network address holds an IP address and the port number joined by a colon. It doesn't support IPv6 yet.
func NewAddress ¶
NewAddress takes a connection type and the raw address. It returns a correctly formatted address, which will be of type t. It doesn't do any checking of ConnType or network.
func NewLocalAddress ¶
NewLocalAddress returns an Address of type Local with the given raw addr.
func NewTCPAddress ¶
NewTCPAddress returns a new Address that has type PlainTCP with the given address addr.
func (Address) Host ¶
Host returns the host part of the address. ex: "tcp://127.0.0.1:2000" => "127.0.0.1" In case of an error, it returns an empty string.
func (Address) NetworkAddress ¶
NetworkAddress returns the network address part of the address, which is the IP address and the port joined by a colon. It returns an empty string if the a.Valid() returns false.
func (Address) Port ¶
Port will return the port part of the Address. In the case of an invalid address or an invalid port, it will return "".
func (Address) Public ¶
Public returns true if the address is a public and valid one or false otherwise. Specifically it checks if it is a private address by checking 192.168.**,10.***,127.***,172.16-31.**,169.254.**
func (Address) Valid ¶
Valid returns true if the address is well formed or false otherwise. An address is well formed if it is of the form: ConnType://NetworkAddress. ConnType must be one of the constants defined in this file, NetworkAddress must contain the IP address + Port number. The IP address is validated by net.ParseIP & the port must be included in the range [0;65536]. Ex. tls:192.168.1.10:5678
type BlockingDispatcher ¶
BlockingDispatcher is a Dispatcher that simply calls `p.Process()` on a processor p each time it receives a message with `Dispatch`. It does *not* launch a go routine, or put the message in a queue, etc. It can be re-used for more complex dispatchers.
func NewBlockingDispatcher ¶
func NewBlockingDispatcher() *BlockingDispatcher
NewBlockingDispatcher will return a new BlockingDispatcher.
func (*BlockingDispatcher) Dispatch ¶
func (d *BlockingDispatcher) Dispatch(from Address, msg Message) error
Dispatch calls the corresponding processor's method Process. It's a blocking call if the Processor is blocking.
func (*BlockingDispatcher) RegisterProcessor ¶
func (d *BlockingDispatcher) RegisterProcessor(p Processor, msgType ...Message)
RegisterProcessor saves the given processor in the dispatcher.
func (*BlockingDispatcher) RegisterProcessorFunc ¶
func (d *BlockingDispatcher) RegisterProcessorFunc(msg Message, fn func(Address, Message))
RegisterProcessorFunc takes a func, creates a Processor struct around it and registers it to the dispatcher.
type Conn ¶
type Conn interface {
Encoder
// Send a message through the connection.
// obj should be a POINTER to the actual struct to send, or an interface.
// It should not be a Golang type.
Send(Message) error
// Receive any message through the connection. It is a blocking call that
// returns either when a message arrived or when Close() has been called, or
// when a network error occurred.
Receive() (Message, error)
// Close will close the connection. Implementations must take care that
// Close() makes Receive() returns with an error, and any subsequent Send()
// will return with an error. Calling Close() on a closed Conn will return
// ErrClosed.
Close() error
// Type returns the type of this connection.
Type() ConnType
// Gives the address of the remote endpoint.
Remote() Address
// Returns the local address and port.
Local() Address
// Tx returns how many bytes this connection has written
Tx() uint64
// Rx returns how many bytes this connection has read
Rx() uint64
}
Conn represents any communication between two hosts.
type ConnType ¶
type ConnType string
ConnType represents the type of a Connection. The supported types are defined as constants of type ConnType.
type Dispatcher ¶
type Dispatcher interface {
// RegisterProcessor is called by a Processor so it can receive all messages
// of type msgType. If given multiple msgType, the same processor will be
// called for each of the msgType given.
// **NOTE** In the current version, if a subsequent call to RegisterProcessor
// happens for the same msgType, the latest Processor will be used; there
// is no *copy* or *duplication* of messages.
RegisterProcessor(p Processor, msg ...Message)
// RegisterProcessorFunc enables to register directly a function that will
// be called for each message of type msgType. It's a shorter way of
// registering a Processor.
RegisterProcessorFunc(Message, func(from Address, msg Message))
// Dispatch will find the right processor to dispatch the packet to.
// from is the remote string address of the connection who sent this
// message.
// It can be called for example by the network layer.
// If no processor is found for this message type, then an error is returned
Dispatch(from Address, msg Message) error
}
Dispatcher is an interface whose sole role is to distribute messages to the right Processor. No processing is done,i.e. no looking at packet content. Each Processor that wants to receive all messages of a specific type must register itself to the dispatcher using `RegisterProcessor()`. The network layer calls `Dispatch()` each time it receives a message, so the dispatcher is able to dispatch correctly to the corresponding Processor. Two Dispatchers are available:
- BlockingDispatcher - waits for the return of the Processor before taking another message
- RoutineDispatcher - starts every Processor in a go-routine
type Encoder ¶
type Encoder interface {
// Marshal takes a message and returns the corresponding encoding.
// The msg must be a POINTER to the message.
Marshal(msg Message) ([]byte, error)
// Unmarshal takes a slice of bytes and returns the corresponding message
// and its type. The caller is responsible to give the right slice length so
// the Encoder can decode. It returns a POINTER to the message.
Unmarshal([]byte) (Message, error)
}
Encoder's role is to marshal and unmarshal messages from the network layer. Different encoding techniques can be easily used with this generic interface.
func NewMultiProtoEncoder ¶
func NewMultiProtoEncoder() Encoder
type Host ¶
Host listens for a specific type of Conn and can Connect to specific types of Conn. It is used by the Router so the router can manage connections while being oblivious to which type of connections it's handling.
type Listener ¶
type Listener interface {
Encoder
// Listen for incoming connections.
// Each time there is an incoming Conn, it calls the given
// function in a go routine with the incoming Conn as parameter.
// The call is blocking. If this listener is already Listening, Listen
// should return an error.
Listen(func(Conn)) error
// Stop the listening. Implementations must take care of making
// Stop() a blocking call. Stop() should return when the Listener really
// has stopped listening, i.e. the call to Listen has returned. Calling twice
// Stop() should return an error ErrClosed on the second call.
Stop() error
// A complete address including the type this listener is listening
// to.
Address() Address
// Returns whether this listener is actually listening or not. This
// function is mainly useful for tests where we need to make sure the
// listening routine is started.
Listening() bool
}
Listener is responsible for listening for incoming Conns on a particular address. It can only accept one type of incoming Conn.
type LocalConn ¶
type LocalConn struct {
Encoder
// contains filtered or unexported fields
}
LocalConn is a connection that sends and receives messages to other connections locally.
func NewLocalConn ¶
NewLocalConn returns a new channel connection from local to remote. It mimics the behavior of NewTCPConn and tries to connect right away. It uses the default local manager. The encoder is determined by the local listener.
func NewLocalConnWithManager ¶
func NewLocalConnWithManager(lm *LocalManager, local, remote Address) (*LocalConn, error)
NewLocalConnWithManager is similar to NewLocalConn but takes a specific LocalManager.
func (*LocalConn) Close ¶
Close shuts down the connection on the local and the remote side. If the connection is not open, it returns an error.
func (*LocalConn) Receive ¶
Receive takes a context (that is not used) and waits for a packet to be ready. It returns the received packet. In case of an error the packet is nil and the error is returned.
type LocalHost ¶
type LocalHost struct {
*LocalListener
// contains filtered or unexported fields
}
LocalHost implements the Host interface. It uses LocalConn and LocalListener as the underlying means of communication.
func NewLocalHost ¶
NewLocalHost returns a new Host using Local communication. It listens on the given addr. If an error happened during setup, it returns a nil LocalHost and the error.
func NewLocalHostWithManager ¶
func NewLocalHostWithManager(lm *LocalManager, addr Address, e Encoder) (*LocalHost, error)
NewLocalHostWithManager is similar to NewLocalHost but takes a LocalManager used for communication. If an error happened during setup, it returns a nil LocalHost and the error. If e == nil, MultiProtoEncoder is instantiated.
type LocalListener ¶
LocalListener implements Listener and uses LocalConn to communicate. It behaves as much as possible as a real golang net.Listener but using LocalConn as the underlying communication layer.
func NewLocalListener ¶
func NewLocalListener(addr Address, enc Encoder) (*LocalListener, error)
NewLocalListener returns a fresh LocalListener using the defaultLocalManager. In case of an error the LocalListener is nil and the error is returned. If enc == nil, MultiProtoEncoder is instantiated.
func NewLocalListenerWithManager ¶
func NewLocalListenerWithManager(lm *LocalManager, addr Address, e Encoder) (*LocalListener, error)
NewLocalListenerWithManager returns a new LocalListener using the given LocalManager. In case of an error, the LocalListener is nil and the error is returned. An error occurs in case the address is invalid or the manager is already listening on that address. If e == nil, MultiProtoEncoder is instantiated.
func (*LocalListener) Address ¶
func (ll *LocalListener) Address() Address
Address returns the address used to listen.
func (*LocalListener) Listen ¶
func (ll *LocalListener) Listen(fn func(Conn)) error
Listen calls fn every time a connection-request is received. This call blocks until Stop() is called on the listener. It returns an error if the LocalListener is already listening.
func (*LocalListener) Listening ¶
func (ll *LocalListener) Listening() bool
Listening returns true if this Listener is listening for incoming connections.
func (*LocalListener) Stop ¶
func (ll *LocalListener) Stop() error
Stop shuts down listening. It always returns nil whether ll is listening or not.
type LocalManager ¶
LocalManager keeps a reference to all opened local connections. It also keeps track of who is "listening", so it's possible to mimic Conn & Listener.
func NewLocalManager ¶
func NewLocalManager() *LocalManager
NewLocalManager returns a fresh new manager that can be used by LocalConn, LocalListener & LocalHost.
type Message ¶
type Message interface{}
Message is a type for any message that the user wants to send
type MultiProtoEncoder ¶
type MultiProtoEncoder struct{}
MULTI STRUCT ENCODING PART:
type Processor ¶
type Processor interface {
// Process takes a received Envelope.
Process(from Address, msg Message)
}
Processor is an abstraction to represent any object that want to process messages. It is used in conjunction with Dispatcher: A processor must register itself to a Dispatcher so the Dispatcher will dispatch every messages asked for to the Processor.
type Router ¶
type Router struct {
// Dispatcher is used to dispatch incoming message to the right recipient
Dispatcher
sync.Mutex
event.Publisher
// contains filtered or unexported fields
}
Router handles all networking operations such as:
- listening to incoming connections using a host.Listener method
- opening up new connections using host.Connect method
- dispatching incoming message using a Dispatcher
- dispatching outgoing message maintaining a translation between ServerIdentity <-> address
- managing the re-connections of non-working Conn
Most caller should use the creation function like NewTCPRouter(...), NewLocalRouter(...) then use the Host such as:
router.Start() // will listen for incoming Conn and block router.Stop() // will stop the listening and the managing of all Conn
func NewLocalRouter ¶
NewLocalRouter returns a fresh router which uses only local queues. It uses the default local manager. If you need multiple independent local-queues, use NewLocalRouterWithManager. In case of an error it is returned together with a nil-Router.
func NewLocalRouterWithManager ¶
func NewLocalRouterWithManager(l *LocalManager, addr Address, e Encoder) (*Router, error)
NewLocalRouterWithManager is the same as NewLocalRouter but takes a specific LocalManager. This is useful to run parallel different local overlays. In case of an error it is returned together with a nil-Router.
func NewRouter ¶
NewRouter returns a new Router attached to a ServerIdentity and the host we want to use.
func NewTCPRouter ¶
NewTCPRouter returns a new Router using TCPHost as the underlying Host. If enc == nil, MultiProtoEncoder is instantiated.
func (*Router) Closed ¶
Closed returns true if the router is closed (or is closing). For a router to be closed means that a call to Stop() must have been made.
func (*Router) Rx ¶
Rx implements monitor/CounterIO It returns the Rx for all connections managed by this router
func (*Router) Start ¶
func (r *Router) Start()
Start the listening routine of the underlying Host. This is a blocking call until r.Stop() is called.
type RoutineDispatcher ¶
type RoutineDispatcher struct {
*BlockingDispatcher
}
RoutineDispatcher dispatches messages to the Processors in a go routine. RoutineDispatcher creates one go routine per messages it receives.
func NewRoutineDispatcher ¶
func NewRoutineDispatcher() *RoutineDispatcher
NewRoutineDispatcher returns a fresh RoutineDispatcher
type SingleProtoEncoder ¶
type SingleProtoEncoder struct {
// contains filtered or unexported fields
}
SingleProtoEncoder is a struct that encodes and decodes a unique message using protobuf. This encoder is useful when the whole message set can be contained in a single wrapper struct that protobuf can decode.
func NewSingleProtoEncoder ¶
func NewSingleProtoEncoder(msg Message) *SingleProtoEncoder
type Size ¶
type Size uint32
Size is a type to reprensent the size that is sent before every packet to correctly decode it.
type TCPConn ¶
type TCPConn struct {
Encoder
// contains filtered or unexported fields
}
TCPConn implements the Conn interface using plain, unencrypted TCP.
func NewTCPConn ¶
NewTCPConn will open a TCPConn to the given address. In case of an error it returns a nil TCPConn and the error. If enc == nil, MultiProtoEncoder is instantiated.
func (*TCPConn) Receive ¶
Receive get the bytes from the connection then decodes the buffer. It returns the Envelope containing the message, or EmptyEnvelope and an error if something wrong happened.
type TCPHost ¶
type TCPHost struct {
*TCPListener
}
TCPHost implements the Host interface using TCP connections.
func NewTCPHost ¶
NewTCPHost returns a new Host using TCP connection based type. If e == nil, MultiProtoEncoder is instantiated.
type TCPListener ¶
type TCPListener struct {
Encoder
// contains filtered or unexported fields
}
TCPListener implements the Host-interface using Tcp as a communication channel.
func NewTCPListener ¶
func NewTCPListener(addr Address, enc Encoder) (*TCPListener, error)
NewTCPListener returns a TCPListener. This function binds to the given address. It returns the listener and an error if one occurred during the binding. A subsequent call to Address() gives the actual listening address which is different if you gave it a ":0"-address. If enc == nil, a MultiProtoEncoder is instantiated.
func (*TCPListener) Address ¶
func (t *TCPListener) Address() Address
Address returns the listening address.
func (*TCPListener) Listen ¶
func (t *TCPListener) Listen(fn func(Conn)) error
Listen starts to listen for incoming connections and calls fn for every connection-request it receives. If the connection is closed, an error will be returned.
func (*TCPListener) Listening ¶
func (t *TCPListener) Listening() bool
Listening returns whether it's already listening.
func (*TCPListener) Stop ¶
func (t *TCPListener) Stop() error
Stop the listener. It waits till all connections are closed and returned from. If there is no listener it will return an error.
Source Files