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 'life0: 'async_trait,
Self: 'async_trait;
fn close_substream<'life0, 'async_trait>(
&'life0 mut self,
peer: PeerId,
) -> Pin<Box<dyn Future<Output = Result<(), ()>> + Send + 'async_trait>>
where 'life0: 'async_trait,
Self: '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 'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait;
fn set_handshake<'life0, 'async_trait>(
&'life0 mut self,
handshake: Vec<u8>,
) -> Pin<Box<dyn Future<Output = Result<(), ()>> + Send + 'async_trait>>
where 'life0: 'async_trait,
Self: '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 'life0: 'async_trait,
Self: 'async_trait;
fn clone(&mut self) -> Result<Box<dyn NotificationService>, ()>;
fn protocol(&self) -> &ProtocolName;
fn message_sink(&self, peer: &PeerId) -> Option<Box<dyn MessageSink>>;
}
Expand description
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
'life0: 'async_trait,
Self: 'async_trait,
fn open_substream<'life0, 'async_trait>(
&'life0 mut self,
peer: PeerId,
) -> Pin<Box<dyn Future<Output = Result<(), ()>> + Send + 'async_trait>>where
'life0: 'async_trait,
Self: '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
'life0: 'async_trait,
Self: 'async_trait,
fn close_substream<'life0, 'async_trait>(
&'life0 mut self,
peer: PeerId,
) -> Pin<Box<dyn Future<Output = Result<(), ()>> + Send + 'async_trait>>where
'life0: 'async_trait,
Self: 'async_trait,
Instruct Notifications
to close substream for peer
.
fn send_sync_notification(&mut self, peer: &PeerId, notification: Vec<u8>)
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
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait,
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
'life0: 'async_trait,
'life1: 'async_trait,
Self: '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
'life0: 'async_trait,
Self: 'async_trait,
fn set_handshake<'life0, 'async_trait>(
&'life0 mut self,
handshake: Vec<u8>,
) -> Pin<Box<dyn Future<Output = Result<(), ()>> + Send + 'async_trait>>where
'life0: 'async_trait,
Self: 'async_trait,
Set handshake for the notification protocol replacing the old handshake.
fn try_set_handshake(&mut self, handshake: Vec<u8>) -> Result<(), ()>
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
'life0: 'async_trait,
Self: 'async_trait,
fn next_event<'life0, 'async_trait>(
&'life0 mut self,
) -> Pin<Box<dyn Future<Output = Option<NotificationEvent>> + Send + 'async_trait>>where
'life0: 'async_trait,
Self: 'async_trait,
Get next event from the Notifications
event stream.
fn clone(&mut self) -> Result<Box<dyn NotificationService>, ()>
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
fn protocol(&self) -> &ProtocolName
Get protocol name of the NotificationService
.
fn message_sink(&self, peer: &PeerId) -> Option<Box<dyn MessageSink>>
fn message_sink(&self, peer: &PeerId) -> Option<Box<dyn MessageSink>>
Get message sink of the peer.