CLI et cURL

La commande honk-me envoie depuis les scripts shell, les tâches cron et la CI, avec les mêmes nouvelles tentatives et la même idempotence que les bibliothèques. Ou passez l’installation et utilisez une seule requête cURL.

Paquet: github.com/honk-me/honk-go Publié
Code source: github.com/honk-me/honk-go · Licence MIT
Prérequis: Linux, macOS ou Windows (amd64 ou arm64). Go 1.22+ pour la compiler vous-même.

Installation

La CLI fait partie du module Go.

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

Une clé d’ingestion (honk_…) permet à quiconque la détient d’envoyer des messages dans son projet. Gardez-la sur vos serveurs, dans vos tâches et dans les secrets de votre CI, jamais dans un navigateur ni dans une app mobile ou de bureau.

Envoyer un événement

Elle lit HONK_URL et HONK_KEY dans l’environnement ; la clé n’est jamais passée en option, elle n’apparaît donc ni dans l’historique de votre shell ni dans la liste des processus.

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"

Commandes

Les raccourcis light, beep, loud, long et blast fixent le niveau et prennent le texte en arguments. send, problem et recovery prennent des options. honk-me send -h les liste toutes.

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

Dans cron : alerter seulement en cas d’échec

N’envoyez un rétablissement que si quelque chose était vraiment en panne. Un rétablissement sans problème en cours crée quand même un épisode « rétabli » et vous notifie : envoyé après chaque exécution réussie, il ferait vibrer votre téléphone toutes les nuits.

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 $?"

Dans la CI

Une clé d’idempotence par tentative d’exécution, pour que les nouvelles tentatives de la CLI ne créent jamais de doublon, et || true pour qu’une notification ne puisse jamais faire échouer le build.

.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

Codes de sortie

Ajoutez || true là où l’échec d’une notification ne doit pas faire échouer le script.

0	Accepté, ou doublon d’un événement accepté
1	Réponse inattendue : `HONK_URL` incorrecte, redirection, réponse mal formée
2	Erreur d’utilisation, ou `HONK_URL` ou `HONK_KEY` manquante
3	Message invalide : corrigez les options
4	Authentification : clé invalide ou révoquée, priorité urgente non autorisée, projet suspendu
5	Quota ou limite de débit (`429`) ; stderr affiche `Retry-After`
6	Conflit d’idempotence (`409`) : même clé, contenu différent
7	Échec temporaire après les nouvelles tentatives : relancez avec la même `--idempotency-key`

Avec cURL

Aucune installation. Ajoutez une Idempotency-Key pour que les nouvelles tentatives de cURL ne puissent pas créer de doublons.

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"}'

Des nouvelles tentatives sans doublon

Chaque envoi porte une Idempotency-Key : la vôtre, ou un UUIDv7 généré pour l’occasion. La même clé est réutilisée à chaque nouvelle tentative, et pendant 24 heures Honk répond à une requête rejouée avec l’identifiant d’origine et duplicate: true : une réponse perdue ne crée jamais de second message.
Une nouvelle tentative n’a lieu qu’en cas d’erreur réseau, de délai dépassé, de 429 ou de 5xx, avec un backoff exponentiel et un jitter complet, jamais avant le Retry-After du serveur. Les autres réponses 4xx ne donnent lieu à aucune nouvelle tentative : corrigez plutôt la requête.
Chaque tentative expire au bout de 5 secondes, et tout s’arrête au bout de 30 secondes au total. Une attente qui dépasserait cette échéance, comme un quota quotidien remis à zéro à minuit, échoue immédiatement et indique quand réessayer.
Les champs sont vérifiés localement avant l’envoi, et tous les champs invalides sont signalés en une seule fois.