Allows async hosts by splitting "handle" (#35)

This reduces the complexity of implementing async hosts such as mosn by
splitting the guest export "handle" into "handle_request" and
"handle_response".

* `handle_request`: called by the host on each request and returns `next=1` to
  continue to the next handler on the host.
* `handle_response`: caller by the host, regardless of error, when
  `handle_request` returned `next=1`.

The `next` field is combined with an optional `reqCtx` as the i64 result
of `handler_request`.

When the guest decides to proceed to the next handler, it can return
`ctxNext=1` which is the same as `next=1` without any request context. If it
wants the host to propagate request context, it shifts that into the upper
32-bits of ctxNext like so:

```go
ctxNext = uint64(reqCtx) << 32
if next {
	ctxNext |= 1
}
```

== Impact of the new design ==

This results in the same amount of calls between the guest and the host,
as "next" is no longer needed. This also allows the guest to be called
regardless of host failure, for example in logging interceptors. On the
other hand, splitting the ABI may feel a little more work, as you have
to define two callbacks, not one. That said, in TinyGo, the default
response callback will be invisible to those who only deal with
requests, as it can simply no-op return.

Signed-off-by: Adrian Cole <[email protected]>

Author: codefromthecrypt

api/handler/handler.go

@@ -23,7 +23,7 @@ type Middleware[H any] interface {
 }
 
 // Host supports the host side of the WebAssembly module named HostModule.
-// These callbacks are used by the guest function export FuncHandle.
+// These callbacks are used by the guest function export FuncHandleRequest.
 type Host interface {
 	// EnableFeatures supports the WebAssembly function export EnableFeatures.
 	EnableFeatures(ctx context.Context, features Features) Features
@@ -99,10 +99,6 @@ type Host interface {
 	// FeatureTrailers is not supported.
 	RemoveRequestTrailer(ctx context.Context, name string)
 
-	// Next supports the WebAssembly function export FuncNext, which invokes
-	// the next handler.
-	Next(ctx context.Context)
-
 	// GetStatusCode supports the WebAssembly function export
 	// FuncGetStatusCode.
 	GetStatusCode(ctx context.Context) uint32

api/handler/wasm.go

@@ -1,5 +1,34 @@
 package handler
 
+// CtxNext is the result of FuncHandleRequest. For compatability with
+// WebAssembly Core Specification 1.0, two uint32 values are combined into a
+// single uint64 in the following order:
+//
+//   - ctx: opaque 32-bits the guest defines and the host propagates to
+//     FuncHandleResponse. A typical use is correlation of request state.
+//   - next: one to proceed to the next handler on the host. zero to skip any
+//     next handler. Guests skip when they wrote a response or decided not to.
+//
+// When the guest decides to proceed to the next handler, it can return
+// `ctxNext=1` which is the same as `next=1` without any request context. If it
+// wants the host to propagate request context, it shifts that into the upper
+// 32-bits of ctxNext like so:
+//
+//	ctxNext = uint64(reqCtx) << 32
+//	if next {
+//		ctxNext |= 1
+//	}
+//
+// # Examples
+//
+//   - 0<<32|0  (0): don't proceed to the next handler.
+//   - 0<<32|1  (1): proceed to the next handler without context state.
+//   - 16<<32|1 (68719476737): proceed to the next handler and call
+//     FuncHandleResponse with 16.
+//   - 16<<32|16 (68719476736): the value 16 is ignored because
+//     FuncHandleResponse won't be called.
+type CtxNext uint64
+
 // BufLimit is the possibly zero maximum length of a result value to write in
 // bytes. If the actual value is larger than this, nothing is written to
 // memory.
@@ -60,7 +89,7 @@ const (
 	//
 	// # Notes on FuncWriteBody
 	//
-	// The first call to FuncWriteBody in FuncHandle overwrites any request
+	// The first call to FuncWriteBody in FuncHandleRequest overwrites any request
 	// body.
 	BodyKindRequest BodyKind = 0
 
@@ -74,7 +103,7 @@ const (
 	//
 	// # Notes on FuncWriteBody
 	//
-	// The first call to FuncWriteBody in FuncHandle or after FuncNext
+	// The first call to FuncWriteBody in FuncHandleRequest or after FuncNext
 	// overwrites any response body.
 	BodyKindResponse BodyKind = 1
 )
@@ -116,14 +145,14 @@ const (
 	HostModule = "http_handler"
 
 	// FuncEnableFeatures tries to enable the given features and returns the
-	// Features bitflag supported by the host. This must be called prior to
-	// FuncNext to enable Features needed by the guest.
+	// Features bitflag supported by the host. To have any affect, this must be
+	// called prior to returning from FuncHandleRequest.
 	//
-	// This may be called prior to FuncHandle, for example inside a start
-	// function. Doing so reduces overhead per-call and also allows the guest
-	// to fail early on unsupported.
+	// This may be called prior to FuncHandleRequest, for example inside a
+	// start function. Doing so reduces overhead per-call and also allows the
+	// guest to fail early on unsupported.
 	//
-	// If called during FuncHandle, any new features are only enabled for the
+	// If called during FuncHandleRequest, any new features are enabled for the
 	// scope of the current request. This allows fine-grained access to
 	// expensive features such as FeatureBufferResponse.
 	//
@@ -153,11 +182,34 @@ const (
 	// See https://github.com/http-wasm/http-wasm-abi/blob/main/http_handler/http_handler.wit.md#log
 	FuncLog = "log"
 
-	// FuncHandle is the entrypoint guest export called by the host when
+	// FuncHandleRequest is the entrypoint guest export called by the host when
 	// processing a request.
 	//
-	// See https://github.com/http-wasm/http-wasm-abi/blob/main/http_handler/http_handler.wit.md#handle
-	FuncHandle = "handle"
+	// To proceed to the next handler, the guest returns CtxNext `next=1`. The
+	// simplest result is uint64(1). Guests who need request correlation can
+	// also set the CtxNext "ctx" field. This will be propagated by the host as
+	// the `reqCtx` parameter of FuncHandleResponse.
+	//
+	// To skip any next handler, the guest returns CtxNext `next=0`, or simply
+	// uint64(0). In this case, FuncHandleResponse will not be called.
+	FuncHandleRequest = "handle_request"
+
+	// FuncHandleResponse is called by the host after processing the next
+	// handler when the guest returns CtxNext `next=1` from FuncHandleRequest.
+	//
+	// The `reqCtx` parameter is a possibly zero CtxNext "ctx" field the host
+	// the host propagated from FuncHandleRequest. This allows request
+	// correlation for guests who need it.
+	//
+	// The `isError` parameter is one if there was a host error producing a
+	// response. This allows guests to clean up any resources.
+	//
+	// By default, whether the next handler flushes the response prior to
+	// returning is implementation-specific. If your handler needs to inspect
+	// or manipulate the downstream response, enable FeatureBufferResponse via
+	// FuncEnableFeatures prior to returning from FuncHandleRequest.
+	// TODO: update
+	FuncHandleResponse = "handle_response"
 
 	// FuncGetMethod writes the method to memory if it isn't larger than
 	// BufLimit. The result is its length in bytes. Ex. "GET"
@@ -248,18 +300,6 @@ const (
 	// TODO: document on http-wasm-abi
 	FuncWriteBody = "write_body"
 
-	// FuncNext calls a downstream handler and blocks until it is finished
-	// processing.
-	//
-	// By default, whether the next handler flushes the response prior to
-	// returning is implementation-specific. If your handler needs to inspect
-	// or manipulate the downstream response, enable FeatureBufferResponse via
-	// FuncEnableFeatures prior to calling this function.
-	//
-	// TODO: update existing document on http-wasm-abi
-	// See https://github.com/http-wasm/http-wasm-abi/blob/main/http_handler/http_handler.wit.md#next
-	FuncNext = "next"
-
 	// FuncGetStatusCode returns the status code produced by FuncNext. This
 	// requires FeatureBufferResponse.
 	//

examples/auth.wasm

@@ -12,9 +12,6 @@
     (param $buf i32) (param $buf_limit i32)
     (result (; count << 32| len ;) i64)))
 
-  ;; next dispatches control to the next handler on the host.
-  (import "http_handler" "next" (func $next))
-
   ;; set_header_value overwrites a header of the given $kind and $name with a
   ;; single value.
   (import "http_handler" "set_header_value" (func $set_header_value
@@ -68,13 +65,15 @@
       (global.get $authenticate_value)
       (global.get $authenticate_value_len)))
 
-  ;; handle tries BASIC authentication and dispatches to "next" or returns 401.
-  (func $handle (export "handle")
+  ;; handle_request tries BASIC authentication and dispatches to the next
+  ;; handler or returns 401.
+  (func (export "handle_request") (result (; ctx_next ;) i64)
 
     (local $result i64)
     (local $count i32)
     (local $len i32)
     (local $authorization_eq i32)
+    (local $ctx_next i64)
 
     (local.set $result (call $get_authorization))
 
@@ -86,15 +85,15 @@
       (then ;; multiple headers, invalid
         (call $set_authenticate)
         (call $set_status_code (i32.const 401))
-        (return)))
+        (return (i64.const 0)))) ;; don't call the next handler
 
     ;; len = uint32(result)
     (local.set $len (i32.wrap_i64 (local.get $result)))
 
     (if (i32.ne (global.get $authorization_values_len) (local.get $len))
       (then ;; authorization_values_length != i32($header_value)
         (call $set_status_code (i32.const 401))
-        (return)))
+        (return (i64.const 0)))) ;; don't call the next handler
 
     (local.set $authorization_eq (call $memeq
       (global.get $buf)
@@ -104,8 +103,15 @@
     (if (i32.eqz (local.get $authorization_eq))
       (then ;; authenticate_value != authorization_values
         (call $set_status_code (i32.const 401)))
-      (else ;; authorization passed! call the next handler
-        (call $next))))
+      (else ;; authorization passed!
+        (local.set $ctx_next (i64.const 1)))) ;; call the next handler
+    (return (local.get $ctx_next))
+
+    ;; uint32(ctx_next) == 1 means proceed to the next handler on the host.
+    (return (i64.const 1)))
+
+  ;; handle_response is no-op as this is a request-only handler.
+  (func (export "handle_response") (param $reqCtx i32) (param $is_error i32))
 
   ;; memeq is like memcmp except it returns 0 (ne) or 1 (eq)
   (func $memeq (param $ptr1 i32) (param $ptr2 i32) (param $len i32) (result i32)

examples/auth.wat

@@ -14,11 +14,13 @@
     (param $buf i32) (param $buf_limit i32)
     (result (; len ;) i32)))
 
