Struct Upgrade 

pub struct Upgrade<Transport> { /* private fields */ }

An HTTP upgrade — owns the underlying transport along with all the data from the originating Conn.

Reading the transport directly: drain buffer first if it has bytes in it. Reading via the AsyncRead impl on Upgrade handles this automatically.

Implementations

impl<Transport> Upgrade<Transport>

pub fn received_headers(&self) -> &Headers

Borrows The http headers the peer sent to us

pub fn request_headers(&self) -> &Headers

👎Deprecated since 1.3.0:

use received_headers instead

Borrows The http headers the peer sent to us

pub fn received_headers_mut(&mut self) -> &mut Headers

Mutably borrow The http headers the peer sent to us

pub fn request_headers_mut(&mut self) -> &mut Headers

👎Deprecated since 1.3.0:

use received_headers_mut instead

Mutably borrow The http headers the peer sent to us

pub fn set_received_headers(&mut self, received_headers: Headers) -> &mut Self

Sets The http headers the peer sent to us, returning &mut Self for chaining

pub fn set_request_headers(&mut self, request_headers: Headers) -> &mut Self

👎Deprecated since 1.3.0:

use set_received_headers instead

Sets The http headers the peer sent to us, returning &mut Self for chaining

pub fn with_received_headers(self, received_headers: Headers) -> Self

Owned chainable setter for The http headers the peer sent to us, returning Self

pub fn with_request_headers(self, request_headers: Headers) -> Self

👎Deprecated since 1.3.0:

use with_received_headers instead

Owned chainable setter for The http headers the peer sent to us, returning Self

pub fn into_received_headers(self) -> Headers

Consumes self, returning The http headers the peer sent to us

pub fn into_request_headers(self) -> Headers

👎Deprecated since 1.3.0:

use into_received_headers instead

Consumes self, returning The http headers the peer sent to us

pub fn sent_headers(&self) -> &Headers

Borrows The http headers as set before the upgrade was negotiated and sent to the peer.

pub fn response_headers(&self) -> &Headers

👎Deprecated since 1.3.0:

use sent_headers instead

Borrows The http headers as set before the upgrade was negotiated and sent to the peer.

pub fn sent_headers_mut(&mut self) -> &mut Headers

Mutably borrow The http headers as set before the upgrade was negotiated and sent to the peer.

pub fn response_headers_mut(&mut self) -> &mut Headers

👎Deprecated since 1.3.0:

use sent_headers_mut instead

Mutably borrow The http headers as set before the upgrade was negotiated and sent to the peer.

pub fn set_sent_headers(&mut self, sent_headers: Headers) -> &mut Self

Sets The http headers as set before the upgrade was negotiated and sent, returning &mut Self for chaining to the peer.

pub fn set_response_headers(&mut self, response_headers: Headers) -> &mut Self

👎Deprecated since 1.3.0:

use set_sent_headers instead

Sets The http headers as set before the upgrade was negotiated and sent, returning &mut Self for chaining to the peer.

pub fn with_sent_headers(self, sent_headers: Headers) -> Self

Owned chainable setter for The http headers as set before the upgrade was negotiated and sent, returning Self to the peer.

pub fn with_response_headers(self, response_headers: Headers) -> Self

👎Deprecated since 1.3.0:

use with_sent_headers instead

Owned chainable setter for The http headers as set before the upgrade was negotiated and sent, returning Self to the peer.

pub fn into_sent_headers(self) -> Headers

Consumes self, returning The http headers as set before the upgrade was negotiated and sent to the peer.

pub fn into_response_headers(self) -> Headers

👎Deprecated since 1.3.0:

use into_sent_headers instead

Consumes self, returning The http headers as set before the upgrade was negotiated and sent to the peer.

pub fn path_mut(&mut self) -> &mut Cow<'static, str>

Mutably borrow The request path

