Documentation
¶
Overview ¶
Package network is a networking library used in the SDA. You have Hosts which can issue connections to others hosts, and Conn which are the connections itself. Hosts and Conns are interfaces and can be of type Tcp, or Chans, or Udp or whatever protocols you think might implement this interface. In this library we also provide a way to encode / decode any kind of packet / structs. When you want to send a struct to a conn, you first register (one-time operation) this packet to the library, and then directly pass the pointer to the struct itself to the conn that will recognize its type. When decoding, it will automatically detect the underlying type of struct given, and decode it accordingly. You can provide your own decode / encode methods if for example, you have a variable length packet structure. Since this library uses gopkg.in/dedis/protobuf.v0 library for encoding, you just have to implement MarshalBinary or UnmarshalBinary.
Index ¶
- Constants
- Variables
- func DefaultConstructors(suite abstract.Suite) protobuf.Constructors
- func DumpTypes()
- func GlobalBind(address string) (string, error)
- func MarshalRegisteredType(data ProtocolMessage) ([]byte, error)
- func UnmarshalRegisteredType(buf []byte, constructors protobuf.Constructors) (MessageTypeID, ProtocolMessage, error)
- type Conn
- type Entity
- type EntityID
- type EntityToml
- type Host
- type Message
- type MessageTypeID
- func RTypeToMessageTypeID(msg reflect.Type) MessageTypeID
- func RegisterMessageType(msg ProtocolMessage) MessageTypeID
- func RegisterMessageUUID(mt MessageTypeID, rt reflect.Type) MessageTypeID
- func TypeFromData(msg ProtocolMessage) MessageTypeID
- func TypeToMessageTypeID(msg ProtocolMessage) MessageTypeID
- type ProtocolMessage
- type SecureConn
- type SecureHost
- type SecureTCPConn
- type SecureTCPHost
- type Size
- type TCPConn
- type TCPHost
Constants ¶
const MaxRetry = 10
MaxRetry defines how many times should we try to connect
const NamespaceProtocolMessageType = NamespaceURL + "/protocolType/"
NamespaceProtocolMessageType is the namespace used for MessageTypeID
const NamespaceURL = "https://dedis.epfl.ch/"
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 = 100 * time.Millisecond
WaitRetry defines how much time should we wait before trying again
Variables ¶
var EmptyApplicationMessage = Message{MsgType: MessageTypeID(uuid.Nil)}
EmptyApplicationMessage is the default empty message that is returned in case something went wrong.
FIXME currently there seems no way with go1.6 for this to compile without repeating the definition of ErrorType above as MessageTypeID(uuid.Nil). Somehow it still gets inlined (maybe through the indirection). should be fixed properly in go1.7: https://github.com/golang/go/commit/feb2a5d6103dad76b6374c5f346e33d55612cb2a
var EntityType = RegisterMessageType(Entity{})
EntityType can be used to recognise an Entity-message
var ErrCanceled = errors.New("Operation Canceled")
ErrCanceled means something went wrong with the sending or receiving
var ErrClosed = errors.New("Connection Closed")
ErrClosed is when a connection has been closed
var ErrEOF = errors.New("EOF")
ErrEOF is when the EOF signal comes to the connection (mostly means that it is shutdown)
var ErrTemp = errors.New("Temporary Error")
ErrTemp is a temporary error
var ErrTimeout = errors.New("Timeout Error")
ErrTimeout is raised if the connection has set a timeout on read or write, and the operation lasted longer
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 Suite = edwards.NewAES128SHA256Ed25519(false)
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 DefaultConstructors ¶
DefaultConstructors gives a default constructor for protobuf out of the global suite
func GlobalBind ¶
GlobalBind returns the global-binding address
func MarshalRegisteredType ¶
func MarshalRegisteredType(data ProtocolMessage) ([]byte, error)
MarshalRegisteredType will marshal a struct with its respective type into a slice of bytes. That slice of bytes can be then decoded in UnmarshalRegisteredType.
func UnmarshalRegisteredType ¶
func UnmarshalRegisteredType(buf []byte, constructors protobuf.Constructors) (MessageTypeID, ProtocolMessage, error)
UnmarshalRegisteredType returns the type, the data and an error trying to decode a message from a buffer. The type must be registered to the network library in order to be decodable.
Types ¶
type Conn ¶
type Conn interface {
// Gives the address of the remote endpoint
Remote() string
// Returns the local address and port
Local() string
// Send a message through the connection. Always pass a pointer !
Send(ctx context.Context, obj ProtocolMessage) error
// Receive any message through the connection.
Receive(ctx context.Context) (Message, error)
Close() error
monitor.CounterIO
}
Conn is the basic interface to represent any communication mean between two host. It is closely related to the underlying type of Host since a TcpHost will generate only TcpConn
type Entity ¶
type Entity struct {
// This is the public key of that Entity
Public abstract.Point
// The EntityID corresponding to that public key
ID EntityID
// A slice of addresses of where that Id might be found
Addresses []string
// contains filtered or unexported fields
}
Entity is used to represent a Conode in the whole internet. It's based on a public key, and there can be one or more addresses to contact it.
func NewEntity ¶
NewEntity creates a new Entity based on a public 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 public key.
type EntityToml ¶
EntityToml is the struct that can be marshalled into a toml file
type Host ¶
type Host interface {
Open(name string) (Conn, error)
Listen(addr string, fn func(Conn)) error // the srv processing function
Close() error
monitor.CounterIO
}
Host is the basic interface to represent a Host of any kind Host can open new Conn(ections) and Listen for any incoming Conn(...)
type Message ¶
type Message struct {
// The Entity of the remote peer we are talking to.
// Basically, this means that when you open a new connection to someone, and
// / or listens to incoming connections, the network library will already
// make some exchange between the two communicants so each knows the
// Entity of the others.
Entity *Entity
// the origin of the message
From string
// What kind of msg do we have
MsgType MessageTypeID
// The underlying message
Msg ProtocolMessage
// which constructors are used
Constructors protobuf.Constructors
// contains filtered or unexported fields
}
Message is the container for any NetworkMessage
func NewNetworkMessage ¶
func NewNetworkMessage(obj ProtocolMessage) (*Message, error)
ConstructFrom takes a ProtocolMessage and then constructs a Message from it. Error if the type is unknown
func (*Message) Error ¶
Error returns the error that has been encountered during the unmarshaling of this message.
func (*Message) MarshalBinary ¶
MarshalBinary the application message => to bytes Implements BinaryMarshaler interface so it will be used when sending with protobuf
func (*Message) SetError ¶
SetError is workaround so we can set the error after creation of the application message
func (*Message) UnmarshalBinary ¶
UnmarshalBinary will decode the incoming bytes It uses protobuf for decoding (using the constructors in the NetworkMessage).
type MessageTypeID ¶
type MessageTypeID uuid.UUID
MessageTypeID is the ID used to uniquely identify different registered messages
func RTypeToMessageTypeID ¶
func RTypeToMessageTypeID(msg reflect.Type) MessageTypeID
RTypeToMessageTypeID converts a reflect.Type to a MessageTypeID
func RegisterMessageType ¶
func RegisterMessageType(msg ProtocolMessage) MessageTypeID
RegisterMessageType registers a custom "struct" / "packet" and returns the corresponding MessageTypeID. Simply pass your non-initialized struct.
func RegisterMessageUUID ¶
func RegisterMessageUUID(mt MessageTypeID, rt reflect.Type) MessageTypeID
RegisterMessageUUID can be used if the uuid and the type is already known NOTE: be sure to only registers VALUE message and not POINTERS to message.
func TypeFromData ¶
func TypeFromData(msg ProtocolMessage) MessageTypeID
TypeFromData returns the MessageTypeID corresponding to the given structure. It returns 'ErrorType' if the type wasn't found or an error occurred.
func TypeToMessageTypeID ¶
func TypeToMessageTypeID(msg ProtocolMessage) MessageTypeID
TypeToMessageTypeID converts a ProtocolMessage to a MessageTypeID
func (MessageTypeID) String ¶
func (mId MessageTypeID) String() string
String returns the canonical string representation of the MessageTypeID
type ProtocolMessage ¶
type ProtocolMessage interface{}
ProtocolMessage is a type for any message that the user wants to send
type SecureConn ¶
SecureConn is the analog of Conn but for secure communication
type SecureHost ¶
type SecureHost interface {
// Close terminates the `Listen()` function and closes all connections.
Close() error
Listen(func(SecureConn)) error
Open(*Entity) (SecureConn, error)
String() string
monitor.CounterIO
}
SecureHost is the analog of Host but with secure communication It is tied to an entity can only open connection with entities
type SecureTCPConn ¶
type SecureTCPConn struct {
*TCPConn
*SecureTCPHost
// contains filtered or unexported fields
}
SecureTCPConn is a secured tcp connection using Entity as an identity.
func (*SecureTCPConn) Entity ¶
func (sc *SecureTCPConn) Entity() *Entity
Entity returns the underlying entity tied to this connection
func (*SecureTCPConn) Receive ¶
func (sc *SecureTCPConn) Receive(ctx context.Context) (Message, error)
Receive is analog to Conn.Receive but also set the right Entity in the message
func (*SecureTCPConn) Rx ¶
func (sc *SecureTCPConn) Rx() uint64
Rx implements the CounterIO interface
func (*SecureTCPConn) Tx ¶
func (sc *SecureTCPConn) Tx() uint64
Tx implements the CounterIO interface
type SecureTCPHost ¶
type SecureTCPHost struct {
*TCPHost
// contains filtered or unexported fields
}
SecureTCPHost is a TcpHost but with the additional property that it handles Entity.
func NewSecureTCPHost ¶
func NewSecureTCPHost(private abstract.Secret, e *Entity) *SecureTCPHost
NewSecureTCPHost returns a Secure Tcp Host If the entity is nil, it will not verify the identity of the remote host
func (*SecureTCPHost) Listen ¶
func (st *SecureTCPHost) Listen(fn func(SecureConn)) error
Listen will try each addresses it the host Entity. Returns an error if it can listen on any address
func (*SecureTCPHost) Open ¶
func (st *SecureTCPHost) Open(e *Entity) (SecureConn, error)
Open will try any address that is in the Entity and connect to the first one that works. Then it exchanges the Entity to verify it is talking with the right host.
func (*SecureTCPHost) Rx ¶
func (st *SecureTCPHost) Rx() uint64
Rx implements the CounterIO interface
func (*SecureTCPHost) String ¶
func (st *SecureTCPHost) String() string
String returns a string identifying that host
func (*SecureTCPHost) Tx ¶
func (st *SecureTCPHost) Tx() uint64
Tx implements the CounterIO interface
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 {
// The name of the endpoint we are connected to.
Endpoint string
// contains filtered or unexported fields
}
TCPConn is the underlying implementation of Conn using Tcp
func (*TCPConn) Receive ¶
Receive waits for any input on the connection and returns the ApplicationMessage **decoded** and an error if something wrong occured
func (*TCPConn) Rx ¶
Rx returns the number of bytes read by this connection Needed so TCPConn implements the CounterIO interface from lib/monitor
type TCPHost ¶
type TCPHost struct {
// contains filtered or unexported fields
}
TCPHost is the underlying implementation of Host using Tcp as a communication channel
func NewTCPHost ¶
func NewTCPHost() *TCPHost
NewTCPHost returns a Fresh TCP Host If constructors == nil, it will take an empty one.
func (*TCPHost) Listen ¶
Listen for any host trying to contact him. Will launch in a goroutine the srv function once a connection is established
func (*TCPHost) Open ¶
Open will create a new connection between this host and the remote host named "name". This is a TCPConn. If anything went wrong, Conn will be nil.
Source Files