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

Examples found in repository

examples/hello_world.rs (line 11)

fn main() {
    let mut unit = Unit::new().unwrap();

    unit.set_request_handler(|req: Request| {
        let headers = &[("Content-Type", "text/plain")];
        let body = "Hello world!\n";
        req.send_response(200, headers, body)?;

        Ok(())
    });

    unit.run();
}

examples/multi_threaded.rs (line 43)

fn worker(thread_id: i32, global_visits: Arc<AtomicI32>) {
    let mut unit = Unit::new().unwrap();

    // Thread state, available through a mutable, unique reference.
    let mut thread_visits = 0;

    unit.set_request_handler(move |req: Request| {
        if req.path() == "/panic" {
            // This library supports safely forwarding panics through the FFI.
            panic!("The /panic path panics!")
        }

        let headers = &[("Content-Type", "text/plain")];
        let body = "Hello world!\n";
        req.send_response(200, headers, body)?;
        thread_visits += 1;
        global_visits.fetch_add(1, Ordering::Release);

        req.send_chunk_with_buffer(4096, |buf| {
            writeln!(
                buf,
                "Thread {} visits: {} (global visits: {})",
                thread_id,
                thread_visits,
                global_visits.load(Ordering::Acquire),
            )
            .unwrap();
            Ok(())
        })?;

        Ok(())
    });

    unit.run();
}

examples/request_info.rs (line 19)

fn request_handler(req: Request) -> UnitResult<()> {
    // Create and send a response.
    let headers = &[("Content-Type", "text/plain")];
    req.send_response(200, headers, "Hello world!\n")?;

    // NGINX Unit uses "Transfer-Encoding: chunked" by default, and can send
    // additional chunks after the initial response was already sent to the
    // client.
    req.send_chunks_with_writer(4096, |w| {
        write!(w, "Request data:\n")?;
        write!(w, "  Method: {}\n", req.method())?;
        write!(w, "  Protocol: {}\n", req.version())?;
        write!(w, "  Remote addr: {}\n", req.remote())?;
        write!(w, "  Local addr: {}\n", req.local())?;
        write!(w, "  Server name: {}\n", req.server_name())?;
        write!(w, "  Target: {}\n", req.target())?;
        write!(w, "  Path: {}\n", req.path())?;
        write!(w, "  Query: {}\n", req.query())?;
        write!(w, "  Fields:\n")?;
        for (name, value) in req.fields() {
            write!(w, "    {}: {}\n", name, value).unwrap();
        }
        write!(w, "  Body:\n    ").unwrap();

        w.copy_from_reader(req.body())?;

        Ok(())
    })?;

    Ok(())
}

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.

Examples found in repository

examples/request_info.rs (lines 24-43)

fn request_handler(req: Request) -> UnitResult<()> {
    // Create and send a response.
    let headers = &[("Content-Type", "text/plain")];
    req.send_response(200, headers, "Hello world!\n")?;

    // NGINX Unit uses "Transfer-Encoding: chunked" by default, and can send
    // additional chunks after the initial response was already sent to the
    // client.
    req.send_chunks_with_writer(4096, |w| {
        write!(w, "Request data:\n")?;
        write!(w, "  Method: {}\n", req.method())?;
        write!(w, "  Protocol: {}\n", req.version())?;
        write!(w, "  Remote addr: {}\n", req.remote())?;
        write!(w, "  Local addr: {}\n", req.local())?;
        write!(w, "  Server name: {}\n", req.server_name())?;
        write!(w, "  Target: {}\n", req.target())?;
        write!(w, "  Path: {}\n", req.path())?;
        write!(w, "  Query: {}\n", req.query())?;
        write!(w, "  Fields:\n")?;
        for (name, value) in req.fields() {
            write!(w, "    {}: {}\n", name, value).unwrap();
        }
        write!(w, "  Body:\n    ").unwrap();

        w.copy_from_reader(req.body())?;

        Ok(())
    })?;

    Ok(())
}

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.

