Skip to content

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

20.7 KB
Raw Blame
//! Integration tests for guest-debug support (gdbstub + LLDB).
//!
//! These tests launch `wasmtime run` with `-g 0` (binding to an
//! OS-assigned port, which is parsed from the startup messages), connect LLDB via
//! the wasm remote protocol, execute debug scripts (set breakpoints,
//! continue, step, inspect variables), and validate output.
//!
//! Requirements:
//!   - LLDB with Wasm plugin support (`LLDB` env var or `/opt/wasi-sdk/bin/lldb` by default)
//!   - `WASI_SDK_PATH` env var set (for C test programs)
//!   - Built with `--features gdbstub`

use filecheck::{CheckerBuilder, NO_VARIABLES};
use std::io::{BufRead, BufReader, Write};
use std::net::{SocketAddr, TcpStream};
use std::process::{Child, Command, Stdio};
use std::time::Duration;
use test_programs_artifacts::*;
use wasmtime::{Result, bail, format_err};

/// Find the wasmtime binary built alongside the test binary.
fn wasmtime_binary() -> std::path::PathBuf {
    env!("CARGO_BIN_EXE_wasmtime").into()
}

/// Path to the wasm-aware LLDB.
fn lldb_path() -> String {
    std::env::var("LLDB").unwrap_or("/opt/wasi-sdk/bin/lldb".to_string())
}

/// The readiness marker printed by the gdbstub to stderr.
const GDBSTUB_READY_MARKER: &str = "Debugger listening on";

/// A running wasmtime process with a gdbstub endpoint.
struct WasmtimeWithGdbstub {
    child: Child,
    /// The port the gdbstub is listening on, as reported by wasmtime.
    port: u16,
    /// Keeps the stderr pipe alive to avoid SIGPIPE on the child.
    /// Also used by serve tests to read the HTTP address.
    stderr_reader: BufReader<std::process::ChildStderr>,
}

impl WasmtimeWithGdbstub {
    /// Spawn wasmtime with the gdbstub listening on an OS-assigned
    /// port, and wait for stderr to contain the gdbstub readiness
    /// marker, from which we parse the port.
    ///
    /// Letting wasmtime bind to port 0 (rather than picking a free port
    /// beforehand and passing it in) avoids a race with other processes
    /// (e.g. concurrently-running tests) grabbing the port in between.
    fn spawn(subcmd: &str, extra_args: &[&str], timeout: Duration) -> Result<Self> {
        let mut cmd = Command::new(wasmtime_binary());
        cmd.arg(subcmd)
            .arg("-g0")
            .args(extra_args)
            .stdin(Stdio::null())
            .stdout(Stdio::null())
            .stderr(Stdio::piped());
        eprintln!("spawning: {cmd:?}");
        let mut child = cmd.spawn()?;

        let stderr = child.stderr.take().unwrap();
        let mut reader = BufReader::new(stderr);
        let deadline = std::time::Instant::now() + timeout;
        let mut line = String::new();
        loop {
            if std::time::Instant::now() > deadline {
                let _ = child.kill();
                bail!("timed out waiting for gdbstub readiness");
            }
            line.clear();
            reader.read_line(&mut line)?;
            eprintln!("wasmtime stderr: {}", line.trim_end());
            if let Some(idx) = line.find(GDBSTUB_READY_MARKER) {
                let addr = line[idx + GDBSTUB_READY_MARKER.len()..].trim();
                let port = match addr.parse::<SocketAddr>() {
                    Ok(addr) => addr.port(),
                    Err(e) => {
                        let _ = child.kill();
                        bail!("failed to parse gdbstub address `{addr}`: {e}");
                    }
                };
                return Ok(Self {
                    child,
                    port,
                    stderr_reader: reader,
                });
            }
            if line.is_empty() {
                let _ = child.kill();
                let status = child.wait()?;
                bail!("wasmtime exited ({status}) without readiness marker");
            }
        }
    }

    /// Read stderr lines until one contains `marker`, returning that line.
    fn wait_for_stderr(&mut self, marker: &str, timeout: Duration) -> Result<String> {
        let deadline = std::time::Instant::now() + timeout;
        let mut line = String::new();
        loop {
            if std::time::Instant::now() > deadline {
                bail!("timed out waiting for '{marker}' on stderr");
            }
            line.clear();
            self.stderr_reader.read_line(&mut line)?;
            eprintln!("wasmtime stderr: {}", line.trim_end());
            if line.contains(marker) {
                return Ok(line);
            }
            if line.is_empty() {
                bail!("wasmtime stderr closed before finding '{marker}'");
            }
        }
    }
}

