# Portabilität: UNIVERSAL
# Version: 1.0.0
# Zuletzt validiert: 2026-05-17
# Nächste Prüfung: 2026-11-17

CONNECTOR - Externe Kommunikationsverbindungen
===============================================

BESCHREIBUNG
Verwaltet externe Kommunikationsverbindungen (Telegram, Discord,
HomeAssistant, etc.) und führt sie aus. Unterstützt automatisches
Polling, Queue-Versand mit Retry/Backoff und Circuit Breaker.

UNTERSTÜTZTE TYPEN
-------------------
  telegram        Telegram Bot API (getUpdates Polling)
  discord         Discord Bot (REST API)
  homeassistant   Home Assistant (REST API)
  webhook         Eingehende Webhooks (Push-basiert)
  signal          Signal Messenger (geplant, signal-cli)
  whatsapp        WhatsApp (geplant, Baileys)

Runtime-Adapter verfügbar: telegram, discord, homeassistant

CLI-BEFEHLE
-----------

Verwaltung:
  bach connector list                    Alle Connectors anzeigen
  bach connector status                  Status + Statistiken
  bach connector add <type> <name> [url] Neuen Connector registrieren
  bach connector remove <name>           Connector entfernen
  bach connector enable <name>           Aktivieren
  bach connector disable <name>          Deaktivieren

Nachrichten:
  bach connector messages [name]         Nachrichten anzeigen
  bach connector unprocessed             Unverarbeitete Nachrichten
  bach connector route                   Nachrichten routen (inbox)
  bach connector send <name> <to> <text> In ausgehende Queue einreihen

Runtime:
  bach connector poll <name>             Einmal pollen (Nachrichten holen + speichern)
  bach connector dispatch <name>         Ausgehende Queue versenden

Queue-Management:
  bach connector setup-daemon            Daemon-Jobs registrieren (einmalig)
  bach connector queue-status            Queue-Statistiken (pending/failed/dead)
  bach connector retry <id|all>          Dead-Letter zurücksetzen

ZUVERLAESSIGE ZUSTELLUNG (v2.0)
-------------------------------
Das Message-System arbeitet mit dem Daemon zusammen für
automatische Zustellung auch ohne aktive CLI-Session.

Einrichtung:
  1. bach connector setup-daemon       # Einmalig: 2 Daemon-Jobs anlegen
  2. bach daemon start --bg            # Daemon im Hintergrund starten

Ab jetzt automatisch:
  - Telegram/Discord alle 1-2 Min gepollt
  - Eingehende Nachrichten in Inbox (mit Kontext-Hints)
  - Ausgehende Queue jede Minute abgearbeitet
  - Fehlgeschlagene Sends bis 5x mit Backoff wiederholt

Daemon-Jobs:
  connector_poll_and_route   (2 Min Intervall) Pollt und routet
  connector_dispatch         (1 Min Intervall) Versendet Queue

RETRY UND BACKOFF
-----------------
Fehlgeschlagene Nachrichten werden mit exponentiellem Backoff
wiederholt: 30s, 60s, 120s, 240s, 480s (~15 Minuten gesamt).

Nach 5 Fehlversuchen (konfigurierbar) wird die Nachricht als
"Dead Letter" markiert. Dead Letters können manuell
zurückgesetzt werden:

  bach connector retry all             Alle Dead Letters zurücksetzen
  bach connector retry 42              Einzelne Nachricht zurücksetzen

CIRCUIT BREAKER
---------------
Nach 5 aufeinanderfolgenden Fehlern wird ein Connector für
5 Minuten gesperrt (disabled_until). Weitere Sende-/Poll-Versuche
werden übersprungen bis der Cooldown abgelaufen ist. Danach
wird der Zaehler automatisch zurückgesetzt.

KONTEXT-INTEGRATION
-------------------
Eingehende Nachrichten werden beim Routing durch zwei
Trigger-Systeme gefiltert (Assoziatives Gedaechtnis):

  a) ContextInjector (hardcoded, ~100 Trigger)
     → injector_hint in messages.metadata

  b) context_triggers Tabelle (dynamisch, 900+ Trigger)
     → context_triggers in messages.metadata

Ergebnis in messages.metadata (JSON):
  {
    "source": "telegram:123456",
    "injector_hint": "[KONTEXT] Backup: bach backup create ...",
    "context_triggers": ["backup", "sicherung"],
    "routed_at": "2026-02-08T22:00:00"
  }

REST-API
--------
Verfügbar wenn Headless API läuft (Port 8001):

  POST /api/v1/messages/send      Nachricht in Queue einreihen
  GET  /api/v1/messages/queue     Queue-Status (pending/failed/dead)
  GET  /api/v1/messages/inbox     Inbox lesen (Paginierung, Filter)
  POST /api/v1/messages/route     Routing manuell auslösen

Beispiele:
  curl localhost:8001/api/v1/messages/queue
  curl -X POST localhost:8001/api/v1/messages/send \
    -H "Content-Type: application/json" \
    -d '{"connector":"telegram_main","recipient":"123","content":"Hallo"}'

POLL-INTERVALLE (Default)
-------------------------
  Typ              Intervall   Rationale
  telegram         60s         getUpdates ist guenstig
  discord          120s        REST-Polling, Rate-Limits
  homeassistant    300s        Events, weniger dringend
  webhook          N/A         Push-basiert, kein Polling

Überschreibbar per auth_config JSON: {"poll_interval": 30}

DATENBANK
---------
Tabellen:
  connections         Connector-Konfiguration + Circuit-Breaker-Status
  connector_messages  Nachrichten-Queue (ein-/ausgehend, Retry-Tracking)
  messages            Inbox/Outbox (geroutete Nachrichten)
  scheduler_jobs         Automatische Poll/Dispatch-Jobs

Relevante Spalten connector_messages:
  status          TEXT (pending/sent/failed/dead)
  retry_count     INTEGER (aktuelle Versuchsnummer)
  max_retries     INTEGER (Default 5)
  next_retry_at   TEXT (nächster Retry-Zeitpunkt)

Relevante Spalten connections:
  consecutive_failures  INTEGER (Circuit-Breaker-Zaehler)
  disabled_until        TEXT (Sperre bis Timestamp)

DATEIEN
-------
  hub/connector.py                           CLI-Handler
  hub/_services/connector/queue_processor.py Queue-Processor (Kern)
  gui/api/messages_api.py                    REST-API Router
  connectors/base.py                 Abstrakte Basisklasse
  connectors/telegram_connector.py   Telegram-Adapter
  connectors/discord_connector.py    Discord-Adapter
  connectors/homeassistant_connector.py  HA-Adapter
  db/migrations/001_connector_queue_upgrade.sql  Schema-Migration

SIEHE AUCH
----------
  bach --help messages        Internes Nachrichtensystem
  bach --help daemon          Hintergrund-Jobs
  bach --help injectors       Kontext-Injektoren