Examples found in repository

examples/multi_threaded.rs (lines 47-57)

fn worker(thread_id: i32, global_visits: Arc<AtomicI32>) {
    let mut unit = Unit::new().unwrap();

    // Thread state, available through a mutable, unique reference.
    let mut thread_visits = 0;

    unit.set_request_handler(move |req: Request| {
        if req.path() == "/panic" {
            // This library supports safely forwarding panics through the FFI.
            panic!("The /panic path panics!")
        }

        let headers = &[("Content-Type", "text/plain")];
        let body = "Hello world!\n";
        req.send_response(200, headers, body)?;
        thread_visits += 1;
        global_visits.fetch_add(1, Ordering::Release);

        req.send_chunk_with_buffer(4096, |buf| {
            writeln!(
                buf,
                "Thread {} visits: {} (global visits: {})",
                thread_id,
                thread_visits,
                global_visits.load(Ordering::Acquire),
            )
            .unwrap();
            Ok(())
        })?;

        Ok(())
    });

    unit.run();
}

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.

Examples found in repository

examples/request_info.rs (line 40)

fn request_handler(req: Request) -> UnitResult<()> {
    // Create and send a response.
    let headers = &[("Content-Type", "text/plain")];
    req.send_response(200, headers, "Hello world!\n")?;

    // NGINX Unit uses "Transfer-Encoding: chunked" by default, and can send
    // additional chunks after the initial response was already sent to the
    // client.
    req.send_chunks_with_writer(4096, |w| {
        write!(w, "Request data:\n")?;
        write!(w, "  Method: {}\n", req.method())?;
        write!(w, "  Protocol: {}\n", req.version())?;
        write!(w, "  Remote addr: {}\n", req.remote())?;
        write!(w, "  Local addr: {}\n", req.local())?;
        write!(w, "  Server name: {}\n", req.server_name())?;
        write!(w, "  Target: {}\n", req.target())?;
        write!(w, "  Path: {}\n", req.path())?;
        write!(w, "  Query: {}\n", req.query())?;
        write!(w, "  Fields:\n")?;
        for (name, value) in req.fields() {
            write!(w, "    {}: {}\n", name, value).unwrap();
        }
        write!(w, "  Body:\n    ").unwrap();

        w.copy_from_reader(req.body())?;

        Ok(())
    })?;

    Ok(())
}

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

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

Examples found in repository

examples/request_info.rs (line 35)

fn request_handler(req: Request) -> UnitResult<()> {
    // Create and send a response.
    let headers = &[("Content-Type", "text/plain")];
    req.send_response(200, headers, "Hello world!\n")?;

    // NGINX Unit uses "Transfer-Encoding: chunked" by default, and can send
    // additional chunks after the initial response was already sent to the
    // client.
    req.send_chunks_with_writer(4096, |w| {
        write!(w, "Request data:\n")?;
        write!(w, "  Method: {}\n", req.method())?;
        write!(w, "  Protocol: {}\n", req.version())?;
        write!(w, "  Remote addr: {}\n", req.remote())?;
        write!(w, "  Local addr: {}\n", req.local())?;
        write!(w, "  Server name: {}\n", req.server_name())?;
        write!(w, "  Target: {}\n", req.target())?;
        write!(w, "  Path: {}\n", req.path())?;
        write!(w, "  Query: {}\n", req.query())?;
        write!(w, "  Fields:\n")?;
        for (name, value) in req.fields() {
            write!(w, "    {}: {}\n", name, value).unwrap();
        }
        write!(w, "  Body:\n    ").unwrap();

        w.copy_from_reader(req.body())?;

        Ok(())
    })?;

    Ok(())
}

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”).

Examples found in repository

examples/request_info.rs (line 26)

