Struct Session

pub struct Session {
    pub downstream_session: Box<ServerSession>,
    pub cache: HttpCache,
    pub upstream_compression: ResponseCompressionCtx,
    pub ignore_downstream_range: bool,
    pub downstream_modules_ctx: HttpModuleCtx,
    /* private fields */
}

The established HTTP session

This object is what users interact with in order to access the request itself or change the proxy behavior.

Fields

downstream_session: Box<ServerSession>

the HTTP session to downstream (the client)

cache: HttpCache

The interface to control HTTP caching

upstream_compression: ResponseCompressionCtx

(de)compress responses coming into the proxy (from upstream)

ignore_downstream_range: bool

ignore downstream range (skip downstream range filters)

downstream_modules_ctx: HttpModuleCtx

Implementations

impl Session

pub fn new_h1(stream: Stream) -> Self

Create a new Session from the given Stream

This function is mostly used for testing and mocking.

pub fn new_h1_with_modules( stream: Stream, downstream_modules: &HttpModules, ) -> Self

Create a new Session from the given Stream with modules

This function is mostly used for testing and mocking.

pub fn as_downstream_mut(&mut self) -> &mut HttpSession

pub fn as_downstream(&self) -> &HttpSession

pub async fn respond_error(&mut self, error: u16) -> Result<()>

Write HTTP response with the given error code to the downstream

pub async fn write_response_header( &mut self, resp: Box<ResponseHeader>, end_of_stream: bool, ) -> Result<()>

Write the given HTTP response header to the downstream

Different from directly calling HttpSession::write_response_header, this function also invokes the filter modules.

pub async fn write_response_body( &mut self, body: Option<Bytes>, end_of_stream: bool, ) -> Result<()>

Write the given HTTP response body chunk to the downstream

Different from directly calling HttpSession::write_response_body, this function also invokes the filter modules.

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

Methods from Deref<Target = HttpSession>

pub fn is_http2(&self) -> bool

Whether the session is HTTP/2. If not it is HTTP/1.x

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

Read the request header. This method is required to be called first before doing anything else with the session.

• Ok(true): successful
• Ok(false): client exit without sending any bytes. This is normal on reused connection. In this case the user should give up this session.

pub fn req_header(&self) -> &RequestHeader

Return the request header it just read.

Panic

This function will panic if Self::read_request() is not called.

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

Return a mutable reference to request header it just read.

Panic

This function will panic if Self::read_request() is not called.

pub fn get_header<K>(&self, key: K) -> Option<&HeaderValue>

where K: AsHeaderName,

Return the header by name. None if the header doesn’t exist.

In case there are multiple headers under the same name, the first one will be returned. To get all the headers: use self.req_header().headers.get_all().

pub fn get_header_bytes<K>(&self, key: K) -> &[u8]

where K: AsHeaderName,

Get the header value in its raw format. If the header doesn’t exist, return an empty slice.

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

Read the request body. Ok(None) if no (more) body to read

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

Write the response header to client Informational headers (status code 100-199, excluding 101) can be written multiple times the final response header (status code 200+ or 101) is written.

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

Similar to write_response_header(), this fn will clone the resp internally

pub async fn write_response_body( &mut self, data: Bytes, end: bool, ) -> Result<(), Box<Error>>

Write the response body to client

pub async fn write_response_trailers( &mut self, trailers: HeaderMap, ) -> Result<(), Box<Error>>

Write the response trailers to client

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

pub fn set_keepalive(&mut self, duration: Option<u64>)

Set connection reuse. duration defines how long the connection is kept open for the next request to reuse. Noop for h2

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

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

This is a noop for h2.

pub fn set_min_send_rate(&mut self, rate: 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 a noop.

This is a noop for h2.

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

Sets whether we ignore writing informational responses downstream.

For HTTP/1.1 this is a noop if the response is Upgrade or Continue and Expect: 100-continue was set on the request.

This is a noop for h2 because informational responses are always ignored.

pub fn request_summary(&self) -> String

Return a digest of the request including the method, path and Host header

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

Return the written response header. None if it is not written yet. Only the final (status code >= 200 or 101) response header will be returned

pub async fn shutdown(&mut self)

Give up the http session abruptly. For H1 this will close the underlying connection For H2 this will send RESET frame to end this stream without impacting the connection

pub fn to_h1_raw(&self) -> Bytes

pub fn is_body_done(&mut self) -> bool

Whether the whole request body is sent

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

Notify the client that the entire body is sent for H1 chunked encoding, this will end the last empty chunk for H1 content-length, this has no effect. for H2, this will send an empty DATA frame with END_STREAM flag

pub async fn respond_error(&mut self, error: u16)

Send error response to client

pub fn is_body_empty(&mut self) -> bool

Whether there is no request body

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 read_body_or_idle( &mut self, no_body_expected: bool, ) -> Result<Option<Bytes>, Box<Error>>

Read body (same as read_request_body()) or pending forever until downstream terminates the session.

pub fn as_http1(&self) -> Option<&HttpSession>

pub fn as_http2(&self) -> Option<&HttpSession>

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

Write a 100 Continue response to the client.

pub fn is_upgrade_req(&self) -> bool

Whether this request is for upgrade (e.g., websocket)

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 digest(&self) -> Option<&Digest>

Return the Digest for the connection.

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

Return a mutable Digest reference for the connection.

Will return None if multiple H2 streams are open.

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

Return the client (peer) address of the connection.

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

Return the server (local) address of the connection.

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

Get the reference of the Stream that this HTTP/1 session is operating upon. None if the HTTP session is over H2

Trait Implementations

impl AsMut<Session> for Session

fn as_mut(&mut self) -> &mut HttpSession

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<Session> for Session

fn as_ref(&self) -> &HttpSession

Converts this type into a shared reference of the (usually inferred) input type.

impl Deref for Session

type Target = Session

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Session

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.