feat(docker): update base images to Java 25, Spring 4, Jackson 3, Gradle 9 and optimize JVM options (Project Lilliput) (#5725)

Co-authored-by: Anthony Stirling <[email protected]>

app/common/build.gradle

@@ -27,8 +27,8 @@ spotless {
     }
 }
 dependencies {
-    api 'org.springframework.boot:spring-boot-starter-web'
-    api 'org.springframework.boot:spring-boot-starter-aop'
+    api 'org.springframework.boot:spring-boot-starter-webmvc'
+    api 'org.springframework.boot:spring-boot-starter-aspectj'
     api 'com.googlecode.owasp-java-html-sanitizer:owasp-java-html-sanitizer:20240325.1'
     api 'com.fathzer:javaluator:3.0.6'
     api 'com.posthog.java:posthog:1.2.0'
@@ -42,7 +42,7 @@ dependencies {
     api 'com.github.junrar:junrar:7.5.7' // RAR archive support for CBR files
     api 'jakarta.servlet:jakarta.servlet-api:6.1.0'
     api 'org.snakeyaml:snakeyaml-engine:3.0.1'
-    api "org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.15"
+    api "org.springdoc:springdoc-openapi-starter-webmvc-ui:3.0.1"
     // Simple Java Mail for EML/MSG parsing (replaces direct Angus Mail usage)
     api 'org.simplejavamail:simple-java-mail:8.12.6'
     api 'org.simplejavamail:outlook-module:8.12.6' // MSG file support

app/common/src/main/java/stirling/software/common/configuration/RuntimePathConfig.java

@@ -91,9 +91,9 @@ public class RuntimePathConfig {
 
         // Initialize Operation paths
         String defaultWeasyPrintPath = isDocker ? "/opt/venv/bin/weasyprint" : "weasyprint";
-        String defaultUnoConvertPath = isDocker ? "/opt/venv/bin/unoconvert" : "unoconvert";
+        String defaultUnoConvertPath = isDocker ? "/usr/local/bin/unoconvert" : "unoconvert";
         String defaultCalibrePath = isDocker ? "/opt/calibre/ebook-convert" : "ebook-convert";
-        String defaultOcrMyPdfPath = isDocker ? "/usr/bin/ocrmypdf" : "ocrmypdf";
+        String defaultOcrMyPdfPath = isDocker ? "/opt/venv/bin/ocrmypdf" : "ocrmypdf";
         String defaultSOfficePath = isDocker ? "/usr/bin/soffice" : "soffice";
 
         Operations operations = customPaths.getOperations();

app/common/src/main/java/stirling/software/common/configuration/SchedulingConfig.java

@@ -0,0 +1,23 @@
+package stirling.software.common.configuration;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.scheduling.TaskScheduler;
+import org.springframework.scheduling.concurrent.SimpleAsyncTaskScheduler;
+
+/**
+ * Configures the scheduler used by all {@code @Scheduled} methods. Uses virtual threads so that
+ * long-running scheduled tasks (e.g. cleanup, license checks, file monitoring) never block each
+ * other — each runs on its own lightweight virtual thread.
+ */
+@Configuration
+public class SchedulingConfig {
+
+    @Bean
+    public TaskScheduler taskScheduler() {
+        SimpleAsyncTaskScheduler scheduler = new SimpleAsyncTaskScheduler();
+        scheduler.setVirtualThreads(true);
+        scheduler.setThreadNamePrefix("scheduled-vt-");
+        return scheduler;
+    }
+}

app/common/src/main/java/stirling/software/common/service/JobExecutorService.java

@@ -35,7 +35,7 @@ public class JobExecutorService {
     private final HttpServletRequest request;
     private final ResourceMonitor resourceMonitor;
     private final JobQueue jobQueue;
-    private final ExecutorService executor = ExecutorFactory.newVirtualOrCachedThreadExecutor();
+    private final ExecutorService executor = ExecutorFactory.newVirtualThreadExecutor();
     private final long effectiveTimeoutMs;
 
     @Autowired(required = false)

app/common/src/main/java/stirling/software/common/service/JobQueue.java

@@ -44,8 +44,10 @@ public class JobQueue implements SmartLifecycle {
 
     private volatile BlockingQueue<QueuedJob> jobQueue;
     private final Map<String, QueuedJob> jobMap = new ConcurrentHashMap<>();
-    private final ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor();
-    private final ExecutorService jobExecutor = ExecutorFactory.newVirtualOrCachedThreadExecutor();
+    private final ScheduledExecutorService scheduler =
+            Executors.newSingleThreadScheduledExecutor(
+                    Thread.ofVirtual().name("job-queue-scheduler-", 0).factory());
+    private final ExecutorService jobExecutor = ExecutorFactory.newVirtualThreadExecutor();
     private final Object queueLock = new Object(); // Lock for synchronizing queue operations
 
     private boolean shuttingDown = false;

app/common/src/main/java/stirling/software/common/service/ResourceMonitor.java

@@ -43,7 +43,9 @@ public class ResourceMonitor {
     @Value("${stirling.resource.monitor.interval-ms:60000}")
     private long monitorIntervalMs = 60000; // 60 seconds
 
-    private final ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor();
+    private final ScheduledExecutorService scheduler =
+            Executors.newSingleThreadScheduledExecutor(
+                    Thread.ofVirtual().name("resource-monitor-", 0).factory());
     private final MemoryMXBean memoryMXBean = ManagementFactory.getMemoryMXBean();
     private final OperatingSystemMXBean osMXBean = ManagementFactory.getOperatingSystemMXBean();
 

app/common/src/main/java/stirling/software/common/service/TaskManager.java

@@ -42,7 +42,8 @@ public class TaskManager {
 
     private final FileStorage fileStorage;
     private final ScheduledExecutorService cleanupExecutor =
-            Executors.newSingleThreadScheduledExecutor();
+            Executors.newSingleThreadScheduledExecutor(
+                    Thread.ofVirtual().name("task-cleanup-", 0).factory());
 
     /** Initialize the task manager and start the cleanup scheduler */
     public TaskManager(FileStorage fileStorage) {

app/common/src/main/java/stirling/software/common/util/ExecutorFactory.java

@@ -2,30 +2,28 @@ package stirling.software.common.util;
 
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
 
-import lombok.extern.slf4j.Slf4j;
+/**
+ * Factory for creating executors backed by virtual threads (Java 21+). Virtual threads are
+ * lightweight, managed by the JVM, and ideal for I/O-bound tasks. They eliminate the need for
+ * thread pool sizing since thousands can run concurrently with minimal overhead.
+ */
+public final class ExecutorFactory {
 
-@Slf4j
-public class ExecutorFactory {
+    private ExecutorFactory() {}
+
+    /** Creates an {@link ExecutorService} that starts a new virtual thread for each task. */
+    public static ExecutorService newVirtualThreadExecutor() {
+        return Executors.newVirtualThreadPerTaskExecutor();
+    }
 
     /**
-     * Creates an ExecutorService using virtual threads if available (Java 21+), or falls back to a
-     * cached thread pool on older Java versions.
+     * Creates a {@link ScheduledExecutorService} backed by a single virtual thread. Useful for
+     * periodic/delayed tasks that should not pin a platform thread.
      */
-    public static ExecutorService newVirtualOrCachedThreadExecutor() {
-        try {
-            ExecutorService executor =
-                    (ExecutorService)
-                            Executors.class
-                                    .getMethod("newVirtualThreadPerTaskExecutor")
-                                    .invoke(null);
-            return executor;
-        } catch (NoSuchMethodException e) {
-            log.debug("Virtual threads not available; falling back to cached thread pool.");
-        } catch (Exception e) {
-            log.debug("Error initializing virtual thread executor: {}", e.getMessage(), e);
-        }
-
-        return Executors.newCachedThreadPool();
+    public static ScheduledExecutorService newSingleVirtualThreadScheduledExecutor() {
+        return Executors.newSingleThreadScheduledExecutor(
+                Thread.ofVirtual().name("scheduled-vt-", 0).factory());
     }
 }

app/common/src/main/java/stirling/software/common/util/FileMonitor.java

@@ -68,6 +68,17 @@ public class FileMonitor {
 
         if (this.rootDirs.isEmpty()) {
             log.error("No valid directories to monitor - FileMonitor will not function");
+        } else {
+            // Register directories eagerly so the first @Scheduled tick does not warn.
+            for (Path rootDir : this.rootDirs) {
+                if (Files.exists(rootDir)) {
+                    try {
+                        recursivelyRegisterEntry(rootDir);
+                    } catch (IOException e) {
+                        log.error("Failed to register monitoring for {}", rootDir, e);
+                    }
+                }
+            }
         }
     }
 

app/common/src/main/java/stirling/software/common/util/GeneralUtils.java

@@ -649,7 +649,8 @@ public class GeneralUtils {
     }
 
     public List<Integer> parsePageList(String[] pages, int totalPages, boolean oneBased) {
-        List<Integer> result = new ArrayList<>();
+        // Use LinkedHashSet to prevent duplicates from inflating size and triggering maxSize guard
+        Set<Integer> result = new LinkedHashSet<>();
         int offset = oneBased ? 1 : 0;
         int maxSize = Math.max(1000, totalPages * 3);
         for (String page : pages) {
@@ -672,7 +673,7 @@ public class GeneralUtils {
                         "Page list exceeds maximum allowed size of " + maxSize);
             }
         }
-        return result;
+        return new ArrayList<>(result);
     }
 
     /*

app/common/src/main/java/stirling/software/common/util/ProcessExecutor.java

@@ -226,50 +226,54 @@ public class ProcessExecutor {
             List<String> outputLines = new ArrayList<>();
 
             Thread errorReaderThread =
-                    new Thread(
-                            () -> {
-                                try (BufferedReader errorReader =
-                                        new BufferedReader(
-                                                new InputStreamReader(
-                                                        process.getErrorStream(),
-                                                        StandardCharsets.UTF_8))) {
-                                    String line;
-                                    while ((line =
-                                                    BoundedLineReader.readLine(
-                                                            errorReader, 5_000_000))
-                                            != null) {
-                                        errorLines.add(line);
-                                        if (liveUpdates) log.info(line);
-                                    }
-                                } catch (InterruptedIOException e) {
-                                    log.warn("Error reader thread was interrupted due to timeout.");
-                                } catch (IOException e) {
-                                    log.error("exception", e);
-                                }
-                            });
+                    Thread.ofVirtual()
+                            .unstarted(
+                                    () -> {
+                                        try (BufferedReader errorReader =
+                                                new BufferedReader(
+                                                        new InputStreamReader(
+                                                                process.getErrorStream(),
+                                                                StandardCharsets.UTF_8))) {
+                                            String line;
+                                            while ((line =
+                                                            BoundedLineReader.readLine(
+                                                                    errorReader, 5_000_000))
+                                                    != null) {
+                                                errorLines.add(line);
+                                                if (liveUpdates) log.info(line);
+                                            }
+                                        } catch (InterruptedIOException e) {
+                                            log.warn(
+                                                    "Error reader thread was interrupted due to timeout.");
+                                        } catch (IOException e) {
+                                            log.error("exception", e);
+                                        }
+                                    });
 
             Thread outputReaderThread =
-                    new Thread(
-                            () -> {
-                                try (BufferedReader outputReader =
-                                        new BufferedReader(
-                                                new InputStreamReader(
-                                                        process.getInputStream(),
-                                                        StandardCharsets.UTF_8))) {
-                                    String line;
-                                    while ((line =
-                                                    BoundedLineReader.readLine(
-                                                            outputReader, 5_000_000))
-                                            != null) {
-                                        outputLines.add(line);
-                                        if (liveUpdates) log.info(line);
-                                    }
-                                } catch (InterruptedIOException e) {
-                                    log.warn("Error reader thread was interrupted due to timeout.");
-                                } catch (IOException e) {
-                                    log.error("exception", e);
-                                }
-                            });
+                    Thread.ofVirtual()
+                            .unstarted(
+                                    () -> {
+                                        try (BufferedReader outputReader =
+                                                new BufferedReader(
+                                                        new InputStreamReader(
+                                                                process.getInputStream(),
+                                                                StandardCharsets.UTF_8))) {
+                                            String line;
+                                            while ((line =
+                                                            BoundedLineReader.readLine(
+                                                                    outputReader, 5_000_000))
+                                                    != null) {
+                                                outputLines.add(line);
+                                                if (liveUpdates) log.info(line);
+                                            }
+                                        } catch (InterruptedIOException e) {
+                                            log.warn(
+                                                    "Error reader thread was interrupted due to timeout.");
+                                        } catch (IOException e) {
+                                            log.error("exception", e);
+                                        }
+                                    });
 
             errorReaderThread.start();
             outputReaderThread.start();
@@ -370,7 +374,7 @@ public class ProcessExecutor {
             }
             // Match common unoconvert variants (but NOT soffice)
             String lowerBasename = basename.toLowerCase(java.util.Locale.ROOT);
-            if (lowerBasename.contains("unoconvert") || lowerBasename.equals("unoconv")) {
+            if (lowerBasename.contains("unoconvert") || "unoconv".equals(lowerBasename)) {
                 return true;
             }
         }

app/common/src/main/java/stirling/software/common/util/propertyeditor/StringToArrayListPropertyEditor.java

@@ -4,18 +4,23 @@ import java.beans.PropertyEditorSupport;
 import java.util.ArrayList;
 import java.util.List;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.DeserializationFeature;
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import lombok.extern.slf4j.Slf4j;
 
 import stirling.software.common.model.api.security.RedactionArea;
 
+import tools.jackson.core.type.TypeReference;
+import tools.jackson.databind.DeserializationFeature;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.json.JsonMapper;
+
 @Slf4j
 public class StringToArrayListPropertyEditor extends PropertyEditorSupport {
 
-    private final ObjectMapper objectMapper = new ObjectMapper();
+    private final ObjectMapper objectMapper =
+            JsonMapper.builder()
+                    .enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
+                    .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
+                    .build();
 
     @Override
     public void setAsText(String text) throws IllegalArgumentException {
@@ -24,7 +29,6 @@ public class StringToArrayListPropertyEditor extends PropertyEditorSupport {
             return;
         }
         try {
-            objectMapper.configure(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY, true);
             TypeReference<ArrayList<RedactionArea>> typeRef = new TypeReference<>() {};
             List<RedactionArea> list = objectMapper.readValue(text, typeRef);
             setValue(list);

app/common/src/main/java/stirling/software/common/util/propertyeditor/StringToMapPropertyEditor.java

@@ -4,12 +4,13 @@ import java.beans.PropertyEditorSupport;
 import java.util.HashMap;
 import java.util.Map;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.core.type.TypeReference;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.json.JsonMapper;
 
 public class StringToMapPropertyEditor extends PropertyEditorSupport {
 
-    private final ObjectMapper objectMapper = new ObjectMapper();
+    private final ObjectMapper objectMapper = JsonMapper.builder().build();
 
     @Override
     public void setAsText(String text) throws IllegalArgumentException {

app/common/src/test/java/stirling/software/common/service/SpyPDFDocumentFactory.java

@@ -12,11 +12,12 @@ class SpyPDFDocumentFactory extends CustomPDFDocumentFactory {
     public StrategyType lastStrategyUsed;
 
     public SpyPDFDocumentFactory(PdfMetadataService service) {
-        super(service);
+        super(service); // TempFileManager falls back to Files.createTempFile in tests
     }
 
     @Override
-    public StreamCacheCreateFunction getStreamCacheFunction(long contentSize) {
+    protected StreamCacheCreateFunction getStreamCacheFunction(
+            long contentSize, MemorySnapshot mem) {
         StrategyType type;
         if (contentSize < 10 * 1024 * 1024) {
             type = StrategyType.MEMORY_ONLY;
@@ -26,6 +27,6 @@ class SpyPDFDocumentFactory extends CustomPDFDocumentFactory {
             type = StrategyType.TEMP_FILE;
         }
         this.lastStrategyUsed = type;
-        return super.getStreamCacheFunction(contentSize); // delegate to real behavior
+        return super.getStreamCacheFunction(contentSize, mem);
     }
 }

app/common/src/test/java/stirling/software/common/util/UnoServerPoolTest.java

@@ -121,17 +121,19 @@ public class UnoServerPoolTest {
 
         // Try to acquire a third endpoint in separate thread (should block)
         Thread blockingThread =
-                new Thread(
-                        () -> {
-                            try {
-                                acquireLatch.countDown(); // Signal we're about to block
-                                UnoServerPool.UnoServerLease lease3 = pool.acquireEndpoint();
-                                acquired.incrementAndGet();
-                                lease3.close();
-                            } catch (InterruptedException e) {
-                                Thread.currentThread().interrupt();
-                            }
-                        });
+                Thread.ofVirtual()
+                        .unstarted(
+                                () -> {
+                                    try {
+                                        acquireLatch.countDown(); // Signal we're about to block
+                                        UnoServerPool.UnoServerLease lease3 =
+                                                pool.acquireEndpoint();
+                                        acquired.incrementAndGet();
+                                        lease3.close();
+                                    } catch (InterruptedException e) {
+                                        Thread.currentThread().interrupt();
+                                    }
+                                });
 
         blockingThread.start();
         acquireLatch.await(); // Wait for thread to start

app/common/src/test/java/stirling/software/common/util/propertyeditor/StringToArrayListPropertyEditorTest.java

@@ -143,11 +143,21 @@ class StringToArrayListPropertyEditorTest {
     }
 
     @Test
-    void testSetAsText_InvalidStructure() {
-        // Arrange - this JSON doesn't match RedactionArea structure
+    void testSetAsText_UnknownProperties() {
+        // Arrange - this JSON contains properties not in RedactionArea
+        // With FAIL_ON_UNKNOWN_PROPERTIES disabled, this should ignore the unknown properties
         String json = "[{\"invalid\":\"structure\"}]";
 
-        // Act & Assert
-        assertThrows(IllegalArgumentException.class, () -> editor.setAsText(json));
+        // Act
+        editor.setAsText(json);
+        Object value = editor.getValue();
+
+        // Assert
+        assertNotNull(value, "Value should not be null");
+        assertInstanceOf(List.class, value, "Value should be a List");
+
+        @SuppressWarnings("unchecked")
+        List<RedactionArea> list = (List<RedactionArea>) value;
+        assertEquals(1, list.size(), "List should have 1 entry (empty object)");
     }
 }