C Library for creating WebAssembly modules for use with NGINX Unit.
#include <unit/unit-wasm.h>- luw_init_ctx
- luw_set_req_buf
- luw_get_http_path
- luw_get_http_method
- luw_get_http_version
- luw_get_http_query
- luw_get_http_remote
- luw_get_http_local_addr
- luw_get_http_local_port
- luw_get_http_server_name
- luw_get_http_content
- luw_get_http_content_len
- luw_get_http_content_sent
- luw_get_http_total_content_sent
- luw_http_is_tls
- luw_http_hdr_iter
- luw_http_hdr_get_value
- luw_get_response_data_size
- luw_mem_writep
- luw_mem_writep_data
- luw_req_buf_append
- luw_req_buf_copy
- luw_mem_splice_file
- luw_mem_fill_buf_from_req
- luw_mem_reset
- luw_http_set_response_status
- luw_http_send_response
- luw_http_init_headers
- luw_http_add_header
- luw_http_send_headers
- luw_http_response_end
- luw_mem_get_init_size
- luw_foreach_http_hdr
#define LUW_VERSION_MAJOR M
#define LUW_VERSION_MINOR m
#define LUW_VERSION_PATCH p/* Version number in hex 0xMMmmpp00 */
#define LUW_VERSION_NUMBER \
( (LUW_VERSION_MAJOR << 24) | \
(LUW_VERSION_MINOR << 16) | \
(LUW_VERSION_PATCH << 8) )#define __luw_export_name(name) __attribute__((export_name(name)))#define __luw_unused __attribute__((unused))
#define __luw_maybe_unused __luw_unused#define luw_foreach_http_hdr(ctx, iter, name, value) \
for (iter = ctx.req->fields, \
name = (const char *)ctx.req + iter->name_off; \
(iter < (ctx.req->fields + ctx.req->nr_fields)) && \
(value = (const char *)ctx.req + iter->value_off); \
iter++, name = (const char *)ctx.req + iter->name_off)typedef uint64_t u64;
typedef int64_t s64;
typedef uint32_t u32;
typedef int32_t s32;
typedef uint16_t u16;
typedef int16_t s16;
typedef uint8_t u8;
typedef int8_t s8;typedef enum {
LUW_SRB_NONE = 0x00,
LUW_SRB_APPEND = 0x01,
LUW_SRB_ALLOC = 0x02,
LUW_SRB_FULL_SIZE = 0x04,
LUW_SRB_FLAGS_ALL = (LUW_SRB_NONE|LUW_SRB_APPEND|LUW_SRB_ALLOC|
LUW_SRB_FULL_SIZE)
} luw_srb_flags_t;typedef enum {
LUW_HTTP_CONTINUE = 100,
LUW_HTTP_SWITCHING_PROTOCOLS = 101,
LUW_HTTP_OK = 200,
LUW_HTTP_CREATED = 201,
LUW_HTTP_ACCEPTED = 202,
LUW_HTTP_NO_CONTENT = 204,
LUW_HTTP_MULTIPLE_CHOICES = 300,
LUW_HTTP_MOVED_PERMANENTLY = 301,
LUW_HTTP_FOUND = 302,
LUW_HTTP_SEE_OTHER = 303,
LUW_HTTP_NOT_MODIFIED = 304,
LUW_HTTP_TEMPORARY_REDIRECT = 307,
LUW_HTTP_PERMANENT_REDIRECT = 308,
LUW_HTTP_BAD_REQUEST = 400,
LUW_HTTP_UNAUTHORIZED = 401,
LUW_HTTP_FORBIDDEN = 403,
LUW_HTTP_NOT_FOUND = 404,
LUW_HTTP_METHOD_NOT_ALLOWED = 405,
LUW_HTTP_NOT_ACCEPTABLE = 406,
LUW_HTTP_REQUEST_TIMEOUT = 408,
LUW_HTTP_CONFLICT = 409,
LUW_HTTP_GONE = 410,
LUW_HTTP_LENGTH_REQUIRED = 411,
LUW_HTTP_PAYLOAD_TOO_LARGE = 413,
LUW_HTTP_URI_TOO_LONG = 414,
LUW_HTTP_UNSUPPORTED_MEDIA_TYPE = 415,
LUW_HTTP_UPGRADE_REQUIRED = 426,
LUW_HTTP_TOO_MANY_REQUESTS = 429,
LUW_HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE = 431,
/* Proposed by RFC 7725 */
LUW_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS = 451,
LUW_HTTP_INTERNAL_SERVER_ERROR = 500,
LUW_HTTP_NOT_IMPLEMENTED = 501,
LUW_HTTP_BAD_GATEWAY = 502,
LUW_HTTP_SERVICE_UNAVAILABLE = 503,
LUW_HTTP_GATEWAY_TIMEOUT = 504,
} luw_http_status_t;struct luw_hdr_field {
u32 name_off;
u32 name_len;
u32 value_off;
u32 value_len;
};struct luw_req {
u32 method_off;
u32 method_len;
u32 version_off;
u32 version_len;
u32 path_off;
u32 path_len;
u32 query_off;
u32 query_len;
u32 remote_off;
u32 remote_len;
u32 local_addr_off;
u32 local_addr_len;
u32 local_port_off;
u32 local_port_len;
u32 server_name_off;
u32 server_name_len;
u64 content_len;
u64 total_content_sent;
u32 content_sent;
u32 content_off;
u32 request_size;
u32 nr_fields;
u32 tls;
char __pad[4];
struct luw_hdr_field fields[];
};struct luw_resp {
u32 size;
u8 data[];
};struct luw_resp_hdr {
u32 nr_fields;
struct luw_hdr_field fields[];
};typedef struct {
/* pointer to the shared memory */
u8 *addr;
/* points to the end of ctx->resp->data */
u8 *mem;
/* struct luw_req representation of the shared memory */
struct luw_req *req;
/* struct luw_resp representation of the shared memory */
struct luw_resp *resp;
/* struct luw_resp_hdr representation of the shared memory */
struct luw_resp_hdr *resp_hdr;
/* offset to where the struct resp starts in the shared memory */
size_t resp_offset;
/* points to the external buffer used for a copy of the request */
u8 *req_buf;
/* points to the end of the fields array in struct luw_resp_hdr */
u8 *hdrp;
/* points to the end of ctx->req_buf */
u8 *reqp;
/* tracks the response header index number */
s32 resp_hdr_idx;
} luw_ctx_t;typedef struct luw_hdr_field luw_http_hdr_iter_t;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.
__attribute__((export_name("luw_request_handler"), __weak__))
int luw_request_handler(u8 *addr);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().
This memory will contain a struct luw_req.
It returns an int. This should nearly always be 0.
If you wish to indicate a '500 Internal Server Error', for example if some internal API has failed or an OS level error occurred, then you can simply return -1, if you have haven't already sent any response or headers.
You can still return 0 and set the HTTP response status to 500 using luw_http_set_response_status.
__attribute__((export_name("luw_malloc_handler"), __weak__))
u32 luw_malloc_handler(size_t size);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).
__attribute__((export_name("luw_free_handler"), __weak__))
void luw_free_handler(u32 addr);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().
__attribute__((export_name("luw_module_init_handler"), __weak__))
void luw_module_init_handler(void);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.
__attribute__((export_name("luw_module_end_handler"), __weak__))
void luw_module_end_handler(void);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.
__attribute__((export_name("luw_request_init_handler"), __weak__))
void luw_request_init_handler(void);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.
__attribute__((export_name("luw_request_end_handler"), __weak__))
void luw_request_end_handler(void);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.
__attribute__((export_name("luw_response_end_handler"), __weak__))
void luw_response_end_handler(void);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.
void luw_init_ctx(luw_ctx_t *ctx, u8 *addr, size_t offset);This function sets up a luw_ctx_t context structure, this contains stuff required all throughout the API. It's a typedef for opaqueness and you should not in general be concerned with its contents.
It take a pointer to a stack allocated luw_ctx_t, this will be zeroed and have various members initialised.
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.
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=$((810241024)) 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, luw_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
luw_ctx_t ctx;
/* ... */
luw_init_ctx(&ctx, addr, 4096 /* Response offset */);int luw_set_req_buf(luw_ctx_t *ctx, u8 **buf, unsigned int flags);This function is used to take a copy of the request buffer (as discussed above).
This takes a previously initialised (with luw_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
static u8 *request_buf;
*/ ... */
int luw_request_handler(u8 *addr)
{
if (!request_buf) {
luw_init_ctx(&ctx, addr, 0);
/*
* 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.
*/
luw_set_req_buf(&ctx, &request_buf,
LUW_SRB_APPEND|LUW_SRB_ALLOC|LUW_SRB_FULL_SIZE);
} else {
luw_req_buf_append(&ctx, addr);
}
/* operate on the request (ctx) */
return 0;
}That example is taken from the luw-upload-reflector.c demo module. For a simpler example see luw-echo-request.c
const char *luw_get_http_path(const luw_ctx_t *ctx);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
const char *luw_get_http_method(const luw_ctx_t *ctx);This function returns a pointer to the HTTP method.
E.g
GET
const char *luw_get_http_version(const luw_ctx_t *ctx);This function returns a pointer to the HTTP version.
E.g
1.1
const char *luw_get_http_query(const luw_ctx_t *ctx);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
const char *luw_get_http_remote(const luw_ctx_t *ctx);This function returns a pointer to the remote/client/peer address.
E.g
2001:db8::f00
const char *luw_get_http_local_addr(const luw_ctx_t *ctx);This function returns a pointer to the local/server address.
E.g
2001:db8::1
const char *luw_get_http_local_port(const luw_ctx_t *ctx);This function returns a pointer to the local/server port.
E.g
443
const char *luw_get_http_server_name(const luw_ctx_t *ctx);This function returns a pointer to the local/server name.
E.g
www.example.com
const u8 *luw_get_http_content(const luw_ctx_t *ctx);This function returns a pointer to the start of the request body.
u64 luw_get_http_content_len(const luw_ctx_t *ctx);This function returns the size of the overall content. I.e Content-Length.
Prior to version 0.3.0 it returned a size_t
size_t luw_get_http_content_sent(const luw_ctx_t *ctx);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().
u64 luw_get_http_total_content_sent(const luw_ctx_t *ctx);This function returns the total length of the content that was sent to the WebAssembly module so far. Remember, a single HTTP request may be split over several calls to luw_request_handler().
Version: 0.2.0 Prior to 0.3.0 it returned a size_t
bool luw_http_is_tls(const luw_ctx_t *ctx);This function returns true if the connection to Unit was made over TLS.
void luw_http_hdr_iter(luw_ctx_t *ctx,
bool (*luw_http_hdr_iter_func)(luw_ctx_t *ctx,
const char *name,
const char *value,
void *data),
void *user_data)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
bool luw_http_hdr_iter_func(luw_ctx_t *ctx,
const char *name, const char *value, void *data);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
static bool hdr_iter_func(luw_ctx_t *ctx, const char *name, const char *value,
void *user_data __luw_unused)
{
/* Do something with name & value */
/* Continue iteration or return false to stop */
return true;
}
/* ... *
luw_http_hdr_iter(&ctx, hdr_iter_func, NULL);const char *luw_http_hdr_get_value(const luw_ctx_t *ctx, const char *hdr);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.
size_t luw_get_response_data_size(const luw_ctx_t *ctx);This function returns the size of the response data written to memory.
__attribute__((__format__(printf, 2, 3)))
int luw_mem_writep(luw_ctx_t *ctx, const char *fmt, ...);This function is a cross between vasprintf(3) and mempcpy(3).
It takes a format argument and zero or more arguments that will be substituted into the format string.
It then appends this formatted string to the memory. Note this string will not be nul terminated. Unit does not expect this response data to be nul terminated and we track the size of the response and return that to Unit.
This function returns -1 on error or the length of the string written.
size_t luw_mem_writep_data(luw_ctx_t *ctx, const u8 *src, size_t size);This function just appends size bytes from src to the response.
It returns the new size of the response.
void luw_req_buf_append(luw_ctx_t *ctx, const u8 *src);This function appends the request data contained in src to the previously setup request_buffer with luw_set_req_buf().
This function would be used after an initial request to append the data from subsequent requests to the request_buffer.
Example
int luw_request_handler(u8 *addr)
{
if (!request_buf) {
luw_init_ctx(&ctx, addr, 0);
/*
* 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.
*/
luw_set_req_buf(&ctx, &request_buf,
LUW_SRB_APPEND|LUW_SRB_ALLOC|LUW_SRB_FULL_SIZE);
} else {
luw_req_buf_append(&ctx, addr);
}
/* Do something with the request (ctx) */
return 0;
}void luw_req_buf_copy(luw_ctx_t *ctx, const u8 *src);This function is analogous to luw_req_buf_append but rather than appending the request data contained in src to the previously setup request_buffer with luw_set_req_buf(), it simply overwrites what's currently there.
This function could be used to handle large requests/uploads that you want to save out to disk or some such and can't buffer it all in memory.
Example
int luw_request_handler(u8 *addr)
{
const u8 *buf;
ssize_t bytes_wrote;
if (total_bytes_wrote == 0) {
luw_init_ctx(&ctx, addr, 0);
luw_set_req_buf(&ctx, &request_buf, LUW_SRB_NONE);
fd = open("/var/tmp/large-file.dat", O_CREAT|O_TRUNC|O_WRONLY,
0666);
} else {
luw_req_buf_copy(&ctx, addr);
}
buf = luw_get_http_content(&ctx);
bytes_wrote = write(fd, buf, luw_get_http_content_sent(&ctx));
if (bytes_wrote == -1)
return -1;
total_bytes_wrote += bytes_wrote;
if (total_bytes_wrote == luw_get_http_content_len(&ctx))
luw_http_response_end();
return 0;
}Version: 0.3.0
ssize_t luw_mem_splice_file(const u8 *src, int fd);This function write(2)'s the request data directly from the shared memory (src) to the file represented by the given file-descriptor (fd).
This can be used as an alternative to luw_req_buf_copy and avoids an extra copying of the request data.
Example
int luw_request_handler(u8 *addr) {
ssize_t bytes_wrote;
if (total_bytes_wrote == 0) {
luw_init_ctx(&ctx, addr, 0);
luw_set_req_buf(&ctx, &request_buf, LUW_SRB_NONE);
fd = open("/var/tmp/large-file.dat", O_CREAT|O_TRUNC|O_WRONLY,
0666);
}
bytes_wrote = luw_mem_splice_file(addr, fd);
if (bytes_wrote == -1)
return -1;
total_bytes_wrote += bytes_wrote;
if (total_bytes_wrote == luw_get_http_content_len(&ctx))
luw_http_response_end();
return 0;
}Version: 0.3.0
size_t luw_mem_fill_buf_from_req(luw_ctx_t *ctx, size_t from);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
/* ... */
write_bytes = luw_mem_fill_buf_from_req(ctx, total_response_sent);
total_response_sent += write_bytes;
/* ... */This is taken from the luw-upload-reflector.c 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.
void luw_mem_reset(luw_ctx_t *ctx);This function resets the response buffer size and the number of response headers back to 0.
void luw_http_set_response_status(luw_http_status_t status);This function is used to set the HTTP response status. It takes one of the luw_http_status_t enum values.
It should be called before any calls to luw_http_send_response() or luw_http_send_headers().
If you don't call this function the response status defaults to '200 OK'.
If you wish to error out with a '500 Internal Server Error', you don't need to call this function. Simply returning -1 from the request_handler function will indicate this error.
E.g
Send a '403 Forbidden'
/* ... */
luw_http_set_response_status(LUW_HTTP_FORBIDDEN);
luw_http_send_response(ctx); /* Doesn't require any body */
luw_http_response_end();
/* ... */
return 0;Send a '307 Temporary Re-direct'
/* ... */
luw_http_set_response_status(LUW_HTTP_TEMPORARY_REDIRECT);
luw_http_init_headers(ctx, 1, 0);
luw_http_add_header(ctx, "Location", "https://example.com/");
luw_http_send_headers(ctx);
luw_http_response_end();
/* ... */
return 0;Version: 0.3.0
void luw_http_send_response(const luw_ctx_t *ctx);This function calls into Unit to send the response buffer back.
void luw_http_init_headers(luw_ctx_t *ctx, size_t nr, size_t offset);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
luw_http_init_headers(ctx, 2, 0);void luw_http_add_header(luw_ctx_t *ctx, const char *name, const char *value);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
char clen[32];
/* ... */
snprintf(clen, sizeof(clen), "%lu", luw_get_response_data_size(&ctx));
luw_http_add_header(&ctx, "Content-Type", "text/plain");
luw_http_add_header(&ctx, "Content-Length", clen);void luw_http_send_headers(const luw_ctx_t *ctx);This function calls into Unit and triggers the sending of the response headers.
void luw_http_response_end(void);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.
u32 luw_mem_get_init_size(void);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().
void luw_foreach_http_hdr(luw_ctx_t ctx, luw_http_hdr_iter_t *iter,
const char *name, const char *value)Defined as a macro, this is used to iterate over the HTTP header fields.
It takes a luw_ctx_t * and a luw_http_hdr_iter_t * and returns pointers to the field name and value.
Example
luw_ctx_t ctx;
luw_http_hdr_iter_t *iter;
const char *name;
const char *value;
/* ... */
luw_foreach_http_hdr(ctx, iter, name, value) {
printf("Field name : %s, field value : %s\n", name, value);
/* do something else with name & value */
}The following functions are convenience wrappers for the Rust bindings and should not be used directly.
void *luw_malloc(size_t size);Straight wrapper for malloc(3).
void luw_free(void *ptr);Straight wrapper for free(3).