Add explicit `context_id` parameter to all hostcalls. by PiotrSikora · Pull Request #92 · proxy-wasm/spec

PiotrSikora · 2025-09-25T16:41:18Z

While there, add and consistently use UNKNOWN_RESOURCE_ID error
for when resources are accessed using an unknown ID.

While there, add and consistently use `UNKNOWN_RESOURCE_ID` error for when resources are accessed using an unknown ID. Signed-off-by: Piotr Sikora <code@piotrsikora.dev>

PiotrSikora · 2025-09-25T16:41:55Z

abi-versions/vNEXT/README.md

 * 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


Perhaps it should be completely removed?

It == proxy_set_effective_context, since we're explicitly passing the context IDs.

Thoughts?

I see no reason to keep this method around.

It'll still be exported by cpp-host for plugins using older versions of the ABI, it just won't be used by the new ABI version.

PiotrSikora · 2025-09-25T16:43:58Z

abi-versions/vNEXT/HOST_FEATURES.md

+
+| 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    |


I originally envisioned this as a helpful step to ease the migration (i.e. SDKs could simply pass 0 as context_id and rely on hosts doing the tracking), but I'm not sure if that's worth it?

Would the alternative be for SDKs to track and pass explicit context IDs from the get go, as part of initial support for the new ABI version? Unless you think there are tricky cases where it would be hard for an SDK to track, ISTM it's not too much work for SDKs to do as part of the switchover.

Yes, that's the alternative.

I think I was originally worried about plugins directly calling hostcalls, and wanted to avoid adding extra code paths to each hostcall to retrieve SDK-tracked context ID, and instead rely on the existing host-side tracking... But I don't have strong opinion here, and perhaps we don't care about plugins that call the hostcalls directly, so we can drop this.

IMO plugins that break out of the SDK are on their own to get the context ID from the SDK (though we should provide getters for the context id in each context).

mpwarres · 2025-12-02T05:27:17Z

abi-versions/vNEXT/HOST_FEATURES.md

+
+| 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    |


Would the alternative be for SDKs to track and pass explicit context IDs from the get go, as part of initial support for the new ABI version? Unless you think there are tricky cases where it would be hard for an SDK to track, ISTM it's not too much work for SDKs to do as part of the switchover.

mpwarres · 2025-12-02T05:36:45Z

abi-versions/vNEXT/README.md


 * params:
-  - none
+  - `i32 (uint32_t) context_id`


In hostcalls like this one, which list their param as context_id rather than stream_context_id or plugin_context_id, is it correct to interpret that as meaning that either type of context ID can be passed?

For this hostcall in particular, would passing plugin_context_id to proxy_done be a way of signalling shutdown of the plugin as a whole?

Sorry, I think I was just being lazy here. proxy_done can only be called with plugin_context_id to signal shutdown of the plugin, that's the only function of this hostcall. It's not supported with stream_context_id.

Signed-off-by: Piotr Sikora <code@piotrsikora.dev>

PiotrSikora · 2026-02-12T16:31:27Z

abi-versions/vNEXT/README.md

 ## Timers

+> **Note**
+> The default timer can be accessed using `timer_id=0`.


This and the default shared KV store (kvstore_id=0) and queue (queue_id=0) are added to ease migration from single instance model in the current ABI, and to simplify plugins that don't require multiple instances, but perhaps we don't need those default instances?

leonm1

My understanding now is that the wasm code itself tells the host which context to use via the context_id parameter. Previously, it was implicit based on the last wasm callback the host invoked.

The context id is given to the wasm code during proxy_on_context_create, then is it the responsibility of the SDK to keep track of it, or is it on plugin authors? It would be helpful guidance to explain this in the description. Can you expand the PR description a bit to express what is changing with this spec change?

leonm1 · 2026-02-12T20:27:20Z

abi-versions/vNEXT/README.md

 * 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


I see no reason to keep this method around.

It'll still be exported by cpp-host for plugins using older versions of the ABI, it just won't be used by the new ABI version.

leonm1 · 2026-02-12T21:17:04Z

abi-versions/vNEXT/HOST_FEATURES.md

+
+| 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    |


IMO plugins that break out of the SDK are on their own to get the context ID from the SDK (though we should provide getters for the context id in each context).

leonm1 · 2026-02-12T21:19:20Z

abi-versions/vNEXT/README.md


 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.


Can you confirm that context_id provided here by the host is what is to be passed as a parameter to all the hostcalls?

Add explicit context_id parameter to all hostcalls.

0c0e758

While there, add and consistently use `UNKNOWN_RESOURCE_ID` error for when resources are accessed using an unknown ID. Signed-off-by: Piotr Sikora <code@piotrsikora.dev>

PiotrSikora requested review from leonm1, martijneken and mpwarres September 25, 2025 16:41

PiotrSikora commented Sep 25, 2025

View reviewed changes

mpwarres reviewed Dec 2, 2025

View reviewed changes

Merge branch 'main' into add_context_id

5eaecd1

PiotrSikora marked this pull request as ready for review February 12, 2026 14:44

review: add note about queue_id=0.

a4f364f

Signed-off-by: Piotr Sikora <code@piotrsikora.dev>

PiotrSikora commented Feb 12, 2026

View reviewed changes

This was referenced Feb 12, 2026

Combine proxy_{register,resolve}_shared_queue into proxy_open_shared_queue. #97

Open

Add support for multiple key-value stores. #98

Open

Add support for multiple timers. #96

Open

Add proxy_exists_shared_data. #99

Open

Add proxy_remove_shared_key. #100

Open

leonm1 reviewed Feb 12, 2026

View reviewed changes

Conversation

PiotrSikora commented Sep 25, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leonm1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants