Struct bonsaidb::client::fabruic::Endpoint

pub struct Endpoint { /* private fields */ }

Represents a socket using the QUIC protocol to communicate with peers.

Stream

Receives incoming Connections through [Stream].

Implementations

impl Endpoint

pub fn builder() -> Builder

Builds a new Builder. See Builder methods for defaults.

Examples

use fabruic::Endpoint;

let endpoint = Endpoint::builder().build()?;

pub fn new_client() -> Result<Endpoint, Config>

Simplified version of creating a client. See Builder for more sophisticated configuration options. Must be called from inside a Tokio Runtime.

Notes

This configuration will not be able to receive incoming Connections.

Errors

std::io::Error if the socket couldn’t be bound to the given address.

Panics

If not called from inside a Tokio Runtime.

Examples

use fabruic::Endpoint;

let endpoint = Endpoint::new_client()?;

pub fn new_server(port: u16, key_pair: KeyPair) -> Result<Endpoint, Config>

Simplified version of creating a server. See Builder for more sophisticated configuration options. Must be called from inside a Tokio Runtime.

Errors

std::io::Error if the socket couldn’t be bound to the given address.

Panics

• if the given KeyPair is invalid - can’t happen if properly validated through KeyPair::from_parts
• if not called from inside a Tokio Runtime

Examples

use fabruic::{Endpoint, KeyPair};

let endpoint = Endpoint::new_server(0, KeyPair::new_self_signed("self-signed"))?;

pub async fn connect<U>( &self, url: U ) -> impl Future<Output = Result<Connecting, Connect>>where U: AsRef<str>,

Establishes a new Connection to a server. The servers Certificate will be validated aggainst the root certificate store and the domain in the URL.

Attempts to resolve the IP from the given URL. Uses trust-dns by default if the crate feature trust-dns is enabled. Otherwise ToSocketAddrs is used.

See Builder::set_trust_dns or Builder::disable_trust_dns for more control.

Notes

The following settings are used when using trust-dns:

• all system configurations are ignored, see Builder::set_hosts_file
• Cloudflare with DoH is used as the name server
• DNSSEC is enabled, see Builder::set_dnssec
• IPv6 is preferred over IPv4 if the bound socket is IPv6

Errors

• error::Connect::ParseUrl if the URL couldn’t be parsed
• error::Connect::Domain if the URL didn’t contain a domain
• error::Connect::Port if the URL didn’t contain a port
• error::Connect::ParseDomain if the domain couldn’t be parsed
• error::Connect::TrustDns if the URL couldn’t be resolved to an IP address with trust-dns
• error::Connect::StdDns if the URL couldn’t be resolved to an IP address with ToSocketAddrs
• error::Connect::NoIp if no IP address was found for that domain

Examples

use fabruic::Endpoint;

let endpoint = Endpoint::new_client()?;
// not going to actually work because `localhost` can't have a valid certificate
let connecting = endpoint.connect("quic://localhost:443").await?;

pub async fn connect_pinned<U>( &self, url: U, server_certificate: &Certificate, client_key_pair: Option<KeyPair> ) -> impl Future<Output = Result<Connecting, Connect>>where U: AsRef<str>,

Establishes a new Connection to a server.

See connect for more information on host name resolution.

Notes

The root certificate store will be ignored and the given Certificate will validate the server.

A client certificate KeyPair set with Builder::set_client_key_pair will be ignored, use client_key_pair to add a client certificate to this connection.

This method is intended for direct connection to a known server, the domain name in the URL is not checked against the Certificate. Multiple domain names in the Certificate aren’t supported.

Errors

• error::Connect::MultipleDomains if multiple domains are present in the Certificate, which isn’t supported
• error::Connect::ParseUrl if the URL couldn’t be parsed
• error::Connect::Domain if the URL didn’t contain a domain
• error::Connect::Port if the URL didn’t contain a port
• error::Connect::ParseDomain if the domain couldn’t be parsed
• error::Connect::TrustDns if the URL couldn’t be resolved to an IP address with trust-dns
• error::Connect::StdDns if the URL couldn’t be resolved to an IP address with ToSocketAddrs
• error::Connect::NoIp if no IP address was found for that domain

Panics

Panics if the given Certificate or KeyPair are invalid. Can’t happen if they were properly validated through Certificate::from_der or KeyPair::from_parts.

Examples

use fabruic::Endpoint;

let endpoint = Endpoint::new_client()?;
// the server certificate has to be imported from somewhere else
let connecting = endpoint
	.connect_pinned("quic://localhost:443", &server_certificate, None)
	.await?;

pub fn local_address(&self) -> Result<SocketAddr, Error>

Get the local SocketAddr the underlying socket is bound to.

Errors

std::io::Error if aquiring the local address failed.

Examples

use fabruic::Endpoint;

let endpoint = Endpoint::new_client()?;
assert!(endpoint.local_address().is_ok());

pub async fn close(&self) -> impl Future<Output = ()>

Close all of this Endpoint’s Connections immediately and cease accepting new Connections.

To close an Endpoint gracefully use close_incoming, Sender::finish and wait_idle.

Examples

use fabruic::Endpoint;

let endpoint = Endpoint::new_client()?;
endpoint.close();

pub async fn close_incoming( &self ) -> impl Future<Output = Result<(), AlreadyClosed>>

Prevents any new incoming connections. Already incoming connections will finish first. This will always return error::AlreadyClosed if the Endpoint wasn’t started with a listener.

See Builder::set_server_key_pair.

Errors

error::AlreadyClosed if it was already closed.

Examples

use fabruic::{Endpoint, KeyPair};

let endpoint = Endpoint::new_server(0, KeyPair::new_self_signed("test"))?;
assert!(endpoint.close_incoming().await.is_ok());

pub async fn wait_idle(&self) -> impl Future<Output = ()>

Wait for all Connections to the Endpoint to be cleanly shut down. Does not close existing connections or cause incoming connections to be rejected. See close_incoming.

Examples

use fabruic::Endpoint;

let endpoint = Endpoint::new_client()?;
endpoint.wait_idle().await;

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 Dangerous for Endpoint

fn connect_unverified<'life0, 'async_trait, U>( endpoint: &'life0 Endpoint, url: U, client_key_pair: Option<KeyPair> ) -> Pin<Box<dyn Future<Output = Result<Connecting, Connect>> + Send + 'async_trait, Global>>where 'life0: 'async_trait, U: 'async_trait + AsRef<str> + Send, Endpoint: 'async_trait,

Establishes a new Connection to a server without verifying the servers Certificate. The servers CertificateChain can still be manually insepcted through Connection::peer_identity.

impl Debug for Endpoint

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

Formats the value using the given formatter.

impl FusedStream for Endpoint

fn is_terminated(&self) -> bool

Returns true if the stream should no longer be polled.

impl Stream for Endpoint

type Item = Connecting

Values yielded by the stream.

fn poll_next( self: Pin<&mut Endpoint>, cx: &mut Context<'_> ) -> Poll<Option<<Endpoint as Stream>::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.