archivmail/features/PROJ-56-last-entzerrung-hintergrundjobs.md

PROJ-56: Last-Entzerrung für Hintergrundjobs (OCR, IMAP-Sync)

Status: Deployed

Created: 2026-06-22 Last Updated: 2026-06-22

Dependencies

• PROJ-35 (OCR & Anhang-Volltext-Indexierung)
• PROJ-8 (Automatischer IMAP-Sync)

Hintergrund (Nutzerwunsch)

Vergleich mit Mailpiler: dort laufen Wartungsprozesse zeitlich entzerrt statt komplett parallel. Bei archivmail laufen OCR-Worker (sofort bei Import, 2 parallel, je tesseract-Mehrthread) und IMAP-Sync (alle Postfächer pollen unabhängig, ohne Jitter, exakt zum Intervall-Ablauf) unkoordiniert nebeneinander, was bei begrenztem RAM (z.B. 4GB-LXC) zu Lastspitzen führt.

Manticore-Reindex wurde geprüft, ist aber bereits ein rein manuelles CLI-Kommando (kein Scheduler) — keine automatische Last-Entzerrung nötig/möglich, daher außerhalb des Scopes dieses Tickets.

Entscheidung (Nutzer, 2026-06-22)

Alle drei vorgeschlagenen Maßnahmen gewünscht, soweit technisch sinnvoll:

1. OCR zeitlich entzerren — konfigurierbares Zeitfenster, in dem OCR-Verarbeitung pausiert (z.B. Geschäftszeiten ausnehmen).
2. IMAP-Sync-Intervalle entzerren — deterministischer Jitter pro Postfach, damit nicht alle Accounts auf derselben Minutengrenze pollen.
3. Reindex in Nachtfenster — entfällt, da bereits manuell/CLI-only ohne automatischen Trigger.

Acceptance Criteria

• config.yml erlaubt ein optionales OCR-Zeitfenster (z.B. ocr.paused_hours: [8, 18] = pausiert 08:00–18:00 Uhr); ohne Konfiguration: Verhalten unverändert (sofortige Verarbeitung, wie bisher).
• Außerhalb des erlaubten Fensters werden neue OCR-Aufträge weiterhin in die Queue/DB als pending aufgenommen, aber nicht abgearbeitet, bis das Fenster sich öffnet (kein Datenverlust, kein Crash bei vollem Queue).
• IMAP-Scheduler verteilt den tatsächlichen Sync-Start jedes Accounts über einen deterministischen Jitter (abgeleitet aus Account-ID, kein Zufall bei jedem Tick) innerhalb eines konfigurierbaren Fensters (Default z.B. 0–4 Minuten), sodass bei N Accounts mit gleichem Intervall nicht alle zur gleichen Minute synchronisieren.
• Bestehende Funktionalität (Sync-Intervall pro Account, manuelles "Jetzt synchronisieren") bleibt unverändert nutzbar — Jitter gilt nur für den automatischen Scheduler-Trigger.
• Kein Verhalten ändert sich für Installationen ohne neue Config-Werte (Default = bisheriges Verhalten, kein Opt-in nötig für Jitter da inhärent sinnvoll, aber abschaltbar via jitter_seconds: 0).

Tech Design

Übersprungen (kleine, klar umrissene Performance-Änderung, kein architektonischer Schnitt nötig) — analog zum Vorgehen bei PROJ-55.

Implementation Notes (2026-06-22)

Geänderte/neue Dateien

• config/config.go: neue Sektionen OCRConfig (paused_hours *[2]int) und IMAPSchedulerConfig (jitter_seconds *int) in Config. Helper ResolvedJitterSeconds() + Konstante DefaultIMAPJitterSeconds = 240.
• internal/ocr/worker.go: Options.PausedHours, Worker-Feld pausedHours, isPaused(now), Pause-Gate im run-Loop.
• internal/imap/scheduler.go: Feld jitterSeconds, SetJitterSeconds(), jitterOffset(), Anpassung der Fälligkeitsbedingung (interval + jitterOffset(acc.ID)).
• cmd/archivmail/main.go: PausedHours an OCR-Worker durchgereicht; imapSched.SetJitterSeconds(cfg.IMAPScheduler.ResolvedJitterSeconds()).
• config/config.docker.yml.example: auskommentierte Beispielsektionen ocr und imap_scheduler.

OCR-Pausenmechanismus

Gewählt: Worker konsumiert die Queue gar nicht erst, solange das Pausenfenster aktiv ist. Vor jedem Dequeue prüft jeder Worker isPaused(time.Now()). Bei aktiver Pause wartet er per select (60s-Ticker via pauseCheckInterval, reagiert sofort auf done/ctx.Done()) und liest erst dann wieder aus dem Channel. Vorteile:

