path: root/API-Rust.md

# 'Rusty' Rust API

Rusty is a more native Rust wrapper around the auto-generated bindings to
[libunit-wasm](https://github.com/nginx/unit-wasm/blob/main/API-C.md).

```Rust
use unit_wasm::rusty::*;
```

If using

```Rust
uwr_http_hdr_iter();
```

```Rust
use std::ffi::CStr;
use std::os::raw::c_char;
use std::os::raw::c_void;
```

## Naming

You will see references to functions etc starting with *luw_* or *LUW_* and
*uwr_".

**luw/LUW** (libunit-wasm) come from the underlying C library and in the Rust
case are the auto-generated bindings with a few manual additions.

**uwr** (Unit Wasm Rust aka '_rusty_') is a more Rust native wrapper ontop of
the bindings.

In _rusty_ the luw/LUW API is generally the low level stuff like the library
version macros and the various function handlers where they can be used as is
and there isn't a real need to create wrappers specifically for them.

1. ['Rusty' Rust API](#rusty-rust-api)
  * [Naming](#naming)
2. [Macros](#macros)
  * [Version](#version)
  * [String Conversion](#string-conversion)
  * [uwr_write_str!](#uwr_write_str)
6. [Function Handlers](#function-handlers)
  * [Optional](#optional)
    - [luw_module_init_handler](#luw_module_init_handler)
    - [luw_module_end_handler](#luw_module_end_handler)
    - [luw_request_init_handler](#luw_request_init_handler)
    - [luw_request_end_handler](#luw_request_end_handler)
    - [luw_response_end_handler](#luw_response_end_handler)
  * [Required](#required)
    - [luw_request_handler](#luw_request_handler)
    - [luw_free_handler](#luw_free_handler)
    - [luw_malloc_handler](#luw_malloc_handler)
7. [Functions](#functions)
  * [UWR_CTX_INITIALIZER](#uwr_ctx_initializer)
  * [uwr_init_ctx](#uwr_init_ctx)
  * [uwr_set_req_buf](#uwr_set_req_buf)
  * [uwr_get_http_path](#uwr_get_http_path)
  * [uwr_get_http_method](#uwr_get_http_method)
  * [uwr_get_http_version](#uwr_get_http_version)
  * [uwr_get_http_query](#uwr_get_http_query)
  * [uwr_get_http_remote](#uwr_get_http_remote)
  * [uwr_get_http_local_addr](#uwr_get_http_local_addr)
  * [uwr_get_http_local_port](#uwr_get_http_local_port)
  * [uwr_get_http_server_name](#uwr_get_http_server_name)
  * [uwr_get_http_content](#uwr_get_http_content)
  * [uwr_get_http_content_str](#uwr_get_http_content_str)
  * [uwr_get_http_content_len](#uwr_get_http_content_len)
  * [uwr_get_http_content_sent](#uwr_get_http_content_sent)
  * [uwr_http_is_tls](#uwr_http_is_tls)
  * [uwr_http_hdr_iter](#uwr_http_hdr_iter)
  * [uwr_http_hdr_get_value](#uwr_http_hdr_get_value)
  * [uwr_get_response_data_size](#uwr_get_response_data_size)
  * [uwr_mem_write_buf](#uwr_mem_write_buf)
  * [uwr_req_buf_append](#uwr_req_buf_append)
  * [uwr_mem_fill_buf_from_req](#uwr_mem_fill_buf_from_req)
  * [uwr_mem_reset](#uwr_mem_reset)
  * [uwr_http_send_response](#uwr_http_send_response)
  * [uwr_http_init_headers](#uwr_http_init_headers)
  * [uwr_http_add_header](#uwr_http_add_header)
  * [uwr_http_send_headers](#uwr_http_send_headers)
  * [uwr_http_response_end](#uwr_http_response_end)
  * [uwr_mem_get_init_size](#uwr_mem_get_init_size)
8. [Misc. Functions](#misc-functions)
  * [uwr_malloc](#uwr_malloc)
  * [uwr_free](#uwr_free)

## Macros

### Version

For the underlying libunit-wasm version.

```Rust
pub const LUW_VERSION_MAJOR: i32;
pub const LUW_VERSION_MINOR: i32;
pub const LUW_VERSION_PATCH: i32;
```

```Rust
/* Version number in hex 0xMMmmpp00 */
pub const LUW_VERSION_NUMBER: i32 =
    (LUW_VERSION_MAJOR << 24) | \
    (LUW_VERSION_MINOR << 16) | \
    (LUW_VERSION_PATCH << 8);
```

### String Conversion

```Rust
C2S!(string);
```

Converts a C string into a Rust String

Main use is internally and in the *uwr_http_hdr_iter()* callback function,
e.g

```Rust
pub extern "C" fn hdr_iter_func(
    ctx: *mut luw_ctx_t,
    name: *const c_char,
    value: *const c_char,
    _data: *mut c_void,
) -> bool {
    uwr_write_str!(ctx, "{} = {}\n", C2S!(name), C2S!(value));

    return true;
}
```

Example taken from the
[echo-request](https://github.com/nginx/unit-wasm/blob/main/examples/rust/echo-request/src/lib.rs)
Wasm demo module

```Rust
S2C!(formatted string);
```

Converts a Rust String, with optional formatting, to a C string.

Used internally.

### uwr_write_str!

```Rust
uwr_write_str!*ctx, fmt, ...);
```

This is essentially a wrapper around
[luw_mem_writep_data()](https://github.com/nginx/unit-wasm/blob/main/API-C.md#luw_mem_writep_data)

It is the main way to write responses back to the client.

It takes the luw_ctx_t context pointer, a string that will be run through the
[format!()](https://doc.rust-lang.org/std/macro.format.html) macro and any
optional arguments.

## Function Handlers

These functions are exported from the WebAssembly module and are called from
the WebAssembly runtime (the Unit WebAssembly language module in this case).

There are two types of handlers; required & optional.

luw_request_handler(), luw_malloc_handler() & luw_free_handler() are required
with the rest being optional.

libunit-wasm includes exports for these handlers and some default
implementations.

These functions are defined as _weak_ symbols and so if a developer writes
their own function of the same name, that will take precedence.

However, developers are under no obligation to use these and can create their
own with any (valid) names they like.

Whatever names developers choose, they are specified in the Unit config.

## Required

#### luw_request_handler

```Rust
#[no_mangle]
pub extern "C" fn luw_request_handler(addr: *mut u8) -> i32;
```

This is called by Unit during a request. It may be called multiple times for
a single HTTP request if there is more request data than the available memory
for host <--> module communications.

You will need to provide your own implementation of this function.

It receives the base address of the shared memory. Essentially what is
returned by luw_malloc_handler().

It returns an int, this is currently ignored but will likely be used to
indicate a HTTP status code.

#### luw_malloc_handler

```Rust
#[no_mangle]
pub extern "C" fn luw_malloc_handler(size: usize) -> u32;
```

This is called by Unit when it loads the WebAssembly language module. This
provides the shared memory used for host <--> module communications.

It receives the desired size of the memory, which is currently
NXT_WASM_MEM_SIZE + NXT_WASM_PAGE_SIZE.

However calls to luw_mem_get_init_size() will return just NXT_WASM_MEM_SIZE
(which is currently 32MiB). The extra NXT_WASM_PAGE_SIZE is to cater for
structure sizes in the response so developers can generally assume they have
the full NXT_WASM_MEM_SIZE for their data.

A default implementation of this function is provided ready for use that
calls malloc(3).

#### luw_free_handler

```Rust
#[no_mangle]
pub extern "C" fn luw_free_handler(addr: u32);
```

This is called by Unit when it shuts down the WebAssembly language module and
free's the memory previously allocated by luw_malloc_handler().

It receives the address of the memory to free.

An implementation of this function is provided ready for use that calls
free(3), in which case it receives the address that was previously returned
by luw_malloc_handler().

### Optional

#### luw_module_init_handler

```Rust
#[no_mangle]
pub extern "C" fn luw_module_init_handler();
```

This is called by Unit when it loads the WebAssembly language module.

A default dummy function is provided. If this handler is not required, there
is no need to specify it in the Unit config.

#### luw_module_end_handler

```Rust
#[no_mangle]
pub extern "C" fn luw_module_end_handler();
```

This is called by Unit when it shuts down the WebAssembly language module.

A default dummy function is provided. If this handler is not required, there
is no need to specify it in the Unit config.

#### luw_request_init_handler

```Rust
#[no_mangle]
pub extern "C" fn luw_request_init_handler();
```

This is called by Unit at the start of nxt_wasm_request_handler(), i.e at the
start of a new request.

A default dummy function is provided. If this handler is not required, there
is no need to specify it in the Unit config.

#### luw_request_end_handler

```Rust
#[no_mangle]
pub extern "C" fn luw_request_end_handler();
```

This is called by Unit at the end of nxt_wasm_request_handler(), i.e at the
end of a request.

A default dummy function is provided. If this handler is not required, there
is no need to specify it in the Unit config.

#### luw_response_end_handler

```Rust
#[no_mangle]
pub extern "C" fn luw_response_end_handler();
```

This is called by Unit after luw_http_response_end() has been called.

A default dummy function is provided. If this handler is not required, there
is no need to specify it in the Unit config.

## Functions

### UWR_CTX_INITIALIZER

```Rust
pub const fn UWR_CTX_INITIALIZER() -> luw_ctx_t;
```

Used to initialise a luw_ctx_t context structure. E.g

```Rust
let ctx = &mut UWR_CTX_INITIALIZER();
```

### uwr_init_ctx

```Rust
pub fn uwr_init_ctx(ctx: *mut luw_ctx_t, addr: *mut u8, offset: usize);
```

This function sets up a *luw_ctx_t* context structure, this contains stuff
required all throughout the API.

**addr** is a pointer to the shared memory as passed into luw_request_handler().

**offset** is where in the shared memory it should start writing the response.

#### A quick word about memory

The way the Unit WebAssembly language module (the host/runtime) and the
WebAssembly module you want to write (the guest) communicate is via a chunk
of shared memory.

This shared memory is simply the modules (guest) address space from which we
can allocate a chunk. How this memory is laid out varies on how the module
is built.

With clang/linker flags of -Wl,--stack-first -Wl,-z,stack-size=$((8*1024*1024))
we get a memory layout something like

```
  |----------------------------------------------------------------------|
  |                     |             |                                  |
  |       <-- Stack     | Global Data |      Heap -->                    |
  |                     |             |                                  |
  |----------------------------------------------------------------------|
  0                     0x800000                               0x100000000

            WebAssembly Module Linear Memory / Process Memory Layout
```

(The above is assuming _--target=wasm32-wasi_, i.e 32bit)

A chunk of memory from the heap is allocated at Unit WebAssembly language
module startup.

We currently use this same chunk of memory for both requests and responses.
This means that depending on what you're doing, you'll want to take a copy
of the request (and remember luw_request_handler() may be called multiple
times for a single http request).

That will be covered in more detail by the next function, uwr_set_req_buf().

Now back to _offset_, it may be convenient to put the response headers at the
beginning of this memory and then put the response after it, rather than
doing the headers and then doing the response as separate steps, if the
headers depends on some aspect of the response, its size for example and
Content-Length.

Example

```Rust
#[no_mangle]
pub extern "C" fn uwr_request_handler(addr: *mut u8) -> i32 {
    let ctx = &mut UWR_CTX_INITIALIZER();
    /* ... */
    uwr_init_ctx(ctx, addr, 4096 /* Response offset */);
```

### uwr_set_req_buf

```Rust
pub fn uwr_set_req_buf(
    ctx: *mut luw_ctx_t,
    buf: *mut *mut u8,
    flags: u32,
) -> i32;
```

This function is used to take a copy of the request buffer (as discussed
above).

This takes a previously initialised (with uwr_init_ctx()) luw_ctx_t.

**buf** is a buffer where the request data will written.

**flags** can be some combination (OR'd) of the following

**LUW_SRB_NONE**

No specific action to be performed. It will simply copy the request data
into the specified buffer.

**LUW_SRB_APPEND**

Sets up append mode whereby multiple successive requests will be appended
to the specified buffer.

The first request will have all its metadata copied. Subsequent requests
will _only_ have the actual body data appended.

**LUW_SRB_ALLOC**

Allocate memory for the specified buffer.

**LUW_SRB_FULL_SIZE**

Used in conjunction with *LUW_SRB_ALLOC*. By default only
*ctx->req->request_size* is allocated. If this flag is present it says to
allocate memory for the _entire_ request that will eventually be sent.

Example

```Rust
static mut CTX: luw_ctx_t = UWR_CTX_INITIALIZER();

static mut REQUEST_BUF: *mut u8 = null_mut();
*/ ... */
#[no_mangle]
pub extern "C" fn uwr_request_handler(addr: *mut u8) -> i32 {
    let ctx: *mut luw_ctx_t = unsafe { &mut CTX };

    if unsafe { REQUEST_BUF.is_null() } {
        uwr_init_ctx(ctx, addr, 0 /* Response offset */);
        /*
         * Take a copy of the request and use that, we do this
         * in APPEND mode so we can build up request_buf from
         * multiple requests.
         *
         * Just allocate memory for the total amount of data we
         * expect to get, this includes the request structure
         * itself as well as any body content.
         */
        uwr_set_req_buf(
            ctx,
            unsafe { &mut REQUEST_BUF },
            LUW_SRB_APPEND | LUW_SRB_ALLOC | LUW_SRB_FULL_SIZE,
        );
    } else {
        uwr_req_buf_append(ctx, addr);
    }

    upload_reflector(ctx);

    return 0;
}
```

That example is taken from the
[upload-reflector demo](https://github.com/nginx/unit-wasm/blob/main/examples/rust/upload-reflector/src/lib.rs)
demo module. For a simpler example see the
[echo-request demo](https://github.com/nginx/unit-wasm/blob/main/examples/rust/echo-request/src/lib.rs)

### uwr_get_http_path

```Rust
pub fn uwr_get_http_path(ctx: *const luw_ctx_t) -> &'static str;
```

This function returns a pointer to the HTTP request path.

E.g

Given a request of
```
http://localhost:8080/echo/?q=a
```
this function will return
```
/echo/?q=a
```

### uwr_get_http_method

```Rust
pub fn uwr_get_http_method(ctx: *const luw_ctx_t) -> &'static str;
```

This function returns a pointer to the HTTP method.

E.g

```
GET
```

### uwr_get_http_version

```Rust
pub fn uwr_get_http_version(ctx: *const luw_ctx_t) -> &'static str;
```

This function returns a pointer to the HTTP version.

E.g

```
1.1
```

### uwr_get_http_query

```Rust
pub fn uwr_get_http_query(ctx: *const luw_ctx_t) -> &'static str;
```

This function returns a pointer to the query string (empty string for no query
string).

E.g

Given a request of
```
http://localhost:8080/echo/?q=a
```
this function will return
```
q=a
```

### uwr_get_http_remote

```Rust
pub fn uwr_get_http_remote(ctx: *const luw_ctx_t) -> &'static str;
```

This function returns a pointer to the remote/client/peer address.

E.g

```
2001:db8::f00
```

### uwr_get_http_local_addr

```Rust
pub fn uwr_get_http_local_addr(ctx: *const luw_ctx_t) -> &'static str;
```

This function returns a pointer to the local/server address.

E.g

```
2001:db8::1
```

### uwr_get_http_local_port

```Rust
pub fn uwr_get_http_local_port(ctx: *const luw_ctx_t) -> &'static str;
```

This function returns a pointer to the local/server port.

E.g

```
443
```

### uwr_get_http_server_name

```Rust
pub fn uwr_get_http_server_name(ctx: *const luw_ctx_t) -> &'static str;
```

This function returns a pointer to the local/server name.

E.g

```
www.example.com
```

### uwr_get_http_content

```Rust
pub fn uwr_get_http_content(ctx: *const luw_ctx_t) -> *const u8;
```

This function returns a pointer to the start of the request body.

### uwr_get_http_content_str

```Rsut
pub fn uwr_get_http_content_str(ctx: *const luw_ctx_t) -> &'static str;
```

Same as above but returns a Rust str.

### uwr_get_http_content_len

```Rust
pub fn uwr_get_http_content_len(ctx: *const luw_ctx_t) -> usize;
```

This function returns the size of the overall content. I.e Content-Length.


### uwr_get_http_content_sent

```Rust
pub fn uwr_get_http_content_sent(ctx: *const luw_ctx_t) -> usize;
```

This function returns the length of the content that was sent to the
WebAssembly module in _this_ request. Remember, a single HTTP request may be
split over several calls to luw_request_handler().

### uwr_http_is_tls

```Rust
pub fn uwr_http_is_tls(ctx: *const luw_ctx_t) -> bool;
```

This function returns _true_ if the connection to Unit was made over TLS.

### uwr_http_hdr_iter

```Rust
pub fn uwr_http_hdr_iter(
    ctx: *mut luw_ctx_t,
    luw_http_hdr_iter_func: ::std::option::Option<
        unsafe extern "C" fn(
            ctx: *mut luw_ctx_t,
            name: *const c_char,
            value: *const c_char,
            data: *mut c_void,
        ) -> bool,
    >,
    user_data: *mut c_void,
);
```

This function allows to iterate over the HTTP headers. For each header it
will call the given luw_http_hdr_iter_func() function whose prototype is

```Rust
pub extern "C" fn hdr_iter_func(
    ctx: *mut luw_ctx_t,
    name: *const c_char,
    value: *const c_char,
    data: *mut c_void,
) -> bool;
```

You may call this function whatever you like. For each header it will be
passed the *luw_ctx_t*, the header name, its value and a user specified
pointer if any, can be NULL.

Returning _true_ from this function will cause the iteration process to
continue, returning _false_ will terminate it.

Example

```Rust
pub extern "C" fn hdr_iter_func(
    ctx: *mut luw_ctx_t,
    name: *const c_char,
    value: *const c_char,
    _data: *mut c_void,
) -> bool {
    /* Do something with name & value, ignoring data */

    return true;
}

/* ... *

uwr_http_hdr_iter(ctx, Some(hdr_iter_func), null_mut());
```

### uwr_http_hdr_get_value

```Rust
pub fn uwr_http_hdr_get_value(ctx: *const luw_ctx_t, hdr: &str) -> &'static str;
```

Given a HTTP header _hdr_ this function will look it up in the request and
return its value if found, otherwise _NULL_.

The lookup is done case insensitively.

### uwr_get_response_data_size

```Rust
pub fn uwr_get_response_data_size(ctx: *const luw_ctx_t) -> usize;
```

This function returns the size of the response data written to memory.

### uwr_mem_write_buf

```Rust
pub fn uwr_mem_write_buf(
    ctx: *mut luw_ctx_t,
    src: *const u8,
    size: usize,
) -> usize;
```

This function just appends _size_ bytes from _src_ to the response.

It returns the new size of the response.

### uwr_req_buf_append

```Rust
pub fn uwr_req_buf_append(ctx: *mut luw_ctx_t, src: *const u8);
```

This function appends the request data contained in _src_ to the previously
setup *request_buffer* with uwr_set_req_buf().

This function would be used after an initial request to append the data from
subsequent requests to the request_buffer.

Example

```Rust
#[no_mangle]
pub extern "C" fn uwr_request_handler(addr: *mut u8) -> i32 {
    let ctx: *mut luw_ctx_t = unsafe { &mut CTX };

    if unsafe { REQUEST_BUF.is_null() } {
        uwr_init_ctx(ctx, addr, 0 /* Response offset */);
        /*
         * Take a copy of the request and use that, we do this
         * in APPEND mode so we can build up request_buf from
         * multiple requests.
         *
         * Just allocate memory for the total amount of data we
         * expect to get, this includes the request structure
         * itself as well as any body content.
         */
        uwr_set_req_buf(
            ctx,
            unsafe { &mut REQUEST_BUF },
            LUW_SRB_APPEND | LUW_SRB_ALLOC | LUW_SRB_FULL_SIZE,
        );
    } else {
        uwr_req_buf_append(ctx, addr);
    }

    upload_reflector(ctx);

    return 0;
}
```

### uwr_mem_fill_buf_from_req

```Rust
pub fn uwr_req_buf_append(ctx: *mut luw_ctx_t, src: *const u8);
```

This is a convenience function to fill the response buffer with data from
the request buffer.

_from_ is basically the offset in the request_buffer where to start copying
data from.

Example

```Rust
/* ... */
write_bytes = uwr_mem_fill_buf_from_req(ctx, TOTAL_RESPONSE_SENT);
TOTAL_RESPONSE_SENT += write_bytes;
/* ... */
```

This is taken from the
[upload-reflector demo](https://github.com/nginx/unit-wasm/blob/main/examples/c/upload-reflector/src/lib.rs)
demo module.

In this case we build up a request_buffer on each call of
luw_request_handler(), so TOTAL_RESPONSE_SENT grows each time by how much
data was sent in _that_ request.

Here are are sending data back to the client after each time we receive it to
demonstrate the interleaving of requests and responses from the WebAssembly
module during a single http request.

This function returns the number of bytes written to the response buffer.

### uwr_mem_reset

```Rust
pub fn uwr_luw_mem_reset(ctx: *mut luw_ctx_t);
```

This function resets the response buffer size and the number of response
headers back to 0.

### uwr_http_send_response

```Rust
pub fn uwr_http_send_response(ctx: *const luw_ctx_t);
```

This function calls into Unit to send the response buffer back.

### uwr_http_init_headers

```Rust
pub fn uwr_http_init_headers(ctx: *mut luw_ctx_t, nr: usize, offset: usize);
```

This function is used in the preparation of sending back response headers.

_nr_ is the number of headers we are sending.

_offset_ is the offset into the response buffer where we are placing these
headers. This will usually be 0.

Example

```Rust
uwr_http_init_headers(ctx, 2, 0);
```

### uwr_http_add_header

```Rust
pub fn uwr_http_add_header(
    ctx: *mut luw_ctx_t,
    name: &str,
    value: &str,
);
```

This function is used to add a header to the response.

_name_ is the name of the header.

_value_ is the value of the header.

Example

```Rust
uwr_http_add_header(&ctx, "Content-Type", "text/plain");
uwr_http_add_header(
    ctx,
    "Content-Length",
    &format!("{}", uwr_get_response_data_size(ctx)),
);
```

### uwr_http_send_headers

```Rust
pub fn uwr_http_send_headers(ctx: *const luw_ctx_t);
```

This function calls into Unit and triggers the sending of the response
headers.

### uwr_http_response_end

```Rust
pub fn uwr_http_response_end();
```

This function calls into Unit and tells it this is the end of the response
which will trigger Unit to send it to the client.

### uwr_mem_get_init_size

```Rust
pub fn uwr_mem_get_init_size() -> u32;
```

This function calls into Unit to get the size of the shared memory. This is
the amount of memory you should assume you have for creating responses.
Remember you can create multiple responses before calling
luw_http_response_end().

## Misc. Functions

The following functions are convenience wrappers for the Rust bindings and
should **not** be used directly.

### uwr_malloc

```Rust
pub fn uwr_malloc(size: u32) -> *mut u8;
```

Essentially a straight wrapper for malloc(3).

### uwr_free

```Rust
pub fn uwr_free(ptr: *mut u8);
```

Essentially a straight wrapper for free(3).