Struct RpcConn

pub struct RpcConn {
    receiver: Arc<Receiver>,
    writer: Mutex<Writer>,
    pub(super) session: Option<ObjectId>,
}

An open RPC connection to Arti.

Fields

receiver: Arc<Receiver>

The receiver object for this conn.

It’s in an Arc<> so that we can share it with the RequestHandles.

writer: Mutex<Writer>

A writer that we use to send requests to Arti.

This has its own lock so that we do not have to lock the Receiver just in order to write.

This lock does not nest with thereceiver lock. You must never hold both at the same time.

(For now, this lock is ONLY held in the send_request method.)

session: Option<ObjectId>

If set, we are authenticated and we have negotiated a session that has this ObjectID.

Implementations

impl RpcConn

pub(crate) fn authenticate_inherent( &self, scheme_name: &str, ) -> Result<ObjectId, ConnectError>

Try to negotiate “inherent” authentication, using the provided scheme name.

(Inherent authentication is available whenever the client proves that they are authorized through being able to connect to Arti at all. Examples include connecting to a unix domain socket, and an in-process Arti implementation.)

pub(crate) fn authenticate_cookie( &self, cookie: &Cookie, server_addr: &str, ) -> Result<ObjectId, ConnectError>

Try to negotiate “cookie” authentication, using the provided cookie and server address.

impl RpcConn

pub(super) fn new(reader: Reader, writer: Writer) -> Self

Construct a new RpcConn with a given reader and writer.

pub(super) fn send_request( &self, msg: &str, ) -> Result<RequestHandle, ProtoError>

Send the request in msg on this connection, and return a RequestHandle to wait for a reply.

We validate msg before sending it out, and reject it if it doesn’t make sense. If msg has no id field, we allocate a new one according to the rules in IdGenerator.

Limitation: We don’t preserved unrecognized fields in the framing and meta parts of msg. See notes in request.rs.

impl RpcConn

pub fn open_stream_as_object( &self, on_object: Option<&ObjectId>, target: (&str, u16), isolation: &str, ) -> Result<(ObjectId, TcpStream), StreamError>

Open a new data stream, registering the stream with the RPC system.

Behaves the same as open_stream(), with the following exceptions:

• Returns a ObjectId that can be used to identify the DataStream for later RPC requests.
• Tells Arti not to wait for the stream to succeed or fail over the Tor network. (To wait for the stream to succeed or fail, use the appropriate method.)

(TODO RPC: Implement such a method!)

pub fn open_stream( &self, on_object: Option<&ObjectId>, (hostname, port): (&str, u16), isolation: &str, ) -> Result<TcpStream, StreamError>

Open a new data stream, using Arti to connect anonymously to a given address and port.

If on_object is provided, it must be a an ID for a client-like RPC object that supports opening data streams. If it is not provided, the data stream is opened relative to the current session.

We tell Arti that the stream must not share a circuit with any other stream with a different value for isolation. (If your application doesn’t care about isolating its streams from one another, it is acceptable to leave isolation as an empty string.)

fn lookup_socks_proxy_addr(&self) -> Result<SocketAddr, StreamError>

Ask Arti for its supported SOCKS addresses; return the first one.

fn session_id_required(&self) -> Result<&ObjectId, StreamError>

Helper: Return the session ID, or an error.

fn resolve_on_object( &self, on_object: Option<&ObjectId>, ) -> Result<ObjectId, StreamError>

Helper: Return on_object if it’s present, or the session ID otherwise.

impl RpcConn

pub fn session(&self) -> Option<&ObjectId>

Return the ObjectId for the negotiated Session.

Nearly all RPC methods require a Session, or some other object accessed via the session.

(This function will only return None if no authentication has been performed. TODO RPC: It is not currently possible to make an unauthenticated connection.)

pub fn execute( &self, cmd: &str, ) -> Result<Result<SuccessResponse, ErrorResponse>, ProtoError>

Run a command, and wait for success or failure.

Note that this function will return Err(.) only if sending the command or getting a response failed. If the command was sent successfully, and Arti reported an error in response, this function returns Ok(Err(.)).

Note that the command does not need to include an id field. If you omit it, one will be generated.

pub(crate) fn execute_internal<T: DeserializeOwned>( &self, cmd: &str, ) -> Result<Result<T, ErrorResponse>, ProtoError>

Helper for executing internally-generated requests and decoding their results.

Behaves like execute, except on success, where it tries to decode the result field of the response as a T.

Use this method in cases where it’s reasonable for Arti to sometimes return an RPC error: in other words, where it’s not necessarily a programming error or version mismatch.

Don’t use this for user-generated requests: it will misreport unexpected replies as internal errors.

pub(crate) fn execute_internal_ok<T: DeserializeOwned>( &self, cmd: &str, ) -> Result<T, ProtoError>

Helper for executing internally-generated requests and decoding their results.

Behaves like execute_internal, except that it treats any RPC error reply as an internal error or version mismatch.

Don’t use this for user-generated requests, or for requests that can fail because of incorrect user inputs: it will misreport failures in those requests as internal errors.

pub fn cancel(&self, request_id: &AnyRequestId) -> Result<(), ProtoError>

Cancel a request by ID.

pub fn execute_with_handle( &self, cmd: &str, ) -> Result<RequestHandle, ProtoError>

Like execute, but don’t wait. This lets the caller see the request ID and maybe cancel it.

pub fn execute_with_updates<F>( &self, cmd: &str, update_cb: F, ) -> Result<Result<SuccessResponse, ErrorResponse>, ProtoError>

where F: FnMut(UpdateResponse) + Send + Sync,

As execute(), but run update_cb for every update we receive.

pub(crate) fn release_obj(&self, obj: ObjectId) -> Result<(), ProtoError>

Helper: Tell Arti to release obj.

Do not use this method for a user-provided object ID: It gives an internal error if the object does not exist.

Trait Implementations

impl Debug for RpcConn

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

Formats the value using the given formatter.