Skip to main content

NetworkEngine

Struct NetworkEngine 

Source
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>

Source

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.

Source

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.

Source

pub fn endpoint_id(&self) -> EndpointId

Returns the stable identifier of this peer.

Source

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.

Source

pub fn network_id(&self) -> NetworkId

Returns the network this engine participates in.

Source

pub fn schema_id(&self) -> SchemaId

Returns the message schema this engine uses.

Source

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.

Source

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.

Source

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.

Source

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).

Source

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.

Source

pub fn connected_peers(&self) -> Vec<EndpointId> ⓘ

Returns the ids of all currently connected peers.

Source

pub fn health(&self) -> NetworkHealthSnapshot

Returns a point-in-time snapshot of transport and rendezvous health.

Source

pub fn is_connected(&self, peer: EndpointId) -> bool

Returns true if there is an active connection to peer.

Source

pub async fn disconnect(&self, peer: EndpointId) -> Result<()>

Closes the connection to peer and removes it from the registry.

Source

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>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<M> Debug for NetworkEngine<M>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<M> !RefUnwindSafe for NetworkEngine<M>

§

impl<M> !UnwindSafe for NetworkEngine<M>

§

impl<M> Freeze for NetworkEngine<M>
where Arc<Shared<M>>: Freeze,

§

impl<M> Send for NetworkEngine<M>
where Arc<Shared<M>>: Send,

§

impl<M> Sync for NetworkEngine<M>
where Arc<Shared<M>>: Sync,

§

impl<M> Unpin for NetworkEngine<M>
where Arc<Shared<M>>: Unpin,

§

impl<M> UnsafeUnpin for NetworkEngine<M>
where Arc<Shared<M>>: UnsafeUnpin,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DynClone for T
where T: Clone,

Source§

fn __clone_box(&self, _: Private) -> *mut ()

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more