Trait NotificationService

pub trait NotificationService: Debug + Send {
    // Required methods
    fn open_substream<'life0, 'async_trait>(
        &'life0 mut self,
        peer: PeerId,
    ) -> Pin<Box<dyn Future<Output = Result<(), ()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn close_substream<'life0, 'async_trait>(
        &'life0 mut self,
        peer: PeerId,
    ) -> Pin<Box<dyn Future<Output = Result<(), ()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn send_sync_notification(&mut self, peer: &PeerId, notification: Vec<u8>);
    fn send_async_notification<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        peer: &'life1 PeerId,
        notification: Vec<u8>,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn set_handshake<'life0, 'async_trait>(
        &'life0 mut self,
        handshake: Vec<u8>,
    ) -> Pin<Box<dyn Future<Output = Result<(), ()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn try_set_handshake(&mut self, handshake: Vec<u8>) -> Result<(), ()>;
    fn next_event<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Option<NotificationEvent>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn clone(&mut self) -> Result<Box<dyn NotificationService>, ()>;
    fn protocol(&self) -> &ProtocolName;
    fn message_sink(&self, peer: &PeerId) -> Option<Box<dyn MessageSink>>;
}

Notification service

Defines behaviors that both the protocol implementations and Notifications can expect from each other.

Notifications can send two different kinds of information to protocol:

• substream-related information
• notification-related information

When an unvalidated, inbound substream is received by Notifications, it sends the inbound stream information (peer ID, handshake) to protocol for validation. Protocol must then verify that the handshake is valid (and in the future that it has a slot it can allocate for the peer) and then report back the ValidationResult which is either Accept or Reject.

After the validation result has been received by Notifications, it prepares the substream for communication by initializing the necessary sinks and emits NotificationStreamOpened which informs the protocol that the remote peer is ready to receive notifications.

Two different flavors of sending options are provided:

• synchronous sending (NotificationService::send_sync_notification())
• asynchronous sending (NotificationService::send_async_notification())

The former is used by the protocols not ready to exercise backpressure and the latter by the protocols that can do it.

Both local and remote peer can close the substream at any time. Local peer can do so by calling NotificationService::close_substream() which instructs Notifications to close the substream. Remote closing the substream is indicated to the local peer by receiving NotificationEvent::NotificationStreamClosed event.

In case the protocol must update its handshake while it’s operating (such as updating the best block information), it can do so by calling NotificationService::set_handshake() which instructs Notifications to update the handshake it stored during protocol initialization.

All peer events are multiplexed on the same incoming event stream from Notifications and thus each event carries a PeerId so the protocol knows whose information to update when receiving an event.

Required Methods

fn open_substream<'life0, 'async_trait>( &'life0 mut self, peer: PeerId, ) -> Pin<Box<dyn Future<Output = Result<(), ()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Instruct Notifications to open a new substream for peer.

dial_if_disconnected informs Notifications whether to dial

fn close_substream<'life0, 'async_trait>( &'life0 mut self, peer: PeerId, ) -> Pin<Box<dyn Future<Output = Result<(), ()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Instruct Notifications to close substream for peer.

fn send_sync_notification(&mut self, peer: &PeerId, notification: Vec<u8>)

Send synchronous notification to peer.

fn send_async_notification<'life0, 'life1, 'async_trait>( &'life0 mut self, peer: &'life1 PeerId, notification: Vec<u8>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Send asynchronous notification to peer, allowing sender to exercise backpressure.

Returns an error if the peer doesn’t exist.

fn set_handshake<'life0, 'async_trait>( &'life0 mut self, handshake: Vec<u8>, ) -> Pin<Box<dyn Future<Output = Result<(), ()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Set handshake for the notification protocol replacing the old handshake.

fn try_set_handshake(&mut self, handshake: Vec<u8>) -> Result<(), ()>

Non-blocking variant of set_handshake() that attempts to update the handshake and returns an error if the channel is blocked.

Technically the function can return an error if the channel to Notifications is closed but that doesn’t happen under normal operation.

fn next_event<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Option<NotificationEvent>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get next event from the Notifications event stream.

fn clone(&mut self) -> Result<Box<dyn NotificationService>, ()>

Make a copy of the object so it can be shared between protocol components who wish to have access to the same underlying notification protocol.

fn protocol(&self) -> &ProtocolName

Get protocol name of the NotificationService.

fn message_sink(&self, peer: &PeerId) -> Option<Box<dyn MessageSink>>

Get message sink of the peer.

Implementors