Struct StreamTarget

pub(crate) struct StreamTarget {
    hop: HopLocation,
    stream_id: StreamId,
    relay_cell_format: RelayCellFormat,
    tx: Sender<AnyRelayMsg, MpscSpec>,
    circ: Arc<ClientCirc>,
}

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

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: 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.

tx: Sender<AnyRelayMsg, MpscSpec>

Channel to send cells down.

circ: Arc<ClientCirc>

Reference to the circuit 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<()>>>

Available on crate feature hs-service only.

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

The stream is closed by sending a CtrlMsg::ClosePendingStream message 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 ClientCirc. (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 circuit needs to shut down.

pub(crate) async fn send_sendme(&mut self) -> Result<()>

Send a SENDME cell for this stream.

pub(crate) fn circuit(&self) -> &Arc<ClientCirc>

Available on crate features experimental-api or stream-ctrl only.

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

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

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

Trait Implementations

impl Clone for StreamTarget

fn clone(&self) -> StreamTarget

Returns a copy 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.