diff options
| -rw-r--r-- | API-C.md | 110 | ||||
| -rw-r--r-- | src/c/include/unit/unit-wasm.h | 47 | ||||
| -rw-r--r-- | src/c/libunit-wasm.c | 5 |
3 files changed, 160 insertions, 2 deletions
@@ -12,6 +12,8 @@ C Library for creating WebAssembly modules for use with NGINX Unit. * [Misc](#misc) 3. [Types](#types) 4. [Enums](#enums) + * [luw_srb_flags_t](#luw_srb_flags_t) + * [luw_http_status_t](#luw_http_status_t) 5. [Structs](#structs) 6. [Function Handlers](#function-handlers) * [Optional](#optional) @@ -48,6 +50,7 @@ C Library for creating WebAssembly modules for use with NGINX Unit. * [luw_req_buf_append](#luw_req_buf_append) * [luw_mem_fill_buf_from_req](#luw_mem_fill_buf_from_req) * [luw_mem_reset](#luw_mem_reset) + * [luw_http_set_response_status](#luw_http_set_response_status) * [luw_http_send_response](#luw_http_send_response) * [luw_http_init_headers](#luw_http_init_headers) * [luw_http_add_header](#luw_http_add_header) @@ -112,6 +115,8 @@ typedef int8_t s8; ## Enums +### luw_srb_flags_t + ```C typedef enum { LUW_SRB_NONE = 0x00, @@ -124,6 +129,54 @@ typedef enum { } luw_srb_flags_t; ``` +### luw_http_status_t + +```C +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; +``` + ## Structs ```C @@ -264,8 +317,14 @@ returned by luw_malloc_handler(). This memory will contain a *struct luw_req*. -It returns an int, this is currently ignored but will likely be used to -indicate a HTTP status code. +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_resp_status](#luw_http_set_resp_status). #### luw_malloc_handler @@ -850,6 +909,53 @@ void luw_mem_reset(luw_ctx_t *ctx); This function resets the response buffer size and the number of response headers back to 0. +### luw_http_set_response_status + +```C +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](#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' + +```C +/* ... */ +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' + +```C +/* ... */ +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_ + ### luw_http_send_response ```C diff --git a/src/c/include/unit/unit-wasm.h b/src/c/include/unit/unit-wasm.h index 272d762..c870e30 100644 --- a/src/c/include/unit/unit-wasm.h +++ b/src/c/include/unit/unit-wasm.h @@ -40,6 +40,50 @@ typedef int16_t s16; typedef uint8_t u8; typedef int8_t s8; +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; @@ -151,6 +195,8 @@ __attribute__((import_module("env"), import_name("nxt_wasm_send_headers"))) void nxt_wasm_send_headers(u32 offset); __attribute__((import_module("env"), import_name("nxt_wasm_send_response"))) void nxt_wasm_send_response(u32 offset); +__attribute__((import_module("env"), import_name("nxt_wasm_set_resp_status"))) +void nxt_wasm_set_resp_status(u32 status); extern void luw_module_init_handler(void); extern void luw_module_end_handler(void); @@ -192,6 +238,7 @@ extern size_t luw_mem_writep_data(luw_ctx_t *ctx, const u8 *src, size_t size); extern void luw_req_buf_append(luw_ctx_t *ctx, const u8 *src); extern size_t luw_mem_fill_buf_from_req(luw_ctx_t *ctx, size_t from); extern void luw_mem_reset(luw_ctx_t *ctx); +extern void luw_http_set_response_status(luw_http_status_t status); extern void luw_http_send_response(const luw_ctx_t *ctx); extern void luw_http_init_headers(luw_ctx_t *ctx, size_t nr, size_t offset); extern void luw_http_add_header(luw_ctx_t *ctx, const char *name, diff --git a/src/c/libunit-wasm.c b/src/c/libunit-wasm.c index 69fe4c0..165dcd7 100644 --- a/src/c/libunit-wasm.c +++ b/src/c/libunit-wasm.c @@ -336,6 +336,11 @@ void luw_mem_reset(luw_ctx_t *ctx) ctx->resp_hdr_idx = -1; } +void luw_http_set_response_status(luw_http_status_t status) +{ + nxt_wasm_set_resp_status(status); +} + void luw_http_send_response(const luw_ctx_t *ctx) { nxt_wasm_send_response(ctx->resp_offset); |