Cache fix issues V2 (#5237)

# Description of Changes  --- ## 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.
2026-07-16 19:33:11 +02:00 · 2025-12-15 23:54:25 +00:00
parent 336ec34125
commit d80e627899
26 changed files with 805 additions and 229 deletions
@@ -94,6 +94,7 @@ public class InitialSetup {
        }
        GeneralUtils.saveKeyToSettings("AutomaticallyGenerated.appVersion", appVersion);
        applicationProperties.getAutomaticallyGenerated().setAppVersion(appVersion);
+        applicationProperties.getAutomaticallyGenerated().setIsNewServer(isNewServer);
    }

    public static boolean isNewServer() {
@@ -0,0 +1,60 @@
+package stirling.software.SPDF.controller.api.converters;
+
+import java.nio.charset.StandardCharsets;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ControllerAdvice;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.ResponseBody;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.SPDF.exception.CacheUnavailableException;
+
+@ControllerAdvice(assignableTypes = ConvertPdfJsonController.class)
+@Slf4j
+@RequiredArgsConstructor
+public class ConvertPdfJsonExceptionHandler {
+
+    private final ObjectMapper objectMapper;
+
+    @ExceptionHandler(CacheUnavailableException.class)
+    @ResponseBody
+    public ResponseEntity<byte[]> handleCacheUnavailable(CacheUnavailableException ex) {
+        try {
+            byte[] body =
+                    objectMapper.writeValueAsBytes(
+                            java.util.Map.of(
+                                    "error", "cache_unavailable",
+                                    "action", "reupload",
+                                    "message", ex.getMessage()));
+            return ResponseEntity.status(HttpStatus.GONE)
+                    .contentType(MediaType.APPLICATION_JSON)
+                    .body(body);
+        } catch (Exception e) {
+            log.warn("Failed to serialize cache_unavailable response", e);
+            var fallbackBody =
+                    java.util.Map.of(
+                            "error", "cache_unavailable",
+                            "action", "reupload",
+                            "message", String.valueOf(ex.getMessage()));
+            try {
+                return ResponseEntity.status(HttpStatus.GONE)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .body(objectMapper.writeValueAsBytes(fallbackBody));
+            } catch (Exception ignored) {
+                // Truly last-ditch fallback
+                return ResponseEntity.status(HttpStatus.GONE)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .body(
+                                "{\"error\":\"cache_unavailable\",\"action\":\"reupload\",\"message\":\"Cache unavailable\"}"
+                                        .getBytes(StandardCharsets.UTF_8));
+            }
+        }
+    }
+}
@@ -0,0 +1,8 @@
+package stirling.software.SPDF.exception;
+
+public class CacheUnavailableException extends RuntimeException {
+
+    public CacheUnavailableException(String message) {
+        super(message);
+    }
+}
@@ -86,7 +86,6 @@ import org.apache.pdfbox.text.PDFTextStripper;
 import org.apache.pdfbox.text.TextPosition;
 import org.apache.pdfbox.util.DateConverter;
 import org.apache.pdfbox.util.Matrix;
-import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Service;
 import org.springframework.web.multipart.MultipartFile;

@@ -144,15 +143,23 @@ public class PdfJsonConversionService {
    private final PdfJsonFontService fontService;
    private final Type3FontConversionService type3FontConversionService;
    private final Type3GlyphExtractor type3GlyphExtractor;
+    private final stirling.software.common.model.ApplicationProperties applicationProperties;
    private final Map<String, PDFont> type3NormalizedFontCache = new ConcurrentHashMap<>();
    private final Map<String, Set<Integer>> type3GlyphCoverageCache = new ConcurrentHashMap<>();

-    @Value("${stirling.pdf.json.font-normalization.enabled:true}")
    private boolean fontNormalizationEnabled;
+    private long cacheMaxBytes;
+    private int cacheMaxPercent;

    /** Cache for storing PDDocuments for lazy page loading. Key is jobId. */
    private final Map<String, CachedPdfDocument> documentCache = new ConcurrentHashMap<>();

+    private final java.util.LinkedHashMap<String, CachedPdfDocument> lruCache =
+            new java.util.LinkedHashMap<>(16, 0.75f, true);
+    private final Object cacheLock = new Object();
+    private volatile long currentCacheBytes = 0L;
+    private volatile long cacheBudgetBytes = -1L;
+
    private volatile boolean ghostscriptAvailable;

    private static final float FLOAT_EPSILON = 0.0001f;
@@ -161,7 +168,23 @@ public class PdfJsonConversionService {

    @PostConstruct
    private void initializeToolAvailability() {
+        loadConfigurationFromProperties();
        initializeGhostscriptAvailability();
+        initializeCacheBudget();
+    }
+
+    private void loadConfigurationFromProperties() {
+        stirling.software.common.model.ApplicationProperties.PdfEditor cfg =
+                applicationProperties.getPdfEditor();
+        if (cfg != null) {
+            fontNormalizationEnabled = cfg.getFontNormalization().isEnabled();
+            cacheMaxBytes = cfg.getCache().getMaxBytes();
+            cacheMaxPercent = cfg.getCache().getMaxPercent();
+        } else {
+            fontNormalizationEnabled = false;
+            cacheMaxBytes = -1;
+            cacheMaxPercent = 20;
+        }
    }

    private void initializeGhostscriptAvailability() {
@@ -202,6 +225,25 @@ public class PdfJsonConversionService {
        }
    }

+    private void initializeCacheBudget() {
+        long effective = -1L;
+        if (cacheMaxBytes > 0) {
+            effective = cacheMaxBytes;
+        } else if (cacheMaxPercent > 0) {
+            long maxMem = Runtime.getRuntime().maxMemory();
+            effective = Math.max(0L, (maxMem * cacheMaxPercent) / 100);
+        }
+        cacheBudgetBytes = effective;
+        if (cacheBudgetBytes > 0) {
+            log.info(
+                    "PDF JSON cache budget configured: {} bytes (source: {})",
+                    cacheBudgetBytes,
+                    cacheMaxBytes > 0 ? "max-bytes" : "max-percent");
+        } else {
+            log.info("PDF JSON cache budget: unlimited");
+        }
+    }
+
    public byte[] convertPdfToJson(MultipartFile file) throws IOException {
        return convertPdfToJson(file, null, false);
    }
@@ -236,7 +278,10 @@ public class PdfJsonConversionService {
            log.debug("Generated synthetic jobId for synchronous conversion: {}", jobId);
        } else {
            jobId = contextJobId;
-            log.debug("Starting PDF to JSON conversion, jobId from context: {}", jobId);
+            log.info(
+                    "Starting PDF to JSON conversion, jobId from context: {} (lightweight={})",
+                    jobId,
+                    lightweight);
        }

        Consumer<PdfJsonConversionProgress> progress =
@@ -318,9 +363,9 @@ public class PdfJsonConversionService {

            try (PDDocument document = pdfDocumentFactory.load(workingPath, true)) {
                int totalPages = document.getNumberOfPages();
-                // Only use lazy images for real async jobs where client can access the cache
-                // Synchronous calls with synthetic jobId should do full extraction
-                boolean useLazyImages = totalPages > 5 && isRealJobId;
+                // Always enable lazy mode for real async jobs so cache is available regardless of
+                // page count. Synchronous calls with synthetic jobId still do full extraction.
+                boolean useLazyImages = isRealJobId;
                Map<COSBase, FontModelCacheEntry> fontCache = new IdentityHashMap<>();
                Map<COSBase, EncodedImage> imageCache = new IdentityHashMap<>();
                log.debug(
@@ -403,6 +448,11 @@ public class PdfJsonConversionService {

                // Only cache for real async jobIds, not synthetic synchronous ones
                if (useLazyImages && isRealJobId) {
+                    log.info(
+                            "Creating cache for jobId: {} (useLazyImages={}, isRealJobId={})",
+                            jobId,
+                            useLazyImages,
+                            isRealJobId);
                    PdfJsonDocumentMetadata docMetadata = new PdfJsonDocumentMetadata();
                    docMetadata.setMetadata(pdfJson.getMetadata());
                    docMetadata.setXmpMetadata(pdfJson.getXmpMetadata());
@@ -435,16 +485,23 @@ public class PdfJsonConversionService {
                        cachedPdfBytes = Files.readAllBytes(workingPath);
                    }
                    CachedPdfDocument cached =
-                            new CachedPdfDocument(
-                                    cachedPdfBytes, docMetadata, fonts, pageFontResources);
-                    documentCache.put(jobId, cached);
-                    log.debug(
-                            "Cached PDF bytes ({} bytes, {} pages, {} fonts) for lazy images, jobId: {}",
-                            cachedPdfBytes.length,
+                            buildCachedDocument(
+                                    jobId, cachedPdfBytes, docMetadata, fonts, pageFontResources);
+                    putCachedDocument(jobId, cached);
+                    log.info(
+                            "Successfully cached PDF ({} bytes, {} pages, {} fonts) for jobId: {} (diskBacked={})",
+                            cached.getPdfSize(),
                            totalPages,
                            fonts.size(),
-                            jobId);
+                            jobId,
+                            cached.isDiskBacked());
                    scheduleDocumentCleanup(jobId);
+                } else {
+                    log.warn(
+                            "Skipping cache creation: useLazyImages={}, isRealJobId={}, jobId={}",
+                            useLazyImages,
+                            isRealJobId,
+                            jobId);
                }

                if (lightweight) {
@@ -2973,6 +3030,139 @@ public class PdfJsonConversionService {
        }
    }

+    // Cache helpers
+    private CachedPdfDocument buildCachedDocument(
+            String jobId,
+            byte[] pdfBytes,
+            PdfJsonDocumentMetadata metadata,
+            Map<String, PdfJsonFont> fonts,
+            Map<Integer, Map<PDFont, String>> pageFontResources)
+            throws IOException {
+        if (pdfBytes == null) {
+            throw new IllegalArgumentException("pdfBytes must not be null");
+        }
+        long budget = cacheBudgetBytes;
+        // If single document is larger than budget, spill straight to disk
+        if (budget > 0 && pdfBytes.length > budget) {
+            TempFile tempFile = new TempFile(tempFileManager, ".pdfjsoncache");
+            Files.write(tempFile.getPath(), pdfBytes);
+            log.debug(
+                    "Cached PDF spilled to disk ({} bytes exceeds budget {}) for jobId {}",
+                    pdfBytes.length,
+                    budget,
+                    jobId);
+            return new CachedPdfDocument(
+                    null, tempFile, pdfBytes.length, metadata, fonts, pageFontResources);
+        }
+        return new CachedPdfDocument(
+                pdfBytes, null, pdfBytes.length, metadata, fonts, pageFontResources);
+    }
+
+    private void putCachedDocument(String jobId, CachedPdfDocument cached) {
+        synchronized (cacheLock) {
+            CachedPdfDocument existing = documentCache.put(jobId, cached);
+            if (existing != null) {
+                lruCache.remove(jobId);
+                currentCacheBytes = Math.max(0L, currentCacheBytes - existing.getInMemorySize());
+                existing.close();
+            }
+            lruCache.put(jobId, cached);
+            currentCacheBytes += cached.getInMemorySize();
+            enforceCacheBudget();
+        }
+    }
+
+    private CachedPdfDocument getCachedDocument(String jobId) {
+        synchronized (cacheLock) {
+            CachedPdfDocument cached = documentCache.get(jobId);
+            if (cached != null) {
+                lruCache.remove(jobId);
+                lruCache.put(jobId, cached);
+            }
+            return cached;
+        }
+    }
+
+    private void enforceCacheBudget() {
+        if (cacheBudgetBytes <= 0) {
+            return;
+        }
+        // Must be called under cacheLock
+        java.util.Iterator<java.util.Map.Entry<String, CachedPdfDocument>> it =
+                lruCache.entrySet().iterator();
+        while (currentCacheBytes > cacheBudgetBytes && it.hasNext()) {
+            java.util.Map.Entry<String, CachedPdfDocument> entry = it.next();
+            it.remove();
+            CachedPdfDocument removed = entry.getValue();
+            documentCache.remove(entry.getKey(), removed);
+            currentCacheBytes = Math.max(0L, currentCacheBytes - removed.getInMemorySize());
+            removed.close();
+            log.warn(
+                    "Evicted cached PDF for jobId {} to enforce cache budget (budget={} bytes, current={} bytes)",
+                    entry.getKey(),
+                    cacheBudgetBytes,
+                    currentCacheBytes);
+        }
+        if (currentCacheBytes > cacheBudgetBytes && !lruCache.isEmpty()) {
+            // Spill the most recently used large entry to disk
+            String key =
+                    lruCache.entrySet().stream()
+                            .reduce((first, second) -> second)
+                            .map(java.util.Map.Entry::getKey)
+                            .orElse(null);
+            if (key != null) {
+                CachedPdfDocument doc = lruCache.get(key);
+                if (doc != null && doc.getInMemorySize() > 0) {
+                    try {
+                        CachedPdfDocument diskDoc =
+                                buildCachedDocument(
+                                        key,
+                                        doc.getPdfBytes(),
+                                        doc.getMetadata(),
+                                        doc.getFonts(),
+                                        doc.getPageFontResources());
+                        lruCache.put(key, diskDoc);
+                        documentCache.put(key, diskDoc);
+                        currentCacheBytes =
+                                Math.max(0L, currentCacheBytes - doc.getInMemorySize())
+                                        + diskDoc.getInMemorySize();
+                        doc.close();
+                        log.debug("Spilled cached PDF for jobId {} to disk to satisfy budget", key);
+                    } catch (IOException ex) {
+                        log.warn(
+                                "Failed to spill cached PDF for jobId {} to disk: {}",
+                                key,
+                                ex.getMessage());
+                    }
+                }
+            }
+        }
+    }
+
+    private void removeCachedDocument(String jobId) {
+        log.warn(
+                "removeCachedDocument called for jobId: {} [CALLER: {}]",
+                jobId,
+                Thread.currentThread().getStackTrace()[2].toString());
+        CachedPdfDocument removed = null;
+        synchronized (cacheLock) {
+            removed = documentCache.remove(jobId);
+            if (removed != null) {
+                lruCache.remove(jobId);
+                currentCacheBytes = Math.max(0L, currentCacheBytes - removed.getInMemorySize());
+                log.warn(
+                        "Removed cached document for jobId: {} (size={} bytes)",
+                        jobId,
+                        removed.getInMemorySize());
+            } else {
+                log.warn("Attempted to remove jobId: {} but it was not in cache", jobId);
+            }
+        }
+        if (removed != null) {
+            removed.close();
+        }
+    }
+
    private void applyTextState(PDPageContentStream contentStream, PdfJsonTextElement element)
            throws IOException {
        if (element.getCharacterSpacing() != null) {
@@ -5311,6 +5501,8 @@ public class PdfJsonConversionService {
     */
    private static class CachedPdfDocument {
        private final byte[] pdfBytes;
+        private final TempFile pdfTempFile;
+        private final long pdfSize;
        private final PdfJsonDocumentMetadata metadata;
        private final Map<String, PdfJsonFont> fonts; // Font map with UIDs for consistency
        private final Map<Integer, Map<PDFont, String>> pageFontResources; // Page font resources
@@ -5318,10 +5510,14 @@ public class PdfJsonConversionService {

        public CachedPdfDocument(
                byte[] pdfBytes,
+                TempFile pdfTempFile,
+                long pdfSize,
                PdfJsonDocumentMetadata metadata,
                Map<String, PdfJsonFont> fonts,
                Map<Integer, Map<PDFont, String>> pageFontResources) {
            this.pdfBytes = pdfBytes;
+            this.pdfTempFile = pdfTempFile;
+            this.pdfSize = pdfSize;
            this.metadata = metadata;
            // Create defensive copies to prevent mutation of shared maps
            this.fonts =
@@ -5336,8 +5532,14 @@ public class PdfJsonConversionService {
        }

        // Getters return defensive copies to prevent external mutation
-        public byte[] getPdfBytes() {
-            return pdfBytes;
+        public byte[] getPdfBytes() throws IOException {
+            if (pdfBytes != null) {
+                return pdfBytes;
+            }
+            if (pdfTempFile != null) {
+                return Files.readAllBytes(pdfTempFile.getPath());
+            }
+            throw new IOException("Cached PDF backing missing");
        }

        public PdfJsonDocumentMetadata getMetadata() {
@@ -5352,6 +5554,18 @@ public class PdfJsonConversionService {
            return new java.util.concurrent.ConcurrentHashMap<>(pageFontResources);
        }

+        public long getPdfSize() {
+            return pdfSize;
+        }
+
+        public long getInMemorySize() {
+            return pdfBytes != null ? pdfBytes.length : 0L;
+        }
+
+        public boolean isDiskBacked() {
+            return pdfBytes == null && pdfTempFile != null;
+        }
+
        public long getTimestamp() {
            return timestamp;
        }
@@ -5363,7 +5577,19 @@ public class PdfJsonConversionService {
        public CachedPdfDocument withUpdatedFonts(
                byte[] nextBytes, Map<String, PdfJsonFont> nextFonts) {
            Map<String, PdfJsonFont> fontsToUse = nextFonts != null ? nextFonts : this.fonts;
-            return new CachedPdfDocument(nextBytes, metadata, fontsToUse, pageFontResources);
+            return new CachedPdfDocument(
+                    nextBytes,
+                    null,
+                    nextBytes != null ? nextBytes.length : 0,
+                    metadata,
+                    fontsToUse,
+                    pageFontResources);
+        }
+
+        public void close() {
+            if (pdfTempFile != null) {
+                pdfTempFile.close();
+            }
        }
    }

@@ -5444,14 +5670,15 @@ public class PdfJsonConversionService {
            // Cache PDF bytes, metadata, and fonts for lazy page loading
            if (jobId != null) {
                CachedPdfDocument cached =
-                        new CachedPdfDocument(pdfBytes, docMetadata, fonts, pageFontResources);
-                documentCache.put(jobId, cached);
+                        buildCachedDocument(jobId, pdfBytes, docMetadata, fonts, pageFontResources);
+                putCachedDocument(jobId, cached);
                log.debug(
-                        "Cached PDF bytes ({} bytes, {} pages, {} fonts) for lazy loading, jobId: {}",
-                        pdfBytes.length,
+                        "Cached PDF bytes ({} bytes, {} pages, {} fonts) for lazy loading, jobId: {} (diskBacked={})",
+                        cached.getPdfSize(),
                        totalPages,
                        fonts.size(),
-                        jobId);
+                        jobId,
+                        cached.isDiskBacked());

                // Schedule cleanup after 30 minutes
                scheduleDocumentCleanup(jobId);
@@ -5466,9 +5693,10 @@ public class PdfJsonConversionService {

    /** Extracts a single page from cached PDF bytes. Re-loads the PDF for each request. */
    public byte[] extractSinglePage(String jobId, int pageNumber) throws IOException {
-        CachedPdfDocument cached = documentCache.get(jobId);
+        CachedPdfDocument cached = getCachedDocument(jobId);
        if (cached == null) {
-            throw new IllegalArgumentException("No cached document found for jobId: " + jobId);
+            throw new stirling.software.SPDF.exception.CacheUnavailableException(
+                    "No cached document found for jobId: " + jobId);
        }

        int pageIndex = pageNumber - 1;
@@ -5480,8 +5708,8 @@ public class PdfJsonConversionService {
        }

        log.debug(
-                "Loading PDF from bytes ({} bytes) to extract page {} (jobId: {})",
-                cached.getPdfBytes().length,
+                "Loading PDF from {} to extract page {} (jobId: {})",
+                cached.isDiskBacked() ? "disk cache" : "memory cache",
                pageNumber,
                jobId);

@@ -5627,10 +5855,21 @@ public class PdfJsonConversionService {
        if (jobId == null || jobId.isBlank()) {
            throw new IllegalArgumentException("jobId is required for incremental export");
        }
-        CachedPdfDocument cached = documentCache.get(jobId);
+        log.info("Looking up cache for jobId: {}", jobId);
+        CachedPdfDocument cached = getCachedDocument(jobId);
        if (cached == null) {
-            throw new IllegalArgumentException("No cached document available for jobId: " + jobId);
+            log.error(
+                    "Cache not found for jobId: {}. Available cache keys: {}",
+                    jobId,
+                    documentCache.keySet());
+            throw new stirling.software.SPDF.exception.CacheUnavailableException(
+                    "No cached document available for jobId: " + jobId);
        }
+        log.info(
+                "Found cached document for jobId: {} (size={}, diskBacked={})",
+                jobId,
+                cached.getPdfSize(),
+                cached.isDiskBacked());
        if (updates == null || updates.getPages() == null || updates.getPages().isEmpty()) {
            log.debug(
                    "Incremental export requested with no page updates; returning cached PDF for jobId {}",
@@ -5709,7 +5948,14 @@ public class PdfJsonConversionService {
            document.save(baos);
            byte[] updatedBytes = baos.toByteArray();

-            documentCache.put(jobId, cached.withUpdatedFonts(updatedBytes, mergedFonts));
+            CachedPdfDocument updated =
+                    buildCachedDocument(
+                            jobId,
+                            updatedBytes,
+                            cached.getMetadata(),
+                            mergedFonts,
+                            cached.getPageFontResources());
+            putCachedDocument(jobId, updated);

            // Clear Type3 cache entries for this incremental update
            clearType3CacheEntriesForJob(updateJobId);
@@ -5724,11 +5970,13 @@ public class PdfJsonConversionService {

    /** Clears a cached document. */
    public void clearCachedDocument(String jobId) {
-        CachedPdfDocument cached = documentCache.remove(jobId);
+        CachedPdfDocument cached = getCachedDocument(jobId);
+        removeCachedDocument(jobId);
        if (cached != null) {
            log.debug(
-                    "Removed cached PDF bytes ({} bytes) for jobId: {}",
-                    cached.getPdfBytes().length,
+                    "Removed cached PDF ({} bytes, diskBacked={}) for jobId: {}",
+                    cached.getPdfSize(),
+                    cached.isDiskBacked(),
                    jobId);
        }

@@ -312,12 +312,29 @@ public class PdfJsonFallbackFontService {
                                    "ttf")));

    private final ResourceLoader resourceLoader;
+    private final stirling.software.common.model.ApplicationProperties applicationProperties;

    @Value("${stirling.pdf.fallback-font:" + DEFAULT_FALLBACK_FONT_LOCATION + "}")
+    private String legacyFallbackFontLocation;
+
    private String fallbackFontLocation;

    private final Map<String, byte[]> fallbackFontCache = new ConcurrentHashMap<>();

+    @jakarta.annotation.PostConstruct
+    private void loadConfig() {
+        String configured = null;
+        if (applicationProperties.getPdfEditor() != null) {
+            configured = applicationProperties.getPdfEditor().getFallbackFont();
+        }
+        if (configured != null && !configured.isBlank()) {
+            fallbackFontLocation = configured;
+        } else {
+            fallbackFontLocation = legacyFallbackFontLocation;
+        }
+        log.info("Using fallback font location: {}", fallbackFontLocation);
+    }
+
    public PdfJsonFont buildFallbackFontModel() throws IOException {
        return buildFallbackFontModel(FALLBACK_FONT_ID);
    }
@@ -5,7 +5,6 @@ import java.nio.file.Files;
 import java.util.Base64;
 import java.util.Locale;

-import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Service;

 import jakarta.annotation.PostConstruct;
@@ -25,22 +24,16 @@ import stirling.software.common.util.TempFileManager;
 public class PdfJsonFontService {

    private final TempFileManager tempFileManager;
+    private final stirling.software.common.model.ApplicationProperties applicationProperties;

-    @Getter
-    @Value("${stirling.pdf.json.cff-converter.enabled:true}")
-    private boolean cffConversionEnabled;
+    @Getter private boolean cffConversionEnabled;

-    @Getter
-    @Value("${stirling.pdf.json.cff-converter.method:python}")
-    private String cffConverterMethod;
+    @Getter private String cffConverterMethod;

-    @Value("${stirling.pdf.json.cff-converter.python-command:/opt/venv/bin/python3}")
    private String pythonCommand;

-    @Value("${stirling.pdf.json.cff-converter.python-script:/scripts/convert_cff_to_ttf.py}")
    private String pythonScript;

-    @Value("${stirling.pdf.json.cff-converter.fontforge-command:fontforge}")
    private String fontforgeCommand;

    private volatile boolean pythonCffConverterAvailable;
@@ -48,6 +41,7 @@ public class PdfJsonFontService {

    @PostConstruct
    private void initialiseCffConverterAvailability() {
+        loadConfiguration();
        if (!cffConversionEnabled) {
            log.warn("[FONT-DEBUG] CFF conversion is DISABLED in configuration");
            pythonCffConverterAvailable = false;
@@ -77,6 +71,22 @@ public class PdfJsonFontService {
        log.info("[FONT-DEBUG] Selected CFF converter method: {}", cffConverterMethod);
    }

+    private void loadConfiguration() {
+        if (applicationProperties.getPdfEditor() != null
+                && applicationProperties.getPdfEditor().getCffConverter() != null) {
+            var cfg = applicationProperties.getPdfEditor().getCffConverter();
+            this.cffConversionEnabled = cfg.isEnabled();
+            this.cffConverterMethod = cfg.getMethod();
+            this.pythonCommand = cfg.getPythonCommand();
+            this.pythonScript = cfg.getPythonScript();
+            this.fontforgeCommand = cfg.getFontforgeCommand();
+        } else {
+            // Use defaults when config is not available
+            this.cffConversionEnabled = false;
+            log.warn("[FONT-DEBUG] PdfEditor configuration not available, CFF conversion disabled");
+        }
+    }
+
    public byte[] convertCffProgramToTrueType(byte[] fontBytes, String toUnicode) {
        if (!cffConversionEnabled || fontBytes == null || fontBytes.length == 0) {
            log.warn(
@@ -2,7 +2,6 @@ package stirling.software.SPDF.service.pdfjson.type3;

 import java.io.IOException;

-import org.springframework.beans.factory.annotation.Value;
 import org.springframework.core.annotation.Order;
 import org.springframework.stereotype.Component;

@@ -23,8 +22,8 @@ import stirling.software.SPDF.service.pdfjson.type3.library.Type3FontLibraryPayl
 public class Type3LibraryStrategy implements Type3ConversionStrategy {

    private final Type3FontLibrary fontLibrary;
+    private final stirling.software.common.model.ApplicationProperties applicationProperties;

-    @Value("${stirling.pdf.json.type3.library.enabled:true}")
    private boolean enabled;

    @Override
@@ -42,6 +41,19 @@ public class Type3LibraryStrategy implements Type3ConversionStrategy {
        return enabled && fontLibrary != null && fontLibrary.isLoaded();
    }

+    @jakarta.annotation.PostConstruct
+    private void loadConfiguration() {
+        if (applicationProperties.getPdfEditor() != null
+                && applicationProperties.getPdfEditor().getType3() != null
+                && applicationProperties.getPdfEditor().getType3().getLibrary() != null) {
+            var cfg = applicationProperties.getPdfEditor().getType3().getLibrary();
+            this.enabled = cfg.isEnabled();
+        } else {
+            this.enabled = false;
+            log.warn("PdfEditor Type3 library configuration not available, disabled");
+        }
+    }
+
    @Override
    public PdfJsonFontConversionCandidate convert(
            Type3ConversionRequest request, Type3GlyphContext context) throws IOException {
@@ -14,7 +14,6 @@ import java.util.stream.Collectors;

 import org.apache.pdfbox.cos.COSName;
 import org.apache.pdfbox.pdmodel.font.PDType3Font;
-import org.springframework.beans.factory.annotation.Value;
 import org.springframework.core.io.Resource;
 import org.springframework.core.io.ResourceLoader;
 import org.springframework.stereotype.Component;
@@ -34,8 +33,8 @@ public class Type3FontLibrary {

    private final ObjectMapper objectMapper;
    private final ResourceLoader resourceLoader;
+    private final stirling.software.common.model.ApplicationProperties applicationProperties;

-    @Value("${stirling.pdf.json.type3.library.index:classpath:/type3/library/index.json}")
    private String indexLocation;

    private final Map<String, Type3FontLibraryEntry> signatureIndex = new ConcurrentHashMap<>();
@@ -44,6 +43,17 @@ public class Type3FontLibrary {

    @jakarta.annotation.PostConstruct
    void initialise() {
+        if (applicationProperties.getPdfEditor() != null
+                && applicationProperties.getPdfEditor().getType3() != null
+                && applicationProperties.getPdfEditor().getType3().getLibrary() != null) {
+            this.indexLocation =
+                    applicationProperties.getPdfEditor().getType3().getLibrary().getIndex();
+        } else {
+            log.warn(
+                    "[TYPE3] PdfEditor Type3 library configuration not available; Type3 library disabled");
+            entries = List.of();
+            return;
+        }
        Resource resource = resourceLoader.getResource(indexLocation);
        if (!resource.exists()) {
            log.info("[TYPE3] Library index {} not found; Type3 library disabled", indexLocation);
@@ -58,6 +58,8 @@ security:
    idpCert: classpath:okta.cert # The certificate your Provider will use to authenticate your app's SAML authentication requests. Provided by your Provider
    privateKey: classpath:saml-private-key.key # Your private key. Generated from your keypair
    spCert: classpath:saml-public-cert.crt # Your signing certificate. Generated from your keypair
+    # IMPORTANT: For SAML setup, download your SP metadata from the BACKEND URL: http://localhost:8080/saml2/service-provider-metadata/{registrationId}
+    # Do NOT use the frontend dev server URL (localhost:5173) as it will generate incorrect ACS URLs. Always use the backend URL (localhost:8080) for SAML configuration.
  jwt: # This feature is currently under development and not yet fully supported. Do not use in production.
    persistence: true # Set to 'true' to enable JWT key store
    enableKeyRotation: true # Set to 'true' to enable key pair rotation
@@ -132,8 +134,9 @@ system:
  enableUrlToPDF: false # Set to 'true' to enable URL to PDF, INTERNAL ONLY, known security issues, should not be used externally
  disableSanitize: false # set to true to disable Sanitize HTML; (can lead to injections in HTML)
  maxDPI: 500 # Maximum allowed DPI for PDF to image conversion
-  corsAllowedOrigins: [] # List of allowed origins for CORS (e.g. ['http://localhost:5173', 'https://app.example.com']). Leave empty to disable CORS.
-  frontendUrl: '' # Base URL for frontend (e.g. 'https://pdf.example.com'). Used for generating invite links in emails. If empty, falls back to backend URL.
+  corsAllowedOrigins: [] # List of allowed origins for CORS (e.g. ['http://localhost:5173', 'https://app.example.com']). Leave empty to disable CORS. For local development with frontend on port 5173, add 'http://localhost:5173'
+  backendUrl: '' # Backend base URL for SAML/OAuth/API callbacks (e.g. 'http://localhost:8080' for dev, 'https://api.example.com' for production). REQUIRED for SSO authentication to work correctly. This is where your IdP will send SAML responses and OAuth callbacks. Leave empty to default to 'http://localhost:8080' in development.
+  frontendUrl: '' # Frontend URL for invite email links (e.g. 'https://app.example.com'). Optional - if not set, will use backendUrl. This is the URL users click in invite emails.
  serverCertificate:
    enabled: true # Enable server-side certificate for "Sign with Stirling-PDF" option
    organizationName: Stirling-PDF # Organization name for generated certificates
@@ -179,23 +182,6 @@ system:
  databaseBackup:
    cron: '0 0 0 * * ?' # Cron expression for automatic database backups "0 0 0 * * ?" daily at midnight

-stirling:
-  pdf:
-    fallback-font: classpath:/static/fonts/NotoSans-Regular.ttf # Override to point at a custom fallback font
-    json:
-      font-normalization:
-        enabled: false # IMPORTANT: Disable to preserve ToUnicode CMaps for correct font rendering. Ghostscript strips Unicode mappings from CID fonts.
-      cff-converter:
-        enabled: true # Wrap CFF/Type1C fonts as OpenType-CFF for browser compatibility
-        method: python # Converter method: 'python' (fontTools, recommended - wraps as OTF), 'fontforge' (legacy - converts to TTF, may hang on CID fonts)
-        python-command: /opt/venv/bin/python3 # Python interpreter path
-        python-script: /scripts/convert_cff_to_ttf.py # Path to font wrapping script
-        fontforge-command: fontforge # Override if FontForge is installed under a different name/path
-      type3:
-        library:
-          enabled: true # Match common Type3 fonts against the built-in library of converted programs
-          index: classpath:/type3/library/index.json # Override to point at a custom index.json (supports http:, file:, classpath:)
-
 ui:
  appNameNavbar: '' # name displayed on the navigation bar
  logoStyle: classic # Options: 'classic' (default - classic S icon) or 'modern' (minimalist logo)
@@ -239,3 +225,21 @@ processExecutor:
    qpdfTimeoutMinutes: 30
    ghostscriptTimeoutMinutes: 30
    ocrMyPdfTimeoutMinutes: 30
+
+pdfEditor:
+  fallback-font: classpath:/static/fonts/NotoSans-Regular.ttf # Override to point at a custom fallback font
+  cache:
+    max-bytes: -1 # Max in-memory cache size in bytes; -1 disables byte cap
+    max-percent: 20 # Max in-memory cache as % of JVM max; used when max-bytes <= 0
+  font-normalization:
+    enabled: false # IMPORTANT: Disable to preserve ToUnicode CMaps for correct font rendering. Ghostscript strips Unicode mappings from CID fonts.
+  cff-converter:
+    enabled: true # Wrap CFF/Type1CFF fonts as OpenType-CFF for browser compatibility
+    method: python # Converter method: 'python' (fontTools, recommended - wraps as OTF), 'fontforge' (legacy - converts to TTF, may hang on CID fonts)
+    python-command: /opt/venv/bin/python3 # Python interpreter path
+    python-script: /scripts/convert_cff_to_ttf.py # Path to font wrapping script
+    fontforge-command: fontforge # Override if FontForge is installed under a different name/path
+  type3:
+    library:
+      enabled: true # Match common Type3 fonts against the built-in library of converted programs
+      index: classpath:/type3/library/index.json # Override to point at a custom index.json (supports http:, file:, classpath:)