github.com/machinefi/w3bstream@v1.6.5-rc9.0.20240426031326-b8c7c4876e72/__doc__/w3bstream_wasm_design.md (about)

     1  ## Wasm programming model for w3bStream
     2  
     3  ### Rational
     4  
     5  Several programming models is proposed for w3bStream
     6  
     7  1. Data In Data Out
     8  
     9  ```rust
    10  fn main(data_ptr *i32, data_size i32) -> i32 {
    11      copy(scr, data_ptr, output_size);
    12      return output_size
    13  }
    14  ```
    15  
    16  In this model, wasm acts as a streaming data handler. It is straightforward to pass a input data in and return the filtered data from the func.
    17  
    18  2. Struct Wrapper
    19  
    20  ```rust
    21  fn main(in Request) -> Response {
    22  }
    23  ```
    24  
    25  Examples:
    26  
    27  [wasmedge_wasi_socket](https://github.com/second-state/wasmedge_wasi_socket/blob/main/_examples/http_server/src/main.rs#L15)
    28  
    29  [Rust on Compute@Edge](https://developer.fastly.com/learning/compute/rust/#main-interface)
    30  
    31  This model enforces the adaptation of pre-defined struct on the bost host side and wasm dev side, which doesn't provide any advantages compared with the data-in data-out model in data handling scenario.
    32  
    33  3. Main-entry style (preferred one)
    34  
    35  ```rust
    36  fn main(resource_id i32) -> i32 {
    37      return status_code;
    38  }
    39  ```
    40  
    41  In this model, the data from IoT devices is not directly passed to the wasm once it is initiated. But it has to be requested data with the resource_id from the host. This model is preferred because it transfer to the [memory ownership](https://github.com/proxy-wasm/spec/tree/master/abi-versions#memory-ownership) to wasm code, who can manage the memory by itself. Besides, a bundle of ABIs is used to build the bridge between host and wasm.
    42  
    43  ABI examples:
    44  
    45  [proxy-wasm-go-host/imports.go](https://github.com/mosn/proxy-wasm-go-host/blob/main/proxywasm/v2/imports.go)
    46  
    47  [proxy-wasm-go-host/exports.go](https://github.com/mosn/proxy-wasm-go-host/blob/main/proxywasm/v2/exports.go)
    48  
    49  4. Injection
    50  
    51  ```rust
    52  fn map() -> i32 {
    53      return status_code; 
    54  }
    55  
    56  fn reduce() -> i32 {
    57      return status_code;
    58  }
    59  ```
    60  
    61  In this model, the developer is supposed to inject the wasm into the interface the host provides. When certain func of the interface is invoked on the host side, the corresponding wasm is run. The development of this model is easier than other models, but, unlike HTTP handling, the data flow for streaming isn't fixed. So this model isn't suitable for our application.
    62  
    63  Examples:
    64  
    65  [proxy-wasm](https://github.com/proxy-wasm/spec/tree/master/abi-versions/vNEXT)
    66  
    67  ### Implements
    68  
    69  #### ABIs
    70  
    71  - Func exported by wasm
    72  
    73  ```rust
    74  fn alloc(size: usize) -> *mut c_void {
    75      return ptr;
    76  }
    77  
    78  fn start(resource_id i32) -> i32 {
    79      return status_code;
    80  }
    81  ```
    82  
    83  - Func imported to wasm
    84  
    85  ```rust
    86  fn ws_get_data(resource_id i32, return_ptr i32, return_size i32) -> i32 {
    87      copy(data_ptr, return_ptr, return_size)
    88      return Result_OK
    89  }
    90  
    91  fn ws_set_data(resource_id i32, ptr i32, size i32) -> i32 {
    92      return Result_OK
    93  }
    94  
    95  fn ws_get_dB(key_ptr i32, key_size i32, return_value_ptr i32, return_value_size i32) -> i32 {
    96      return Result_OK
    97  }
    98  
    99  fn ws_set_dB(key_ptr i32, key_size i32, value_ptr i32, value_size i32) -> i32 {
   100      return Result_OK
   101  }
   102  
   103  fn ws_log(logLevel i32, ptr i32, size i32) -> i32 {
   104      return Result_OK
   105  }
   106  
   107  // an example of encoded data
   108  // `{
   109  //        "to":    "0xb576c141e5659137ddda4223d209d4744b2106be",
   110  //        "value": "0",
   111  //        "data":  "..."  // hex encoding 
   112  // }`
   113  fn ws_send_tx(encoded_data i32, encoded_size i32, return_value_ptr i32, return_value_size i32) -> i32 {}
   114  
   115  // an example of encoded data
   116  // `{
   117  //        "to":    "0xb576c141e5659137ddda4223d209d4744b2106be",
   118  //        "data":  "..."  // hex encoding 
   119  // }`
   120  fn ws_call_contract(encoded_ptr i32, encoded_size i32) -> i32 {}
   121  ```
   122