Struct ClientRequest

pub struct ClientRequest<'req, 'sent> {
    stream: &'req mut TcpStream,
    actor_name: &'req str,
    sent: &'sent mut bool,
}

Wrapper around a client stream that guarantees request/reply invariants.

Client messages, which are always requests, are dispatched to Actor instances one at a time via crate::Actor::handle_message. Each request must be paired with exactly one reply from the same actor the request was sent to, where a reply is a message with no type (if a message from the server has a type, it’s a notification, not a reply).

Failing to reply to a request will almost always permanently break that actor, because either the client gets stuck waiting for a reply, or the client receives the reply for a subsequent request as if it was the reply for the current request. If an actor fails to reply to a request, we want the dispatcher (crate::ActorRegistry::handle_message) to send an error of type unrecognizedPacketType, to keep the conversation for that actor in sync.

Since replies come in all shapes and sizes, we want to allow Actor types to send replies without having to return them to the dispatcher. This wrapper type allows the dispatcher to check if a valid reply was sent, and guarantees that if the actor tries to send a reply, it’s actually a valid reply (see Self::is_valid_reply).

It does not currently guarantee anything about messages sent via the TcpStream released via Self::try_clone_stream or the return value of Self::reply.

Fields

stream: &'req mut TcpStream

Client stream.

actor_name: &'req str

Expected actor name.

sent: &'sent mut bool

Sent flag, allowing ActorRegistry to check for unhandled requests.

Implementations

impl ClientRequest<'_, '_>

pub fn handle<'req>( client: &'req mut TcpStream, actor_name: &'req str, handler: impl FnOnce(ClientRequest<'req, '_>) -> Result<(), ActorError>, ) -> Result<(), ActorError>

Run the given handler, with a new request that wraps the given client stream and expected actor name.

Returns ActorError::UnrecognizedPacketType if the actor did not send a reply.

impl<'req> ClientRequest<'req, '_>

pub fn reply<T: Serialize>( self, reply: &T, ) -> Result<&'req mut TcpStream, ActorError>

Send the given reply to the request being handled.

If successful, sets the sent flag and returns the underlying stream, allowing other messages to be sent after replying to a request.

pub fn reply_final<T: Serialize>(self, reply: &T) -> Result<(), ActorError>

Like reply, but for cases where the actor no longer needs the stream.

pub fn try_clone_stream(&self) -> Result<TcpStream>

fn is_valid_reply<T: Serialize>(&self, message: &T) -> bool

Return true iff the given message is a reply (has no type or to), and is from the expected actor.

This incurs a runtime conversion to a BTreeMap, so it should only be used in debug assertions.

Trait Implementations

impl JsonPacketStream for ClientRequest<'_, '_>

Actors can also send other messages before replying to a request.

fn write_json_packet<T: Serialize>( &mut self, message: &T, ) -> Result<(), ActorError>

fn read_json_packet(&mut self) -> Result<Option<Value>, String>