Struct Endpoint

pub struct Endpoint { /* private fields */ }

Controls an iroh node, establishing connections with other nodes.

This is the main API interface to create connections to, and accept connections from other iroh nodes. The connections are peer-to-peer and encrypted, a Relay server is used to make the connections reliable. See the [crate docs] for a more detailed overview of iroh.

It is recommended to only create a single instance per application. This ensures all the connections made share the same peer-to-peer connections to other iroh nodes, while still remaining independent connections. This will result in more optimal network behaviour.

New connections are typically created using the Endpoint::connect and Endpoint::accept methods. Once established, the Connection gives access to most QUIC features. Individual streams to send data to the peer are created using the Connection::open_bi, Connection::accept_bi, Connection::open_uni and Connection::open_bi functions.

Note that due to the light-weight properties of streams a stream will only be accepted once the initiating peer has sent some data on it.

Implementations

impl Endpoint

pub fn builder() -> Builder

Returns the builder for an Endpoint, with a production configuration.

pub fn set_alpns(&self, alpns: Vec<Vec<u8>>) -> Result<()>

Sets the list of accepted ALPN protocols.

This will only affect new incoming connections. Note that this overrides the current list of ALPNs.

pub async fn connect( &self, node_addr: impl Into<NodeAddr>, alpn: &[u8], ) -> Result<Connection>

Connects to a remote Endpoint.

A value that can be converted into a NodeAddr is required. This can be either a NodeAddr, a NodeId or a iroh_base::ticket::NodeTicket.

The NodeAddr must contain the NodeId to dial and may also contain a RelayUrl and direct addresses. If direct addresses are provided, they will be used to try and establish a direct connection without involving a relay server.

If neither a RelayUrl or direct addresses are configured in the NodeAddr it may still be possible a connection can be established. This depends on other calls to Endpoint::add_node_addr which may provide contact information, or via the Discovery service configured using Builder::discovery. The discovery service will also be used if the remote node is not reachable on the provided direct addresses and there is no RelayUrl.

If addresses or relay servers are neither provided nor can be discovered, the connection attempt will fail with an error.

The alpn, or application-level protocol identifier, is also required. The remote endpoint must support this alpn, otherwise the connection attempt will fail with an error.

pub fn accept(&self) -> Accept<'_>

Accepts an incoming connection on the endpoint.

Only connections with the ALPNs configured in Builder::alpns will be accepted. If multiple ALPNs have been configured the ALPN can be inspected before accepting the connection using Connecting::alpn.

The returned future will yield None if the endpoint is closed by calling Endpoint::close.

pub fn add_node_addr(&self, node_addr: NodeAddr) -> Result<()>

Informs this Endpoint about addresses of the iroh node.

This updates the local state for the remote node. If the provided NodeAddr contains a RelayUrl this will be used as the new relay server for this node. If it contains any new IP endpoints they will also be stored and tried when next connecting to this node. Any address that matches this node’s direct addresses will be silently ignored.

See also Endpoint::add_node_addr_with_source.

Errors

Will return an error if we attempt to add our own PublicKey to the node map or if the direct addresses are a subset of ours.

