The WDP Reference
Implementation
The reference Rust library for the Waddling Diagnostic Protocol. Zero runtime dependencies, compile-time validation, and automated catalog generation.
📋 Overview
Structured diagnostic codes with a consistent 4-part format
Error Code Format
Examples
✨ Key Features
Everything you need for robust error handling
Type-safe
Define your own enums with compile-time checking
Zero Runtime Deps
Macros run at compile time. No bloat.
no_std
Works in embedded and WASM environments
Documentation
Auto-generate JSON & HTML docs
Semantic Methods
is_blocking(), is_positive(), priority()
Validation
Catch invalid sequences at compile time
Hashes
5-character base62 hashes for compact logs
Customizable
Define your own strictness rules
🎯 Severity Levels
Nine severity levels with semantic methods
| Severity | Code | Emoji | Priority | Blocking | Use Case |
|---|---|---|---|---|---|
| Error | E | ❌ | 8 | Yes | Invalid input, logic errors |
| Blocked | B | 🚫 | 7 | Yes | Deadlock, I/O wait |
| Critical | C | 🔥 | 6 | No | Data corruption |
| Warning | W | ⚠️ | 5 | No | Deprecated API |
| Help | H | 💡 | 4 | No | Suggestions |
| Success | S | ✅ | 3 | No | Operation succeeded |
| Completed | K | ✔️ | 2 | No | Task finished |
| Info | I | ℹ️ | 1 | No | Events, status |
| Trace | T | 🔍 | 0 | No | Debug traces |
🔢 Sequence Conventions
Semantic sequence numbers for consistency across projects
001-010
Missing params, type mismatches
011-020
Uninitialized, closed, cancelled
021-030
Not found, already exists, locked
031-897
Domain-specific errors
998-999
Completion indicators
📖 Interactive Documentation Examples
Explore role-based documentation generation with searchable error browsers
🌐 Public Documentation
End-user facing errors with helpful hints and solutions. Perfect for API consumers.
Role: Public👨💻 Developer Documentation
Internal developer documentation with implementation details and debugging information.
Role: Developer🔒 Internal Documentation
Full team visibility with complete error catalog, internal debugging notes, and architecture.
Role: Internal🚀 Quick Start
Get started in minutes
Step 1: Add Dependency
[dependencies]
waddling-errors = "0.7"Step 2: Define & Use
use waddling_errors_macros::{component, primary, sequence, diag, setup};
// 1. Setup macro paths (at crate root, before diag!)
setup! {
components = crate,
primaries = crate,
sequences = crate,
}
// 2. Define Architecture
component! { Auth { docs: "Authentication" } }
primary! { Token { docs: "Token errors" } }
// 3. Define Events
sequence! {
MISSING(1) { description: "Required item missing" }
}
// 4. Create Diagnostics
diag! {
E.Auth.Token.MISSING: {
message: "JWT token not found in Authorization header",
hints: ["Include 'Authorization: Bearer <token>' header"],
}
}
fn main() {
println!("Code: {}", E_AUTH_TOKEN_MISSING.runtime.code); // "E.Auth.Token.001"
println!("Hash: {}", E_AUTH_TOKEN_MISSING.hash); // "Xy8Qz"
}