fix(prod): audit hardening across batch budget, dispatch, cache, auth example, reader UX

fix(prod): audit hardening across batch budget, dispatch, cache, auth example, reader UX (#48)

Author: fgapel

.env.hub.example

@@ -7,8 +7,11 @@
 BT_ENABLE_CWA=true
 BT_ENABLE_KAVITA=true
 BT_ROLE=api
-BT_AUTH_MODE=disabled
-BT_ALLOW_INSECURE_AUTH=true
+# Production auth: token mode with an explicit secret. For local development
+# only you may use BT_AUTH_MODE=disabled with BT_ALLOW_INSECURE_AUTH=true;
+# never expose a disabled-auth hub beyond localhost.
+BT_AUTH_MODE=token
+BT_API_TOKEN=change-me-to-a-long-random-secret
 
 # --- Unified Ports ---
 PORT=8390
@@ -21,8 +24,10 @@ BT_LOCAL_URL=http://192.168.0.122:8082/v1/chat/completions
 LLM_MODEL=groq/openai/gpt-oss-120b
 
 # --- High-Throughput Batching Economics ---
-# Sweet spot empirically tested for 0% segment loss and < 2s latency
-BT_BATCH_SIZE=20
+# Batch size and attempt budget must satisfy:
+#   ceil(BT_MAX_BATCH_PARAGRAPHS / BT_BATCH_SIZE) + BT_BATCH_SIZE + 1
+#     <= BT_REQUEST_MAX_ATTEMPTS (default 20). B=5/max=50 needs 16.
+BT_BATCH_SIZE=5
 BT_BATCH_SOURCE_TOKEN_BUDGET=1400
 BT_BATCH_MAX_TOKENS=3500
 BT_TIMEOUT=90

CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Reject impossible batch/attempt configurations at startup: require
+  `ceil(BT_MAX_BATCH_PARAGRAPHS / BT_BATCH_SIZE) <= BT_REQUEST_MAX_ATTEMPTS`
+  so a max-size request can execute in the attempt budget.
+- Bound batch dispatch to a `max_concurrent` replenishment window instead of
+  submitting every group upfront, cutting parked-thread pressure on the
+  upstream semaphore under concurrent API requests.
+- Run cache retention (expiry + cap scan) on a write watermark instead of on
+  every `put_many`, reducing SQLite WAL writer serialization on fresh batches.
+- Harden `.env.hub.example` to token auth and a budget-consistent batch size.
+- Make the reader prefetch toggle honest (enable rediscovers, disable drops
+  queued background work), discard stale in-flight batch responses on
+  page/language/mode change, add a compact narrow-viewport bar layout, and
+  safeguard reader element extraction.
+
 ## [2.3.0] - 2026-09-03
 
 ### Added

cache.py

@@ -155,6 +155,8 @@ def __init__(
         self._pending_hits_total = 0
         self._pending_lock = threading.Lock()
         self._flush_lock = threading.Lock()
+        self._writes_since_prune = 0
+        self._prune_lock = threading.Lock()
         self._init_lock = threading.Lock()
         self._initialized = False
         self._prepare_directory()
@@ -558,8 +560,20 @@ def put_many(
                        last_accessed_at = excluded.last_accessed_at""",
                 rows,
             )
-            self._delete_expired(conn)
-            self._enforce_cap(conn)
+            # Retention (expiry + cap ORDER BY/OFFSET scan) runs on a
+            # watermark, not on every write: the scan serializes the WAL
+            # writer and adds p95 on every fresh batch once near capacity.
+            # The watermark scales down for tiny test caps so cap behavior
+            # stays observable in unit tests.
+            with self._prune_lock:
+                self._writes_since_prune += len(rows)
+                threshold = min(1000, self.max_entries)
+                due = self._writes_since_prune >= threshold
+                if due:
+                    self._writes_since_prune = 0
+            if due:
+                self._delete_expired(conn)
+                self._enforce_cap(conn)
             conn.commit()
         except Exception:
             conn.rollback()

server.py

@@ -35,6 +35,7 @@
     single_cache_contract, singleflight_stats, BatchRecoveryTracker,
     RECOVERY_METRIC_NAMES,
     estimate_source_tokens, provider_call_stats, BT_BATCH_SIZE,
+    BT_REQUEST_MAX_ATTEMPTS,
     _reset_provider_call_stats_for_tests,
     provider_policy,
     initialize_provider_configuration,
@@ -133,6 +134,14 @@ def _cache_lookup(
     raise ValueError(
         "BT_BATCH_SIZE must not exceed BT_MAX_BATCH_PARAGRAPHS"
     )
+# A max-size request must be executable within the attempt budget even
+# in the clean path with no retries.
+_min_attempts = -(-BT_MAX_BATCH_PARAGRAPHS // BT_BATCH_SIZE)
+if BT_REQUEST_MAX_ATTEMPTS < _min_attempts:
+    raise ValueError(
+        "BT_REQUEST_MAX_ATTEMPTS too small for BT_MAX_BATCH_PARAGRAPHS / "
+        f"BT_BATCH_SIZE: need at least {_min_attempts} attempts"
+    )
 BT_MAX_PARAGRAPH_CHARS = int(os.environ.get("BT_MAX_PARAGRAPH_CHARS", "8000"))
 BT_CACHE_SCOPE_MAX_CHARS = int(os.environ.get("BT_CACHE_SCOPE_MAX_CHARS", "512"))
 

static/translator.css

@@ -66,6 +66,8 @@
     transform: translateX(-50%);
     height: auto;
     max-height: 48px;
+    max-width: calc(100vw - 20px);
+    touch-action: none;
     z-index: 2147483000;
     display: flex;
     align-items: center;
@@ -314,3 +316,11 @@ button.bt-menu-item:focus-visible { outline: 2px solid var(--bt-bilingual); }
 #bt-toast.bt-toast-visible { opacity: 1; transform: translateX(-50%) translateY(0); }
 
 @media print { #bt-bar, #bt-toast { display: none !important; } }
+
+/* ── Compact layout for narrow viewports ──────────────────────────── */
+@media (max-width: 420px) {
+    #bt-bar { gap: 4px; padding: 5px 6px; font-size: 12px; }
+    #bt-status { width: 64px; }
+    #bt-toggle-label { max-width: 64px; overflow: hidden; text-overflow: ellipsis; }
+    #bt-lang { max-width: 96px; }
+}

static/translator.js

@@ -799,7 +799,12 @@
                     prefetchEnabled = !prefetchEnabled;
                     localStorage.setItem('bt_prefetch', prefetchEnabled ? '1' : '0');
                     buildMenu();
-                    if (prefetchEnabled && translationMode !== 'off') triggerPrefetch();
+                    if (!prefetchEnabled) {
+                        prefetchQueue = [];
+                        refreshStatus();
+                    } else if (translationMode !== 'off') {
+                        scheduleTranslate('prefetch_enabled', { immediate: true, forceRediscover: true });
+                    }
                 } else if (action === 'cloud-fallback') {
                     allowCloudFallback = !allowCloudFallback;
                     buildMenu();
@@ -1425,6 +1430,7 @@
                     return true;
                 });
                 prefetchQueue = prefetchQueue.filter(x => {
+                    if (!prefetchEnabled) return false;
                     if (x.gen !== generation || translatedParagraphs[x.hash] || seenHash.has(x.hash)) return false;
                     seenHash.add(x.hash);
                     return true;
@@ -1502,6 +1508,15 @@
 
                 inflightCount = 0;
 
+                // Stale-response guard: page/language/mode may have changed
+                // while the request was in flight. Never let an old batch
+                // pollute cache, counters, or DOM.
+                if ((batch.length ? batch[0].gen : generation) !== generation
+                        || translationMode === 'off' || !readerRouteActive) {
+                    refreshStatus();
+                    continue;
+                }
+
                 if (data && data.error === 'aborted') {
                     // Deliberate cancel (mode/language/page change) — the items
                     // belong to a stale generation and get filtered next pass.

tests/python/test_provider_budget.py

@@ -1323,6 +1323,31 @@ def test_api_startup_rejects_browser_batch_above_request_limit(self):
             result.stderr,
         )
 
+    def test_api_startup_rejects_attempt_budget_below_worst_case(self):
+        env = os.environ.copy()
+        env.update({
+            "BT_AUTH_MODE": "disabled",
+            "BT_ALLOW_INSECURE_AUTH": "true",
+            "BT_BATCH_SIZE": "2",
+            "BT_MAX_BATCH_PARAGRAPHS": "50",
+            "BT_REQUEST_MAX_ATTEMPTS": "20",
+        })
+
+        result = subprocess.run(
+            [sys.executable, "-c", "import server"],
+            cwd=ROOT,
+            env=env,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn(
+            "BT_REQUEST_MAX_ATTEMPTS too small",
+            result.stderr,
+        )
+
     def test_recommended_compose_pins_safe_budget_defaults(self):
         compose = (ROOT / "docker-compose.yml").read_text()
         expected = {

translator.py

@@ -24,7 +24,7 @@
 import time
 import logging
 import requests
-from concurrent.futures import ThreadPoolExecutor, as_completed
+from concurrent.futures import ThreadPoolExecutor, as_completed, wait, FIRST_COMPLETED
 from dataclasses import dataclass
 from requests.adapters import HTTPAdapter
 from typing import Callable, Literal, Optional
@@ -2114,31 +2114,41 @@ def _do_group(idxs):
         return idxs, translations
 
     executor = ThreadPoolExecutor(max_workers=max_concurrent)
-    futures = [executor.submit(_do_group, g) for g in groups]
+    pending = list(groups)
+    futures = {}
     try:
-        for future in as_completed(futures):
-            try:
-                idxs, translations = future.result()
-            except WorkBudgetExceeded as exc:
-                if exc.reason == "cancelled":
-                    with fatal_lock:
-                        protocol_error = fatal_protocol_error[0]
-                    if protocol_error is not None:
-                        raise protocol_error
-                raise
-            for j, idx in enumerate(idxs):
-                # Each entry carries the provider that ACTUALLY served it
-                # (the fallback provider when the primary failed).
-                results[idx] = (
-                    translations[j]
-                    if j < len(translations)
-                    else BatchTranslationItem(
-                        "[TRANSLATION ERROR: missing segment]",
-                        "",
-                        False,
-                        "failed",
+        # Bounded window: never hold more than max_concurrent futures at once.
+        # Previously every group was submitted upfront, so 8 concurrent API
+        # requests could park dozens of threads on the 2s upstream semaphore.
+        while pending or futures:
+            while pending and len(futures) < max_concurrent:
+                g = pending.pop(0)
+                futures[executor.submit(_do_group, g)] = g
+            done, _ = wait(list(futures), return_when=FIRST_COMPLETED)
+            for future in done:
+                idxs = futures.pop(future)
+                try:
+                    idxs, translations = future.result()
+                except WorkBudgetExceeded as exc:
+                    if exc.reason == "cancelled":
+                        with fatal_lock:
+                            protocol_error = fatal_protocol_error[0]
+                        if protocol_error is not None:
+                            raise protocol_error
+                    raise
+                for j, idx in enumerate(idxs):
+                    # Each entry carries the provider that ACTUALLY served it
+                    # (the fallback provider when the primary failed).
+                    results[idx] = (
+                        translations[j]
+                        if j < len(translations)
+                        else BatchTranslationItem(
+                            "[TRANSLATION ERROR: missing segment]",
+                            "",
+                            False,
+                            "failed",
+                        )
                     )
-                )
     except (SegmentProtocolError, WorkBudgetExceeded):
         for future in futures:
             future.cancel()