Skip to content

Split up plugin and stream contexts. #110

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PiotrSikora merged 2 commits into from
Oct 22, 2026
Merged

Split up plugin and stream contexts. #110

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ef2379b
Split plugin and stream context lifecycles.
PiotrSikora Sep 24, 2026
04401f6
review: split `OUT_OF_MEMORY` to `REFUSED` and `GOAWAY`.
PiotrSikora Oct 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 82 additions & 96 deletions abi-versions/vNEXT/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,144 +158,123 @@ Returning `0` indicates failure.
This function is always supported.


## Context lifecycle
## Plugin lifecycle

### Callbacks exposed by the Wasm module

#### `proxy_on_context_create`

* params:
- `i32 (uint32_t) context_id`
- `i32 (uint32_t) parent_context_id`
* returns:
- none

Called when the host creates a new context (`context_id`).

When `parent_context_id` is `0` then a new plugin context is created,
otherwise a new per-stream context is created and `parent_context_id`
refers to the plugin context.

This function is gated on [`HAS_CORE`] host feature.


#### `proxy_on_done`
#### `proxy_on_plugin_create`

* params:
- `i32 (uint32_t) context_id`
* returns:
- `i32 (bool) completed`

Called when the host is done processing context (`context_id`).

Plugin must return one of the following values:
- `true` to allow the host to finalize and delete context.
- `false` to indicate that the context is still being used,
and that plugin is going to call [`proxy_done`] later to
allow the host to finalize and delete that context.

This function is gated on [`HAS_CORE`] host feature.


#### `proxy_on_log`

* params:
- `i32 (uint32_t) context_id`
- `i32 (uint32_t) plugin_context_id`
- `i32 (size_t) plugin_configuration_size`
* returns:
- none
- `i32 (`[`proxy_status_t`]`) status`

Called after the host is done processing context, but before
releasing its state.
Called when the host starts the Proxy-Wasm plugin.

This can be used e.g. for generating final log entries.
Its configuration (of `plugin_configuration_size`) can be retrieved
using [`proxy_get_buffer_bytes`] with `buffer_id` set to
`PLUGIN_CONFIGURATION`.

It's called after `true` was returned from [`proxy_on_done`]
or after a call to [`proxy_done`].
Returned `status` value is:
- `OK` on success.
- `FAILED` when configuration processing and plugin instantiation failed.
- `DUPLICATE_ID` for duplicate `plugin_context_id`.
- `REFUSED` to indicate that plugin cannot be instantiated at this time
(e.g. due to Wasm VM being at capacity).
- `GOAWAY` to indicate that no new plugins will be instantiated in this
Wasm VM.

This function is gated on [`HAS_CORE`] host feature.


#### `proxy_on_delete`
#### `proxy_on_plugin_shutdown`

* params:
- `i32 (uint32_t) context_id`
- `i32 (uint32_t) plugin_context_id`
* returns:
- none
- `i32 (`[`proxy_status_t`]`) status`

Called when the host removes the context (`context_id`) to signal that
the plugin should stop tracking it and remove all associated state.
Called when the host stops the Proxy-Wasm plugin (`plugin_context_id`).

It's called after `true` was returned from [`proxy_on_done`]
or after a call to [`proxy_done`].
Returned `status` value is:
- `OK` to allow the host to finalize and delete context.
- `PENDING` to indicate that the context is still being used,
and that plugin is going to call [`proxy_plugin_done`] later
to allow the host to finalize and delete that context.

This function is gated on [`HAS_CORE`] host feature.


### Functions exposed by the host

#### `proxy_done`
#### `proxy_plugin_done`

* params:
- `i32 (uint32_t) context_id`
- `i32 (uint32_t) plugin_context_id`
* returns:
- `i32 (`[`proxy_status_t`]`) status`

Indicates to the host that the plugin is done processing context
(`context_id`).
(`plugin_context_id`).

This should be used after returning `false` in [`proxy_on_done`].
This should be used after returning `false` in [`proxy_on_plugin_shutdown`].

