Documentation
¶
Index ¶
- Constants
- Variables
- func DefaultConstructors() protobuf.Constructors
- func DumpTypes()
- func GlobalBind(address string) (string, error)
- func Marshal(msg Message) ([]byte, error)
- func Unmarshal(buf []byte) (MessageTypeID, Message, error)
- type Address
- func (a Address) ConnType() ConnType
- func (a Address) Host() string
- func (a Address) IsHostname() bool
- func (a Address) NetworkAddress() string
- func (a Address) NetworkAddressResolved() string
- func (a Address) Port() string
- func (a Address) Resolve() string
- func (a Address) String() string
- func (a Address) Valid() bool
- type BlockingDispatcher
- type Conn
- type ConnType
- type Dispatcher
- type Envelope
- type Host
- type KCPConn
- func (c *KCPConn) Close() error
- func (c *KCPConn) IsClosed() bool
- func (c *KCPConn) Local() Address
- func (c *KCPConn) Receive() (env *Envelope, e error)
- func (c *KCPConn) Remote() Address
- func (c *KCPConn) Rx() (out uint64)
- func (c *KCPConn) Send(msg Message) (uint64, error)
- func (c *KCPConn) Tx() (out uint64)
- func (c *KCPConn) Type() ConnType
- type KCPHost
- type KCPListener
- type Listener
- type Message
- type MessageTypeID
- type Processor
- type Router
- func (r *Router) AddErrorHandler(errorHandler func(*ServerIdentity))
- func (r *Router) AdjustConnect(mlist map[ServerIdentityID]bool)
- func (r *Router) CloseConnectByID(id ServerIdentityID)
- func (r *Router) Closed() bool
- func (r *Router) GetBlocks(e *ServerIdentity) int
- func (r *Router) Listening() bool
- func (r *Router) Pause()
- func (r *Router) Rx() uint64
- func (r *Router) Send(e *ServerIdentity, msg Message, bForeConnect bool) (uint64, error)
- func (r *Router) Start()
- func (r *Router) Stop() error
- func (r *Router) Tx() uint64
- func (r *Router) Unpause()
- type RoutineDispatcher
- type ServerIdentity
- type ServerIdentityID
- type Size
Constants ¶
const ( // PlainKCP is an unencrypted KCP connection. PlainKCP ConnType = "kcp" // TLS is a TLS encrypted connection over KCP. TLS = "tls" // Local is a channel based connection type. Local = "local" // InvalidConnType is an invalid connection type. InvalidConnType = "wrong" )
const MaxRetryConnect = 3
MaxRetryConnect defines how many times we should try to connect.
const NamespaceBodyType = NamespaceURL + "/protocolType/"
NamespaceBodyType is the namespace used for PacketTypeID
const NamespaceURL = "https://cypherium.io/"
NamespaceURL is the basic namespace used for uuid XXX should move that to external of the library as not every cothority/packages should be expected to use that.
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 ErrorType = MessageTypeID(uuid.Nil)
ErrorType is reserved by the network library. When you receive a message of ErrorType, it is generally because an error happened, then you can call Error() on it.
var ReadTimeout = 3 * time.Minute // 60 * time.Second
a connection will return an io.EOF after ReadTimeout if nothing has been sent.
var ServerIdentityType = RegisterMessage(ServerIdentity{})
ServerIdentityType can be used to recognise an ServerIdentity-message
Functions ¶
func DefaultConstructors ¶
func DefaultConstructors() protobuf.Constructors
DefaultConstructors gives a default constructor for protobuf
func GlobalBind ¶
GlobalBind returns the global-binding address. Given any IP:PORT combination, it will return ":PORT".
func Marshal ¶
Marshal outputs the type and the byte representation of a structure. It first marshals the type as a uuid, i.e. a 16 byte length slice, then the struct encoded by protobuf. That slice of bytes can be then decoded with Unmarshal. msg must be a pointer to the message.
func Unmarshal ¶
func Unmarshal(buf []byte) (MessageTypeID, Message, error)
Unmarshal returns the type and the message out of a buffer. One can cast the resulting Message to a *pointer* of the underlying type, i.e. it returns a pointer. The type must be registered to the network library in order to be decodable and the buffer must have been generated by Marshal otherwise it returns an error.
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 NewKCPAddress ¶
NewKCPAddress returns a new Address that has type PlainKCP with the given address addr.
func (Address) ConnType ¶
ConnType returns the connection type from the address. It returns InvalidConnType if the address is not valid or if the connection type is not known.
func (Address) Host ¶
Host returns the host part of the address. ex: "kcp://127.0.0.1:2000" => "127.0.0.1" In case of an error, it returns an empty string.
func (Address) IsHostname ¶
IsHostname returns true if the address is defined by a VALID DNS name
func (Address) NetworkAddress ¶
NetworkAddress returns the network address part of the address, which is the host and the port joined by a colon. It returns an empty string the address is not valid
func (Address) NetworkAddressResolved ¶
NetworkAddressResolved returns the network address of the address, but resolved. That is: the hostname resolved and the port joined by a colon. It returns an empty string if the address is not valid.
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) Resolve ¶
Resolve returns the IP address associated to the hostname that represents the address a. If a is defined by an IP address (*.*.*.*) or if the hostname is not valid, the empty string is returned
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]. For example, "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(packet *Envelope) 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 ...MessageTypeID)
RegisterProcessor saves the given processor in the dispatcher.
func (*BlockingDispatcher) RegisterProcessorFunc ¶
func (d *BlockingDispatcher) RegisterProcessorFunc(msgType MessageTypeID, fn func(*Envelope))
RegisterProcessorFunc takes a func, creates a Processor struct around it and registers it to the dispatcher.
type Conn ¶
type Conn interface {
// 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.
// Returns the number of bytes sent and an error if any.
Send(Message) (uint64, 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() (*Envelope, 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
IsClosed() bool
// 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, msgType ...MessageTypeID)
// 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(MessageTypeID, func(*Envelope))
// Dispatch will find the right processor to dispatch the packet to. The id
// is the identity of the author / sender of the packet.
// 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(*Envelope) 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 Envelope ¶
type Envelope struct {
// The ServerIdentity of the remote peer we are talking to.
// Basically, this means that when you open a new connection to someone, and
// or listen to incoming connections, the network library will already
// make some exchange between the two communicants so each knows the
// ServerIdentity of the others.
ServerIdentity *ServerIdentity
// What kind of msg do we have
MsgType MessageTypeID
// A *pointer* to the underlying message
Msg Message
// which constructors are used
Constructors protobuf.Constructors
}
Envelope is a container for any Message received through the network that contains the Message itself as well as some metadata such as the type and the sender. This is created by the network stack upon reception and is never transmitted.
type Host ¶
type Host interface {
Listener
Connect(si *ServerIdentity) (Conn, error)
}
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 KCPConn ¶
type KCPConn struct {
// contains filtered or unexported fields
}
KCPConn implements the Conn interface using plain, unencrypted KCP.
func NewKCPConn ¶
NewKCPConn will open a KCPConn to the given address. In case of an error it returns a nil KCPConn and the error.
func (*KCPConn) 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 KCPHost ¶
type KCPHost struct {
*KCPListener
// contains filtered or unexported fields
}
KCPHost implements the Host interface using KCP connections.
func NewKCPHost ¶
func NewKCPHost(sid *ServerIdentity) (*KCPHost, error)
NewKCPHost returns a new Host using KCP connection based type.
func NewKCPHostWithListenAddr ¶
func NewKCPHostWithListenAddr(sid *ServerIdentity, listenAddr string) (*KCPHost, error)
NewKCPHostWithListenAddr returns a new Host using KCP connection based type listening on the given address.
type KCPListener ¶
type KCPListener struct {
// contains filtered or unexported fields
}
KCPListener implements the Host-interface using Kcp as a communication channel.
func NewKCPListener ¶
func NewKCPListener(addr Address) (*KCPListener, error)
NewKCPListener returns a KCPListener. This function binds globally using the port of 'addr'. 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.
func NewKCPListenerWithListenAddr ¶
func NewKCPListenerWithListenAddr(addr Address, listenAddr string) (*KCPListener, error)
NewKCPListenerWithListenAddr returns a KCPListener. This function binds to the given 'listenAddr'. If it is empty, the function binds globally using the port of 'addr'. 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.
func (*KCPListener) Address ¶
func (t *KCPListener) Address() Address
Address returns the listening address.
func (*KCPListener) Listen ¶
func (t *KCPListener) 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 (*KCPListener) Listening ¶
func (t *KCPListener) Listening() bool
Listening returns whether it's already listening.
func (*KCPListener) Stop ¶
func (t *KCPListener) 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.
type Listener ¶
type Listener interface {
// 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 Message ¶
type Message interface{}
Message is a type for any message that the user wants to send
type MessageTypeID ¶
MessageTypeID is the ID used to uniquely identify different registered messages
func MessageType ¶
func MessageType(msg Message) MessageTypeID
MessageType returns a Message's MessageTypeID if registered or ErrorType if the message has not been registered with RegisterMessage().
func RegisterMessage ¶
func RegisterMessage(msg Message) MessageTypeID
RegisterMessage registers any struct or ptr and returns the corresponding MessageTypeID. Once a struct is registered, it can be sent and received by the network library.
func RegisterMessages ¶
func RegisterMessages(msg ...Message) []MessageTypeID
RegisterMessages is a convenience function to register multiple messages together. It returns the MessageTypeIDs of the registered messages. If you give the same message more than once, it will register it only once, but return it's id as many times as it appears in the arguments.
func (MessageTypeID) Equal ¶
func (mId MessageTypeID) Equal(mID2 MessageTypeID) bool
Equal returns true if and only if mID2 equals this MessageTypeID
func (MessageTypeID) IsNil ¶
func (mId MessageTypeID) IsNil() bool
IsNil returns true iff the MessageTypeID is Nil
func (MessageTypeID) String ¶
func (mId MessageTypeID) String() string
String returns the name of the structure if it is known, else it returns the hexadecimal value of the Id.
type Processor ¶
type Processor interface {
// Process takes a received Envelope.
Process(*Envelope)
}
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 {
// id is our own ServerIdentity
ServerIdentity *ServerIdentity
// Dispatcher is used to dispatch incoming message to the right recipient
Dispatcher
sync.Mutex
// This field should only be set during testing. It disables an important
// log message meant to discourage KCP connections.
UnauthOk bool
// 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 NewKCPRouter(...), 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 NewKCPRouter ¶
func NewKCPRouter(sid *ServerIdentity) (*Router, error)
NewKCPRouter returns a new Router using KCPHost as the underlying Host.
func NewKCPRouterWithListenAddr ¶
func NewKCPRouterWithListenAddr(sid *ServerIdentity, listenAddr string) (*Router, error)
NewKCPRouterWithListenAddr returns a new Router using KCPHost with the given listen address as the underlying Host.
func NewRouter ¶
func NewRouter(own *ServerIdentity, h Host) *Router
NewRouter returns a new Router attached to a ServerIdentity and the host we want to use.
func (*Router) AddErrorHandler ¶
func (r *Router) AddErrorHandler(errorHandler func(*ServerIdentity))
AddErrorHandler adds a network error handler function for this router. The functions will be called on network error (e.g. Timeout, Connection Closed, or EOF) with the identity of the faulty remote host as 1st parameter.
func (*Router) AdjustConnect ¶
func (r *Router) AdjustConnect(mlist map[ServerIdentityID]bool)
AdjustConnect close all remote connects that not in mlist
func (*Router) CloseConnectByID ¶
func (r *Router) CloseConnectByID(id ServerIdentityID)
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) GetBlocks ¶
func (r *Router) GetBlocks(e *ServerIdentity) int
func (*Router) Pause ¶
func (r *Router) Pause()
Pause casues the router to stop after reading the next incoming message. It sleeps until it is woken up by Unpause. For testing use only.
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.
func (*Router) Stop ¶
Stop the listening routine, and stop any routine of handling connections. Calling r.Start(), then r.Stop() then r.Start() again leads to an undefined behaviour. Callers should most of the time re-create a fresh Router.
type RoutineDispatcher ¶
type RoutineDispatcher struct {
*BlockingDispatcher
// contains filtered or unexported fields
}
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
func (*RoutineDispatcher) Dispatch ¶
func (d *RoutineDispatcher) Dispatch(packet *Envelope) error
Dispatch implements the Dispatcher interface. It will give the packet to the right Processor in a go routine.
func (*RoutineDispatcher) GetRoutines ¶
func (d *RoutineDispatcher) GetRoutines() int
GetRoutines returns how many routines are waiting.
type ServerIdentity ¶
type ServerIdentity struct {
// The ServerIdentityID corresponding to that address key
ID ServerIdentityID
// A slice of addresses of where that Id might be found
Address Address
// Description of the server
Description string
}
ServerIdentity is used to represent a Server in the whole internet. It's based on a address key, and there can be one or more addresses to contact it.
func NewServerIdentity ¶
func NewServerIdentity(address string) *ServerIdentity
NewServerIdentity creates a new ServerIdentity based on a address key and with a slice of IP-addresses where to find that entity. The Id is based on a version5-UUID which can include a URL that is based on it's address key.
func (*ServerIdentity) String ¶
func (si *ServerIdentity) String() string
type ServerIdentityID ¶
ServerIdentityID uniquely identifies an ServerIdentity struct
func (ServerIdentityID) Equal ¶
func (eId ServerIdentityID) Equal(other ServerIdentityID) bool
Equal returns true if both ServerIdentityID are equal or false otherwise.
func (ServerIdentityID) IsNil ¶
func (eId ServerIdentityID) IsNil() bool
IsNil returns true iff the ServerIdentityID is Nil
func (ServerIdentityID) String ¶
func (eId ServerIdentityID) String() string
String returns a canonical representation of the ServerIdentityID.
Source Files