/// Run an LLDB debug script against a gdbstub endpoint.
///
/// Connects LLDB to `127.0.0.1:<port>` using the Wasm plugin,
/// executes the given script commands, and returns LLDB's stdout.
fn lldb_with_gdbstub_script(port: u16, script: &str) -> Result<String> {
    let _ = env_logger::try_init();

    let mut script_file = tempfile::Builder::new().suffix(".lldb").tempfile()?;
    writeln!(
        script_file,
        "process connect --plugin wasm connect://127.0.0.1:{port}"
    )?;
    for line in script.lines() {
        let line = line.trim();
        if !line.is_empty() {
            writeln!(script_file, "{line}")?;
        }
    }

    let mut cmd = Command::new(lldb_path());
    cmd.args(["--batch", "-s"]).arg(script_file.path());

    eprintln!("Running LLDB: {cmd:?}");
    let output = cmd.output()?;

    let stdout = String::from_utf8(output.stdout)?;
    let stderr = String::from_utf8(output.stderr)?;
    eprintln!("--- LLDB stdout ---\n{stdout}");
    eprintln!("--- LLDB stderr ---\n{stderr}");

    Ok(stdout)
}

/// Validate output against FileCheck-style directives.
fn check_output(output: &str, directives: &str) -> Result<()> {
    let mut builder = CheckerBuilder::new();
    builder
        .text(directives)
        .map_err(|e| format_err!("unable to build checker: {e:?}"))?;
    let checker = builder.finish();
    let check = checker
        .explain(output, NO_VARIABLES)
        .map_err(|e| format_err!("{e:?}"))?;
    assert!(check.0, "didn't pass check {}", check.1);
    Ok(())
}

/// Test that breakpoints can be set at the initial stop (before any
/// continue), then hit when the program runs.
#[test]
#[ignore]
fn guest_debug_cli_fib_breakpoint() -> Result<()> {
    let mut wt = WasmtimeWithGdbstub::spawn(
        "run",
        &["-Ccache=n", GUEST_DEBUG_FIB],
        Duration::from_secs(30),
    )?;

    // Set breakpoint at the initial stop, *before* continuing.
    // This tests that modules are visible immediately.
    let output = lldb_with_gdbstub_script(
        wt.port,
        r#"
b fib
c
fr v
c
"#,
    )?;
    wt.child.kill().ok();
    wt.child.wait()?;

    check_output(
        &output,
        r#"
check: stop reason
check: fib
check: n =
"#,
    )?;
    Ok(())
}

/// Test single-stepping within fib.
#[test]
#[ignore]
fn guest_debug_cli_fib_step() -> Result<()> {
    let mut wt = WasmtimeWithGdbstub::spawn(
        "run",
        &["-Ccache=n", GUEST_DEBUG_FIB],
        Duration::from_secs(30),
    )?;

    let output = lldb_with_gdbstub_script(
        wt.port,
        r#"
b fib
c
n
n
n
fr v
c
"#,
    )?;
    wt.child.kill().ok();
    wt.child.wait()?;

    check_output(
        &output,
        r#"
check: stop reason
check: fib
"#,
    )?;
    Ok(())
}

/// Shared linear memories should be readable through the synthetic Wasm
/// address space after the guest stops.
#[cfg(feature = "threads")]
#[test]
#[ignore]
fn guest_debug_cli_shared_memory() -> Result<()> {
    let mut module = tempfile::Builder::new().suffix(".wat").tempfile()?;
    module.write_all(
        br#"(module
  (memory (export "memory") 1 1 shared)
  (func (export "_start")
    i32.const 0
    i32.const 42
    i32.store
    unreachable))
"#,
    )?;
    let module = module.into_temp_path();
    let module_path = module
        .to_str()
        .ok_or_else(|| format_err!("temporary module path is not UTF-8"))?;

    let mut wt = WasmtimeWithGdbstub::spawn(
        "run",
        &["-Ccache=n", "-W", "threads=y,shared-memory=y", module_path],
        Duration::from_secs(30),
    )?;

    let output = lldb_with_gdbstub_script(
        wt.port,
        r#"
continue
memory read --size 4 --format decimal --count 1 0x0
"#,
    )?;
    wt.child.kill().ok();
    wt.child.wait()?;

    check_output(
        &output,
        r#"
check: 42
"#,
    )?;
    Ok(())
}

