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 noq(endpoint: Endpoint, addr: SocketAddr) -> Self

Available on crate feature rpc only.

Create a new client to a remote service using the given noq 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 noq, 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>> + use<S>

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 noq or iroh connection.

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

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

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 + use<Req, Update, Res, S>

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 purpose of notify is to send messages to the remote without waiting for the remote to respond.

The returned future completes once the message is written locally. Therefore we have no guarantee that the remote has received the message.

If we close the connection immediately after the future returns, the connection might be closed before the message is on the wire, so the remote might never receive it.

If you need to send a message with unit result but want to wait until the remote has received it, consider using rpc with a unit () return type instead.

This method is safe to use with both regular and 0-RTT connections. If 0-RTT data is rejected, the message will be automatically re-sent.

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.

This method is safe to use with both regular and 0-RTT connections. If 0-RTT data is rejected, the message will be automatically re-sent.

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

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.

This method is safe to use with both regular and 0-RTT connections. If 0-RTT data is rejected, the message will be automatically re-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>,

👎Deprecated:

use notify instead, it handles 0rtt automatically

Deprecated: use Self::notify instead, it handles 0rtt automatically.

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,

👎Deprecated:

use rpc instead, it handles 0rtt automatically

Deprecated: use Self::rpc instead, it handles 0rtt automatically.

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,

👎Deprecated:

use server_streaming instead, it handles 0rtt automatically

Deprecated: use Self::server_streaming instead, it handles 0rtt automatically.

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.