fn request_handler(req: Request) -> UnitResult<()> {
    // Create and send a response.
    let headers = &[("Content-Type", "text/plain")];
    req.send_response(200, headers, "Hello world!\n")?;

    // NGINX Unit uses "Transfer-Encoding: chunked" by default, and can send
    // additional chunks after the initial response was already sent to the
    // client.
    req.send_chunks_with_writer(4096, |w| {
        write!(w, "Request data:\n")?;
        write!(w, "  Method: {}\n", req.method())?;
        write!(w, "  Protocol: {}\n", req.version())?;
        write!(w, "  Remote addr: {}\n", req.remote())?;
        write!(w, "  Local addr: {}\n", req.local())?;
        write!(w, "  Server name: {}\n", req.server_name())?;
        write!(w, "  Target: {}\n", req.target())?;
        write!(w, "  Path: {}\n", req.path())?;
        write!(w, "  Query: {}\n", req.query())?;
        write!(w, "  Fields:\n")?;
        for (name, value) in req.fields() {
            write!(w, "    {}: {}\n", name, value).unwrap();
        }
        write!(w, "  Body:\n    ").unwrap();

        w.copy_from_reader(req.body())?;

        Ok(())
    })?;

    Ok(())
}

pub fn version(&self) -> &str

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

Examples found in repository

examples/request_info.rs (line 27)

fn request_handler(req: Request) -> UnitResult<()> {
    // Create and send a response.
    let headers = &[("Content-Type", "text/plain")];
    req.send_response(200, headers, "Hello world!\n")?;

    // NGINX Unit uses "Transfer-Encoding: chunked" by default, and can send
    // additional chunks after the initial response was already sent to the
    // client.
    req.send_chunks_with_writer(4096, |w| {
        write!(w, "Request data:\n")?;
        write!(w, "  Method: {}\n", req.method())?;
        write!(w, "  Protocol: {}\n", req.version())?;
        write!(w, "  Remote addr: {}\n", req.remote())?;
        write!(w, "  Local addr: {}\n", req.local())?;
        write!(w, "  Server name: {}\n", req.server_name())?;
        write!(w, "  Target: {}\n", req.target())?;
        write!(w, "  Path: {}\n", req.path())?;
        write!(w, "  Query: {}\n", req.query())?;
        write!(w, "  Fields:\n")?;
        for (name, value) in req.fields() {
            write!(w, "    {}: {}\n", name, value).unwrap();
        }
        write!(w, "  Body:\n    ").unwrap();

        w.copy_from_reader(req.body())?;

        Ok(())
    })?;

    Ok(())
}

pub fn remote(&self) -> &str

Return the remote IP address of the client.

Examples found in repository

examples/request_info.rs (line 28)

fn request_handler(req: Request) -> UnitResult<()> {
    // Create and send a response.
    let headers = &[("Content-Type", "text/plain")];
    req.send_response(200, headers, "Hello world!\n")?;

    // NGINX Unit uses "Transfer-Encoding: chunked" by default, and can send
    // additional chunks after the initial response was already sent to the
    // client.
    req.send_chunks_with_writer(4096, |w| {
        write!(w, "Request data:\n")?;
        write!(w, "  Method: {}\n", req.method())?;
        write!(w, "  Protocol: {}\n", req.version())?;
        write!(w, "  Remote addr: {}\n", req.remote())?;
        write!(w, "  Local addr: {}\n", req.local())?;
        write!(w, "  Server name: {}\n", req.server_name())?;
        write!(w, "  Target: {}\n", req.target())?;
        write!(w, "  Path: {}\n", req.path())?;
        write!(w, "  Query: {}\n", req.query())?;
        write!(w, "  Fields:\n")?;
        for (name, value) in req.fields() {
            write!(w, "    {}: {}\n", name, value).unwrap();
        }
        write!(w, "  Body:\n    ").unwrap();

        w.copy_from_reader(req.body())?;

        Ok(())
    })?;

    Ok(())
}

pub fn local(&self) -> &str

