Struct JrConnection

Source

pub struct JrConnection<H: JrMessageHandler, R: JrResponder<H::Link> = NullResponder> { /* private fields */ }

Expand description

A JSON-RPC connection with an active transport.

This type represents a JrConnectionBuilder that has been connected to a transport via connect_to(). It can be driven in two modes:

serve() - Run as a server, handling incoming messages until the connection closes
run_until() - Run until a closure completes, allowing you to send requests/notifications

Most users won’t construct this directly - instead use JrConnectionBuilder::connect_to() or JrConnectionBuilder::serve() for convenience.

Implementations§

Source §

impl<H: JrMessageHandler, R: JrResponder<H::Link>> JrConnection<H, R>

Source

pub async fn serve(self) -> Result<(), Error>

Run the connection in server mode with the provided transport.

This drives the connection by continuously processing messages from the transport and dispatching them to your registered handlers. The connection will run until:

The transport closes (e.g., EOF on byte streams)
An error occurs
One of your handlers returns an error

The transport is responsible for serializing and deserializing jsonrpcmsg::Message values to/from the underlying I/O mechanism (byte streams, channels, etc.).

Use this mode when you only need to respond to incoming messages and don’t need to initiate your own requests. If you need to send requests to the other side, use run_until instead.

§Example: Byte Stream Transport

let transport = ByteStreams::new(
    tokio::io::stdout().compat_write(),
    tokio::io::stdin().compat(),
);

UntypedLink::builder()
    .on_receive_request(async |req: MyRequest, request_cx, cx| {
        request_cx.respond(MyResponse { status: "ok".into() })
    }, sacp::on_receive_request!())
    .serve(transport)
    .await?;

Source

pub async fn run_until<T>( self, main_fn: impl AsyncFnOnce(JrConnectionCx<H::Link>) -> Result<T, Error>, ) -> Result<T, Error>

Run the connection until the provided closure completes.

This drives the connection by:

Running your registered handlers in the background to process incoming messages
Executing your main_fn closure with a JrConnectionCx<R> for sending requests/notifications

The connection stays active until your main_fn returns, then shuts down gracefully. If the connection closes unexpectedly before main_fn completes, this returns an error.

Use this mode when you need to initiate communication (send requests/notifications) in addition to responding to incoming messages. For server-only mode where you just respond to messages, use serve instead.

§Example

let transport = ByteStreams::new(
    tokio::io::stdout().compat_write(),
    tokio::io::stdin().compat(),
);

UntypedLink::builder()
    .on_receive_request(async |req: MyRequest, request_cx, cx| {
        // Handle incoming requests in the background
        request_cx.respond(MyResponse { status: "ok".into() })
    }, sacp::on_receive_request!())
    .connect_to(transport)?
    .run_until(async |cx| {
        // Initialize the protocol
        let init_response = cx.send_request(InitializeRequest::make())
            .block_task()
            .await?;

        // Send more requests...
        let result = cx.send_request(MyRequest {})
            .block_task()
            .await?;

        // When this closure returns, the connection shuts down
        Ok(())
    })
    .await?;