-  ;; next dispatches control to the next handler on the host.
-  (import "http_handler" "next" (func $next))
+  ;; handle_request just calls next by returning non-zero.
+  (func (export "handle_request") (result (; ctx_next ;) i64)
+    ;; uint32(ctx_next) == 1 means proceed to the next handler on the host.
+    (return (i64.const 1)))
 
-  ;; handle just calls next.
-  (func (export "handle") (call $next))
+  ;; handle_response is no-op as this is a request-only handler.
+  (func (export "handle_response") (param $reqCtx i32) (param $is_error i32))
 
   ;; http_handler guests are required to export "memory", so that imported
   ;; functions like "get_header" can read memory.

examples/config.wasm

@@ -19,7 +19,7 @@
   (data (i32.const 0) "hello world")
   (global $message_len i32 (i32.const 11))
 
-  (func $handle (export "handle")
+  (func (export "handle_request") (result (; ctx_next ;) i64)
     ;; We expect debug logging to be disabled. Panic otherwise!
     (if (i32.eq
           (call $log_enabled (i32.const -1)) ;; log_level_debug
@@ -29,5 +29,11 @@
     (call $log
       (i32.const 0) ;; log_level_info
       (global.get $message)
-      (global.get $message_len)))
+      (global.get $message_len))
+
+    ;; uint32(ctx_next) == 1 means proceed to the next handler on the host.
+    (return (i64.const 1)))
+
+  ;; handle_response is no-op as this is a request-only handler.
+  (func (export "handle_response") (param $reqCtx i32) (param $is_error i32))
 )

