msngr

README

Messenger

Messenger provides a simple arbitrary message sending API to multiple peers for libp2p-based protocols. The main purpose is to bootstrap development for new protocols and decrease boilerplate code.

Features

• Simple non-blocking API
• Not a protocol - sends only user's data without message wrapping on the wire
• Not a framework - use it anyhow
• Ready for generics

Background

The libp2p provides all necessary primitives to build custom fully decentralized p2p protocols. Also, it is solely stream-based for reasons, but in practice, the vast majority of libp2p based protocols are message-based, with messages sent over reliable and multiplexed streams.

Mainly, there are two typical patterns for message sending over streams.

Request/Response

The most popular pattern in libp2p protocols is sending requests over a fresh stream and waiting for a response with a subsequent closing. Using libp2p's bare Stream API is trivial for such a case, which also explains why it is the most popular pattern.

'Fire and Forget'

Another less common pattern in libp2p protocols is sending messages without expecting a response. Once instantiated, a protocol establishes a unique and persistent stream with a remote endpoint and only sends messages over it. This pattern optimizes protocols by removing unnecessary stream negotiations, which are primarily expensive for round trips.

Motivations

• Provide reusable utility for common use-cases in libp2p protocol development.

  • Even for simple Request/Response pattern, there is some level of boilerplate that can be avoided (Examples: Bitswap, kadDHT)

    Currently, the Messenger does not provide a Request/Response semantics, and the main focus is 'fire and forget'.

  • 'Fire and Forget' is more complex. It can be implemented in multiple ways, has undesirable edge cases, and requires a more profound knowledge of the libp2p stack. Although the pattern is an interesting engineering challenge to solve, in business and rapidly changing environments, it is easier to reuse existing instruments, like Messenger.

• Lower entrance threshold for new developers exploring decentralization and p2p networking.

• Bootstrap migration of Tendermint over libp2p.

  Tendermint is the first and most popular BFT consensus implementation, and it is decentralized and requires p2p networking. The project's team, through time, developed an in-house solution for it. However, they are now committed to migration over libp2p.

  Tendermint is a towering stack of multiple sub-protocols(or their terms - reactors) which rely on patterns explained above. Therefore, a lesser code boilerplate and simple API would be convenient for such migration.

  Technically, Tendermint p2p stack only supports 'fire and forget' pattern, but a few sub-protocols can benefit from migration to Request/Response pattern.

Documentation

See these docs.

License

Apache-2.0.

Documentation

Index

• type Messenger
  • func New(host host.Host, opts ...Option) (*Messenger, error)
  • func (m *Messenger) Broadcast(ctx context.Context, out serde.Message) (peer.IDSlice, error)
  • func (m *Messenger) Close() error
  • func (m *Messenger) Host() host.Host
  • func (m *Messenger) Peers() []peer.ID
  • func (m *Messenger) Receive(ctx context.Context) (serde.Message, peer.ID, error)
  • func (m *Messenger) Send(ctx context.Context, out serde.Message, to peer.ID) error
• type Option
  • func WithMessageType(msg serde.Message) Option
  • func WithProtocols(pids ...protocol.ID) Option

Types

type Messenger

type Messenger struct {
	// contains filtered or unexported fields
}

Messenger provides a simple API to send messages to multiple peers.

func New

func New(host host.Host, opts ...Option) (*Messenger, error)

New instantiates a Messenger. WithProtocols option is mandatory for at least one protocol. WithMessageType overrides default serde.PlainMessage.

func (*Messenger) Broadcast

func (m *Messenger) Broadcast(ctx context.Context, out serde.Message) (peer.IDSlice, error)

Broadcast optimistically sends the given message 'out' to each connected peer speaking *the same* protocol. It returns a slice od peers to whom the message was sent and errors in case the given ctx was closed or in case when Messenger is closed. WARNING: It should be used deliberately. Avoid use cases requiring message propagation to a whole protocol network,

not to flood the network with message duplicates. For such cases use libp2p.PubSub instead.

func (*Messenger) Close

func (m *Messenger) Close() error

Close stops the Messenger and unregisters further protocol handling on the Host.

func (*Messenger) Host

func (m *Messenger) Host() host.Host

Host is a getter for the Host.

func (*Messenger) Peers

func (m *Messenger) Peers() []peer.ID

Peers returns a list of connected/immediate peers speaking the protocol registered on the Messenger.

func (*Messenger) Receive

func (m *Messenger) Receive(ctx context.Context) (serde.Message, peer.ID, error)

Receive awaits for incoming messages from peers. It receives messages sent through both Send and Broadcast. It errors only if the given context 'ctx' is closed or when Messenger is closed.

func (*Messenger) Send

func (m *Messenger) Send(ctx context.Context, out serde.Message, to peer.ID) error

Send optimistically sends the given message 'out' to the peer 'to'. It errors in case the given ctx was closed or in case when Messenger is closed. All messages are sent in a per peer queue, so the ordering of sent messages is guaranteed. In case the Messenger is given with a RoutedHost, It tries to connect to the peer, if not connected.

type Option

type Option func(messenger *Messenger)

Option defines an functional configurability for Messenger.

func WithMessageType

func WithMessageType(msg serde.Message) Option

WithMessageType sets a custom message type for receiving messages. Otherwise Messenger would not know what type to return in Receive.

func WithProtocols

func WithProtocols(pids ...protocol.ID) Option

WithProtocols sets custom protocols for messenger to speak with At least one protocol is required.