use waddling_errors::PrimaryIdDocumented;
use waddling_errors::prelude::*;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Primary {
Token, Connection, RateLimit, Validation, Permission, Timeout, Data, Page, Route, Redirect, }
impl PrimaryId for Primary {
fn as_str(&self) -> &'static str {
match self {
Primary::Token => "Token",
Primary::Connection => "Connection",
Primary::RateLimit => "RateLimit",
Primary::Validation => "Validation",
Primary::Permission => "Permission",
Primary::Timeout => "Timeout",
Primary::Data => "Data",
Primary::Page => "Page",
Primary::Route => "Route",
Primary::Redirect => "Redirect",
}
}
}
impl PrimaryIdDocumented for Primary {
fn description(&self) -> Option<&'static str> {
Some(match self {
Primary::Token => {
"Authentication token errors. JWT parsing, validation, expiry, and signature verification."
}
Primary::Connection => {
"Connection and network errors. TCP failures, DNS resolution, connection pooling."
}
Primary::RateLimit => {
"Rate limiting errors. Request throttling, quota exceeded, backoff requirements."
}
Primary::Validation => {
"Data validation errors. Schema validation, constraint checks, format verification."
}
Primary::Permission => {
"Authorization and permission errors. Role checks, scope verification, ACL violations."
}
Primary::Timeout => {
"Operation timeout errors. Query timeouts, request timeouts, job execution limits."
}
Primary::Data => {
"Data integrity errors. Corruption detection, constraint violations, referential integrity."
}
Primary::Page => {
"Page and view errors. Page resolution, rendering, and view state management."
}
Primary::Route => {
"Routing errors. Route matching, parameter extraction, and navigation guards."
}
Primary::Redirect => {
"Redirect handling errors. Redirect chains, permanent vs temporary redirects."
}
})
}
fn related(&self) -> &'static [&'static str] {
match self {
Primary::Token => &["Permission", "Validation"],
Primary::Connection => &["Timeout"],
Primary::RateLimit => &["Timeout"],
Primary::Validation => &["Data"],
Primary::Permission => &["Token"],
Primary::Timeout => &["Connection"],
Primary::Data => &["Validation"],
Primary::Page => &["Route", "Validation"],
Primary::Route => &["Page", "Validation"],
Primary::Redirect => &["Page", "Route"],
}
}
}
#[cfg(feature = "doc-gen")]
pub fn register_primaries(generator: &mut waddling_errors::doc_generator::DocRegistry) {
generator.register_primary(
"Token",
Some("Authentication token errors. Covers JWT parsing, signature validation, expiry checks, and token refresh flows. Includes handling for malformed tokens, invalid signatures, expired tokens, and revoked credentials."),
&[
"Missing Authorization header",
"Malformed JWT structure",
"Invalid signature verification",
"Expired token (check 'exp' claim)",
"Token revoked by user/admin",
"Refresh token invalid or expired",
],
&["Permission", "Validation"])
.register_primary(
"Connection",
Some("Connection and network errors. Covers TCP connection failures, DNS resolution errors, connection pool exhaustion, and timeout scenarios. Includes handling for transient network issues and connection lifecycle management."),
&[
"Connection pool exhausted",
"Connection refused by server",
"DNS resolution failure",
"Connection timeout exceeded",
"Connection lost during operation",
"Maximum connections reached",
],
&["Timeout"])
.register_primary(
"RateLimit",
Some("Rate limiting and throttling errors. Implements token bucket and leaky bucket algorithms for request rate limiting. Tracks per-user, per-IP, and per-endpoint quotas with configurable time windows and burst allowances."),
&[
"Request quota exceeded (per minute/hour)",
"Burst limit exceeded",
"Concurrent request limit reached",
"API tier limit exceeded",
"Retry-After header provided",
"Rate limit reset time available",
],
&["Timeout", "Validation"])
.register_primary(
"Validation",
Some("Data validation and constraint errors. Covers schema validation, type checking, format verification, and business rule enforcement. Includes JSON schema validation, regex pattern matching, and custom validator support."),
&[
"JSON schema validation failure",
"Required field missing",
"Invalid data type",
"Format constraint violation (email, URL)",
"Range or length constraint violation",
"Business rule validation failure",
],
&["Data", "Token"])
.register_primary(
"Permission",
Some("Authorization and permission errors. Implements role-based access control (RBAC), attribute-based access control (ABAC), and scope-based permissions. Covers role checks, resource ownership verification, and fine-grained permission scopes."),
&[
"User lacks required role",
"Permission scope insufficient",
"Resource ownership mismatch",
"ACL entry denied",
"Action not permitted for user tier",
"Admin privileges required",
],
&["Token", "Validation"])
.register_primary(
"Timeout",
Some("Operation timeout errors. Covers query timeouts, request timeouts, job execution time limits, and lock wait timeouts. Implements configurable timeout thresholds with context-aware timeout values for different operation types."),
&[
"Database query timeout",
"HTTP request timeout",
"Lock acquisition timeout",
"Job execution time limit exceeded",
"Connection establishment timeout",
"Graceful shutdown timeout",
],
&["Connection", "RateLimit"])
.register_primary(
"Data",
Some("Data integrity and corruption errors. Covers checksum mismatches, foreign key violations, unique constraint violations, and referential integrity checks. Includes handling for concurrent modification conflicts and data consistency validation."),
&[
"Checksum verification failed",
"Foreign key constraint violation",
"Unique constraint violation",
"Referential integrity violation",
"Concurrent modification detected",
"Data corruption detected",
],
&["Validation", "Permission"])
.register_primary(
"Page",
Some("Page and view errors. Covers page resolution, rendering failures, and view state management. Includes 404 handling, page template errors, and page data loading issues."),
&[
"Page not found (404)",
"Page access denied",
"Page template rendering failed",
"Page data loading failed",
"Page state serialization error",
"Page cache miss",
],
&["Route", "Validation"])
.register_primary(
"Route",
Some("Routing errors. Covers route matching, parameter extraction, and navigation guards. Includes URL pattern validation and dynamic route resolution."),
&[
"Route pattern invalid",
"Route parameter missing",
"Route guard rejected navigation",
"Dynamic route resolution failed",
"Nested route configuration error",
"Route alias collision",
],
&["Page", "Validation"])
.register_primary(
"Redirect",
Some("Redirect handling errors. Covers redirect chains, permanent vs temporary redirects, and redirect loop detection."),
&[
"Redirect chain detected",
"Permanent redirect (301)",
"Temporary redirect (302/307)",
"Redirect loop detected",
"Invalid redirect target",
],
&["Page", "Route"]);
}