Report status tracking with state machine¶

Report status tracking in this system is implemented using a state machine pattern to manage the lifecycle of report generation jobs.^[001-todo-code-copy.md] The lifecycle primarily revolves around three statuses, handling asynchronous processing, retries, and potential failure scenarios through message queues.

States¶

The system tracks the progress of a report using an enumeration ReportStatus with three distinct states:^[001-todo-code-copy.md]

RUNNING: Indicates that the report is currently being processed.^[001-todo-code-copy.md]
SUCCESS: Indicates that the report generation was completed successfully and the file is ready.^[001-todo-code-copy.md]
FAIL: Indicates that the report generation failed.^[001-todo-code-copy.md]

Workflow and Transitions¶

The workflow begins when a user requests a report. The system inserts a new database record with an initial status of RUNNING and immediately dispatches a message to a RabbitMQ topic exchange to trigger the asynchronous generation process.^[001-todo-code-copy.md]

Monitoring and Delay¶

To handle reports that take too long to generate or fail silently, the system utilizes a delay queue. A listener monitors the main queue; if a job is found to be incomplete, it is routed to a delay queue (plt.basic.report.delay.q) with a predefined Time-To-Live (TTL).^[001-todo-code-copy.md]

Upon expiration of the TTL, the message is routed to a Dead Letter Exchange. A dedicated listener consumes this message to explicitly update the report's status in the database to FAIL, recording the event as a timeout.^[001-todo-code-copy.md]

Final Status Update¶

If the asynchronous task completes successfully (either on the first attempt or after retries managed by the application logic), the system updates the database record, setting the status to SUCCESS and storing the file path.^[001-todo-code-copy.md] If an unhandled error occurs during processing, the status is updated to FAIL with an accompanying error message.^[001-todo-code-copy.md]

Data Storage¶

The state of the report is persisted in the vs_report_download_record table.^[001-todo-code-copy.md] The schema includes fields for the status, file path, search parameters (hashed and as JSON), and error messages, allowing for full traceability of the report's lifecycle.^[001-todo-code-copy.md]

Message Queue
[[Asynchronous Processing]]
[[Dead Letter Queue]]

Sources¶

^[001-todo-code-copy.md]