Struct StreamTarget 

pub(crate) struct StreamTarget {
    pub(crate) hop: Option<HopLocation>,
    pub(crate) stream_id: StreamId,
    pub(crate) relay_cell_format: RelayCellFormat,
    pub(crate) rate_limit_stream: Receiver<StreamRateLimit>,
    pub(crate) tx: Sender<AnyRelayMsg, MpscSpec>,
    pub(crate) tunnel: Tunnel,
}

Internal handle, used to implement a stream on a particular tunnel.

The reader and the writer for a stream should hold a StreamTarget for the stream; the reader should additionally hold an mpsc::Receiver to get relay messages for the stream.

When all the StreamTargets for a stream are dropped, the Reactor will close the stream by sending an END message to the other side. You can close a stream earlier by using StreamTarget::close or StreamTarget::close_pending.

Fields

hop: Option<HopLocation>

Which hop of the circuit this stream is with.

stream_id: StreamId

Reactor ID for this stream.

relay_cell_format: RelayCellFormat

Encoding to use for relay cells sent on this stream.

This is mostly irrelevant, except when deciding how many bytes we can pack in a DATA message.

rate_limit_stream: Receiver<StreamRateLimit>

A Stream that provides updates to the rate limit for sending data.

tx: Sender<AnyRelayMsg, MpscSpec>

Channel to send cells down.

tunnel: Tunnel

Reference to the tunnel that this stream is on.

Implementations

impl StreamTarget

pub(crate) async fn send(&mut self, msg: AnyRelayMsg) -> Result<()>

Deliver a relay message for the stream that owns this StreamTarget.

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.

pub(crate) fn close_pending( &self, 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 (CtrlMsg::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) fn close(&mut self)

Queue a “close” for the stream corresponding to this StreamTarget.

Unlike close_pending, this method does not allow the caller to provide an END message.

Once this method has been called, no more messages may be sent with StreamTarget::send, on this `StreamTarget`` or any clone of it. The reactor will try to flush any already-send messages before it closes the stream.

You don’t need to call this method if the stream is closing because all of its StreamTargets have been dropped.

pub(crate) fn protocol_error(&mut self)

Called when a circuit-level protocol error has occurred and the tunnel needs to shut down.

pub(crate) fn send_sendme(&mut self) -> 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 drain_rate_update(&mut self, 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 tunnel(&self) -> &Tunnel

Return a reference to the tunnel that this StreamTarget is using.

pub(crate) fn relay_cell_format(&self) -> RelayCellFormat

Return the kind of relay cell in use on this StreamTarget.

pub(crate) fn rate_limit_stream(&self) -> &Receiver<StreamRateLimit>

A Stream that provides updates to the rate limit for sending data.

Trait Implementations

impl Clone for StreamTarget

fn clone(&self) -> StreamTarget

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StreamTarget

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

Formats the value using the given formatter.