• Kein Datenverlust: Jobs bleiben im gepufferten Channel und v.a. als ocr_status='pending' in PostgreSQL.
• Kein Queue-Überlauf: Der Boot-Resume-Refill ist QueueLen-gesteuert und legt nichts nach, sobald der Channel voll ist; neue Submits werden wie bisher non-blocking verworfen (bleiben aber pending in der DB und werden beim nächsten Boot-Resume/Fensteröffnen nachgezogen).
• Kein Busy-Loop: Pollintervall 60s.
• cmd_ocr_reprocess.go setzt PausedHours bewusst nicht (nil) → manueller Admin-Befehl ignoriert das Fenster und läuft sofort.
• Wrap-around-Fenster (z.B. [22, 6]) werden in isPaused unterstützt (start>end → h>=start || h<end); start==end = No-op (nie pausieren).

IMAP-Jitter

Deterministischer Offset accountID % jitterSeconds Sekunden, nur aus der Account-ID abgeleitet (stabil über alle Ticks, kein rand()). Fälligkeit erst bei now.Sub(lastSync) >= interval + jitterOffset. Default 240s wenn imap_scheduler fehlt (jitter_seconds-Pointer = nil); explizit 0 deaktiviert. TriggerSync (manuell) bleibt unberührt.

Offene Risiken / Edge Cases

• Mitternachts-übergreifendes Fenster [22,6] ist abgedeckt; reine Stunden-Granularität (kein Minutenanteil) ist bewusst einfach gehalten.
• Server-Zeitzone: time.Now().Hour() nutzt lokale Serverzeit — bei UTC-Servern muss das Fenster entsprechend gesetzt werden.
• Jitter verlängert das effektive Intervall um bis zu jitter_seconds (max +4 Min bei Default); akzeptabel, da nur Spitzenglättung bezweckt ist.
• Lokal kein go build möglich (kein Toolchain) — nur statische Konsistenzprüfung erfolgt; Build-Verifikation auf 192.168.1.131.

QA Test Results (Code-Review + Build-Verifikation, 2026-06-22)

Getestet von: QA / Red-Team. Methode: statisches Code-Review der geänderten Dateien

• isolierte Build-Verifikation auf Test-Server 192.168.1.132 (Go 1.24.4), ohne den produktiven Checkout / Dienst zu berühren (Tarball → /tmp/archivmail-qa56 → go build → version-Smoke-Test + go vet → vollständige Bereinigung).

Build-Verifikation (192.168.1.132)

• CGO_ENABLED=0 go build -buildvcs=false -o /tmp/archivmail-test ./cmd/archivmail/ → EXIT 0 (20 MB Binary).
• Smoke-Test archivmail-test version → OK (archivmail 0.9.1, Modul-Liste wird ausgegeben).
• go vet ./config/... ./internal/ocr/... ./internal/imap/... ./cmd/archivmail/... → EXIT 0 (keine Befunde).
• Kein Eingriff in /opt/archivmail, kein systemctl restart. Temp-Artefakte auf 132 entfernt.

Acceptance Criteria

• [PASS] AC1 — Optionales OCR-Zeitfenster: OCRConfig.PausedHours *[2]int (yaml:"paused_hours,omitempty"). nil → isPaused() gibt false, Verhalten unverändert.
• [PASS] AC2 — Außerhalb des Fensters bleiben Jobs pending: Worker konsumiert die Queue im Pausenfenster nicht (run-Loop: bei isPaused nur select mit 60s-Ticker, kein Dequeue). Jobs bleiben im gepufferten Channel bzw. ocr_status='pending' in der DB; Boot-Resume zieht sie nach. Kein Datenverlust, kein Crash bei vollem Channel (Submit ist non-blocking; verworfene Submits bleiben pending in DB).
• [PASS] AC3 — Deterministischer IMAP-Jitter: jitterOffset(accountID) = (accountID % jitterSeconds) s, nur aus Account-ID abgeleitet, stabil über alle Ticks (kein rand()). Fälligkeit erst bei now.Sub(lastSync) >= interval + jitterOffset.
• [PASS] AC4 — Bestehende Funktionalität unverändert: TriggerSync (manuell) umgeht checkAccounts/Jitter vollständig und startet sofort (runSyncWithRetry direkt). Sync-Intervall pro Account bleibt Basis.
• [PASS] AC5 — Default ohne Config: OCR paused_hours unset → nie Pause. imap_scheduler ganz weggelassen → ResolvedJitterSeconds() = 240s Default; jitter_seconds: 0 → Jitter aus (Legacy-Tick exakt zum Intervall).

