Skip to content

refactor(exceptions): RFC 7807 Problem Details, ResourceBundle i18n, and error factory pattern #4791

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 16 commits into
base: main
Choose a base branch
from
Open

refactor(exceptions): RFC 7807 Problem Details, ResourceBundle i18n, and error factory pattern #4791

wants to merge 16 commits into from

Conversation

@balazs-szucs
Copy link
Collaborator

@balazs-szucs balazs-szucs commented Oct 31, 2025 •
edited
Loading

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:
image
Password-protected file (invalid password):
image
Unsupported RAR:
image
No images in RAR/ZIP:
image

OOM:
image
Invalid html (on the html to pdf endpoint)
image

GS conversion fail:
image

Checklist

General

Documentation

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 for more details.
@balazs-szucs
Refactor exception handling across services and utilities for improve…
b16e0dc 
…d clarity and maintainability.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
@balazs-szucs
Merge branch 'main' into rfc-7808-error-factory
0656cab 
# Conflicts:
#	app/common/src/main/java/stirling/software/common/util/ExceptionUtils.java
#	app/common/src/test/java/stirling/software/common/service/JobExecutorServiceTest.java
#	app/core/src/test/java/stirling/software/SPDF/controller/api/converters/PdfToCbzUtilsTest.java
@balazs-szucs
Refactor exception handling to utilize ExceptionUtils across contro…
54ed9c4 
…llers and services for improved consistency and localization.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
@stirlingbot stirlingbot bot added Java Pull requests that update Java code Front End Issues or pull requests related to front-end development Back End Issues related to back-end development Translation API API-related issues or pull requests Test Testing-related issues or pull requests refactor Code changes that neither fix a bug nor add a feature labels Oct 31, 2025
balazs-szucs and others added 10 commits October 31, 2025 17:43
@balazs-szucs
Validate PDF rendering dimensions before operations to prevent OOM er…
21ebb7d 
…rors and improve memory safety.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
@balazs-szucs
Enhance Ghostscript error handling by detecting critical errors, logg…
fe493c9 
…ing detailed diagnostics, and refining exception messages for better clarity and context.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
@balazs-szucs
Merge branch 'main' into rfc-7808-error-factory
2c94371
@balazs-szucs
**test(ExceptionUtils): simplify and enhance test coverage for except…
382fc2f 
…ion utility methods**

- Updated `testCreatePdfCorruptedExceptionWithoutContext` to assert message content and properly pass a `null` context.
- Removed redundant tests: `testCreateFileNotFoundException`, `testCreateInvalidComparatorException`, `testCreateCompressionOptionsException`, and `testCreateQpdfCompressionException`.
- Enhanced `testCreateInvalidArgumentExceptionSingle` to validate message content for both argument and value.
- Adjusted `INVALID_ARGUMENT` error message format for clarity.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
@balazs-szucs
**refactor(CompressController): enhance image compression logic for i…
95c7ede 
…mproved performance and code maintainability**

- Replaced `String`-based hashes with `ImageIdentity` class for better accuracy in identifying unique images.
- Refactored `compressImagesInPDF` to streamline compression workflow and leverage new helper methods.
- Improved method visibility, added static modifiers, and reduced code duplication across compression utilities.
- Enhanced hashing logic by considering additional image properties like filters, decode parameters, and metadata.
- Simplified and extended error handling for various edge cases, ensuring safer PDF processing.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
@balazs-szucs
Merge branch 'main' into rfc-7808-error-factory
129e96e
@balazs-szucs
refactor(GlobalExceptionHandler): standardize response content type f…
c096ce6 
…or error handling**

- Updated all exception response methods to explicitly set `APPLICATION_PROBLEM_JSON` as the content type.
- Ensured consistency across status codes and exception scenarios for improved client compatibility.
- Simplified and enhanced readability of response entity construction.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
@balazs-szucs
refactor(ExceptionUtils): improve regex handling and memory efficienc…
a2879ab 
…y in exception utilities

- Added reusable regex patterns in `RegexPatternUtils` for line separator and leading asterisks whitespace removal.
- Replaced inline regex logic with `RegexPatternUtils` patterns for better maintainability.
- Improved memory usage and readability in key generation logic with `StringBuilder`.
- Removed redundant methods and streamlined utility functionality for better clarity.
- Converted `GhostscriptErrorInfo` to a `record` for immutability and reduced boilerplate.
- Adjusted method visibility and modifiers in `GlobalExceptionHandler` for consistency.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
@balazs-szucs
refactor(ExceptionUtils): improve exception and error handling structure
4d91bb1 
- Added new `ErrorCodeProvider` interface for consistent error code support across exceptions.
- Consolidated exception-related constants into `GlobalExceptionHandler` for better maintainability.
- Updated error response methods to standardize content and REST compatibility.
- Improved logging for all exception handlers using a unified `logException` method.
- Refactored and removed redundant code, including outdated factory methods for exceptions.
- Introduced helper methods for handling hints and localized error messages.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
@balazs-szucs
refactor(ExceptionUtils): correct documentation and update response c…
b85f463 
…ode in tests