Returned `status` value is:
- `OK` on success.
- `UNKNOWN_RESOURCE_ID` for unknown `context_id`.
- `NOT_FOUND` when active context was not pending finalization.
- `UNKNOWN_RESOURCE_ID` for unknown `plugin_context_id`.
- `BAD_ARGUMENT` when `plugin_context_id` was not pending finalization.

This function is gated on [`HAS_CORE`] host feature.


## Configuration
## Stream Context lifecycle

### Callbacks exposed by the Wasm module

#### `proxy_on_vm_start`
#### `proxy_on_context_create`

* params:
- `i32 (uint32_t) unused`
- `i32 (size_t) vm_configuration_size`
- `i32 (uint32_t) context_id`
- `i32 (`[`proxy_context_type_t`]`) context_type`
- `i32 (uint32_t) plugin_context_id`
* returns:
- `i32 (bool) status`

Called when the host starts the WebAssembly Virtual Machine.
- `i32 (`[`proxy_status_t`]`) status`

Its configuration (of `vm_configuration_size`) can be retrieved using
[`proxy_get_buffer_bytes`] with `buffer_id` set to `VM_CONFIGURATION`.
Called when the host creates a new stream context (`context_id`)
of type `context_type` for plugin (`plugin_context_id`).

Plugin must return one of the following values:
- `true` to indicate that the configuration was processed successfully.
- `false` to indicate that the configuration processing failed, and that
this instance of WasmVM shouldn't be used.
Returned `status` value is:
- `OK` on success.
- `DUPLICATE_ID` for duplicate `context_id`.
- `BAD_ARGUMENT` for unknown `context_type`.
- `UNKNOWN_RESOURCE_ID` for unknown `plugin_context_id`.
- `REFUSED` to indicate that stream context cannot be instantiated
at this time (e.g. due to Wasm VM being at capacity).
- `GOAWAY` to indicate that no new contexts will be instantiated
in this Wasm VM.

This function is gated on [`HAS_CORE`] host feature.


#### `proxy_on_configure`
#### `proxy_on_context_finalize`

* params:
- `i32 (uint32_t) plugin_context_id`
- `i32 (size_t) plugin_configuration_size`
- `i32 (uint32_t) context_id`
* returns:
- `i32 (bool) status`
- `i32 (`[`proxy_status_t`]`) status`

Called when the host starts the Proxy-Wasm plugin.
Called after the host is done processing stream context (`context_id`),
but before releasing its state.

Its configuration (of `plugin_configuration_size`) can be retrieved
using [`proxy_get_buffer_bytes`] with `buffer_id` set to
`PLUGIN_CONFIGURATION`.
This can be used e.g. for generating final log entries.

Plugin must return one of the following values:
- `true` to indicate that the configuration was processed successfully.
- `false` to indicate that the configuration processing failed, and that
this instance of plugin shouldn't be used.
After completing this callback, plugin should stop tracking this context
and remove all associated state.

Returned `status` value is:
- `OK` on success.
- `UNKNOWN_RESOURCE_ID` for unknown `context_id`.

This function is gated on [`HAS_CORE`] host feature.

Expand Down Expand Up @@ -606,8 +585,7 @@ in this section is restricted to specific callbacks:
- `HTTP_CALL_RESPONSE_BODY` can be read in
[`proxy_on_http_call_response`].
- `GRPC_CALL_MESSAGE` can be read in [`proxy_on_grpc_receive`].
- `VM_CONFIGURATION` can be read in [`proxy_on_vm_start`].
- `PLUGIN_CONFIGURATION` can be read in [`proxy_on_configure`].
- `PLUGIN_CONFIGURATION` can be read in [`proxy_on_plugin_create`].
- `FOREIGN_FUNCTION_ARGUMENTS` can be read in
[`proxy_on_foreign_function`].