Prüfpunkte

1. Datenverlust bei Pause — PASS. Jobs werden nicht verworfen; Channel-Buffer + pending-Status + Boot-Resume garantieren Nachzug.
2. Race Conditions — PASS (in der aktuellen Verdrahtung). pausedHours wird nur im Konstruktor gesetzt, danach nur gelesen → keine Concurrent-Writes. jitterSeconds wird in main.go per SetJitterSeconds() vor imapSched.Start() gesetzt; der Loop liest erst nach Start(). Kein Daten-Rennen im realen Pfad. Hinweis (LOW, kein Bug): SetJitterSeconds/jitterOffset greifen unsynchronisiert auf s.jitterSeconds zu — würde ein künftiger Aufrufer Jitter zur Laufzeit ändern, wäre es ein Race. Aktuell nicht der Fall. go vet meldet nichts; ein -race-Test wurde nicht ausgeführt (kein Test-Harness im Scope).
3. Edge Cases — PASS.
   • Mitternachtsfenster [22,6]: start>end → h>=start || h<end, korrekt (pausiert 22–05).
   • start==end: explizit No-op (nie pausieren).
   • Fehlende Config / nil-Pointer: isPaused prüft pausedHours==nil; ResolvedJitterSeconds prüft JitterSeconds==nil. Keine nil-Derefs.
   • jitter_seconds: 0: jitterOffset gibt 0 → reines Intervall-Verhalten.
   • Negativ: SetJitterSeconds und ResolvedJitterSeconds klemmen <0 auf 0.
4. Backward-Compat — PASS (siehe AC5). Default-Pfad identisch zum Alt-Verhalten, mit einer bewussten Ausnahme: ohne imap_scheduler-Sektion ist nun 240s Jitter aktiv (laut Spec gewollt, „abschaltbar via jitter_seconds: 0"). Verlängert das effektive Sync-Intervall um bis zu 4 Min — dokumentiert in den Implementation Notes als akzeptiert.
5. cmd_ocr_reprocess.go erbt kein Pausenfenster — PASS. Der ocr.Options-Block dort setzt PausedHours nicht (= nil) → manuelle Reprocessing-Läufe ignorieren das Fenster und laufen sofort. Verifiziert (Zeilen 103–107).
6. Manuelles "Jetzt synchronisieren" ignoriert Jitter — PASS. TriggerSync ruft runSyncWithRetry direkt auf, ohne dueAfter/jitterOffset-Berechnung. Verifiziert.

Findings

• Keine Bugs (Severity Critical/High/Medium) gefunden.
• LOW / INFO 1 (kein Fix nötig): Scheduler.jitterSeconds ist nicht mutex-geschützt. Unkritisch, da set-before-start. Nur relevant, falls künftig eine Laufzeit-Rekonfiguration eingeführt wird → dann s.mu o.ä. ergänzen.
• LOW / INFO 2 (kein Fix nötig): Pausenfenster nutzt lokale Serverzeit (time.Now().Hour()). Auf UTC-Servern muss das Fenster entsprechend gewählt werden — bereits in den Implementation Notes dokumentiert.
• INFO 3 (vorbestehend, nicht Teil von PROJ-56): config.docker.yml.example enthält weiterhin xapian_path/backend: xapian, obwohl der StorageConfig kein xapian_path-Feld hat und der Default-Backend Manticore ist. Unkritisch (YAML-Unmarshal ignoriert unbekannte Keys), aber irreführend. Außerhalb des Scopes dieses Tickets.

Fazit

Production-Ready: JA. Alle 5 Acceptance Criteria erfüllt, alle 6 Sicherheits-/Korrektheits-Prüfpunkte bestanden, Build + vet + Smoke-Test auf 192.168.1.132 grün. Keine blockierenden Findings; nur 2 LOW-Hinweise (kein Fix nötig) und 1 vorbestehender, ticket-fremder Konfig-Hinweis.

Deployment

• Test (192.168.1.132): update.sh (Commit 4dbf27c), Backend+Frontend aktiv, Health-Checks bestanden, keine Config-Parsing-Fehler trotz fehlender OCRConfig/IMAPSchedulerConfig in der lokalen config.yml (Default-Verhalten bestätigt). 2026-06-22.
• Produktion (192.168.1.131): update.sh (Commit 12c4dc7), Backend+Frontend aktiv, Health-Checks bestanden, keine Config-Parsing-Fehler. 2026-06-22.