mirror of
https://github.com/Frooodle/Stirling-PDF.git
synced 2025-12-18 20:04:17 +01:00
43345021bf
# Description of Changes Implemented RFC 7807 problem-details standard to provide consistent, structured error responses across the application. All exceptions now flow through a centralized `GlobalExceptionHandler` with tailored handlers for password-protected files, corruption, validation, and Spring framework errors. Every response includes localized `errorCode`, contextual hints, actionable guidance, timestamps, and request paths. **Key improvements:** - Unified error handling prevents inconsistent response formats across services - Localized error messages support multiple languages at runtime - Error context (hints, actionRequired field) improves user experience - Structured metadata enables programmatic error handling on client side Reference: https://www.baeldung.com/spring-boot-return-errors-problemdetail ### Exception Handling - Centralized all exception handling in `GlobalExceptionHandler` with specific handlers for password protection, file corruption, validation errors, and Spring exceptions - Refactored `ExceptionUtils` to generate consistent `ProblemDetail` responses with error metadata - Introduced `ErrorCode` enum to centralize error identification and metadata (supports localization) - Added helper methods for creating standardized exceptions across services ### Implementation Details - **Replaced generic exceptions** with `ExceptionUtils` methods across utility classes (`CbrUtils`, `CbzUtils`, `PdfToCbrUtils`, `EmlProcessingUtils`, `ImageProcessingUtils`) for consistent error handling of invalid formats, empty files, and missing resources - **Improved method signatures** in `JobExecutorService` and `AutoJobAspect` by explicitly declaring thrown exceptions - **Refined job execution error handling** by removing unnecessary catch blocks in synchronous execution, allowing exceptions to propagate to the centralized handler - **Enhanced error messages** for unsupported formats (e.g., RAR5 limitations, PDF-to-CBR constraints) with clearer user guidance ### Response Format All errors now include: - `errorCode`: Machine-readable error identifier (localized at runtime) - `title`: Localized error title - `detail`: Context-specific error message - `hints`: Array of actionable suggestions - `actionRequired`: Boolean flag indicating if user action is needed - `timestamp`: Error occurrence time - `path`: Request path where error occurred **Error examples shown in PR include:** corrupt files, invalid passwords, unsupported formats (RAR5), missing images, OOM conditions, and invalid HTML ### Why This Change - Eliminates ad-hoc error handling patterns scattered across services - Provides actionable guidance instead of technical stack traces - Supports error messages in multiple languages without code changes - Aligns with RFC 7807, improving API interoperability - Error context reduces time to diagnose issues ### Error sample (note the unformatted JSON is NOT visible by default but for presenting purposes I clicked on show stack on each error. By default only error banner (top part of error) visible) Corrupt file: <img width="1912" height="568" alt="image" src="https://github.com/user-attachments/assets/fc6c9dd6-4929-49ab-8e44-bd79c59d875a" /> Password-protected file (invalid password): <img width="1912" height="757" alt="image" src="https://github.com/user-attachments/assets/31632271-8b2f-45c5-ad4a-dff51e085ea0" /> Unsupported RAR: <img width="1912" height="636" alt="image" src="https://github.com/user-attachments/assets/d13cd521-4b07-4399-b97b-4defa842fc05" /> No images in RAR/ZIP: <img width="1912" height="642" alt="image" src="https://github.com/user-attachments/assets/f02999ed-7a56-4e34-9a95-df50c77012cf" /> OOM: <img width="1912" height="714" alt="image" src="https://github.com/user-attachments/assets/3aaf491a-fe42-4831-b905-a4d248e34860" /> Invalid html (on the html to pdf endpoint) <img width="1912" height="577" alt="image" src="https://github.com/user-attachments/assets/584ec7c8-f14c-4eb1-a6b2-cf7812ae8f0a" /> GS conversion fail: <img width="1912" height="674" alt="image" src="https://github.com/user-attachments/assets/8504a876-75e6-40ef-891b-4ee2b3bbdb0a" /> <!-- Please provide a summary of the changes, including: - What was changed - Why the change was made - Any challenges encountered Closes #(issue_number) --> --- ## Checklist ### General - [ ] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) - [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md) (if applicable) - [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md) (if applicable) - [ ] I have performed a self-review of my own code - [ ] My changes generate no new warnings ### Documentation - [ ] I have updated relevant docs on [Stirling-PDF's doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) (if functionality has heavily changed) - [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only) ### UI Changes (if applicable) - [ ] Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR) ### Testing (if applicable) - [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing) for more details. --------- Signed-off-by: Balázs Szücs <bszucs1209@gmail.com> |
||
|---|---|---|
| .. | ||
| steps | ||
| environment.py | ||
| examples.feature | ||
| external.feature | ||
| general.feature | ||