Struct RelayCirc 

pub struct RelayCirc(pub(crate) CircReactorHandle<Forward, Backward>);

A handle for interacting with a relay circuit.

Tuple Fields

0: CircReactorHandle<Forward, Backward>

Implementations

impl RelayCirc

pub fn terminate(&self)

Shut down this circuit, along with all streams that are using it. Happens asynchronously (i.e. the tunnel won’t necessarily be done shutting down immediately after this function returns!).

Note that other references to this tunnel may exist. If they do, they will stop working after you call this function.

It’s not necessary to call this method if you’re just done with a circuit: the circuit should close on its own once nothing is using it any more.

pub fn is_closing(&self) -> bool

Return true if this circuit is closed and therefore unusable.

pub(crate) fn drain_rate_update( &self, _stream_id: StreamId, _rate: XonKbpsEwma, ) -> Result<()>

Inform the circuit reactor that there has been a change in the drain rate for this stream.

Typically the circuit reactor would send this new rate in an XON message to the other end of the stream. But it may decide not to, and may discard this update. For example the stream may have a large amount of buffered data, and the reactor may not want to send an XON while the buffer is large.

This sends a message to inform the circuit reactor of the new drain rate, but it does not block or wait for a response from the reactor. An error is only returned if we are unable to send the update.

pub(crate) fn send_sendme(&self, _stream_id: StreamId) -> Result<()>

Request to send a SENDME cell for this stream.

This sends a request to the circuit reactor to send a stream-level SENDME, but it does not block or wait for a response from the circuit reactor. An error is only returned if we are unable to send the request. This means that if the circuit reactor is unable to send the SENDME, we are not notified of this here and an error will not be returned.

pub(crate) fn close_pending( &self, _stream_id: StreamId, _message: CloseStreamBehavior, ) -> Result<Receiver<Result<()>>>

Close the pending stream that owns this StreamTarget, delivering the specified END message (if any)

The stream is closed by sending a control message (ClosePendingStream) to the reactor.

Returns a oneshot::Receiver that can be used to await the reactor’s response.

The StreamTarget will set the correct stream ID and pick the right hop, but will not validate that the message is well-formed or meaningful in context.

Note that in many cases, the actual contents of an END message can leak unwanted information. Please consider carefully before sending anything but an End::new_misc() message over a ClientTunnel. (For onion services, we send DONE )

In addition to sending the END message, this function also ensures the state of the stream map entry of this stream is updated accordingly.

Normally, you shouldn’t need to call this function, as streams are implicitly closed by the reactor when their corresponding StreamTarget is dropped. The only valid use of this function is for closing pending incoming streams (a stream is said to be pending if we have received the message initiating the stream but have not responded to it yet).

NOTE: This function should be called at most once per request. Calling it twice is an error.

pub(crate) async fn allow_stream_requests<'a, FILT>( self: Arc<Self>, allow_commands: &'a [RelayCmd], filter: FILT, ) -> Result<impl Stream<Item = IncomingStream> + use<'a, FILT>>

where FILT: IncomingStreamRequestFilter,

Tell this reactor to begin allowing incoming stream requests, and to return those pending requests in an asynchronous stream.

Ordinarily, these requests are rejected.

Needed for exits. Middle relays should reject every incoming stream, either through the filter provided in filter, or by explicitly calling .reject() on each received stream.

The user of the reactor must handle this stream (either by .accept()ing and opening and proxying the corresponding streams as appropriate, or by .reject()ing).

There can only be one Stream of this type created on a given reactor. If a such a Stream already exists, this method will return an error.

After this method has been called on a reactor, the reactor is expected to receive requests of this type indefinitely, until it is finally closed. If the Stream is dropped, the next request on this reactor will cause it to close.

Trait Implementations

impl Debug for RelayCirc

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

Formats the value using the given formatter.