Struct Builder 

pub struct Builder { /* private fields */ }

Builder for Endpoint.

By default the endpoint will generate a new random SecretKey, which will result in a new EndpointId.

To create the Endpoint call Builder::bind.

Implementations

impl Builder

pub fn new<P: Preset>(preset: P) -> Self

Creates a new Builder using the given Preset.

See presets for more.

pub fn preset<P: Preset>(self, preset: P) -> Self

Applies the given Preset.

pub fn empty(relay_mode: RelayMode) -> Self

Creates an empty builder with no address lookup services.

pub async fn bind(self) -> Result<Endpoint, BindError>

Binds the endpoint.

pub fn bind_addr<A>(self, addr: A) -> Result<Self, InvalidSocketAddr>

where A: ToSocketAddr, <A as ToSocketAddr>::Err: Into<InvalidSocketAddr>,

Available on non-wasm_browser only.

Binds an IP socket at the provided socket address.

This is an advanced API to tightly control the sockets used by the endpoint. Most uses do not need to explicitly bind sockets.

Warning

• The builder always comes pre-configured with an IPv4 socket to be bound on the unspecified address: 0.0.0.0. This is the equivalent of using INADDR_ANY special bind address and results in a socket listening on all interfaces available.

• Likewise the builder always comes pre-configured with an IPv6 socket to be bound on the unspecified address: [::]. This bind is allowed to fail however.

• Adding a bind address removes the pre-configured unspecified bind address for this address family. Use Self::bind_addr_with_opts to bind additional addresses without replacing the default bind address.

• This should be called at most once for each address family: once for IPv4 and/or once for IPv6. Calling it multiple times for the same address family will result in undefined routing behaviour. To bind multiple sockets of the same address family, use Self::bind_addr_with_opts.

Description

Requests a socket to be bound on a specific address, with an implied netmask of /0. This allows restricting binding to only one network interface for a given address family.

If the port specified is already in use, binding the endpoint will fail. Using port 0 in the socket address assigns a random free port.

Example

let endpoint = Endpoint::builder()
    .clear_ip_transports()
    .bind_addr("127.0.0.1:0")?
    .bind_addr("[::1]:0")?
    .bind()
    .await?;

pub fn bind_addr_with_opts<A>( self, addr: A, opts: BindOpts, ) -> Result<Self, InvalidSocketAddr>

where A: ToSocketAddr, <A as ToSocketAddr>::Err: Into<InvalidSocketAddr>,

Available on non-wasm_browser only.

Binds an IP socket at the provided socket address.

This is an advanced API to tightly control the sockets used by the endpoint. Most uses do not need to explicitly bind sockets.

Warning

• The builder always comes pre-configured with an IPv4 socket to be bound on the unspecified address: 0.0.0.0. This is the equivalent of using INADDR_ANY special bind address and results in a socket listening on all interfaces available.

• Likewise the builder always comes pre-configured with an IPv6 socket to be bound on the unspecified address: [::]. This bind is allowed to fail however.

Description

Requests a socket to be bound on a specific address. This allows restricting binding to only one network interface for a given address family.

BindOpts::set_prefix_len should be used to configure the netmask of the network interface. This allows outgoing datagrams that start a new network flow to be sent over the socket which is attached to the subnet of the destination address. If multiple sockets are bound the standard routing-table semantics are used: the socket attached to the subnet with the longest prefix matching the destination is used. Practically this means the smallest subnets are at the top of the routing table, and the first subnet containing the destination address is chosen.

If no socket is bound to a subnet that contains the destination address, the notion of “default route” is used. At most one socket per address family may be marked as the default route using BindOpts::set_is_default_route, and this will be used for destinations not contained by the subnets of the bound sockets. This network is expected to have a default gateway configured. A socket with a prefix length of /0 will be set as a “default route” implicitly, unless BindOpts::set_is_default_route is set to false explicitly.

Be aware that using a subnet with a prefix length of /0 will always contain all destination addresses. It is valid to configure this, but no more than one such socket should be bound or the routing will be non-deterministic.