examples/config.wat

@@ -30,9 +30,6 @@
     (param $kind i32)
     (param $buf i32) (param $buf_len i32)))
 
-  ;; next dispatches control to the next handler on the host.
-  (import "http_handler" "next" (func $next))
-
   ;; http_handler guests are required to export "memory", so that imported
   ;; functions like $read_body can read memory.
   (memory (export "memory") 1 1 (; 1 page==64KB ;))
@@ -117,8 +114,8 @@
 
     (local.get $len))
 
-  ;; handle implements a simple HTTP router.
-  (func $handle (export "handle")
+  ;; handle_request redacts any request body.
+  (func (export "handle_request") (result (; ctx_next ;) i64)
     (local $len i32)
 
     ;; load the request body from the upstream handler into memory.
@@ -131,7 +128,15 @@
           (i32.const 0) ;; body_kind_request
           (global.get $body) (local.get $len))))
 
-    (call $next) ;; dispatch with $feature_buffer_response enabled.
+    ;; uint32(ctx_next) == 1 means proceed to the next handler on the host.
+    (return (i64.const 1)))
+
+  ;; handle_response redacts any request body.
+  (func (export "handle_response") (param $reqCtx i32) (param $is_error i32)
+    (local $len i32)
+
+    (if (i32.eq (local.get $is_error) (i32.const 1))
+      (then (return))) ;; nothing to redact on error
 
     ;; load the response body from the downstream handler into memory.
     (local.set $len (call $must_read_body (i32.const 1)))

examples/log.wasm

@@ -12,9 +12,6 @@
   (import "http_handler" "set_uri" (func $set_uri
     (param $uri i32) (param $uri_len i32)))
 
-  ;; next dispatches control to the next handler on the host.
-  (import "http_handler" "next" (func $next))
-
   ;; set_header_value overwrites a header of the given $kind and $name with a
   ;; single value.
   (import "http_handler" "set_header_value" (func $set_header_value
@@ -52,8 +49,8 @@
   (data (i32.const 96) "hello world")
   (global $body_len i32 (i32.const 11))
 
-  ;; handle implements a simple HTTP router.
-  (func $handle (export "handle")
+  ;; handle_request implements a simple HTTP router.
+  (func (export "handle_request") (result (; ctx_next ;) i64)
 
     (local $uri_len i32)
 
@@ -66,8 +63,7 @@
     ;; if uri_len > uri_limit { next() }
     (if (i32.gt_u (local.get $uri_len) (global.get $uri_limit))
       (then
-        (call $next)
-        (return))) ;; dispatch if the uri is too long.
+        (return (i64.const 1)))) ;; dispatch if the uri is too long.
 
     ;; Next, strip any paths starting with '/host' and dispatch.
 
@@ -83,8 +79,7 @@
             (call $set_uri ;; uri = uri[path_prefix_len:]
               (i32.add (global.get $uri)     (global.get $path_prefix_len))
               (i32.sub (local.get  $uri_len) (global.get $path_prefix_len)))
-            (call $next)
-            (return))))) ;; dispatch with the stripped path.
+            (return (i64.const 1)))))) ;; dispatch with the stripped path.
 
     ;; Otherwise, serve a static response.
     (call $set_header_value
@@ -96,7 +91,11 @@
     (call $write_body
       (i32.const 1) ;; body_kind_response
       (global.get $body)
-      (global.get $body_len)))
+      (global.get $body_len))
+    (return (i64.const 0))) ;; don't call the next handler
+
+  ;; handle_response is no-op as this is a request-only handler.
+  (func (export "handle_response") (param $reqCtx i32) (param $is_error i32))
 
   ;; memeq is like memcmp except it returns 0 (ne) or 1 (eq)
   (func $memeq (param $ptr1 i32) (param $ptr2 i32) (param $len i32) (result i32)