DebugBundle for Rust

Safe, bounded runtime error reporting for vanilla Rust, Tokio, Axum and Actix Web.

This SDK is an unpublished release candidate. Every candidate must pass the source and exact-crate CI matrix on Linux x64/arm64, macOS and Windows. See qualification and the same-commit CI run for evidence and the separate release gates.

No crates.io release is available from this work. make package prepares a local candidate; make smoke-package tests its extracted contents in isolated vanilla, Axum and Actix applications. Registry ownership and publication are separate gates.

First local event

Use the extracted local candidate in an isolated evaluation application:

[dependencies]
debugbundle = { path = "/path/to/extracted/debugbundle-1.0.0-alpha.1", default-features = false, features = ["local"] }

use debugbundle::{Client, Config, Context, ExceptionSnapshot};
use std::time::Duration;

fn main() {
    let client = Client::new(Config::local("checkout-api", ".debugbundle/local/events"));
    client.capture_exception(
        &ExceptionSnapshot::new("SyntheticFailure", "First local event"),
        &Context::default(),
    );
    let outcome = client.flush(Duration::from_secs(2));
    println!("Accepted local events: {}", outcome.accepted_events);
}

Run debugbundle process in that application to read its canonical local arrays. Capture is best effort: if no event was accepted, check client.status() and retry the explicit verification event. A drained queue alone is not a delivery receipt. Private file and relay runtime tests run natively on Linux, macOS and Windows; a cross-compile alone does not qualify an OS backend.

For connected capture, retain the default http feature and use Client::new(Config::from_env()). Set DEBUGBUNDLE_PROJECT_TOKEN, DEBUGBUNDLE_SERVICE, DEBUGBUNDLE_ENVIRONMENT and optionally DEBUGBUNDLE_ENDPOINT. Connected mode always uses configured HTTP, including development. Missing/invalid credentials produce an inactive client visible in status(). Capture and a drained queue alone do not establish cloud acceptance.

Features and integrations

Compose client.tracing_layer() into an existing subscriber, or use client.logger().tee(existing_sink) with the log feature. Instrument Axum with debugbundle::axum::DebugBundleLayer::new(client.clone()), or Actix with debugbundle::actix_web::DebugBundleMiddleware::new(client.clone()).

Both native browser_relay(relay) factories mount /debugbundle/browser and provide origin validation, bounded uploads, credential isolation and durable connected admission. Configure explicit allowed origins for split hosts. Browser service names such as checkout-web remain distinct from backend checkout-api unless the relay explicitly overrides them. See the API guide for complete lifecycle, body opt-in, proxy/peer, spool and status semantics.

Development

Use Docker-backed make test, make typecheck, make lint, make test-features and make package. The minimum supported Rust version is 1.89; CI includes that compiler and the complete native/platform matrix. Current and previous stable source lanes use Rust 1.100.0 and 1.99.1. No Rust installation on the host is required.

Safety model

Capture calls use bounded owned data and mandatory credential protection. Arbitrary error formatters and source accessors do not run during capture. Complete delivery requires canonical indexed acknowledgements.

The current API and its runtime limits are documented in the API guide and configuration reference. Axum/Tower and Actix middleware have source integration tests. Extracted-crate vanilla/Axum/Actix consumers run on Linux x64/arm64, macOS and Windows; genuine published Browser ordinary/beacon/keepalive relay paths run on Linux arm64. Audit refinements must pass those gates again. See the qualification guide and manual release procedure for exact artifact and registry gates.

Licensed under Apache-2.0.