libunit-wasm: Allow to set the HTTP response status

This adds a new luw_http_set_response_status() function that takes one
of the luw_http_status_t response status codes.

This function should be called before any calls to
luw_http_send_headers() or luw_http_send_response().

This function calls into Unit via a new function import,
nxt_wasm_set_resp_status().

Signed-off-by: Andrew Clayton <a.clayton@nginx.com>

Author: ac000

API-C.md

@@ -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

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,

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);