/// Hitting a breakpoint in a module's `(start)` function should not
/// panic when the debugger inspects the stack. The start function is
/// called from a compiled module-startup function that has no
/// program points of its own; that frame must not be mistaken for a
/// Wasm frame (#14609).
#[test]
#[ignore]
fn guest_debug_cli_breakpoint_in_start_func() -> Result<()> {
    let mut module = tempfile::Builder::new().suffix(".wat").tempfile()?;
    module.write_all(
        br#"(module
  (func $run)
  (start $run))
"#,
    )?;
    let module = module.into_temp_path();
    let module_path = module
        .to_str()
        .ok_or_else(|| format_err!("temporary module path is not UTF-8"))?;

    let mut wt =
        WasmtimeWithGdbstub::spawn("run", &["-Ccache=n", module_path], Duration::from_secs(30))?;

    let output = lldb_with_gdbstub_script(
        wt.port,
        r#"
b run
c
bt
c
"#,
    )?;

    // Wasmtime should run to completion rather than panicking.
    let deadline = std::time::Instant::now() + Duration::from_secs(30);
    let status = loop {
        if let Some(status) = wt.child.try_wait()? {
            break status;
        }
        if std::time::Instant::now() > deadline {
            wt.child.kill().ok();
            wt.child.wait()?;
            bail!("timed out waiting for wasmtime to exit");
        }
        std::thread::sleep(Duration::from_millis(100));
    };
    assert!(status.success(), "wasmtime exited with {status}");

    check_output(
        &output,
        r#"
check: stop reason
check: run
check: exited with status = 0
"#,
    )?;
    Ok(())
}

/// Helper: send an HTTP/1.0 request and return the full response.
fn http_request(addr: SocketAddr, path: &str) -> Result<String> {
    let mut tcp = TcpStream::connect_timeout(&addr, Duration::from_secs(5))?;
    tcp.set_read_timeout(Some(Duration::from_secs(5)))?;
    write!(tcp, "GET {path} HTTP/1.0\r\nHost: localhost\r\n\r\n")?;
    let mut response = String::new();
    let _ = std::io::Read::read_to_string(&mut tcp, &mut response);
    Ok(response)
}

/// Parse an HTTP serve address from a "Serving HTTP on http://addr/" line.
fn parse_http_addr(line: &str) -> Result<SocketAddr> {
    line.find("127.0.0.1")
        .and_then(|start| {
            let addr = &line[start..];
            let end = addr.find('/')?;
            addr[..end].parse().ok()
        })
        .ok_or_else(|| format_err!("failed to parse HTTP address from: {line}"))
}

/// Start serve under debugger, continue, and send multiple HTTP requests
/// to verify instance reuse works correctly under the debugger.
#[test]
#[ignore]
fn guest_debug_serve_requests() -> Result<()> {
    let mut wt = WasmtimeWithGdbstub::spawn(
        "serve",
        &[
            "-Ccache=n",
            "--addr=127.0.0.1:0",
            "-Scli",
            P2_CLI_SERVE_HELLO_WORLD_COMPONENT,
        ],
        Duration::from_secs(30),
    )?;
    let gdb_port = wt.port;

    // Connect LLDB in background: just continue to start the HTTP server.
    let lldb_handle = std::thread::spawn(move || lldb_with_gdbstub_script(gdb_port, "c\n"));

    // Wait for the HTTP server to start.
    let line = wt.wait_for_stderr("Serving HTTP", Duration::from_secs(15))?;
    let http_addr = parse_http_addr(&line)?;
    eprintln!("HTTP address: {http_addr}");

    // Send 3 requests to the same instance, verifying instance reuse.
    for i in 1..=3 {
        let resp = http_request(http_addr, "/")?;
        eprintln!("Response {i}: {}", resp.lines().last().unwrap_or(""));
        assert!(
            resp.contains("Hello, WASI!"),
            "request {i}: expected 'Hello, WASI!' in response, got:\n{resp}"
        );
    }

    // Kill wasmtime to unblock LLDB (which is waiting for the process).
    wt.child.kill().ok();
    wt.child.wait()?;

    // Collect LLDB output (it exits once the process is killed).
    let lldb_output = lldb_handle.join().unwrap()?;

    // Verify LLDB connected and the process was running.
    check_output(
        &lldb_output,
        r#"
check: stop reason
check: resuming
"#,
    )?;

    Ok(())
}

