Struct Endpoint

pub struct Endpoint { /* private fields */ }

Controls an iroh-net node, establishing connections with other nodes.

This is the main API interface to create connections to, and accept connections from other iroh-net 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-net.

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-net 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 async fn connect_by_node_id( &self, node_id: NodeId, alpn: &[u8], ) -> Result<Connection>

👎Deprecated since 0.27.0: Please use connect directly with a NodeId. This fn will be removed in 0.28.0.

Connects to a remote endpoint, using just the nodes’s NodeId.

This is a convenience function for Endpoint::connect. It relies on addressing information being provided by either the discovery service or using Endpoint::add_node_addr. See Endpoint::connect for the details of how it uses the discovery service to establish a connection to a remote node.

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-net 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-net 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 local IP endpoints as they would be returned by Endpoint::home_relay and Endpoint::direct_addresses.

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

Returns 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-net nodes can use to reliably establish a connection to this node.

Returns None if we are not connected to any Relay server.

Note that this will be None right after the Endpoint is created since it takes some time to connect to find and connect to the home relay server. Use Endpoint::watch_home_relay to wait until the home relay server is available.

pub fn watch_home_relay(&self) -> impl Stream<Item = RelayUrl>

Watches for changes to the home relay.

If there is currently a home relay it will be yielded immediately as the first item in the stream. This makes it possible to use this function to wait for the initial home relay to be known.

Note that it is not guaranteed that a home relay will ever become available. If no servers are configured with Builder::relay_mode this stream will never yield an item.

pub fn direct_addresses(&self) -> DirectAddrsStream

Returns the direct addresses of this Endpoint.

The direct addresses of the Endpoint are those that could be used by other iroh-net 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-net 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 first item of the returned stream will not be immediately available. Once this first set of local IP endpoints are discovered the stream will always return the first set of IP endpoints immediately, which are the most recently discovered IP endpoints.

Examples

To get the current endpoints, drop the stream after the first item was received:

use futures_lite::StreamExt;
use iroh_net::Endpoint;

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

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-net 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-net 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_stream(&self, node_id: NodeId) -> Result<ConnectionTypeStream>

Returns a stream that reports connection type changes for the remote node.

This returns a stream of ConnectionType items, each time the underlying connection to a remote node changes it yields an item. These connection changes are when the connection switches between using the Relay server and a direct connection.

If there is currently a connection with the remote node the first item in the stream will yield immediately returning the current connection type.

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.

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::discovery.

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

Returns the discovery mechanism, if configured.

See Builder::dns_resolver.

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, error_code: VarInt, reason: &[u8]) -> Result<()>

Closes the QUIC endpoint and the magic socket.

This will close all open QUIC connections with the provided error_code and reason. See quinn::Connection for details on how these are interpreted.

It will then wait for all connections to actually be shutdown, and afterwards close the magic socket.

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

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.