Struct unit_rs::Request

pub struct Request<'a> { /* private fields */ }

A request received by the NGINX Unit server.

This object can be used to inspect the properties and headers of the request, and send a response back to the client.

Implementations

impl<'a> Request<'a>

pub fn create_response(
    &'a self,
    status_code: u16,
    max_fields_count: usize,
    max_response_size: usize
) -> UnitResult<Response<'a>>

Allocate a buffer for the initial response, capable of containing at most max_fields_count fields (headers), and at most max_response_size bytes for the field names, field values, and response content combined.

The buffer can be filled and sent using the methods on the returned Response.

The buffer can be resized with Response::realloc.

pub fn send_response(
    &self,
    status_code: u16,
    headers: &[(impl AsRef<[u8]>, impl AsRef<[u8]>)],
    body: impl AsRef<[u8]>
) -> UnitResult<()>

Send an initial response to the client.

This is a convenience method that calls the Request::create_response, Response::add_field, Response::add_content, and Response::send methods.

Panic

This method will panic if the header name is longer than u8::MAX bytes, or if the header value is longer than u32::MAX.

pub fn write_chunks(&'a self, chunk_size: usize) -> Result<BodyWriter<'a>>

Allocate and send additional response chunks to the client, using a writer to copy data into the chunks.

A chunk will be immediately sent to the client once the writer’s memory buffer reaches chunk_size, or flush() is called on the writer.

The writer will also flush when dropped, but may panic in case of errors.

Panic

Panics if flushing was not successful when flushing during a drop. It is recommended to manually call flush(), or use the Request::send_chunks_with_writer() method.

pub fn send_chunks_with_writer<T>(
    &'a self,
    chunk_size: usize,
    f: impl FnOnce(&mut BodyWriter<'a>) -> Result<T>
) -> UnitResult<T>

Allocate and send additional response chunks to the client.

This is similar to write_chunks(), but will also flush the writer before returning, convert the result into a UnitError, and log the error.

This is useful to prevent errors from being silently ignored if the writer needs to flush while being dropped.

pub fn send_chunk_with_buffer<T>(
    &self,
    size: usize,
    f: impl FnOnce(&mut &mut [u8]) -> UnitResult<T>
) -> UnitResult<T>

Send another chunk of bytes for this request’s response. The bytes will be immediately sent to the client.

This method allocates a buffer in Unit’s shared memory region, and calls a user function to fill it.

The user function receives a &mut &mut [u8] slice, and the write! macro can be used to advance the start position of the slice. Only the bytes between the original start and the new start positions will be sent, and the rest will be discarded.

pub fn read_body(&self, target: &mut [u8]) -> usize

Copy bytes from the request body into the target buffer and return the number of bytes written.

If the buffer is smaller than the contents of the body, the contents will be truncated to the size of the buffer.

pub fn body(&self) -> BodyReader<'a>

Create a reader that implements the Read trait, which will read from the request body in a blocking manner.

pub fn fields(&self) -> impl Iterator<Item = (&str, &str)>

Create an interator over all header (name, value) tuples.

pub fn tls(&self) -> bool

Return whether or not the request was encrypted.

pub fn method(&self) -> &str

Return the method of the request (e.g. “GET”).

pub fn version(&self) -> &str

Return the protocol version of the request (e.g. “HTTP/1.1”).

pub fn remote(&self) -> &str

Return the remote IP address of the client.

pub fn local(&self) -> &str

Return the local IP address of the server.

pub fn server_name(&self) -> &str

Return the host name of the server.

pub fn target(&self) -> &str

Return the combined URI path and query string.

pub fn path(&self) -> &str

Return the URI path.

pub fn query(&self) -> &str

Return the URI query string.

pub fn log<S: AsRef<str>>(&self, level: LogLevel, message: S)

Log an error message.