/// Start serve under debugger, set a breakpoint on the HTTP handler,
/// send requests, verify breakpoints fire and responses are correct.
/// Tests instance reuse across multiple requests.
#[test]
#[ignore]
fn guest_debug_serve_breakpoint() -> Result<()> {
    let mut wt = WasmtimeWithGdbstub::spawn(
        "serve",
        &[
            "-Ccache=n",
            "--addr=127.0.0.1:0",
            "-Scli",
            P2_CLI_SERVE_HELLO_WORLD_COMPONENT,
        ],
        Duration::from_secs(30),
    )?;
    let gdb_port = wt.port;

    // LLDB script: set a breakpoint on the incoming-handler Guest::handle,
    // continue to start the server, then for each request: print backtrace
    // at breakpoint and continue. We do this for 3 requests.
    let lldb_handle = std::thread::spawn(move || {
        lldb_with_gdbstub_script(
            gdb_port,
            r#"
rbreak Guest.*handle
c
bt
c
bt
c
bt
c
"#,
        )
    });

    // Wait for the HTTP server to start.
    let line = wt.wait_for_stderr("Serving HTTP", Duration::from_secs(15))?;
    let http_addr = parse_http_addr(&line)?;
    eprintln!("HTTP address: {http_addr}");

    // Send 3 requests. Each one will hit the breakpoint, LLDB prints
    // the backtrace, then continues to let the response through.
    for i in 1..=3 {
        let resp = http_request(http_addr, "/")?;
        eprintln!("Response {i}: {}", resp.lines().last().unwrap_or(""));
        assert!(
            resp.contains("Hello, WASI!"),
            "request {i}: expected 'Hello, WASI!' in response, got:\n{resp}"
        );
    }

    // Kill wasmtime to unblock LLDB.
    wt.child.kill().ok();
    wt.child.wait()?;

    let lldb_output = lldb_handle.join().unwrap()?;

    // Verify LLDB stopped at the breakpoint with the correct function
    // in the backtrace, and that it happened multiple times.
    check_output(
        &lldb_output,
        r#"
check: Guest
check: handle
check: stop reason
check: Guest
check: handle
check: stop reason
check: Guest
check: handle
"#,
    )?;

    Ok(())
}

/// Test write watchpoints on a stack variable: LLDB reports each write
/// that changes `a` as a watchpoint stop, after the write.
#[test]
#[ignore]
fn guest_debug_cli_fib_watchpoint() -> Result<()> {
    let mut wt = WasmtimeWithGdbstub::spawn(
        "run",
        &["-Ccache=n", GUEST_DEBUG_FIB],
        Duration::from_secs(30),
    )?;

    let output = lldb_with_gdbstub_script(
        wt.port,
        r#"
b fib
c
br disable 1
watchpoint set variable a
c
fr v
c
fr v
watchpoint delete 1
c
"#,
    )?;
    wt.child.kill().ok();
    wt.child.wait()?;

    check_output(
        &output,
        r#"
check: Watchpoint created: Watchpoint 1
check: old value: 0
check: new value: 1
check: stop reason = watchpoint 1
check: a = 1
check: old value: 1
check: new value: 2
check: stop reason = watchpoint 1
check: a = 2
check: exited with status = 0
"#,
    )?;
    Ok(())
}

/// A minimal GDB remote serial protocol client, for tests that need
/// precise control over the packets sent.
struct RspClient {
    tcp: TcpStream,
}

impl RspClient {
    fn connect(port: u16) -> Result<Self> {
        let tcp = TcpStream::connect(("127.0.0.1", port))?;
        tcp.set_read_timeout(Some(Duration::from_secs(30)))?;
        Ok(Self { tcp })
    }

    /// Send a packet without waiting for a reply.
    fn send(&mut self, payload: &str) -> Result<()> {
        let checksum = payload.bytes().fold(0u8, |a, b| a.wrapping_add(b));
        write!(self.tcp, "${payload}#{checksum:02x}")?;
        Ok(())
    }

    /// Send a packet and return the reply packet's payload.
    fn request(&mut self, payload: &str) -> Result<String> {
        self.send(payload)?;
        self.reply(payload)
    }

    /// Read the reply packet to `payload`, returning its payload.
    fn reply(&mut self, payload: &str) -> Result<String> {
        // Skip acks until the reply packet starts.
        let mut byte = [0u8];
        loop {
            std::io::Read::read_exact(&mut self.tcp, &mut byte)?;
            match byte[0] {
                b'+' => continue,
                b'$' => break,
                other => bail!("unexpected byte {other:#x} before reply to {payload}"),
            }
        }
        let mut reply = vec![];
        loop {
            std::io::Read::read_exact(&mut self.tcp, &mut byte)?;
            if byte[0] == b'#' {
                break;
            }
            reply.push(byte[0]);
        }
        let mut checksum = [0u8; 2];
        std::io::Read::read_exact(&mut self.tcp, &mut checksum)?;
        self.tcp.write_all(b"+")?;
        let reply = String::from_utf8(reply)?;
        eprintln!("RSP: {payload} -> {reply}");
        Ok(reply)
    }
}

