Struct Client 

pub struct Client<S: Service>(/* private fields */);

A client to the service S using the local message type M and the remote message type R.

R is typically a serializable enum with a case for each possible message type. It can be thought of as the definition of the protocol.

M is typically an enum with a case for each possible message type, where each case is a WithChannels struct that extends the inner protocol message with a local tx and rx channel as well as a tracing span to allow for keeping tracing context across async boundaries.

In some cases, M and R can be enums for a subset of the protocol. E.g. if you have a subsystem that only handles a part of the messages.

The service type S provides a scope for the protocol messages. It exists so you can use the same message with multiple services.

Implementations

impl<S: Service> Client<S>

pub fn quinn(endpoint: Endpoint, addr: SocketAddr) -> Self

Available on crate feature rpc only.

Create a new client to a remote service using the given quinn endpoint and a socket addr of the remote service.

pub fn boxed(remote: impl RemoteConnection) -> Self

Available on crate feature rpc only.

Create a new client from a rpc::RemoteConnection trait object. This is used from crates that want to provide other transports than quinn, such as the iroh transport.

pub fn local(tx: impl Into<Sender<S::Message>>) -> Self

Creates a new client from a tokio::sync::mpsc::Sender.

pub fn as_local(&self) -> Option<LocalSender<S>>

Get the local sender. This is useful if you don’t care about remote requests.

pub fn request( &self, ) -> impl Future<Output = Result<Request<LocalSender<S>, RemoteSender<S>>, RequestError>> + 'static

Start a request by creating a sender that can be used to send the initial message to the local or remote service.

In the local case, this is just a clone which has almost zero overhead. Creating a local sender can not fail.

In the remote case, this involves lazily creating a connection to the remote side and then creating a new stream on the underlying quinn or iroh connection.

In both cases, the returned sender is fully self contained.

pub fn rpc<Req, Res>( &self, msg: Req, ) -> impl Future<Output = Result<Res>> + Send + 'static

where S: From<Req>, S::Message: From<WithChannels<Req, S>>, Req: Channels<S, Tx = Sender<Res>, Rx = NoReceiver>, Res: RpcMessage,

Performs a request for which the server returns a oneshot receiver.

pub fn server_streaming<Req, Res>( &self, msg: Req, local_response_cap: usize, ) -> impl Future<Output = Result<Receiver<Res>>> + Send + 'static

where S: From<Req>, S::Message: From<WithChannels<Req, S>>, Req: Channels<S, Tx = Sender<Res>, Rx = NoReceiver>, Res: RpcMessage,

Performs a request for which the server returns a mpsc receiver.

pub fn client_streaming<Req, Update, Res>( &self, msg: Req, local_update_cap: usize, ) -> impl Future<Output = Result<(Sender<Update>, Receiver<Res>)>>

where S: From<Req>, S::Message: From<WithChannels<Req, S>>, Req: Channels<S, Tx = Sender<Res>, Rx = Receiver<Update>>, Update: RpcMessage, Res: RpcMessage,

Performs a request for which the client can send updates.

pub fn bidi_streaming<Req, Update, Res>( &self, msg: Req, local_update_cap: usize, local_response_cap: usize, ) -> impl Future<Output = Result<(Sender<Update>, Receiver<Res>)>> + Send + 'static

where S: From<Req>, S::Message: From<WithChannels<Req, S>>, Req: Channels<S, Tx = Sender<Res>, Rx = Receiver<Update>>, Update: RpcMessage, Res: RpcMessage,

Performs a request for which the client can send updates, and the server returns a mpsc receiver.

pub fn notify<Req>( &self, msg: Req, ) -> impl Future<Output = Result<()>> + Send + 'static

where S: From<Req>, S::Message: From<WithChannels<Req, S>>, Req: Channels<S, Tx = NoSender, Rx = NoReceiver>,

Performs a request for which the server returns nothing.

The returned future completes once the message is sent.

pub fn notify_0rtt<Req>( &self, msg: Req, ) -> impl Future<Output = Result<()>> + Send + 'static

where S: From<Req>, S::Message: From<WithChannels<Req, S>>, Req: Channels<S, Tx = NoSender, Rx = NoReceiver>,

Performs a request for which the server returns nothing.

The returned future completes once the message is sent.

Compared to Self::notify, this variant takes a future that returns true if 0rtt has been accepted. If not, the data is sent again via the same remote channel. For local requests, the future is ignored.

pub fn rpc_0rtt<Req, Res>( &self, msg: Req, ) -> impl Future<Output = Result<Res>> + Send + 'static

where S: From<Req>, S::Message: From<WithChannels<Req, S>>, Req: Channels<S, Tx = Sender<Res>, Rx = NoReceiver>, Res: RpcMessage,

Performs a request for which the server returns a oneshot receiver.

Compared to Self::rpc, this variant takes a future that returns true if 0rtt has been accepted. If not, the data is sent again via the same remote channel. For local requests, the future is ignored.

pub fn server_streaming_0rtt<Req, Res>( &self, msg: Req, local_response_cap: usize, ) -> impl Future<Output = Result<Receiver<Res>>> + Send + 'static

where S: From<Req>, S::Message: From<WithChannels<Req, S>>, Req: Channels<S, Tx = Sender<Res>, Rx = NoReceiver>, Res: RpcMessage,

Performs a request for which the server returns a mpsc receiver.

Compared to Self::server_streaming, this variant takes a future that returns true if 0rtt has been accepted. If not, the data is sent again via the same remote channel. For local requests, the future is ignored.

Trait Implementations

impl<S: Service> Clone for Client<S>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<S: Debug + Service> Debug for Client<S>

where S::Message: Debug,

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

Formats the value using the given formatter.

impl<S: Service> From<LocalSender<S>> for Client<S>

fn from(tx: LocalSender<S>) -> Self

Converts to this type from the input type.

impl<S: Service> From<Sender<<S as Service>::Message>> for Client<S>

fn from(tx: Sender<S::Message>) -> Self

Converts to this type from the input type.