mirror of
https://github.com/Frooodle/Stirling-PDF.git
synced 2025-12-18 20:04:17 +01:00
# 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>
132 lines
5.7 KiB
Gherkin
132 lines
5.7 KiB
Gherkin
@example @general
|
|
Feature: API Validation
|
|
|
|
@positive @password
|
|
Scenario: Remove password
|
|
Given I generate a PDF file as "fileInput"
|
|
And the pdf contains 3 pages
|
|
And the pdf is encrypted with password "password123"
|
|
And the request data includes
|
|
| parameter | value |
|
|
| password | password123 |
|
|
When I send the API request to the endpoint "/api/v1/security/remove-password"
|
|
Then the response content type should be "application/pdf"
|
|
And the response file should have size greater than 0
|
|
And the response PDF is not passworded
|
|
And the response status code should be 200
|
|
|
|
@negative @password
|
|
Scenario: Remove password wrong password
|
|
Given I generate a PDF file as "fileInput"
|
|
And the pdf contains 3 pages
|
|
And the pdf is encrypted with password "password123"
|
|
And the request data includes
|
|
| parameter | value |
|
|
| password | wrongPassword |
|
|
When I send the API request to the endpoint "/api/v1/security/remove-password"
|
|
Then the response status code should be 400
|
|
|
|
@positive @info
|
|
Scenario: Get info
|
|
Given I generate a PDF file as "fileInput"
|
|
When I send the API request to the endpoint "/api/v1/security/get-info-on-pdf"
|
|
Then the response content type should be "application/json"
|
|
And the response file should have size greater than 100
|
|
And the response status code should be 200
|
|
|
|
@positive @password
|
|
Scenario: Add password
|
|
Given I generate a PDF file as "fileInput"
|
|
And the pdf contains 3 pages
|
|
And the request data includes
|
|
| parameter | value |
|
|
| password | password123 |
|
|
When I send the API request to the endpoint "/api/v1/security/add-password"
|
|
Then the response content type should be "application/pdf"
|
|
And the response file should have size greater than 100
|
|
And the response PDF is passworded
|
|
And the response status code should be 200
|
|
|
|
@positive @password
|
|
Scenario: Add password with other params
|
|
Given I generate a PDF file as "fileInput"
|
|
And the pdf contains 3 pages
|
|
And the request data includes
|
|
| parameter | value |
|
|
| ownerPassword | ownerPass |
|
|
| password | password123 |
|
|
| keyLength | 256 |
|
|
| canPrint | true |
|
|
| canModify | false |
|
|
When I send the API request to the endpoint "/api/v1/security/add-password"
|
|
Then the response content type should be "application/pdf"
|
|
And the response file should have size greater than 100
|
|
And the response PDF is passworded
|
|
And the response status code should be 200
|
|
|
|
@positive @watermark
|
|
Scenario: Add watermark
|
|
Given I generate a PDF file as "fileInput"
|
|
And the pdf contains 3 pages
|
|
And the request data includes
|
|
| parameter | value |
|
|
| watermarkType | text |
|
|
| watermarkText | Sample Watermark |
|
|
| fontSize | 30 |
|
|
| rotation | 45 |
|
|
| opacity | 0.5 |
|
|
| widthSpacer | 50 |
|
|
| heightSpacer | 50 |
|
|
| alphabet | roman |
|
|
| customColor | #d3d3d3 |
|
|
When I send the API request to the endpoint "/api/v1/security/add-watermark"
|
|
Then the response content type should be "application/pdf"
|
|
And the response file should have size greater than 100
|
|
And the response status code should be 200
|
|
|
|
@positive
|
|
Scenario: Remove blank pages
|
|
Given I generate a PDF file as "fileInput"
|
|
And the pdf contains 3 blank pages
|
|
And the request data includes
|
|
| parameter | value |
|
|
| threshold | 90 |
|
|
| whitePercent | 99.9 |
|
|
When I send the API request to the endpoint "/api/v1/misc/remove-blanks"
|
|
Then the response content type should be "application/octet-stream"
|
|
And the response file should have extension ".zip"
|
|
And the response ZIP should contain 1 files
|
|
And the response file should have size greater than 0
|
|
|
|
@positive @flatten
|
|
Scenario: Flatten PDF
|
|
Given I generate a PDF file as "fileInput"
|
|
And the request data includes
|
|
| parameter | value |
|
|
| flattenOnlyForms | false |
|
|
When I send the API request to the endpoint "/api/v1/misc/flatten"
|
|
Then the response content type should be "application/pdf"
|
|
And the response file should have size greater than 0
|
|
And the response status code should be 200
|
|
|
|
@positive @metadata
|
|
Scenario: Update metadata
|
|
Given I generate a PDF file as "fileInput"
|
|
And the request data includes
|
|
| parameter | value |
|
|
| author | John Doe |
|
|
| title | Sample Title |
|
|
| subject | Sample Subject |
|
|
| keywords | sample, test |
|
|
| producer | Test Producer |
|
|
When I send the API request to the endpoint "/api/v1/misc/update-metadata"
|
|
Then the response content type should be "application/pdf"
|
|
And the response file should have size greater than 0
|
|
And the response PDF metadata should include "Author" as "John Doe"
|
|
And the response PDF metadata should include "Keywords" as "sample, test"
|
|
And the response PDF metadata should include "Subject" as "Sample Subject"
|
|
And the response PDF metadata should include "Title" as "Sample Title"
|
|
And the response status code should be 200
|
|
|
|
|