pub fn add_node_addr_with_source( &self, node_addr: NodeAddr, source: &'static str, ) -> Result<()>

Informs this Endpoint about addresses of the iroh node, noting the source.

This updates the local state for the remote node. If the provided NodeAddr contains a RelayUrl this will be used as the new relay server for this node. If it contains any new IP endpoints they will also be stored and tried when next connecting to this node. Any address that matches this node’s direct addresses will be silently ignored. The source is used for logging exclusively and will not be stored.

Errors

Will return an error if we attempt to add our own PublicKey to the node map or if the direct addresses are a subset of ours.

pub fn secret_key(&self) -> &SecretKey

Returns the secret_key of this endpoint.

pub fn node_id(&self) -> NodeId

Returns the node id of this endpoint.

This ID is the unique addressing information of this node and other peers must know it to be able to connect to this node.

pub async fn node_addr(&self) -> Result<NodeAddr>

Returns the current NodeAddr for this endpoint.

The returned NodeAddr will have the current RelayUrl and direct addresses as they would be returned by Endpoint::home_relay and Endpoint::direct_addresses.

pub fn home_relay(&self) -> Watcher<Option<RelayUrl>>

Returns a Watcher for the RelayUrl of the Relay server used as home relay.

Every endpoint has a home Relay server which it chooses as the server with the lowest latency out of the configured servers provided by Builder::relay_mode. This is the server other iroh nodes can use to reliably establish a connection to this node.

The watcher stores None if we are not connected to any Relay server.

Note that this will store None right after the Endpoint is created since it takes some time to connect to find and connect to the home relay server.

Examples

To wait for a home relay connection to be established, use Watcher::initialized:

use futures_lite::StreamExt;
use iroh::Endpoint;

let mep = Endpoint::builder().bind().await.unwrap();
let _relay_url = mep.home_relay().initialized().await.unwrap();

pub fn direct_addresses(&self) -> Watcher<Option<BTreeSet<DirectAddr>>>

Returns a Watcher for the direct addresses of this Endpoint.

The direct addresses of the Endpoint are those that could be used by other iroh nodes to establish direct connectivity, depending on the network situation. The yielded lists of direct addresses contain both the locally-bound addresses and the Endpoint’s publicly reachable addresses discovered through mechanisms such as STUN and port mapping. Hence usually only a subset of these will be applicable to a certain remote iroh node.

The Endpoint continuously monitors the direct addresses for changes as its own location in the network might change. Whenever changes are detected this stream will yield a new list of direct addresses.

When issuing the first call to this method the first direct address discovery might still be underway, in this case the Watcher might not be initialized with Some value yet. Once the first set of local direct addresses are discovered the Watcher will always return Some set of direct addresses immediately, which are the most recently discovered direct addresses.

Examples

To get the first set of direct addresses use Watcher::initialized:

use futures_lite::StreamExt;
use iroh::Endpoint;

let mep = Endpoint::builder().bind().await.unwrap();
let _addrs = mep.direct_addresses().initialized().await.unwrap();

pub fn bound_sockets(&self) -> (SocketAddr, Option<SocketAddr>)

Returns the local socket addresses on which the underlying sockets are bound.

The Endpoint always binds on an IPv4 address and also tries to bind on an IPv6 address if available.

pub fn remote_info(&self, node_id: NodeId) -> Option<RemoteInfo>

Returns information about the remote node identified by a NodeId.

The Endpoint keeps some information about remote iroh nodes, which it uses to find the best path to a node. Having information on a remote node, however, does not mean we have ever connected to it to or even whether a connection is even possible. The information about a remote node will change over time, as the Endpoint learns more about the node. Future calls may return different information. Furthermore, node information may even be completely evicted as it becomes stale.

See also Endpoint::remote_info_iter which returns information on all nodes known by this Endpoint.

pub fn remote_info_iter(&self) -> impl Iterator<Item = RemoteInfo>

Returns information about all the remote nodes this Endpoint knows about.

This returns the same information as Endpoint::remote_info for each node known to this Endpoint.

The Endpoint keeps some information about remote iroh nodes, which it uses to find the best path to a node. This returns all the nodes it knows about, regardless of whether a connection was ever made or is even possible.

See also Endpoint::remote_info to only retrieve information about a single node.

pub fn conn_type(&self, node_id: NodeId) -> Result<Watcher<ConnectionType>>

Returns a Watcher that reports the current connection type and any changes for given remote node.

This watcher allows observing a stream of ConnectionType items by calling Watcher::stream(). If the underlying connection to a remote node changes, it will yield a new item. These connection changes are when the connection switches between using the Relay server and a direct connection.

Note that this does not guarantee each connection change is yielded in the stream. If the connection type changes several times before this stream is polled, only the last recorded state is returned. This can be observed e.g. right at the start of a connection when the switch from a relayed to a direct connection can be so fast that the relayed state is never exposed.

If there is currently a connection with the remote node, then using Watcher::get will immediately return either ConnectionType::Relay, ConnectionType::Direct or ConnectionType::Mixed.

It is possible for the connection type to be ConnectionType::None if you’ve recently connected to this node id but previous methods of reaching the node have become inaccessible.

Errors

Will error if we do not have any address information for the given node_id.

pub fn dns_resolver(&self) -> &DnsResolver

Returns the DNS resolver used in this Endpoint.

See Builder::dns_resolver.

pub fn discovery(&self) -> Option<&dyn Discovery>

Returns the discovery mechanism, if configured.

See Builder::discovery.

pub async fn network_change(&self)

Notifies the system of potential network changes.

On many systems iroh is able to detect network changes by itself, however some systems like android do not expose this functionality to native code. Android does however provide this functionality to Java code. This function allows for notifying iroh of any potential network changes like this.

Even when the network did not change, or iroh was already able to detect the network change itself, there is no harm in calling this function.

pub async fn close(&self) -> Result<()>

Closes the QUIC endpoint and the magic socket.

This will close any remaining open Connections with an error code of 0 and an empty reason. Though it is best practice to close those explicitly before with a custom error code and reason.

It will then make a best effort to wait for all close notifications to be acknowledged by the peers, re-transmitting them if needed. This ensures the peers are aware of the closed connections instead of having to wait for a timeout on the connection. Once all connections are closed or timed out, the magic socket is closed.

Be aware however that the underlying UDP sockets are only closed on Drop, bearing in mind the Endpoint is only dropped once all the clones are dropped.

Returns an error if closing the magic socket failed. TODO: Document error cases.

pub fn is_closed(&self) -> bool

Check if this endpoint is still alive, or already closed.

Trait Implementations

impl Clone for Endpoint

fn clone(&self) -> Endpoint

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Endpoint

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

Formats the value using the given formatter.