waddling-errors-macros 0.7.3

Procedural macros for structured error codes with compile-time validation and taxonomy enforcement
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! Database Component
//!
//! PostgreSQL database operations - connection pooling, queries, transactions, data integrity.
//!
//! This version uses the `component!` and `diag!` macros from waddling-errors-macros.

use waddling_errors_macros::{component, component_location, diag};

// Mark this file as Database component - internal only (sensitive DB details)
component_location!(Database, role = internal);

component! {
    Database {
        docs: "PostgreSQL database operations. Covers connection pooling, query execution, transactions, and data integrity checks.",
        examples: [
            "E.Db.Connection.NOT_FOUND: Database connection pool exhausted",
            "C.Db.Data.CORRUPTED: Foreign key constraint violation detected",
            "E.Db.Timeout.EXCEEDED: Query execution timeout after 30 seconds"
        ],
        tags: ["persistence", "sql", "transactions"],
    },
}

// ============================================================================
// Error Code Definitions
// ============================================================================

diag! {
    <json, html>,


    E.Db.Connection.NOT_FOUND: {
        message: "Database connection not found in pool",
        'CR 'Pub description: "The requested database connection could not be found in the connection pool. This may indicate the connection was closed or the pool is not initialized.",
        'CR 'Pub hints: [
            "Check DATABASE_URL",
            "Verify DB server is running"
        ],
        'CR 'Int hints: [
            "Review connection pool configuration",
            "Check for connection leaks"
        ],
        'R role: "Internal",
        'R tags: ["database", "connectivity"],
        'R related_codes: ["C.Db.Connection.EXHAUSTED"],
    },

    C.Db.Connection.EXHAUSTED: {
        message: "CRITICAL: Connection pool exhausted",
        'CR 'Pub description: "The database connection pool has no available connections. This is a critical issue that can cause cascading failures and service degradation.",
        'CR 'Pub hints: [
            "Scale up immediately",
            "Investigate long queries",
            "Enable read replicas"
        ],
        'CR 'Int hints: [
            "Monitor connection pool metrics",
            "Review slow query log",
            "Check for connection leaks in application code"
        ],
        'R role: "Internal",
        'R tags: ["database", "performance", "critical"],
        'R related_codes: ["E.Db.Connection.NOT_FOUND", "E.Db.Timeout.EXCEEDED"],
    },

    E.Db.Timeout.EXCEEDED: {
        message: "Database query timeout exceeded",
        'CR 'Pub description: "The database query took longer than the configured timeout limit. This may indicate missing indexes, inefficient queries, or database overload.",
        'CR 'Pub hints: [
            "Optimize query with indexes",
            "Increase timeout limit",
            "Add query cache"
        ],
        'CR 'Int hints: [
            "Run EXPLAIN ANALYZE on slow queries",
            "Check for table locks",
            "Review query execution plan"
        ],
        'R role: "Internal",
        'R tags: ["database", "performance"],
        'R related_codes: ["C.Db.Connection.EXHAUSTED"],
    },

    C.Db.Data.CORRUPTED: {
        message: "CRITICAL: Data corruption detected",
        'CR 'Pub description: "Database data corruption has been detected. This is a critical issue requiring immediate attention to prevent data loss.",
        'CR 'Pub hints: [
            "Backup immediately",
            "Run VACUUM FULL",
            "Check hardware"
        ],
        'CR 'Int hints: [
            "Check PostgreSQL logs for I/O errors",
            "Verify disk integrity with fsck",
            "Review replication lag if using replicas"
        ],
        'R role: "Internal",
        'R tags: ["database", "integrity", "critical"],
        'R related_codes: ["E.Db.Data.CONFLICT", "C.Storage.Data.CORRUPTED"],
    },

    E.Db.Data.CONFLICT: {
        message: "Data conflict - concurrent modification detected",
        'CR 'Pub description: "A concurrent modification conflict was detected. Another transaction modified the same data between read and write operations.",
        'CR 'Pub hints: [
            "Retry with latest version",
            "Implement optimistic locking"
        ],
        'CR 'Dev hints: [
            "Use SELECT FOR UPDATE for pessimistic locking",
            "Implement version-based conflict resolution"
        ],
        'R role: "Developer",
        'R tags: ["database", "concurrency"],
    },

    E.Db.Validation.INVALID: {
        message: "Database constraint validation failed",
        'CR 'Pub description: "A database constraint (foreign key, unique, check) validation failed. The data does not meet the database schema requirements.",
        'CR 'Pub hints: [
            "Check foreign key references",
            "Verify unique constraints"
        ],
        'CR 'Dev hints: [
            "Review constraint definitions in schema",
            "Validate data before insertion"
        ],
        'R role: "Developer",
        'R tags: ["database", "validation"],
    },
}