Struct HttpSession 

pub struct HttpSession { /* private fields */ }

The HTTP 1.x server session

Implementations

impl HttpSession

pub fn new(underlying_stream: Box<dyn IO>) -> HttpSession

Create a new http server session from an established (TCP or TLS) Stream. The created session needs to call Self::read_request() first before performing any other operations.

pub async fn read_request(&mut self) -> Result<Option<usize>, Box<Error>>

Read the request header. Return Ok(Some(n)) where the read and parsing are successful. Return Ok(None) when the client closed the connection without sending any data, which is common on a reused connection.

pub fn req_header(&self) -> &RequestHeader

Return a reference of the RequestHeader this session read

Panics

this function and most other functions will panic if called before Self::read_request()

pub fn req_header_mut(&mut self) -> &mut RequestHeader

Return a mutable reference of the RequestHeader this session read

Panics

this function and most other functions will panic if called before Self::read_request()

pub fn get_header(&self, name: impl AsHeaderName) -> Option<&HeaderValue>

Get the header value for the given header name If there are multiple headers under the same name, the first one will be returned Use self.req_header().header.get_all(name) to get all the headers under the same name

pub fn request_summary(&self) -> String

Return a string $METHOD $PATH, Host: $HOST. Mostly for logging and debug purpose

pub fn is_upgrade_req(&self) -> bool

Is the request a upgrade request

pub fn get_header_bytes(&self, name: impl AsHeaderName) -> &[u8]

Get the request header as raw bytes, b"" when the header doesn’t exist

pub async fn read_body_bytes(&mut self) -> Result<Option<Bytes>, Box<Error>>

Read the request body. Ok(None) when there is no (more) body to read.

pub async fn drain_request_body(&mut self) -> Result<(), Box<Error>>

Drain the request body. Ok(()) when there is no (more) body to read.

pub fn is_body_done(&mut self) -> bool

Whether there is no (more) body need to be read.

pub fn is_body_empty(&mut self) -> bool

Whether the request has an empty body Because HTTP 1.1 clients have to send either Content-Length or Transfer-Encoding in order to signal the server that it will send the body, this function returns accurate results even only when the request header is just read.

pub async fn write_response_header( &mut self, header: Box<ResponseHeader>, ) -> Result<(), Box<Error>>

Write the response header to the client. This function can be called more than once to send 1xx informational headers excluding 101.

pub fn response_written(&self) -> Option<&ResponseHeader>

Return the response header if it is already sent.

pub fn is_upgrade(&self, header: &ResponseHeader) -> Option<bool>

Some(true) if the this is a successful upgrade Some(false) if the request is an upgrade but the response refuses it None if the request is not an upgrade.

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

pub fn will_keepalive(&self) -> bool

Return whether the session will be keepalived for connection reuse.

pub fn respect_keepalive(&mut self)

Apply keepalive settings according to the client For HTTP 1.1, assume keepalive as long as there is no Connection: Close request header. For HTTP 1.0, only keepalive if there is an explicit header Connection: keep-alive.

pub async fn write_response_header_ref( &mut self, resp: &ResponseHeader, ) -> Result<(), Box<Error>>

Same as Self::write_response_header() but takes a reference.

pub async fn write_body( &mut self, buf: &[u8], ) -> Result<Option<usize>, Box<Error>>

Write response body to the client. Return Ok(None) when there shouldn’t be more body to be written, e.g., writing more bytes than what the Content-Length header suggests

pub async fn finish_body(&mut self) -> Result<Option<usize>, Box<Error>>

Signal that there is no more body to write. This call will try to flush the buffer if there is any un-flushed data. For chunked encoding response, this call will also send the last chunk. For upgraded sessions, this call will also close the reading of the client body.

pub fn body_bytes_sent(&self) -> usize

Return how many response body bytes (application, not wire) already sent downstream

pub fn body_bytes_read(&self) -> usize

Return how many request body bytes (application, not wire) already read from downstream

pub fn retry_buffer_truncated(&self) -> bool

pub fn enable_retry_buffering(&mut self)

pub fn get_retry_buffer(&self) -> Option<Bytes>

