CLI und cURL

Der Befehl honk-me sendet aus Shell-Skripten, Cronjobs und CI, mit denselben Retries und derselben Idempotenz wie die Bibliotheken. Oder du sparst dir die Installation und nimmst eine einzige cURL-Anfrage.

Paket: github.com/honk-me/honk-go Veröffentlicht
Quellcode: github.com/honk-me/honk-go · MIT-Lizenz
Voraussetzungen: Linux, macOS oder Windows (amd64 oder arm64). Go 1.22+, wenn du sie selbst bauen willst.

Installation

Die CLI ist Teil des Go-Moduls.

Terminal

go install github.com/honk-me/honk-go/cmd/honk-me@latest
# or download a prebuilt binary (Linux, macOS, Windows; amd64 and arm64):
# https://github.com/honk-me/honk-go/releases

Mit einem Ingest-Schlüssel (honk_…) kann jeder an sein Projekt senden. Er gehört auf Server, in Jobs und in CI-Secrets, nie in einen Browser, eine Mobil- oder Desktop-App.

Ein Ereignis senden

Sie liest HONK_URL und HONK_KEY aus der Umgebung. Der Schlüssel ist nie ein Flag und landet so nie in deinem Shell-Verlauf oder in der Prozessliste.

Terminal

export HONK_URL=https://honk-me.app HONK_KEY=honk_…   # better: your secret store

honk-me beep "Backup finished" "nightly pg_dump took 42 s"
honk-me loud "Disk 91%" --group-key "disk/$(hostname)/var"

Befehle

Die Kurzformen light, beep, loud, long und blast legen die Stufe fest und erwarten den Text als Argument. send, problem und recovery arbeiten mit Flags. honk-me send -h listet sie alle auf.

Terminal

honk-me loud "Disk 91%"                                   # shortcut: light, beep, loud, long, blast
honk-me beep "Backup finished" "nightly pg_dump took 42 s" # [TITLE] MESSAGE, flags anywhere
honk-me send --title "Disk almost full" --message "/var at 91%" --severity loud \
  --group-key "disk/$(hostname)/var" --source "$(hostname)" --meta host="$(hostname)" --meta used:=91
honk-me problem  --group-key db/backup --title "Backup failed" --message "pg_dump exited with 1"
honk-me recovery --group-key db/backup --title "Backup OK"     --message "pg_dump finished"
tail -c 8000 /var/log/backup.log | honk-me send --title "Backup log" --message -   # message from stdin
honk-me send --message "Front door" --image-url https://cam.example.com/snap.jpg --priority high
honk-me light "New request from Emily" "Wants a quote for an online shop" \
  --action "Reply by email=mailto:[email protected]" --action "Call=tel:+12025550147"   # buttons, up to 3

Im Cronjob: nur bei Fehlern melden

Sende eine Entwarnung nur, wenn wirklich etwas kaputt war. Auch ohne offenes Problem eröffnet eine Entwarnung eine Episode mit dem Status „Behoben“ und benachrichtigt dich. Eine Entwarnung nach jedem erfolgreichen Lauf ließe dein Handy also jede Nacht vibrieren.

crontab

0 3 * * * pg_dump app > /backup/app.sql || honk-me problem --group-key db/backup --source "$(hostname)" --title "Backup failed" --message "pg_dump exited with $?"

In der CI

Ein Idempotency-Key pro Lauf und Versuch, damit die eigenen Retries der CLI nie doppelt senden, und || true, damit eine fehlgeschlagene Mitteilung nie den Build scheitern lässt.

.github/workflows/…

- name: Notify
  if: failure()
  env:
    HONK_URL: ${{ secrets.HONK_URL }}
    HONK_KEY: ${{ secrets.HONK_KEY }}
  run: |
    honk-me problem --group-key "ci/${{ github.repository }}/${{ github.ref_name }}" \
      --title "CI failed: ${{ github.workflow }}" --message "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
      --source github-actions --category deployments \
      --idempotency-key "gh-${{ github.run_id }}-${{ github.run_attempt }}" || true

Exit-Codes

Häng || true an, wo eine fehlgeschlagene Mitteilung das Skript nicht scheitern lassen darf.

0	Angenommen, oder ein Duplikat eines angenommenen Ereignisses
1	Unerwartete Antwort: eine falsche `HONK_URL`, eine Weiterleitung, eine fehlerhafte Antwort
2	Falscher Aufruf, oder `HONK_URL` oder `HONK_KEY` fehlt
3	Ungültige Nachricht: Korrigiere die Flags
4	Authentifizierung: ungültiger oder widerrufener Schlüssel, „dringend“ nicht erlaubt, gesperrtes Projekt
5	Kontingent oder Ratenlimit (`429`); stderr zeigt `Retry-After`
6	Idempotenzkonflikt (`409`): gleicher Schlüssel, andere Daten
7	Vorübergehender Fehler nach allen Retries: mit demselben `--idempotency-key` erneut ausführen

Mit cURL

Ganz ohne Installation. Füge einen Idempotency-Key hinzu, damit die eigenen Retries von cURL keine Duplikate erzeugen.

Terminal

curl -sS https://honk-me.app/v1/messages \
  -H "Authorization: Bearer $HONK_KEY" \
  -H "Idempotency-Key: backup-$(date +%Y%m%d)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Backup failed",
    "message": "pg_dump exited with 1",
    "severity": "long",
    "group_key": "db/backup",
    "event_type": "problem"
  }'
# → 202 {"id":"msg_…","status":"accepted","duplicate":false,"received_at":"…"}

Terminal

curl --fail-with-body -sS --max-time 10 --retry 3 --retry-all-errors \
  -X POST "$HONK_URL/v1/messages" \
  -H "Authorization: Bearer $HONK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: request-42" \
  -d '{"title":"New request from Ana Pop","message":"Wants a quote for an online shop, budget €4,000.","severity":"light","priority":"high","category":"customers","group_key":"requests/42"}'

Retries ohne Doppelversand

Jedes Senden hat einen Idempotency-Key: deinen oder eine neue UUIDv7. Jeder Retry nutzt denselben Schlüssel, und innerhalb von 24 Stunden beantwortet Honk eine erneut gesendete Anfrage mit der ursprünglichen ID und duplicate: true. Geht eine Antwort verloren, entsteht also nie eine zweite Nachricht.
Wiederholt werden nur Netzwerkfehler, Timeouts, 429 und 5xx, mit exponentiellem Backoff und vollem Jitter, nie früher als das Retry-After des Servers. Andere 4xx-Antworten werden nie wiederholt: Korrigiere stattdessen die Anfrage.
Jeder Versuch bricht nach 5 Sekunden ab, und nach insgesamt 30 Sekunden ist Schluss. Wäre die nötige Wartezeit länger, etwa bis ein Tageskontingent um Mitternacht zurückgesetzt wird, schlägt der Aufruf sofort fehl und sagt dir, wann du es erneut versuchen kannst.
Felder werden vor dem Senden geprüft, und alle ungültigen Felder werden auf einmal gemeldet.