Struct qp2p::Endpoint

pub struct Endpoint<I: ConnId> { /* fields omitted */ }

Endpoint instance which can be used to create connections to peers, and listen to incoming messages from other peers.

Implementations

impl<I: ConnId> Endpoint<I>

pub async fn new(
    local_addr: impl Into<SocketAddr>,
    contacts: &[SocketAddr],
    config: Config
) -> Result<(Self, IncomingConnections, IncomingMessages, DisconnectionEvents, Option<SocketAddr>), EndpointError>

Create a peer endpoint at the given address.

A peer endpoint, unlike a client endpoint, can receive incoming connections.

Bootstrapping

When given a non-empty list of contacts, this will attempt to ‘bootstrap’ against them. This involves connecting to all the contacts concurrently and selecting the first successfully connected peer (if any), whose SocketAddr will be returned.

If bootstrapping is successful, the connected peer will be used to perform a reachability check to validate that this endpoint can be reached at its public_addr.

Note: if no contacts are given, the public_addr of the endpoint will not have been validated to be reachable by anyone

Port forwarding (UPnP)

If configured (via config.forward_port), an external port mapping will be set up (using the IGD UPnP protocol). The established external port will be reflected in public_addr, and the lease will be renewed automatically every config.upnp_lease_duration.

pub fn new_client(
    local_addr: impl Into<SocketAddr>,
    config: Config
) -> Result<(Self, IncomingMessages, DisconnectionEvents), ClientEndpointError>

Create a client endpoint at the given address.

A client endpoint cannot receive incoming connections, as such they also do not need to be publicly reachable. They can still communicate over outgoing connections and receive incoming streams, since QUIC allows for either side of a connection to initiate streams.

pub fn local_addr(&self) -> SocketAddr

Endpoint local address

pub fn public_addr(&self) -> SocketAddr

Get the public address of the endpoint.

pub async fn disconnect_from(&self, peer_addr: &SocketAddr)

Removes all existing connections to a given peer

pub async fn connect_to(
    &self,
    node_addr: &SocketAddr
) -> Result<(), ConnectionError>

Connects to another peer, retries for config.retry_duration_msec if the connection fails.

Note: this method is intended for use when it’s necessary to connect to a specific peer. See connect_to_any if you just need a connection with any of a set of peers.

Returns Connection which is a handle for sending messages to the peer and IncomingMessages which is a stream of messages received from the peer. The incoming messages stream might be None. See the next section for more info.

Connection pooling

Connection are stored in an internal pool and reused if possible. A connection remains in the pool while its IncomingMessages instances exists and while the connection is open.

When a new connection is established, this function returns both the Connection instance and the IncomingMessages stream. If an existing connection is retrieved from the pool, the incoming messages will be None. Multiple Connection instances can exists simultaneously and they all share the same underlying connection resource. On the other hand, at most one IncomingMessages stream can exist per peer.

How to handle the IncomingMessages depends on the networking model of the application:

In the peer-to-peer model, where peers can arbitrarily send and receive messages to/from other peers, it is recommended to keep the IncomingMessages around and listen on it for new messages by repeatedly calling next and only drop it when it returns None. On the other hand, there is no need to keep Connection around as it can be cheaply retrieved again when needed by calling connect_to. When the connection gets closed by the peer or it timeouts due to inactivity, the incoming messages stream gets closed and once it’s dropped the connection gets removed from the pool automatically. Calling connect_to afterwards will open a new connection.

In the client-server model, where only the client send requests to the server and then listens for responses and never the other way around, it’s OK to ignore (drop) the incoming messages stream and only use bi-directional streams obtained by calling Connection::open_bi. In this case the connection won’t be pooled and the application is responsible for caching it.

When sending a message on Connection fails, the connection is also automatically removed from the pool and the subsequent call to connect_to is guaranteed to reopen new connection too.

pub async fn connect_to_any(
    &self,
    peer_addrs: &[SocketAddr]
) -> Option<SocketAddr>

Connect to any of the given peers.

Often in peer-to-peer networks, it’s sufficient to communicate to any node on the network, rather than having to connect to specific nodes. This method will start connecting to every peer in peer_addrs, and return the address of the first successfully established connection (the rest are cancelled and discarded). All connection attempts will be retried for config.retry_duration_msec on failure.

The successful connection, if any, will be stored in the connection pool (see connect_to for more info on connection pooling).

pub async fn is_reachable(&self, peer_addr: &SocketAddr) -> Result<(), RpcError>

Verify if an address is publicly reachable. This will attempt to create a new connection and use it to exchange a message and verify that the node can be reached.

pub async fn get_connection_id(&self, addr: &SocketAddr) -> Option<I>

Get the connection ID of an existing connection with the provided socket address

pub async fn get_socket_addr_by_id(&self, addr: &I) -> Option<SocketAddr>

Get the SocketAddr of a connection using the connection ID

pub async fn open_bidirectional_stream(
    &self,
    peer_addr: &SocketAddr,
    priority: i32
) -> Result<(SendStream, RecvStream), ConnectionError>

Open a bi-directional peer with a given peer Priority default is 0. Both lower and higher can be passed in.

pub async fn try_send_message(
    &self,
    msg: Bytes,
    dest: &SocketAddr,
    priority: i32
) -> Result<(), Option<SendError>>

Send a message to a peer over an existing connection.

Priority default is 0. Both lower and higher can be passed in.

Errors

If a connection with dest exists in the pool but the message fails to send, Err(Some(_)) will be returned. If there’s no connection with dest in the pool, then Err(None) will be returned.

pub async fn send_message(
    &self,
    msg: Bytes,
    dest: &SocketAddr,
    priority: i32
) -> Result<(), SendError>

Sends a message to a peer. This will attempt to use an existing connection to the peer first. If this connection is broken or doesn’t exist a new connection is created and the message is sent. Priority default is 0. Both lower and higher can be passed in.

pub fn close(&self)

Close all the connections of this endpoint immediately and stop accepting new connections.

Trait Implementations

impl<I: Clone + ConnId> Clone for Endpoint<I>

fn clone(&self) -> Endpoint<I>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<I: ConnId> Debug for Endpoint<I>

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

Formats the value using the given formatter.