net

Documentation

Index

• type BroadcastChannel
• type BroadcastChannelFilter
• type ConnectionManager
• type Firewall
• type Message
• type Provider
• type TaggedMarshaler
• type TaggedUnmarshaler
• type TransportIdentifier
• type UnicastChannel

Types

type BroadcastChannel

type BroadcastChannel interface {
	// Name returns the name of this broadcast channel.
	Name() string
	// Send function publishes a message m to the channel. Message m needs to
	// conform to the marshalling interface. Message will be periodically
	// retransmitted by the channel for the lifetime of the provided context.
	Send(ctx context.Context, m TaggedMarshaler) error
	// Recv installs a message handler that will receive messages from the
	// channel for the entire lifetime of the provided context.
	// When the context is done, handler is automatically unregistered and
	// receives no more messages. Already received message retransmissions are
	// filtered out before calling the handler.
	Recv(ctx context.Context, handler func(m Message))
	// RegisterUnmarshaler registers an unmarshaler that will unmarshal a given
	// type to a concrete object that can be passed to and understood by any
	// registered message handling functions. The unmarshaler should be a
	// function that returns a fresh object of type proto.TaggedUnmarshaler,
	// ready to read in the bytes for an object marked as tpe.
	//
	// The string type associated with the unmarshaler is the result of calling
	// Type() on a raw unmarshaler.
	RegisterUnmarshaler(unmarshaler func() TaggedUnmarshaler) error
	// SetFilter registers a broadcast channel filter which will be used
	// to determine if given broadcast channel message should be processed
	// by the receivers.
	SetFilter(filter BroadcastChannelFilter) error
}

BroadcastChannel represents a named pubsub channel. It allows group members to broadcast and receive messages. BroadcastChannel implements strategy for the retransmission of broadcast messages and handle duplicates before passing the received message to the client.

type BroadcastChannelFilter

type BroadcastChannelFilter func(*ecdsa.PublicKey) bool

BroadcastChannelFilter represents a filter which determine if the incoming message should be processed by the receivers. It takes the message author's public key as its argument and returns true if the message should be processed or false otherwise.

type ConnectionManager

type ConnectionManager interface {
	ConnectedPeers() []string
	GetPeerPublicKey(connectedPeer string) (*key.NetworkPublic, error)
	DisconnectPeer(connectedPeer string)

	// AddrStrings returns all listen addresses of the provider.
	AddrStrings() []string
}

ConnectionManager is an interface which exposes peers a client is connected to, and their individual identities, so that a client may forcibly disconnect from any given connected peer.

type Firewall

type Firewall interface {

	// Validate takes the remote peer public key and executes all the checks
	// needed to decide whether the connection with the remote peer can be
	// approved.
	// If expectations are not met, this function should return an error
	// describing what is wrong.
	Validate(remotePeerPublicKey *ecdsa.PublicKey) error
}

Firewall represents a set of rules the remote peer has to conform to so that a connection with that peer can be approved.

type Message

type Message interface {
	TransportSenderID() TransportIdentifier
	SenderPublicKey() []byte

	Payload() interface{}

	Type() string
	Seqno() uint64
}

Message represents a message exchanged within the network layer. It carries a sender id for the transport layer and, if available, for the protocol layer. It also carries an unmarshaled payload.

type Provider

type Provider interface {
	// ID returns provider identifier.
	ID() TransportIdentifier
	// Type gives an information about provider type.
	Type() string

	// UnicastChannelWith provides a unicast channel instance with given peer.
	UnicastChannelWith(peerID TransportIdentifier) (UnicastChannel, error)
	// OnUnicastChannelOpened allows to register a channel handler which will
	// be invoked when a new unicast channel will be opened.
	OnUnicastChannelOpened(handler func(channel UnicastChannel))

	// BroadcastChannelFor provides a broadcast channel instance for given
	// channel name.
	BroadcastChannelFor(name string) (BroadcastChannel, error)

	// ConnectionManager returns the connection manager used by the provider.
	ConnectionManager() ConnectionManager

	// CreateTransportIdentifier creates a transport identifier based on the
	// provided public key.
	CreateTransportIdentifier(publicKey ecdsa.PublicKey) (TransportIdentifier, error)

	// BroadcastChannelForwarderFor creates a message relay for given channel name.
	BroadcastChannelForwarderFor(name string)
}

Provider represents an entity that can provide network access.

Providers expose the ability to get a named BroadcastChannel, the ability to return a provider type, which is an informational string indicating what type of provider this is, the list of IP addresses on which it can listen, and known peers from peer discovery mechanims.

type TaggedMarshaler

type TaggedMarshaler interface {
	proto.Marshaler
	Type() string
}

TaggedMarshaler is an interface that includes the proto.Marshaler interface, but also provides a string type for the marshalable object.

type TaggedUnmarshaler

type TaggedUnmarshaler interface {
	proto.Unmarshaler
	Type() string
}

TaggedUnmarshaler is an interface that includes the proto.Unmarshaler interface, but also provides a string type for the unmarshalable object. The Type() method is expected to be invokable on a just-initialized instance of the unmarshaler (i.e., before unmarshaling is completed).

type TransportIdentifier

type TransportIdentifier interface {
	String() string
}

TransportIdentifier represents a protocol-level identifier. It is an opaque type to the network layer.

type UnicastChannel

type UnicastChannel interface {
	// Send function publishes a message m to the channel. Message m needs to
	// conform to the marshalling interface.
	Send(m TaggedMarshaler) error
	// Recv installs a message handler that will receive messages from the
	// channel for the entire lifetime of the provided context.
	// When the context is done, handler is automatically unregistered and
	// receives no more messages.
	Recv(ctx context.Context, handler func(m Message))
	// SetUnmarshaler set an unmarshaler that will unmarshal a given
	// type to a concrete object that can be passed to and understood by any
	// registered message handling functions. The unmarshaler should be a
	// function that returns a fresh object of type proto.TaggedUnmarshaler,
	// ready to read in the bytes for an object marked as tpe.
	//
	// The string type associated with the unmarshaler is the result of calling
	// Type() on a raw unmarshaler.
	SetUnmarshaler(unmarshaler func() TaggedUnmarshaler)
}

UnicastChannel represents a bidirectional communication channel between two network peers.

Every implementation must fulfill the following guarantees:

1. If the channel was opened without errors, the communication is possible.
2. Communication is performed through a direct connection.
3. If a message was sent with no errors, it was received by the remote peer on the network level. Though, it does not guarantee that the remote peer handled that message.