diff --git a/docs/content/wasm.md b/docs/content/wasm.md index 43b3ac31ad..0b890f7f04 100644 --- a/docs/content/wasm.md +++ b/docs/content/wasm.md @@ -142,27 +142,27 @@ ABI | Notes The primary exported functions for interacting with policy modules are listed below. In the ABI column, you can find the ABI version with which the export was introduced. -| Function Signature | Description | ABI +| Function | Description | ABI | --- | --- | --- | -| `int32 eval(ctx_addr)` | Evaluates the loaded policy with the provided evaluation context. The return value is reserved for future use. | 1.0 | -| `value_addr builtins(void)` | Returns the address of a mapping of built-in function names to numeric identifiers that are required by the policy. | 1.0 | -| `value_addr entrypoints(void)` | Returns the address of a mapping of entrypoints to numeric identifiers that can be selected when evaluating the policy. | 1.0 | -| `ctx_addr opa_eval_ctx_new(void)` | Returns the address of a newly allocated evaluation context. | 1.0 | -| `void opa_eval_ctx_set_input(ctx_addr, value_addr)` | Set the input value to use during evaluation. This must be called before each `eval()` call. If the input value is not set before evaluation, references to the `input` document result produce no results (i.e., they are undefined.) | 1.0 | -| `void opa_eval_ctx_set_data(ctx_addr, value_addr)` | Set the data value to use during evalutaion. This should be called before each `eval()` call. If the data value is not set before evalutaion, references to base `data` documents produce no results (i.e., they are undefined.) | 1.0 | -| `void opa_eval_ctx_set_entrypoint(ctx_addr, entrypoint_id)` | Set the entrypoint to evaluate. By default, entrypoint with id `0` is evaluated. | 1.0 | -| `value_addr opa_eval_ctx_get_result(ctx_addr)` | Get the result set produced by the evaluation process. | 1.0 | -| `addr opa_malloc(int32 size)` | Allocates size bytes in the shared memory and returns the starting address. | 1.0 | -| `void opa_free(addr)` | Free a pointer. Calls `opa_abort` on error. | 1.0 | -| `value_addr opa_json_parse(str_addr, size)` | Parses the JSON serialized value starting at str_addr of size bytes and returns the address of the parsed value. The parsed value may refer to a null, boolean, number, string, array, or object value. | 1.0 | -| `value_addr opa_value_parse(str_addr, size)` | The same as `opa_json_parse` except Rego set literals are supported. | 1.0 | -| `str_addr opa_json_dump(value_addr)` | Dumps the value referred to by `value_addr` to a null-terminated JSON serialized string and returns the address of the start of the string. Rego sets are serialized as JSON arrays. Non-string Rego object keys are serialized as strings. | 1.0 | -| `str_addr opa_value_dump(value_addr)` | The same as `opa_json_dump` except Rego sets are serialized using the literal syntax and non-string Rego object keys are not serialized as strings. | 1.0 | -| `void opa_heap_ptr_set(addr)` | Set the heap pointer for the next evaluation. | 1.0 | -| `addr opa_heap_ptr_get(void)` | Get the current heap pointer. | 1.0 | -| `int32 opa_value_add_path(base_value_addr, path_value_addr, value_addr)` | Add the value at the `value_addr` into the object referenced by `base_value_addr` at the given path. The `path_value_addr` must point to an array value with string keys (eg: `["a", "b", "c"]`). Existing values will be updated. On success the value at `value_addr` is no longer owned by the caller, it will be freed with the base value. The path must be freed by the caller after use (see `opa_free`). If an error occurs the base value will remain unchanged. Example: base object `{"a": {"b": 123}}`, path `["a", "x", "y"]`, and value `{"foo": "bar"}` will yield `{"a": {"b": 123, "x": {"y": {"foo": "bar"}}}}`. Returns an error code (see below). | 1.0 | -| `int32 opa_value_remove_path(base_value_addr, path_value_addr)` | Remove the value from the object referenced by `base_value_addr` at the given path. Values removed will be freed. The path must be freed by the caller after use (see `opa_free`). The `path_value_addr` must point to an array value with string keys (eg: `["a", "b", "c"]`). Returns an error code (see below). | 1.0 | -| `str_addr opa_eval(_ addr, entrypoint_id int32, data value_addr, input str_addr, input_len int32, heap_ptr addr, format int32)` | One-off policy evaluation method. Its arguments are everything needed to evaluate: entrypoint, address of data in memory, address and length of input JSON string in memory, heap address to use, and the output format (`0` is JSON, `1` is "value", i.e. serialized Rego values). The first argument is reserved for future use and must be `0`. Returns the address to the serialised result value. | 1.2 | +| `eval` |
`int32 eval(ctx_addr)`
Evaluates the loaded policy with the provided evaluation context. The return value is reserved for future use.
| 1.0 | +| `builtins` |
`value_addr builtins(void)`
Returns the address of a mapping of built-in function names to numeric identifiers that are required by the policy.
| 1.0 | +| `entrypoints` |
`value_addr entrypoints(void)`
Returns the address of a mapping of entrypoints to numeric identifiers that can be selected when evaluating the policy.
| 1.0 | +| `opa_eval_ctx_new` |
`ctx_addr opa_eval_ctx_new(void)`
Returns the address of a newly allocated evaluation context.
| 1.0 | +| `opa_eval_ctx_set_input` |
`void opa_eval_ctx_set_input(ctx_addr, value_addr)`
Set the input value to use during evaluation. This must be called before each `eval()` call. If the input value is not set before evaluation, references to the `input` document result produce no results (i.e., they are undefined.)
| 1.0 | +| `opa_eval_ctx_set_data` |
`void opa_eval_ctx_set_data(ctx_addr, value_addr)`
Set the data value to use during evalutaion. This should be called before each `eval()` call. If the data value is not set before evalutaion, references to base `data` documents produce no results (i.e., they are undefined.)
| 1.0 | +| `opa_eval_ctx_set_entrypoint` |
`void opa_eval_ctx_set_entrypoint(ctx_addr, entrypoint_id)`
Set the entrypoint to evaluate. By default, entrypoint with id `0` is evaluated.
| 1.0 | +| `opa_eval_ctx_get_result` |
`value_addr opa_eval_ctx_get_result(ctx_addr)`
Get the result set produced by the evaluation process.
| 1.0 | +| `opa_malloc` |
`addr opa_malloc(int32 size)`
Allocates size bytes in the shared memory and returns the starting address.
| 1.0 | +| `opa_free` |
`void opa_free(addr)`
Free a pointer. Calls `opa_abort` on error.
| 1.0 | +| `opa_json_parse` |
`value_addr opa_json_parse(str_addr, size)`
Parses the JSON serialized value starting at str_addr of size bytes and returns the address of the parsed value. The parsed value may refer to a null, boolean, number, string, array, or object value.
| 1.0 | +| `opa_value_parse` |
`value_addr opa_value_parse(str_addr, size)`
The same as `opa_json_parse` except Rego set literals are supported.
| 1.0 | +| `opa_json_dump` |
`str_addr opa_json_dump(value_addr)`
Dumps the value referred to by `value_addr` to a null-terminated JSON serialized string and returns the address of the start of the string. Rego sets are serialized as JSON arrays. Non-string Rego object keys are serialized as strings.
| 1.0 | +| `opa_value_dump` |
`str_addr opa_value_dump(value_addr)`
The same as `opa_json_dump` except Rego sets are serialized using the literal syntax and non-string Rego object keys are not serialized as strings.
| 1.0 | +| `opa_heap_ptr_set` |
`void opa_heap_ptr_set(addr)`
Set the heap pointer for the next evaluation.
| 1.0 | +| `opa_heap_ptr_get` |
`addr opa_heap_ptr_get(void)`
Get the current heap pointer.
| 1.0 | +| `opa_value_add_path` |
`int32 opa_value_add_path(base_value_addr, path_value_addr, value_addr)`
Add the value at the `value_addr` into the object referenced by `base_value_addr` at the given path. The `path_value_addr` must point to an array value with string keys (eg: `["a", "b", "c"]`). Existing values will be updated. On success the value at `value_addr` is no longer owned by the caller, it will be freed with the base value. The path must be freed by the caller after use (see `opa_free`). If an error occurs the base value will remain unchanged. Example: base object `{"a": {"b": 123}}`, path `["a", "x", "y"]`, and value `{"foo": "bar"}` will yield `{"a": {"b": 123, "x": {"y": {"foo": "bar"}}}}`. Returns an error code (see below).
| 1.0 | +| `opa_value_remove_path` |
`int32 opa_value_remove_path(base_value_addr, path_value_addr)`
Remove the value from the object referenced by `base_value_addr` at the given path. Values removed will be freed. The path must be freed by the caller after use (see `opa_free`). The `path_value_addr` must point to an array value with string keys (eg: `["a", "b", "c"]`). Returns an error code (see below).
| 1.0 | +| `opa_eval` |
`str_addr opa_eval(_ addr, entrypoint_id int32, data value_addr, input str_addr, input_len int32, heap_ptr addr, format int32)`
One-off policy evaluation method. Its arguments are everything needed to evaluate: entrypoint, address of data in memory, address and length of input JSON string in memory, heap address to use, and the output format (`0` is JSON, `1` is "value", i.e. serialized Rego values). The first argument is reserved for future use and must be `0`. Returns the address to the serialised result value.
| 1.2 | The addresses passed and returned by the policy modules are 32-bit integer offsets into the shared memory region. The `value_addr` parameters and return