mirror of
https://github.com/Frooodle/Stirling-PDF.git
synced 2026-02-01 20:10:35 +01:00
locally hosted web application that allows you to perform various operations on PDF files
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> |
||
|---|---|---|
| .claude | ||
| .devcontainer | ||
| .github | ||
| .vscode | ||
| app | ||
| devGuide | ||
| devTools | ||
| docs | ||
| exampleYmlFiles | ||
| gradle/wrapper | ||
| images | ||
| scripts | ||
| testing | ||
| .editorconfig | ||
| .git-blame-ignore-revs | ||
| .gitattributes | ||
| .gitignore | ||
| .pre-commit-config.yaml | ||
| build.gradle | ||
| CONTRIBUTING.md | ||
| DATABASE.md | ||
| Dockerfile | ||
| Dockerfile.dev | ||
| Dockerfile.fat | ||
| Dockerfile.ultra-lite | ||
| gradle.properties | ||
| gradlew | ||
| gradlew.bat | ||
| HowToUseOCR.md | ||
| launch4jConfig.xml | ||
| LICENSE | ||
| README.md | ||
| SECURITY.md | ||
| settings.gradle | ||
Stirling-PDF
Stirling-PDF is a robust, locally hosted web-based PDF manipulation tool using Docker. It enables you to carry out various operations on PDF files, including splitting, merging, converting, reorganizing, adding images, rotating, compressing, and more. This locally hosted web application has evolved to encompass a comprehensive set of features, addressing all your PDF requirements.
All files and PDFs exist either exclusively on the client side, reside in server memory only during task execution, or temporarily reside in a file solely for the execution of the task. Any file downloaded by the user will have been deleted from the server by that point.
Homepage: https://stirlingpdf.com
All documentation available at https://docs.stirlingpdf.com/
Features
- Parallel file processing and downloads
- Dark mode support
- Custom download options
- Custom 'Pipelines' to run multiple features in an automated queue
- API for integration with external scripts
- Optional Login and Authentication support (see here for documentation)
- Enterprise features like SSO (see here for documentation)
- Database Backup and Import (see here for documentation)
50+ PDF Operations
Organise
- Merge: Combine multiple PDFs into one
- Split: Divide PDFs into multiple files
- Extract page(s): Extract specific pages from PDF
- Remove: Delete pages from PDF
- Crop PDF: Adjust PDF page boundaries
- Rotate: Rotate pages in 90-degree increments
- Adjust page size/scale: Resize page contents
- Multi-Page Layout: Add multiple pages to PDF
- PDF to Single Large Page: Convert to single continuous page
- Organize: Rearrange PDF pages
Convert to PDF
- Image to PDF: Convert images to PDF format
- Convert file to PDF: Convert various common file types to PDF
- HTML to PDF: Transform HTML documents to PDF
- Markdown to PDF: Convert Markdown files to PDF
- CBZ to PDF: Convert comic book archives
- CBR to PDF: Convert comic book rar archives
- Email to PDF: Convert email files to PDF
- eBook to PDF: Convert eBook formats (EPUB, MOBI, AZW3, FB2, TXT, DOCX) to PDF (using Calibre)
- Vector Image to PDF: Convert vector images (PS, EPS, EPSF) to PDF format
Convert from PDF
- PDF to Word: Convert to document (docx, doc, odt) format
- PDF to Image: Extract PDF pages as images
- PDF to RTF (Text): Convert to Rich Text Format
- PDF to Presentation: Convert to presentation (pptx, ppt, odp) format
- PDF to CSV: Extract tables to CSV
- PDF to XML: Convert to XML format
- PDF to HTML: Transform to HTML
- PDF to PDF/A: Convert to archival (PDF/A-1b, PDF/A-2b) format
- PDF to Markdown: Convert PDF to Markdown
- PDF to CBZ: Convert to comic book archive
- PDF to CBR: Convert to comic book rar archive
- PDF to Vector Image: Convert PDF to vector image (EPS, PS, PCL, XPS) format
Sign & Security
- Sign: Add digital signatures
- Remove Password: Remove PDF security
- Add Watermark: Apply watermarks
- Sign with Certificate: Certificate-based signing
- Add Stamp to PDF: Apply digital stamps
- Auto Redact: Automatically redact content
- Change Permissions: Modify access permissions
- Add Password: Apply PDF encryption
- Manual Redaction: Manual content redaction
- Remove Certificate Sign: Remove digital signatures
- Sanitize: Clean PDF of potential security issues
- Validate PDF Signature: Verify digital signatures
View & Edit
- OCR / Cleanup scans: Optical Character Recognition
- Add Image: Insert images into PDF
- Extract Images: Extract embedded images
- Change Metadata: Edit PDF metadata
- Get ALL Info on PDF: Comprehensive PDF analysis
- Advanced Colour options: Colour manipulation (various options for colour inversion, CMYK conversion)
- Compare: Compare PDF documents
- Add Page Numbers: Insert page numbering
- Flatten: Flatten PDF layers, and interactive elements
- Remove Annotations: Delete comments and markups
- Remove Blank pages: Delete empty pages
- Remove Image: Delete embedded images
- View/Edit PDF: Interactive PDF editing
- Unlock PDF Forms: Enable form editing
- Add Attachments: Attach files to PDF
Advanced
- Compress: Reduce file size
- Pipeline: Automated workflow processing (OCR images pipeline, prepare PDFs for emailing pipeline)
- Adjust Colours/Contrast: Colour and contrast adjustment
- Auto Rename PDF File: Automatic file renaming
- Auto Split Pages: Automatic page splitting
- Detect/Split Scanned photos: Photo detection and splitting
- Overlay PDFs: Layer PDFs over each other
- Repair: Fix corrupted PDFs
- Show JavaScript: Display embedded JavaScript
- Auto Split by Size/Count: Split by file size or page count
- Split PDF by Chapters: Chapter-based splitting
- Split PDF by Sections: Section-based splitting
- Scanner Effect: Apply scanner-like effects
- Edit Table of Contents: Modify PDF bookmarks and TOC
📖 Get Started
Visit our comprehensive documentation at docs.stirlingpdf.com for:
- Installation guides for all platforms
- Configuration options
- Feature documentation
- API reference
- Security setup
- Enterprise features
Supported Languages
Stirling-PDF currently supports 40 languages!
| Language | Progress |
|---|---|
| Arabic (العربية) (ar_AR) | |
| Azerbaijani (Azərbaycan Dili) (az_AZ) | |
| Basque (Euskara) (eu_ES) | |
| Bulgarian (Български) (bg_BG) | |
| Catalan (Català) (ca_CA) | |
| Croatian (Hrvatski) (hr_HR) | |
| Czech (Česky) (cs_CZ) | |
| Danish (Dansk) (da_DK) | |
| Dutch (Nederlands) (nl_NL) | |
| English (English) (en_GB) | |
| English (US) (en_US) | |
| French (Français) (fr_FR) | |
| German (Deutsch) (de_DE) | |
| Greek (Ελληνικά) (el_GR) | |
| Hindi (हिंदी) (hi_IN) | |
| Hungarian (Magyar) (hu_HU) | |
| Indonesian (Bahasa Indonesia) (id_ID) | |
| Irish (Gaeilge) (ga_IE) | |
| Italian (Italiano) (it_IT) | |
| Japanese (日本語) (ja_JP) | |
| Korean (한국어) (ko_KR) | |
| Norwegian (Norsk) (no_NB) | |
| Persian (فارسی) (fa_IR) | |
| Polish (Polski) (pl_PL) | |
| Portuguese (Português) (pt_PT) | |
| Portuguese Brazilian (Português) (pt_BR) | |
| Romanian (Română) (ro_RO) | |
| Russian (Русский) (ru_RU) | |
| Serbian Latin alphabet (Srpski) (sr_LATN_RS) | |
| Simplified Chinese (简体中文) (zh_CN) | |
| Slovakian (Slovensky) (sk_SK) | |
| Slovenian (Slovenščina) (sl_SI) | |
| Spanish (Español) (es_ES) | |
| Swedish (Svenska) (sv_SE) | |
| Thai (ไทย) (th_TH) | |
| Tibetan (བོད་ཡིག་) (bo_CN) | |
| Traditional Chinese (繁體中文) (zh_TW) | |
| Turkish (Türkçe) (tr_TR) | |
| Ukrainian (Українська) (uk_UA) | |
| Vietnamese (Tiếng Việt) (vi_VN) | |
| Malayalam (മലയാളം) (ml_IN) |
Stirling PDF Enterprise
Stirling PDF offers an Enterprise edition of its software. This is the same great software but with added features, support and comforts. Check out our Enterprise docs
🤝 Looking to contribute?
Join our community: