13 KiB
13 KiB
Backend feature audit for frontend-only viability
This note reviews each frontend tool that currently posts to the Java API and summarises what the backend actually does today. For every tool (or small group of closely related tools) the table calls out the implementation details we observed in the Spring controllers/services and whether an equivalent browser-only port looks tractable with the current pdf-lib based helper layer.
| Tool(s) | What the backend does | Frontend-only feasibility |
|---|---|---|
| Add Attachments | Streams every uploaded attachment into PDComplexFileSpecification entries, updates the embedded files name tree, and toggles the viewer preferences through PDFBox APIs.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/AttachmentController.java†L34-L53】【F:app/core/src/main/java/stirling/software/SPDF/service/AttachmentService.java†L28-L104】 |
pdf-lib does not expose low-level name tree or attachment primitives today, so we would need significant custom parsing/writing work to recreate the COS dictionaries in the browser. |
| Add Page Numbers | Iterates every selected page and draws text with precise positioning, font selection (including non Latin fonts), and string templating via PDPageContentStream and PDFBox font metrics.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/PageNumbersController.java†L37-L148】 |
Achievable but non-trivial—pdf-lib can draw text, yet we would have to reimplement margin presets, font loading, and multi-language font fallbacks in TS. |
| Add Password / Change Permissions / Remove Password | Loads the document with PDFBox, toggles security flags, and applies StandardProtectionPolicy encryption or strips it entirely when removing passwords.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/PasswordController.java†L32-L113】 |
Browser tooling has no equivalent for modifying encrypted PDFs; a frontend-only port would require implementing encryption/decryption, which is out of scope. |
| Add Stamp | Builds either text or image stamps with alpha blending, font loading from bundled TTFs, optional coordinate overrides, and applies them through PDPageContentStream for selected pages.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/StampController.java†L52-L167】 |
Implemented with pdf-lib in the browser—addStampClientSide mirrors the font loading, opacity, and positioning logic so the tool can now run without the backend for supported formats.【F:frontend/src/utils/pdfOperations/addStamp.ts†L1-L120】 |
| Add Watermark | Mirrors the stamp pipeline but adds image conversion, transparency, and optional PDF-to-image fallback via shared PDF utilities.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/WatermarkController.java†L64-L153】 | Implemented with pdf-lib in the browser—addWatermarkClientSide handles tiled text/image watermarks; the PDF-to-image fallback still requires the server when requested.【F:frontend/src/utils/pdfOperations/addWatermark.ts†L1-L99】 |
| Adjust Page Scale | Rebuilds each page inside a new document, importing the original page as a form XObject and scaling it with PDFBox’ LayerUtility while computing centring offsets.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/ScalePagesController.java†L38-L103】 |
Technically possible client-side, but pdf-lib lacks a one-liner for reusing existing content streams; we would need to reimplement the import/scale maths and could run into performance issues for large files. |
| Auto Rename | Reads the PDF with a custom PDFTextStripper, groups text runs by font size, and heuristically picks the biggest headline as the suggested filename.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/AutoRenameController.java†L33-L118】 |
pdf-lib has no built-in text extraction; we would have to port PDFBox’ text parsing to JS or rely on wasm, so a browser rewrite is currently impractical. |
| Automate (pipelines) | Parses the uploaded JSON config and sequentially replays each operation by making internal HTTP calls to the other backend endpoints, managing ZIP outputs and error accumulation.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineController.java†L47-L132】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineProcessor.java†L91-L200】 | Browser-only automation would require reproducing the entire backend orchestration plus every dependent tool in JS, so it is not viable until the individual operations have browser implementations. |
| Booklet Imposition / Reorganise Pages / Remove Pages | Uses PDFBox to compute saddle-stitch signatures, duplicate/reorder pages, and rebuild the document via form XObjects and layout maths.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/BookletImpositionController.java†L41-L183】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/RearrangePagesPDFController.java†L38-L220】 | Simple page removal now ships with a browser implementation (removePagesClientSide), but booklet imposition and complex reordering still require backend logic.【F:frontend/src/utils/pdfOperations/removePages.ts†L1-L27】 |
| Change Metadata / Sanitize | Mutates document info dictionaries, strips XMP blocks, removes JavaScript/embedded files, and walks annotations/forms to clear actions with PDFBox COS access.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/MetadataController.java†L54-L185】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/SanitizeController.java†L46-L198】 | Requires low-level catalog and COS manipulation that pdf-lib exposes only partially; a full port would likely need a dedicated parser/writer to match PDFBox behaviour. |
| Compress | Chains optional Ghostscript and QPDF CLI invocations, falls back to iterative image recompression inside PDFBox, and manages many temp files to hit the requested target size.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/CompressController.java†L658-L823】 | Impossible to match in-browser without wasm bindings to Ghostscript/QPDF equivalents; image recompression alone would not deliver parity. |
| Convert (URL → PDF, PDF → PDF/A, etc.) | Delegates to external binaries such as WeasyPrint and LibreOffice before finishing with PDFBox clean-up and metadata stamping.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertWebsiteToPDF.java†L40-L99】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertPDFToPDFA.java†L78-L214】 | These flows rely on heavy native tooling; there is no realistic pure-browser substitute today. |
| Crop / Adjust Layout | Imports each page as a form XObject, applies clipping rectangles, and rebuilds the media box to the requested dimensions with LayerUtility.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/CropController.java†L33-L95】 | Rectangular cropping is now handled in-browser via cropPdfClientSide; the advanced layout transformations still lean on the server.【F:frontend/src/utils/pdfOperations/crop.ts†L1-L33】 |
| Extract Images / Remove Blanks / Flatten | Traverse resources and renderers from PDFBox to locate images, run multithreaded extraction, identify blank pages via PDFRenderer heuristics, or rasterise entire pages when flattening forms.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/ExtractImagesController.java†L54-L170】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/BlankPageController.java†L68-L166】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/FlattenController.java†L38-L85】 | Image extraction and blank-page detection depend on PDFBox renderers; replicating them in JS would need a wasm renderer or bespoke canvas logic, so they are currently impractical. |
| Merge / Overlay PDFs | Loads multiple files, optionally sorts them, stitches pages, builds outlines, and uses PDFBox’ Overlay helper to mix foreground/background documents with temp-file juggling.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/MergeController.java†L183-L220】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/PdfOverlayController.java†L39-L200】 |
Simple merges are achievable with pdf-lib, but matching TOC generation, overlay modes, and stream-safe stitching would require a sizeable port. |
| OCR | Chooses between OCRmyPDF and Tesseract CLI runs, manages temporary sidecar files, and merges the results back into a PDF/ZIP response.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/OCRController.java†L76-L214】 | No pure-browser OCR stack offers comparable quality/performance; a wasm bridge to tesseract.js might help, but it would struggle with large PDFs and multi-language pipelines. |
| Security: Cert Sign / Validate Signature / Remove Cert | Leverages BouncyCastle and PDFBox to embed PKCS#7 signatures, craft visible appearance streams, and validate chains via PKIX path building and revocation checks.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/CertSignController.java†L115-L199】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/ValidateSignatureController.java†L68-L220】 | Browser crypto APIs cannot access arbitrary certificate stores or craft incremental PDF signatures, so these flows must stay server-side. |
Can our existing frontend libraries cover the remaining gaps?
The browser stack is currently anchored around pdf-lib for structural edits and pdfjs-dist for rendering support.【F:frontend/package.json†L8-L67】 Those libraries are excellent for page re-ordering, lightweight drawing, and viewer presentation, but the backend-only tools above depend on capabilities that pdf-lib and pdf.js simply do not expose today:
- Encryption and permission management – The password tools use PDFBox’
StandardProtectionPolicyworkflow to set encryption keys, permission flags, and to strip security when unlocking documents.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/PasswordController.java†L32-L113】 None of the shipped frontend libraries can generate or remove those encrypted revisions, so we cannot match the backend feature-set in the browser. - Low-level catalog and attachment access – Adding attachments reaches into the embedded-file name tree, constructs
PDComplexFileSpecificationobjects, and rewrites viewer preferences.【F:app/core/src/main/java/stirling/software/SPDF/service/AttachmentService.java†L28-L104】 Metadata sanitisation follows a similar COS-level pattern. pdf-lib intentionally hides these PDF internals, leaving no straightforward way to recreate the same structures client-side. - Rasterisation-heavy flows – Compression, blank-page removal, and full-page flattening all rely on PDFBox renderers plus optional Ghostscript/QPDF passes for image recompression and heuristic detection.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/CompressController.java†L44-L205】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/BlankPageController.java†L68-L166】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/FlattenController.java†L38-L85】 Replicating those pipelines in pure TypeScript would require shipping large wasm builds of the same engines.
- External binary orchestration – Converters and OCR call out to native tools such as LibreOffice, WeasyPrint, OCRmyPDF, and Tesseract, marshalling intermediate files before re-wrapping the results.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertPDFToPDFA.java†L78-L214】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/OCRController.java†L76-L214】 Without comparable browser binaries we cannot achieve parity for those tasks.
- Digital signatures and certificate validation – Signing invokes BouncyCastle to parse keystores, craft PKCS#7 envelopes, and paint visible signature appearances, while validation performs PKIX path building and revocation checks.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/CertSignController.java†L1-L199】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/ValidateSignatureController.java†L68-L220】 Browser crypto APIs deliberately omit those PDF-specific primitives.
Because the features we still need from PDFBox span encryption, name-tree rewrites, rasterisation, native CLI orchestration, and advanced cryptography, the current frontend libraries cannot satisfy the outstanding requirements on their own. A wasm port of a native PDF engine would be required before we could retire these backend endpoints.