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

//! Queue Component
//!
//! Background job processing - async tasks, job scheduling, retry logic, worker pools.
//!
//! This version uses the `component!` and `diag!` macros from waddling-errors-macros.

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

// Mark this file as Queue component - default (internal)
component_location!(Queue);

component! {
    Queue {
        docs: "Background job processing system. Manages async tasks, job scheduling, retry logic, and worker pool management.",
        examples: [
            "E.Queue.Connection.NOT_FOUND: Message broker not found",
            "B.Queue.Timeout.IN_PROGRESS: Job execution in progress (5/10 min)",
            "W.Queue.Validation.INVALID: Job payload validation warning"
        ],
        tags: ["async", "background-jobs", "workers"],
    },
}

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

diag! {
    <json, html>,


    E.Queue.Connection.NOT_FOUND: {
        message: "Message broker connection not found",
        'CR 'Pub description: "The connection to the message broker (RabbitMQ, Redis, etc.) could not be established or was lost.",
        'CR 'Pub hints: [
            "Check broker service is running",
            "Verify connection URL and credentials"
        ],
        'CR 'Int hints: [
            "Review broker connection pool settings",
            "Check network connectivity to broker",
            "Verify broker authentication credentials"
        ],
        'R role: "Internal",
        'R tags: ["queue", "broker", "connectivity"],
    },

    B.Queue.Timeout.IN_PROGRESS: {
        message: "Background job execution in progress",
        'CR 'Pub description: "The background job is still executing and has not completed yet. This is a blocking status indicating the operation is ongoing.",
        'CR 'Pub hints: [
            "Wait for completion",
            "Check progress status"
        ],
        'CR 'Dev hints: [
            "Monitor job execution time",
            "Review timeout settings if taking too long",
            "Check worker health status"
        ],
        'R role: "Developer",
        'R tags: ["queue", "jobs", "async"],
    },

    E.Queue.Timeout.CANCELLED: {
        message: "Background job cancelled by user/timeout",
        'CR 'Pub description: "The background job was cancelled either by user request or because it exceeded the maximum execution time.",
        'CR 'Pub hints: [
            "Check cancellation reason",
            "Retry if needed"
        ],
        'CR 'Dev hints: [
            "Review job timeout configuration",
            "Implement job cleanup logic",
            "Check cancellation source (user/timeout/system)"
        ],
        'R role: "Developer",
        'R tags: ["queue", "jobs", "cancellation"],
    },

    W.Queue.Validation.INVALID: {
        message: "Job payload validation warning",
        'CR 'Pub description: "The job payload failed validation but the job will continue with best-effort processing or default values.",
        'CR 'Pub hints: [
            "Review payload schema",
            "Check required fields"
        ],
        'CR 'Dev hints: [
            "Validate data types and formats",
            "Update job producers to send correct payload",
            "Review schema validation rules"
        ],
        'R role: "Developer",
        'R tags: ["queue", "validation", "jobs"],
    },

    K.Queue.Data.COMPLETED: {
        message: "Background job completed successfully",
        'CR 'Pub description: "The background job has finished executing successfully. Results are available and any side effects have been applied.",
        'CR 'Pub hints: [
            "Retrieve job results if needed"
        ],
        'CR 'Dev hints: [
            "Clean up temporary resources",
            "Update job status in database",
            "Trigger any post-completion hooks"
        ],
        'R role: "Developer",
        'R tags: ["queue", "jobs", "success"],
    },
}