To use a subnet with a non-zero prefix length as the default route in addition to being routed when its prefix matches, use `BindOpts::set_is_default_route. Subnets with a prefix length of zero are always marked as default routes.

Finally note that most outgoing datagrams are part of an existing network flow. That is, they are in response to an incoming datagram. In this case the outgoing datagram will be sent over the same socket as the incoming datagram was received on, and the routing with the prefix length and default route as described above does not apply.

Using port 0 in the socket address assigns a random free port.

If the port specified is already in use, binding the endpoint will fail, unless BindOpts::set_is_required is set to false

Example

let endpoint = Endpoint::builder()
    .clear_ip_transports()
    .bind_addr_with_opts("127.0.0.1:0", BindOpts::default().set_prefix_len(24))?
    .bind_addr_with_opts("[::1]:0", BindOpts::default().set_prefix_len(48))?
    .bind()
    .await?;

pub fn clear_ip_transports(self) -> Self

Available on non-wasm_browser only.

Removes all IP based transports.

pub fn clear_relay_transports(self) -> Self

Removes all relay based transports.

pub fn secret_key(self, secret_key: SecretKey) -> Self

Sets a secret key to authenticate with other peers.

This secret key’s public key will be the PublicKey of this endpoint and thus also its EndpointId

If not set, a new secret key will be generated.

pub fn alpns(self, alpn_protocols: Vec<Vec<u8>>) -> Self

Sets the ALPN protocols that this endpoint will accept on incoming connections.

Not setting this will still allow creating connections, but to accept incoming connections at least one ALPN must be set.

pub fn relay_mode(self, relay_mode: RelayMode) -> Self

Sets the relay servers to assist in establishing connectivity.

Relay servers are used to establish initial connection with another iroh endpoint. They also perform various functions related to hole punching, see the crate docs for more details.

By default the number 0 relay servers are used, see RelayMode::Default.

When using RelayMode::Custom, the provided relay_map must contain at least one configured relay endpoint. If an invalid RelayMap is provided bind will result in an error.

pub fn clear_address_lookup(self) -> Self

Removes all Address Lookup services from the builder.

If no Address Lookup is set, connecting to an endpoint without providing its direct addresses or relay URLs will fail.

See the documentation of the crate::address_lookup::AddressLookup trait for details.

pub fn address_lookup(self, address_lookup: impl IntoAddressLookup) -> Self

Adds an additional Address Lookup for this endpoint.

Once the endpoint is created the provided IntoAddressLookup::into_address_lookup will be called. This allows Address Lookup’s to finalize their configuration by e.g. using the secret key from the endpoint which can be needed to sign published information.

This method can be called multiple times and all the Address Lookup’s passed in will be combined using an internal instance of the crate::address_lookup::ConcurrentAddressLookup. To clear all Address Lookup’s, use Self::clear_address_lookup.

If no Address Lookup is set, connecting to an endpoint without providing its direct addresses or relay URLs will fail.

See the documentation of the crate::address_lookup::AddressLookup trait for details.

pub fn user_data_for_address_lookup(self, user_data: UserData) -> Self

Sets the initial user-defined data to be published in Address Lookup’s for this node.

When using Address Lookup’s, this string of UserData will be published together with the endpoint’s addresses and relay URL. When other endpoints discover this endpoint, they retrieve the UserData in addition to the addressing info.

Iroh itself does not interpret the user-defined data in any way, it is purely left for applications to parse and use.

pub fn transport_config(self, transport_config: QuicTransportConfig) -> Self

Sets a custom QuicTransportConfig for this endpoint.

The transport config contains parameters governing the QUIC state machine.

If unset, the default config is used. Default values should be suitable for most internet applications. Applications protocols which forbid remotely-initiated streams should set max_concurrent_bidi_streams and max_concurrent_uni_streams to zero.

Please be aware that changing some settings may have adverse effects on establishing and maintaining direct connections.

pub fn dns_resolver(self, dns_resolver: DnsResolver) -> Self

Available on non-wasm_browser only.

Optionally sets a custom DNS resolver to use for this endpoint.

The DNS resolver is used to resolve relay hostnames, and endpoint addresses if crate::address_lookup::DnsAddressLookup is configured.

By default, a new DNS resolver is created which is configured to use the host system’s DNS configuration. You can pass a custom instance of DnsResolver here to use a differently configured DNS resolver for this endpoint, or to share a DnsResolver between multiple endpoints.

pub fn proxy_url(self, url: Url) -> Self

Sets an explicit proxy url to proxy all HTTP(S) traffic through.

pub fn proxy_from_env(self) -> Self

Sets the proxy url from the environment, in this order:

• HTTP_PROXY
• http_proxy
• HTTPS_PROXY
• https_proxy

pub fn keylog(self, keylog: bool) -> Self

Enables saving the TLS pre-master key for connections.

This key should normally remain secret but can be useful to debug networking issues by decrypting captured traffic.

If keylog is true then setting the SSLKEYLOGFILE environment variable to a filename will result in this file being used to log the TLS pre-master keys.

pub fn insecure_skip_relay_cert_verify(self, skip_verify: bool) -> Self

Available on crate features test-utils only.

Skip verification of SSL certificates from relay servers

May only be used in tests.

pub fn max_tls_tickets(self, n: usize) -> Self

Set the maximum number of TLS tickets to cache.

Set this to a larger value if you want to do 0rtt connections to a large number of clients.

The default is 256, taking about 150 KiB in memory.

pub fn hooks(self, hooks: impl EndpointHooks + 'static) -> Self

Install hooks onto the endpoint.

Endpoint hooks intercept the connection establishment process of an Endpoint.

You can install multiple EndpointHooks by calling this function multiple times. Order matters: hooks are invoked in the order they were installed onto the endpoint builder. Once a hook returns reject, further processing is aborted and other hooks won’t be invoked.

See EndpointHooks for details on the possible interception points in the connection lifecycle.

Trait Implementations

impl Debug for Builder

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

Formats the value using the given formatter.