Expand Down Expand Up @@ -702,18 +680,18 @@ This function is gated on [`HAS_CORE`] host feature.
Access to HTTP fields (listed in [`proxy_map_type_t`]) using
functions in this section is restricted to specific callbacks:

- `HTTP_REQUEST_HEADERS` can be read in [`proxy_on_log`],
- `HTTP_REQUEST_HEADERS` can be read in [`proxy_on_context_finalize`],
and read and modified from [`proxy_on_request_headers`]
(or for as long as request processing is paused from it).
- `HTTP_REQUEST_TRAILERS` can be read in [`proxy_on_log`],
- `HTTP_REQUEST_TRAILERS` can be read in [`proxy_on_context_finalize`],
and read and modified in [`proxy_on_request_trailers`]
(or for as long as request processing is paused from it).
They can be added in [`proxy_on_request_body`], but only when the
proxied request doesn't have trailers (`end_of_stream` is `true`).
- `HTTP_RESPONSE_HEADERS` can be read in [`proxy_on_log`],
- `HTTP_RESPONSE_HEADERS` can be read in [`proxy_on_context_finalize`],
and read and modified in [`proxy_on_response_headers`]
(or for as long as response processing is paused from it).
- `HTTP_RESPONSE_TRAILERS` can be read in [`proxy_on_log`],
- `HTTP_RESPONSE_TRAILERS` can be read in [`proxy_on_context_finalize`],
and read and modified in [`proxy_on_response_trailers`]
(or for as long as response processing is paused from it).
They can be added in [`proxy_on_response_body`], but only when the
Expand Down Expand Up @@ -2325,6 +2303,11 @@ changes to unrelated connections/requests.
- `NOT_SUPPORTED` = `12`
- `UNKNOWN_RESOURCE_ID` = `13`
- `CREATED` = `14`
- `FAILED` = `15`
- `DUPLICATE_ID` = `16`
- `REFUSED` = `17`
- `PENDING` = `18`
- `GOAWAY` = `19`


#### `proxy_action_t`
Expand All @@ -2341,7 +2324,6 @@ changes to unrelated connections/requests.
- `UPSTREAM_DATA` = `3`
- `HTTP_CALL_RESPONSE_BODY` = `4`
- `GRPC_CALL_MESSAGE` = `5`
- `VM_CONFIGURATION` = `6`
- `PLUGIN_CONFIGURATION` = `7`
- `FOREIGN_FUNCTION_ARGUMENTS` = `8`

Expand All @@ -2365,6 +2347,13 @@ changes to unrelated connections/requests.
- `REMOTE` =`2`


#### `proxy_context_type_t`

- `HTTP` = `1`
- `GRPC` = `2`
- `TCP` = `3`


#### `proxy_stream_type_t`

- `HTTP_REQUEST` = `0`
Expand Down Expand Up @@ -2431,14 +2420,11 @@ changes to unrelated connections/requests.
[`_start`]: #_start
[`proxy_on_memory_allocate`]: #proxy_on_memory_allocate
[`malloc`]: #malloc
[`proxy_on_plugin_create`]: #proxy_on_plugin_create
[`proxy_on_plugin_shutdown`]: #proxy_on_plugin_shutdown
[`proxy_plugin_done`]: #proxy_plugin_done
[`proxy_on_context_create`]: #proxy_on_context_create
[`proxy_on_done`]: #proxy_on_done
[`proxy_on_log`]: #proxy_on_log
[`proxy_on_delete`]: #proxy_on_delete
[`proxy_done`]: #proxy_done
[`proxy_set_effective_context`]: #proxy_set_effective_context
[`proxy_on_vm_start`]: #proxy_on_vm_start
[`proxy_on_configure`]: #proxy_on_configure
[`proxy_on_context_finalize`]: #proxy_on_context_finalize
[`proxy_log`]: #proxy_log
[`proxy_get_log_level`]: #proxy_get_log_level
[`proxy_get_current_time_nanoseconds`]: #proxy_get_current_time_nanoseconds
Expand Down
Loading