Trait sc_network::service::traits::NotificationService
source · 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>>;
}
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§
sourcefn 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 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
sourcefn 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 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
.
sourcefn 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
.
sourcefn 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 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.
sourcefn 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 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.
sourcefn 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.
sourcefn 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 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.
sourcefn 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.
sourcefn protocol(&self) -> &ProtocolName
fn protocol(&self) -> &ProtocolName
Get protocol name of the NotificationService
.
sourcefn 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.