debuglet

Overview ¶

Package debuglet is the Go client library for writing debuglets (WASM measurement programs) that run on the Debuglet executor.

A debuglet is a standard WASI command module: write a normal `func main()`, build it with `GOOS=wasip1 GOARCH=wasm`, and the executor streams whatever you print to stdout/stderr back to the user. The executor passes the user's command-line arguments verbatim as WASI argv, so `flag.CommandLine.Parse(os.Args)` reads them directly (note: there is no program name at os.Args[0]).

This package wraps the raw host imports exported by the executor engine (internal/executor/debuglet/wasm/host_functions.go) so that debuglet authors do not have to deal with //go:wasmimport declarations or unsafe pointer math. Instead of juggling 32-bit memory offsets, you work with a small Conn type:

conn, err := debuglet.ConnectTCP("example.com:80")
if err != nil { ... }
defer conn.Close()
if err := conn.Write([]byte("GET / HTTP/1.0\r\n\r\n")); err != nil { ... }
body, err := io.ReadAll(conn) // Read returns io.EOF when the peer closes
if err != nil { ... }
fmt.Println(string(body))

Conn.Read follows the io.Reader contract: short reads are normal, and a TCP or TLS stream (including connections from AcceptTCP) reports the peer's clean close as (0, io.EOF). UDP and ICMP reads return (0, nil) for an empty datagram, never io.EOF. Reads of an empty buffer return (0, nil) without a host call. Conn.Write keeps its Write([]byte) error signature; it is not an io.Writer.

One host call transfers at most MaxIOBytes bytes. Read therefore fills a larger buffer only up to that bound, which is an ordinary short read. Write splits a longer stream payload into consecutive calls, and rejects a longer datagram rather than sending a truncated one.

In the legacy Conn API, only a clean TCP/TLS end of stream surfaces as a Go error. Other host-side failures reach the caller as neither a value nor an error: a refused or policy-denied destination, a socket error other than EOF, an invalid handle and an invalid buffer all abort the guest as WASM traps, so the job ends with whatever the guest printed before the call.

Dial and DialTimeout use the optional debuglet_io_v1 extension and return Socket instead. Its Read and Write preserve byte counts alongside typed transport errors, so a diagnostic can handle a timeout or reset and continue. Invalid memory and never-issued handles still trap.

On non-wasip1 platforms the package compiles against panic stubs (debuglet_stub.go) so the rest of the module builds and tests on the host; every SDK call panics off-target. The real implementation is in debuglet_wasip1.go.

This stub lets the package (and therefore the whole module) build and test on the host. The host imports it shadows are only available inside a wasip1 guest, so calling these off-target panics. Build a debuglet with `GOOS=wasip1 GOARCH=wasm` to get the real implementation.