Return the local IP address of the server.

Examples found in repository

examples/request_info.rs (line 29)

fn request_handler(req: Request) -> UnitResult<()> {
    // Create and send a response.
    let headers = &[("Content-Type", "text/plain")];
    req.send_response(200, headers, "Hello world!\n")?;

    // NGINX Unit uses "Transfer-Encoding: chunked" by default, and can send
    // additional chunks after the initial response was already sent to the
    // client.
    req.send_chunks_with_writer(4096, |w| {
        write!(w, "Request data:\n")?;
        write!(w, "  Method: {}\n", req.method())?;
        write!(w, "  Protocol: {}\n", req.version())?;
        write!(w, "  Remote addr: {}\n", req.remote())?;
        write!(w, "  Local addr: {}\n", req.local())?;
        write!(w, "  Server name: {}\n", req.server_name())?;
        write!(w, "  Target: {}\n", req.target())?;
        write!(w, "  Path: {}\n", req.path())?;
        write!(w, "  Query: {}\n", req.query())?;
        write!(w, "  Fields:\n")?;
        for (name, value) in req.fields() {
            write!(w, "    {}: {}\n", name, value).unwrap();
        }
        write!(w, "  Body:\n    ").unwrap();

        w.copy_from_reader(req.body())?;

        Ok(())
    })?;

    Ok(())
}

pub fn server_name(&self) -> &str

Return the host name of the server.

Examples found in repository

examples/request_info.rs (line 30)

fn request_handler(req: Request) -> UnitResult<()> {
    // Create and send a response.
    let headers = &[("Content-Type", "text/plain")];
    req.send_response(200, headers, "Hello world!\n")?;

    // NGINX Unit uses "Transfer-Encoding: chunked" by default, and can send
    // additional chunks after the initial response was already sent to the
    // client.
    req.send_chunks_with_writer(4096, |w| {
        write!(w, "Request data:\n")?;
        write!(w, "  Method: {}\n", req.method())?;
        write!(w, "  Protocol: {}\n", req.version())?;
        write!(w, "  Remote addr: {}\n", req.remote())?;
        write!(w, "  Local addr: {}\n", req.local())?;
        write!(w, "  Server name: {}\n", req.server_name())?;
        write!(w, "  Target: {}\n", req.target())?;
        write!(w, "  Path: {}\n", req.path())?;
        write!(w, "  Query: {}\n", req.query())?;
        write!(w, "  Fields:\n")?;
        for (name, value) in req.fields() {
            write!(w, "    {}: {}\n", name, value).unwrap();
        }
        write!(w, "  Body:\n    ").unwrap();

        w.copy_from_reader(req.body())?;

        Ok(())
    })?;

    Ok(())
}

pub fn target(&self) -> &str

Return the combined URI path and query string.

Examples found in repository

examples/request_info.rs (line 31)

fn request_handler(req: Request) -> UnitResult<()> {
    // Create and send a response.
    let headers = &[("Content-Type", "text/plain")];
    req.send_response(200, headers, "Hello world!\n")?;

    // NGINX Unit uses "Transfer-Encoding: chunked" by default, and can send
    // additional chunks after the initial response was already sent to the
    // client.
    req.send_chunks_with_writer(4096, |w| {
        write!(w, "Request data:\n")?;
        write!(w, "  Method: {}\n", req.method())?;
        write!(w, "  Protocol: {}\n", req.version())?;
        write!(w, "  Remote addr: {}\n", req.remote())?;
        write!(w, "  Local addr: {}\n", req.local())?;
        write!(w, "  Server name: {}\n", req.server_name())?;
        write!(w, "  Target: {}\n", req.target())?;
        write!(w, "  Path: {}\n", req.path())?;
        write!(w, "  Query: {}\n", req.query())?;
        write!(w, "  Fields:\n")?;
        for (name, value) in req.fields() {
            write!(w, "    {}: {}\n", name, value).unwrap();
        }
        write!(w, "  Body:\n    ").unwrap();

        w.copy_from_reader(req.body())?;

        Ok(())
    })?;

    Ok(())
}

