fix: stop the streaming queue shrinking with the pool on small instances

Tying queue capacity to max-threads made sense at Cloud's 32 threads and was
punishing everywhere else. A default self-hosted install derives 3 streaming
threads from Hikari's default pool of 10, which gave it a six-request admission
window — and import-progress streams hold a thread for the whole import, so three
concurrent imports made every export and machine-translation suggestion fail with
503 where they previously queued and completed.

A burst is the same size regardless of how many threads drain it, so the queue now
floors at 50 and only follows the thread count above that. Cloud is unaffected (it
pins 32), and the 180s async timeout still bounds how long anything can wait —
answered as 503 rather than left hanging, which is what this change fixed earlier.

The capacity report now includes the queue capacity, which is the number that
decides whether a burst is absorbed or rejected, and counts the two serial pools
it also creates. The serial pools' keep-alive constant is no longer named after
websockets now that automations use it too.

Author: JanCizmar

backend/app/src/main/kotlin/io/tolgee/configuration/AsyncCapacityReporter.kt

@@ -15,6 +15,7 @@ class AsyncCapacityReporter(
   @EventListener(ApplicationReadyEvent::class)
   fun report() {
     val streaming = asyncExecutorFactory.streamingMaxThreads
+    val streamingQueue = asyncExecutorFactory.streamingQueueCapacity
     val background = asyncExecutorFactory.backgroundMaxThreads
     val batch = tolgeeProperties.batch.concurrency
     val connectionPoolSize = asyncExecutorFactory.connectionPoolSize
@@ -30,11 +31,11 @@ class AsyncCapacityReporter(
     }
 
     logger.info(
-      "Async capacity: $streaming streaming threads, $background background threads, " +
-        "$batch batch jobs, $connectionPoolSize database connections.",
+      "Async capacity: $streaming streaming threads (queue $streamingQueue), $background background " +
+        "threads, $SERIAL_POOLS serial pools, $batch batch jobs, $connectionPoolSize database connections.",
     )
 
-    val reserved = streaming + background + batch
+    val reserved = streaming + background + batch + SERIAL_POOLS
     if (reserved <= connectionPoolSize - minimumSyncReserve(connectionPoolSize)) return
 
     logger.warn(
@@ -56,5 +57,8 @@ class AsyncCapacityReporter(
 
   companion object {
     const val SYNC_RESERVE_DIVISOR = 4
+
+    /** The websocket and automation executors, one thread each. */
+    const val SERIAL_POOLS = 2
   }
 }

backend/app/src/main/kotlin/io/tolgee/configuration/AsyncExecutorFactory.kt

@@ -27,7 +27,7 @@ class AsyncExecutorFactory(
     get() {
       val configured = tolgeeProperties.async.streaming.queueCapacity
       if (configured >= 0) return configured
-      return streamingMaxThreads
+      return maxOf(MIN_QUEUE_CAPACITY, streamingMaxThreads)
     }
 
   val backgroundMaxThreads: Int
@@ -80,6 +80,9 @@ class AsyncExecutorFactory(
     const val STREAMING_POOL_DIVISOR = 3
     const val BACKGROUND_POOL_DIVISOR = 6
     const val FALLBACK_CONNECTION_POOL_SIZE = 10
+
+    /** A burst is a burst regardless of how many threads drain it; 3 threads still deserve a buffer. */
+    const val MIN_QUEUE_CAPACITY = 50
     const val SHUTDOWN_DRAIN_SECONDS = 20
 
     const val UNBOUNDED_QUEUE = Int.MAX_VALUE

backend/app/src/main/kotlin/io/tolgee/configuration/AsyncMethodConfiguration.kt

@@ -44,7 +44,7 @@ class AsyncMethodConfiguration(
       threadNamePrefix = AsyncExecutorFactory.WEBSOCKET_THREAD_NAME_PREFIX,
       maxThreads = 1,
       queueCapacity = AsyncExecutorFactory.UNBOUNDED_QUEUE,
-      keepAliveSeconds = WEBSOCKET_KEEP_ALIVE_SECONDS,
+      keepAliveSeconds = SERIAL_POOL_KEEP_ALIVE_SECONDS,
     )
 
   /**
@@ -58,13 +58,13 @@ class AsyncMethodConfiguration(
       threadNamePrefix = AsyncExecutorFactory.AUTOMATION_THREAD_NAME_PREFIX,
       maxThreads = 1,
       queueCapacity = AsyncExecutorFactory.UNBOUNDED_QUEUE,
-      keepAliveSeconds = WEBSOCKET_KEEP_ALIVE_SECONDS,
+      keepAliveSeconds = SERIAL_POOL_KEEP_ALIVE_SECONDS,
     )
 
   companion object {
     const val BACKGROUND_EXECUTOR_BEAN_NAME = "backgroundAsyncExecutor"
     const val WEBSOCKET_EXECUTOR_BEAN_NAME = "websocketAsyncExecutor"
     const val AUTOMATION_EXECUTOR_BEAN_NAME = "automationAsyncExecutor"
-    const val WEBSOCKET_KEEP_ALIVE_SECONDS = 60
+    const val SERIAL_POOL_KEEP_ALIVE_SECONDS = 60
   }
 }

backend/app/src/test/kotlin/io/tolgee/configuration/AsyncCapacityReporterTest.kt

@@ -39,8 +39,9 @@ class AsyncCapacityReporterTest {
 
   @Test
   fun `sits exactly on the boundary without warning, and warns one job past it`() {
-    report(connectionPoolSize = 60, batchConcurrency = 15).warnings.assert.isEmpty()
-    report(connectionPoolSize = 60, batchConcurrency = 16).warnings.assert.isNotEmpty()
+    // 60 -> 20 streaming + 10 background + 2 serial, reserve 60/4 = 15.
+    report(connectionPoolSize = 60, batchConcurrency = 13).warnings.assert.isEmpty()
+    report(connectionPoolSize = 60, batchConcurrency = 14).warnings.assert.isNotEmpty()
   }
 
   @Test

backend/app/src/test/kotlin/io/tolgee/configuration/AsyncExecutorConfigurationTest.kt

@@ -57,7 +57,7 @@ class AsyncExecutorConfigurationTest {
 
     asyncExecutorFactory.connectionPoolSize.assert.isEqualTo(100)
     asyncExecutorFactory.streamingMaxThreads.assert.isEqualTo(33)
-    asyncExecutorFactory.streamingQueueCapacity.assert.isEqualTo(33)
+    asyncExecutorFactory.streamingQueueCapacity.assert.isEqualTo(AsyncExecutorFactory.MIN_QUEUE_CAPACITY)
     asyncExecutorFactory.backgroundMaxThreads.assert.isEqualTo(16)
   }
 
@@ -74,7 +74,7 @@ class AsyncExecutorConfigurationTest {
     streamingAsyncExecutor.threadPoolExecutor.queue
       .remainingCapacity()
       .assert
-      .isEqualTo(33)
+      .isEqualTo(AsyncExecutorFactory.MIN_QUEUE_CAPACITY)
     asyncMethodConfiguration
       .backgroundAsyncExecutor()
       .threadPoolExecutor.queue
@@ -91,13 +91,17 @@ class AsyncExecutorConfigurationTest {
   /** Without these, context close rejects in-flight submissions into their callers. */
   @Test
   fun `executors keep accepting work while the context closes`() {
-    listOf(streamingAsyncExecutor, backgroundAsyncExecutor, asyncMethodConfiguration.websocketAsyncExecutor())
-      .forEach { executor ->
-        ReflectionTestUtils
-          .getField(executor, "acceptTasksAfterContextClose")
-          .assert
-          .isEqualTo(true)
-      }
+    listOf(
+      streamingAsyncExecutor,
+      backgroundAsyncExecutor,
+      asyncMethodConfiguration.websocketAsyncExecutor(),
+      asyncMethodConfiguration.automationAsyncExecutor(),
+    ).forEach { executor ->
+      ReflectionTestUtils
+        .getField(executor, "acceptTasksAfterContextClose")
+        .assert
+        .isEqualTo(true)
+    }
   }
 
   /** Background work is worth draining; a queued stream's client is already gone. */
@@ -150,6 +154,11 @@ class AsyncExecutorConfigurationTest {
     val automation = asyncMethodConfiguration.automationAsyncExecutor()
     automation.corePoolSize.assert.isEqualTo(1)
     automation.maxPoolSize.assert.isEqualTo(1)
+    automation.threadNamePrefix.assert.isEqualTo(AsyncExecutorFactory.AUTOMATION_THREAD_NAME_PREFIX)
+    automation.threadPoolExecutor.queue
+      .remainingCapacity()
+      .assert
+      .isEqualTo(Int.MAX_VALUE)
 
     AutomationActivityListener::class.java.declaredMethods
       .filter { it.name == "listen" }

backend/app/src/test/kotlin/io/tolgee/configuration/AsyncPoolSizeDerivationTest.kt

@@ -23,6 +23,15 @@ class AsyncPoolSizeDerivationTest {
     factory.backgroundMaxThreads.assert.isEqualTo(AsyncExecutorFactory.MIN_POOL_SIZE)
   }
 
+  /** A small install still deserves a burst buffer; tying the queue to 3 threads gave it a window of 6. */
+  @Test
+  fun `queue capacity does not shrink with the thread count`() {
+    factory(connectionPoolSize = 10)
+      .streamingQueueCapacity.assert
+      .isEqualTo(AsyncExecutorFactory.MIN_QUEUE_CAPACITY)
+    factory(connectionPoolSize = 600).streamingQueueCapacity.assert.isEqualTo(200)
+  }
+
   @Test
   fun `explicit configuration wins over the derivation`() {
     val properties = TolgeeProperties()

backend/data/src/main/kotlin/io/tolgee/configuration/tolgee/AsyncProperties.kt

@@ -44,10 +44,11 @@ class StreamingAsyncProperties {
     description =
       "How many streaming requests may wait for a free thread before Tolgee replies " +
         "`503 Service Unavailable`.\n\n" +
-        "Keep this small. A queued request already counts against `spring.mvc.async.request-timeout`, " +
-        "so a deep queue only means clients wait the full timeout and fail anyway.",
+        "A queued request already counts against `spring.mvc.async.request-timeout`, so the queue " +
+        "cannot make a request wait longer than that — it absorbs bursts while threads turn over, " +
+        "and requests that still cannot be served in time are answered rather than left hanging.",
     defaultValue = "-1",
-    defaultExplanation = "Same as max-threads",
+    defaultExplanation = "50, or max-threads if that is larger",
   )
   var queueCapacity: Int = -1