- Fixed typo in the `ExceptionUtils` class documentation for better clarity.
- Updated the expected response code in the Cucumber test scenario from 422 to 400 to reflect correct behavior.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
@balazs-szucs balazs-szucs marked this pull request as ready for review October 31, 2025 20:40
Copilot AI review requested due to automatic review settings October 31, 2025 20:40
@dosubot dosubot bot added the size:XXL This PR changes 1000+ lines ignoring generated files. label Oct 31, 2025
@dosubot dosubot bot added the enhancement New feature or request label Oct 31, 2025
@balazs-szucs balazs-szucs marked this pull request as draft October 31, 2025 20:42
@balazs-szucs
refactor(PipelineProcessor): enhance ZIP detection logic and improve …
61b8954 
…maintainability

- Added filename-based validation to the `isZip` method for improved filtering, especially for `.cbz` files.
- Overloaded `isZip` to support both data and filename parameters for better usability.
- Updated all existing ZIP-check references to use the new overloaded method, ensuring backward compatibility.
- Improved code readability and ensured consistent handling of ZIP-like files during the unzipping process.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
Copilot AI reviewed Oct 31, 2025
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR implements a comprehensive RFC 7807 Problem Details error handling system with internationalized messages, replacing the previous error handling approach. The changes standardize error responses across the application and provide better user-facing error messages with actionable hints.

  • Introduces GlobalExceptionHandler for centralized exception handling with RFC 7807 Problem Details responses
  • Expands ExceptionUtils with typed exception classes, error codes, and helper methods for consistent error creation
  • Updates all controllers and services to use typed exceptions instead of generic IllegalArgumentException and IOException
  • Adds extensive internationalized error messages with hints and action-required text in messages_en_GB.properties
  • Updates frontend JavaScript to parse and display structured error messages from Problem Details responses

Reviewed Changes

Copilot reviewed 52 out of 52 changed files in this pull request and generated 10 comments.

Show a summary per file
File Description
GlobalExceptionHandler.java New centralized exception handler implementing RFC 7807 Problem Details with error codes, hints, and localized messages
ExceptionUtils.java Major expansion with typed exception classes, error code enum, OOM handling utilities, and Ghostscript error detection
messages_en_GB.properties Extensive new error messages, titles, hints, and action-required text for all error codes
PasswordController.java Updated to catch and wrap password errors with typed exceptions
examples.feature Test expectation changed from 500 to 400 for wrong password scenario
PdfToCbzUtilsTest.java Updated test to match new error message format
Multiple controller files Updated to use ExceptionUtils factory methods instead of raw exception constructors
Frontend JS files Enhanced error handling to parse Problem Details JSON and display user-friendly messages with hints
application.properties Enabled RFC 7807 Problem Details support
JobExecutorService.java Removed inline error handling to let GlobalExceptionHandler process exceptions

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
@stirlingbot stirlingbot bot removed the enhancement New feature or request label Oct 31, 2025
@balazs-szucs balazs-szucs marked this pull request as ready for review October 31, 2025 20:48
@dosubot dosubot bot added the enhancement New feature or request label Oct 31, 2025
@balazs-szucs
refactor(ExceptionUtils): update @Getter annotations for error code…
ff9d4fe 
… fields

- Replaced `@Getter` with `@Getter(onMethod_ = {@OverRide})` for `BaseAppException` and `BaseValidationException`.
- Ensured alignment with `ErrorCodeProvider` interface implementation.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
@stirlingbot stirlingbot bot removed the enhancement New feature or request label Oct 31, 2025
@balazs-szucs balazs-szucs added the Priority: High Issues or pull requests with high priority label Nov 1, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

API API-related issues or pull requests Back End Issues related to back-end development Front End Issues or pull requests related to front-end development Java Pull requests that update Java code Priority: High Issues or pull requests with high priority refactor Code changes that neither fix a bug nor add a feature size:XXL This PR changes 1000+ lines ignoring generated files. Test Testing-related issues or pull requests Translation

1 participant

@balazs-szucs