pub fn path(&self) -> &str

Return the URI path.

Examples found in repository

examples/multi_threaded.rs (line 36)

fn worker(thread_id: i32, global_visits: Arc<AtomicI32>) {
    let mut unit = Unit::new().unwrap();

    // Thread state, available through a mutable, unique reference.
    let mut thread_visits = 0;

    unit.set_request_handler(move |req: Request| {
        if req.path() == "/panic" {
            // This library supports safely forwarding panics through the FFI.
            panic!("The /panic path panics!")
        }

        let headers = &[("Content-Type", "text/plain")];
        let body = "Hello world!\n";
        req.send_response(200, headers, body)?;
        thread_visits += 1;
        global_visits.fetch_add(1, Ordering::Release);

        req.send_chunk_with_buffer(4096, |buf| {
            writeln!(
                buf,
                "Thread {} visits: {} (global visits: {})",
                thread_id,
                thread_visits,
                global_visits.load(Ordering::Acquire),
            )
            .unwrap();
            Ok(())
        })?;

        Ok(())
    });

    unit.run();
}

examples/request_info.rs (line 32)

fn request_handler(req: Request) -> UnitResult<()> {
    // Create and send a response.
    let headers = &[("Content-Type", "text/plain")];
    req.send_response(200, headers, "Hello world!\n")?;

    // NGINX Unit uses "Transfer-Encoding: chunked" by default, and can send
    // additional chunks after the initial response was already sent to the
    // client.
    req.send_chunks_with_writer(4096, |w| {
        write!(w, "Request data:\n")?;
        write!(w, "  Method: {}\n", req.method())?;
        write!(w, "  Protocol: {}\n", req.version())?;
        write!(w, "  Remote addr: {}\n", req.remote())?;
        write!(w, "  Local addr: {}\n", req.local())?;
        write!(w, "  Server name: {}\n", req.server_name())?;
        write!(w, "  Target: {}\n", req.target())?;
        write!(w, "  Path: {}\n", req.path())?;
        write!(w, "  Query: {}\n", req.query())?;
        write!(w, "  Fields:\n")?;
        for (name, value) in req.fields() {
            write!(w, "    {}: {}\n", name, value).unwrap();
        }
        write!(w, "  Body:\n    ").unwrap();

        w.copy_from_reader(req.body())?;

        Ok(())
    })?;

    Ok(())
}

pub fn query(&self) -> &str

Return the URI query string.

Examples found in repository

examples/request_info.rs (line 33)

fn request_handler(req: Request) -> UnitResult<()> {
    // Create and send a response.
    let headers = &[("Content-Type", "text/plain")];
    req.send_response(200, headers, "Hello world!\n")?;

    // NGINX Unit uses "Transfer-Encoding: chunked" by default, and can send
    // additional chunks after the initial response was already sent to the
    // client.
    req.send_chunks_with_writer(4096, |w| {
        write!(w, "Request data:\n")?;
        write!(w, "  Method: {}\n", req.method())?;
        write!(w, "  Protocol: {}\n", req.version())?;
        write!(w, "  Remote addr: {}\n", req.remote())?;
        write!(w, "  Local addr: {}\n", req.local())?;
        write!(w, "  Server name: {}\n", req.server_name())?;
        write!(w, "  Target: {}\n", req.target())?;
        write!(w, "  Path: {}\n", req.path())?;
        write!(w, "  Query: {}\n", req.query())?;
        write!(w, "  Fields:\n")?;
        for (name, value) in req.fields() {
            write!(w, "    {}: {}\n", name, value).unwrap();
        }
        write!(w, "  Body:\n    ").unwrap();

        w.copy_from_reader(req.body())?;

        Ok(())
    })?;

    Ok(())
}

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

Log an error message.