From 24ceff3f48a58bea9bc2bc12a16f51fb34509e1b Mon Sep 17 00:00:00 2001 From: m3ta-chiron Date: Sun, 18 Oct 2026 17:40:56 +0200 Subject: [PATCH] docs(readme): Rate-Limit, Ruhezeiten und now-Ausbruch dokumentieren MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Endpunkt-Tabelle (discarded-Feld, Gesetz-State in /status), neuer Abschnitt zu Semantik (wer wartet, wer verfällt, was now darf), Rangordnung mute > now > Ruhezeit > Rate-Limit, Config-/Env-Referenz und die status-Zeilen der CLI. --- README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 49 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 38f1087..5f478cc 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ mit der kompletten Provider-Kette und Daemon-Anbindung (non-blocking über `talkd`, siehe unten), `mute`, `unmute`, `status`, `cancel`. Die übrigen Befehle sind Stubs und melden `not implemented yet` (Exit-Code ≠ 0). -## Daemon talkd (Task 04) +## Daemon talkd (Task 04 + 05) `talkd` besitzt die Ansage-Queue und spricht seriell ab — genau eine Ansage gleichzeitig, Reihenfolge `now` > `high` > `normal` > `low` (FIFO je @@ -42,17 +42,17 @@ config `[server] port`, Env `TALK_PORT` (schlagen den Default). | Endpunkt | Wirkung | | --- | --- | -| `POST /speak` | `{text, priority?, provider?, voice?, lang?, now?}` → `202 {"id":"…"}`; bei Mute: `202 {"id":"","muted":true}` (Ansage verworfen — dokumentiertes Verhalten) | -| `GET /status` | `{"version", "queue", "queue_ids", "current", "muted", "provider"}` | +| `POST /speak` | `{text, priority?, provider?, voice?, lang?, now?}` → `202 {"id":"…"}`; bei Mute: `202 {"id":"","muted":true}`; bei Gesetz-Verwurf: `202 {"id":"","discarded":"rate_limit"\|"quiet_hours"}` (+ `"toast":true` im Toast-Modus) — verworfen, dokumentiertes Verhalten | +| `GET /status` | `{"version", "queue", "queue_ids", "current", "muted", "provider", "rate_limit": {"interval", "allow_high_burst", "next_slot"}, "quiet_hours": {"window", "active", "mode", "until"}}` | | `POST /cancel` | bricht die laufende Ansage ab + leert die Queue → `200 {"cancelled":n}` | | `POST /mute` / `POST /unmute` | persistenter Mute-State → `200 {"muted":bool}` | - **CLI-Verhalten:** `talk say` (und `talk "Text"`) erkennt den Daemon via `GET /status`. Läuft er: enqueue + sofortige Rückkehr (non-blocking, stdout erhält die Item-ID); `--wait` pollt bis zur Fertigstellung; - `--now` springt vor die Warteschlange; bei Mute sagt die CLI `muted`. - `talk mute`/`unmute`/`status`/`cancel` sind Daemon-Aufrufe mit plain - Output. + `--now` springt vor die Warteschlange; bei Mute sagt die CLI `muted`, + bei Gesetz-Verwurf `discarded: `. `talk mute`/`unmute`/`status`/ + `cancel` sind Daemon-Aufrufe mit plain Output. - **Mute ist persistent** (Datei `mute` im Config-Dir, Inhalt `true`/ `false`) und überlebt Daemon-Restarts. `talk mute` ohne laufenden Daemon schreibt die Datei direkt — der Daemon liest sie bei jeder Ansage neu, @@ -61,9 +61,49 @@ config `[server] port`, Env `TALK_PORT` (schlagen den Default). sequenziell weiter — serialisiert über die Lock-Datei `talk.lock` im Config-Dir (Kollision = warten; verwaisste Locks gelten nach 60 s als verfallen). Mute wird auch hier respektiert. Nichts bricht still. -- Rate-Limit und Ruhezeiten folgen in Task 05; die Rate-Limit-Struktur - existiert bereits (`internal/queue`), ist in diesem Stand aber bewusst - noch nicht angebunden (Default: unbegrenzt). + +### Rate-Limit + Ruhezeiten (Task 05) + +Der Daemon erzwingt das Anti-Spam-Gesetz als Backstop unter allem +Prompt-Verhalten. **Rate-Limit:** Jede *gestartete* Ansage bucht ein +Zeitfenster — Default **1 Ansage / 30 s**. Bis zum Fenster-Ablauf gilt: + +- `priority=low` wird **verworfen** (schon beim Eintritt, die 202-Antwort + nennt `discarded: "rate_limit"`); war das Fenster beim Eintritt noch + frei, entscheidet der Worker später. +- `normal` **parkt** in der Queue und spielt zum freien Slot (in `/status` + als `rate_limit.next_slot` sichtbar). +- `priority=high` darf mit `queue.allow_high_burst = true` (Default) + **bewusst verstoßen**; ohne Burst-Recht wartet high wie normal. +- `now:true` **umgeht auch das Rate-Limit** — der dokumentierte Ausbruch + für Dringendes (startet trotzdem ein neues Fenster). + +**Ruhezeiten:** `quiet_hours = "18:00-08:00"` (lokale Zeit, überspannt +Mitternacht; leer/`off` = aus — bewusst kein Default-Fenster, Ruhezeiten +sind Opt-in wie Mute). In der Ruhezeit verfällt Audio, auch für high +(Burst ist ein Rate-Recht, kein Ruhe-Recht): + +- `quiet_mode = "discard"` (Default): still verwerfen. +- `quiet_mode = "toast"`: Benachrichtigung statt Audio — derzeit eine + Protokoll-Zeile über den Notification-Pfad (OS-Toast folgt mit der + Notification-Anbindung). +- `now:true` **bricht auch die Ruhezeit** (bewusster Ausbruch). + +**Rangordnung:** manuelles Mute gewinnt immer > `now` > Ruhezeit > +Rate-Limit. Konfiguration (config.toml, Env schlägt Datei): + +```toml +[queue] +rate_limit = "30s" # Dauer; "0s" = unbegrenzt (TALK_RATE_LIMIT) +allow_high_burst = true # high darf verstoßen (TALK_ALLOW_HIGH_BURST) + +quiet_hours = "18:00-08:00" # leer = aus; Env TALK_QUIET_HOURS ("off" = aus) +quiet_mode = "discard" # discard | toast (TALK_QUIET_MODE) +``` + +`talk status` zeigt den Gesetz-State: `rate-limit: 30s (high-burst +erlaubt), nächster slot …` und `ruhezeit: 18:00-08:00 (modus discard, +aktiv bis 08:00)`. ### Provider-Kette (Task 03)