# dataexcept-rs
[](https://github.com/DiogoRibeiro7/dataexcept-rs/actions/workflows/ci.yml)
[](LICENSE)
Rust implementation of the **DataExcept** structured error and failure-observability model.
The project is a companion to the Python [DataExcept](https://github.com/DiogoRibeiro7/DataExcept) package. It is not a line-by-line port. The Rust API remains idiomatic while preserving the language-neutral failure metadata and serialized error-envelope contract used across service and process boundaries.
> **Status:** experimental alpha. APIs may change before the first stable release.
## Installation
For the alpha release:
```toml
[dependencies]
dataexcept = "0.1.0-alpha.2"
```
Optional observability integrations are feature-gated:
```toml
[dependencies]
dataexcept = { version = "0.1.0-alpha.2", features = ["tracing", "opentelemetry", "sentry"] }
```
## Current scope
The alpha includes:
- transient, permanent, and unknown failure classification;
- retryability and optional retry-after metadata;
- JSON-safe structured error envelopes with cause, context, and grouped errors;
- canonical JSON Schema validation and cross-language fixtures;
- credential-bearing URL redaction;
- idiomatic `DataError` plus conversions from common Rust errors;
- ingestion, validation, schema, transformation, database, network, broker, and ML error types;
- product-neutral operation context;
- W3C Trace Context parsing and propagation;
- optional `tracing`, OpenTelemetry, and Sentry integrations;
- framework-neutral HTTP, worker, broker, and orchestrator boundary adapters.
## Example
```rust
use dataexcept::{DataError, FailureMetadata};
use serde_json::json;
fn validate() -> dataexcept::Result<()> {
let error = DataError::new(
"missing_column",
"customer_id is required",
)
.with_module("pipeline::validation")
.with_attribute("column", json!("customer_id"))
.with_failure(FailureMetadata::permanent());
Err(error)
}
fn main() {
if let Err(error) = validate() {
let envelope = error.to_envelope();
println!("{}", envelope.to_json_pretty().expect("valid JSON"));
}
}
```
The resulting envelope contains stable machine-readable fields such as:
```json
{
"type": "missing_column",
"module": "pipeline::validation",
"message": "customer_id is required",
"attributes": {
"column": "customer_id"
},
"failure": {
"kind": "permanent",
"retryable": false,
"retry_after_seconds": null
}
}
```
## Runnable examples
The repository includes examples that are compiled in CI:
```bash
cargo run --example core_error
cargo run --example observability
cargo run --example boundaries
```
They cover structured error envelopes, trace-aware observability events, and
framework-neutral HTTP/broker boundary context.
## Design principles
Rust errors and wire-format errors are separate concerns. Existing domain-specific Rust enums should remain domain-specific; they can be converted to `ErrorEnvelope` values at process, API, worker, or broker boundaries.
The serialized envelope is a separate language-neutral contract. Compatibility with the canonical DataExcept JSON Schema is protected by cross-language fixtures and contract tests rather than by forcing Python implementation details into Rust.
Observability integrations do not own application runtime configuration. Subscriber setup, OpenTelemetry providers/exporters, and Sentry SDK initialization remain application concerns.
## Development
```bash
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo doc --no-deps --all-features
```
See [CONTRIBUTING.md](CONTRIBUTING.md), [ROADMAP.md](ROADMAP.md), and [CHANGELOG.md](CHANGELOG.md).
## License
MIT. See [LICENSE](LICENSE).