wasmtime / PR #12367 Debugging: provide access to private... · git-wasmtime

Stream: git-wasmtime

Topic: wasmtime / PR #12367 Debugging: provide access to private...

Wasmtime GitHub notifications bot (Jan 17 2026 at 03:25):

cfallin requested alexcrichton for a review on PR #12367.

Wasmtime GitHub notifications bot (Jan 17 2026 at 03:25):

cfallin opened PR #12367 from cfallin:debugging-access-private-entities to bytecodealliance:main:

A debugger will need to access all entities (globals, tables, memories), even those that are not exported, in order to provide a full debugging experience: for example, a developer who has a developer attached to a Wasm component will expect to be able to see data in its memory.

Historically we have been very careful in Wasmtime to provide access to Wasm instances' entities only as the Wasm type system allows -- that is, only if they are exported. However, debugging is privileged -- in the same way that a native host debugger has ptrace and can view everything about the debuggee, we need to provide APIs for seeing through the encapsulation boundary.

To ensure that this "violation of encapsulation" is scoped only to the extent needed for the legitimate need (debugging), this API is dynamically available only when guest_debug is configured true for a given engine. Otherwise, the accessor returns None.

I opted not to provide a full introspection API that enumerates all of the entities as the debugger should already have access to the debuggee module and be able to enumerate the entities. Thus, the API only provides a host-API handle when asking for an entity by index in a given instance's index space.

Wasmtime GitHub notifications bot (Jan 17 2026 at 03:25):

cfallin requested wasmtime-core-reviewers for a review on PR #12367.

Wasmtime GitHub notifications bot (Jan 17 2026 at 03:26):

cfallin edited PR #12367:

A debugger will need to access all entities (globals, tables, memories), even those that are not exported, in order to provide a full debugging experience: for example, a developer who has a debugger attached to a Wasm component will expect to be able to see data in its memory.

Historically we have been very careful in Wasmtime to provide access to Wasm instances' entities only as the Wasm type system allows -- that is, only if they are exported. However, debugging is privileged -- in the same way that a native host debugger has ptrace and can view everything about the debuggee, we need to provide APIs for seeing through the encapsulation boundary.

To ensure that this "violation of encapsulation" is scoped only to the extent needed for the legitimate need (debugging), this API is dynamically available only when guest_debug is configured true for a given engine. Otherwise, the accessor returns None.

I opted not to provide a full introspection API that enumerates all of the entities as the debugger should already have access to the debuggee module and be able to enumerate the entities. Thus, the API only provides a host-API handle when asking for an entity by index in a given instance's index space.

Wasmtime GitHub notifications bot (Jan 17 2026 at 03:26):

cfallin updated PR #12367.

Wasmtime GitHub notifications bot (Jan 17 2026 at 04:50):

github-actions[bot] added the label wasmtime:api on PR #12367.

Wasmtime GitHub notifications bot (Jan 20 2026 at 00:20):

alexcrichton submitted PR review.

Wasmtime GitHub notifications bot (Jan 20 2026 at 00:20):

alexcrichton created PR review comment:

In the limit, this is something we'll want debuggers to do, right? And this in theory would be pretty easy for us to handle internally by using tunables.debug_guest as a flag to assume that all functions are exported?

Wasmtime GitHub notifications bot (Jan 20 2026 at 00:20):

alexcrichton created PR review comment:

Instead of duplicating the documentation, could one of the methods with documentation link to the other?

Wasmtime GitHub notifications bot (Jan 20 2026 at 00:20):

alexcrichton created PR review comment:

Could this function use vm::Instance::get_export_by_index_mut to avoid duplication? Plus some extra validation ahead of time that the index is valid for the instance-at-hand.

Wasmtime GitHub notifications bot (Jan 20 2026 at 00:20):

alexcrichton created PR review comment:

Despite being unable to do anything with them at the moment, is there a reason to specifically disallow this? I figure it'd be best to go ahead and fill things out while we can otherwise

Wasmtime GitHub notifications bot (Jan 20 2026 at 00:20):

alexcrichton created PR review comment:

Right now FooIndex-style types are all internal to Wasmtime and not present in Wasmtime's public API (or at least that's the intention). Given that it might be best to switch this to debug_get_{global,func,table,memory,tag} perhaps?

Also, I might recommend putting the functionality on Instance since that seems like a natural place to put the methods. You can still do it in this file with impl Instance { ... } since this is still in the same crate defining Instance.

