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

//! Authentication & Authorization Component
//!
//! Handles JWT tokens, OAuth2 flows, session management, and permission checks.
//!
//! This version uses the `component!` and `diag!` macros from waddling-errors-macros.

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

// Mark this file as Auth component location - public facing (API docs)
component_location!(Auth, role = public);

component! {
    Auth {
        docs: "Authentication and authorization system. Handles JWT tokens, OAuth2 flows, session management, and permission checks.",
        examples: [
            "E.Auth.Token.MISSING: JWT token missing in Authorization header",
            "E.Auth.Token.INVALID: JWT token signature invalid",
            "E.Auth.Permission.DENIED: User lacks required role for this operation"
        ],
        tags: ["security", "authentication", "authorization"],
    },
}

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

diag! {
    <json, html>,


    E.Auth.Token.MISSING: {
        message: "JWT token missing from Authorization header",
        'CR 'Pub description: "The client did not provide a JWT token in the Authorization header. This is required for all authenticated endpoints.",
        'CR 'Pub hints: [
            "Include Authorization header",
            "Check authentication middleware"
        ],
        'CR 'Int hints: [
            "Verify middleware is properly configured",
            "Check request interceptors"
        ],
        'R role: "Internal",
        'R tags: ["authentication", "security", "http"],
        'R related_codes: ["E.Auth.Token.INVALID", "E.Auth.Token.EXPIRED"],

        // New rich code snippet syntax!
        'C 'Pub code_snippet: {
            language: "javascript",
            wrong: "fetch('/api/data')",
            correct: "fetch('/api/data', {\n  headers: { 'Authorization': 'Bearer <token>' }\n})",
            explanation: "Include the JWT token in the Authorization header",
        },
        'C 'Dev code_snippet: {
            language: "rust",
            wrong: "client.get(url).send()?",
            correct: "client.get(url)\n    .header(\"Authorization\", format!(\"Bearer {}\", token))\n    .send()?",
            explanation: "Use the header() method to add auth",
        },
    },

    E.Auth.Token.INVALID: {
        message: "JWT token signature validation failed",
        'CR 'Pub description: "The JWT token signature could not be verified. This indicates the token was tampered with or signed with a different secret.",
        'CR 'Pub hints: [
            "Verify JWT_SECRET",
            "Check token hasn't been modified"
        ],
        'CR 'Dev hints: [
            "Validate JWT signature using correct algorithm",
            "Ensure public key matches signing key"
        ],
        'R role: "Developer",
        'R tags: ["authentication", "security", "cryptography"],
        'R related_codes: ["E.Auth.Token.MISSING", "E.Auth.Token.EXPIRED"],
    },

    E.Auth.Token.EXPIRED: {
        message: "JWT token expired - refresh required",
        'CR 'Pub description: "The JWT token has passed its expiration time (exp claim). The client should use their refresh token to obtain a new access token.",
        'CR 'Pub hints: [
            "Use refresh token endpoint",
            "Implement auto-refresh"
        ],
        'R role: "Public",
        'R tags: ["authentication", "session"],
        'R related_codes: ["E.Auth.Token.MISSING", "E.Auth.Token.INVALID"],
    },

    E.Auth.Token.MALFORMED: {
        message: "JWT token malformed",
        'CR 'Pub description: "JWT token malformed - deprecated, use E.Auth.Token.INVALID instead",
        'CR 'Pub hints: [
            "Migrate to E.Auth.Token.INVALID for new code",
            "This error is deprecated since v2.0.0"
        ],
        'R role: "Internal",
        'R tags: ["authentication", "deprecated"],
        'R related_codes: ["E.Auth.Token.INVALID"],
        'C deprecated: "2.0.0",
        'C see_also: ["E.Auth.Token.INVALID"],
    },

    E.Auth.Permission.DENIED: {
        message: "Insufficient permissions for operation",
        'CR 'Pub description: "The authenticated user does not have the required permissions to perform this operation. Check role assignments and permission scopes.",
        'CR 'Pub hints: [
            "Check user roles",
            "Request elevated permissions"
        ],
        'R role: "Public",
        'R tags: ["authorization", "rbac"],
    },

    W.Auth.Permission.LIMITED: {
        message: "Limited permissions - some features unavailable",
        'CR 'Pub description: "The user has limited permissions for this resource. Some features will be unavailable or restricted.",
        'CR 'Pub hints: [
            "Upgrade account tier",
            "Contact support for access"
        ],
        'R role: "Public",
        'R tags: ["authorization", "account"],
        'R related_codes: ["E.Auth.Permission.DENIED"],
    },
}