memberlist_net/
stream_layer.rs

1use std::{future::Future, io, net::SocketAddr};
2
3use agnostic::RuntimeLite;
4
5/// `StreamLayer` implementations based on TCP.
6pub mod tcp;
7
8/// `StreamLayer` implementations based on [`rustls`](https://crates.io/crates/rustls).
9#[cfg(feature = "tls")]
10#[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
11pub mod tls;
12
13/// Represents a network listener.
14///
15/// This trait defines the operations required for a network listener that can bind to an address,
16/// accept incoming connections, and query its local address.
17pub trait Listener: Send + Sync + 'static {
18  /// The type of the network stream associated with this listener.
19  type Stream: PromisedStream;
20
21  /// Accepts an incoming connection.
22  fn accept(&self) -> impl Future<Output = io::Result<(Self::Stream, SocketAddr)>> + Send;
23
24  /// Retrieves the local socket address of the listener.
25  fn local_addr(&self) -> SocketAddr;
26
27  /// Shuts down the listener.
28  fn shutdown(&self) -> impl Future<Output = io::Result<()>> + Send;
29}
30
31/// Represents a network connection.
32///
33/// This trait encapsulates functionality for a network connection that supports asynchronous
34/// read/write operations and can be split into separate read and write halves.
35pub trait PromisedStream:
36  memberlist_core::transport::Connection + Unpin + Send + Sync + 'static
37{
38  /// The instant type
39  type Instant: agnostic::time::Instant + Send + Sync + 'static;
40
41  /// Returns the address of the local endpoint of the connection.
42  fn local_addr(&self) -> SocketAddr;
43
44  /// Returns the address of the remote endpoint of the connection.
45  fn peer_addr(&self) -> SocketAddr;
46}
47
48/// A trait defining the necessary components for a stream-based network layer.
49/// This layer must promise a reliable, ordered, and bi-directional stream of data, e.g. TCP, QUIC, gRPC and etc.
50///
51/// This trait is used in conjunction with [`NetTransport`](super::NetTransport) to provide
52/// an abstraction over the underlying network stream. It specifies the types for listeners
53/// and connections that operate on this stream.
54pub trait StreamLayer: Send + Sync + 'static {
55  /// The runtime for this stream layer
56  type Runtime: RuntimeLite;
57
58  /// The listener type for the network stream.
59  type Listener: Listener<Stream = Self::Stream>;
60
61  /// The connection type for the network stream.
62  type Stream: PromisedStream<Instant = <Self::Runtime as RuntimeLite>::Instant>;
63
64  /// The options type for constructing the stream layer.
65  type Options: Send + Sync + 'static;
66
67  /// Creates a new instance of the stream layer with the given options.
68  fn new(options: Self::Options) -> impl Future<Output = io::Result<Self>> + Send
69  where
70    Self: Sized;
71
72  /// Establishes a connection to a specified socket address.
73  fn connect(&self, addr: SocketAddr) -> impl Future<Output = io::Result<Self::Stream>> + Send;
74
75  /// Binds the listener to a given socket address.
76  fn bind(&self, addr: SocketAddr) -> impl Future<Output = io::Result<Self::Listener>> + Send;
77
78  /// Indicates whether the connection is secure.
79  ///
80  /// This method returns `true` if the connection is considered secure, which means
81  /// no additional encryption is applied for the promised stream by the transport layer.
82  ///
83  /// # Returns
84  /// `true` if the connection is secure (e.g., TLS), `false` otherwise (e.g., TCP).
85  fn is_secure() -> bool;
86}
memberlist_net/stream_layer.rs

memberlist_net/
stream_layer.rs