pub async fn idle(&mut self) -> Result<usize, Box<Error>>

This function will (async) block forever until the client closes the connection.

pub async fn read_body_or_idle( &mut self, no_body_expected: bool, ) -> Result<Option<Bytes>, Box<Error>>

This function will return body bytes (same as Self::read_body_bytes()), but after the client body finishes (Ok(None) is returned), calling this function again will block forever, same as Self::idle().

pub fn get_headers_raw_bytes(&self) -> Bytes

Return the raw bytes of the request header.

pub async fn shutdown(&mut self)

Close the connection abruptly. This allows to signal the client that the connection is closed before dropping HttpSession

pub fn set_server_keepalive(&mut self, keepalive: Option<u64>)

Set the server keepalive timeout. None: disable keepalive, this session cannot be reused. Some(0): reusing this session is allowed and there is no timeout. Some(>0): reusing this session is allowed within the given timeout in seconds. If the client disallows connection reuse, then keepalive will be ignored.

pub fn set_read_timeout(&mut self, timeout: Option<Duration>)

Sets the downstream read timeout. This will trigger if we’re unable to read from the stream after timeout.

pub fn set_write_timeout(&mut self, timeout: Option<Duration>)

Sets the downstream write timeout. This will trigger if we’re unable to write to the stream after timeout. If a min_send_rate is configured then the min_send_rate calculated timeout has higher priority.

pub fn set_total_drain_timeout(&mut self, timeout: Option<Duration>)

Sets the total drain timeout. For HTTP/1.1, reusing a session requires ensuring that the request body is consumed. This timeout will be used to determine how long to wait for the entirety of the downstream request body to finish after the upstream response is completed to return the session to the reuse pool. If the timeout is exceeded, we will give up on trying to reuse the session.

Note that the downstream read timeout still applies between body byte reads.

pub fn set_min_send_rate(&mut self, min_send_rate: Option<usize>)

Sets the minimum downstream send rate in bytes per second. This is used to calculate a write timeout in seconds based on the size of the buffer being written. If a min_send_rate is configured it has higher priority over a set write_timeout. The minimum send rate must be greater than zero.

Calculated write timeout is guaranteed to be at least 1s if min_send_rate is greater than zero, a send rate of zero is equivalent to disabling.

pub fn set_ignore_info_resp(&mut self, ignore: bool)

Sets whether we ignore writing informational responses downstream.

This is a noop if the response is Upgrade or Continue and Expect: 100-continue was set on the request.

pub fn set_close_on_response_before_downstream_finish(&mut self, close: bool)

Sets whether keepalive should be disabled if response is written prior to downstream body finishing.

This may be set to avoid draining downstream if the body is no longer necessary.

pub fn digest(&self) -> &Digest

Return the Digest of the connection.

pub fn digest_mut(&mut self) -> &mut Digest

Return a mutable Digest reference for the connection.

pub fn client_addr(&self) -> Option<&SocketAddr>

Return the client (peer) address of the underlying connection.

pub fn server_addr(&self) -> Option<&SocketAddr>

Return the server (local) address of the underlying connection.

pub async fn reuse(self) -> Result<Option<Box<dyn IO>>, Box<Error>>

Consume self, if the connection can be reused, the underlying stream will be returned to be fed to the next Self::new(). This drains any remaining request body if it hasn’t yet been read and the stream is reusable.

The next session can just call Self::read_request().

If the connection cannot be reused, the underlying stream will be closed and None will be returned. If there was an error while draining any remaining request body that error will be returned.

pub async fn write_continue_response(&mut self) -> Result<(), Box<Error>>

Write a 100 Continue response to the client.

pub async fn response_duplex_vec( &mut self, tasks: Vec<HttpTask>, ) -> Result<bool, Box<Error>>

pub fn stream(&self) -> &Box<dyn IO>

Get the reference of the Stream that this HTTP session is operating upon.

pub fn into_inner(self) -> Box<dyn IO>

Consume self, the underlying stream will be returned and can be used directly, for example, in the case of HTTP upgrade. The stream is not flushed prior to being returned.