From f90d5efdaead62726aaede39c65d67e7a80eff36 Mon Sep 17 00:00:00 2001 From: Gabriel Radureau Date: Sat, 9 May 2026 14:29:40 +0200 Subject: [PATCH] =?UTF-8?q?docs(HOWTO):=20add=20Cas=202.5=20=E2=80=94=20ht?= =?UTF-8?q?tp=20forward=20handler=20(Phase=202a=20livr=C3=A9e)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- HOWTO_ADD_BOT.md | 72 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 59 insertions(+), 13 deletions(-) diff --git a/HOWTO_ADD_BOT.md b/HOWTO_ADD_BOT.md index f3eebcc..dd1bf44 100644 --- a/HOWTO_ADD_BOT.md +++ b/HOWTO_ADD_BOT.md @@ -98,19 +98,65 @@ Steps (humain ou session Claude avec accès au cluster + au repo) : - Si `requireAuth` est laissé à true : envoie un message → réponse `🔒 /auth chez @arcodange_factory_bot` ; fais `/auth ` chez factory ; renvoie un message → echo en < 2 s. - Si `requireAuth: false` : echo direct en < 2 s. -**Limite Phase 1** : tous les bots ont le handler `echo` ou `auth`. Pas encore de routage vers une logique métier différente par bot — voir Cas 3. +**Limite handler `echo`** : tous les bots `echo` répondent toujours pareil. Pour de la logique métier, voir Cas 2.5 (HTTP forward) ou Cas 3 (agent async). --- -## Cas 3 — Bot interactif piloté par un agent (Phase 3, pas encore livré) +## Cas 2.5 — Bot piloté par un service interne via HTTP forward (Phase 2a, livré) -Cible : utilisateur DM le bot → gateway déclenche un wrapper shell (ex. `claude --print`, `mistral-vibe`, ou un script Python qui appelle Ollama) → la réponse est renvoyée via Telegram. +Cible : un service du cluster (par ex. `webapp`, ou un mini-service Go/Python dédié) reçoit l'`Update` Telegram complet en POST JSON, traite sa logique, renvoie `{"text": ""}`. Le gateway envoie `text` au user. -Pour l'instant **non supporté** côté gateway. Phases requises : -- Phase 2 (queue Postgres + handler `http`) → permet à un service in-cluster d'être le handler -- Phase 3 (handlers async `shell` / `script` / `ollama` + retry pour Macbook endormi) +Sync : le webhook ack attend la réponse (timeout par défaut 5 s, plafond 30 s — Telegram coupe vers 60 s). Pour des backends lents, voir Cas 3. -Quand Phase 3 sera up, le ajout d'un tel bot sera : steps Cas 2 + handler `shell`/`script`/`ollama` au lieu d'`echo`, plus la commande/script à exécuter. +Setup côté gateway (suit Cas 2 pour le bot Telegram + le Secret) puis : + +1. **Déclarer le bot avec `handler: http`** dans `chart/values.yaml` : + + ```yaml + bots: + webappbot: + handler: http + http: + url: http://webapp.webapp.svc.cluster.local:8080/telegram/update + timeout: 5s + # requireAuth: true (implicite — défaut sécurisé) + ``` + +2. **Côté service interne**, exposer un endpoint qui : + - Accepte `POST ` avec un body = JSON Telegram `Update` (champs : `update_id`, `message.text`, `message.from.id`, `message.chat.id`, etc.) + - Lit le header `X-Bot-Slug: ` pour distinguer plusieurs bots qui forwarderaient au même service + - Renvoie `200 {"text": "réponse au user"}` (ou `200` body vide si pas de réponse à envoyer) + - Respecte le timeout configuré (le gateway coupe à `timeout`) + +3. **Push values.yaml + rollout** comme dans Cas 2. + +Exemple minimal de upstream service (Go) : + +```go +http.HandleFunc("/telegram/update", func(w http.ResponseWriter, r *http.Request) { + var u struct { + Message struct { + Text string `json:"text"` + From struct{ ID int64 `json:"id"` } `json:"from"` + } `json:"message"` + } + json.NewDecoder(r.Body).Decode(&u) + reply := fmt.Sprintf("hello user %d, you said: %s", u.Message.From.ID, u.Message.Text) + json.NewEncoder(w).Encode(map[string]string{"text": reply}) +}) +``` + +--- + +## Cas 3 — Bot interactif piloté par un agent async (Phase 3, pas encore livré) + +Cible : utilisateur DM le bot → gateway enqueue le job → worker async exécute un wrapper shell (ex. `claude --print`, `mistral-vibe`, ou un script Python qui appelle Ollama) → la réponse est renvoyée via Telegram, **même si le backend (Macbook Ollama) dort au moment du DM** (retry exponentiel jusqu'à 1 h). + +Pour l'instant **non supporté**. Requiert : +- Phase 2b (queue Postgres + worker — fondation async) +- Phase 3 (handlers `shell` / `script` / `ollama` + WoL Macbook optionnel) + +Quand Phase 3 sera up, l'ajout d'un tel bot sera : steps Cas 2 + handler `shell`/`script`/`ollama` au lieu d'`echo`, plus la commande/script à exécuter. Plan complet : `~/.claude/plans/pour-les-notifications-on-inherited-seal.md`. @@ -118,9 +164,9 @@ Plan complet : `~/.claude/plans/pour-les-notifications-on-inherited-seal.md`. ## Récap : quel cas choisir ? -| Besoin | Cas | Gateway impliqué ? | -|---|---|---| -| Notifs sortantes one-way (Cowork → user) | Cas 1 | non, Bot API directe | -| Bot qui répond toujours pareil (echo, ack, ping) | Cas 2 | oui (Phase 1) | -| Bot conversationnel piloté par agent (Claude / Mistral / Ollama / script) | Cas 3 | oui (Phase 3, futur) | -| Bot qui forwarde au backend d'une app cluster (webapp, etc.) | Cas 3 | oui (Phase 2, futur) | +| Besoin | Cas | État | Gateway impliqué ? | +|---|---|---|---| +| Notifs sortantes one-way (Cowork → user) | Cas 1 | livré | non, Bot API directe | +| Bot qui répond toujours pareil (echo, ack, ping) | Cas 2 | livré (Phase 1) | oui | +| Bot piloté par un service interne du cluster (webapp, mini-service custom) | Cas 2.5 | **livré (Phase 2a)** | oui | +| Bot conversationnel piloté par agent async (Claude / Mistral / Ollama / script, retry si backend dort) | Cas 3 | futur (Phase 3) | oui |