Skip to content

A lightweight WebAssembly runtime that is fast, secure, and standards-compliant

Debugging: add the debug-main world. (#12756)

Chris Fallin133a0ef4af99
diff --git a/.github/actions/install-rust/action.yml b/.github/actions/install-rust/action.yml
index 7c8cf29458..f7622e2272 100644
--- a/.github/actions/install-rust/action.yml
+++ b/.github/actions/install-rust/action.yml
@@ -79,4 +79,4 @@ runs:
- name: Install the WASI target
shell: bash
- run: rustup target add wasm32-wasip1 wasm32-unknown-unknown
+ run: rustup target add wasm32-wasip2 wasm32-wasip1 wasm32-unknown-unknown
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 65cbd936c3..bad3100334 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -739,7 +739,7 @@ jobs:
toolchain: ${{ matrix.rust }}
# Install targets in order to build various tests throughout the repo
- - run: rustup target add wasm32-wasip1 wasm32-unknown-unknown ${{ matrix.target }}
+ - run: rustup target add wasm32-wasip1 wasm32-unknown-unknown wasm32-wasip2 ${{ matrix.target }}
- run: echo CARGO_BUILD_TARGET=${{ matrix.target }} >> $GITHUB_ENV
if: matrix.target != ''
@@ -937,7 +937,7 @@ jobs:
if: (runner.os == 'Windows') && (matrix.feature == 'winml')
# Install Rust targets.
- - run: rustup target add wasm32-wasip1
+ - run: rustup target add wasm32-wasip1 wasm32-wasip2
# Run the tests!
- run: cargo test -p wasmtime-wasi-nn --features ${{ matrix.feature }}
@@ -1009,7 +1009,7 @@ jobs:
submodules: true
- uses: ./.github/actions/install-rust
- run: |
- rustup target add wasm32-wasip1 wasm32-unknown-unknown
+ rustup target add wasm32-wasip2 wasm32-wasip1 wasm32-unknown-unknown
cd /tmp
curl --retry 5 --retry-all-errors -OL https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-30/wasi-sdk-30.0-x86_64-linux.tar.gz
tar -xzf wasi-sdk-30.0-x86_64-linux.tar.gz
@@ -1038,7 +1038,7 @@ jobs:
with:
submodules: true
- uses: ./.github/actions/install-rust
- - run: rustup target add wasm32-wasip1 wasm32-unknown-unknown
+ - run: rustup target add wasm32-wasip2 wasm32-wasip1 wasm32-unknown-unknown
- name: Install wasm-tools
run: |
@@ -1118,7 +1118,7 @@ jobs:
with:
submodules: true
- uses: ./.github/actions/install-rust
- - run: rustup target add wasm32-wasip1
+ - run: rustup target add wasm32-wasip2 wasm32-wasip1
- run: cargo test --benches --release
# Verify that cranelift's code generation is deterministic
diff --git a/Cargo.lock b/Cargo.lock
index 6b7caf5db7..34b7101877 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4672,6 +4672,7 @@ dependencies = [
"wasmtime-internal-cache",
"wasmtime-internal-component-util",
"wasmtime-internal-cranelift",
+ "wasmtime-internal-debugger",
"wasmtime-internal-explorer",
"wasmtime-internal-unwinder",
"wasmtime-test-macros",
@@ -4917,10 +4918,13 @@ dependencies = [
name = "wasmtime-internal-debugger"
version = "44.0.0"
dependencies = [
+ "async-trait",
"env_logger 0.11.5",
"log",
"tokio",
"wasmtime",
+ "wasmtime-wasi",
+ "wasmtime-wasi-io",
]
[[package]]
diff --git a/Cargo.toml b/Cargo.toml
index 7e5d171bfb..8a68c79afc 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -60,6 +60,7 @@ wasmtime-wasi-threads = { workspace = true, optional = true }
wasmtime-wasi-http = { workspace = true, optional = true }
wasmtime-unwinder = { workspace = true }
wasmtime-wizer = { workspace = true, optional = true, features = ['clap', 'wasmtime'] }
+wasmtime-debugger = { workspace = true, optional = true }
clap = { workspace = true }
clap_complete = { workspace = true, optional = true }
target-lexicon = { workspace = true }
@@ -565,7 +566,7 @@ gc-drc = ["gc", "wasmtime/gc-drc", "wasmtime-cli-flags/gc-drc"]
gc-null = ["gc", "wasmtime/gc-null", "wasmtime-cli-flags/gc-null"]
pulley = ["wasmtime-cli-flags/pulley"]
stack-switching = ["wasmtime/stack-switching", "wasmtime-cli-flags/stack-switching"]
-debug = ["wasmtime-cli-flags/debug", "wasmtime/debug"]
+debug = ["wasmtime-cli-flags/debug", "wasmtime/debug", "component-model"]
# CLI subcommands for the `wasmtime` executable. See `wasmtime $cmd --help`
# for more information on each subcommand.
@@ -591,6 +592,7 @@ run = [
"dep:tokio",
"wasmtime-cli-flags/async",
"wasmtime-wasi-http?/p2",
+ "dep:wasmtime-debugger",
]
completion = ["dep:clap_complete"]
objdump = [
diff --git a/ci/vendor-wit.sh b/ci/vendor-wit.sh
index 150b4ee149..80547228f4 100755
--- a/ci/vendor-wit.sh
+++ b/ci/vendor-wit.sh
@@ -90,6 +90,15 @@ wkg get --format wit --overwrite "wasi:random@$p3" -o "crates/wasi-http/src/p3/w
wkg get --format wit --overwrite "wasi:sockets@$p3" -o "crates/wasi-http/src/p3/wit/deps/sockets.wit"
wkg get --format wit --overwrite "wasi:http@$p3" -o "crates/wasi-http/src/p3/wit/deps/http.wit"
+rm -rf crates/debugger/wit/deps
+mkdir -p crates/debugger/wit/deps
+wkg get --format wit --overwrite "wasi:io@$p2" -o "crates/debugger/wit/deps/io.wit"
+wkg get --format wit --overwrite "wasi:clocks@$p2" -o "crates/debugger/wit/deps/clocks.wit"
+wkg get --format wit --overwrite "wasi:cli@$p2" -o "crates/debugger/wit/deps/cli.wit"
+wkg get --format wit --overwrite "wasi:filesystem@$p2" -o "crates/debugger/wit/deps/filesystem.wit"
+wkg get --format wit --overwrite "wasi:random@$p2" -o "crates/debugger/wit/deps/random.wit"
+wkg get --format wit --overwrite "wasi:sockets@$p2" -o "crates/debugger/wit/deps/sockets.wit"
+
# wasi-nn is fetched separately since it's not in the standard WASI registry
repo=https://raw.githubusercontent.com/WebAssembly/wasi-nn
revision=0.2.0-rc-2024-10-28
diff --git a/crates/cli-flags/src/lib.rs b/crates/cli-flags/src/lib.rs
index a966f53f63..c543771bc1 100644
--- a/crates/cli-flags/src/lib.rs
+++ b/crates/cli-flags/src/lib.rs
@@ -273,6 +273,22 @@ wasmtime_option_group! {
pub log_to_files: Option<bool>,
/// Enable coredump generation to this file after a WebAssembly trap.
pub coredump: Option<String>,
+ /// Load the given debugger component and attach it to the
+ /// main module or component.
+ pub debugger: Option<PathBuf>,
+ /// Pass the given command-line arguments to the debugger
+ /// component. May be specified multiple times.
+ #[serde(default)]
+ pub arg: Vec<String>,
+ /// Allow the debugger component to inherit stdin.Off by
+ /// default.
+ pub inherit_stdin: Option<bool>,
+ /// Allow the debugger component to inherit stdout. Off by
+ /// default.
+ pub inherit_stdout: Option<bool>,
+ /// Allow the debugger component to inherit stderr. Off by
+ /// default.
+ pub inherit_stderr: Option<bool>,
}
enum Debug {
@@ -491,6 +507,12 @@ wasmtime_option_group! {
///
/// This option can be further overwritten with `--env` flags.
pub inherit_env: Option<bool>,
+ /// Inherit stdin from the parent process. On by default.
+ pub inherit_stdin: Option<bool>,
+ /// Inherit stdout from the parent process. On by default.
+ pub inherit_stdout: Option<bool>,
+ /// Inherit stderr from the parent process. On by default.
+ pub inherit_stderr: Option<bool>,
/// Pass a wasi config variable to the program.
#[serde(skip)]
pub config_var: Vec<KeyValuePair>,
diff --git a/crates/cli-flags/src/opt.rs b/crates/cli-flags/src/opt.rs
index c8c8ef4e20..1427bb93c1 100644
--- a/crates/cli-flags/src/opt.rs
+++ b/crates/cli-flags/src/opt.rs
@@ -9,6 +9,8 @@ use crate::{KeyValuePair, WasiNnGraph};
use clap::builder::{StringValueParser, TypedValueParser, ValueParserFactory};
use clap::error::{Error, ErrorKind};
use serde::de::{self, Visitor};
+use std::path::PathBuf;
+use std::str::FromStr;
use std::time::Duration;
use std::{fmt, marker};
use wasmtime::{Result, bail};
@@ -344,6 +346,20 @@ impl WasmtimeOptionValue for String {
}
}
+impl WasmtimeOptionValue for PathBuf {
+ const VAL_HELP: &'static str = "=path";
+ fn parse(val: Option<&str>) -> Result<Self> {
+ match val {
+ Some(val) => Ok(PathBuf::from_str(val)?),
+ None => bail!("value must be specified with key=val syntax"),
+ }
+ }
+
+ fn display(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ write!(f, "{self:?}")
+ }
+}
+
impl WasmtimeOptionValue for u32 {
const VAL_HELP: &'static str = "=N";
fn parse(val: Option<&str>) -> Result<Self> {
diff --git a/crates/debugger/Cargo.toml b/crates/debugger/Cargo.toml
index 466b24c82b..9aeb815d96 100644
--- a/crates/debugger/Cargo.toml
+++ b/crates/debugger/Cargo.toml
@@ -12,9 +12,12 @@ rust-version.workspace = true
workspace = true
[dependencies]
-wasmtime = { workspace = true, features = ["debug", "std", "async"] }
+wasmtime = { workspace = true, features = ["debug", "std", "async", "component-model", "gc", "gc-drc"] }
+wasmtime-wasi = { workspace = true }
+wasmtime-wasi-io = { workspace = true }
tokio = { workspace = true, features = ["rt", "sync", "macros"] }
log = { workspace = true }
+async-trait = { workspace = true }
[dev-dependencies]
# Depend on `wasmtime` again to get `cranelift` and `wat` so we can
diff --git a/crates/debugger/src/host.rs b/crates/debugger/src/host.rs
new file mode 100644
index 0000000000..8e0bb3921a
--- /dev/null
+++ b/crates/debugger/src/host.rs
@@ -0,0 +1,38 @@
+//! Host implementation for the debugger world.
+
+use wasmtime::{
+ Result,
+ component::{Resource, ResourceTable},
+};
+
+mod api;
+mod bindings;
+mod opaque;
+
+pub use api::Debuggee;
+pub use bindings::DebugMain as DebuggerComponent;
+pub use bindings::bytecodealliance::wasmtime::debuggee as wit;
+use opaque::OpaqueDebugger;
+
+/// Register a debuggee in a resource table.
+pub fn add_debuggee<T: Send + 'static>(
+ table: &mut ResourceTable,
+ debuggee: crate::Debuggee<T>,
+) -> Result<Resource<Debuggee>> {
+ let engine = debuggee.engine().clone();
+ let interrupt_pending = debuggee.interrupt_pending().clone();
+ let inner: Option<Box<dyn OpaqueDebugger + Send + 'static>> = Some(Box::new(debuggee));
+ Ok(table.push(Debuggee {
+ inner,
+ engine,
+ interrupt_pending,
+ })?)
+}
+
+/// Add the debugger world's host functions to a [`wasmtime::component::Linker`].
+pub fn add_to_linker<T: Send + 'static>(
+ linker: &mut wasmtime::component::Linker<T>,
+ f: fn(&mut T) -> &mut ResourceTable,
+) -> wasmtime::Result<()> {
+ wit::add_to_linker::<_, wasmtime::component::HasSelf<ResourceTable>>(linker, f)
+}
diff --git a/crates/debugger/src/host/api.rs b/crates/debugger/src/host/api.rs
new file mode 100644
index 0000000000..e3a6280c21
--- /dev/null
+++ b/crates/debugger/src/host/api.rs
@@ -0,0 +1,1055 @@
+//! Implementations of the host API traits.
+
+use crate::host::opaque::OpaqueDebugger;
+use crate::host::wit;
+use crate::{DebugRunResult, host::bindings::wasm_type_to_val_type};
+use std::pin::Pin;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use wasmtime::{
+ Engine, ExnRef, FrameHandle, Func, Global, Instance, Memory, Module, OwnedRooted, Result,
+ Table, Tag, Val, component::Resource, component::ResourceTable,
+};
+use wasmtime_wasi::p2::{DynPollable, Pollable, subscribe};
+
+/// Representation of one debuggee: a store with debugged code inside,
+/// under the control of the debugger.
+pub struct Debuggee {
+ /// The type-erased debugger implementation. This field is `Some`
+ /// when execution is paused, and `None`, with ownership of the
+ /// debugger (hence debuggee's store) passed to the future when
+ /// executing.
+ pub(crate) inner: Option<Box<dyn OpaqueDebugger + Send + 'static>>,
+
+ /// A separate handle to the Engine, allowing incrementing the
+ /// epoch (hence interrupting a running debuggee) without taking
+ /// the mutex.
+ pub(crate) engine: Engine,
+
+ /// Shared flag: set to `true` by `interrupt()` so the inner
+ /// handler treats the next epoch yield as an `Interrupted` event.
+ pub(crate) interrupt_pending: Arc<AtomicBool>,
+}
+
+impl Debuggee {
+ /// Finish execution of the debuggee before returning.
+ pub async fn finish(&mut self) -> Result<()> {
+ if let Some(inner) = self.inner.as_mut() {
+ inner.finish().await?;
+ }
+ Ok(())
+ }
+}
+
+impl WasmValue {
+ pub(crate) fn new(store: impl wasmtime::AsContextMut, val: Val) -> Result<WasmValue> {
+ Ok(match val {
+ Val::ExnRef(Some(rooted)) => {
+ WasmValue::Exn(Some(rooted.to_owned_rooted(store).unwrap()))
+ }
+ Val::ExnRef(None) => WasmValue::Exn(None),
+ Val::FuncRef(Some(f)) => WasmValue::Func(Some(f)),
+ Val::FuncRef(None) => WasmValue::Func(None),
+ Val::ExternRef(_) | Val::AnyRef(_) | Val::ContRef(_) => {
+ return Err(wit::Error::UnsupportedType.into());
+ }
+ Val::I32(_) | Val::I64(_) | Val::F32(_) | Val::F64(_) | Val::V128(_) => {
+ WasmValue::Primitive(val)
+ }
+ })
+ }
+
+ pub(crate) fn into_val(self, store: impl wasmtime::AsContextMut) -> Val {
+ match self {
+ WasmValue::Primitive(v) => v,
+ WasmValue::Exn(Some(owned)) => Val::ExnRef(Some(owned.to_rooted(store))),
+ WasmValue::Exn(None) => Val::ExnRef(None),
+ WasmValue::Func(Some(f)) => Val::FuncRef(Some(f)),
+ WasmValue::Func(None) => Val::FuncRef(None),
+ }
+ }
+}
+
+/// Representation of an async debug event that the debugger is
+/// waiting on.
+///
+/// Cancel-safety: the non-cancel-safe OpaqueDebugger async methods
+/// are called inside an `async move` block that owns the debugger.
+/// `ready()` merely polls this stored future, which is always safe to
+/// re-poll after cancelation. The debugger is returned in the `Done`
+/// state and extracted by `finish()`.
+pub struct EventFuture {
+ state: EventFutureState,
+}
+
+enum EventFutureState {
+ /// The future is running; owns the debugger.
+ Running(
+ Pin<
+ Box<
+ dyn Future<
+ Output = (
+ Box<dyn OpaqueDebugger + Send + 'static>,
+ Result<DebugRunResult>,
+ ),
+ > + Send,
+ >,
+ >,
+ ),
+ /// The future has completed; debugger is ready to be returned.
+ Done {
+ inner: Box<dyn OpaqueDebugger + Send + 'static>,
+ result: Option<Result<DebugRunResult>>,
+ },
+}
+
+impl EventFuture {
+ fn new_single_step(
+ mut inner: Box<dyn OpaqueDebugger + Send + 'static>,
+ resumption: wit::ResumptionValue,
+ ) -> Self {
+ EventFuture {
+ state: EventFutureState::Running(Box::pin(async move {
+ if let Err(e) = inner.handle_resumption(&resumption).await {
+ return (inner, Err(e));
+ }
+ let result = inner.single_step().await;
+ (inner, result)
+ })),
+ }
+ }
+
+ fn new_continue(
+ mut inner: Box<dyn OpaqueDebugger + Send + 'static>,
+ resumption: wit::ResumptionValue,
+ ) -> Self {
+ EventFuture {
+ state: EventFutureState::Running(Box::pin(async move {
+ if let Err(e) = inner.handle_resumption(&resumption).await {
+ return (inner, Err(e));
+ }
+ let result = inner.continue_().await;
+ (inner, result)
+ })),
+ }
+ }
+}
+
+#[async_trait::async_trait]
+impl wasmtime_wasi_io::poll::Pollable for EventFuture {
+ async fn ready(&mut self) {
+ match &mut self.state {
+ EventFutureState::Running(future) => {
+ let (inner, result) = future.await;
+ self.state = EventFutureState::Done {
+ inner,
+ result: Some(result),
+ };
+ }
+ EventFutureState::Done { .. } => {}
+ }
+ }
+}
+
+/// Representation of a frame within a debuggee.
+#[derive(Clone)]
+pub struct Frame(FrameHandle);
+
+/// Representation of a Wasm exception object.
+#[derive(Clone)]
+pub struct WasmException(OwnedRooted<ExnRef>);
+
+/// Representation of a Wasm value.
+///
+/// This is distinct from `wasmtime::Val` because we need the Owned
+/// variants of GC references here.
+#[derive(Clone)]
+pub enum WasmValue {
+ /// A primitive (non-GC) value.
+ Primitive(Val),
+ /// An exception object.
+ Exn(Option<OwnedRooted<ExnRef>>),
+ /// A funcref.
+ Func(Option<Func>),
+ // TODO: GC structs and arrays.
+}
+
+/// Get the `OpaqueDebugger` or raise an error.
+fn debugger<'a>(
+ table: &'a mut ResourceTable,
+ debuggee: &Resource<Debuggee>,
+) -> Result<&'a mut dyn OpaqueDebugger> {
+ let d = table.get_mut(&debuggee)?.inner.as_mut().ok_or_else(|| {
+ wasmtime::error::format_err!("Attempt to use debuggee API while a future is pending")
+ })?;
+ Ok(&mut **d)
+}
+
+impl wit::HostDebuggee for ResourceTable {
+ async fn all_modules(&mut self, debuggee: Resource<Debuggee>) -> Result<Vec<Resource<Module>>> {
+ let d = debugger(self, &debuggee)?;
+ let modules = d.all_modules().await?;
+ let mut resources = vec![];
+ for module in modules {
+ resources.push(self.push_child(module, &debuggee)?);
+ }
+ Ok(resources)
+ }
+
+ async fn all_instances(
+ &mut self,
+ debuggee: Resource<Debuggee>,
+ ) -> Result<Vec<Resource<Instance>>> {
+ let d = debugger(self, &debuggee)?;
+ let instances = d.all_instances().await?;
+ let mut resources = vec![];
+ for instance in instances {
+ resources.push(self.push_child(instance, &debuggee)?);
+ }
+ Ok(resources)
+ }
+
+ async fn interrupt(&mut self, debuggee: Resource<Debuggee>) -> Result<()> {
+ let d = self.get_mut(&debuggee)?;
+ d.interrupt_pending.store(true, Ordering::SeqCst);
+ d.engine.increment_epoch();
+ Ok(())
+ }
+
+ async fn single_step(
+ &mut self,
+ debuggee: Resource<Debuggee>,
+ resumption: wit::ResumptionValue,
+ ) -> Result<Resource<EventFuture>> {
+ let d = self.get_mut(&debuggee).unwrap().inner.take().unwrap();
+ Ok(self.push_child(EventFuture::new_single_step(d, resumption), &debuggee)?)
+ }
+
+ async fn continue_(
+ &mut self,
+ debuggee: Resource<Debuggee>,
+ resumption: wit::ResumptionValue,
+ ) -> Result<Resource<EventFuture>> {
+ let d = self.get_mut(&debuggee).unwrap().inner.take().unwrap();
+ Ok(self.push_child(EventFuture::new_continue(d, resumption), &debuggee)?)
+ }
+
+ async fn exit_frames(&mut self, debuggee: Resource<Debuggee>) -> Result<Vec<Resource<Frame>>> {
+ let d = debugger(self, &debuggee)?;
+ let frames = d.exit_frames().await?;
+ let mut result = vec![];
+ for frame in frames {
+ result.push(self.push_child(Frame(frame), &debuggee)?);
+ }
+ Ok(result)
+ }
+
+ async fn drop(&mut self, debuggee: Resource<Debuggee>) -> Result<()> {
+ self.delete(debuggee)?;
+ Ok(())
+ }
+}
+
+fn result_to_event(table: &mut ResourceTable, value: DebugRunResult) -> Result<wit::Event> {
+ Ok(match value {
+ DebugRunResult::Finished => wit::Event::Complete,
+ DebugRunResult::HostcallError => wit::Event::Trap,
+ DebugRunResult::Trap(_t) => wit::Event::Trap,
+ DebugRunResult::Breakpoint => wit::Event::Breakpoint,
+ DebugRunResult::EpochYield => wit::Event::Interrupted,
+ DebugRunResult::CaughtExceptionThrown(e) => {
+ let e = table.push(WasmException(e))?;
+ wit::Event::CaughtExceptionThrown(e)
+ }
+ DebugRunResult::UncaughtExceptionThrown(e) => {
+ let e = table.push(WasmException(e))?;
+ wit::Event::UncaughtExceptionThrown(e)
+ }
+ })
+}
+
+impl wit::HostEventFuture for ResourceTable {
+ async fn finish(
+ &mut self,
+ self_: Resource<EventFuture>,
+ debuggee: Resource<Debuggee>,
+ ) -> Result<wit::Event> {
+ let mut f = self.delete(self_)?;
+ f.ready().await;
+ match f.state {
+ EventFutureState::Running(..) => {
+ unreachable!("ready() cannot return until setting Done state")
+ }
+ EventFutureState::Done { inner, result } => {
+ self.get_mut(&debuggee)?.inner = Some(inner);
+ match result.unwrap() {
+ Ok(result) => Ok(result_to_event(self, result)?),
+ Err(e) => Err(e),
+ }
+ }
+ }
+ }
+
+ async fn drop(&mut self, rep: Resource<EventFuture>) -> Result<()> {
+ self.delete(rep)?;
+ Ok(())
+ }
+
+ async fn subscribe(&mut self, self_: Resource<EventFuture>) -> Result<Resource<DynPollable>> {
+ subscribe(self, self_)
+ }
+}
+
+impl wit::HostInstance for ResourceTable {
+ async fn get_module(
+ &mut self,
+ self_: Resource<Instance>,
+ d: Resource<Debuggee>,
+ ) -> Result<Resource<Module>> {
+ let i = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ let module = d.get_instance_module(i).await?;
+ let module = self.push(module)?;
+ Ok(module)
+ }
+
+ async fn get_memory(
+ &mut self,
+ self_: Resource<Instance>,
+ d: Resource<Debuggee>,
+ memory_index: u32,
+ ) -> Result<Resource<Memory>> {
+ let instance = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ let memory = d
+ .instance_get_memory(instance, memory_index)
+ .await?
+ .ok_or(wit::Error::InvalidEntity)?;
+ Ok(self.push(memory)?)
+ }
+
+ async fn get_global(
+ &mut self,
+ self_: Resource<Instance>,
+ d: Resource<Debuggee>,
+ global_index: u32,
+ ) -> Result<Resource<Global>> {
+ let instance = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ let global = d
+ .instance_get_global(instance, global_index)
+ .await?
+ .ok_or(wit::Error::InvalidEntity)?;
+ Ok(self.push(global)?)
+ }
+
+ async fn get_table(
+ &mut self,
+ self_: Resource<Instance>,
+ d: Resource<Debuggee>,
+ table_index: u32,
+ ) -> Result<Resource<Table>> {
+ let instance = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ let table = d
+ .instance_get_table(instance, table_index)
+ .await?
+ .ok_or(wit::Error::InvalidEntity)?;
+ Ok(self.push(table)?)
+ }
+
+ async fn get_func(
+ &mut self,
+ self_: Resource<Instance>,
+ d: Resource<Debuggee>,
+ func_index: u32,
+ ) -> Result<Resource<Func>> {
+ let instance = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ let func = d
+ .instance_get_func(instance, func_index)
+ .await?
+ .ok_or(wit::Error::InvalidEntity)?;
+ Ok(self.push(func)?)
+ }
+
+ async fn get_tag(
+ &mut self,
+ self_: Resource<Instance>,
+ d: Resource<Debuggee>,
+ tag_index: u32,
+ ) -> Result<Resource<Tag>> {
+ let instance = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ let tag = d
+ .instance_get_tag(instance, tag_index)
+ .await?
+ .ok_or(wit::Error::InvalidEntity)?;
+ Ok(self.push(tag)?)
+ }
+
+ async fn clone(&mut self, self_: Resource<Instance>) -> Result<Resource<Instance>> {
+ let instance = *self.get(&self_)?;
+ Ok(self.push(instance)?)
+ }
+
+ async fn unique_id(&mut self, self_: Resource<Instance>) -> Result<u64> {
+ let instance = self.get(&self_)?;
+ Ok(u64::from(instance.debug_index_in_store()))
+ }
+
+ async fn drop(&mut self, rep: Resource<Instance>) -> Result<()> {
+ self.delete(rep)?;
+ Ok(())
+ }
+}
+
+impl wit::HostModule for ResourceTable {
+ async fn add_breakpoint(
+ &mut self,
+ self_: Resource<Module>,
+ d: Resource<Debuggee>,
+ pc: u32,
+ ) -> Result<()> {
+ let module = self.get(&self_)?.clone();
+ let d = debugger(self, &d)?;
+ d.module_add_breakpoint(module, pc).await
+ }
+
+ async fn remove_breakpoint(
+ &mut self,
+ self_: Resource<Module>,
+ d: Resource<Debuggee>,
+ pc: u32,
+ ) -> Result<()> {
+ let module = self.get(&self_)?.clone();
+ let d = debugger(self, &d)?;
+ d.module_remove_breakpoint(module, pc).await
+ }
+
+ async fn bytecode(&mut self, self_: Resource<Module>) -> Result<Option<Vec<u8>>> {
+ let module = self.get(&self_)?;
+ Ok(module.debug_bytecode().map(|b| b.to_vec()))
+ }
+
+ async fn clone(&mut self, self_: Resource<Module>) -> Result<Resource<Module>> {
+ let module = self.get(&self_)?.clone();
+ Ok(self.push(module)?)
+ }
+
+ async fn unique_id(&mut self, self_: Resource<Module>) -> Result<u64> {
+ let module = self.get(&self_)?;
+ Ok(module.debug_index_in_engine())
+ }
+
+ async fn drop(&mut self, rep: Resource<Module>) -> Result<()> {
+ self.delete(rep)?;
+ Ok(())
+ }
+}
+
+impl wit::HostMemory for ResourceTable {
+ async fn size_bytes(&mut self, self_: Resource<Memory>, d: Resource<Debuggee>) -> Result<u64> {
+ let memory = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ d.memory_size_bytes(memory).await
+ }
+
+ async fn page_size_bytes(
+ &mut self,
+ self_: Resource<Memory>,
+ d: Resource<Debuggee>,
+ ) -> Result<u64> {
+ let memory = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ d.memory_page_size(memory).await
+ }
+
+ async fn grow_to_bytes(
+ &mut self,
+ self_: Resource<Memory>,
+ d: Resource<Debuggee>,
+ delta_bytes: u64,
+ ) -> Result<u64> {
+ let memory = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ d.memory_grow(memory, delta_bytes).await
+ }
+
+ async fn get_bytes(
+ &mut self,
+ self_: Resource<Memory>,
+ d: Resource<Debuggee>,
+ addr: u64,
+ len: u64,
+ ) -> Result<Vec<u8>> {
+ let memory = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ Ok(d.memory_read_bytes(memory, addr, len)
+ .await?
+ .ok_or(wit::Error::OutOfBounds)?)
+ }
+
+ async fn set_bytes(
+ &mut self,
+ self_: Resource<Memory>,
+ d: Resource<Debuggee>,
+ addr: u64,
+ bytes: Vec<u8>,
+ ) -> Result<()> {
+ let memory = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ d.memory_write_bytes(memory, addr, bytes)
+ .await?
+ .ok_or(wit::Error::OutOfBounds)?;
+ Ok(())
+ }
+
+ async fn get_u8(
+ &mut self,
+ self_: Resource<Memory>,
+ d: Resource<Debuggee>,
+ addr: u64,
+ ) -> Result<u8> {
+ let memory = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ Ok(d.memory_read_u8(memory, addr)
+ .await?
+ .ok_or(wit::Error::OutOfBounds)?)
+ }
+
+ async fn get_u16(
+ &mut self,
+ self_: Resource<Memory>,
+ d: Resource<Debuggee>,
+ addr: u64,
+ ) -> Result<u16> {
+ let memory = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ Ok(d.memory_read_u16(memory, addr)
+ .await?
+ .ok_or(wit::Error::OutOfBounds)?)
+ }
+
+ async fn get_u32(
+ &mut self,
+ self_: Resource<Memory>,
+ d: Resource<Debuggee>,
+ addr: u64,
+ ) -> Result<u32> {
+ let memory = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ Ok(d.memory_read_u32(memory, addr)
+ .await?
+ .ok_or(wit::Error::OutOfBounds)?)
+ }
+
+ async fn get_u64(
+ &mut self,
+ self_: Resource<Memory>,
+ d: Resource<Debuggee>,
+ addr: u64,
+ ) -> Result<u64> {
+ let memory = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ Ok(d.memory_read_u64(memory, addr)
+ .await?
+ .ok_or(wit::Error::OutOfBounds)?)
+ }
+
+ async fn set_u8(
+ &mut self,
+ self_: Resource<Memory>,
+ d: Resource<Debuggee>,
+ addr: u64,
+ value: u8,
+ ) -> Result<()> {
+ let memory = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ d.memory_write_u8(memory, addr, value)
+ .await?
+ .ok_or(wit::Error::OutOfBounds)?;
+ Ok(())
+ }
+
+ async fn set_u16(
+ &mut self,
+ self_: Resource<Memory>,
+ d: Resource<Debuggee>,
+ addr: u64,
+ value: u16,
+ ) -> Result<()> {
+ let memory = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ d.memory_write_u16(memory, addr, value)
+ .await?
+ .ok_or(wit::Error::OutOfBounds)?;
+ Ok(())
+ }
+
+ async fn set_u32(
+ &mut self,
+ self_: Resource<Memory>,
+ d: Resource<Debuggee>,
+ addr: u64,
+ value: u32,
+ ) -> Result<()> {
+ let memory = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ d.memory_write_u32(memory, addr, value)
+ .await?
+ .ok_or(wit::Error::OutOfBounds)?;
+ Ok(())
+ }
+
+ async fn set_u64(
+ &mut self,
+ self_: Resource<Memory>,
+ d: Resource<Debuggee>,
+ addr: u64,
+ value: u64,
+ ) -> Result<()> {
+ let memory = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ d.memory_write_u64(memory, addr, value)
+ .await?
+ .ok_or(wit::Error::OutOfBounds)?;
+ Ok(())
+ }
+
+ async fn clone(&mut self, self_: Resource<Memory>) -> Result<Resource<Memory>> {
+ let memory = *self.get(&self_)?;
+ Ok(self.push(memory)?)
+ }
+
+ async fn unique_id(&mut self, self_: Resource<Memory>) -> Result<u64> {
+ Ok(self.get(&self_)?.debug_index_in_store())
+ }
+
+ async fn drop(&mut self, rep: Resource<Memory>) -> Result<()> {
+ self.delete(rep)?;
+ Ok(())
+ }
+}
+
+impl wit::HostGlobal for ResourceTable {
+ async fn get(
+ &mut self,
+ self_: Resource<Global>,
+ d: Resource<Debuggee>,
+ ) -> Result<Resource<WasmValue>> {
+ // N.B.: we use UFCS here because `HostGlobal::get` conflicts
+ // with `ResourceTable::get` and we're implementing the WIT
+ // trait directly on the `ResourceTable`.
+ let global = *ResourceTable::get(self, &self_)?;
+ let d = debugger(self, &d)?;
+ let value = d.global_get(global).await?;
+ Ok(self.push(value)?)
+ }
+
+ async fn set(
+ &mut self,
+ self_: Resource<Global>,
+ d: Resource<Debuggee>,
+ val: Resource<WasmValue>,
+ ) -> Result<()> {
+ let global = *ResourceTable::get(self, &self_)?;
+ let value = ResourceTable::get(self, &val)?.clone();
+ let d = debugger(self, &d)?;
+ d.global_set(global, value).await
+ }
+
+ async fn clone(&mut self, self_: Resource<Global>) -> Result<Resource<Global>> {
+ let global = *ResourceTable::get(self, &self_)?;
+ Ok(self.push(global)?)
+ }
+
+ async fn unique_id(&mut self, self_: Resource<Global>) -> Result<u64> {
+ let global = *ResourceTable::get(self, &self_)?;
+ Ok(global.debug_index_in_store())
+ }
+
+ async fn drop(&mut self, rep: Resource<Global>) -> Result<()> {
+ self.delete(rep)?;
+ Ok(())
+ }
+}
+
+impl wit::HostTable for ResourceTable {
+ async fn len(&mut self, self_: Resource<Table>, d: Resource<Debuggee>) -> Result<u64> {
+ let table = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ d.table_len(table).await
+ }
+
+ async fn get_element(
+ &mut self,
+ self_: Resource<Table>,
+ d: Resource<Debuggee>,
+ index: u64,
+ ) -> Result<Resource<WasmValue>> {
+ let table = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ let value = d.table_get_element(table, index).await?;
+ Ok(self.push(value)?)
+ }
+
+ async fn set_element(
+ &mut self,
+ self_: Resource<Table>,
+ d: Resource<Debuggee>,
+ index: u64,
+ val: Resource<WasmValue>,
+ ) -> Result<()> {
+ let table = *self.get(&self_)?;
+ let value = self.get(&val)?.clone();
+ let d = debugger(self, &d)?;
+ d.table_set_element(table, index, value).await
+ }
+
+ async fn clone(&mut self, self_: Resource<Table>) -> Result<Resource<Table>> {
+ let table = *self.get(&self_)?;
+ Ok(self.push(table)?)
+ }
+
+ async fn unique_id(&mut self, self_: Resource<Table>) -> Result<u64> {
+ Ok(self.get(&self_)?.debug_index_in_store())
+ }
+
+ async fn drop(&mut self, rep: Resource<Table>) -> Result<()> {
+ self.delete(rep)?;
+ Ok(())
+ }
+}
+
+impl wit::HostWasmFunc for ResourceTable {
+ async fn params(
+ &mut self,
+ self_: Resource<Func>,
+ d: Resource<Debuggee>,
+ ) -> Result<Vec<wit::WasmType>> {
+ let func = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ d.func_params(func).await
+ }
+
+ async fn results(
+ &mut self,
+ self_: Resource<Func>,
+ d: Resource<Debuggee>,
+ ) -> Result<Vec<wit::WasmType>> {
+ let func = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ d.func_results(func).await
+ }
+
+ async fn clone(&mut self, self_: Resource<Func>) -> Result<Resource<Func>> {
+ let func = *self.get(&self_)?;
+ Ok(self.push(func)?)
+ }
+
+ async fn drop(&mut self, rep: Resource<Func>) -> Result<()> {
+ self.delete(rep)?;
+ Ok(())
+ }
+}
+
+impl wit::HostWasmException for ResourceTable {
+ async fn get_tag(
+ &mut self,
+ self_: Resource<WasmException>,
+ d: Resource<Debuggee>,
+ ) -> Result<Resource<Tag>> {
+ let exn = self.get(&self_)?.clone();
+ let d = debugger(self, &d)?;
+ let tag = d.exnref_get_tag(exn.0).await?;
+ Ok(self.push(tag)?)
+ }
+
+ async fn get_values(
+ &mut self,
+ self_: Resource<WasmException>,
+ d: Resource<Debuggee>,
+ ) -> Result<Vec<Resource<WasmValue>>> {
+ let exn = self.get(&self_)?.clone();
+ let d = debugger(self, &d)?;
+ let values = d.exnref_get_fields(exn.0).await?;
+ let mut resources = vec![];
+ for v in values {
+ resources.push(self.push(v)?);
+ }
+ Ok(resources)
+ }
+
+ async fn clone(
+ &mut self,
+ self_: Resource<WasmException>,
+ _d: Resource<Debuggee>,
+ ) -> Result<Resource<WasmException>> {
+ let exn = self.get(&self_)?.clone();
+ Ok(self.push(exn)?)
+ }
+
+ async fn make(
+ &mut self,
+ d: Resource<Debuggee>,
+ tag: Resource<Tag>,
+ values: Vec<Resource<WasmValue>>,
+ ) -> Result<Resource<WasmException>> {
+ let tag_val = *self.get(&tag)?;
+ let mut wasm_values = vec![];
+ for v in &values {
+ wasm_values.push(self.get(v)?.clone());
+ }
+ let d = debugger(self, &d)?;
+ let owned = d.exnref_new(tag_val, wasm_values).await?;
+ Ok(self.push(WasmException(owned))?)
+ }
+
+ async fn drop(&mut self, rep: Resource<WasmException>) -> Result<()> {
+ self.delete(rep)?;
+ Ok(())
+ }
+}
+
+impl wit::HostWasmTag for ResourceTable {
+ async fn params(
+ &mut self,
+ self_: Resource<Tag>,
+ d: Resource<Debuggee>,
+ ) -> Result<Vec<wit::WasmType>> {
+ let tag = *self.get(&self_)?;
+ let d = debugger(self, &d)?;
+ d.tag_params(tag).await
+ }
+
+ async fn unique_id(&mut self, self_: Resource<Tag>) -> Result<u64> {
+ Ok(self.get(&self_)?.debug_index_in_store())
+ }
+
+ async fn clone(&mut self, self_: Resource<Tag>) -> Result<Resource<Tag>> {
+ let tag = *self.get(&self_)?;
+ Ok(self.push(tag)?)
+ }
+
+ async fn make(
+ &mut self,
+ d: Resource<Debuggee>,
+ params: Vec<wit::WasmType>,
+ ) -> Result<Resource<Tag>> {
+ let engine = self.get(&d)?.engine.clone();
+ let val_types = params.into_iter().map(wasm_type_to_val_type).collect();
+ let d = debugger(self, &d)?;
+ let tag = d.tag_new(engine, val_types).await?;
+ Ok(self.push(tag)?)
+ }
+
+ async fn drop(&mut self, rep: Resource<Tag>) -> Result<()> {
+ self.delete(rep)?;
+ Ok(())
+ }
+}
+
+impl wit::HostFrame for ResourceTable {
+ async fn get_instance(
+ &mut self,
+ self_: Resource<Frame>,
+ d: Resource<Debuggee>,
+ ) -> Result<Resource<Instance>> {
+ let frame = self.get(&self_)?.0.clone();
+ let d = debugger(self, &d)?;
+ let instance = d.frame_instance(frame).await?;
+ Ok(self.push(instance)?)
+ }
+
+ async fn get_func_index(
+ &mut self,
+ self_: Resource<Frame>,
+ d: Resource<Debuggee>,
+ ) -> Result<u32> {
+ let frame = self.get(&self_)?.0.clone();
+ let d = debugger(self, &d)?;
+ let (f, _) = d.frame_func_and_pc(frame).await?;
+ Ok(f)
+ }
+
+ async fn get_pc(&mut self, self_: Resource<Frame>, d: Resource<Debuggee>) -> Result<u32> {
+ let frame = self.get(&self_)?.0.clone();
+ let d = debugger(self, &d)?;
+ let (_, pc) = d.frame_func_and_pc(frame).await?;
+ Ok(pc)
+ }
+
+ async fn get_locals(
+ &mut self,
+ self_: Resource<Frame>,
+ d: Resource<Debuggee>,
+ ) -> Result<Vec<Resource<WasmValue>>> {
+ let frame = self.get(&self_)?.0.clone();
+ let d = debugger(self, &d)?;
+ let locals = d.frame_locals(frame).await?;
+ let mut resources = vec![];
+ for local in locals {
+ resources.push(self.push(local)?);
+ }
+ Ok(resources)
+ }
+
+ async fn get_stack(
+ &mut self,
+ self_: Resource<Frame>,
+ d: Resource<Debuggee>,
+ ) -> Result<Vec<Resource<WasmValue>>> {
+ let frame = self.get(&self_)?.0.clone();
+ let d = debugger(self, &d)?;
+ let stacks = d.frame_stack(frame).await?;
+ let mut resources = vec![];
+ for val in stacks {
+ resources.push(self.push(val)?);
+ }
+ Ok(resources)
+ }
+
+ async fn parent_frame(
+ &mut self,
+ self_: Resource<Frame>,
+ d: Resource<Debuggee>,
+ ) -> Result<Option<Resource<Frame>>> {
+ let frame = self.get(&self_)?.0.clone();
+ let d = debugger(self, &d)?;
+ let parent = d.frame_parent(frame).await?;
+ match parent {
+ Some(p) => Ok(Some(self.push(Frame(p))?)),
+ None => Ok(None),
+ }
+ }
+
+ async fn drop(&mut self, rep: Resource<Frame>) -> Result<()> {
+ self.delete(rep)?;
+ Ok(())
+ }
+}
+
+impl wit::HostWasmValue for ResourceTable {
+ async fn get_type(&mut self, self_: Resource<WasmValue>) -> Result<wit::WasmType> {
+ let value = self.get(&self_)?;
+ match value {
+ WasmValue::Primitive(Val::I32(_)) => Ok(wit::WasmType::WasmI32),
+ WasmValue::Primitive(Val::I64(_)) => Ok(wit::WasmType::WasmI64),
+ WasmValue::Primitive(Val::F32(_)) => Ok(wit::WasmType::WasmF32),
+ WasmValue::Primitive(Val::F64(_)) => Ok(wit::WasmType::WasmF64),
+ WasmValue::Primitive(Val::V128(_)) => Ok(wit::WasmType::WasmV128),
+ WasmValue::Func(_) => Ok(wit::WasmType::WasmFuncref),
+ WasmValue::Exn(_) => Ok(wit::WasmType::WasmExnref),
+ WasmValue::Primitive(_) => unreachable!(),
+ }
+ }
+
+ async fn unwrap_i32(&mut self, self_: Resource<WasmValue>) -> Result<u32> {
+ let value = self.get(&self_)?;
+ match value {
+ WasmValue::Primitive(Val::I32(x)) => Ok(x.cast_unsigned()),
+ _ => wasmtime::bail!("Wasm value is not an i32."),
+ }
+ }
+
+ async fn unwrap_i64(&mut self, self_: Resource<WasmValue>) -> Result<u64> {
+ let value = self.get(&self_)?;
+ match value {
+ WasmValue::Primitive(Val::I64(x)) => Ok(x.cast_unsigned()),
+ _ => wasmtime::bail!("Wasm value is not an i64."),
+ }
+ }
+
+ async fn unwrap_f32(&mut self, self_: Resource<WasmValue>) -> Result<f32> {
+ let value = self.get(&self_)?;
+ match value {
+ WasmValue::Primitive(Val::F32(x)) => Ok(f32::from_bits(*x)),
+ _ => wasmtime::bail!("Wasm value is not an f32."),
+ }
+ }
+
+ async fn unwrap_f64(&mut self, self_: Resource<WasmValue>) -> Result<f64> {
+ let value = self.get(&self_)?;
+ match value {
+ WasmValue::Primitive(Val::F64(x)) => Ok(f64::from_bits(*x)),
+ _ => wasmtime::bail!("Wasm value is not an f64."),
+ }
+ }
+
+ async fn unwrap_v128(&mut self, self_: Resource<WasmValue>) -> Result<Vec<u8>> {
+ let value = self.get(&self_)?;
+ match value {
+ WasmValue::Primitive(Val::V128(x)) => Ok(x.as_u128().to_le_bytes().to_vec()),
+ _ => wasmtime::bail!("Wasm value is not a v128."),
+ }
+ }
+
+ async fn unwrap_func(&mut self, self_: Resource<WasmValue>) -> Result<Option<Resource<Func>>> {
+ let value = self.get(&self_)?;
+ match value {
+ WasmValue::Func(Some(f)) => {
+ let f = *f;
+ Ok(Some(self.push(f)?))
+ }
+ WasmValue::Func(None) => Ok(None),
+ _ => wasmtime::bail!("Wasm value is not a funcref."),
+ }
+ }
+
+ async fn unwrap_exception(
+ &mut self,
+ self_: Resource<WasmValue>,
+ ) -> Result<Option<Resource<WasmException>>> {
+ let value = self.get(&self_)?;
+ match value {
+ WasmValue::Exn(Some(e)) => {
+ let e = e.clone();
+ Ok(Some(self.push(WasmException(e))?))
+ }
+ WasmValue::Exn(None) => Ok(None),
+ _ => wasmtime::bail!("Wasm value is not an exnref."),
+ }
+ }
+
+ async fn make_i32(&mut self, value: u32) -> Result<Resource<WasmValue>> {
+ Ok(self.push(WasmValue::Primitive(Val::I32(value.cast_signed())))?)
+ }
+
+ async fn make_i64(&mut self, value: u64) -> Result<Resource<WasmValue>> {
+ Ok(self.push(WasmValue::Primitive(Val::I64(value.cast_signed())))?)
+ }
+
+ async fn make_f32(&mut self, value: f32) -> Result<Resource<WasmValue>> {
+ Ok(self.push(WasmValue::Primitive(Val::F32(value.to_bits())))?)
+ }
+
+ async fn make_f64(&mut self, value: f64) -> Result<Resource<WasmValue>> {
+ Ok(self.push(WasmValue::Primitive(Val::F64(value.to_bits())))?)
+ }
+
+ async fn make_v128(&mut self, value: Vec<u8>) -> Result<Resource<WasmValue>> {
+ let bytes: [u8; 16] = value
+ .try_into()
+ .map_err(|_| wasmtime::format_err!("v128 requires exactly 16 bytes"))?;
+ Ok(self.push(WasmValue::Primitive(Val::V128(
+ u128::from_le_bytes(bytes).into(),
+ )))?)
+ }
+
+ async fn clone(&mut self, self_: Resource<WasmValue>) -> Result<Resource<WasmValue>> {
+ let value = self.get(&self_)?.clone();
+ Ok(self.push(value)?)
+ }
+
+ async fn drop(&mut self, rep: Resource<WasmValue>) -> Result<()> {
+ self.delete(rep)?;
+ Ok(())
+ }
+}
+
+impl wit::Host for ResourceTable {
+ fn convert_error(&mut self, err: wasmtime::Error) -> Result<wit::Error> {
+ err.downcast()
+ }
+}
diff --git a/crates/debugger/src/host/bindings.rs b/crates/debugger/src/host/bindings.rs
new file mode 100644
index 0000000000..fbf698bf28
--- /dev/null
+++ b/crates/debugger/src/host/bindings.rs
@@ -0,0 +1,65 @@
+//! wit-bindgen-generated host binding types.
+
+use wasmtime::{Result, ValType};
+
+wasmtime::component::bindgen!({
+ path: "wit",
+ world: "bytecodealliance:wasmtime/debug-main",
+ imports: {
+ // Everything is async, even the seemingly simple things
+ // like unwrapping a Wasm value, because we need to access
+ // the Store in many places and that is an async access
+ // via channels within the debuggee.
+ default: async | trappable
+ },
+ exports: {
+ default: async,
+ },
+ with: {
+ "bytecodealliance:wasmtime/debuggee.debuggee": super::api::Debuggee,
+ "bytecodealliance:wasmtime/debuggee.event-future": super::api::EventFuture,
+ "bytecodealliance:wasmtime/debuggee.frame": super::api::Frame,
+ "bytecodealliance:wasmtime/debuggee.instance": wasmtime::Instance,
+ "bytecodealliance:wasmtime/debuggee.module": wasmtime::Module,
+ "bytecodealliance:wasmtime/debuggee.table": wasmtime::Table,
+ "bytecodealliance:wasmtime/debuggee.global": wasmtime::Global,
+ "bytecodealliance:wasmtime/debuggee.memory": wasmtime::Memory,
+ "bytecodealliance:wasmtime/debuggee.wasm-tag": wasmtime::Tag,
+ "bytecodealliance:wasmtime/debuggee.wasm-func": wasmtime::Func,
+ "bytecodealliance:wasmtime/debuggee.wasm-exception": super::api::WasmException,
+ "bytecodealliance:wasmtime/debuggee.wasm-value": super::api::WasmValue,
+
+ "wasi": wasmtime_wasi::p2::bindings,
+ },
+ trappable_error_type: {
+ "bytecodealliance:wasmtime/debuggee.error" => wasmtime::Error,
+ },
+ require_store_data_send: true,
+});
+
+use bytecodealliance::wasmtime::debuggee as wit;
+
+pub(crate) fn val_type_to_wasm_type(vt: &ValType) -> Result<wit::WasmType> {
+ match vt {
+ ValType::I32 => Ok(wit::WasmType::WasmI32),
+ ValType::I64 => Ok(wit::WasmType::WasmI64),
+ ValType::F32 => Ok(wit::WasmType::WasmF32),
+ ValType::F64 => Ok(wit::WasmType::WasmF64),
+ ValType::V128 => Ok(wit::WasmType::WasmV128),
+ ValType::Ref(rt) if rt.heap_type().is_exn() => Ok(wit::WasmType::WasmExnref),
+ ValType::Ref(rt) if rt.heap_type().is_func() => Ok(wit::WasmType::WasmFuncref),
+ ValType::Ref(_) => Err(wit::Error::UnsupportedType.into()),
+ }
+}
+
+pub(crate) fn wasm_type_to_val_type(wt: wit::WasmType) -> ValType {
+ match wt {
+ wit::WasmType::WasmI32 => ValType::I32,
+ wit::WasmType::WasmI64 => ValType::I64,
+ wit::WasmType::WasmF32 => ValType::F32,
+ wit::WasmType::WasmF64 => ValType::F64,
+ wit::WasmType::WasmV128 => ValType::V128,
+ wit::WasmType::WasmFuncref => ValType::FUNCREF,
+ wit::WasmType::WasmExnref => ValType::EXNREF,
+ }
+}
diff --git a/crates/debugger/src/host/opaque.rs b/crates/debugger/src/host/opaque.rs
new file mode 100644
index 0000000000..2c4d0013a4
--- /dev/null
+++ b/crates/debugger/src/host/opaque.rs
@@ -0,0 +1,582 @@
+//! A type-erased trait wrapping the `Debugger<T>` to permit its use
+//! within a resource.
+
+use crate::host::wit;
+use crate::host::{api::WasmValue, bindings::val_type_to_wasm_type};
+use wasmtime::{
+ Engine, ExnRef, ExnRefPre, ExnType, FrameHandle, Func, FuncType, Global, Instance, Memory,
+ Module, OwnedRooted, Result, Table, Tag, TagType, Val, ValType,
+};
+
+/// Type-erased interface to the `Debugger<T>` implementing all
+/// functionality necessary for the interfaces here. This needs to be
+/// type-erased because the host-side resource APIs do not support
+/// type-parameterized resource kinds -- e.g., we cannot have a
+/// resource for a `Debugger<T>`, only a `Debugger`, so the debuggee
+/// resource essentially needs to carry a vtable for the kind of store
+/// the debuggee has.
+///
+/// Methods here return `wasmtime::Result<T>`, where `Err` may wrap
+/// either a `wit::Error` (which `convert_error` will extract and
+/// return as an in-band WIT-level error to the component) or any
+/// other error (which becomes a trap).
+///
+/// These methods do not handle the "wrong state" errors (i.e.,
+/// execution is continuing so we cannot query store state): those are
+/// handled one level up, via moving ownership of the instance of this
+/// trait between the execution future and the debuggee resource
+/// itself.
+#[async_trait::async_trait]
+pub(crate) trait OpaqueDebugger {
+ async fn all_instances(&mut self) -> Result<Vec<Instance>>;
+ async fn all_modules(&mut self) -> Result<Vec<Module>>;
+ async fn handle_resumption(&mut self, resumption: &wit::ResumptionValue) -> Result<()>;
+ async fn single_step(&mut self) -> Result<crate::DebugRunResult>;
+ async fn continue_(&mut self) -> Result<crate::DebugRunResult>;
+ async fn exit_frames(&mut self) -> Result<Vec<FrameHandle>>;
+ async fn get_instance_module(&mut self, instance: Instance) -> Result<Module>;
+
+ async fn instance_get_memory(&mut self, instance: Instance, idx: u32)
+ -> Result<Option<Memory>>;
+ async fn instance_get_global(&mut self, instance: Instance, idx: u32)
+ -> Result<Option<Global>>;
+ async fn instance_get_table(&mut self, instance: Instance, idx: u32) -> Result<Option<Table>>;
+ async fn instance_get_func(&mut self, instance: Instance, idx: u32) -> Result<Option<Func>>;
+ async fn instance_get_tag(&mut self, instance: Instance, idx: u32) -> Result<Option<Tag>>;
+
+ async fn memory_size_bytes(&mut self, memory: Memory) -> Result<u64>;
+ async fn memory_page_size(&mut self, memory: Memory) -> Result<u64>;
+ async fn memory_grow(&mut self, memory: Memory, delta_bytes: u64) -> Result<u64>;
+ async fn memory_read_bytes(
+ &mut self,
+ memory: Memory,
+ addr: u64,
+ len: u64,
+ ) -> Result<Option<Vec<u8>>>;
+ async fn memory_write_bytes(
+ &mut self,
+ memory: Memory,
+ addr: u64,
+ bytes: Vec<u8>,
+ ) -> Result<Option<()>>;
+ async fn memory_read_u8(&mut self, memory: Memory, addr: u64) -> Result<Option<u8>>;
+ async fn memory_read_u16(&mut self, memory: Memory, addr: u64) -> Result<Option<u16>>;
+ async fn memory_read_u32(&mut self, memory: Memory, addr: u64) -> Result<Option<u32>>;
+ async fn memory_read_u64(&mut self, memory: Memory, addr: u64) -> Result<Option<u64>>;
+ async fn memory_write_u8(&mut self, memory: Memory, addr: u64, data: u8) -> Result<Option<()>>;
+ async fn memory_write_u16(
+ &mut self,
+ memory: Memory,
+ addr: u64,
+ data: u16,
+ ) -> Result<Option<()>>;
+ async fn memory_write_u32(
+ &mut self,
+ memory: Memory,
+ addr: u64,
+ data: u32,
+ ) -> Result<Option<()>>;
+ async fn memory_write_u64(
+ &mut self,
+ memory: Memory,
+ addr: u64,
+ data: u64,
+ ) -> Result<Option<()>>;
+
+ async fn global_get(&mut self, global: Global) -> Result<WasmValue>;
+ async fn global_set(&mut self, global: Global, val: WasmValue) -> Result<()>;
+
+ async fn table_len(&mut self, table: Table) -> Result<u64>;
+ async fn table_get_element(&mut self, table: Table, index: u64) -> Result<WasmValue>;
+ async fn table_set_element(&mut self, table: Table, index: u64, val: WasmValue) -> Result<()>;
+
+ async fn func_params(&mut self, func: Func) -> Result<Vec<wit::WasmType>>;
+ async fn func_results(&mut self, func: Func) -> Result<Vec<wit::WasmType>>;
+
+ async fn tag_params(&mut self, tag: Tag) -> Result<Vec<wit::WasmType>>;
+ async fn tag_new(&mut self, engine: Engine, params: Vec<ValType>) -> Result<Tag>;
+
+ async fn exnref_get_tag(&mut self, exn: OwnedRooted<ExnRef>) -> Result<Tag>;
+ async fn exnref_get_fields(&mut self, exn: OwnedRooted<ExnRef>) -> Result<Vec<WasmValue>>;
+ async fn exnref_new(&mut self, tag: Tag, fields: Vec<WasmValue>)
+ -> Result<OwnedRooted<ExnRef>>;
+
+ async fn frame_instance(&mut self, frame: FrameHandle) -> Result<Instance>;
+ async fn frame_func_and_pc(&mut self, frame: FrameHandle) -> Result<(u32, u32)>;
+ async fn frame_locals(&mut self, frame: FrameHandle) -> Result<Vec<WasmValue>>;
+ async fn frame_stack(&mut self, frame: FrameHandle) -> Result<Vec<WasmValue>>;
+ async fn frame_parent(&mut self, frame: FrameHandle) -> Result<Option<FrameHandle>>;
+
+ async fn module_add_breakpoint(&mut self, module: Module, pc: u32) -> Result<()>;
+ async fn module_remove_breakpoint(&mut self, module: Module, pc: u32) -> Result<()>;
+
+ async fn finish(&mut self) -> Result<()>;
+}
+
+#[async_trait::async_trait]
+impl<T: Send + 'static> OpaqueDebugger for crate::Debuggee<T> {
+ async fn all_instances(&mut self) -> Result<Vec<Instance>> {
+ self.with_store(|store| store.debug_all_instances()).await
+ }
+
+ async fn all_modules(&mut self) -> Result<Vec<Module>> {
+ self.with_store(|store| store.debug_all_modules()).await
+ }
+
+ async fn single_step(&mut self) -> Result<crate::DebugRunResult> {
+ self.with_store(|store| store.edit_breakpoints().unwrap().single_step(true).unwrap())
+ .await?;
+
+ self.run().await
+ }
+
+ async fn continue_(&mut self) -> Result<crate::DebugRunResult> {
+ self.with_store(|store| {
+ store
+ .edit_breakpoints()
+ .unwrap()
+ .single_step(false)
+ .unwrap()
+ })
+ .await?;
+
+ self.run().await
+ }
+
+ async fn handle_resumption(&mut self, resumption: &wit::ResumptionValue) -> Result<()> {
+ match resumption {
+ wit::ResumptionValue::Normal => {}
+ _ => {
+ unimplemented!("Non-`Normal` resumption not yet supported");
+ }
+ }
+ Ok(())
+ }
+
+ async fn exit_frames(&mut self) -> Result<Vec<FrameHandle>> {
+ self.with_store(|mut store| store.debug_exit_frames().collect::<Vec<_>>())
+ .await
+ }
+
+ async fn get_instance_module(&mut self, instance: Instance) -> Result<Module> {
+ self.with_store(move |store| instance.module(&store).clone())
+ .await
+ }
+
+ async fn instance_get_memory(
+ &mut self,
+ instance: Instance,
+ idx: u32,
+ ) -> Result<Option<Memory>> {
+ self.with_store(move |mut store| instance.debug_memory(&mut store, idx))
+ .await
+ }
+
+ async fn instance_get_global(
+ &mut self,
+ instance: Instance,
+ idx: u32,
+ ) -> Result<Option<Global>> {
+ self.with_store(move |mut store| instance.debug_global(&mut store, idx))
+ .await
+ }
+
+ async fn instance_get_table(&mut self, instance: Instance, idx: u32) -> Result<Option<Table>> {
+ self.with_store(move |mut store| instance.debug_table(&mut store, idx))
+ .await
+ }
+
+ async fn instance_get_func(&mut self, instance: Instance, idx: u32) -> Result<Option<Func>> {
+ self.with_store(move |mut store| instance.debug_function(&mut store, idx))
+ .await
+ }
+
+ async fn instance_get_tag(&mut self, instance: Instance, idx: u32) -> Result<Option<Tag>> {
+ self.with_store(move |mut store| instance.debug_tag(&mut store, idx))
+ .await
+ }
+
+ async fn memory_size_bytes(&mut self, memory: Memory) -> Result<u64> {
+ self.with_store(move |store| u64::try_from(memory.data_size(&store)).unwrap())
+ .await
+ }
+
+ async fn memory_page_size(&mut self, memory: Memory) -> Result<u64> {
+ self.with_store(move |store| memory.page_size(&store)).await
+ }
+
+ async fn memory_grow(&mut self, memory: Memory, delta_bytes: u64) -> Result<u64> {
+ self.with_store(move |mut store| -> Result<u64> {
+ let page_size = memory.page_size(&store);
+ if delta_bytes & (page_size - 1) != 0 {
+ return Err(wit::Error::MemoryGrowFailure.into());
+ }
+ let delta_pages = delta_bytes / page_size;
+ let old_pages = memory
+ .grow(&mut store, delta_pages)
+ .map_err(|_| wit::Error::MemoryGrowFailure)?;
+ Ok(old_pages * page_size)
+ })
+ .await?
+ }
+
+ async fn memory_read_bytes(
+ &mut self,
+ memory: Memory,
+ addr: u64,
+ len: u64,
+ ) -> Result<Option<Vec<u8>>> {
+ self.with_store(move |store| {
+ let data = memory.data(&store);
+ let addr = usize::try_from(addr).unwrap();
+ let len = usize::try_from(len).unwrap();
+ data.get(addr..addr + len).map(|s| s.to_vec())
+ })
+ .await
+ }
+
+ async fn memory_write_bytes(
+ &mut self,
+ memory: Memory,
+ addr: u64,
+ bytes: Vec<u8>,
+ ) -> Result<Option<()>> {
+ self.with_store(move |mut store| {
+ let data = memory.data_mut(&mut store);
+ let addr = usize::try_from(addr).unwrap();
+ let dest = data.get_mut(addr..addr + bytes.len())?;
+ dest.copy_from_slice(&bytes);
+ Some(())
+ })
+ .await
+ }
+
+ async fn memory_read_u8(&mut self, memory: Memory, addr: u64) -> Result<Option<u8>> {
+ self.with_store(move |store| {
+ let data = memory.data(&store);
+ let addr = usize::try_from(addr).unwrap();
+ Some(*data.get(addr)?)
+ })
+ .await
+ }
+
+ async fn memory_read_u16(&mut self, memory: Memory, addr: u64) -> Result<Option<u16>> {
+ self.with_store(move |store| {
+ let data = memory.data(&store);
+ let addr = usize::try_from(addr).unwrap();
+ Some(u16::from_le_bytes([*data.get(addr)?, *data.get(addr + 1)?]))
+ })
+ .await
+ }
+
+ async fn memory_read_u32(&mut self, memory: Memory, addr: u64) -> Result<Option<u32>> {
+ self.with_store(move |store| {
+ let data = memory.data(&store);
+ let addr = usize::try_from(addr).unwrap();
+ Some(u32::from_le_bytes([
+ *data.get(addr)?,
+ *data.get(addr + 1)?,
+ *data.get(addr + 2)?,
+ *data.get(addr + 3)?,
+ ]))
+ })
+ .await
+ }
+
+ async fn memory_read_u64(&mut self, memory: Memory, addr: u64) -> Result<Option<u64>> {
+ self.with_store(move |store| {
+ let data = memory.data(&store);
+ let addr = usize::try_from(addr).unwrap();
+ Some(u64::from_le_bytes([
+ *data.get(addr)?,
+ *data.get(addr + 1)?,
+ *data.get(addr + 2)?,
+ *data.get(addr + 3)?,
+ *data.get(addr + 4)?,
+ *data.get(addr + 5)?,
+ *data.get(addr + 6)?,
+ *data.get(addr + 7)?,
+ ]))
+ })
+ .await
+ }
+
+ async fn memory_write_u8(
+ &mut self,
+ memory: Memory,
+ addr: u64,
+ value: u8,
+ ) -> Result<Option<()>> {
+ self.with_store(move |mut store| {
+ let data = memory.data_mut(&mut store);
+ let addr = usize::try_from(addr).unwrap();
+ *data.get_mut(addr)? = value;
+ Some(())
+ })
+ .await
+ }
+
+ async fn memory_write_u16(
+ &mut self,
+ memory: Memory,
+ addr: u64,
+ value: u16,
+ ) -> Result<Option<()>> {
+ self.with_store(move |mut store| {
+ let data = memory.data_mut(&mut store);
+ let addr = usize::try_from(addr).unwrap();
+ data.get_mut(addr..(addr + 2))?
+ .copy_from_slice(&value.to_le_bytes());
+ Some(())
+ })
+ .await
+ }
+
+ async fn memory_write_u32(
+ &mut self,
+ memory: Memory,
+ addr: u64,
+ value: u32,
+ ) -> Result<Option<()>> {
+ self.with_store(move |mut store| {
+ let data = memory.data_mut(&mut store);
+ let addr = usize::try_from(addr).unwrap();
+ data.get_mut(addr..(addr + 4))?
+ .copy_from_slice(&value.to_le_bytes());
+ Some(())
+ })
+ .await
+ }
+
+ async fn memory_write_u64(
+ &mut self,
+ memory: Memory,
+ addr: u64,
+ value: u64,
+ ) -> Result<Option<()>> {
+ self.with_store(move |mut store| {
+ let data = memory.data_mut(&mut store);
+ let addr = usize::try_from(addr).unwrap();
+ data.get_mut(addr..(addr + 8))?
+ .copy_from_slice(&value.to_le_bytes());
+ Some(())
+ })
+ .await
+ }
+
+ async fn global_get(&mut self, global: Global) -> Result<WasmValue> {
+ self.with_store(move |mut store| {
+ let val = global.get(&mut store);
+ WasmValue::new(&mut store, val)
+ })
+ .await?
+ }
+
+ async fn global_set(&mut self, global: Global, val: WasmValue) -> Result<()> {
+ self.with_store(move |mut store| -> Result<()> {
+ let v = val.into_val(&mut store);
+ global
+ .set(&mut store, v)
+ .map_err(|_| wit::Error::MismatchedType)?;
+ Ok(())
+ })
+ .await?
+ }
+
+ async fn table_len(&mut self, table: Table) -> Result<u64> {
+ self.with_store(move |store| table.size(&store)).await
+ }
+
+ async fn table_get_element(&mut self, table: Table, index: u64) -> Result<WasmValue> {
+ self.with_store(move |mut store| -> Result<WasmValue> {
+ let val = table
+ .get(&mut store, index)
+ .ok_or(wit::Error::OutOfBounds)?;
+ WasmValue::new(&mut store, val.into())
+ })
+ .await?
+ }
+
+ async fn table_set_element(&mut self, table: Table, index: u64, val: WasmValue) -> Result<()> {
+ self.with_store(move |mut store| -> Result<()> {
+ let v = val.into_val(&mut store);
+ let r = v.ref_().ok_or(wit::Error::MismatchedType)?;
+ table
+ .set(&mut store, index, r)
+ .map_err(|_| wit::Error::MismatchedType)?;
+ Ok(())
+ })
+ .await?
+ }
+
+ async fn func_params(&mut self, func: Func) -> Result<Vec<wit::WasmType>> {
+ self.with_store(move |store| {
+ let ty = func.ty(&store);
+ ty.params()
+ .map(|ty| val_type_to_wasm_type(&ty))
+ .collect::<Result<Vec<_>>>()
+ })
+ .await?
+ }
+
+ async fn func_results(&mut self, func: Func) -> Result<Vec<wit::WasmType>> {
+ self.with_store(move |store| {
+ let ty = func.ty(&store);
+ ty.results()
+ .map(|ty| val_type_to_wasm_type(&ty))
+ .collect::<Result<Vec<_>>>()
+ })
+ .await?
+ }
+
+ async fn tag_params(&mut self, tag: Tag) -> Result<Vec<wit::WasmType>> {
+ self.with_store(move |store| {
+ let ty = tag.ty(&store);
+ ty.ty()
+ .params()
+ .map(|ty| val_type_to_wasm_type(&ty))
+ .collect::<Result<Vec<_>>>()
+ })
+ .await?
+ }
+
+ async fn tag_new(&mut self, engine: Engine, params: Vec<ValType>) -> Result<Tag> {
+ self.with_store(move |mut store| {
+ let func_ty = FuncType::new(&engine, params, []);
+ let tag_ty = TagType::new(func_ty);
+ Tag::new(&mut store, &tag_ty)
+ })
+ .await?
+ }
+
+ async fn exnref_get_tag(&mut self, exn: OwnedRooted<ExnRef>) -> Result<Tag> {
+ self.with_store(move |mut store| exn.tag(&mut store).expect("reference must be rooted"))
+ .await
+ }
+
+ async fn exnref_get_fields(&mut self, exn: OwnedRooted<ExnRef>) -> Result<Vec<WasmValue>> {
+ self.with_store(move |mut store| {
+ let fields = exn
+ .fields(&mut store)
+ .expect("reference must be rooted")
+ .collect::<Vec<Val>>();
+ fields
+ .into_iter()
+ .map(|v| WasmValue::new(&mut store, v))
+ .collect::<Result<Vec<_>>>()
+ })
+ .await?
+ }
+
+ async fn exnref_new(
+ &mut self,
+ tag: Tag,
+ fields: Vec<WasmValue>,
+ ) -> Result<OwnedRooted<ExnRef>> {
+ self.with_store(move |mut store| -> Result<OwnedRooted<ExnRef>> {
+ let exn_ty =
+ ExnType::from_tag_type(&tag.ty(&store)).expect("tag type is already validated");
+ let allocator = ExnRefPre::new(&mut store, exn_ty);
+ let field_vals = fields
+ .into_iter()
+ .map(|v| v.into_val(&mut store))
+ .collect::<Vec<_>>();
+ let exn = ExnRef::new(&mut store, &allocator, &tag, &field_vals)
+ .map_err(|_| wit::Error::AllocFailure)?;
+ Ok(exn.to_owned_rooted(&mut store).unwrap())
+ })
+ .await?
+ }
+
+ async fn frame_instance(&mut self, frame: FrameHandle) -> Result<Instance> {
+ self.with_store(move |mut store| -> Result<Instance> {
+ Ok(frame
+ .instance(&mut store)
+ .map_err(|_| wit::Error::InvalidFrame)?)
+ })
+ .await?
+ }
+
+ async fn frame_func_and_pc(&mut self, frame: FrameHandle) -> Result<(u32, u32)> {
+ self.with_store(move |mut store| -> Result<(u32, u32)> {
+ let (func, pc) = frame
+ .wasm_function_index_and_pc(&mut store)
+ .map_err(|_| wit::Error::InvalidFrame)?
+ .ok_or(wit::Error::NonWasmFrame)?;
+ Ok((func.as_u32(), pc))
+ })
+ .await?
+ }
+
+ async fn frame_locals(&mut self, frame: FrameHandle) -> Result<Vec<WasmValue>> {
+ self.with_store(move |mut store| -> Result<Vec<WasmValue>> {
+ let n_locals = frame
+ .num_locals(&mut store)
+ .map_err(|_| wit::Error::InvalidFrame)?;
+ let mut result = vec![];
+ for i in 0..n_locals {
+ let val = frame
+ .local(&mut store, i)
+ .expect("checked for validity above");
+ result.push(WasmValue::new(&mut store, val)?);
+ }
+ Ok(result)
+ })
+ .await?
+ }
+
+ async fn frame_stack(&mut self, frame: FrameHandle) -> Result<Vec<WasmValue>> {
+ self.with_store(move |mut store| -> Result<Vec<WasmValue>> {
+ let n_stacks = frame
+ .num_stacks(&mut store)
+ .map_err(|_| wit::Error::InvalidFrame)?;
+ let mut result = vec![];
+ for i in 0..n_stacks {
+ let val = frame
+ .stack(&mut store, i)
+ .expect("checked for validity above");
+ result.push(WasmValue::new(&mut store, val)?);
+ }
+ Ok(result)
+ })
+ .await?
+ }
+
+ async fn frame_parent(&mut self, frame: FrameHandle) -> Result<Option<FrameHandle>> {
+ self.with_store(move |mut store| -> Result<Option<FrameHandle>> {
+ Ok(frame
+ .parent(&mut store)
+ .map_err(|_| wit::Error::InvalidFrame)?)
+ })
+ .await?
+ }
+
+ async fn module_add_breakpoint(&mut self, module: Module, pc: u32) -> Result<()> {
+ self.with_store(move |store| -> Result<()> {
+ store
+ .edit_breakpoints()
+ .expect("guest debugging is enabled")
+ .add_breakpoint(&module, pc)
+ .map_err(|_| wit::Error::InvalidPc)?;
+ Ok(())
+ })
+ .await?
+ }
+
+ async fn module_remove_breakpoint(&mut self, module: Module, pc: u32) -> Result<()> {
+ self.with_store(move |store| -> Result<()> {
+ store
+ .edit_breakpoints()
+ .expect("guest debugging is enabled")
+ .remove_breakpoint(&module, pc)
+ .map_err(|_| wit::Error::InvalidPc)?;
+ Ok(())
+ })
+ .await?
+ }
+
+ async fn finish(&mut self) -> Result<()> {
+ self.finish().await?;
+ Ok(())
+ }
+}
diff --git a/crates/debugger/src/lib.rs b/crates/debugger/src/lib.rs
index 92ec2ce7f2..51743d9524 100644
--- a/crates/debugger/src/lib.rs
+++ b/crates/debugger/src/lib.rs
@@ -9,14 +9,28 @@
//! In the future, this crate will also provide a WIT-level API and
//! world in which to run debugger components.
-use std::{any::Any, future::Future, pin::Pin, sync::Arc};
-use tokio::sync::{Mutex, mpsc};
+use std::{
+ any::Any,
+ future::Future,
+ pin::Pin,
+ sync::{
+ Arc,
+ atomic::{AtomicBool, Ordering},
+ },
+};
+use tokio::{
+ sync::{Mutex, mpsc},
+ task::JoinHandle,
+};
use wasmtime::{
AsContextMut, DebugEvent, DebugHandler, Engine, ExnRef, OwnedRooted, Result, Store,
StoreContextMut, Trap,
};
-/// A `Debugger` wraps up state associated with debugging the code
+mod host;
+pub use host::{DebuggerComponent, add_debuggee, add_to_linker, wit};
+
+/// A `Debuggee` wraps up state associated with debugging the code
/// running in a single `Store`.
///
/// It acts as a Future combinator, wrapping an inner async body that
@@ -26,24 +40,32 @@ use wasmtime::{
/// states: running or paused. When paused, it acts as a
/// `StoreContextMut` and can allow examining the paused execution's
/// state. One runs until the next event suspends execution by
-/// invoking `Debugger::run`.
-pub struct Debugger<T: Send + 'static> {
+/// invoking `Debuggee::run`.
+pub struct Debuggee<T: Send + 'static> {
/// A handle to the Engine that the debuggee store lives within.
engine: Engine,
/// State: either a task handle or the store when passed out of
/// the complete task.
- state: DebuggerState,
+ state: DebuggeeState,
/// The store, once complete.
store: Option<Store<T>>,
in_tx: mpsc::Sender<Command<T>>,
out_rx: mpsc::Receiver<Response<T>>,
+ handle: Option<JoinHandle<Result<()>>>,
+ /// Flag shared with the inner handler: set to `true` by
+ /// `interrupt()` so the next epoch yield is surfaced as an
+ /// `Interrupted` event rather than eaten by the handler. Epoch
+ /// yields serve two purposes, namely ensuring regular yields to
+ /// the event loop and enacting an explicit interrupt, and this
+ /// flag distinguishes those cases.
+ interrupt_pending: Arc<AtomicBool>,
}
/// State machine from the perspective of the outer logic.
///
/// The intermediate states here, and the separation of these states
/// from the `JoinHandle` above, are what allow us to implement a
-/// cancel-safe version of `Debugger::run` below.
+/// cancel-safe version of `Debuggee::run` below.
///
/// The state diagram for the outer logic is:
///
@@ -73,7 +95,7 @@ pub struct Debugger<T: Send + 'static> {
/// `---<-'
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-enum DebuggerState {
+enum DebuggeeState {
/// Inner body has just been started.
Initial,
/// Inner body is running in an async task and not in a debugger
@@ -138,6 +160,7 @@ enum Response<T: 'static> {
struct HandlerInner<T: Send + 'static> {
in_rx: Mutex<mpsc::Receiver<Command<T>>>,
out_tx: mpsc::Sender<Response<T>>,
+ interrupt_pending: Arc<AtomicBool>,
}
struct Handler<T: Send + 'static>(Arc<HandlerInner<T>>);
@@ -161,23 +184,39 @@ impl<T: Send + 'static> DebugHandler for Handler<T> {
}
DebugEvent::Trap(trap) => DebugRunResult::Trap(trap),
DebugEvent::Breakpoint => DebugRunResult::Breakpoint,
- DebugEvent::EpochYield => DebugRunResult::EpochYield,
+ DebugEvent::EpochYield => {
+ // Only pause on epoch yields that were requested via
+ // interrupt(). Other epoch ticks simply yield to the
+ // event loop (funcionality already implemented in
+ // core Wasmtime; no need to do that yield here in the
+ // debug handler).
+ if !self.0.interrupt_pending.swap(false, Ordering::SeqCst) {
+ return;
+ }
+ DebugRunResult::EpochYield
+ }
};
- self.0
- .out_tx
- .send(Response::Paused(result))
- .await
- .expect("outbound channel closed prematurely");
+ if self.0.out_tx.send(Response::Paused(result)).await.is_err() {
+ // Outer Debuggee has been dropped: just continue
+ // executing.
+ return;
+ }
while let Some(cmd) = in_rx.recv().await {
match cmd {
Command::Query(closure) => {
let result = closure(store.as_context_mut());
- self.0
+ if self
+ .0
.out_tx
.send(Response::QueryResponse(result))
.await
- .expect("outbound channel closed prematurely");
+ .is_err()
+ {
+ // Outer Debuggee has been dropped: just
+ // continue executing.
+ return;
+ }
}
Command::Continue => {
break;
@@ -187,7 +226,7 @@ impl<T: Send + 'static> DebugHandler for Handler<T> {
}
}
-impl<T: Send + 'static> Debugger<T> {
+impl<T: Send + 'static> Debuggee<T> {
/// Create a new Debugger that attaches to the given Store and
/// runs the given inner body.
///
@@ -195,14 +234,14 @@ impl<T: Send + 'static> Debugger<T> {
/// paused.
///
/// When paused, the holder of this object can invoke
- /// `Debugger::run` to enter the running state. The inner body
+ /// `Debuggee::run` to enter the running state. The inner body
/// will run until paused by a debug event. While running, the
- /// future returned by either of these methods owns the `Debugger`
+ /// future returned by either of these methods owns the `Debuggee`
/// and hence no other methods can be invoked.
///
/// When paused, the holder of this object can access the `Store`
/// indirectly by providing a closure
- pub fn new<F>(mut store: Store<T>, inner: F) -> Debugger<T>
+ pub fn new<F>(mut store: Store<T>, inner: F) -> Debuggee<T>
where
F: for<'a> FnOnce(
&'a mut Store<T>,
@@ -213,45 +252,52 @@ impl<T: Send + 'static> Debugger<T> {
let engine = store.engine().clone();
let (in_tx, in_rx) = mpsc::channel(1);
let (out_tx, out_rx) = mpsc::channel(1);
-
- tokio::spawn(async move {
- // Create the handler that's invoked from within the async
- // debug-event callback.
- let out_tx_clone = out_tx.clone();
- let handler = Handler(Arc::new(HandlerInner {
- in_rx: Mutex::new(in_rx),
- out_tx,
- }));
-
- // Emulate a breakpoint at startup.
- log::trace!("inner debuggee task: first breakpoint");
- handler
- .handle(store.as_context_mut(), DebugEvent::Breakpoint)
- .await;
- log::trace!("inner debuggee task: first breakpoint resumed");
-
- // Now invoke the actual inner body.
- store.set_debug_handler(handler);
- log::trace!("inner debuggee task: running `inner`");
- let result = inner(&mut store).await;
- log::trace!("inner debuggee task: done with `inner`");
- let _ = out_tx_clone.send(Response::Finished(store)).await;
- result
+ let interrupt_pending = Arc::new(AtomicBool::new(false));
+
+ let handle = tokio::spawn({
+ let interrupt_pending = interrupt_pending.clone();
+ async move {
+ // Create the handler that's invoked from within the async
+ // debug-event callback.
+ let out_tx_clone = out_tx.clone();
+ let handler = Handler(Arc::new(HandlerInner {
+ in_rx: Mutex::new(in_rx),
+ out_tx,
+ interrupt_pending,
+ }));
+
+ // Emulate a breakpoint at startup.
+ log::trace!("inner debuggee task: first breakpoint");
+ handler
+ .handle(store.as_context_mut(), DebugEvent::Breakpoint)
+ .await;
+ log::trace!("inner debuggee task: first breakpoint resumed");
+
+ // Now invoke the actual inner body.
+ store.set_debug_handler(handler);
+ log::trace!("inner debuggee task: running `inner`");
+ let result = inner(&mut store).await;
+ log::trace!("inner debuggee task: done with `inner`");
+ let _ = out_tx_clone.send(Response::Finished(store)).await;
+ result
+ }
});
- Debugger {
+ Debuggee {
engine,
- state: DebuggerState::Initial,
+ state: DebuggeeState::Initial,
store: None,
in_tx,
out_rx,
+ interrupt_pending,
+ handle: Some(handle),
}
}
/// Is the inner body done running?
pub fn is_complete(&self) -> bool {
match self.state {
- DebuggerState::Complete => true,
+ DebuggeeState::Complete => true,
_ => false,
}
}
@@ -261,8 +307,14 @@ impl<T: Send + 'static> Debugger<T> {
&self.engine
}
+ /// Get the interrupt-pending flag. Setting this to `true` causes
+ /// the next epoch yield to surface as an `Interrupted` event.
+ pub fn interrupt_pending(&self) -> &Arc<AtomicBool> {
+ &self.interrupt_pending
+ }
+
async fn wait_for_initial(&mut self) -> Result<()> {
- if let DebuggerState::Initial = &self.state {
+ if let DebuggeeState::Initial = &self.state {
// Need to receive and discard first `Paused`.
let response = self
.out_rx
@@ -270,7 +322,7 @@ impl<T: Send + 'static> Debugger<T> {
.await
.ok_or_else(|| wasmtime::format_err!("Premature close of debugger channel"))?;
assert!(matches!(response, Response::Paused(_)));
- self.state = DebuggerState::Paused;
+ self.state = DebuggeeState::Paused;
}
Ok(())
}
@@ -284,8 +336,8 @@ impl<T: Send + 'static> Debugger<T> {
self.wait_for_initial().await?;
match self.state {
- DebuggerState::Initial => unreachable!(),
- DebuggerState::Paused => {
+ DebuggeeState::Initial => unreachable!(),
+ DebuggeeState::Paused => {
log::trace!("sending Continue");
self.in_tx
.send(Command::Continue)
@@ -297,13 +349,13 @@ impl<T: Send + 'static> Debugger<T> {
// sent, so it's fine to remain in `Paused`. If it
// succeeded and we reached here, transition to
// `Running` so we don't re-send.
- self.state = DebuggerState::Running;
+ self.state = DebuggeeState::Running;
}
- DebuggerState::Running => {
+ DebuggeeState::Running => {
// Previous `run()` must have been canceled; no action
// to take here.
}
- DebuggerState::Queried => {
+ DebuggeeState::Queried => {
// We expect to receive a `QueryResponse`; drop it if
// the query was canceled, then transition back to
// `Paused`.
@@ -314,7 +366,7 @@ impl<T: Send + 'static> Debugger<T> {
})?;
log::trace!("in Queried; received, dropping");
assert!(matches!(response, Response::QueryResponse(_)));
- self.state = DebuggerState::Paused;
+ self.state = DebuggeeState::Paused;
// Now send a `Continue`, as above.
log::trace!("in Paused; sending Continue");
@@ -322,10 +374,10 @@ impl<T: Send + 'static> Debugger<T> {
.send(Command::Continue)
.await
.map_err(|_| wasmtime::format_err!("Failed to send over debug channel"))?;
- self.state = DebuggerState::Running;
+ self.state = DebuggeeState::Running;
}
- DebuggerState::Complete => {
- panic!("Cannot `run()` an already-complete Debugger");
+ DebuggeeState::Complete => {
+ panic!("Cannot `run()` an already-complete Debuggee");
}
}
@@ -344,13 +396,13 @@ impl<T: Send + 'static> Debugger<T> {
match response {
Response::Finished(store) => {
log::trace!("got Finished");
- self.state = DebuggerState::Complete;
+ self.state = DebuggeeState::Complete;
self.store = Some(store);
Ok(DebugRunResult::Finished)
}
Response::Paused(result) => {
log::trace!("got Paused");
- self.state = DebuggerState::Paused;
+ self.state = DebuggeeState::Paused;
Ok(result)
}
Response::QueryResponse(_) => {
@@ -372,6 +424,9 @@ impl<T: Send + 'static> Debugger<T> {
}
}
}
+ if let Some(handle) = self.handle.take() {
+ handle.await??;
+ }
assert!(self.is_complete());
Ok(())
}
@@ -379,7 +434,7 @@ impl<T: Send + 'static> Debugger<T> {
/// Perform some action on the contained `Store` while not running.
///
/// This may only be invoked before the inner body finishes and
- /// when it is paused; that is, when the `Debugger` is initially
+ /// when it is paused; that is, when the `Debuggee` is initially
/// created and after any call to `run()` returns a result other
/// than `DebugRunResult::Finished`. If an earlier `run()`
/// invocation was canceled, it must be re-invoked and return
@@ -401,25 +456,25 @@ impl<T: Send + 'static> Debugger<T> {
self.wait_for_initial().await?;
match self.state {
- DebuggerState::Initial => unreachable!(),
- DebuggerState::Queried => {
+ DebuggeeState::Initial => unreachable!(),
+ DebuggeeState::Queried => {
// Earlier query canceled; drop its response first.
let response =
self.out_rx.recv().await.ok_or_else(|| {
wasmtime::format_err!("Premature close of debugger channel")
})?;
assert!(matches!(response, Response::QueryResponse(_)));
- self.state = DebuggerState::Paused;
+ self.state = DebuggeeState::Paused;
}
- DebuggerState::Running => {
+ DebuggeeState::Running => {
// Results from a canceled `run()`; `run()` must
// complete before this can be invoked.
panic!("Cannot query in Running state");
}
- DebuggerState::Complete => {
+ DebuggeeState::Complete => {
panic!("Cannot query when complete");
}
- DebuggerState::Paused => {
+ DebuggeeState::Paused => {
// OK -- this is the state we want.
}
}
@@ -429,7 +484,7 @@ impl<T: Send + 'static> Debugger<T> {
.send(Command::Query(Box::new(|store| Box::new(f(store)))))
.await
.map_err(|_| wasmtime::format_err!("Premature close of debugger channel"))?;
- self.state = DebuggerState::Queried;
+ self.state = DebuggeeState::Queried;
let response = self
.out_rx
@@ -439,13 +494,13 @@ impl<T: Send + 'static> Debugger<T> {
let Response::QueryResponse(resp) = response else {
wasmtime::bail!("Incorrect response from debugger task");
};
- self.state = DebuggerState::Paused;
+ self.state = DebuggeeState::Paused;
Ok(*resp.downcast::<R>().expect("type mismatch"))
}
}
-/// The result of one call to `Debugger::run()`.
+/// The result of one call to `Debuggee::run()`.
///
/// This is similar to `DebugEvent` but without the lifetime, so it
/// can be sent across async tasks, and incorporates the possibility
@@ -497,7 +552,7 @@ mod test {
let instance = Instance::new_async(&mut store, &module, &[]).await?;
let main = instance.get_func(&mut store, "main").unwrap();
- let mut debugger = Debugger::new(store, move |store| {
+ let mut debuggee = Debuggee::new(store, move |store| {
Box::pin(async move {
let mut results = [Val::I32(0)];
store.edit_breakpoints().unwrap().single_step(true).unwrap();
@@ -511,10 +566,10 @@ mod test {
})
});
- let event = debugger.run().await?;
+ let event = debuggee.run().await?;
assert!(matches!(event, DebugRunResult::Breakpoint));
// At (before executing) first `local.get`.
- debugger
+ debuggee
.with_store(|mut store| {
let frame = store.debug_exit_frames().next().unwrap();
assert_eq!(
@@ -543,10 +598,10 @@ mod test {
})
.await?;
- let event = debugger.run().await?;
+ let event = debuggee.run().await?;
// At second `local.get`.
assert!(matches!(event, DebugRunResult::Breakpoint));
- debugger
+ debuggee
.with_store(|mut store| {
let frame = store.debug_exit_frames().next().unwrap();
assert_eq!(
@@ -576,10 +631,10 @@ mod test {
})
.await?;
- let event = debugger.run().await?;
+ let event = debuggee.run().await?;
// At `i32.add`.
assert!(matches!(event, DebugRunResult::Breakpoint));
- debugger
+ debuggee
.with_store(|mut store| {
let frame = store.debug_exit_frames().next().unwrap();
assert_eq!(
@@ -610,10 +665,10 @@ mod test {
})
.await?;
- let event = debugger.run().await?;
+ let event = debuggee.run().await?;
// At return point.
assert!(matches!(event, DebugRunResult::Breakpoint));
- debugger
+ debuggee
.with_store(|mut store| {
let frame = store.debug_exit_frames().next().unwrap();
assert_eq!(
@@ -644,7 +699,7 @@ mod test {
.await?;
// Now disable breakpoints before continuing. Second call should proceed with no more events.
- debugger
+ debuggee
.with_store(|store| {
store
.edit_breakpoints()
@@ -654,10 +709,10 @@ mod test {
})
.await?;
- let event = debugger.run().await?;
+ let event = debuggee.run().await?;
assert!(matches!(event, DebugRunResult::Finished));
- assert!(debugger.is_complete());
+ assert!(debuggee.is_complete());
Ok(())
}
@@ -685,7 +740,7 @@ mod test {
let instance = Instance::new_async(&mut store, &module, &[]).await?;
let main = instance.get_func(&mut store, "main").unwrap();
- let mut debugger = Debugger::new(store, move |store| {
+ let mut debuggee = Debuggee::new(store, move |store| {
Box::pin(async move {
let mut results = [Val::I32(0)];
store.edit_breakpoints().unwrap().single_step(true).unwrap();
@@ -696,15 +751,15 @@ mod test {
})
});
- debugger.finish().await?;
- assert!(debugger.is_complete());
+ debuggee.finish().await?;
+ assert!(debuggee.is_complete());
Ok(())
}
#[tokio::test]
#[cfg_attr(miri, ignore)]
- async fn drop_debugger_and_store() -> Result<()> {
+ async fn drop_debuggee_and_store() -> Result<()> {
let _ = env_logger::try_init();
let mut config = Config::new();
@@ -725,7 +780,7 @@ mod test {
let instance = Instance::new_async(&mut store, &module, &[]).await?;
let main = instance.get_func(&mut store, "main").unwrap();
- let mut debugger = Debugger::new(store, move |store| {
+ let mut debuggee = Debuggee::new(store, move |store| {
Box::pin(async move {
let mut results = [Val::I32(0)];
store.edit_breakpoints().unwrap().single_step(true).unwrap();
@@ -740,7 +795,7 @@ mod test {
// function. Wasmtime's fiber cleanup should safely happen
// without attempting to raise debug async handler calls with
// missing async context.
- let _ = debugger.run().await?;
+ let _ = debuggee.run().await?;
Ok(())
}
diff --git a/crates/debugger/wit/deps/cli.wit b/crates/debugger/wit/deps/cli.wit
new file mode 100644
index 0000000000..d7a3ca4d2c
--- /dev/null
+++ b/crates/debugger/wit/deps/cli.wit
@@ -0,0 +1,261 @@
+package wasi:[email protected];
+
+@since(version = 0.2.0)
+interface environment {
+ /// Get the POSIX-style environment variables.
+ ///
+ /// Each environment variable is provided as a pair of string variable names
+ /// and string value.
+ ///
+ /// Morally, these are a value import, but until value imports are available
+ /// in the component model, this import function should return the same
+ /// values each time it is called.
+ @since(version = 0.2.0)
+ get-environment: func() -> list<tuple<string, string>>;
+
+ /// Get the POSIX-style arguments to the program.
+ @since(version = 0.2.0)
+ get-arguments: func() -> list<string>;
+
+ /// Return a path that programs should use as their initial current working
+ /// directory, interpreting `.` as shorthand for this.
+ @since(version = 0.2.0)
+ initial-cwd: func() -> option<string>;
+}
+
+@since(version = 0.2.0)
+interface exit {
+ /// Exit the current instance and any linked instances.
+ @since(version = 0.2.0)
+ exit: func(status: result);
+
+ /// Exit the current instance and any linked instances, reporting the
+ /// specified status code to the host.
+ ///
+ /// The meaning of the code depends on the context, with 0 usually meaning
+ /// "success", and other values indicating various types of failure.
+ ///
+ /// This function does not return; the effect is analogous to a trap, but
+ /// without the connotation that something bad has happened.
+ @unstable(feature = cli-exit-with-code)
+ exit-with-code: func(status-code: u8);
+}
+
+@since(version = 0.2.0)
+interface run {
+ /// Run the program.
+ @since(version = 0.2.0)
+ run: func() -> result;
+}
+
+@since(version = 0.2.0)
+interface stdin {
+ @since(version = 0.2.0)
+ use wasi:io/[email protected].{input-stream};
+
+ @since(version = 0.2.0)
+ get-stdin: func() -> input-stream;
+}
+
+@since(version = 0.2.0)
+interface stdout {
+ @since(version = 0.2.0)
+ use wasi:io/[email protected].{output-stream};
+
+ @since(version = 0.2.0)
+ get-stdout: func() -> output-stream;
+}
+
+@since(version = 0.2.0)
+interface stderr {
+ @since(version = 0.2.0)
+ use wasi:io/[email protected].{output-stream};
+
+ @since(version = 0.2.0)
+ get-stderr: func() -> output-stream;
+}
+
+/// Terminal input.
+///
+/// In the future, this may include functions for disabling echoing,
+/// disabling input buffering so that keyboard events are sent through
+/// immediately, querying supported features, and so on.
+@since(version = 0.2.0)
+interface terminal-input {
+ /// The input side of a terminal.
+ @since(version = 0.2.0)
+ resource terminal-input;
+}
+
+/// Terminal output.
+///
+/// In the future, this may include functions for querying the terminal
+/// size, being notified of terminal size changes, querying supported
+/// features, and so on.
+@since(version = 0.2.0)
+interface terminal-output {
+ /// The output side of a terminal.
+ @since(version = 0.2.0)
+ resource terminal-output;
+}
+
+/// An interface providing an optional `terminal-input` for stdin as a
+/// link-time authority.
+@since(version = 0.2.0)
+interface terminal-stdin {
+ @since(version = 0.2.0)
+ use terminal-input.{terminal-input};
+
+ /// If stdin is connected to a terminal, return a `terminal-input` handle
+ /// allowing further interaction with it.
+ @since(version = 0.2.0)
+ get-terminal-stdin: func() -> option<terminal-input>;
+}
+
+/// An interface providing an optional `terminal-output` for stdout as a
+/// link-time authority.
+@since(version = 0.2.0)
+interface terminal-stdout {
+ @since(version = 0.2.0)
+ use terminal-output.{terminal-output};
+
+ /// If stdout is connected to a terminal, return a `terminal-output` handle
+ /// allowing further interaction with it.
+ @since(version = 0.2.0)
+ get-terminal-stdout: func() -> option<terminal-output>;
+}
+
+/// An interface providing an optional `terminal-output` for stderr as a
+/// link-time authority.
+@since(version = 0.2.0)
+interface terminal-stderr {
+ @since(version = 0.2.0)
+ use terminal-output.{terminal-output};
+
+ /// If stderr is connected to a terminal, return a `terminal-output` handle
+ /// allowing further interaction with it.
+ @since(version = 0.2.0)
+ get-terminal-stderr: func() -> option<terminal-output>;
+}
+
+@since(version = 0.2.0)
+world imports {
+ @since(version = 0.2.0)
+ import environment;
+ @since(version = 0.2.0)
+ import exit;
+ @since(version = 0.2.0)
+ import wasi:io/[email protected];
+ @since(version = 0.2.0)
+ import wasi:io/[email protected];
+ @since(version = 0.2.0)
+ import wasi:io/[email protected];
+ @since(version = 0.2.0)
+ import stdin;
+ @since(version = 0.2.0)
+ import stdout;
+ @since(version = 0.2.0)
+ import stderr;
+ @since(version = 0.2.0)
+ import terminal-input;
+ @since(version = 0.2.0)
+ import terminal-output;
+ @since(version = 0.2.0)
+ import terminal-stdin;
+ @since(version = 0.2.0)
+ import terminal-stdout;
+ @since(version = 0.2.0)
+ import terminal-stderr;
+ @since(version = 0.2.0)
+ import wasi:clocks/[email protected];
+ @since(version = 0.2.0)
+ import wasi:clocks/[email protected];
+ @unstable(feature = clocks-timezone)
+ import wasi:clocks/[email protected];
+ @since(version = 0.2.0)
+ import wasi:filesystem/[email protected];
+ @since(version = 0.2.0)
+ import wasi:filesystem/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:random/[email protected];
+ @since(version = 0.2.0)
+ import wasi:random/[email protected];
+ @since(version = 0.2.0)
+ import wasi:random/[email protected];
+}
+@since(version = 0.2.0)
+world command {
+ @since(version = 0.2.0)
+ import environment;
+ @since(version = 0.2.0)
+ import exit;
+ @since(version = 0.2.0)
+ import wasi:io/[email protected];
+ @since(version = 0.2.0)
+ import wasi:io/[email protected];
+ @since(version = 0.2.0)
+ import wasi:io/[email protected];
+ @since(version = 0.2.0)
+ import stdin;
+ @since(version = 0.2.0)
+ import stdout;
+ @since(version = 0.2.0)
+ import stderr;
+ @since(version = 0.2.0)
+ import terminal-input;
+ @since(version = 0.2.0)
+ import terminal-output;
+ @since(version = 0.2.0)
+ import terminal-stdin;
+ @since(version = 0.2.0)
+ import terminal-stdout;
+ @since(version = 0.2.0)
+ import terminal-stderr;
+ @since(version = 0.2.0)
+ import wasi:clocks/[email protected];
+ @since(version = 0.2.0)
+ import wasi:clocks/[email protected];
+ @unstable(feature = clocks-timezone)
+ import wasi:clocks/[email protected];
+ @since(version = 0.2.0)
+ import wasi:filesystem/[email protected];
+ @since(version = 0.2.0)
+ import wasi:filesystem/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:sockets/[email protected];
+ @since(version = 0.2.0)
+ import wasi:random/[email protected];
+ @since(version = 0.2.0)
+ import wasi:random/[email protected];
+ @since(version = 0.2.0)
+ import wasi:random/[email protected];
+
+ @since(version = 0.2.0)
+ export run;
+}
diff --git a/crates/debugger/wit/deps/clocks.wit b/crates/debugger/wit/deps/clocks.wit
new file mode 100644
index 0000000000..d638f1a40f
--- /dev/null
+++ b/crates/debugger/wit/deps/clocks.wit
@@ -0,0 +1,157 @@
+package wasi:[email protected];
+
+/// WASI Monotonic Clock is a clock API intended to let users measure elapsed
+/// time.
+///
+/// It is intended to be portable at least between Unix-family platforms and
+/// Windows.
+///
+/// A monotonic clock is a clock which has an unspecified initial value, and
+/// successive reads of the clock will produce non-decreasing values.
+@since(version = 0.2.0)
+interface monotonic-clock {
+ @since(version = 0.2.0)
+ use wasi:io/[email protected].{pollable};
+
+ /// An instant in time, in nanoseconds. An instant is relative to an
+ /// unspecified initial value, and can only be compared to instances from
+ /// the same monotonic-clock.
+ @since(version = 0.2.0)
+ type instant = u64;
+
+ /// A duration of time, in nanoseconds.
+ @since(version = 0.2.0)
+ type duration = u64;
+
+ /// Read the current value of the clock.
+ ///
+ /// The clock is monotonic, therefore calling this function repeatedly will
+ /// produce a sequence of non-decreasing values.
+ @since(version = 0.2.0)
+ now: func() -> instant;
+
+ /// Query the resolution of the clock. Returns the duration of time
+ /// corresponding to a clock tick.
+ @since(version = 0.2.0)
+ resolution: func() -> duration;
+
+ /// Create a `pollable` which will resolve once the specified instant
+ /// has occurred.
+ @since(version = 0.2.0)
+ subscribe-instant: func(when: instant) -> pollable;
+
+ /// Create a `pollable` that will resolve after the specified duration has
+ /// elapsed from the time this function is invoked.
+ @since(version = 0.2.0)
+ subscribe-duration: func(when: duration) -> pollable;
+}
+
+/// WASI Wall Clock is a clock API intended to let users query the current
+/// time. The name "wall" makes an analogy to a "clock on the wall", which
+/// is not necessarily monotonic as it may be reset.
+///
+/// It is intended to be portable at least between Unix-family platforms and
+/// Windows.
+///
+/// A wall clock is a clock which measures the date and time according to
+/// some external reference.
+///
+/// External references may be reset, so this clock is not necessarily
+/// monotonic, making it unsuitable for measuring elapsed time.
+///
+/// It is intended for reporting the current date and time for humans.
+@since(version = 0.2.0)
+interface wall-clock {
+ /// A time and date in seconds plus nanoseconds.
+ @since(version = 0.2.0)
+ record datetime {
+ seconds: u64,
+ nanoseconds: u32,
+ }
+
+ /// Read the current value of the clock.
+ ///
+ /// This clock is not monotonic, therefore calling this function repeatedly
+ /// will not necessarily produce a sequence of non-decreasing values.
+ ///
+ /// The returned timestamps represent the number of seconds since
+ /// 1970-01-01T00:00:00Z, also known as [POSIX's Seconds Since the Epoch],
+ /// also known as [Unix Time].
+ ///
+ /// The nanoseconds field of the output is always less than 1000000000.
+ ///
+ /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16
+ /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time
+ @since(version = 0.2.0)
+ now: func() -> datetime;
+
+ /// Query the resolution of the clock.
+ ///
+ /// The nanoseconds field of the output is always less than 1000000000.
+ @since(version = 0.2.0)
+ resolution: func() -> datetime;
+}
+
+@unstable(feature = clocks-timezone)
+interface timezone {
+ @unstable(feature = clocks-timezone)
+ use wall-clock.{datetime};
+
+ /// Information useful for displaying the timezone of a specific `datetime`.
+ ///
+ /// This information may vary within a single `timezone` to reflect daylight
+ /// saving time adjustments.
+ @unstable(feature = clocks-timezone)
+ record timezone-display {
+ /// The number of seconds difference between UTC time and the local
+ /// time of the timezone.
+ ///
+ /// The returned value will always be less than 86400 which is the
+ /// number of seconds in a day (24*60*60).
+ ///
+ /// In implementations that do not expose an actual time zone, this
+ /// should return 0.
+ utc-offset: s32,
+ /// The abbreviated name of the timezone to display to a user. The name
+ /// `UTC` indicates Coordinated Universal Time. Otherwise, this should
+ /// reference local standards for the name of the time zone.
+ ///
+ /// In implementations that do not expose an actual time zone, this
+ /// should be the string `UTC`.
+ ///
+ /// In time zones that do not have an applicable name, a formatted
+ /// representation of the UTC offset may be returned, such as `-04:00`.
+ name: string,
+ /// Whether daylight saving time is active.
+ ///
+ /// In implementations that do not expose an actual time zone, this
+ /// should return false.
+ in-daylight-saving-time: bool,
+ }
+
+ /// Return information needed to display the given `datetime`. This includes
+ /// the UTC offset, the time zone name, and a flag indicating whether
+ /// daylight saving time is active.
+ ///
+ /// If the timezone cannot be determined for the given `datetime`, return a
+ /// `timezone-display` for `UTC` with a `utc-offset` of 0 and no daylight
+ /// saving time.
+ @unstable(feature = clocks-timezone)
+ display: func(when: datetime) -> timezone-display;
+
+ /// The same as `display`, but only return the UTC offset.
+ @unstable(feature = clocks-timezone)
+ utc-offset: func(when: datetime) -> s32;
+}
+
+@since(version = 0.2.0)
+world imports {
+ @since(version = 0.2.0)
+ import wasi:io/[email protected];
+ @since(version = 0.2.0)
+ import monotonic-clock;
+ @since(version = 0.2.0)
+ import wall-clock;
+ @unstable(feature = clocks-timezone)
+ import timezone;
+}
diff --git a/crates/debugger/wit/deps/filesystem.wit b/crates/debugger/wit/deps/filesystem.wit
new file mode 100644
index 0000000000..9f4a8288b4
--- /dev/null
+++ b/crates/debugger/wit/deps/filesystem.wit
@@ -0,0 +1,587 @@
+package wasi:[email protected];
+
+/// WASI filesystem is a filesystem API primarily intended to let users run WASI
+/// programs that access their files on their existing filesystems, without
+/// significant overhead.
+///
+/// It is intended to be roughly portable between Unix-family platforms and
+/// Windows, though it does not hide many of the major differences.
+///
+/// Paths are passed as interface-type `string`s, meaning they must consist of
+/// a sequence of Unicode Scalar Values (USVs). Some filesystems may contain
+/// paths which are not accessible by this API.
+///
+/// The directory separator in WASI is always the forward-slash (`/`).
+///
+/// All paths in WASI are relative paths, and are interpreted relative to a
+/// `descriptor` referring to a base directory. If a `path` argument to any WASI
+/// function starts with `/`, or if any step of resolving a `path`, including
+/// `..` and symbolic link steps, reaches a directory outside of the base
+/// directory, or reaches a symlink to an absolute or rooted path in the
+/// underlying filesystem, the function fails with `error-code::not-permitted`.
+///
+/// For more information about WASI path resolution and sandboxing, see
+/// [WASI filesystem path resolution].
+///
+/// [WASI filesystem path resolution]: https://github.com/WebAssembly/wasi-filesystem/blob/main/path-resolution.md
+@since(version = 0.2.0)
+interface types {
+ @since(version = 0.2.0)
+ use wasi:io/[email protected].{input-stream, output-stream, error};
+ @since(version = 0.2.0)
+ use wasi:clocks/[email protected].{datetime};
+
+ /// File size or length of a region within a file.
+ @since(version = 0.2.0)
+ type filesize = u64;
+
+ /// The type of a filesystem object referenced by a descriptor.
+ ///
+ /// Note: This was called `filetype` in earlier versions of WASI.
+ @since(version = 0.2.0)
+ enum descriptor-type {
+ /// The type of the descriptor or file is unknown or is different from
+ /// any of the other types specified.
+ unknown,
+ /// The descriptor refers to a block device inode.
+ block-device,
+ /// The descriptor refers to a character device inode.
+ character-device,
+ /// The descriptor refers to a directory inode.
+ directory,
+ /// The descriptor refers to a named pipe.
+ fifo,
+ /// The file refers to a symbolic link inode.
+ symbolic-link,
+ /// The descriptor refers to a regular file inode.
+ regular-file,
+ /// The descriptor refers to a socket.
+ socket,
+ }
+
+ /// Descriptor flags.
+ ///
+ /// Note: This was called `fdflags` in earlier versions of WASI.
+ @since(version = 0.2.0)
+ flags descriptor-flags {
+ /// Read mode: Data can be read.
+ read,
+ /// Write mode: Data can be written to.
+ write,
+ /// Request that writes be performed according to synchronized I/O file
+ /// integrity completion. The data stored in the file and the file's
+ /// metadata are synchronized. This is similar to `O_SYNC` in POSIX.
+ ///
+ /// The precise semantics of this operation have not yet been defined for
+ /// WASI. At this time, it should be interpreted as a request, and not a
+ /// requirement.
+ file-integrity-sync,
+ /// Request that writes be performed according to synchronized I/O data
+ /// integrity completion. Only the data stored in the file is
+ /// synchronized. This is similar to `O_DSYNC` in POSIX.
+ ///
+ /// The precise semantics of this operation have not yet been defined for
+ /// WASI. At this time, it should be interpreted as a request, and not a
+ /// requirement.
+ data-integrity-sync,
+ /// Requests that reads be performed at the same level of integrity
+ /// requested for writes. This is similar to `O_RSYNC` in POSIX.
+ ///
+ /// The precise semantics of this operation have not yet been defined for
+ /// WASI. At this time, it should be interpreted as a request, and not a
+ /// requirement.
+ requested-write-sync,
+ /// Mutating directories mode: Directory contents may be mutated.
+ ///
+ /// When this flag is unset on a descriptor, operations using the
+ /// descriptor which would create, rename, delete, modify the data or
+ /// metadata of filesystem objects, or obtain another handle which
+ /// would permit any of those, shall fail with `error-code::read-only` if
+ /// they would otherwise succeed.
+ ///
+ /// This may only be set on directories.
+ mutate-directory,
+ }
+
+ /// Flags determining the method of how paths are resolved.
+ @since(version = 0.2.0)
+ flags path-flags {
+ /// As long as the resolved path corresponds to a symbolic link, it is
+ /// expanded.
+ symlink-follow,
+ }
+
+ /// Open flags used by `open-at`.
+ @since(version = 0.2.0)
+ flags open-flags {
+ /// Create file if it does not exist, similar to `O_CREAT` in POSIX.
+ create,
+ /// Fail if not a directory, similar to `O_DIRECTORY` in POSIX.
+ directory,
+ /// Fail if file already exists, similar to `O_EXCL` in POSIX.
+ exclusive,
+ /// Truncate file to size 0, similar to `O_TRUNC` in POSIX.
+ truncate,
+ }
+
+ /// Number of hard links to an inode.
+ @since(version = 0.2.0)
+ type link-count = u64;
+
+ /// File attributes.
+ ///
+ /// Note: This was called `filestat` in earlier versions of WASI.
+ @since(version = 0.2.0)
+ record descriptor-stat {
+ /// File type.
+ %type: descriptor-type,
+ /// Number of hard links to the file.
+ link-count: link-count,
+ /// For regular files, the file size in bytes. For symbolic links, the
+ /// length in bytes of the pathname contained in the symbolic link.
+ size: filesize,
+ /// Last data access timestamp.
+ ///
+ /// If the `option` is none, the platform doesn't maintain an access
+ /// timestamp for this file.
+ data-access-timestamp: option<datetime>,
+ /// Last data modification timestamp.
+ ///
+ /// If the `option` is none, the platform doesn't maintain a
+ /// modification timestamp for this file.
+ data-modification-timestamp: option<datetime>,
+ /// Last file status-change timestamp.
+ ///
+ /// If the `option` is none, the platform doesn't maintain a
+ /// status-change timestamp for this file.
+ status-change-timestamp: option<datetime>,
+ }
+
+ /// When setting a timestamp, this gives the value to set it to.
+ @since(version = 0.2.0)
+ variant new-timestamp {
+ /// Leave the timestamp set to its previous value.
+ no-change,
+ /// Set the timestamp to the current time of the system clock associated
+ /// with the filesystem.
+ now,
+ /// Set the timestamp to the given value.
+ timestamp(datetime),
+ }
+
+ /// A directory entry.
+ record directory-entry {
+ /// The type of the file referred to by this directory entry.
+ %type: descriptor-type,
+ /// The name of the object.
+ name: string,
+ }
+
+ /// Error codes returned by functions, similar to `errno` in POSIX.
+ /// Not all of these error codes are returned by the functions provided by this
+ /// API; some are used in higher-level library layers, and others are provided
+ /// merely for alignment with POSIX.
+ enum error-code {
+ /// Permission denied, similar to `EACCES` in POSIX.
+ access,
+ /// Resource unavailable, or operation would block, similar to `EAGAIN` and `EWOULDBLOCK` in POSIX.
+ would-block,
+ /// Connection already in progress, similar to `EALREADY` in POSIX.
+ already,
+ /// Bad descriptor, similar to `EBADF` in POSIX.
+ bad-descriptor,
+ /// Device or resource busy, similar to `EBUSY` in POSIX.
+ busy,
+ /// Resource deadlock would occur, similar to `EDEADLK` in POSIX.
+ deadlock,
+ /// Storage quota exceeded, similar to `EDQUOT` in POSIX.
+ quota,
+ /// File exists, similar to `EEXIST` in POSIX.
+ exist,
+ /// File too large, similar to `EFBIG` in POSIX.
+ file-too-large,
+ /// Illegal byte sequence, similar to `EILSEQ` in POSIX.
+ illegal-byte-sequence,
+ /// Operation in progress, similar to `EINPROGRESS` in POSIX.
+ in-progress,
+ /// Interrupted function, similar to `EINTR` in POSIX.
+ interrupted,
+ /// Invalid argument, similar to `EINVAL` in POSIX.
+ invalid,
+ /// I/O error, similar to `EIO` in POSIX.
+ io,
+ /// Is a directory, similar to `EISDIR` in POSIX.
+ is-directory,
+ /// Too many levels of symbolic links, similar to `ELOOP` in POSIX.
+ loop,
+ /// Too many links, similar to `EMLINK` in POSIX.
+ too-many-links,
+ /// Message too large, similar to `EMSGSIZE` in POSIX.
+ message-size,
+ /// Filename too long, similar to `ENAMETOOLONG` in POSIX.
+ name-too-long,
+ /// No such device, similar to `ENODEV` in POSIX.
+ no-device,
+ /// No such file or directory, similar to `ENOENT` in POSIX.
+ no-entry,
+ /// No locks available, similar to `ENOLCK` in POSIX.
+ no-lock,
+ /// Not enough space, similar to `ENOMEM` in POSIX.
+ insufficient-memory,
+ /// No space left on device, similar to `ENOSPC` in POSIX.
+ insufficient-space,
+ /// Not a directory or a symbolic link to a directory, similar to `ENOTDIR` in POSIX.
+ not-directory,
+ /// Directory not empty, similar to `ENOTEMPTY` in POSIX.
+ not-empty,
+ /// State not recoverable, similar to `ENOTRECOVERABLE` in POSIX.
+ not-recoverable,
+ /// Not supported, similar to `ENOTSUP` and `ENOSYS` in POSIX.
+ unsupported,
+ /// Inappropriate I/O control operation, similar to `ENOTTY` in POSIX.
+ no-tty,
+ /// No such device or address, similar to `ENXIO` in POSIX.
+ no-such-device,
+ /// Value too large to be stored in data type, similar to `EOVERFLOW` in POSIX.
+ overflow,
+ /// Operation not permitted, similar to `EPERM` in POSIX.
+ not-permitted,
+ /// Broken pipe, similar to `EPIPE` in POSIX.
+ pipe,
+ /// Read-only file system, similar to `EROFS` in POSIX.
+ read-only,
+ /// Invalid seek, similar to `ESPIPE` in POSIX.
+ invalid-seek,
+ /// Text file busy, similar to `ETXTBSY` in POSIX.
+ text-file-busy,
+ /// Cross-device link, similar to `EXDEV` in POSIX.
+ cross-device,
+ }
+
+ /// File or memory access pattern advisory information.
+ @since(version = 0.2.0)
+ enum advice {
+ /// The application has no advice to give on its behavior with respect
+ /// to the specified data.
+ normal,
+ /// The application expects to access the specified data sequentially
+ /// from lower offsets to higher offsets.
+ sequential,
+ /// The application expects to access the specified data in a random
+ /// order.
+ random,
+ /// The application expects to access the specified data in the near
+ /// future.
+ will-need,
+ /// The application expects that it will not access the specified data
+ /// in the near future.
+ dont-need,
+ /// The application expects to access the specified data once and then
+ /// not reuse it thereafter.
+ no-reuse,
+ }
+
+ /// A 128-bit hash value, split into parts because wasm doesn't have a
+ /// 128-bit integer type.
+ @since(version = 0.2.0)
+ record metadata-hash-value {
+ /// 64 bits of a 128-bit hash value.
+ lower: u64,
+ /// Another 64 bits of a 128-bit hash value.
+ upper: u64,
+ }
+
+ /// A descriptor is a reference to a filesystem object, which may be a file,
+ /// directory, named pipe, special file, or other object on which filesystem
+ /// calls may be made.
+ @since(version = 0.2.0)
+ resource descriptor {
+ /// Return a stream for reading from a file, if available.
+ ///
+ /// May fail with an error-code describing why the file cannot be read.
+ ///
+ /// Multiple read, write, and append streams may be active on the same open
+ /// file and they do not interfere with each other.
+ ///
+ /// Note: This allows using `read-stream`, which is similar to `read` in POSIX.
+ @since(version = 0.2.0)
+ read-via-stream: func(offset: filesize) -> result<input-stream, error-code>;
+ /// Return a stream for writing to a file, if available.
+ ///
+ /// May fail with an error-code describing why the file cannot be written.
+ ///
+ /// Note: This allows using `write-stream`, which is similar to `write` in
+ /// POSIX.
+ @since(version = 0.2.0)
+ write-via-stream: func(offset: filesize) -> result<output-stream, error-code>;
+ /// Return a stream for appending to a file, if available.
+ ///
+ /// May fail with an error-code describing why the file cannot be appended.
+ ///
+ /// Note: This allows using `write-stream`, which is similar to `write` with
+ /// `O_APPEND` in POSIX.
+ @since(version = 0.2.0)
+ append-via-stream: func() -> result<output-stream, error-code>;
+ /// Provide file advisory information on a descriptor.
+ ///
+ /// This is similar to `posix_fadvise` in POSIX.
+ @since(version = 0.2.0)
+ advise: func(offset: filesize, length: filesize, advice: advice) -> result<_, error-code>;
+ /// Synchronize the data of a file to disk.
+ ///
+ /// This function succeeds with no effect if the file descriptor is not
+ /// opened for writing.
+ ///
+ /// Note: This is similar to `fdatasync` in POSIX.
+ @since(version = 0.2.0)
+ sync-data: func() -> result<_, error-code>;
+ /// Get flags associated with a descriptor.
+ ///
+ /// Note: This returns similar flags to `fcntl(fd, F_GETFL)` in POSIX.
+ ///
+ /// Note: This returns the value that was the `fs_flags` value returned
+ /// from `fdstat_get` in earlier versions of WASI.
+ @since(version = 0.2.0)
+ get-flags: func() -> result<descriptor-flags, error-code>;
+ /// Get the dynamic type of a descriptor.
+ ///
+ /// Note: This returns the same value as the `type` field of the `fd-stat`
+ /// returned by `stat`, `stat-at` and similar.
+ ///
+ /// Note: This returns similar flags to the `st_mode & S_IFMT` value provided
+ /// by `fstat` in POSIX.
+ ///
+ /// Note: This returns the value that was the `fs_filetype` value returned
+ /// from `fdstat_get` in earlier versions of WASI.
+ @since(version = 0.2.0)
+ get-type: func() -> result<descriptor-type, error-code>;
+ /// Adjust the size of an open file. If this increases the file's size, the
+ /// extra bytes are filled with zeros.
+ ///
+ /// Note: This was called `fd_filestat_set_size` in earlier versions of WASI.
+ @since(version = 0.2.0)
+ set-size: func(size: filesize) -> result<_, error-code>;
+ /// Adjust the timestamps of an open file or directory.
+ ///
+ /// Note: This is similar to `futimens` in POSIX.
+ ///
+ /// Note: This was called `fd_filestat_set_times` in earlier versions of WASI.
+ @since(version = 0.2.0)
+ set-times: func(data-access-timestamp: new-timestamp, data-modification-timestamp: new-timestamp) -> result<_, error-code>;
+ /// Read from a descriptor, without using and updating the descriptor's offset.
+ ///
+ /// This function returns a list of bytes containing the data that was
+ /// read, along with a bool which, when true, indicates that the end of the
+ /// file was reached. The returned list will contain up to `length` bytes; it
+ /// may return fewer than requested, if the end of the file is reached or
+ /// if the I/O operation is interrupted.
+ ///
+ /// In the future, this may change to return a `stream<u8, error-code>`.
+ ///
+ /// Note: This is similar to `pread` in POSIX.
+ @since(version = 0.2.0)
+ read: func(length: filesize, offset: filesize) -> result<tuple<list<u8>, bool>, error-code>;
+ /// Write to a descriptor, without using and updating the descriptor's offset.
+ ///
+ /// It is valid to write past the end of a file; the file is extended to the
+ /// extent of the write, with bytes between the previous end and the start of
+ /// the write set to zero.
+ ///
+ /// In the future, this may change to take a `stream<u8, error-code>`.
+ ///
+ /// Note: This is similar to `pwrite` in POSIX.
+ @since(version = 0.2.0)
+ write: func(buffer: list<u8>, offset: filesize) -> result<filesize, error-code>;
+ /// Read directory entries from a directory.
+ ///
+ /// On filesystems where directories contain entries referring to themselves
+ /// and their parents, often named `.` and `..` respectively, these entries
+ /// are omitted.
+ ///
+ /// This always returns a new stream which starts at the beginning of the
+ /// directory. Multiple streams may be active on the same directory, and they
+ /// do not interfere with each other.
+ @since(version = 0.2.0)
+ read-directory: func() -> result<directory-entry-stream, error-code>;
+ /// Synchronize the data and metadata of a file to disk.
+ ///
+ /// This function succeeds with no effect if the file descriptor is not
+ /// opened for writing.
+ ///
+ /// Note: This is similar to `fsync` in POSIX.
+ @since(version = 0.2.0)
+ sync: func() -> result<_, error-code>;
+ /// Create a directory.
+ ///
+ /// Note: This is similar to `mkdirat` in POSIX.
+ @since(version = 0.2.0)
+ create-directory-at: func(path: string) -> result<_, error-code>;
+ /// Return the attributes of an open file or directory.
+ ///
+ /// Note: This is similar to `fstat` in POSIX, except that it does not return
+ /// device and inode information. For testing whether two descriptors refer to
+ /// the same underlying filesystem object, use `is-same-object`. To obtain
+ /// additional data that can be used do determine whether a file has been
+ /// modified, use `metadata-hash`.
+ ///
+ /// Note: This was called `fd_filestat_get` in earlier versions of WASI.
+ @since(version = 0.2.0)
+ stat: func() -> result<descriptor-stat, error-code>;
+ /// Return the attributes of a file or directory.
+ ///
+ /// Note: This is similar to `fstatat` in POSIX, except that it does not
+ /// return device and inode information. See the `stat` description for a
+ /// discussion of alternatives.
+ ///
+ /// Note: This was called `path_filestat_get` in earlier versions of WASI.
+ @since(version = 0.2.0)
+ stat-at: func(path-flags: path-flags, path: string) -> result<descriptor-stat, error-code>;
+ /// Adjust the timestamps of a file or directory.
+ ///
+ /// Note: This is similar to `utimensat` in POSIX.
+ ///
+ /// Note: This was called `path_filestat_set_times` in earlier versions of
+ /// WASI.
+ @since(version = 0.2.0)
+ set-times-at: func(path-flags: path-flags, path: string, data-access-timestamp: new-timestamp, data-modification-timestamp: new-timestamp) -> result<_, error-code>;
+ /// Create a hard link.
+ ///
+ /// Fails with `error-code::no-entry` if the old path does not exist,
+ /// with `error-code::exist` if the new path already exists, and
+ /// `error-code::not-permitted` if the old path is not a file.
+ ///
+ /// Note: This is similar to `linkat` in POSIX.
+ @since(version = 0.2.0)
+ link-at: func(old-path-flags: path-flags, old-path: string, new-descriptor: borrow<descriptor>, new-path: string) -> result<_, error-code>;
+ /// Open a file or directory.
+ ///
+ /// If `flags` contains `descriptor-flags::mutate-directory`, and the base
+ /// descriptor doesn't have `descriptor-flags::mutate-directory` set,
+ /// `open-at` fails with `error-code::read-only`.
+ ///
+ /// If `flags` contains `write` or `mutate-directory`, or `open-flags`
+ /// contains `truncate` or `create`, and the base descriptor doesn't have
+ /// `descriptor-flags::mutate-directory` set, `open-at` fails with
+ /// `error-code::read-only`.
+ ///
+ /// Note: This is similar to `openat` in POSIX.
+ @since(version = 0.2.0)
+ open-at: func(path-flags: path-flags, path: string, open-flags: open-flags, %flags: descriptor-flags) -> result<descriptor, error-code>;
+ /// Read the contents of a symbolic link.
+ ///
+ /// If the contents contain an absolute or rooted path in the underlying
+ /// filesystem, this function fails with `error-code::not-permitted`.
+ ///
+ /// Note: This is similar to `readlinkat` in POSIX.
+ @since(version = 0.2.0)
+ readlink-at: func(path: string) -> result<string, error-code>;
+ /// Remove a directory.
+ ///
+ /// Return `error-code::not-empty` if the directory is not empty.
+ ///
+ /// Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX.
+ @since(version = 0.2.0)
+ remove-directory-at: func(path: string) -> result<_, error-code>;
+ /// Rename a filesystem object.
+ ///
+ /// Note: This is similar to `renameat` in POSIX.
+ @since(version = 0.2.0)
+ rename-at: func(old-path: string, new-descriptor: borrow<descriptor>, new-path: string) -> result<_, error-code>;
+ /// Create a symbolic link (also known as a "symlink").
+ ///
+ /// If `old-path` starts with `/`, the function fails with
+ /// `error-code::not-permitted`.
+ ///
+ /// Note: This is similar to `symlinkat` in POSIX.
+ @since(version = 0.2.0)
+ symlink-at: func(old-path: string, new-path: string) -> result<_, error-code>;
+ /// Unlink a filesystem object that is not a directory.
+ ///
+ /// Return `error-code::is-directory` if the path refers to a directory.
+ /// Note: This is similar to `unlinkat(fd, path, 0)` in POSIX.
+ @since(version = 0.2.0)
+ unlink-file-at: func(path: string) -> result<_, error-code>;
+ /// Test whether two descriptors refer to the same filesystem object.
+ ///
+ /// In POSIX, this corresponds to testing whether the two descriptors have the
+ /// same device (`st_dev`) and inode (`st_ino` or `d_ino`) numbers.
+ /// wasi-filesystem does not expose device and inode numbers, so this function
+ /// may be used instead.
+ @since(version = 0.2.0)
+ is-same-object: func(other: borrow<descriptor>) -> bool;
+ /// Return a hash of the metadata associated with a filesystem object referred
+ /// to by a descriptor.
+ ///
+ /// This returns a hash of the last-modification timestamp and file size, and
+ /// may also include the inode number, device number, birth timestamp, and
+ /// other metadata fields that may change when the file is modified or
+ /// replaced. It may also include a secret value chosen by the
+ /// implementation and not otherwise exposed.
+ ///
+ /// Implementations are encouraged to provide the following properties:
+ ///
+ /// - If the file is not modified or replaced, the computed hash value should
+ /// usually not change.
+ /// - If the object is modified or replaced, the computed hash value should
+ /// usually change.
+ /// - The inputs to the hash should not be easily computable from the
+ /// computed hash.
+ ///
+ /// However, none of these is required.
+ @since(version = 0.2.0)
+ metadata-hash: func() -> result<metadata-hash-value, error-code>;
+ /// Return a hash of the metadata associated with a filesystem object referred
+ /// to by a directory descriptor and a relative path.
+ ///
+ /// This performs the same hash computation as `metadata-hash`.
+ @since(version = 0.2.0)
+ metadata-hash-at: func(path-flags: path-flags, path: string) -> result<metadata-hash-value, error-code>;
+ }
+
+ /// A stream of directory entries.
+ @since(version = 0.2.0)
+ resource directory-entry-stream {
+ /// Read a single directory entry from a `directory-entry-stream`.
+ @since(version = 0.2.0)
+ read-directory-entry: func() -> result<option<directory-entry>, error-code>;
+ }
+
+ /// Attempts to extract a filesystem-related `error-code` from the stream
+ /// `error` provided.
+ ///
+ /// Stream operations which return `stream-error::last-operation-failed`
+ /// have a payload with more information about the operation that failed.
+ /// This payload can be passed through to this function to see if there's
+ /// filesystem-related information about the error to return.
+ ///
+ /// Note that this function is fallible because not all stream-related
+ /// errors are filesystem-related errors.
+ @since(version = 0.2.0)
+ filesystem-error-code: func(err: borrow<error>) -> option<error-code>;
+}
+
+@since(version = 0.2.0)
+interface preopens {
+ @since(version = 0.2.0)
+ use types.{descriptor};
+
+ /// Return the set of preopened directories, and their paths.
+ @since(version = 0.2.0)
+ get-directories: func() -> list<tuple<descriptor, string>>;
+}
+
+@since(version = 0.2.0)
+world imports {
+ @since(version = 0.2.0)
+ import wasi:io/[email protected];
+ @since(version = 0.2.0)
+ import wasi:io/[email protected];
+ @since(version = 0.2.0)
+ import wasi:io/[email protected];
+ @since(version = 0.2.0)
+ import wasi:clocks/[email protected];
+ @since(version = 0.2.0)
+ import types;
+ @since(version = 0.2.0)
+ import preopens;
+}
diff --git a/crates/debugger/wit/deps/io.wit b/crates/debugger/wit/deps/io.wit
new file mode 100644
index 0000000000..08ad78e6b7
--- /dev/null
+++ b/crates/debugger/wit/deps/io.wit
@@ -0,0 +1,331 @@
+package wasi:[email protected];
+
+@since(version = 0.2.0)
+interface error {
+ /// A resource which represents some error information.
+ ///
+ /// The only method provided by this resource is `to-debug-string`,
+ /// which provides some human-readable information about the error.
+ ///
+ /// In the `wasi:io` package, this resource is returned through the
+ /// `wasi:io/streams/stream-error` type.
+ ///
+ /// To provide more specific error information, other interfaces may
+ /// offer functions to "downcast" this error into more specific types. For example,
+ /// errors returned from streams derived from filesystem types can be described using
+ /// the filesystem's own error-code type. This is done using the function
+ /// `wasi:filesystem/types/filesystem-error-code`, which takes a `borrow<error>`
+ /// parameter and returns an `option<wasi:filesystem/types/error-code>`.
+ ///
+ /// The set of functions which can "downcast" an `error` into a more
+ /// concrete type is open.
+ @since(version = 0.2.0)
+ resource error {
+ /// Returns a string that is suitable to assist humans in debugging
+ /// this error.
+ ///
+ /// WARNING: The returned string should not be consumed mechanically!
+ /// It may change across platforms, hosts, or other implementation
+ /// details. Parsing this string is a major platform-compatibility
+ /// hazard.
+ @since(version = 0.2.0)
+ to-debug-string: func() -> string;
+ }
+}
+
+/// A poll API intended to let users wait for I/O events on multiple handles
+/// at once.
+@since(version = 0.2.0)
+interface poll {
+ /// `pollable` represents a single I/O event which may be ready, or not.
+ @since(version = 0.2.0)
+ resource pollable {
+ /// Return the readiness of a pollable. This function never blocks.
+ ///
+ /// Returns `true` when the pollable is ready, and `false` otherwise.
+ @since(version = 0.2.0)
+ ready: func() -> bool;
+ /// `block` returns immediately if the pollable is ready, and otherwise
+ /// blocks until ready.
+ ///
+ /// This function is equivalent to calling `poll.poll` on a list
+ /// containing only this pollable.
+ @since(version = 0.2.0)
+ block: func();
+ }
+
+ /// Poll for completion on a set of pollables.
+ ///
+ /// This function takes a list of pollables, which identify I/O sources of
+ /// interest, and waits until one or more of the events is ready for I/O.
+ ///
+ /// The result `list<u32>` contains one or more indices of handles in the
+ /// argument list that is ready for I/O.
+ ///
+ /// This function traps if either:
+ /// - the list is empty, or:
+ /// - the list contains more elements than can be indexed with a `u32` value.
+ ///
+ /// A timeout can be implemented by adding a pollable from the
+ /// wasi-clocks API to the list.
+ ///
+ /// This function does not return a `result`; polling in itself does not
+ /// do any I/O so it doesn't fail. If any of the I/O sources identified by
+ /// the pollables has an error, it is indicated by marking the source as
+ /// being ready for I/O.
+ @since(version = 0.2.0)
+ poll: func(in: list<borrow<pollable>>) -> list<u32>;
+}
+
+/// WASI I/O is an I/O abstraction API which is currently focused on providing
+/// stream types.
+///
+/// In the future, the component model is expected to add built-in stream types;
+/// when it does, they are expected to subsume this API.
+@since(version = 0.2.0)
+interface streams {
+ @since(version = 0.2.0)
+ use error.{error};
+ @since(version = 0.2.0)
+ use poll.{pollable};
+
+ /// An error for input-stream and output-stream operations.
+ @since(version = 0.2.0)
+ variant stream-error {
+ /// The last operation (a write or flush) failed before completion.
+ ///
+ /// More information is available in the `error` payload.
+ ///
+ /// After this, the stream will be closed. All future operations return
+ /// `stream-error::closed`.
+ last-operation-failed(error),
+ /// The stream is closed: no more input will be accepted by the
+ /// stream. A closed output-stream will return this error on all
+ /// future operations.
+ closed,
+ }
+
+ /// An input bytestream.
+ ///
+ /// `input-stream`s are *non-blocking* to the extent practical on underlying
+ /// platforms. I/O operations always return promptly; if fewer bytes are
+ /// promptly available than requested, they return the number of bytes promptly
+ /// available, which could even be zero. To wait for data to be available,
+ /// use the `subscribe` function to obtain a `pollable` which can be polled
+ /// for using `wasi:io/poll`.
+ @since(version = 0.2.0)
+ resource input-stream {
+ /// Perform a non-blocking read from the stream.
+ ///
+ /// When the source of a `read` is binary data, the bytes from the source
+ /// are returned verbatim. When the source of a `read` is known to the
+ /// implementation to be text, bytes containing the UTF-8 encoding of the
+ /// text are returned.
+ ///
+ /// This function returns a list of bytes containing the read data,
+ /// when successful. The returned list will contain up to `len` bytes;
+ /// it may return fewer than requested, but not more. The list is
+ /// empty when no bytes are available for reading at this time. The
+ /// pollable given by `subscribe` will be ready when more bytes are
+ /// available.
+ ///
+ /// This function fails with a `stream-error` when the operation
+ /// encounters an error, giving `last-operation-failed`, or when the
+ /// stream is closed, giving `closed`.
+ ///
+ /// When the caller gives a `len` of 0, it represents a request to
+ /// read 0 bytes. If the stream is still open, this call should
+ /// succeed and return an empty list, or otherwise fail with `closed`.
+ ///
+ /// The `len` parameter is a `u64`, which could represent a list of u8 which
+ /// is not possible to allocate in wasm32, or not desirable to allocate as
+ /// as a return value by the callee. The callee may return a list of bytes
+ /// less than `len` in size while more bytes are available for reading.
+ @since(version = 0.2.0)
+ read: func(len: u64) -> result<list<u8>, stream-error>;
+ /// Read bytes from a stream, after blocking until at least one byte can
+ /// be read. Except for blocking, behavior is identical to `read`.
+ @since(version = 0.2.0)
+ blocking-read: func(len: u64) -> result<list<u8>, stream-error>;
+ /// Skip bytes from a stream. Returns number of bytes skipped.
+ ///
+ /// Behaves identical to `read`, except instead of returning a list
+ /// of bytes, returns the number of bytes consumed from the stream.
+ @since(version = 0.2.0)
+ skip: func(len: u64) -> result<u64, stream-error>;
+ /// Skip bytes from a stream, after blocking until at least one byte
+ /// can be skipped. Except for blocking behavior, identical to `skip`.
+ @since(version = 0.2.0)
+ blocking-skip: func(len: u64) -> result<u64, stream-error>;
+ /// Create a `pollable` which will resolve once either the specified stream
+ /// has bytes available to read or the other end of the stream has been
+ /// closed.
+ /// The created `pollable` is a child resource of the `input-stream`.
+ /// Implementations may trap if the `input-stream` is dropped before
+ /// all derived `pollable`s created with this function are dropped.
+ @since(version = 0.2.0)
+ subscribe: func() -> pollable;
+ }
+
+ /// An output bytestream.
+ ///
+ /// `output-stream`s are *non-blocking* to the extent practical on
+ /// underlying platforms. Except where specified otherwise, I/O operations also
+ /// always return promptly, after the number of bytes that can be written
+ /// promptly, which could even be zero. To wait for the stream to be ready to
+ /// accept data, the `subscribe` function to obtain a `pollable` which can be
+ /// polled for using `wasi:io/poll`.
+ ///
+ /// Dropping an `output-stream` while there's still an active write in
+ /// progress may result in the data being lost. Before dropping the stream,
+ /// be sure to fully flush your writes.
+ @since(version = 0.2.0)
+ resource output-stream {
+ /// Check readiness for writing. This function never blocks.
+ ///
+ /// Returns the number of bytes permitted for the next call to `write`,
+ /// or an error. Calling `write` with more bytes than this function has
+ /// permitted will trap.
+ ///
+ /// When this function returns 0 bytes, the `subscribe` pollable will
+ /// become ready when this function will report at least 1 byte, or an
+ /// error.
+ @since(version = 0.2.0)
+ check-write: func() -> result<u64, stream-error>;
+ /// Perform a write. This function never blocks.
+ ///
+ /// When the destination of a `write` is binary data, the bytes from
+ /// `contents` are written verbatim. When the destination of a `write` is
+ /// known to the implementation to be text, the bytes of `contents` are
+ /// transcoded from UTF-8 into the encoding of the destination and then
+ /// written.
+ ///
+ /// Precondition: check-write gave permit of Ok(n) and contents has a
+ /// length of less than or equal to n. Otherwise, this function will trap.
+ ///
+ /// returns Err(closed) without writing if the stream has closed since
+ /// the last call to check-write provided a permit.
+ @since(version = 0.2.0)
+ write: func(contents: list<u8>) -> result<_, stream-error>;
+ /// Perform a write of up to 4096 bytes, and then flush the stream. Block
+ /// until all of these operations are complete, or an error occurs.
+ ///
+ /// This is a convenience wrapper around the use of `check-write`,
+ /// `subscribe`, `write`, and `flush`, and is implemented with the
+ /// following pseudo-code:
+ ///
+ /// ```text
+ /// let pollable = this.subscribe();
+ /// while !contents.is_empty() {
+ /// // Wait for the stream to become writable
+ /// pollable.block();
+ /// let Ok(n) = this.check-write(); // eliding error handling
+ /// let len = min(n, contents.len());
+ /// let (chunk, rest) = contents.split_at(len);
+ /// this.write(chunk ); // eliding error handling
+ /// contents = rest;
+ /// }
+ /// this.flush();
+ /// // Wait for completion of `flush`
+ /// pollable.block();
+ /// // Check for any errors that arose during `flush`
+ /// let _ = this.check-write(); // eliding error handling
+ /// ```
+ @since(version = 0.2.0)
+ blocking-write-and-flush: func(contents: list<u8>) -> result<_, stream-error>;
+ /// Request to flush buffered output. This function never blocks.
+ ///
+ /// This tells the output-stream that the caller intends any buffered
+ /// output to be flushed. the output which is expected to be flushed
+ /// is all that has been passed to `write` prior to this call.
+ ///
+ /// Upon calling this function, the `output-stream` will not accept any
+ /// writes (`check-write` will return `ok(0)`) until the flush has
+ /// completed. The `subscribe` pollable will become ready when the
+ /// flush has completed and the stream can accept more writes.
+ @since(version = 0.2.0)
+ flush: func() -> result<_, stream-error>;
+ /// Request to flush buffered output, and block until flush completes
+ /// and stream is ready for writing again.
+ @since(version = 0.2.0)
+ blocking-flush: func() -> result<_, stream-error>;
+ /// Create a `pollable` which will resolve once the output-stream
+ /// is ready for more writing, or an error has occurred. When this
+ /// pollable is ready, `check-write` will return `ok(n)` with n>0, or an
+ /// error.
+ ///
+ /// If the stream is closed, this pollable is always ready immediately.
+ ///
+ /// The created `pollable` is a child resource of the `output-stream`.
+ /// Implementations may trap if the `output-stream` is dropped before
+ /// all derived `pollable`s created with this function are dropped.
+ @since(version = 0.2.0)
+ subscribe: func() -> pollable;
+ /// Write zeroes to a stream.
+ ///
+ /// This should be used precisely like `write` with the exact same
+ /// preconditions (must use check-write first), but instead of
+ /// passing a list of bytes, you simply pass the number of zero-bytes
+ /// that should be written.
+ @since(version = 0.2.0)
+ write-zeroes: func(len: u64) -> result<_, stream-error>;
+ /// Perform a write of up to 4096 zeroes, and then flush the stream.
+ /// Block until all of these operations are complete, or an error
+ /// occurs.
+ ///
+ /// This is a convenience wrapper around the use of `check-write`,
+ /// `subscribe`, `write-zeroes`, and `flush`, and is implemented with
+ /// the following pseudo-code:
+ ///
+ /// ```text
+ /// let pollable = this.subscribe();
+ /// while num_zeroes != 0 {
+ /// // Wait for the stream to become writable
+ /// pollable.block();
+ /// let Ok(n) = this.check-write(); // eliding error handling
+ /// let len = min(n, num_zeroes);
+ /// this.write-zeroes(len); // eliding error handling
+ /// num_zeroes -= len;
+ /// }
+ /// this.flush();
+ /// // Wait for completion of `flush`
+ /// pollable.block();
+ /// // Check for any errors that arose during `flush`
+ /// let _ = this.check-write(); // eliding error handling
+ /// ```
+ @since(version = 0.2.0)
+ blocking-write-zeroes-and-flush: func(len: u64) -> result<_, stream-error>;
+ /// Read from one stream and write to another.
+ ///
+ /// The behavior of splice is equivalent to:
+ /// 1. calling `check-write` on the `output-stream`
+ /// 2. calling `read` on the `input-stream` with the smaller of the
+ /// `check-write` permitted length and the `len` provided to `splice`
+ /// 3. calling `write` on the `output-stream` with that read data.
+ ///
+ /// Any error reported by the call to `check-write`, `read`, or
+ /// `write` ends the splice and reports that error.
+ ///
+ /// This function returns the number of bytes transferred; it may be less
+ /// than `len`.
+ @since(version = 0.2.0)
+ splice: func(src: borrow<input-stream>, len: u64) -> result<u64, stream-error>;
+ /// Read from one stream and write to another, with blocking.
+ ///
+ /// This is similar to `splice`, except that it blocks until the
+ /// `output-stream` is ready for writing, and the `input-stream`
+ /// is ready for reading, before performing the `splice`.
+ @since(version = 0.2.0)
+ blocking-splice: func(src: borrow<input-stream>, len: u64) -> result<u64, stream-error>;
+ }
+}
+
+@since(version = 0.2.0)
+world imports {
+ @since(version = 0.2.0)
+ import error;
+ @since(version = 0.2.0)
+ import poll;
+ @since(version = 0.2.0)
+ import streams;
+}
diff --git a/crates/debugger/wit/deps/random.wit b/crates/debugger/wit/deps/random.wit
new file mode 100644
index 0000000000..73edf5b60e
--- /dev/null
+++ b/crates/debugger/wit/deps/random.wit
@@ -0,0 +1,92 @@
+package wasi:[email protected];
+
+/// The insecure-seed interface for seeding hash-map DoS resistance.
+///
+/// It is intended to be portable at least between Unix-family platforms and
+/// Windows.
+@since(version = 0.2.0)
+interface insecure-seed {
+ /// Return a 128-bit value that may contain a pseudo-random value.
+ ///
+ /// The returned value is not required to be computed from a CSPRNG, and may
+ /// even be entirely deterministic. Host implementations are encouraged to
+ /// provide pseudo-random values to any program exposed to
+ /// attacker-controlled content, to enable DoS protection built into many
+ /// languages' hash-map implementations.
+ ///
+ /// This function is intended to only be called once, by a source language
+ /// to initialize Denial Of Service (DoS) protection in its hash-map
+ /// implementation.
+ ///
+ /// # Expected future evolution
+ ///
+ /// This will likely be changed to a value import, to prevent it from being
+ /// called multiple times and potentially used for purposes other than DoS
+ /// protection.
+ @since(version = 0.2.0)
+ insecure-seed: func() -> tuple<u64, u64>;
+}
+
+/// The insecure interface for insecure pseudo-random numbers.
+///
+/// It is intended to be portable at least between Unix-family platforms and
+/// Windows.
+@since(version = 0.2.0)
+interface insecure {
+ /// Return `len` insecure pseudo-random bytes.
+ ///
+ /// This function is not cryptographically secure. Do not use it for
+ /// anything related to security.
+ ///
+ /// There are no requirements on the values of the returned bytes, however
+ /// implementations are encouraged to return evenly distributed values with
+ /// a long period.
+ @since(version = 0.2.0)
+ get-insecure-random-bytes: func(len: u64) -> list<u8>;
+
+ /// Return an insecure pseudo-random `u64` value.
+ ///
+ /// This function returns the same type of pseudo-random data as
+ /// `get-insecure-random-bytes`, represented as a `u64`.
+ @since(version = 0.2.0)
+ get-insecure-random-u64: func() -> u64;
+}
+
+/// WASI Random is a random data API.
+///
+/// It is intended to be portable at least between Unix-family platforms and
+/// Windows.
+@since(version = 0.2.0)
+interface random {
+ /// Return `len` cryptographically-secure random or pseudo-random bytes.
+ ///
+ /// This function must produce data at least as cryptographically secure and
+ /// fast as an adequately seeded cryptographically-secure pseudo-random
+ /// number generator (CSPRNG). It must not block, from the perspective of
+ /// the calling program, under any circumstances, including on the first
+ /// request and on requests for numbers of bytes. The returned data must
+ /// always be unpredictable.
+ ///
+ /// This function must always return fresh data. Deterministic environments
+ /// must omit this function, rather than implementing it with deterministic
+ /// data.
+ @since(version = 0.2.0)
+ get-random-bytes: func(len: u64) -> list<u8>;
+
+ /// Return a cryptographically-secure random or pseudo-random `u64` value.
+ ///
+ /// This function returns the same type of data as `get-random-bytes`,
+ /// represented as a `u64`.
+ @since(version = 0.2.0)
+ get-random-u64: func() -> u64;
+}
+
+@since(version = 0.2.0)
+world imports {
+ @since(version = 0.2.0)
+ import random;
+ @since(version = 0.2.0)
+ import insecure;
+ @since(version = 0.2.0)
+ import insecure-seed;
+}
diff --git a/crates/debugger/wit/deps/sockets.wit b/crates/debugger/wit/deps/sockets.wit
new file mode 100644
index 0000000000..db6d1a23b4
--- /dev/null
+++ b/crates/debugger/wit/deps/sockets.wit
@@ -0,0 +1,949 @@
+package wasi:[email protected];
+
+@since(version = 0.2.0)
+interface network {
+ @unstable(feature = network-error-code)
+ use wasi:io/[email protected].{error};
+
+ /// An opaque resource that represents access to (a subset of) the network.
+ /// This enables context-based security for networking.
+ /// There is no need for this to map 1:1 to a physical network interface.
+ @since(version = 0.2.0)
+ resource network;
+
+ /// Error codes.
+ ///
+ /// In theory, every API can return any error code.
+ /// In practice, API's typically only return the errors documented per API
+ /// combined with a couple of errors that are always possible:
+ /// - `unknown`
+ /// - `access-denied`
+ /// - `not-supported`
+ /// - `out-of-memory`
+ /// - `concurrency-conflict`
+ ///
+ /// See each individual API for what the POSIX equivalents are. They sometimes differ per API.
+ @since(version = 0.2.0)
+ enum error-code {
+ /// Unknown error
+ unknown,
+ /// Access denied.
+ ///
+ /// POSIX equivalent: EACCES, EPERM
+ access-denied,
+ /// The operation is not supported.
+ ///
+ /// POSIX equivalent: EOPNOTSUPP
+ not-supported,
+ /// One of the arguments is invalid.
+ ///
+ /// POSIX equivalent: EINVAL
+ invalid-argument,
+ /// Not enough memory to complete the operation.
+ ///
+ /// POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY
+ out-of-memory,
+ /// The operation timed out before it could finish completely.
+ timeout,
+ /// This operation is incompatible with another asynchronous operation that is already in progress.
+ ///
+ /// POSIX equivalent: EALREADY
+ concurrency-conflict,
+ /// Trying to finish an asynchronous operation that:
+ /// - has not been started yet, or:
+ /// - was already finished by a previous `finish-*` call.
+ ///
+ /// Note: this is scheduled to be removed when `future`s are natively supported.
+ not-in-progress,
+ /// The operation has been aborted because it could not be completed immediately.
+ ///
+ /// Note: this is scheduled to be removed when `future`s are natively supported.
+ would-block,
+ /// The operation is not valid in the socket's current state.
+ invalid-state,
+ /// A new socket resource could not be created because of a system limit.
+ new-socket-limit,
+ /// A bind operation failed because the provided address is not an address that the `network` can bind to.
+ address-not-bindable,
+ /// A bind operation failed because the provided address is already in use or because there are no ephemeral ports available.
+ address-in-use,
+ /// The remote address is not reachable
+ remote-unreachable,
+ /// The TCP connection was forcefully rejected
+ connection-refused,
+ /// The TCP connection was reset.
+ connection-reset,
+ /// A TCP connection was aborted.
+ connection-aborted,
+ /// The size of a datagram sent to a UDP socket exceeded the maximum
+ /// supported size.
+ datagram-too-large,
+ /// Name does not exist or has no suitable associated IP addresses.
+ name-unresolvable,
+ /// A temporary failure in name resolution occurred.
+ temporary-resolver-failure,
+ /// A permanent failure in name resolution occurred.
+ permanent-resolver-failure,
+ }
+
+ @since(version = 0.2.0)
+ enum ip-address-family {
+ /// Similar to `AF_INET` in POSIX.
+ ipv4,
+ /// Similar to `AF_INET6` in POSIX.
+ ipv6,
+ }
+
+ @since(version = 0.2.0)
+ type ipv4-address = tuple<u8, u8, u8, u8>;
+
+ @since(version = 0.2.0)
+ type ipv6-address = tuple<u16, u16, u16, u16, u16, u16, u16, u16>;
+
+ @since(version = 0.2.0)
+ variant ip-address {
+ ipv4(ipv4-address),
+ ipv6(ipv6-address),
+ }
+
+ @since(version = 0.2.0)
+ record ipv4-socket-address {
+ /// sin_port
+ port: u16,
+ /// sin_addr
+ address: ipv4-address,
+ }
+
+ @since(version = 0.2.0)
+ record ipv6-socket-address {
+ /// sin6_port
+ port: u16,
+ /// sin6_flowinfo
+ flow-info: u32,
+ /// sin6_addr
+ address: ipv6-address,
+ /// sin6_scope_id
+ scope-id: u32,
+ }
+
+ @since(version = 0.2.0)
+ variant ip-socket-address {
+ ipv4(ipv4-socket-address),
+ ipv6(ipv6-socket-address),
+ }
+
+ /// Attempts to extract a network-related `error-code` from the stream
+ /// `error` provided.
+ ///
+ /// Stream operations which return `stream-error::last-operation-failed`
+ /// have a payload with more information about the operation that failed.
+ /// This payload can be passed through to this function to see if there's
+ /// network-related information about the error to return.
+ ///
+ /// Note that this function is fallible because not all stream-related
+ /// errors are network-related errors.
+ @unstable(feature = network-error-code)
+ network-error-code: func(err: borrow<error>) -> option<error-code>;
+}
+
+/// This interface provides a value-export of the default network handle..
+@since(version = 0.2.0)
+interface instance-network {
+ @since(version = 0.2.0)
+ use network.{network};
+
+ /// Get a handle to the default network.
+ @since(version = 0.2.0)
+ instance-network: func() -> network;
+}
+
+@since(version = 0.2.0)
+interface ip-name-lookup {
+ @since(version = 0.2.0)
+ use wasi:io/[email protected].{pollable};
+ @since(version = 0.2.0)
+ use network.{network, error-code, ip-address};
+
+ @since(version = 0.2.0)
+ resource resolve-address-stream {
+ /// Returns the next address from the resolver.
+ ///
+ /// This function should be called multiple times. On each call, it will
+ /// return the next address in connection order preference. If all
+ /// addresses have been exhausted, this function returns `none`.
+ ///
+ /// This function never returns IPv4-mapped IPv6 addresses.
+ ///
+ /// # Typical errors
+ /// - `name-unresolvable`: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)
+ /// - `temporary-resolver-failure`: A temporary failure in name resolution occurred. (EAI_AGAIN)
+ /// - `permanent-resolver-failure`: A permanent failure in name resolution occurred. (EAI_FAIL)
+ /// - `would-block`: A result is not available yet. (EWOULDBLOCK, EAGAIN)
+ @since(version = 0.2.0)
+ resolve-next-address: func() -> result<option<ip-address>, error-code>;
+ /// Create a `pollable` which will resolve once the stream is ready for I/O.
+ ///
+ /// Note: this function is here for WASI 0.2 only.
+ /// It's planned to be removed when `future` is natively supported in Preview3.
+ @since(version = 0.2.0)
+ subscribe: func() -> pollable;
+ }
+
+ /// Resolve an internet host name to a list of IP addresses.
+ ///
+ /// Unicode domain names are automatically converted to ASCII using IDNA encoding.
+ /// If the input is an IP address string, the address is parsed and returned
+ /// as-is without making any external requests.
+ ///
+ /// See the wasi-socket proposal README.md for a comparison with getaddrinfo.
+ ///
+ /// This function never blocks. It either immediately fails or immediately
+ /// returns successfully with a `resolve-address-stream` that can be used
+ /// to (asynchronously) fetch the results.
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: `name` is a syntactically invalid domain name or IP address.
+ ///
+ /// # References:
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html>
+ /// - <https://man7.org/linux/man-pages/man3/getaddrinfo.3.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo>
+ /// - <https://man.freebsd.org/cgi/man.cgi?query=getaddrinfo&sektion=3>
+ @since(version = 0.2.0)
+ resolve-addresses: func(network: borrow<network>, name: string) -> result<resolve-address-stream, error-code>;
+}
+
+@since(version = 0.2.0)
+interface tcp {
+ @since(version = 0.2.0)
+ use wasi:io/[email protected].{input-stream, output-stream};
+ @since(version = 0.2.0)
+ use wasi:io/[email protected].{pollable};
+ @since(version = 0.2.0)
+ use wasi:clocks/[email protected].{duration};
+ @since(version = 0.2.0)
+ use network.{network, error-code, ip-socket-address, ip-address-family};
+
+ @since(version = 0.2.0)
+ enum shutdown-type {
+ /// Similar to `SHUT_RD` in POSIX.
+ receive,
+ /// Similar to `SHUT_WR` in POSIX.
+ send,
+ /// Similar to `SHUT_RDWR` in POSIX.
+ both,
+ }
+
+ /// A TCP socket resource.
+ ///
+ /// The socket can be in one of the following states:
+ /// - `unbound`
+ /// - `bind-in-progress`
+ /// - `bound` (See note below)
+ /// - `listen-in-progress`
+ /// - `listening`
+ /// - `connect-in-progress`
+ /// - `connected`
+ /// - `closed`
+ /// See <https://github.com/WebAssembly/wasi-sockets/blob/main/TcpSocketOperationalSemantics.md>
+ /// for more information.
+ ///
+ /// Note: Except where explicitly mentioned, whenever this documentation uses
+ /// the term "bound" without backticks it actually means: in the `bound` state *or higher*.
+ /// (i.e. `bound`, `listen-in-progress`, `listening`, `connect-in-progress` or `connected`)
+ ///
+ /// In addition to the general error codes documented on the
+ /// `network::error-code` type, TCP socket methods may always return
+ /// `error(invalid-state)` when in the `closed` state.
+ @since(version = 0.2.0)
+ resource tcp-socket {
+ /// Bind the socket to a specific network on the provided IP address and port.
+ ///
+ /// If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which
+ /// network interface(s) to bind to.
+ /// If the TCP/UDP port is zero, the socket will be bound to a random free port.
+ ///
+ /// Bind can be attempted multiple times on the same socket, even with
+ /// different arguments on each iteration. But never concurrently and
+ /// only as long as the previous bind failed. Once a bind succeeds, the
+ /// binding can't be changed anymore.
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
+ /// - `invalid-argument`: `local-address` is not a unicast address. (EINVAL)
+ /// - `invalid-argument`: `local-address` is an IPv4-mapped IPv6 address. (EINVAL)
+ /// - `invalid-state`: The socket is already bound. (EINVAL)
+ /// - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
+ /// - `address-in-use`: Address is already in use. (EADDRINUSE)
+ /// - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
+ /// - `not-in-progress`: A `bind` operation is not in progress.
+ /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
+ ///
+ /// # Implementors note
+ /// When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT
+ /// state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR
+ /// socket option should be set implicitly on all platforms, except on Windows where this is the default behavior
+ /// and SO_REUSEADDR performs something different entirely.
+ ///
+ /// Unlike in POSIX, in WASI the bind operation is async. This enables
+ /// interactive WASI hosts to inject permission prompts. Runtimes that
+ /// don't want to make use of this ability can simply call the native
+ /// `bind` as part of either `start-bind` or `finish-bind`.
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
+ /// - <https://man7.org/linux/man-pages/man2/bind.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind>
+ /// - <https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html>
+ @since(version = 0.2.0)
+ start-bind: func(network: borrow<network>, local-address: ip-socket-address) -> result<_, error-code>;
+ @since(version = 0.2.0)
+ finish-bind: func() -> result<_, error-code>;
+ /// Connect to a remote endpoint.
+ ///
+ /// On success:
+ /// - the socket is transitioned into the `connected` state.
+ /// - a pair of streams is returned that can be used to read & write to the connection
+ ///
+ /// After a failed connection attempt, the socket will be in the `closed`
+ /// state and the only valid action left is to `drop` the socket. A single
+ /// socket can not be used to connect more than once.
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
+ /// - `invalid-argument`: `remote-address` is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)
+ /// - `invalid-argument`: `remote-address` is an IPv4-mapped IPv6 address. (EINVAL, EADDRNOTAVAIL on Illumos)
+ /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EADDRNOTAVAIL on Windows)
+ /// - `invalid-argument`: The port in `remote-address` is set to 0. (EADDRNOTAVAIL on Windows)
+ /// - `invalid-argument`: The socket is already attached to a different network. The `network` passed to `connect` must be identical to the one passed to `bind`.
+ /// - `invalid-state`: The socket is already in the `connected` state. (EISCONN)
+ /// - `invalid-state`: The socket is already in the `listening` state. (EOPNOTSUPP, EINVAL on Windows)
+ /// - `timeout`: Connection timed out. (ETIMEDOUT)
+ /// - `connection-refused`: The connection was forcefully rejected. (ECONNREFUSED)
+ /// - `connection-reset`: The connection was reset. (ECONNRESET)
+ /// - `connection-aborted`: The connection was aborted. (ECONNABORTED)
+ /// - `remote-unreachable`: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
+ /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
+ /// - `not-in-progress`: A connect operation is not in progress.
+ /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
+ ///
+ /// # Implementors note
+ /// The POSIX equivalent of `start-connect` is the regular `connect` syscall.
+ /// Because all WASI sockets are non-blocking this is expected to return
+ /// EINPROGRESS, which should be translated to `ok()` in WASI.
+ ///
+ /// The POSIX equivalent of `finish-connect` is a `poll` for event `POLLOUT`
+ /// with a timeout of 0 on the socket descriptor. Followed by a check for
+ /// the `SO_ERROR` socket option, in case the poll signaled readiness.
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
+ /// - <https://man7.org/linux/man-pages/man2/connect.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
+ /// - <https://man.freebsd.org/cgi/man.cgi?connect>
+ @since(version = 0.2.0)
+ start-connect: func(network: borrow<network>, remote-address: ip-socket-address) -> result<_, error-code>;
+ @since(version = 0.2.0)
+ finish-connect: func() -> result<tuple<input-stream, output-stream>, error-code>;
+ /// Start listening for new connections.
+ ///
+ /// Transitions the socket into the `listening` state.
+ ///
+ /// Unlike POSIX, the socket must already be explicitly bound.
+ ///
+ /// # Typical errors
+ /// - `invalid-state`: The socket is not bound to any local address. (EDESTADDRREQ)
+ /// - `invalid-state`: The socket is already in the `connected` state. (EISCONN, EINVAL on BSD)
+ /// - `invalid-state`: The socket is already in the `listening` state.
+ /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)
+ /// - `not-in-progress`: A listen operation is not in progress.
+ /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
+ ///
+ /// # Implementors note
+ /// Unlike in POSIX, in WASI the listen operation is async. This enables
+ /// interactive WASI hosts to inject permission prompts. Runtimes that
+ /// don't want to make use of this ability can simply call the native
+ /// `listen` as part of either `start-listen` or `finish-listen`.
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html>
+ /// - <https://man7.org/linux/man-pages/man2/listen.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen>
+ /// - <https://man.freebsd.org/cgi/man.cgi?query=listen&sektion=2>
+ @since(version = 0.2.0)
+ start-listen: func() -> result<_, error-code>;
+ @since(version = 0.2.0)
+ finish-listen: func() -> result<_, error-code>;
+ /// Accept a new client socket.
+ ///
+ /// The returned socket is bound and in the `connected` state. The following properties are inherited from the listener socket:
+ /// - `address-family`
+ /// - `keep-alive-enabled`
+ /// - `keep-alive-idle-time`
+ /// - `keep-alive-interval`
+ /// - `keep-alive-count`
+ /// - `hop-limit`
+ /// - `receive-buffer-size`
+ /// - `send-buffer-size`
+ ///
+ /// On success, this function returns the newly accepted client socket along with
+ /// a pair of streams that can be used to read & write to the connection.
+ ///
+ /// # Typical errors
+ /// - `invalid-state`: Socket is not in the `listening` state. (EINVAL)
+ /// - `would-block`: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)
+ /// - `connection-aborted`: An incoming connection was pending, but was terminated by the client before this listener could accept it. (ECONNABORTED)
+ /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html>
+ /// - <https://man7.org/linux/man-pages/man2/accept.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept>
+ /// - <https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2>
+ @since(version = 0.2.0)
+ accept: func() -> result<tuple<tcp-socket, input-stream, output-stream>, error-code>;
+ /// Get the bound local address.
+ ///
+ /// POSIX mentions:
+ /// > If the socket has not been bound to a local name, the value
+ /// > stored in the object pointed to by `address` is unspecified.
+ ///
+ /// WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet.
+ ///
+ /// # Typical errors
+ /// - `invalid-state`: The socket is not bound to any local address.
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html>
+ /// - <https://man7.org/linux/man-pages/man2/getsockname.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname>
+ /// - <https://man.freebsd.org/cgi/man.cgi?getsockname>
+ @since(version = 0.2.0)
+ local-address: func() -> result<ip-socket-address, error-code>;
+ /// Get the remote address.
+ ///
+ /// # Typical errors
+ /// - `invalid-state`: The socket is not connected to a remote address. (ENOTCONN)
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html>
+ /// - <https://man7.org/linux/man-pages/man2/getpeername.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername>
+ /// - <https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1>
+ @since(version = 0.2.0)
+ remote-address: func() -> result<ip-socket-address, error-code>;
+ /// Whether the socket is in the `listening` state.
+ ///
+ /// Equivalent to the SO_ACCEPTCONN socket option.
+ @since(version = 0.2.0)
+ is-listening: func() -> bool;
+ /// Whether this is a IPv4 or IPv6 socket.
+ ///
+ /// Equivalent to the SO_DOMAIN socket option.
+ @since(version = 0.2.0)
+ address-family: func() -> ip-address-family;
+ /// Hints the desired listen queue size. Implementations are free to ignore this.
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
+ ///
+ /// # Typical errors
+ /// - `not-supported`: (set) The platform does not support changing the backlog size after the initial listen.
+ /// - `invalid-argument`: (set) The provided value was 0.
+ /// - `invalid-state`: (set) The socket is in the `connect-in-progress` or `connected` state.
+ @since(version = 0.2.0)
+ set-listen-backlog-size: func(value: u64) -> result<_, error-code>;
+ /// Enables or disables keepalive.
+ ///
+ /// The keepalive behavior can be adjusted using:
+ /// - `keep-alive-idle-time`
+ /// - `keep-alive-interval`
+ /// - `keep-alive-count`
+ /// These properties can be configured while `keep-alive-enabled` is false, but only come into effect when `keep-alive-enabled` is true.
+ ///
+ /// Equivalent to the SO_KEEPALIVE socket option.
+ @since(version = 0.2.0)
+ keep-alive-enabled: func() -> result<bool, error-code>;
+ @since(version = 0.2.0)
+ set-keep-alive-enabled: func(value: bool) -> result<_, error-code>;
+ /// Amount of time the connection has to be idle before TCP starts sending keepalive packets.
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
+ /// I.e. after setting a value, reading the same setting back may return a different value.
+ ///
+ /// Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: (set) The provided value was 0.
+ @since(version = 0.2.0)
+ keep-alive-idle-time: func() -> result<duration, error-code>;
+ @since(version = 0.2.0)
+ set-keep-alive-idle-time: func(value: duration) -> result<_, error-code>;
+ /// The time between keepalive packets.
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
+ /// I.e. after setting a value, reading the same setting back may return a different value.
+ ///
+ /// Equivalent to the TCP_KEEPINTVL socket option.
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: (set) The provided value was 0.
+ @since(version = 0.2.0)
+ keep-alive-interval: func() -> result<duration, error-code>;
+ @since(version = 0.2.0)
+ set-keep-alive-interval: func(value: duration) -> result<_, error-code>;
+ /// The maximum amount of keepalive packets TCP should send before aborting the connection.
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
+ /// I.e. after setting a value, reading the same setting back may return a different value.
+ ///
+ /// Equivalent to the TCP_KEEPCNT socket option.
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: (set) The provided value was 0.
+ @since(version = 0.2.0)
+ keep-alive-count: func() -> result<u32, error-code>;
+ @since(version = 0.2.0)
+ set-keep-alive-count: func(value: u32) -> result<_, error-code>;
+ /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: (set) The TTL value must be 1 or higher.
+ @since(version = 0.2.0)
+ hop-limit: func() -> result<u8, error-code>;
+ @since(version = 0.2.0)
+ set-hop-limit: func(value: u8) -> result<_, error-code>;
+ /// The kernel buffer space reserved for sends/receives on this socket.
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
+ /// I.e. after setting a value, reading the same setting back may return a different value.
+ ///
+ /// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: (set) The provided value was 0.
+ @since(version = 0.2.0)
+ receive-buffer-size: func() -> result<u64, error-code>;
+ @since(version = 0.2.0)
+ set-receive-buffer-size: func(value: u64) -> result<_, error-code>;
+ @since(version = 0.2.0)
+ send-buffer-size: func() -> result<u64, error-code>;
+ @since(version = 0.2.0)
+ set-send-buffer-size: func(value: u64) -> result<_, error-code>;
+ /// Create a `pollable` which can be used to poll for, or block on,
+ /// completion of any of the asynchronous operations of this socket.
+ ///
+ /// When `finish-bind`, `finish-listen`, `finish-connect` or `accept`
+ /// return `error(would-block)`, this pollable can be used to wait for
+ /// their success or failure, after which the method can be retried.
+ ///
+ /// The pollable is not limited to the async operation that happens to be
+ /// in progress at the time of calling `subscribe` (if any). Theoretically,
+ /// `subscribe` only has to be called once per socket and can then be
+ /// (re)used for the remainder of the socket's lifetime.
+ ///
+ /// See <https://github.com/WebAssembly/wasi-sockets/blob/main/TcpSocketOperationalSemantics.md#pollable-readiness>
+ /// for more information.
+ ///
+ /// Note: this function is here for WASI 0.2 only.
+ /// It's planned to be removed when `future` is natively supported in Preview3.
+ @since(version = 0.2.0)
+ subscribe: func() -> pollable;
+ /// Initiate a graceful shutdown.
+ ///
+ /// - `receive`: The socket is not expecting to receive any data from
+ /// the peer. The `input-stream` associated with this socket will be
+ /// closed. Any data still in the receive queue at time of calling
+ /// this method will be discarded.
+ /// - `send`: The socket has no more data to send to the peer. The `output-stream`
+ /// associated with this socket will be closed and a FIN packet will be sent.
+ /// - `both`: Same effect as `receive` & `send` combined.
+ ///
+ /// This function is idempotent; shutting down a direction more than once
+ /// has no effect and returns `ok`.
+ ///
+ /// The shutdown function does not close (drop) the socket.
+ ///
+ /// # Typical errors
+ /// - `invalid-state`: The socket is not in the `connected` state. (ENOTCONN)
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html>
+ /// - <https://man7.org/linux/man-pages/man2/shutdown.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-shutdown>
+ /// - <https://man.freebsd.org/cgi/man.cgi?query=shutdown&sektion=2>
+ @since(version = 0.2.0)
+ shutdown: func(shutdown-type: shutdown-type) -> result<_, error-code>;
+ }
+}
+
+@since(version = 0.2.0)
+interface tcp-create-socket {
+ @since(version = 0.2.0)
+ use network.{network, error-code, ip-address-family};
+ @since(version = 0.2.0)
+ use tcp.{tcp-socket};
+
+ /// Create a new TCP socket.
+ ///
+ /// Similar to `socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP)` in POSIX.
+ /// On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.
+ ///
+ /// This function does not require a network capability handle. This is considered to be safe because
+ /// at time of creation, the socket is not bound to any `network` yet. Up to the moment `bind`/`connect`
+ /// is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.
+ ///
+ /// All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.
+ ///
+ /// # Typical errors
+ /// - `not-supported`: The specified `address-family` is not supported. (EAFNOSUPPORT)
+ /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html>
+ /// - <https://man7.org/linux/man-pages/man2/socket.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasocketw>
+ /// - <https://man.freebsd.org/cgi/man.cgi?query=socket&sektion=2>
+ @since(version = 0.2.0)
+ create-tcp-socket: func(address-family: ip-address-family) -> result<tcp-socket, error-code>;
+}
+
+@since(version = 0.2.0)
+interface udp {
+ @since(version = 0.2.0)
+ use wasi:io/[email protected].{pollable};
+ @since(version = 0.2.0)
+ use network.{network, error-code, ip-socket-address, ip-address-family};
+
+ /// A received datagram.
+ @since(version = 0.2.0)
+ record incoming-datagram {
+ /// The payload.
+ ///
+ /// Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.
+ data: list<u8>,
+ /// The source address.
+ ///
+ /// This field is guaranteed to match the remote address the stream was initialized with, if any.
+ ///
+ /// Equivalent to the `src_addr` out parameter of `recvfrom`.
+ remote-address: ip-socket-address,
+ }
+
+ /// A datagram to be sent out.
+ @since(version = 0.2.0)
+ record outgoing-datagram {
+ /// The payload.
+ data: list<u8>,
+ /// The destination address.
+ ///
+ /// The requirements on this field depend on how the stream was initialized:
+ /// - with a remote address: this field must be None or match the stream's remote address exactly.
+ /// - without a remote address: this field is required.
+ ///
+ /// If this value is None, the send operation is equivalent to `send` in POSIX. Otherwise it is equivalent to `sendto`.
+ remote-address: option<ip-socket-address>,
+ }
+
+ /// A UDP socket handle.
+ @since(version = 0.2.0)
+ resource udp-socket {
+ /// Bind the socket to a specific network on the provided IP address and port.
+ ///
+ /// If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which
+ /// network interface(s) to bind to.
+ /// If the port is zero, the socket will be bound to a random free port.
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
+ /// - `invalid-state`: The socket is already bound. (EINVAL)
+ /// - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
+ /// - `address-in-use`: Address is already in use. (EADDRINUSE)
+ /// - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
+ /// - `not-in-progress`: A `bind` operation is not in progress.
+ /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
+ ///
+ /// # Implementors note
+ /// Unlike in POSIX, in WASI the bind operation is async. This enables
+ /// interactive WASI hosts to inject permission prompts. Runtimes that
+ /// don't want to make use of this ability can simply call the native
+ /// `bind` as part of either `start-bind` or `finish-bind`.
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
+ /// - <https://man7.org/linux/man-pages/man2/bind.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind>
+ /// - <https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html>
+ @since(version = 0.2.0)
+ start-bind: func(network: borrow<network>, local-address: ip-socket-address) -> result<_, error-code>;
+ @since(version = 0.2.0)
+ finish-bind: func() -> result<_, error-code>;
+ /// Set up inbound & outbound communication channels, optionally to a specific peer.
+ ///
+ /// This function only changes the local socket configuration and does not generate any network traffic.
+ /// On success, the `remote-address` of the socket is updated. The `local-address` may be updated as well,
+ /// based on the best network path to `remote-address`.
+ ///
+ /// When a `remote-address` is provided, the returned streams are limited to communicating with that specific peer:
+ /// - `send` can only be used to send to this destination.
+ /// - `receive` will only return datagrams sent from the provided `remote-address`.
+ ///
+ /// This method may be called multiple times on the same socket to change its association, but
+ /// only the most recently returned pair of streams will be operational. Implementations may trap if
+ /// the streams returned by a previous invocation haven't been dropped yet before calling `stream` again.
+ ///
+ /// The POSIX equivalent in pseudo-code is:
+ /// ```text
+ /// if (was previously connected) {
+ /// connect(s, AF_UNSPEC)
+ /// }
+ /// if (remote_address is Some) {
+ /// connect(s, remote_address)
+ /// }
+ /// ```
+ ///
+ /// Unlike in POSIX, the socket must already be explicitly bound.
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
+ /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
+ /// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
+ /// - `invalid-state`: The socket is not bound.
+ /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
+ /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
+ /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
+ /// - <https://man7.org/linux/man-pages/man2/connect.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
+ /// - <https://man.freebsd.org/cgi/man.cgi?connect>
+ @since(version = 0.2.0)
+ %stream: func(remote-address: option<ip-socket-address>) -> result<tuple<incoming-datagram-stream, outgoing-datagram-stream>, error-code>;
+ /// Get the current bound address.
+ ///
+ /// POSIX mentions:
+ /// > If the socket has not been bound to a local name, the value
+ /// > stored in the object pointed to by `address` is unspecified.
+ ///
+ /// WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet.
+ ///
+ /// # Typical errors
+ /// - `invalid-state`: The socket is not bound to any local address.
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html>
+ /// - <https://man7.org/linux/man-pages/man2/getsockname.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname>
+ /// - <https://man.freebsd.org/cgi/man.cgi?getsockname>
+ @since(version = 0.2.0)
+ local-address: func() -> result<ip-socket-address, error-code>;
+ /// Get the address the socket is currently streaming to.
+ ///
+ /// # Typical errors
+ /// - `invalid-state`: The socket is not streaming to a specific remote address. (ENOTCONN)
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html>
+ /// - <https://man7.org/linux/man-pages/man2/getpeername.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername>
+ /// - <https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1>
+ @since(version = 0.2.0)
+ remote-address: func() -> result<ip-socket-address, error-code>;
+ /// Whether this is a IPv4 or IPv6 socket.
+ ///
+ /// Equivalent to the SO_DOMAIN socket option.
+ @since(version = 0.2.0)
+ address-family: func() -> ip-address-family;
+ /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: (set) The TTL value must be 1 or higher.
+ @since(version = 0.2.0)
+ unicast-hop-limit: func() -> result<u8, error-code>;
+ @since(version = 0.2.0)
+ set-unicast-hop-limit: func(value: u8) -> result<_, error-code>;
+ /// The kernel buffer space reserved for sends/receives on this socket.
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
+ /// I.e. after setting a value, reading the same setting back may return a different value.
+ ///
+ /// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: (set) The provided value was 0.
+ @since(version = 0.2.0)
+ receive-buffer-size: func() -> result<u64, error-code>;
+ @since(version = 0.2.0)
+ set-receive-buffer-size: func(value: u64) -> result<_, error-code>;
+ @since(version = 0.2.0)
+ send-buffer-size: func() -> result<u64, error-code>;
+ @since(version = 0.2.0)
+ set-send-buffer-size: func(value: u64) -> result<_, error-code>;
+ /// Create a `pollable` which will resolve once the socket is ready for I/O.
+ ///
+ /// Note: this function is here for WASI 0.2 only.
+ /// It's planned to be removed when `future` is natively supported in Preview3.
+ @since(version = 0.2.0)
+ subscribe: func() -> pollable;
+ }
+
+ @since(version = 0.2.0)
+ resource incoming-datagram-stream {
+ /// Receive messages on the socket.
+ ///
+ /// This function attempts to receive up to `max-results` datagrams on the socket without blocking.
+ /// The returned list may contain fewer elements than requested, but never more.
+ ///
+ /// This function returns successfully with an empty list when either:
+ /// - `max-results` is 0, or:
+ /// - `max-results` is greater than 0, but no results are immediately available.
+ /// This function never returns `error(would-block)`.
+ ///
+ /// # Typical errors
+ /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
+ /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvfrom.html>
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvmsg.html>
+ /// - <https://man7.org/linux/man-pages/man2/recv.2.html>
+ /// - <https://man7.org/linux/man-pages/man2/recvmmsg.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recv>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recvfrom>
+ /// - <https://learn.microsoft.com/en-us/previous-versions/windows/desktop/legacy/ms741687(v=vs.85)>
+ /// - <https://man.freebsd.org/cgi/man.cgi?query=recv&sektion=2>
+ @since(version = 0.2.0)
+ receive: func(max-results: u64) -> result<list<incoming-datagram>, error-code>;
+ /// Create a `pollable` which will resolve once the stream is ready to receive again.
+ ///
+ /// Note: this function is here for WASI 0.2 only.
+ /// It's planned to be removed when `future` is natively supported in Preview3.
+ @since(version = 0.2.0)
+ subscribe: func() -> pollable;
+ }
+
+ @since(version = 0.2.0)
+ resource outgoing-datagram-stream {
+ /// Check readiness for sending. This function never blocks.
+ ///
+ /// Returns the number of datagrams permitted for the next call to `send`,
+ /// or an error. Calling `send` with more datagrams than this function has
+ /// permitted will trap.
+ ///
+ /// When this function returns ok(0), the `subscribe` pollable will
+ /// become ready when this function will report at least ok(1), or an
+ /// error.
+ ///
+ /// Never returns `would-block`.
+ check-send: func() -> result<u64, error-code>;
+ /// Send messages on the socket.
+ ///
+ /// This function attempts to send all provided `datagrams` on the socket without blocking and
+ /// returns how many messages were actually sent (or queued for sending). This function never
+ /// returns `error(would-block)`. If none of the datagrams were able to be sent, `ok(0)` is returned.
+ ///
+ /// This function semantically behaves the same as iterating the `datagrams` list and sequentially
+ /// sending each individual datagram until either the end of the list has been reached or the first error occurred.
+ /// If at least one datagram has been sent successfully, this function never returns an error.
+ ///
+ /// If the input list is empty, the function returns `ok(0)`.
+ ///
+ /// Each call to `send` must be permitted by a preceding `check-send`. Implementations must trap if
+ /// either `check-send` was not called or `datagrams` contains more items than `check-send` permitted.
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
+ /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
+ /// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
+ /// - `invalid-argument`: The socket is in "connected" mode and `remote-address` is `some` value that does not match the address passed to `stream`. (EISCONN)
+ /// - `invalid-argument`: The socket is not "connected" and no value for `remote-address` was provided. (EDESTADDRREQ)
+ /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
+ /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
+ /// - `datagram-too-large`: The datagram is too large. (EMSGSIZE)
+ ///
+ /// # References
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendto.html>
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendmsg.html>
+ /// - <https://man7.org/linux/man-pages/man2/send.2.html>
+ /// - <https://man7.org/linux/man-pages/man2/sendmmsg.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-send>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-sendto>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasendmsg>
+ /// - <https://man.freebsd.org/cgi/man.cgi?query=send&sektion=2>
+ @since(version = 0.2.0)
+ send: func(datagrams: list<outgoing-datagram>) -> result<u64, error-code>;
+ /// Create a `pollable` which will resolve once the stream is ready to send again.
+ ///
+ /// Note: this function is here for WASI 0.2 only.
+ /// It's planned to be removed when `future` is natively supported in Preview3.
+ @since(version = 0.2.0)
+ subscribe: func() -> pollable;
+ }
+}
+
+@since(version = 0.2.0)
+interface udp-create-socket {
+ @since(version = 0.2.0)
+ use network.{network, error-code, ip-address-family};
+ @since(version = 0.2.0)
+ use udp.{udp-socket};
+
+ /// Create a new UDP socket.
+ ///
+ /// Similar to `socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP)` in POSIX.
+ /// On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.
+ ///
+ /// This function does not require a network capability handle. This is considered to be safe because
+ /// at time of creation, the socket is not bound to any `network` yet. Up to the moment `bind` is called,
+ /// the socket is effectively an in-memory configuration object, unable to communicate with the outside world.
+ ///
+ /// All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.
+ ///
+ /// # Typical errors
+ /// - `not-supported`: The specified `address-family` is not supported. (EAFNOSUPPORT)
+ /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
+ ///
+ /// # References:
+ /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html>
+ /// - <https://man7.org/linux/man-pages/man2/socket.2.html>
+ /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasocketw>
+ /// - <https://man.freebsd.org/cgi/man.cgi?query=socket&sektion=2>
+ @since(version = 0.2.0)
+ create-udp-socket: func(address-family: ip-address-family) -> result<udp-socket, error-code>;
+}
+
+@since(version = 0.2.0)
+world imports {
+ @since(version = 0.2.0)
+ import wasi:io/[email protected];
+ @since(version = 0.2.0)
+ import network;
+ @since(version = 0.2.0)
+ import instance-network;
+ @since(version = 0.2.0)
+ import wasi:io/[email protected];
+ @since(version = 0.2.0)
+ import udp;
+ @since(version = 0.2.0)
+ import udp-create-socket;
+ @since(version = 0.2.0)
+ import wasi:io/[email protected];
+ @since(version = 0.2.0)
+ import wasi:clocks/[email protected];
+ @since(version = 0.2.0)
+ import tcp;
+ @since(version = 0.2.0)
+ import tcp-create-socket;
+ @since(version = 0.2.0)
+ import ip-name-lookup;
+}
diff --git a/crates/debugger/wit/world.wit b/crates/debugger/wit/world.wit
new file mode 100644
index 0000000000..09c88d95fb
--- /dev/null
+++ b/crates/debugger/wit/world.wit
@@ -0,0 +1,395 @@
+package bytecodealliance:[email protected];
+
+world debug-main {
+ import wasi:io/[email protected];
+ import debuggee;
+ export debugger;
+}
+
+interface debugger {
+ use debuggee.{debuggee};
+
+ /// Launch the debugger top-half (e.g., protocol server or UI)
+ /// implemented by this component, given the provided interface
+ /// to a debuggee. The debuggee will be paused and awaiting
+ /// a resumption.
+ ///
+ /// `args` contains the command-line arguments of the debugger,
+ /// starting with the program name (args[0]).
+ debug: func(d: borrow<debuggee>, args: list<string>);
+}
+
+interface debuggee {
+ use wasi:io/[email protected].{pollable};
+
+ /// A debuggee consisting of one Store over which we have
+ /// debugging control.
+ ///
+ /// A debuggee is always either "paused" or "running", and certain
+ /// methods below are only available in one or the other state.
+ resource debuggee {
+ /// List all modules that exist in the Store.
+ ///
+ /// If invoked while already running, causes a trap.
+ all-modules: func() -> list<module>;
+
+ /// List of all instances that exist in the Store.
+ ///
+ /// If invoked while already running, causes a trap.
+ all-instances: func() -> list<instance>;
+
+ /// Force an interruption event in any running code.
+ ///
+ /// Usable in paused or running states. If invoked in
+ /// the paused state, the next execution will immediately
+ /// yield an "interrupted" event.
+ interrupt: func();
+
+ /// Single-step, returning a future that will yield an event
+ /// when the single-step execution is complete.
+ ///
+ /// The `resumption` value indicates any mutations to
+ /// perform to execution state as part of resuming:
+ /// for example, injecting a call to another function,
+ /// or throwing an exception, or forcing an early return
+ /// from the current function.
+ ///
+ /// Usable in paused state; transitions to running state.
+ /// Debuggee remains in running state until the returned
+ /// future completes.
+ ///
+ /// If invoked while already running, causes a trap.
+ single-step: func(resumption: resumption-value) -> event-future;
+
+ /// Continue execution, returning a future that will
+ /// yield an event when the resumed execution
+ /// is complete.
+ ///
+ /// The `resumption` value indicates any mutations to
+ /// perform to execution state as part of resuming:
+ /// for example, injecting a call to another function,
+ /// or throwing an exception, or forcing an early return
+ /// from the current function.
+ ///
+ /// Usable in paused state; transitions to running state.
+ /// Debuggee remains in running state until the returned
+ /// future completes.
+ ///
+ /// If invoked while already running, causes a trap.
+ continue: func(resumption: resumption-value) -> event-future;
+
+ /// Get the current exit frames for each activation.
+ ///
+ /// If invoked while already running, causes a trap.
+ exit-frames: func() -> list<frame>;
+ }
+
+ /// A future that represents asynchronous execution of the
+ /// debuggee until the next debug event pausing execution.
+ ///
+ /// When complete, yields the resulting debug event.
+ resource event-future {
+ /// Subscribe to this future, returning a wasi-io pollable.
+ subscribe: func() -> pollable;
+
+ /// Consume this future, producing the resulting
+ /// event. Blocks if not ready. The debuggee
+ /// must be provided as well.
+ finish: static func(self: event-future, debuggee: borrow<debuggee>) -> result<event, error>;
+ }
+
+ /// A `resumption` value indicates how we want to continue
+ /// execution after a pause.
+ ///
+ /// By default, if we are a "read-only" debugger, there is only
+ /// one answer: with no mutation, according to the abstract
+ /// Wasm machine semantics and current machine state.
+ ///
+ /// However, this interface also supports various kinds of mutations.
+ /// For example, the debugger can ask to insert a call to an arbitrary
+ /// Wasm function, it can force an early return from the current function,
+ /// or it can throw an exception.
+ ///
+ /// This `resumption` value is orthogonal to the
+ /// `continue` vs. `single-step` resume axis:
+ /// the resumption value indicates whether we want to mutate
+ /// the executing abstract machine's *state*, while the single-step
+ /// vs. continue axis indicates how we want to step that machine
+ /// forward from whatever state is indicated (i.e., one step or
+ /// many until an event).
+ variant resumption-value {
+ /// Resume normally: do not alter the machine state.
+ normal,
+ /// Inject a call to a Wasm function at the current point, as-if
+ /// the program contained a `call` instruction with the given
+ /// values on the operand stack.
+ ///
+ /// Execution is subject to ordinary debugger events as with
+ /// any other; e.g., the function we call may experience breakpoint
+ /// pauses, may be single-stepped if we resume with `single-step`,
+ /// etc.
+ ///
+ /// If the injected function call completes normally, an
+ /// `injected-call-return` debug event is raised with the
+ /// return value(s).
+ inject-call(inject-call),
+ /// Resume as-if an exception were thrown at the current point.
+ throw-exception(wasm-exception),
+ /// Force a return from the current function frame, with the given
+ /// value(s) as return value(s).
+ early-return(list<wasm-value>),
+ }
+
+ /// A function call to be injected upon resumption.
+ record inject-call {
+ callee: wasm-func,
+ arguments: list<wasm-value>,
+ }
+
+ /// A debug event.
+ variant event {
+ /// Execution of the debuggee has completed.
+ complete,
+ /// A trap occurred in the debuggee. Execution
+ /// is paused at the trap-point, and will terminate
+ /// when resuming execution.
+ trap,
+ /// A breakpoint was hit in the debuggee, pausing
+ /// execution.
+ breakpoint,
+ /// An interruption due to `debuggee.interrupt` occurred.
+ interrupted,
+ /// An exception was thrown and caught by Wasm.
+ caught-exception-thrown(wasm-exception),
+ /// An exception was thrown and not caught by Wasm.
+ uncaught-exception-thrown(wasm-exception),
+ /// An injected call completed with return value(s).
+ injected-call-return(list<wasm-value>),
+ }
+
+ resource instance {
+ /// Get this instance's module.
+ get-module: func(d: borrow<debuggee>) -> module;
+
+ /// Get a memory from this instance's memory index space.
+ get-memory: func(d: borrow<debuggee>, memory-index: u32) -> result<memory, error>;
+
+ /// Get a global from this instance's global index space.
+ get-global: func(d: borrow<debuggee>, global-index: u32) -> result<global, error>;
+
+ /// Get a table from this instance's table index space.
+ get-table: func(d: borrow<debuggee>, table-index: u32) -> result<table, error>;
+
+ /// Get a function from this instance's function index space.
+ get-func: func(d: borrow<debuggee>, func-index: u32) -> result<wasm-func, error>;
+
+ /// Get a tag from this instance's tag index space.
+ get-tag: func(d: borrow<debuggee>, tag-index: u32) -> result<wasm-tag, error>;
+
+ /// Clone this handle.
+ clone: func() -> instance;
+
+ /// Get the unique ID of this instance (within the debuggee)
+ /// to allow equality and hashing.
+ unique-id: func() -> u64;
+ }
+
+ resource module {
+ /// Get the original Wasm bytecode for this module, if available.
+ bytecode: func() -> option<list<u8>>;
+
+ /// Add a breakpoint.
+ add-breakpoint: func(d: borrow<debuggee>, pc: u32) -> result<_, error>;
+
+ /// Remove a breakpoint.
+ remove-breakpoint: func(d: borrow<debuggee>, pc: u32) -> result<_, error>;
+
+ /// Clone this handle.
+ clone: func() -> module;
+
+ /// Get the unique ID of this module to allow equality and hashing.
+ unique-id: func() -> u64;
+ }
+
+ resource memory {
+ /// Get the current memory size, in bytes.
+ size-bytes: func(d: borrow<debuggee>) -> u64;
+
+ /// Get the page size, in bytes.
+ page-size-bytes: func(d: borrow<debuggee>) -> u64;
+
+ /// Increase size by the given `delta`. Returns the old size in bytes.
+ grow-to-bytes: func(d: borrow<debuggee>, delta: u64) -> result<u64, error>;
+
+ /// Read `len` bytes starting at `addr`. Returns `out-of-bounds` if any
+ /// byte in the range is out-of-bounds.
+ get-bytes: func(d: borrow<debuggee>, addr: u64, len: u64) -> result<list<u8>, error>;
+
+ /// Write `bytes` starting at `addr`. Returns `out-of-bounds` if any
+ /// byte in the range is out-of-bounds.
+ set-bytes: func(d: borrow<debuggee>, addr: u64, bytes: list<u8>) -> result<_, error>;
+
+ /// Get a u8 (byte) at an address. Returns `none` if out-of-bounds.
+ get-u8: func(d: borrow<debuggee>, addr: u64) -> result<u8, error>;
+ /// Get a u16 (in little endian order) at an address.
+ get-u16: func(d: borrow<debuggee>, addr: u64) -> result<u16, error>;
+ /// Get a u32 (in little endian order) at an address.
+ get-u32: func(d: borrow<debuggee>, addr: u64) -> result<u32, error>;
+ /// Get a u64 (in little endian order) at an address.
+ get-u64: func(d: borrow<debuggee>, addr: u64) -> result<u64, error>;
+
+ /// Set a u8 (byte) at an address. Returns `none` if out-of-bounds.
+ set-u8: func(d: borrow<debuggee>, addr: u64, value: u8) -> result<_, error>;
+ /// Set a u16 (in little endian order) at an address.
+ set-u16: func(d: borrow<debuggee>, addr: u64, value: u16) -> result<_, error>;
+ /// Set a u32 (in little endian order) at an address.
+ set-u32: func(d: borrow<debuggee>, addr: u64, value: u32) -> result<_, error>;
+ /// Set a u64 (in little endian order) at an address.
+ set-u64: func(d: borrow<debuggee>, addr: u64, value: u64) -> result<_, error>;
+
+ /// Clone this handle.
+ clone: func() -> memory;
+
+ /// Get the unique ID of this memory to allow equality and hashing.
+ unique-id: func() -> u64;
+ }
+
+ resource global {
+ /// Get the value of this global.
+ get: func(d: borrow<debuggee>) -> result<wasm-value, error>;
+
+ /// Set the value of this global.
+ set: func(d: borrow<debuggee>, val: wasm-value) -> result<_, error>;
+
+ /// Clone this handle.
+ clone: func() -> global;
+
+ /// Get the unique ID of this memory to allow equality and hashing.
+ unique-id: func() -> u64;
+ }
+
+ resource table {
+ /// Get the current length of this table, in elements.
+ len: func(d: borrow<debuggee>) -> u64;
+
+ /// Get the value at the Nth slot.
+ get-element: func(d: borrow<debuggee>, index: u64) -> result<wasm-value, error>;
+
+ /// Set the value at the Nth slot.
+ set-element: func(d: borrow<debuggee>, index: u64, val: wasm-value) -> result<_, error>;
+
+ /// Clone this handle.
+ clone: func() -> table;
+
+ /// Get the unique ID of this memory to allow equality and hashing.
+ unique-id: func() -> u64;
+ }
+
+ resource wasm-func {
+ /// Get the parameter types.
+ params: func(d: borrow<debuggee>) -> result<list<wasm-type>, error>;
+
+ /// Get the result types.
+ results: func(d: borrow<debuggee>) -> result<list<wasm-type>, error>;
+
+ /// Clone this handle.
+ clone: func() -> wasm-func;
+ }
+
+ resource wasm-exception {
+ /// Get the tag of this exception.
+ get-tag: func(d: borrow<debuggee>) -> wasm-tag;
+
+ /// Get the payload values of this exception.
+ get-values: func(d: borrow<debuggee>) -> result<list<wasm-value>, error>;
+
+ /// Clone this reference.
+ clone: func(d: borrow<debuggee>) -> wasm-exception;
+
+ /// Allocate a new exception.
+ make: static func(
+ d: borrow<debuggee>,
+ tag: borrow<wasm-tag>,
+ values: list<wasm-value>
+ ) -> result<wasm-exception, error>;
+ }
+
+ resource wasm-tag {
+ /// Get the parameter types.
+ params: func(d: borrow<debuggee>) -> result<list<wasm-type>, error>;
+
+ /// Get the unique ID of this tag to allow equality and hashing.
+ unique-id: func() -> u64;
+
+ /// Clone this handle.
+ clone: func() -> wasm-tag;
+
+ /// Allocate a new tag.
+ make: static func(d: borrow<debuggee>, params: list<wasm-type>) -> wasm-tag;
+ }
+
+ resource frame {
+ /// Instance of this frame.
+ get-instance: func(d: borrow<debuggee>) -> result<instance, error>;
+
+ /// Function index in this frame's instance.
+ get-func-index: func(d: borrow<debuggee>) -> result<u32, error>;
+
+ /// Current PC in this frame's instance.
+ get-pc: func(d: borrow<debuggee>) -> result<u32, error>;
+
+ /// Wasm locals.
+ get-locals: func(d: borrow<debuggee>) -> result<list<wasm-value>, error>;
+
+ /// Operand stack.
+ get-stack: func(d: borrow<debuggee>) -> result<list<wasm-value>, error>;
+
+ /// parent frame (the one that called this frame), if any.
+ parent-frame: func(d: borrow<debuggee>) -> result<option<frame>, error>;
+ }
+
+ enum error {
+ invalid-entity,
+ invalid-pc,
+ invalid-frame,
+ unsupported-type,
+ mismatched-type,
+ non-wasm-frame,
+ alloc-failure,
+ breakpoint-update,
+ read-only,
+ out-of-bounds,
+ memory-grow-failure,
+ execution-trap,
+ }
+
+ resource wasm-value {
+ get-type: func() -> wasm-type;
+ unwrap-i32: func() -> u32;
+ unwrap-i64: func() -> u64;
+ unwrap-f32: func() -> f32;
+ unwrap-f64: func() -> f64;
+ unwrap-v128: func() -> list<u8>;
+ unwrap-func: func() -> option<wasm-func>;
+ unwrap-exception: func() -> option<wasm-exception>;
+
+ make-i32: static func(value: u32) -> wasm-value;
+ make-i64: static func(value: u64) -> wasm-value;
+ make-f32: static func(value: f32) -> wasm-value;
+ make-f64: static func(value: f64) -> wasm-value;
+ make-v128: static func(value: list<u8>) -> wasm-value;
+
+ clone: func() -> wasm-value;
+ }
+
+ variant wasm-type {
+ wasm-i32,
+ wasm-i64,
+ wasm-f32,
+ wasm-f64,
+ wasm-v128,
+ wasm-funcref,
+ wasm-exnref,
+ // TODO: GC structs and arrays
+ }
+}
diff --git a/crates/test-programs/Cargo.toml b/crates/test-programs/Cargo.toml
index cd52866eab..f79059d4cf 100644
--- a/crates/test-programs/Cargo.toml
+++ b/crates/test-programs/Cargo.toml
@@ -26,3 +26,4 @@ flate2 = "1.0.28"
log = { workspace = true }
env_logger = { workspace = true }
pin-project-lite = { workspace = true }
+
diff --git a/crates/test-programs/artifacts/build.rs b/crates/test-programs/artifacts/build.rs
index 4b20673fb4..86681f7873 100644
--- a/crates/test-programs/artifacts/build.rs
+++ b/crates/test-programs/artifacts/build.rs
@@ -93,6 +93,7 @@ impl Artifacts {
s if s.starts_with("p3_") => "p3",
s if s.starts_with("nn_") => "nn",
s if s.starts_with("piped_") => "piped",
+ s if s.starts_with("debugger_") => "debugger",
s if s.starts_with("dwarf_") => "dwarf",
s if s.starts_with("config_") => "config",
s if s.starts_with("keyvalue_") => "keyvalue",
diff --git a/crates/test-programs/src/bin/debugger_component.rs b/crates/test-programs/src/bin/debugger_component.rs
new file mode 100644
index 0000000000..482d6d1f15
--- /dev/null
+++ b/crates/test-programs/src/bin/debugger_component.rs
@@ -0,0 +1,128 @@
+//! Debug-main guest to run debugger tests.
+//!
+//! Invoked by tests/all/debug_component.rs with particular debuggees
+//! loaded for each test (selected by argv) below. We print "OK" to
+//! stderr to communicate success.
+
+use std::time::Duration;
+
+mod api {
+ wit_bindgen::generate!({
+ world: "bytecodealliance:wasmtime/debug-main",
+ path: "../../crates/debugger/wit",
+ with: {
+ "wasi:io/[email protected]": wasip2::io::poll,
+ }
+ });
+}
+use api::bytecodealliance::wasmtime::debuggee::*;
+
+struct Component;
+api::export!(Component with_types_in api);
+
+impl api::exports::bytecodealliance::wasmtime::debugger::Guest for Component {
+ fn debug(d: &Debuggee, args: Vec<String>) {
+ match args.get(1).map(|s| s.as_str()) {
+ Some("simple") => {
+ test_simple(d);
+ }
+ Some("loop") => {
+ test_loop(d);
+ }
+ other => panic!("unknown test mode: {other:?}"),
+ }
+ }
+}
+
+struct Resumption {
+ future: EventFuture,
+}
+
+impl Resumption {
+ fn single_step(d: &Debuggee) -> Self {
+ let future = d.single_step(ResumptionValue::Normal);
+ Self { future }
+ }
+
+ fn continue_(d: &Debuggee) -> Self {
+ let future = d.continue_(ResumptionValue::Normal);
+ Self { future }
+ }
+
+ fn result(self, d: &Debuggee) -> Result<Event, Error> {
+ EventFuture::finish(self.future, d)
+ }
+}
+
+/// Tests single-stepping.
+///
+/// Tests against `debugger_debuggee_simple.wat`.
+fn test_simple(d: &Debuggee) {
+ // Step once to reach the first instruction.
+ let r = Resumption::single_step(d);
+ let _event = r.result(d).unwrap();
+
+ let mut pcs = vec![];
+
+ for _ in 0..5 {
+ let frames = d.exit_frames();
+ let pc = frames[0].get_pc(d).unwrap();
+ pcs.push(pc);
+
+ let r = Resumption::single_step(d);
+ match r.result(d).unwrap() {
+ Event::Breakpoint => {}
+ other => panic!("unexpected event: {other:?}"),
+ }
+ }
+
+ // There should be five PCs and they should each be distinct from the previous.
+ assert_eq!(pcs.len(), 5);
+ assert!(pcs.windows(2).all(|p| p[0] != p[1]));
+
+ eprintln!("OK");
+}
+
+/// Interrupt test: continue an infinite-loop debuggee, interrupt it,
+/// verify the interrupt, then set the exit flag in memory and continue
+/// to completion.
+///
+/// Tests against `debugger_debuggee_loop.wat`.
+fn test_loop(d: &Debuggee) {
+ // Continue execution (the debuggee should loop).
+ let r = Resumption::continue_(d);
+
+ // Yield to the event loop and let it run for a bit.
+ std::thread::sleep(Duration::from_millis(100));
+
+ // Request interrupt.
+ d.interrupt();
+
+ // Wait for the interrupt event.
+ let event = r.result(d).unwrap();
+ assert!(
+ matches!(event, Event::Interrupted),
+ "expected Interrupted, got {event:?}"
+ );
+
+ // Set the exit-flag to kill the infinite loop in the guest (the
+ // debugger environment will not otherwise end until the guest
+ // ends; we have no way of forcing an early exit yet).
+ for inst in &d.all_instances() {
+ if let Ok(mem) = inst.get_memory(d, 0) {
+ mem.set_bytes(d, 0, &[1]).unwrap();
+ }
+ }
+
+ // Continue; the debuggee should exit normally now.
+ let r = Resumption::continue_(d);
+ let event = r.result(d).unwrap();
+ assert!(
+ matches!(event, Event::Complete),
+ "expected Complete, got {event:?}"
+ );
+
+ eprintln!("OK");
+}
+
+fn main() {}
diff --git a/crates/test-programs/src/bin/debugger_debuggee_loop.wat b/crates/test-programs/src/bin/debugger_debuggee_loop.wat
new file mode 100644
index 0000000000..96a90d4173
--- /dev/null
+++ b/crates/test-programs/src/bin/debugger_debuggee_loop.wat
@@ -0,0 +1,11 @@
+(module
+ (memory (export "memory") 1)
+ (func (export "_start")
+ (block $exit
+ (loop $loop
+ (br_if $exit (i32.load8_u (i32.const 0)))
+ (br $loop)
+ )
+ )
+ )
+)
diff --git a/crates/test-programs/src/bin/debugger_debuggee_simple.wat b/crates/test-programs/src/bin/debugger_debuggee_simple.wat
new file mode 100644
index 0000000000..cd24b48156
--- /dev/null
+++ b/crates/test-programs/src/bin/debugger_debuggee_simple.wat
@@ -0,0 +1,9 @@
+(module
+ (memory (export "memory") 1)
+ (func (export "_start")
+ (local $x i32)
+ (local.set $x (i32.const 1))
+ (local.set $x (i32.const 2))
+ (local.set $x (i32.const 3))
+ )
+)
diff --git a/src/commands/run.rs b/src/commands/run.rs
index 497da6497b..6ed6c6ae2e 100644
--- a/src/commands/run.rs
+++ b/src/commands/run.rs
@@ -9,6 +9,8 @@ use crate::common::{Profile, RunCommon, RunTarget};
use clap::Parser;
use std::ffi::OsString;
use std::path::{Path, PathBuf};
+#[cfg(feature = "debug")]
+use std::pin::Pin;
use std::sync::{Arc, Mutex};
use std::thread;
use wasi_common::sync::{Dir, TcpListener, WasiCtxBuilder, ambient_authority};
@@ -72,6 +74,95 @@ pub struct RunCommand {
pub module_and_args: Vec<OsString>,
}
+impl RunCommand {
+ /// Split off a sub-command representing the invocation of a
+ /// debugger component side-car to this execution.
+ ///
+ /// This is used to factor out most of the environment bringup for
+ /// the debugger component environment.
+ ///
+ /// This also adjusts the guest options as needed to enable
+ /// debugging (e.g., implictly set `-D guest-debug=y`).
+ #[cfg(feature = "debug")]
+ pub(crate) fn debugger_run(&mut self) -> Result<Option<RunCommand>> {
+ fn set_implicit_option(
+ place: &str,
+ name: &str,
+ setting: &mut Option<bool>,
+ value: bool,
+ ) -> Result<()> {
+ if *setting == Some(!value) {
+ bail!(
+ "Explicitly-set option on {place} {name}={} is not compatible with debugging-implied setting {value}",
+ setting.unwrap()
+ );
+ }
+ *setting = Some(value);
+ Ok(())
+ }
+
+ if let Some(debugger_component_path) = self.run.common.debug.debugger.as_ref() {
+ set_implicit_option(
+ "debuggee",
+ "guest_debug",
+ &mut self.run.common.debug.guest_debug,
+ true,
+ )?;
+ set_implicit_option(
+ "debuggee",
+ "epoch_interruption",
+ &mut self.run.common.wasm.epoch_interruption,
+ true,
+ )?;
+
+ let mut debugger_run = RunCommand::try_parse_from(
+ ["run".into(), debugger_component_path.into()]
+ .into_iter()
+ .chain(self.run.common.debug.arg.iter().map(OsString::from)),
+ )?;
+
+ // Explicitly permit TCP sockets for the debugger-main
+ // environment, if not already set.
+ debugger_run.run.common.wasi.tcp.get_or_insert(true);
+ debugger_run
+ .run
+ .common
+ .wasi
+ .inherit_network
+ .get_or_insert(true);
+
+ // Copy over stdin/stdout/stderr inheritance settings,
+ // except default to `false` for the debugger (so it
+ // doesn't interfere with the debuggee's CLI interface, if
+ // any). We expect most debug components will serve an
+ // interface over the network; for those that want a TUI,
+ // their setup instructions can instruct the user to set
+ // these flags as needed.
+ set_implicit_option(
+ "debugger",
+ "inherit_stdin",
+ &mut debugger_run.run.common.wasi.inherit_stdin,
+ self.run.common.debug.inherit_stdin.unwrap_or(false),
+ )?;
+ set_implicit_option(
+ "debugger",
+ "inherit_stdout",
+ &mut debugger_run.run.common.wasi.inherit_stdout,
+ self.run.common.debug.inherit_stdout.unwrap_or(false),
+ )?;
+ set_implicit_option(
+ "debugger",
+ "inherit_stderr",
+ &mut debugger_run.run.common.wasi.inherit_stderr,
+ self.run.common.debug.inherit_stderr.unwrap_or(false),
+ )?;
+ Ok(Some(debugger_run))
+ } else {
+ Ok(None)
+ }
+ }
+}
+
#[expect(missing_docs, reason = "don't want to mess with clap doc-strings")]
#[derive(Parser, Default, Clone)]
pub struct Preloads {
@@ -113,12 +204,67 @@ impl RunCommand {
runtime.block_on(async {
self.run.common.init_logging()?;
+ #[cfg(feature = "debug")]
+ let debug_run = self.debugger_run()?;
+
let engine = self.new_engine()?;
let main = self
.run
.load_module(&engine, self.module_and_args[0].as_ref())?;
let (mut store, mut linker) = self.new_store_and_linker(&engine, &main)?;
+ #[cfg(feature = "debug")]
+ if let Some(mut debug_run) = debug_run {
+ let debug_engine = debug_run.new_engine()?;
+ let debug_main = debug_run
+ .run
+ .load_module(&debug_engine, debug_run.module_and_args[0].as_ref())?;
+ let (mut debug_store, debug_linker) =
+ debug_run.new_store_and_linker(&debug_engine, &debug_main)?;
+
+ let debug_component = match debug_main {
+ RunTarget::Core(_) => wasmtime::bail!(
+ "Debugger component is a core module; only components are supported"
+ ),
+ RunTarget::Component(c) => c,
+ };
+ let mut debug_linker = match debug_linker {
+ CliLinker::Core(_) => unreachable!(),
+ CliLinker::Component(l) => l,
+ };
+ debug_run.add_debugger_api(&mut debug_linker)?;
+
+ debug_run
+ .invoke_debugger(
+ &mut debug_store,
+ &debug_component,
+ &mut debug_linker,
+ store,
+ move |store| {
+ Box::pin(async move {
+ let engine_clone = store.engine().clone();
+ let cancel = Arc::new(std::sync::atomic::AtomicBool::new(false));
+ let cancel_clone = cancel.clone();
+ let epoch_thread = thread::spawn(move || {
+ while !cancel_clone.load(std::sync::atomic::Ordering::Relaxed) {
+ thread::sleep(std::time::Duration::from_millis(1));
+ engine_clone.increment_epoch();
+ }
+ });
+ self.instantiate_and_run(&engine, &mut linker, &main, store)
+ .await?;
+ cancel.store(true, std::sync::atomic::Ordering::Relaxed);
+ epoch_thread
+ .join()
+ .map_err(|_| wasmtime::Error::msg("epoch thread panicked"))?;
+ Ok(())
+ })
+ },
+ )
+ .await?;
+ return Ok(());
+ }
+
self.instantiate_and_run(&engine, &mut linker, &main, &mut store)
.await?;
Ok(())
@@ -146,7 +292,7 @@ impl RunCommand {
Engine::new(&config)
}
- /// Populatse a new `Store` and `CliLinker` with the configuration in this
+ /// Populates a new `Store` and `CliLinker` with the configuration in this
/// command.
///
/// The `engine` provided is used to for the store/linker and the `main`
@@ -199,6 +345,12 @@ impl RunCommand {
Ok((store, linker))
}
+ #[cfg(feature = "debug")]
+ fn add_debugger_api(&mut self, linker: &mut wasmtime::component::Linker<Host>) -> Result<()> {
+ wasmtime_debugger::add_to_linker(linker, |x| x.ctx().table)?;
+ Ok(())
+ }
+
/// Executes the `main` after instantiating it within `store`.
///
/// This applies all configuration within `self`, such as timeouts and
@@ -337,30 +489,45 @@ impl RunCommand {
store: &mut Store<Host>,
main_target: &RunTarget,
profiled_modules: Vec<(String, Module)>,
- ) -> Result<Box<dyn FnOnce(&mut Store<Host>)>> {
- if let Some(Profile::Guest { path, interval }) = &self.run.profile {
- #[cfg(feature = "profiling")]
- return Ok(self.setup_guest_profiler(
- store,
- main_target,
- profiled_modules,
- path,
- *interval,
- )?);
- #[cfg(not(feature = "profiling"))]
- {
- let _ = (profiled_modules, path, interval, main_target);
- bail!("support for profiling disabled at compile time");
+ ) -> Result<Box<dyn FnOnce(&mut Store<Host>) + Send>> {
+ // If a debugger component is attached, we set up epoch
+ // interruptions in `debugger_run()` above when enabling guest
+ // instrumentation; we need to ensure that epoch interruptions
+ // cause a debug event but no trap here. This overrides other
+ // behavior below.
+ if self.run.common.debug.debugger.is_some() {
+ if self.run.profile.is_some() {
+ bail!("Cannot set profile options together with debugging; they are incompatible");
+ }
+ if self.run.common.wasm.timeout.is_some() {
+ bail!("Cannot set timeout options together with debugging; they are incompatible");
+ }
+ store.epoch_deadline_async_yield_and_update(1);
+ } else {
+ if let Some(Profile::Guest { path, interval }) = &self.run.profile {
+ #[cfg(feature = "profiling")]
+ return Ok(self.setup_guest_profiler(
+ store,
+ main_target,
+ profiled_modules,
+ path,
+ *interval,
+ )?);
+ #[cfg(not(feature = "profiling"))]
+ {
+ let _ = (profiled_modules, path, interval, main_target);
+ bail!("support for profiling disabled at compile time");
+ }
}
- }
- if let Some(timeout) = self.run.common.wasm.timeout {
- store.set_epoch_deadline(1);
- let engine = store.engine().clone();
- thread::spawn(move || {
- thread::sleep(timeout);
- engine.increment_epoch();
- });
+ if let Some(timeout) = self.run.common.wasm.timeout {
+ store.set_epoch_deadline(1);
+ let engine = store.engine().clone();
+ thread::spawn(move || {
+ thread::sleep(timeout);
+ engine.increment_epoch();
+ });
+ }
}
Ok(Box::new(|_store| {}))
@@ -374,7 +541,7 @@ impl RunCommand {
profiled_modules: Vec<(String, Module)>,
path: &str,
interval: std::time::Duration,
- ) -> Result<Box<dyn FnOnce(&mut Store<Host>)>> {
+ ) -> Result<Box<dyn FnOnce(&mut Store<Host>) + Send>> {
use wasmtime::{AsContext, GuestProfiler, StoreContext, StoreContextMut, UpdateDeadline};
let module_name = self.module_and_args[0].to_str().unwrap_or("<main module>");
@@ -681,6 +848,42 @@ impl RunCommand {
}
}
+ #[cfg(feature = "debug")]
+ async fn invoke_debugger<
+ F: for<'a> FnOnce(
+ &'a mut Store<Host>,
+ ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'a>>
+ + Send
+ + 'static,
+ >(
+ &self,
+ store: &mut Store<Host>,
+ component: &wasmtime::component::Component,
+ linker: &mut wasmtime::component::Linker<Host>,
+ debuggee_host: Store<Host>,
+ body: F,
+ ) -> Result<()> {
+ let instance = linker.instantiate_async(&mut *store, component).await?;
+ let command = wasmtime_debugger::DebuggerComponent::new(&mut *store, &instance)?;
+ let debuggee = wasmtime_debugger::Debuggee::new(debuggee_host, body);
+ let debuggee = wasmtime_debugger::add_debuggee(store.data_mut().ctx().table, debuggee)?;
+ {
+ // Manually construct a borrow -- wasmtime-wit-bindgen
+ // generates code that consumes the `Resource<T>` for
+ // `call_debug()` below even though the WIT type is a
+ // `borrow<debuggee>`.
+ let borrowed = wasmtime::component::Resource::new_borrow(debuggee.rep());
+ let args = self.compute_argv()?;
+ command
+ .bytecodealliance_wasmtime_debugger()
+ .call_debug(&mut *store, borrowed, &args)
+ .await?;
+ }
+ let mut debuggee = store.data_mut().ctx().table.delete(debuggee)?;
+ debuggee.finish().await?;
+ Ok(())
+ }
+
#[cfg(feature = "component-model")]
fn search_component_funcs(
engine: &Engine,
@@ -1085,7 +1288,17 @@ impl RunCommand {
fn set_legacy_p1_ctx(&self, store: &mut Store<Host>) -> Result<()> {
let mut builder = WasiCtxBuilder::new();
- builder.inherit_stdio().args(&self.compute_argv()?)?;
+ builder.args(&self.compute_argv()?)?;
+
+ if self.run.common.wasi.inherit_stdin.unwrap_or(true) {
+ builder.inherit_stdin();
+ }
+ if self.run.common.wasi.inherit_stdout.unwrap_or(true) {
+ builder.inherit_stdout();
+ }
+ if self.run.common.wasi.inherit_stderr.unwrap_or(true) {
+ builder.inherit_stderr();
+ }
if self.run.common.wasi.inherit_env == Some(true) {
for (k, v) in std::env::vars() {
@@ -1139,7 +1352,16 @@ impl RunCommand {
/// `wasmtime-wasi`-vs-`wasi-common` here more than anything else.
fn set_wasi_ctx(&self, store: &mut Store<Host>) -> Result<()> {
let mut builder = wasmtime_wasi::WasiCtxBuilder::new();
- builder.inherit_stdio().args(&self.compute_argv()?);
+ builder.args(&self.compute_argv()?);
+ if self.run.common.wasi.inherit_stdin.unwrap_or(true) {
+ builder.inherit_stdin();
+ }
+ if self.run.common.wasi.inherit_stdout.unwrap_or(true) {
+ builder.inherit_stdout();
+ }
+ if self.run.common.wasi.inherit_stderr.unwrap_or(true) {
+ builder.inherit_stderr();
+ }
self.run.configure_wasip2(&mut builder)?;
let mut ctx = builder.build_p1();
if let Some(max) = self.run.common.wasi.max_resources {
@@ -1227,7 +1449,7 @@ pub struct Host {
}
impl Host {
- fn wasip1_ctx(&mut self) -> &mut wasmtime_wasi::p1::WasiP1Ctx {
+ pub(crate) fn wasip1_ctx(&mut self) -> &mut wasmtime_wasi::p1::WasiP1Ctx {
unwrap_singlethread_context(&mut self.wasip1_ctx)
}
}
diff --git a/src/common.rs b/src/common.rs
index fa7fb061e7..982417fffb 100644
--- a/src/common.rs
+++ b/src/common.rs
@@ -19,6 +19,7 @@ use wasmtime::component::Component;
/// future.
pub const P3_DEFAULT: bool = cfg!(feature = "component-model-async") && false;
+#[derive(Clone)]
pub enum RunTarget {
Core(Module),
diff --git a/supply-chain/audits.toml b/supply-chain/audits.toml
index 4229d8e2b6..0801793991 100644
--- a/supply-chain/audits.toml
+++ b/supply-chain/audits.toml
@@ -2114,6 +2114,12 @@ Well documented invariants, good assertions for those invariants in unsafe code,
and tested with MIRI to boot. LGTM.
"""
+[[audits.async-task]]
+who = "Chris Fallin <[email protected]>"
+criteria = "safe-to-deploy"
+version = "4.7.1"
+notes = "Fairly significant chunk of unsafe code in the async executor core, but seems isolated to well-understood patterns, e.g. a manual vtable and some manual layout code."
+
[[audits.atomic-waker]]
who = "Alex Crichton <[email protected]>"
criteria = "safe-to-deploy"
@@ -3105,6 +3111,12 @@ who = "Joel Dice <[email protected]>"
criteria = "safe-to-deploy"
version = "0.3.31"
+[[audits.futures-lite]]
+who = "Chris Fallin <[email protected]>"
+criteria = "safe-to-deploy"
+version = "1.13.0"
+notes = "No unsafe code and fairly straightforward/expected imports for async IO primitives."
+
[[audits.futures-macro]]
who = "Joel Dice <[email protected]>"
criteria = "safe-to-deploy"
@@ -3377,6 +3389,12 @@ criteria = "safe-to-deploy"
version = "0.1.3"
notes = "A part of RustCrypto/utils, this crate is designed to handle unsafe buffers and carefully documents the safety concerns throughout. Older versions of this tally up to ~130k daily downloads."
+[[audits.instant]]
+who = "Chris Fallin <[email protected]>"
+criteria = "safe-to-deploy"
+version = "0.1.12"
+notes = "Small crate wrapping platform primitives for time that uses `unsafe` only for FFI."
+
[[audits.io-extras]]
who = "Dan Gohman <[email protected]>"
criteria = "safe-to-deploy"
@@ -4119,6 +4137,12 @@ criteria = "safe-to-deploy"
version = "0.1.1"
notes = "small crate, only defines macro-rules!, nicely documented as well"
+[[audits.parking]]
+who = "Chris Fallin <[email protected]>"
+criteria = "safe-to-deploy"
+version = "2.2.1"
+notes = "forbid-unsafe crate with straightforward imports."
+
[[audits.peeking_take_while]]
who = "Nick Fitzgerald <[email protected]>"
criteria = "safe-to-deploy"
@@ -4952,6 +4976,12 @@ criteria = "safe-to-deploy"
version = "0.2.15"
notes = "no build.rs, no macros, no unsafe. It reads the filesystem and makes copies of DLLs into OUT_DIR."
+[[audits.waker-fn]]
+who = "Chris Fallin <[email protected]>"
+criteria = "safe-to-deploy"
+version = "1.2.0"
+notes = "Trivial crate with no unsafe code or use of any unsafe or risky APIs."
+
[[audits.walkdir]]
who = "Andrew Brown <[email protected]>"
criteria = "safe-to-deploy"
@@ -6442,6 +6472,18 @@ criteria = "safe-to-deploy"
delta = "0.243.0 -> 0.244.0"
notes = "The Bytecode Alliance is the author of this crate"
+[[audits.wstd]]
+who = "Chris Fallin <[email protected]>"
+criteria = "safe-to-deploy"
+version = "0.6.6"
+notes = "The Bytecode Alliance is the author of this crate."
+
+[[audits.wstd-macro]]
+who = "Chris Fallin <[email protected]>"
+criteria = "safe-to-deploy"
+version = "0.6.6"
+notes = "The Bytecode Alliance is the author of this crate."
+
[[audits.xattr]]
who = "Andrew Brown <[email protected]>"
criteria = "safe-to-deploy"
diff --git a/tests/all/debug_component.rs b/tests/all/debug_component.rs
new file mode 100644
index 0000000000..6dc7ead5d6
--- /dev/null
+++ b/tests/all/debug_component.rs
@@ -0,0 +1,64 @@
+#![cfg(not(miri))]
+
+use crate::cli_tests::get_wasmtime_command;
+use test_programs_artifacts::*;
+use wasmtime::Result;
+
+fn run_debugger_test(debugger_component: &str, debuggee: &str, test_mode: &str) -> Result<()> {
+ let mut cmd = get_wasmtime_command()?;
+ cmd.args(&[
+ "run",
+ "-Ccache=n",
+ &format!("-Ddebugger={debugger_component}"),
+ &format!("-Darg={test_mode}"),
+ "-Dinherit-stderr=y",
+ debuggee,
+ ]);
+ let output = cmd.output()?;
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ if !output.status.success() {
+ wasmtime::bail!(
+ "wasmtime failed with status {}\nstderr:\n{stderr}",
+ output.status,
+ );
+ }
+ assert!(
+ stderr.contains("OK"),
+ "expected 'OK' in stderr, got:\n{stderr}"
+ );
+ Ok(())
+}
+
+#[test]
+fn debugger_debuggee_simple() -> Result<()> {
+ run_debugger_test(
+ DEBUGGER_COMPONENT_COMPONENT,
+ DEBUGGER_DEBUGGEE_SIMPLE_COMPONENT,
+ "simple",
+ )
+}
+
+#[test]
+fn debugger_debuggee_loop() -> Result<()> {
+ run_debugger_test(
+ DEBUGGER_COMPONENT_COMPONENT,
+ DEBUGGER_DEBUGGEE_LOOP_COMPONENT,
+ "loop",
+ )
+}
+
+#[test]
+fn debugger_component() -> Result<()> {
+ // This is present so that `assert_test_exists` can assert presence of unit-tests for all
+ // components. The debugger component itself exists in this list alongside all the debuggees;
+ // we only test the debuggees (with the debugger implicitly used for each).
+ Ok(())
+}
+
+macro_rules! assert_test_exists {
+ ($name:ident) => {
+ #[expect(unused_imports, reason = "here to assert the test exists")]
+ use self::$name as _;
+ };
+}
+foreach_debugger!(assert_test_exists);
diff --git a/tests/all/main.rs b/tests/all/main.rs
index abbf9be0a6..4d48bc1cf3 100644
--- a/tests/all/main.rs
+++ b/tests/all/main.rs
@@ -11,6 +11,7 @@ mod component_model;
mod coredump;
mod custom_code_memory;
mod debug;
+mod debug_component;
mod defaults;
mod engine;
mod epoch_interruption;