[nacx]

Adds the boe debug command to run extensions compiled with debug symbols so that they can be easily debugged from the IDE.

When running the command, boe compiles the extension with debug symbols, starts Envoy with the extension Dynamic Module configured, installs Delve (for Go extensions, if not present), and attaches it to the Envoy process.

Note

BOE will patch and compile Delve, as the latest version can't properly find the symbols in library code that runs in non-Go host programs. go-delve/delve#4456 has been opened to upstream the patches contained in this PR.

It only supports running local extensions (--local), to simplify having access to the code.
I couldn't make it work natively on macOS. When mac architecture is detected, it will automatically use the Docker image.

Ecxample output:

$ ./cli/out/boe-darwin-arm64 debug --local ~/src/built-on-envoy/extensions/composer/opa \
    --config '{"policies":[{"inline":"package envoy.authz\ndefault allow := true"}]}'

→ Running Envoy in Docker (ghcr.io/tetratelabs/built-on-envoy/boe:latest)...
→ Building composer for opa...
✓ Starting Envoy with extensions: [opa]...
1.38.0 is already downloaded
starting: /var/boe/data/envoy-versions/1.38.0/bin/envoy with logs in /var/boe/state/envoy-runs/0
🐞 Attaching Delve to Envoy (PID 59)...
[dlv] API server listening at: [::]:2345
[dlv] 2026-10-09T20:05:21Z warn layer=rpc Listening for remote connections (connections are not authenticated nor encrypted)
[dlv] Warning: no debug info found, some functionality will be missing such as stack traces and variable evaluation.
🐞 Delve is attached to Envoy and listening on 127.0.0.1:2345 (dlv PID 103)

✓ Envoy is ready after 300ms
  → Proxy: http://localhost:10000
  → Admin: http://localhost:9901

Test with:
  curl http://localhost:10000/

Press Ctrl+C to stop

[nacx]

The e2e debug test is skipped on pull requests, as it could take quite some time (build delve, etc). Here is the output:

$ GO_TEST_ARGS="-run TestDebugLocalComposer" make -C cli test-e2e
(...)
Run e2e tests
ok  	github.com/tetratelabs/built-on-envoy/cli/e2e	7.118s
make: Leaving directory '/Users/nacx/src/built-on-envoy/cli'

@wbpcode @denniskniep I'm running this on mac. Could you run the e2e on your machine to validate it runs fine as well?

[nacx]

I've tested e2e in CI in the now closed Rust PR and all e2e pass fine.

[wbpcode]

LGTM. Great!!!