Wasmtime GitHub notifications bot (Jan 20 2026 at 21:26):

fitzgen submitted PR review.

Wasmtime GitHub notifications bot (Jan 20 2026 at 21:26):

fitzgen created PR review comment:

Yes and yes, IMO.

Wasmtime GitHub notifications bot (Jan 20 2026 at 23:50):

cfallin submitted PR review.

Wasmtime GitHub notifications bot (Jan 20 2026 at 23:50):

cfallin created PR review comment:

Unfortunately I want a panic-free interface here (we will expose this method to the debugger guest) so that whole function hierarchy is unusable -- it panics on out-of-bounds.

Wasmtime GitHub notifications bot (Jan 20 2026 at 23:51):

cfallin submitted PR review.

Wasmtime GitHub notifications bot (Jan 20 2026 at 23:51):

cfallin created PR review comment:

I guess I just didn't want to think through the implications until needed but it seems tag exports are pretty harmless, so I'll add this!

Wasmtime GitHub notifications bot (Jan 20 2026 at 23:51):

cfallin created PR review comment:

Yep, I was following precedent here with the bits on Store/StoreContextMut but since this API will move to Instance this won't be an issue anymore.

Wasmtime GitHub notifications bot (Jan 20 2026 at 23:51):

cfallin submitted PR review.

Wasmtime GitHub notifications bot (Jan 20 2026 at 23:53):

cfallin submitted PR review.

Wasmtime GitHub notifications bot (Jan 20 2026 at 23:53):

cfallin created PR review comment:

Fair enough -- I saw the types were public via wasmtime_environ but I'm happy to stick with u32s!

I'll move the API over to Instance -- was trying to keep the debug API small and localized to a few methods on the store but I agree it makes more sense alongside other accessors per-instance.

Wasmtime GitHub notifications bot (Jan 21 2026 at 00:49):

cfallin updated PR #12367.

Wasmtime GitHub notifications bot (Jan 21 2026 at 00:50):

cfallin submitted PR review.

Wasmtime GitHub notifications bot (Jan 21 2026 at 00:50):

cfallin created PR review comment:

Err, reading again your "extra validation ahead of time" -- once that bit is done, the rest of the logic is pretty trivial (one result expression) and actually a bit simpler than rebuilding an EntityIndex so I think I'll leave as-is -- happy to tweak if desired though.

Wasmtime GitHub notifications bot (Jan 21 2026 at 00:51):

cfallin submitted PR review.

Wasmtime GitHub notifications bot (Jan 21 2026 at 00:51):

cfallin created PR review comment:

Done!

Wasmtime GitHub notifications bot (Jan 21 2026 at 00:51):

cfallin submitted PR review.

Wasmtime GitHub notifications bot (Jan 21 2026 at 00:51):

cfallin created PR review comment:

Done! Added the bit to flag all functions as escaping and test cases both for call to unexported module-defined func and unexported import.

Wasmtime GitHub notifications bot (Jan 21 2026 at 00:52):

cfallin commented on PR #12367:

Reworked now -- a bit more verbose API but seems more in line with what is there already. Thanks!

Wasmtime GitHub notifications bot (Jan 21 2026 at 15:41):

alexcrichton created PR review comment:

In addition to CodeSectionEntry, I think this'll need to be done for function imports too

Wasmtime GitHub notifications bot (Jan 21 2026 at 15:41):

alexcrichton created PR review comment:

Instead of making the field public could this use the instance.id() method?

Wasmtime GitHub notifications bot (Jan 21 2026 at 15:41):

alexcrichton submitted PR review:

FWIW we more-or-less consider wasmtime-environ to be a private crate for now. It's "more public" than everything else we have that's not actually public given its history, but we haven't pulled the trigger on making it actually official or anything like that. I think it would need a lot of API cleanups to have the same quality as wasmtime-the-crate.

Wasmtime GitHub notifications bot (Jan 21 2026 at 15:57):

cfallin submitted PR review.

Wasmtime GitHub notifications bot (Jan 21 2026 at 15:57):

cfallin created PR review comment:

Unfortunately that returns an InstanceId and we need a StoreInstanceId to index into the store; it appears that fn id() isn't used anywhere else for this purpose and all other accessors that pull out the vm::Instance from the store live in instance.rs and use the field directly. Happy to refactor all this in followup if you want to push it in a different direction!