pub fn set_path(&mut self, path: Cow<'static, str>) -> &mut Self

Sets The request path, returning &mut Self for chaining

pub fn with_path(self, path: Cow<'static, str>) -> Self

Owned chainable setter for The request path, returning Self

pub fn into_path(self) -> Cow<'static, str>

Consumes self, returning The request path

pub fn method(&self) -> Method

Returns a copy of The http request method

pub fn method_mut(&mut self) -> &mut Method

Mutably borrow The http request method

pub fn set_method(&mut self, method: Method) -> &mut Self

Sets The http request method, returning &mut Self for chaining

pub fn with_method(self, method: Method) -> Self

Owned chainable setter for The http request method, returning Self

pub fn state(&self) -> &TypeSet

Borrows Any state that has been accumulated on the Conn before negotiating the upgrade

pub fn state_mut(&mut self) -> &mut TypeSet

Mutably borrow Any state that has been accumulated on the Conn before negotiating the upgrade

pub fn set_state(&mut self, state: TypeSet) -> &mut Self

Sets Any state that has been accumulated on the Conn before negotiating the upgrade, returning &mut Self for chaining

pub fn with_state(self, state: TypeSet) -> Self

Owned chainable setter for Any state that has been accumulated on the Conn before negotiating the upgrade, returning Self

pub fn into_state(self) -> TypeSet

Consumes self, returning Any state that has been accumulated on the Conn before negotiating the upgrade

pub fn transport(&self) -> &Transport

Borrows The underlying io (often a TcpStream or similar)

pub fn transport_mut(&mut self) -> &mut Transport

Mutably borrow The underlying io (often a TcpStream or similar)

pub fn set_transport(&mut self, transport: Transport) -> &mut Self

Sets The underlying io (often a TcpStream or similar), returning &mut Self for chaining

pub fn with_transport(self, transport: Transport) -> Self

Owned chainable setter for The underlying io (often a TcpStream or similar), returning Self

pub fn into_transport(self) -> Transport

Consumes self, returning The underlying io (often a TcpStream or similar)

pub fn buffer(&self) -> &[u8]

Borrows Any bytes that have been read from the underlying transport already.

It is your responsibility to process these bytes before reading directly from the transport.

pub fn buffer_mut(&mut self) -> &mut [u8]

Mutably borrow Any bytes that have been read from the underlying transport already.

It is your responsibility to process these bytes before reading directly from the transport.

pub fn context(&self) -> &Arc<HttpContext>

Borrows The HttpContext shared for this server

pub fn context_mut(&mut self) -> &mut Arc<HttpContext>

Mutably borrow The HttpContext shared for this server

pub fn set_context(&mut self, context: Arc<HttpContext>) -> &mut Self

Sets The HttpContext shared for this server, returning &mut Self for chaining

pub fn with_context(self, context: Arc<HttpContext>) -> Self

Owned chainable setter for The HttpContext shared for this server, returning Self

pub fn into_context(self) -> Arc<HttpContext>

Consumes self, returning The HttpContext shared for this server

pub fn peer_ip(&self) -> Option<IpAddr>

Returns a copy of the ip address of the connection, if available

pub fn peer_ip_mut(&mut self) -> Option<&mut IpAddr>

Mutably borrow the ip address of the connection, if available

pub fn set_peer_ip(&mut self, peer_ip: Option<IpAddr>) -> &mut Self

Sets the ip address of the connection, if available, returning &mut Self for chaining

pub fn with_peer_ip(self, peer_ip: Option<IpAddr>) -> Self

Owned chainable setter for the ip address of the connection, if available, returning Self

pub fn take_peer_ip(&mut self) -> Option<IpAddr>

Takes the ip address of the connection, if available, leaving a None in its place

pub fn start_time(&self) -> Instant

Returns a copy of the wall-clock time at which the underlying Conn was constructed

pub fn start_time_mut(&mut self) -> &mut Instant

Mutably borrow the wall-clock time at which the underlying Conn was constructed

pub fn set_start_time(&mut self, start_time: Instant) -> &mut Self

Sets the wall-clock time at which the underlying Conn was constructed, returning &mut Self for chaining

pub fn with_start_time(self, start_time: Instant) -> Self

Owned chainable setter for the wall-clock time at which the underlying Conn was constructed, returning Self

pub fn authority(&self) -> Option<&str>

Borrows the :authority http/3 pseudo-header

pub fn authority_mut(&mut self) -> Option<&mut Cow<'static, str>>

Mutably borrow the :authority http/3 pseudo-header

pub fn set_authority( &mut self, authority: Option<Cow<'static, str>>, ) -> &mut Self

Sets the :authority http/3 pseudo-header, returning &mut Self for chaining

pub fn with_authority(self, authority: Option<Cow<'static, str>>) -> Self

Owned chainable setter for the :authority http/3 pseudo-header, returning Self

pub fn take_authority(&mut self) -> Option<Cow<'static, str>>

Takes the :authority http/3 pseudo-header, leaving a None in its place

pub fn into_authority(self) -> Option<Cow<'static, str>>

Consumes self, returning the :authority http/3 pseudo-header

pub fn scheme(&self) -> Option<&str>

Borrows the :scheme http/3 pseudo-header

pub fn scheme_mut(&mut self) -> Option<&mut Cow<'static, str>>

Mutably borrow the :scheme http/3 pseudo-header

pub fn set_scheme(&mut self, scheme: Option<Cow<'static, str>>) -> &mut Self

Sets the :scheme http/3 pseudo-header, returning &mut Self for chaining

pub fn with_scheme(self, scheme: Option<Cow<'static, str>>) -> Self

Owned chainable setter for the :scheme http/3 pseudo-header, returning Self

pub fn take_scheme(&mut self) -> Option<Cow<'static, str>>

Takes the :scheme http/3 pseudo-header, leaving a None in its place

pub fn into_scheme(self) -> Option<Cow<'static, str>>

Consumes self, returning the :scheme http/3 pseudo-header

pub fn protocol(&self) -> Option<&str>

Borrows the :protocol http/3 pseudo-header

pub fn protocol_mut(&mut self) -> Option<&mut Cow<'static, str>>

Mutably borrow the :protocol http/3 pseudo-header

pub fn set_protocol(&mut self, protocol: Option<Cow<'static, str>>) -> &mut Self

Sets the :protocol http/3 pseudo-header, returning &mut Self for chaining

pub fn with_protocol(self, protocol: Option<Cow<'static, str>>) -> Self

Owned chainable setter for the :protocol http/3 pseudo-header, returning Self

pub fn take_protocol(&mut self) -> Option<Cow<'static, str>>

Takes the :protocol http/3 pseudo-header, leaving a None in its place

pub fn into_protocol(self) -> Option<Cow<'static, str>>

Consumes self, returning the :protocol http/3 pseudo-header

pub fn http_version(&self) -> &Version

Borrows the http version

pub fn http_version_mut(&mut self) -> &mut Version

Mutably borrow the http version

pub fn set_http_version(&mut self, http_version: Version) -> &mut Self

Sets the http version, returning &mut Self for chaining

pub fn with_http_version(self, http_version: Version) -> Self

Owned chainable setter for the http version, returning Self

pub fn into_http_version(self) -> Version

Consumes self, returning the http version

pub fn status(&self) -> Option<Status>

Returns a copy of the http response status set on the underlying Conn before the upgrade (typically 101 Switching Protocols, or 200 OK for CONNECT). None if unset.

pub fn status_mut(&mut self) -> Option<&mut Status>

Mutably borrow the http response status set on the underlying Conn before the upgrade (typically 101 Switching Protocols, or 200 OK for CONNECT). None if unset.

pub fn set_status(&mut self, status: Option<Status>) -> &mut Self

Sets the http response status set on the underlying Conn before the upgrade, returning &mut Self for chaining (typically 101 Switching Protocols, or 200 OK for CONNECT). None if unset.

pub fn with_status(self, status: Option<Status>) -> Self

Owned chainable setter for the http response status set on the underlying Conn before the upgrade, returning Self (typically 101 Switching Protocols, or 200 OK for CONNECT). None if unset.

pub fn take_status(&mut self) -> Option<Status>

Takes the http response status set on the underlying Conn before the upgrade, leaving a None in its place (typically 101 Switching Protocols, or 200 OK for CONNECT). None if unset.

pub fn is_secure(&self) -> bool

Returns a copy of whether this connection was deemed secure by the handler stack

pub fn secure_mut(&mut self) -> &mut bool

Mutably borrow whether this connection was deemed secure by the handler stack

pub fn set_secure(&mut self, secure: bool) -> &mut Self

Sets whether this connection was deemed secure by the handler stack, returning &mut Self for chaining

pub fn with_secure(self, secure: bool) -> Self

Owned chainable setter for whether this connection was deemed secure by the handler stack, returning Self

pub fn received_trailers(&self) -> Option<&Headers>

Borrows Inbound trailers, populated either by a fully-consumed pre-upgrade body or by the post-upgrade inbound state machine. Some only when non-empty.

pub fn received_trailers_mut(&mut self) -> Option<&mut Headers>

Mutably borrow Inbound trailers, populated either by a fully-consumed pre-upgrade body or by the post-upgrade inbound state machine. Some only when non-empty.

pub fn take_received_trailers(&mut self) -> Option<Headers>

Takes Inbound trailers, populated either by a fully-consumed pre-upgrade body or by, leaving a None in its place the post-upgrade inbound state machine. Some only when non-empty.

impl<Transport> Upgrade<Transport>

pub fn h2_connection(&self) -> Option<&Arc<H2Connection>>

the H2Connection driver for this upgrade, if it originated from an HTTP/2 stream

pub fn h2_stream_id(&self) -> Option<u32>

the h2 stream id for this upgrade, if it originated from an HTTP/2 stream

pub fn h3_connection(&self) -> Option<&Arc<H3Connection>>

the H3Connection driver for this upgrade, if it originated from an HTTP/3 stream

pub fn h3_stream_id(&self) -> Option<u64>

the h3 stream id for this upgrade, if it originated from an HTTP/3 stream

pub fn take_buffer(&mut self) -> Vec<u8>

Take any buffered bytes

pub fn shared_state(&self) -> &TypeSet

borrow the shared state TypeSet for this application

pub fn path(&self) -> &str

the http request path up to but excluding any query component

pub fn querystring(&self) -> &str

retrieves the query component of the path

pub fn map_transport<T: AsyncRead + AsyncWrite + Send + Sync + Unpin + 'static>( self, f: impl Fn(Transport) -> T, ) -> Upgrade<T>

Modify the transport type of this upgrade.

This is useful for boxing the transport in order to erase the type argument.

impl<Transport: AsyncWrite + Unpin> Upgrade<Transport>

pub async fn send_trailers(self, trailers: Headers) -> Result<()>

Emit trailing headers and finish the outbound stream. Consumes self; further writes are statically prevented.

Per-protocol behavior:

• HTTP/1.1 with Transfer-Encoding: chunked: writes the last-chunk marker (0\r\n), the trailer section, and a final CRLF, then closes the transport.
• HTTP/2: enqueues a trailing HEADERS frame with END_STREAM via the connection driver and returns. The driver finishes the stream after draining any pending DATA frames.
• HTTP/3: encodes a trailing HEADERS frame via QPACK, writes it to the stream, then closes the stream (QUIC FIN).
• HTTP/1.1 without chunked encoding (raw upgrade, CONNECT tunnel, websocket-over-h1): trailers can’t be expressed on the wire; dropped with a log::warn! and Ok(()) returned.

Errors

Returns the underlying io::Error when the wire write fails, BrokenPipe if the stream has already been closed, and NotConnected if the carried ProtocolSession is missing the expected driver for h2/h3.

Trait Implementations

impl<Transport> AsyncRead for Upgrade<Transport>

where Transport: AsyncRead + AsyncWrite + Unpin + Send + Sync + 'static,

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize, Error>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl<Transport: AsyncWrite + Unpin> AsyncWrite for Upgrade<Transport>

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

impl<Transport> Debug for Upgrade<Transport>

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

Formats the value using the given formatter.

impl<Transport> From<Conn<Transport>> for Upgrade<Transport>

fn from(conn: Conn<Transport>) -> Self

Converts to this type from the input type.