/// Test write watchpoints at the protocol level: read watchpoints are
/// rejected, overlapping watchpoints remain after each other's removal,
/// and stops are reported after the write with the first watched address.
#[test]
#[ignore]
fn guest_debug_rsp_watchpoints() -> Result<()> {
    let dir = tempfile::tempdir()?;
    let wat = dir.path().join("watch.wat");
    std::fs::write(
        &wat,
        r#"
(module
  (memory (export "memory") 1)
  (func (export "_start")
    (i32.store (i32.const 16) (i32.const 0x11223344))
    (i32.store8 (i32.const 32) (i32.const 1))))
"#,
    )?;
    let mut wt = WasmtimeWithGdbstub::spawn(
        "run",
        &["-Ccache=n", wat.to_str().unwrap()],
        Duration::from_secs(30),
    )?;

    let result = (|| -> Result<()> {
        let mut rsp = RspClient::connect(wt.port)?;
        rsp.request("?")?;
        // Step to the first instruction, so that the memory exists.
        let reply = rsp.request("s")?;
        assert!(reply.starts_with("T05"), "unexpected step reply: {reply}");

        // Only write watchpoints are supported.
        assert!(rsp.request("Z3,10,4")?.starts_with('E'));
        assert!(rsp.request("Z4,10,4")?.starts_with('E'));
        // Watchpoints must be within the memory.
        assert!(rsp.request("Z2,fffe,4")?.starts_with('E'));

        // Watch [16, 20) and the overlapping [18, 20), then remove the
        // former: [18, 20) must still be watched.
        assert_eq!(rsp.request("Z2,10,4")?, "OK");
        assert_eq!(rsp.request("Z2,12,2")?, "OK");
        assert_eq!(rsp.request("z2,10,4")?, "OK");
        // Removing something never added fails.
        assert!(rsp.request("z2,10,4")?.starts_with('E'));

        // The store to [16, 20) stops, reporting the first watched byte,
        // once the write has happened.
        let reply = rsp.request("c")?;
        assert!(
            reply.starts_with("T05") && reply.contains("watch:12;"),
            "unexpected stop reply: {reply}"
        );
        assert_eq!(rsp.request("m10,4")?, "44332211");

        // With nothing watched, execution runs to completion.
        assert_eq!(rsp.request("z2,12,2")?, "OK");
        let reply = rsp.request("c")?;
        assert!(reply.starts_with('W'), "unexpected exit reply: {reply}");
        Ok(())
    })();

    wt.child.kill().ok();
    wt.child.wait()?;
    result
}

/// A long loop with no host calls, which only an interrupt can stop early.
const SPIN_WAT: &str = r#"
(module
  (func (export "_start")
    (local $i i32) (local $j i32)
    loop
      (local.set $j (i32.const 0))
      loop
        (local.set $j (i32.add (local.get $j) (i32.const 1)))
        (br_if 0 (i32.lt_u (local.get $j) (i32.const 1000000000)))
      end
      (local.set $i (i32.add (local.get $i) (i32.const 1)))
      (br_if 0 (i32.lt_u (local.get $i) (i32.const 8)))
    end))
"#;

/// Continues `SPIN_WAT` under `wasmtime <subcmd> -g` with `args`, then
/// interrupts it, expecting a stop rather than an exit.
fn interrupt_spin(subcmd: &str, args: &[&str]) -> Result<()> {
    let mut wt = WasmtimeWithGdbstub::spawn(subcmd, args, Duration::from_secs(30))?;
    let result = (|| -> Result<()> {
        let mut rsp = RspClient::connect(wt.port)?;
        rsp.request("?")?;
        rsp.send("c")?;
        std::thread::sleep(Duration::from_millis(200));
        rsp.tcp.write_all(&[0x03])?;
        let reply = rsp.reply("interrupt")?;
        assert!(
            reply.starts_with('T') || reply.starts_with('S'),
            "unexpected interrupt reply: {reply}"
        );
        Ok(())
    })();
    wt.child.kill().ok();
    wt.child.wait()?;
    result
}

/// Test that a debugger can interrupt a running program.
#[test]
#[ignore]
fn guest_debug_cli_interrupt() -> Result<()> {
    let dir = tempfile::tempdir()?;
    let wat = dir.path().join("spin.wat");
    std::fs::write(&wat, SPIN_WAT)?;
    interrupt_spin("run", &["-Ccache=n", wat.to_str().unwrap()])
}