pub struct NetworkEngine<M> { /* private fields */ }Expand description
A generic peer-to-peer network engine on top of Iroh.
M is the application-defined domain message type; the engine treats it
as an opaque, postcard-serializable payload. The engine is cheaply
clonable: all clones share the same endpoint and connection registry.
Implementations§
Source§impl<M: Message> NetworkEngine<M>
impl<M: Message> NetworkEngine<M>
Sourcepub async fn start(
config: NetworkConfig,
) -> Result<(Self, NetworkEventReceiver<M>)>
pub async fn start( config: NetworkConfig, ) -> Result<(Self, NetworkEventReceiver<M>)>
Starts the engine: loads (or creates) the persistent identity, binds the Iroh endpoint and starts accepting connections.
Returns the engine handle together with the single receiver for
NetworkEvents.
Sourcepub async fn start_with_secret_key(
config: NetworkConfig,
secret_key: SecretKey,
) -> Result<(Self, NetworkEventReceiver<M>)>
pub async fn start_with_secret_key( config: NetworkConfig, secret_key: SecretKey, ) -> Result<(Self, NetworkEventReceiver<M>)>
Starts the engine with an application-provided identity key.
Use this when the caller already stores the peer identity in durable
application storage. The regular NetworkEngine::start method
remains the file-backed default.
Sourcepub fn endpoint_id(&self) -> EndpointId
pub fn endpoint_id(&self) -> EndpointId
Returns the stable identifier of this peer.
Sourcepub fn sign_identity(&self, message: &[u8]) -> Signature
pub fn sign_identity(&self, message: &[u8]) -> Signature
Signs application data with this peer’s persistent transport identity.
The secret key never leaves the engine. Protocols can attach the
returned signature to records that may be forwarded by other peers;
recipients verify it against Self::endpoint_id.
Sourcepub fn network_id(&self) -> NetworkId
pub fn network_id(&self) -> NetworkId
Returns the network this engine participates in.
Sourcepub async fn ticket(&self) -> Result<PeerTicket>
pub async fn ticket(&self) -> Result<PeerTicket>
Creates a shareable PeerTicket for this peer.
Waits (bounded by the configured request timeout) for the endpoint to come online so the ticket contains relay information whenever possible; on an isolated network the ticket falls back to the locally known direct addresses.
Sourcepub async fn connect(&self, ticket: PeerTicket) -> Result<EndpointId>
pub async fn connect(&self, ticket: PeerTicket) -> Result<EndpointId>
Connects to the peer described by ticket and performs the handshake.
Incompatible tickets (different network, schema or protocol version) are rejected before any connection is attempted. An existing healthy connection to the same peer is reused.
Sourcepub async fn send(&self, peer: EndpointId, message: &M) -> Result<()>
pub async fn send(&self, peer: EndpointId, message: &M) -> Result<()>
Sends a domain message to a connected peer.
Returns only after the peer acknowledged the message. Fails with
NetworkError::PeerNotConnected if there is no active connection to
the peer; no implicit dialing or peer lookup is performed.
Sourcepub async fn open_stream(
&self,
target: impl Into<EndpointAddr>,
alpn: &[u8],
) -> Result<ByteStream>
pub async fn open_stream( &self, target: impl Into<EndpointAddr>, alpn: &[u8], ) -> Result<ByteStream>
Opens a raw bidirectional byte stream to a peer over a dedicated
connection on the auxiliary ALPN alpn.
The remote peer must have declared alpn in its configuration
(crate::NetworkConfigBuilder::stream_protocol) and hold on to the
matching StreamAcceptor. The stream begins with the regular
network handshake, so it can only be established between peers of the
same network and schema; afterwards the stream carries opaque
application bytes with no framing imposed by the engine.
target can be a full EndpointAddr (e.g. from a ticket) or a
bare EndpointId when the transport already knows how to reach the
peer (an active or recent connection, or discovery).
Sourcepub fn stream_acceptor(&self, alpn: &[u8]) -> Result<StreamAcceptor>
pub fn stream_acceptor(&self, alpn: &[u8]) -> Result<StreamAcceptor>
Takes the acceptor of incoming byte streams for the declared stream
protocol alpn.
The acceptor for a protocol can be taken exactly once. Streams whose handshake succeeded are delivered in accept order; the queue is small and bounded, so an unconsumed acceptor applies backpressure to remote peers.
Sourcepub fn connected_peers(&self) -> Vec<EndpointId> ⓘ
pub fn connected_peers(&self) -> Vec<EndpointId> ⓘ
Returns the ids of all currently connected peers.
Sourcepub fn health(&self) -> NetworkHealthSnapshot
pub fn health(&self) -> NetworkHealthSnapshot
Returns a point-in-time snapshot of transport and rendezvous health.
Sourcepub fn is_connected(&self, peer: EndpointId) -> bool
pub fn is_connected(&self, peer: EndpointId) -> bool
Returns true if there is an active connection to peer.
Sourcepub async fn disconnect(&self, peer: EndpointId) -> Result<()>
pub async fn disconnect(&self, peer: EndpointId) -> Result<()>
Closes the connection to peer and removes it from the registry.
Sourcepub async fn shutdown(self) -> Result<()>
pub async fn shutdown(self) -> Result<()>
Shuts the engine down gracefully.
Rejects new operations, closes all connections, stops the protocol
router, closes the endpoint, waits for background tasks and finally
closes the event channel. Calling shutdown on several clones of the
same engine is safe; only the first call does the work.
Trait Implementations§
Source§impl<M> Clone for NetworkEngine<M>
impl<M> Clone for NetworkEngine<M>
Auto Trait Implementations§
impl<M> !RefUnwindSafe for NetworkEngine<M>
impl<M> !UnwindSafe for NetworkEngine<M>
impl<M> Freeze for NetworkEngine<M>
impl<M> Send for NetworkEngine<M>
impl<M> Sync for NetworkEngine<M>
impl<M> Unpin for NetworkEngine<M>
impl<M> UnsafeUnpin for NetworkEngine<M>where
Arc<Shared<M>>: UnsafeUnpin,
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more