From 0c0e758c8de58055c5286c8911ccaf30371ed9d6 Mon Sep 17 00:00:00 2001 From: Piotr Sikora Date: Thu, 25 Sep 2025 12:19:46 -0400 Subject: [PATCH] Add explicit `context_id` parameter to all hostcalls. While there, add and consistently use `UNKNOWN_RESOURCE_ID` error for when resources are accessed using an unknown ID. Signed-off-by: Piotr Sikora --- abi-versions/vNEXT/HOST_FEATURES.md | 8 ++ abi-versions/vNEXT/README.md | 133 ++++++++++++++++++++-------- 2 files changed, 104 insertions(+), 37 deletions(-) create mode 100644 abi-versions/vNEXT/HOST_FEATURES.md diff --git a/abi-versions/vNEXT/HOST_FEATURES.md b/abi-versions/vNEXT/HOST_FEATURES.md new file mode 100644 index 0000000..bf88c73 --- /dev/null +++ b/abi-versions/vNEXT/HOST_FEATURES.md @@ -0,0 +1,8 @@ +# Host features + +| Identifier | Name | Values | Deprecated | +|:----------:|:--------------------------------|:---------------------------------------------------------------------------------------------------|:----------:| +| 0x1001 | `HOST_TRACKS_ACTIVE_CONTEXT_ID` | When `1`, `context_id` can be set to `0`, which then indicates host-tracked active context ID. | Yes | + + +Identifiers below 0x2000 are reserved for standardized features and options. Random numbers above that range should be used for private extensions. diff --git a/abi-versions/vNEXT/README.md b/abi-versions/vNEXT/README.md index 272062e..319102c 100644 --- a/abi-versions/vNEXT/README.md +++ b/abi-versions/vNEXT/README.md @@ -213,17 +213,18 @@ or after a call to [`proxy_done`]. #### `proxy_done` * params: - - none + - `i32 (uint32_t) context_id` * returns: - `i32 (`[`proxy_status_t`]`) status` -Indicates to the host that the plugin is done processing active -context. +Indicates to the host that the plugin is done processing context +(`context_id`). This should be used after returning `false` in [`proxy_on_done`]. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `context_id`. - `NOT_FOUND` when active context was not pending finalization. @@ -234,6 +235,9 @@ Returned `status` value is: * returns: - `i32 (`[`proxy_status_t`]`) status` +> **Warning** +> This function has been deprecated in favor of explicit context IDs. + Changes the effective context to `context_id`. This can be used to change active context, e.g. during @@ -242,7 +246,7 @@ and/or [`proxy_on_queue_ready`] callbacks. Returned `status` value is: - `OK` on success. -- `BAD_ARGUMENT` for unknown `context_id`. +- `UNKNOWN_RESOURCE_ID` for unknown `context_id`. ## Configuration @@ -408,22 +412,28 @@ Returned `errno` value is: ## Timers +> **Note** +> The default timer can be accessed using `timer_id=0`. + + ### Functions exposed by the host #### `proxy_set_tick_period_milliseconds` * params: + - `i32 (uint32_t) timer_id` - `i32 (uint32_t) tick_period` * returns: - `i32 (`[`proxy_status_t`]`) status` -Sets a low-resolution timer period (`tick_period`). +Sets a tick period (`tick_period`) in a low-resolution timer `timer_id`. When set, the host will call [`proxy_on_tick`] every `tick_period` milliseconds. Setting `tick_period` to `0` disables the timer. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `timer_id`. ### Callbacks exposed by the Wasm module @@ -432,10 +442,11 @@ Returned `status` value is: * params: - `i32 (uint32_t) plugin_context_id` + - `i32 (uint32_t) timer_id` * returns: - none -Called on a timer every tick period. +Called on a timer `timer_id` every tick period. The tick period can be configured using [`proxy_set_tick_period_milliseconds`]. @@ -535,6 +546,7 @@ in this section is restricted to specific callbacks: #### `proxy_set_buffer_bytes` * params: + - `i32 (uint32_t) context_id` - `i32 (`[`proxy_buffer_type_t`]`) buffer_id` - `i32 (size_t) start` - `i32 (size_t) size` @@ -543,8 +555,8 @@ in this section is restricted to specific callbacks: * returns: - `i32 (`[`proxy_status_t`]`) status` -Sets content of the buffer `buffer_id` to the provided value -(`value_data`, `value_size`) replacing `size` bytes starting +Sets content of the buffer `buffer_id` of context `context_id` to the provided +value (`value_data`, `value_size`) replacing `size` bytes starting at `start` in the existing buffer. The combination of `start` and `size` parameters can be used to perform @@ -554,6 +566,7 @@ and replace (`start` smaller than the existing buffer size) operations. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `context_id`. - `BAD_ARGUMENT` for unknown `buffer_id`. - `NOT_FOUND` when the requested `buffer_id` isn't available. - `INVALID_MEMORY_ACCESS` when `value_data` and/or `value_size` @@ -563,6 +576,7 @@ Returned `status` value is: #### `proxy_get_buffer_bytes` * params: + - `i32 (uint32_t) context_id` - `i32 (`[`proxy_buffer_type_t`]`) buffer_id` - `i32 (size_t) start` - `i32 (size_t) max_size` @@ -572,10 +586,11 @@ Returned `status` value is: - `i32 (`[`proxy_status_t`]`) status` Retrieves up to `max_size` bytes starting at `start` from the buffer -`buffer_id`. +`buffer_id` of context `context_id`. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `context_id`. - `BAD_ARGUMENT` for unknown `buffer_id`, or in case of buffer overflow due to invalid `start` and/or `max_size` values. - `NOT_FOUND` when the requested `buffer_id` isn't available. @@ -586,16 +601,19 @@ Returned `status` value is: #### `proxy_get_buffer_status` * params: + - `i32 (uint32_t) context_id` - `i32 (`[`proxy_buffer_type_t`]`) buffer_id` - `i32 (size_t *) return_buffer_size` - `i32 (uint32_t *) return_unused` * returns: - `i32 (`[`proxy_status_t`]`) status` -Retrieves size (`return_buffer_size`) of the buffer `buffer_id`. +Retrieves size (`return_buffer_size`) of the buffer `buffer_id` +of context `context_id`. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `context_id`. - `BAD_ARGUMENT` for unknown `buffer_id`. - `NOT_FOUND` when the requested `buffer_id` isn't available. - `INVALID_MEMORY_ACCESS` when `return_buffer_size` and/or @@ -638,16 +656,18 @@ functions in this section is restricted to specific callbacks: #### `proxy_get_header_map_size` * params: + - `i32 (uint32_t) stream_context_id` - `i32 (`[`proxy_map_type_t`]`) map_id` - `i32 (size_t *) return_serialized_pairs_size` * returns: - `i32 (`[`proxy_status_t`]`) status` Retrieves size (`return_serialized_pairs_size`) of all key-value pairs -from the map `map_id`. +from the map `map_id` of HTTP request `stream_context_id`. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `stream_context_id`. - `BAD_ARGUMENT` for unknown `map_id`. - `INVALID_MEMORY_ACCESS` when `return_serialized_pairs_size` points to invalid memory address. @@ -656,19 +676,22 @@ Returned `status` value is: #### `proxy_get_header_map_pairs` * params: + - `i32 (uint32_t) stream_context_id` - `i32 (`[`proxy_map_type_t`]`) map_id` - `i32 (uint8_t **) return_serialized_pairs_data` - `i32 (size_t *) return_serialized_pairs_size` * returns: - `i32 (`[`proxy_status_t`]`) status` -Retrieves all key-value pairs from the map `map_id`. +Retrieves all key-value pairs from the map `map_id` of HTTP request +`stream_context_id`. Returned map (`return_serialized_pairs_data`, `return_serialized_pairs_size`) is [serialized]. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `stream_context_id`. - `BAD_ARGUMENT` for unknown `map_id`. - `INVALID_MEMORY_ACCESS` when `return_serialized_pairs_data` and/or `return_serialized_pairs_size` point to invalid memory address. @@ -677,17 +700,20 @@ Returned `status` value is: #### `proxy_set_header_map_pairs` * params: + - `i32 (uint32_t) stream_context_id` - `i32 (`[`proxy_map_type_t`]`) map_id` - `i32 (const uint8_t *) serialized_pairs_data` - `i32 (size_t) serialized_pairs_size` * returns: - `i32 (`[`proxy_status_t`]`) status` -Sets all key-value pairs in the map `map_id` to the provided -[serialized] map (`serialized_pairs_data`, `serialized_pairs_size`). +Sets all key-value pairs in the map `map_id` of HTTP request `stream_context_id` +to the provided [serialized] map (`serialized_pairs_data`, +`serialized_pairs_size`). Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `stream_context_id`. - `BAD_ARGUMENT` for unknown `map_id`. - `INVALID_MEMORY_ACCESS` when `serialized_pairs_data` and/or `serialized_pairs_size` point to invalid memory address. @@ -696,6 +722,7 @@ Returned `status` value is: #### `proxy_get_header_map_value` * params: + - `i32 (uint32_t) stream_context_id` - `i32 (`[`proxy_map_type_t`]`) map_id` - `i32 (const char *) key_data` - `i32 (size_t) key_size` @@ -705,10 +732,12 @@ Returned `status` value is: - `i32 (`[`proxy_status_t`]`) status` Retrieves value (`return_value_data`, `return_value_size`) of the key -(`key_data`, `key_value`) from the map `map_id`. +(`key_data`, `key_value`) from the map `map_id` of HTTP request +`stream_context_id`. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `stream_context_id`. - `BAD_ARGUMENT` for unknown `map_id`. - `NOT_FOUND` when the requested key was not found. - `INVALID_MEMORY_ACCESS` when `key_data`, `key_size`, @@ -719,6 +748,7 @@ Returned `status` value is: #### `proxy_add_header_map_value` * params: + - `i32 (uint32_t) stream_context_id` - `i32 (`[`proxy_map_type_t`]`) map_id` - `i32 (const char *) key_data` - `i32 (size_t) key_size` @@ -727,11 +757,12 @@ Returned `status` value is: * returns: - `i32 (`[`proxy_status_t`]`) status` -Adds key (`key_data`, `key_size`) with value (`value_data`, -`value_size`) to the map `map_id`. +Adds key (`key_data`, `key_size`) with value (`value_data`, `value_size`) +to the map `map_id` of HTTP request `stream_context_id`. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `stream_context_id`. - `BAD_ARGUMENT` for unknown `map_id`. - `INVALID_MEMORY_ACCESS` when `key_data`, `key_size`, `value_data` and/or `value_size` point to invalid memory address. @@ -740,6 +771,7 @@ Returned `status` value is: #### `proxy_replace_header_map_value` * params: + - `i32 (uint32_t) stream_context_id` - `i32 (`[`proxy_map_type_t`]`) map_id` - `i32 (const char *) key_data` - `i32 (size_t) key_size` @@ -749,10 +781,12 @@ Returned `status` value is: - `i32 (`[`proxy_status_t`]`) status` Adds or replaces key's (`key_data`, `key_value`) value with the provided -value (`value_data`, `value_size`) in the map `map_id`. +value (`value_data`, `value_size`) in the map `map_id` of HTTP request +`stream_context_id`. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `stream_context_id`. - `BAD_ARGUMENT` for unknown `map_id`. - `INVALID_MEMORY_ACCESS` when `key_data`, `key_size`, `value_data` and/or `value_size` point to invalid memory address. @@ -761,16 +795,19 @@ Returned `status` value is: #### `proxy_remove_header_map_value` * params: + - `i32 (uint32_t) stream_context_id` - `i32 (`[`proxy_map_type_t`]`) map_id` - `i32 (const char *) key_data` - `i32 (size_t) key_size` * returns: - `i32 (`[`proxy_status_t`]`) status` -Removes the key (`key_data`, `key_value`) from the map `map_id`. +Removes the key (`key_data`, `key_value`) from the map `map_id` of HTTP request +`stream_context_id`. Returned `status` value is: - `OK` on success (including the case when the requested key didn't exist). +- `UNKNOWN_RESOURCE_ID` for unknown `stream_context_id`. - `BAD_ARGUMENT` for unknown `map_id`. - `INVALID_MEMORY_ACCESS` when `key_data` and/or `key_size` point to invalid memory address. @@ -783,14 +820,16 @@ Returned `status` value is: #### `proxy_continue_stream` * params: + - `i32 (uint32_t) stream_context_id` - `i32 (`[`proxy_stream_type_t`]`) stream_type` * returns: - `i32 (`[`proxy_status_t`]`) status` -Resumes processing of paused `stream_type`. +Resumes processing of paused `stream_type` in stream `stream_context_id`. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `stream_context_id`. - `BAD_ARGUMENT` for unknown `stream_type`. - `UNIMPLEMENTED` when continuation of the requested `stream_type` is not supported. @@ -799,20 +838,23 @@ Returned `status` value is: #### `proxy_close_stream` * params: + - `i32 (uint32_t) stream_context_id` - `i32 (`[`proxy_stream_type_t`]`) stream_type` * returns: - `i32 (`[`proxy_status_t`]`) status` -Closes or resets `stream_type`. +Closes or resets `stream_type` in stream `stream_context_id`. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `stream_context_id`. - `BAD_ARGUMENT` for unknown `stream_type`. #### `proxy_get_status` * params: + - `i32 (uint32_t) call_or_stream_id` - `i32 (uint32_t *) return_status_code` - `i32 (const char **) return_status_message_data` - `i32 (size_t *) return_status_message_size` @@ -820,12 +862,14 @@ Returned `status` value is: - `i32 (`[`proxy_status_t`]`) status` Retrieves status code (`return_status_code`) and status message -(`return_status_message_data`, `return_status_message_size`) of -the HTTP call when called from [`proxy_on_http_call_response`] -or gRPC stream or call when called from [`proxy_on_grpc_close`]. +(`return_status_message_data`, `return_status_message_size`) of the HTTP call +`call_or_stream_id` when called from [`proxy_on_http_call_response`] +or gRPC stream or call `call_or_stream_id` when called from +[`proxy_on_grpc_close`]. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `call_or_stream_id`. - `INVALID_MEMORY_ACCESS` when `return_status_code`, `return_status_message_data` and/or `return_status_message_size` point to invalid memory address. @@ -1143,6 +1187,7 @@ Plugin must return one of the following values: #### `proxy_send_local_response` * params: + - `i32 (uint32_t) stream_context_id` - `i32 (uint32_t) status_code` - `i32 (const char *) status_code_details_data` - `i32 (size_t) status_code_details_size` @@ -1156,12 +1201,13 @@ Plugin must return one of the following values: Sends HTTP response with body (`body_data`, `body_size`) and [serialized] headers (`serialized_headers_data`, -`serialized_headers_size`). +`serialized_headers_size`) for HTTP request `stream_context_id`. This can be used as long as HTTP response headers were not sent downstream. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `stream_context_id`. - `INVALID_MEMORY_ACCESS` when `status_code_details_data`, `status_code_details_size`, `body_data`, `body_size`, `serialized_headers_data` and/or `serialized_headers_size` @@ -1346,7 +1392,7 @@ Sends gRPC message (`message_data`, `message_size`) on the gRPC stream Returned `status` value is: - `OK` on success. - `BAD_ARGUMENT` for invalid `stream_id`. -- `NOT_FOUND` for unknown `stream_id`. +- `UNKNOWN_RESOURCE_ID` for unknown `stream_id`. - `INVALID_MEMORY_ACCESS` when `message_data` and/or `message_size` point to invalid memory address. @@ -1364,7 +1410,7 @@ Cancels `call_or_stream_id` previously started using Returned `status` value is: - `OK` on success. - `BAD_ARGUMENT` for invalid `call_or_stream_id`. -- `NOT_FOUND` for unknown `call_or_stream_id`. +- `UNKNOWN_RESOURCE_ID` for unknown `call_or_stream_id`. #### `proxy_grpc_close` @@ -1380,7 +1426,7 @@ Closes `call_or_stream_id` previously started using Returned `status` value is: - `OK` on success. - `BAD_ARGUMENT` for invalid `call_or_stream_id`. -- `NOT_FOUND` for unknown `call_or_stream_id`. +- `UNKNOWN_RESOURCE_ID` for unknown `call_or_stream_id`. ### Callbacks exposed by the Wasm module @@ -1454,11 +1500,16 @@ gRPC status message can be retrieved using [`proxy_get_status`]. ## Shared Key-Value Store +> **Note** +> The default pre-opened key-value store can be accessed using `kvstore_id=0`. + + ### Functions exposed by the host #### `proxy_set_shared_data` * params: + - `i32 (uint32_t) kvstore_id` - `i32 (const char *) key_data` - `i32 (size_t) key_size` - `i32 (const uint8_t *) value_data` @@ -1468,7 +1519,7 @@ gRPC status message can be retrieved using [`proxy_get_status`]. - `i32 (`[`proxy_status_t`]`) status` Sets shared data identified by the key (`key_data`, `key_value`) -to the value (`value_data`, `value_size`). +to the value (`value_data`, `value_size`) in key-value store `kvstore_id`. If the compare-and-swap value (`cas`) is set to a non-zero value, then it must match the host's compare-and-swap value in order for @@ -1476,6 +1527,7 @@ the update to succeed. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `kvstore_id`. - `CAS_MISMATCH` when `cas` doesn't match host's compare-and-swap value. - `INVALID_MEMORY_ACCESS` when `key_data`, `key_size`, `value_data`, @@ -1485,6 +1537,7 @@ Returned `status` value is: #### `proxy_get_shared_data` * params: + - `i32 (uint32_t) kvstore_id` - `i32 (const char *) key_data` - `i32 (size_t) key_size` - `i32 (uint8_t **) return_value_data` @@ -1494,13 +1547,14 @@ Returned `status` value is: - `i32 (`[`proxy_status_t`]`) status` Returns shared value (`return_value`) identified by the key (`key_data`, -`key_value`). +`key_value`) in key-value store `kvstore_id`. The compare-and-swap value (`return_cas`) can be used for atomically updating this value using [`proxy_set_shared_data`]. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `kvstore_id`. - `NOT_FOUND` when the requested key was not found. - `INVALID_MEMORY_ACCESS` when `key_data`, `key_size`, `return_value_data`, `return_value_size` and/or `return_cas` @@ -1574,7 +1628,7 @@ Adds item (`value_data`, `value_size`) to the end of the queue Returned `status` value is: - `OK` on success. -- `NOT_FOUND` when the requested `queue_id` was not found. +- `UNKNOWN_RESOURCE_ID` for unknown `queue_id`. - `INVALID_MEMORY_ACCESS` when `value_data` and/or `value_size` point to invalid memory address. @@ -1593,7 +1647,7 @@ the front of the queue `queue_id`. Returned `status` value is: - `OK` on success. -- `NOT_FOUND` when the requested `queue_id` was not found. +- `UNKNOWN_RESOURCE_ID` for unknown `queue_id`. - `EMPTY` when there is nothing to dequeue from the requested queue. - `INVALID_MEMORY_ACCESS` when `return_value_data` and/or `return_value_size` point to invalid memory address. @@ -1651,7 +1705,7 @@ Sets metric `metric_id` to the `value`. Returned `status` value is: - `OK` on success. -- `NOT_FOUND` when the requested `metric_id` was not found. +- `UNKNOWN_RESOURCE_ID` for unknown `metric_id`. #### `proxy_increment_metric` @@ -1666,7 +1720,7 @@ Changes metric `metric_id` by the `delta`. Returned `status` value is: - `OK` on success. -- `NOT_FOUND` when the requested `metric_id` was not found. +- `UNKNOWN_RESOURCE_ID` for unknown `metric_id`. - `BAD_ARGUMENT` when the requested `delta` cannot be applied to `metric_id` (e.g. trying to decrement counter). @@ -1683,7 +1737,7 @@ Retrieves `return_value` of the metric `metric_id`. Returned `status` value is: - `OK` on success. -- `NOT_FOUND` when the requested `metric_id` was not found. +- `UNKNOWN_RESOURCE_ID` for unknown `metric_id`. - `INVALID_MEMORY_ACCESS` when `return_value` points to invalid memory address. @@ -1700,6 +1754,7 @@ Returned `status` value is: #### `proxy_get_property` * params: + - `i32 (uint32_t) context_id` - `i32 (const uint8_t *) path_data` - `i32 (size_t) path_size` - `i32 (uint8_t **) return_value_data` @@ -1708,10 +1763,11 @@ Returned `status` value is: - `i32 (`[`proxy_status_t`]`) status` Retrieves value (`return_value_data`, `return_value_size`) -of the property (`path_data`, `path_size`). +of the property (`path_data`, `path_size`) of context `context_id`. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `context_id`. - `NOT_FOUND` when there was no property found at the requested `path`. - `SERIALIZATION_FAILURE` when host failed to serialize property. - `INVALID_MEMORY_ACCESS` when `path_data`, `path_size`, @@ -1722,6 +1778,7 @@ Returned `status` value is: #### `proxy_set_property` * params: + - `i32 (uint32_t) context_id` - `i32 (const uint8_t *) path_data` - `i32 (size_t) path_size` - `i32 (const uint8_t *) value_data` @@ -1730,10 +1787,11 @@ Returned `status` value is: - `i32 (`[`proxy_status_t`]`) status` Sets value of the property (`path_data`, `path_size`) to the provided -value (`value_data`, `value_size`). +value (`value_data`, `value_size`) in context `context_id`. Returned `status` value is: - `OK` on success. +- `UNKNOWN_RESOURCE_ID` for unknown `context_id`. - `NOT_FOUND` when there was no property found at the requested `path`. - `INVALID_MEMORY_ACCESS` when `path_data`, `path_size`, `value_data` and/or `value_size` point to invalid memory address. @@ -2005,6 +2063,7 @@ changes to unrelated connections/requests. - `CAS_MISMATCH` = `8` - `INTERNAL_FAILURE` = `10` - `UNIMPLEMENTED` = `12` +- `UNKNOWN_RESOURCE_ID` = `13` #### `proxy_action_t`