README
¶
Debuglet
Debuglet runs small WebAssembly programs for network measurements. A dispatcher accepts jobs and stores results. Executors run debuglets within their configured time and bandwidth budgets. The project includes the dbl command-line client, a Go client library, a Go SDK for writing debuglets, and examples.
Debuglet is an alpha for trusted environments. Read the security policy before operating a networked deployment.
Try it locally
Download the current Linux amd64 release from the releases page, install it, then run:
export PATH="$HOME/.local/bin:$PATH"
dbl demo
The demo starts temporary local roles, runs a WebAssembly measurement, verifies the result, and cleans up. It needs no existing service, account, compiler, root access, wallet, or hand-written configuration. See Install Debuglet for the short installation path.
A successful run prints Debuglet VERSION completed locally: ..., its executor
and run IDs, and Cleanup: complete, then exits zero. If it fails, start with
troubleshooting.
How it fits together
flowchart LR
C[Client: dbl or Go application] -->|HTTP API| D[Dispatcher]
D -->|submit, results, scheduling| DB[(Dispatcher state)]
D <-->|authenticated control paths| E[Executor]
E -->|runs| W[Debuglet: WASI program]
E -->|local state| ES[(Executor state)]
The dispatcher exposes the API and coordinates work. Executors connect outward to it, so they do not require a public inbound control port. See the measurement flow for submission and execution, and deployment topology for the operational model.
Documentation
The versioned guides in docs/ are published at the documentation site. Use the documentation for the release you install.
| Need | Start here |
|---|---|
| Install and run a local demo | Install Debuglet |
| Run a first console measurement | HTTP check and two-executor comparison |
| Use the CLI | CLI reference |
| Write a Go application client | Go client library |
| Write a debuglet | Write a debuglet |
| Integrate with the HTTP API | OpenAPI contract and API guide |
| Understand the code and protocol | Architecture |
| Operate a service | Managed services |
| Contribute | Contributing |
Development
Debuglet development and package checks run on Linux amd64 with Go 1.26.9. From a checkout:
make ci-test
make ci-vet
make ci-build
make ci-package
Use CONTRIBUTING.md for the workflow, generated code, and review expectations.
License
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api publishes the machine-readable description of the dispatcher's public HTTP API together with the contract version it describes.
|
Package api publishes the machine-readable description of the dispatcher's public HTTP API together with the contract version it describes. |
|
cmd
|
|
|
dbl
command
Command dbl is the Debuglet command-line client for the private alpha: it discovers nodes, submits TEST-funded WASM, inspects results and output and acknowledges cancellation through the dispatcher's HTTP API.
|
Command dbl is the Debuglet command-line client for the private alpha: it discovers nodes, submits TEST-funded WASM, inspects results and output and acknowledges cancellation through the dispatcher's HTTP API. |
|
dispatcher
command
|
|
|
executor
command
|
|
|
user
command
|
|
|
examples
|
|
|
client
command
Command client submits a WASM measurement to a Debuglet environment and prints its output using only the public Go SDK.
|
Command client submits a WASM measurement to a Debuglet environment and prints its output using only the public Go SDK. |
|
debuglets/go/demo
command
|
|
|
debuglets/go/dns
command
dns — DNS A lookup over UDP, written with the Debuglet Go SDK.
|
dns — DNS A lookup over UDP, written with the Debuglet Go SDK. |
|
debuglets/go/download
command
|
|
|
debuglets/go/hello-local
command
|
|
|
debuglets/go/helloworld
command
Minimal "hello world" debuglet in Go.
|
Minimal "hello world" debuglet in Go. |
|
debuglets/go/http_get
command
http_get — plaintext HTTP/1.0 request, written with the Debuglet Go SDK.
|
http_get — plaintext HTTP/1.0 request, written with the Debuglet Go SDK. |
|
debuglets/go/latency
command
latency — TCP round-trip latency, written with the Debuglet Go SDK.
|
latency — TCP round-trip latency, written with the Debuglet Go SDK. |
|
debuglets/go/latency/evaluation
command
latency measures nonce-matched UDP echoes.
|
latency measures nonce-matched UDP echoes. |
|
debuglets/go/listen_tcp
command
listen_tcp — inbound TCP echo server, written with the Debuglet Go SDK.
|
listen_tcp — inbound TCP echo server, written with the Debuglet Go SDK. |
|
debuglets/go/listen_udp
command
listen_udp — inbound UDP receiver, written with the Debuglet Go SDK.
|
listen_udp — inbound UDP receiver, written with the Debuglet Go SDK. |
|
debuglets/go/loop
command
|
|
|
debuglets/go/ping
command
ping — ICMPv4 latency probe, written with the Debuglet Go SDK.
|
ping — ICMPv4 latency probe, written with the Debuglet Go SDK. |
|
debuglets/go/send_tcp
command
send_tcp — one TCP request over the raw host imports.
|
send_tcp — one TCP request over the raw host imports. |
|
debuglets/go/send_udp
command
send_udp — UDP sender, written with the Debuglet Go SDK.
|
send_udp — UDP sender, written with the Debuglet Go SDK. |
|
debuglets/go/throughput
command
throughput — TCP throughput sender, written with the Debuglet Go SDK.
|
throughput — TCP throughput sender, written with the Debuglet Go SDK. |
|
experiments/delivery
command
delivery compares direct fan-out with peer-assisted delivery of one update.
|
delivery compares direct fan-out with peer-assisted delivery of one update. |
|
experiments/peer
command
peer exchanges one UDP datagram with every other experiment participant.
|
peer exchanges one UDP datagram with every other experiment participant. |
|
experiments/run
command
run submits a saved experiment definition and collects its existing run results.
|
run submits a saved experiment definition and collects its existing run results. |
|
internal
|
|
|
acceptance/canary
command
Package main provides the repository-only local compatibility witness.
|
Package main provides the repository-only local compatibility witness. |
|
acceptance/evaluation
command
evaluation reads saved local experiment artifacts without a dispatcher.
|
evaluation reads saved local experiment artifacts without a dispatcher. |
|
acceptance/procinventory
Package procinventory reads process identities from procfs for the acceptance harnesses, which observe what an installed candidate started before they may repair anything themselves.
|
Package procinventory reads process identities from procfs for the acceptance harnesses, which observe what an installed candidate started before they may repair anything themselves. |
|
artifact
Package artifact defines the private distribution manifest shared by packaging and runtime verification.
|
Package artifact defines the private distribution manifest shared by packaging and runtime verification. |
|
bitrate
Package bitrate is the bandwidth type the dispatcher admits and the executor enforces, so both compute with the same units and bounds.
|
Package bitrate is the bandwidth type the dispatcher admits and the executor enforces, so both compute with the same units and bounds. |
|
buildinfo
Package buildinfo holds linker-set distribution identity.
|
Package buildinfo holds linker-set distribution identity. |
|
configcheck
Package configcheck holds the checks both daemons apply to their configuration file before they open storage, bind listeners or acquire a packet counter.
|
Package configcheck holds the checks both daemons apply to their configuration file before they open storage, bind listeners or acquire a packet counter. |
|
connections
Package connections stores explicitly named dispatcher connections for local commands.
|
Package connections stores explicitly named dispatcher connections for local commands. |
|
connectivity
Package connectivity implements fixed-size reachability challenges.
|
Package connectivity implements fixed-size reachability challenges. |
|
controlrpc
Package controlrpc carries the control session credential of one dispatcher and executor pair over gRPC metadata: the metadata keys both channels agree on, the constant-time match each side admits a request with, and the status vocabulary that answers a request it cannot admit.
|
Package controlrpc carries the control session credential of one dispatcher and executor pair over gRPC metadata: the metadata keys both channels agree on, the constant-time match each side admits a request with, and the status vocabulary that answers a request it cannot admit. |
|
controlsession
Package controlsession defines the nonsecret, immutable identity persisted with a run.
|
Package controlsession defines the nonsecret, immutable identity persisted with a run. |
|
daemonlog
Package daemonlog holds the logger and shutdown handling the dispatcher and executor daemons share, so both report the same way.
|
Package daemonlog holds the logger and shutdown handling the dispatcher and executor daemons share, so both report the same way. |
|
demo
Package demo owns the disposable installed local measurement.
|
Package demo owns the disposable installed local measurement. |
|
demo/service
Package service installs a verified Debuglet role payload as a service the host's service manager supervises.
|
Package service installs a verified Debuglet role payload as a service the host's service manager supervises. |
|
dispatcher
Package dispatcher holds the dispatcher's application state: the registry of the executors that currently hold a control session, admission of submitted runs against reserved capacity, and the results those runs report.
|
Package dispatcher holds the dispatcher's application state: the registry of the executors that currently hold a control session, admission of submitted runs against reserved capacity, and the results those runs report. |
|
dispatcher/enrollment
Package enrollment binds an executor ID to the node credential its machine holds: the SHA-256 fingerprint of a verified client certificate.
|
Package enrollment binds an executor ID to the node credential its machine holds: the SHA-256 fingerprint of a verified client certificate. |
|
dispatcher/transport/rpc
Package rpc serves the dispatcher's side of the executor control plane and owns one session per connected executor.
|
Package rpc serves the dispatcher's side of the executor control plane and owns one session per connected executor. |
|
executor
Package executor runs guest programs for one dispatcher control session at a time.
|
Package executor runs guest programs for one dispatcher control session at a time. |
|
executor/cleanup
Package cleanup is the one place executor components classify resource release failures.
|
Package cleanup is the one place executor components classify resource release failures. |
|
executor/debuglet/netpolicy
Package netpolicy holds the one network policy the executor applies to guest traffic: which transports a guest may use, which destinations it may reach, and on which ports.
|
Package netpolicy holds the one network policy the executor applies to guest traffic: which transports a guest may use, which destinations it may reach, and on which ports. |
|
executor/debuglet/wasm
Package wasm contains the WASM host function implementations that are imported by WASM modules at runtime.
|
Package wasm contains the WASM host function implementations that are imported by WASM modules at runtime. |
|
executor/isolation
Package isolation owns the executor's local compiler and guest processes.
|
Package isolation owns the executor's local compiler and guest processes. |
|
executor/outputstore
Package outputstore persists output independently of execution scheduling.
|
Package outputstore persists output independently of execution scheduling. |
|
executor/ratelimit/destinations
Package destinations holds the bookkeeping both packet counters keep to apply a per-destination limit given by name: which resolved addresses each debuglet's connections to that name reached.
|
Package destinations holds the bookkeeping both packet counters keep to apply a per-destination limit given by name: which resolved addresses each debuglet's connections to that name reached. |
|
executor/scheduler/memory
Package memory is the in-memory admission core both executor schedulers use.
|
Package memory is the in-memory admission core both executor schedulers use. |
|
executor/scheduler/sqlite
Package sqlite keeps one executor's persisted work and terminal results across restarts without silently running stored work again.
|
Package sqlite keeps one executor's persisted work and terminal results across restarts without silently running stored work again. |
|
executor/tagger
Package tagger provides a transparent IPv4 IPID tagger that injects a 16-bit TESLA-derived authentication tag into every outgoing IPv4 packet.
|
Package tagger provides a transparent IPv4 IPID tagger that injects a 16-bit TESLA-derived authentication tag into every outgoing IPv4 packet. |
|
executor/tagger/ebpf
Package ebpf provides an eBPF-based IPv4 IPID tagger for Linux.
|
Package ebpf provides an eBPF-based IPv4 IPID tagger for Linux. |
|
executor/tagger/tagvectors
Package tagvectors loads testdata/tag-vectors-v1.json, the known-answer vectors of the debuglet-tag-v1 packet tag generated by the independent Python reference tools/tag_vectors.py.
|
Package tagvectors loads testdata/tag-vectors-v1.json, the known-answer vectors of the debuglet-tag-v1 packet tag generated by the independent Python reference tools/tag_vectors.py. |
|
executor/tagger/tesla
Package tesla implements a TESLA-inspired hash-chain key schedule for delayed disclosure of packet authentication keys.
|
Package tesla implements a TESLA-inspired hash-chain key schedule for delayed disclosure of packet authentication keys. |
|
fsutil
Package fsutil publishes files so that a reader, including one after a crash or power loss, sees either the previous file or the complete new one.
|
Package fsutil publishes files so that a reader, including one after a crash or power loss, sees either the previous file or the complete new one. |
|
guestio
Package guestio defines the optional debuglet_io_v1 socket import contract.
|
Package guestio defines the optional debuglet_io_v1 socket import contract. |
|
hostprobe
Package hostprobe reads host facts an executor reports about itself: the kernel clock discipline and the host platform.
|
Package hostprobe reads host facts an executor reports about itself: the kernel clock discipline and the host platform. |
|
ids
Package ids parses the identifiers the dispatcher and executor exchange.
|
Package ids parses the identifiers the dispatcher and executor exchange. |
|
ipmetadata
Package ipmetadata performs offline ASN and approximate location lookups.
|
Package ipmetadata performs offline ASN and approximate location lookups. |
|
ipmetadata/ris
Package ris builds the dispatcher's ASN database from RIPE RIS routing data, the method RIPE Atlas uses for a probe's prefix and ASN: an address belongs to the longest prefix announced in BGP, and to that prefix's origin AS.
|
Package ris builds the dispatcher's ASN database from RIPE RIS routing data, the method RIPE Atlas uses for a probe's prefix and ASN: an address belongs to the longest prefix announced in BGP, and to that prefix's origin AS. |
|
observability
Package observability collects on-demand operational observations without changing the subsystems being observed.
|
Package observability collects on-demand operational observations without changing the subsystems being observed. |
|
packaging
command
Command packaging builds and packages a Linux candidate.
|
Command packaging builds and packages a Linux candidate. |
|
protogen
command
Command protogen renders generated Go sources from a compiled protocol descriptor set using the pinned protoc-gen-go plugins.
|
Command protogen renders generated Go sources from a compiled protocol descriptor set using the pinned protoc-gen-go plugins. |
|
readiness
Package readiness publishes daemon startup records in owned private directories and reads them back for the process that launched the daemon.
|
Package readiness publishes daemon startup records in owned private directories and reads them back for the process that launched the daemon. |
|
schemacheck
Package schemacheck reads the canonical SQL of both roles and the bindings generated from it so tests can compare them against a real database.
|
Package schemacheck reads the canonical SQL of both roles and the bindings generated from it so tests can compare them against a real database. |
|
sqlitedb
Package sqlitedb opens and migrates the daemons' SQLite databases with the connection settings their schemas rely on.
|
Package sqlitedb opens and migrates the daemons' SQLite databases with the connection settings their schemas rely on. |
|
storagecheck
Package storagecheck states which database schemas a build can operate on and verifies a supplied SQLite file against that policy before a daemon serves requests or restores work.
|
Package storagecheck states which database schemas a build can operate on and verifies a supplied SQLite file against that policy before a daemon serves requests or restores work. |
|
storageheadroom
Package storageheadroom preserves an advisory margin for SQLite control and terminal records by refusing payload writes before available space is spent.
|
Package storageheadroom preserves an advisory margin for SQLite control and terminal records by refusing payload writes before available space is spent. |
|
testpeer
Package testpeer supplies real control transports around a scripted executor for integration tests.
|
Package testpeer supplies real control transports around a scripted executor for integration tests. |
|
testtls
Package testtls issues certificate material for tests that need real TLS sockets: one authority, the identities it signs, and the unusable variants a verification test has to reject.
|
Package testtls issues certificate material for tests that need real TLS sockets: one authority, the identities it signs, and the unusable variants a verification test has to reject. |
|
tlsfiles
Package tlsfiles loads the configured TLS identity and trust roots of a daemon, and refuses at startup what would fail every handshake later.
|
Package tlsfiles loads the configured TLS identity and trust roots of a daemon, and refuses at startup what would fail every handshake later. |
|
uploadsize
Package uploadsize defines the same payload bounds for HTTP admission and direct executor uploads.
|
Package uploadsize defines the same payload bounds for HTTP admission and direct executor uploads. |
|
pkg
|
|
|
client
Package client is the native Go HTTP client for a Debuglet dispatcher.
|
Package client is the native Go HTTP client for a Debuglet dispatcher. |
|
debuglet
Package debuglet is the Go client library for writing debuglets (WASM measurement programs) that run on the Debuglet executor.
|
Package debuglet is the Go client library for writing debuglets (WASM measurement programs) that run on the Debuglet executor. |
|
tagspec
Package tagspec implements the pure functions of the packet tag specification debuglet-tag-v1 (docs/tag-spec.md): the canonical tag input of an IPv4 packet, SipHash-2-4, the per-measurement key and the 16-bit tag.
|
Package tagspec implements the pure functions of the packet tag specification debuglet-tag-v1 (docs/tag-spec.md): the canonical tag input of an IPv4 packet, SipHash-2-4, the per-measurement key and the 16-bit tag. |
|
wire
Package wire defines the HTTP JSON types shared by the dispatcher and Go client.
|
Package wire defines the HTTP JSON types shared by the dispatcher and Go client. |
|
wire/experiment
Package experiment contains readiness data shared by hosts and guests without dependencies on host protocol implementations.
|
Package experiment contains readiness data shared by hosts and guests without dependencies on host protocol implementations. |
|
tools
|
|
|
guest-measure
command
guest-measure measures one WASI hello module with the executor's interpreter and memory settings.
|
guest-measure measures one WASI hello module with the executor's interpreter and memory settings. |
Click to show internal directories.
Click to hide internal directories.