GitHub Webhooks: Event-Dispatcher

GitHub Webhooks: Event-Dispatcher

Dies ist Folgeartikel 3 aus meiner Serie zu GitHub-Webhooks.

Nachdem die Events in der Queue abgelegt worden sind, müssen sie dort weiterverarbeitet und an die eigentlichen Eventhandler übergeben werden. Darum geht es in diesem Artikel.

Ursprünglich habe ich das mit einem einzigen Skript erledigt, aber es hat sich gezeigt, dass es passender und flexibler ist, das in zwei Teile zu teilen.

Da die Skripte gar nicht respektive nicht tief im JSON rumhantieren müssen (das machen die eigentlichen Event-Handler), kann ich das in Shell lösen und brauche kein Perl.

Der Queue-Beobachter

  1. #!/bin/sh
  2.  
  3. BASE_DIR="$HOME/json"
  4. QUEUE_DIR="$BASE_DIR/queue"
  5. PROCESSING_DIR="$BASE_DIR/processing"
  6. PROCESSED_DIR="$BASE_DIR/done"
  7. ERROR_DIR="$BASE_DIR/error"
  8.  
  9. inotifywait -m -e create -e moved_to "$QUEUE_DIR" | while read -r INOTIFY; do
  10.  
  11.     for QUEUE_FILE in "$QUEUE_DIR"/*; do
  12.  
  13.         [ -e "$QUEUE_FILE" ] || break
  14.  
  15.         FILENAME="$(basename "${QUEUE_FILE}")"
  16.         PROCESSING_FILE="$PROCESSING_DIR/$FILENAME"
  17.         PROCESSED_FILE="$PROCESSED_DIR/$FILENAME"
  18.         ERRORED_FILE="$ERROR_DIR/$FILENAME"
  19.  
  20.         mv "$QUEUE_FILE" "$PROCESSING_FILE"
  21.         if  ./handler.sh "$PROCESSING_FILE"; then
  22.             mv "$PROCESSING_FILE" "$PROCESSED_FILE"
  23.         else
  24.             mv "$PROCESSING_FILE" "$ERRORED_FILE"
  25.             echo "ERROR during processing, see $ERRORED_FILE"
  26.         fi
  27.     done
  28.  
  29. done

Das Skript /home/webhook/watcher.sh macht nichts anderes, als das Queue-Verzeichnis $QUEUE_DIR zu überwachen und bei einer neuen JSON-Datei deren Verarbeitung anzustoßen. Dazu wird die Datei in das Verzeichnis $PROCESSING_DIR verschoben und das zweite Skript ./handler.sh mit dem Dateinamen als Parameter aufgerufen.

Erfolgreich verarbeitete Dateien werden dann nach $PROCESSED_DIR verschoben, fehlerhafte nach $ERROR_DIR. Im Fehlerfall gibt es einen kurzen Hinweis auf STDOUT, ansonsten ist das Skript ruhig.

Um das Verzeichnis $QUEUE_DIR effizient zu überwachen, arbeite ich mit inotifywait, einem Kommandozeilen-Tool für inotify (in Debian im Paket inotify-tools).

Race-Conditions

Ursprünglich sah das Warten auf Dateien in der Queue mal so aus:

  1. while inotifywait -m -e create -e moved_to "$QUEUE_DIR"; do
  2.     for QUEUE_FILE in "$QUEUE_DIR"/*; do
  3.         […]
  4.     done
  5. done

Das hat aber einen Haken: Wenn eine neue Datei eintrudelt, während die for-Schleife noch arbeitet, wird die neue Datei erst berücksichtigt, wenn inotifywait wieder dran ist und dann nochmal eine weitere neue Datei kommt. Da können also ein oder mehrere Events mal ganz lange liegenbleiben…

Im jetzigen Skript ist das genau andersherum: Wenn viele Dateien auf einmal eintrudeln, dann kann es sein, dass die for-Schleife bereits eine Datei verarbeitet, die inotifywait noch gar nicht gemeldet hat. Die Nachmeldung erfolgt dann im nächsten while-Durchlauf. Wenn die Datei schon verarbeitet wurde, sieht die for-Schleife nichts und ist halt schnell fertig. Da bleibt nichts mehr unverarbeitet liegen, es wird höchstens einmal unnötigerweise geguckt, was zu verarbeiten wäre.

Autostart

Dieses Skript muss dauerhaft laufen, daher habe ich dafür auch einen systemd-Service angelegt unter /etc/systemd/system/local-webhook-watcher.service:

  1. [Unit]
  2. Description=Github Webhook Watcher Service (JSON dispatcher)
  3.  
  4. [Service]
  5. Type=simple
  6. ExecStart=/home/webhook/watcher.sh
  7. StandardOutput=journal
  8. StandardError=journal
  9. User=webhook
  10. Group=webhook
  11. WorkingDirectory=~
  12. Nice=19
  13. IOSchedulingClass=idle
  14. ProtectSystem=full
  15. PrivateTmp=true
  16.  
  17. [Install]
  18. WantedBy=local-webhook-receiver.service

Das sieht fast genauso aus wie der Service für plackup.

Neu hinzugekommen sind Nice und IOSchedulingClass, die das Skript mit minimaler Priorität laufen lassen. Wenn der Webhook das Event erstmal empfangen und lokal in die Queue geschrieben hat, kann das Verarbeiten in der Queue gerne mal 5 Sekunden dauern, da geht ja nichts verloren. Also ist das Skript mal ganz brav und stellt sich hinten an, wenn gerade was anderes passiert (mein Server langweilt sich aber eh meist, das dürfte wenig Unterschied machen).

Aktivieren dann wie üblich:

  1. systemctl daemon-reload
  2. systemctl enable local-webhook-watcher.service
  3. systemctl start local-webhook-watcher.service

Autoreload

Ursprünglich hatte ich auch den Aufruf der Event-Handler ebenfalls in diesem Skript und während des Rumprogrammierens musste ich den systemd-Service ständig neu starten. Dafür musste ich jedes Mal root werden, um systemctl restart local-webhook-watcher.service aufzurufen, und das hat genervt.

Das geht natürlich einfacher: systemd kann Pfade beobachten und selbständig Dinge tun, wenn etwas passiert:

  1. local-webhook-watcher-restarter.path anlegen – da steht drin, was beobachtet werden soll:
  1. Path]
  2. PathModified=/home/webhook/watcher.sh
  3.  
  4. [Install]
  5. WantedBy=local-webhook-watcher.service
  1. local-webhook-watcher-restarter.service anlegen – da steht drin, was passiert, wenn sich am beobachteten Pfad etwas ändert:
  1. [Unit]
  2. Description=restart local-webhook-watcher.service when watcher.sh script is changed
  3.  
  4. [Service]
  5. Type=oneshot
  6. ExecStart=/bin/systemctl restart local-webhook-watcher.service
  7.  
  8. [Install]
  9. WantedBy=local-webhook-watcher.service

Durch Type=oneshot stößt systemd den ExecStart-Prozess einmalig an, kümmert sich dann aber nicht weiter um ihn: Fehler werden ignoriert und stoppen lässt sich auch nichts.

  1. Aktivierung wie gehabt, nur dass wir dieses Mal den .path starten, nicht den .service, denn der .service wird ja getriggert, wenn sich die Datei geändert hat:
  1. systemctl daemon-reload
  2. systemctl enable local-webhook-watcher-restarter.path
  3. systemctl start local-webhook-watcher-restarter.path

Jedes Mal, wenn jetzt das Skript watcher.sh editiert wird, wird der zugehörige systemd-Service neu gestartet und das geänderte Skript wird sofort aktiv. Ganz ohne Root-Rechte.

Diesen automatischen Restart brauche ich jetzt zwar nicht mehr, weil handler.sh ein eigenes Skript ist und für jedes Event frisch gestartet wird, es ist aber gut zu wissen, dass das geht. Und es ist schon fertig eingerichtet und jetzt kann es ja auch ruhig aktiv bleiben…

Der Event-Dispatcher

Das zweite Skript /home/webhook/handler.sh ruft abhängig vom Event-Typ die eigentliche Verarbeitung mittels weiterer Perlskripte (die kommen in späteren Artikeln) auf:

  1. #!/bin/bash
  2.  
  3. die()
  4. {
  5.     echo "$@"
  6.     exit 1
  7. }
  8.  
  9. handle_issue()
  10. {
  11.     ./handle_issue.pl "$1"
  12. }
  13.  
  14. handle_ping()
  15. {
  16.     REPO="$(jq -r .payload.repository.full_name "$1")"
  17.     echo "  got a PING for $REPO"
  18. }
  19.  
  20. handle_pull_request()
  21. {
  22.     ./handle_pull_request.pl "$1"
  23. }
  24.  
  25. handle_push()
  26. {
  27.     ./handle_push.pl "$1"
  28. }
  29.  
  30. process_file()
  31. {
  32.     local JSON="$1"
  33.     local EVENT_TYPE="$(jq -r .event "$JSON")"
  34.  
  35.     echo "processing $EVENT_TYPE event from $JSON"
  36.  
  37.     case "$EVENT_TYPE" in
  38.         issues)
  39.             handle_issue "$JSON"
  40.             ;;
  41.         ping)
  42.             handle_ping "$JSON"
  43.             ;;
  44.         pull_request)
  45.             handle_pull_request "$JSON"
  46.             ;;
  47.         push)
  48.             handle_push "$JSON"
  49.             ;;
  50.         *)
  51.             echo "  (E/$EVENT_TYPE is ignored)"
  52.             ;;
  53.     esac
  54. }
  55.  
  56. FILE="$1"
  57.  
  58. [ -n "$FILE" ] || die 'no JSON file given'
  59. [ -e "$FILE" ] || die 'JSON file does not exist'
  60. [ -r "$FILE" ] || die 'JSON file is not readable'
  61.  
  62. process_file "$FILE"

Auch hier nichts besonderes (außer, dass ich den Code etwas zerfleddert habe): Erstmal wird geguckt, ob der übergebene Dateiname vorhanden und lesbar ist, danach wird anhand des Event-Typs aus der Datei entschieden, welches Skript aufgerufen wird – die einzelnen Skripte kommen in späteren Artikeln.

Um an den Event-Typ aus dem JSON zu kommen, benutze ich jq. jq ist das Schweizer Taschenmesser für JSON in Shell und kann richtig wilde Dinge, wenn man sich erstmal an die Syntax gewöhnt hat. Darin steckt schon eine halbe Programmiersprache und man kann Selektieren, Transformieren und noch viel mehr.[1]

So sieht das JSON in der Queue ungefähr aus (das baue ich mir ja selbst so zusammen):

  1. {
  2.     "event": "status",
  3.     "payload": {
  4.         …
  5.     },
  6.     "delivery": "fed8f64c-2622-11a9-9dcc-b0395b1c703b",
  7.     "received": "1549049070"
  8. }

Mit jq -r .event "$JSON" gibt JSON den Event-Typ (hier: status) aus:

  • "$JSON" ist die Datei, aus der das JSON gelesen wird.
  • .event selektiert das Attribut event aus dem Root-Objekt
  • -r gibt Rohdaten aus, sonst wäre der JSON-String status nochmal in Anführungszeichen und die wird man in der Shell nur schwer wieder los

Das ping-Event wird als einziges nicht an ein externes Skript dispatcht, sondern gleich vor Ort verarbeitet. Hier nehme ich nochmal jq, um über .payload.repository.full_name den Namen des angepingten Repositories aus der Payload von GitHub auszulesen.

Ansonsten wird noch ein wenig nach STDOUT geloggt und im Fehlerfall mit einer Fehlermeldung auf STDOUT plus Returncode 1 abgebrochen – dann greift die Fehlerverarbeitung im aufrufenden Skript watcher.sh.

Damit ist die Empfangsseite komplett, jetzt fehlt noch die tatsächliche Verarbeitung der Events.

[1]: Ich zitiere mal von der jq-Homepage, weil es das echt nett zusammenfasst:
jq is like sed for JSON data - you can use it to slice and filter and map and transform structured data with the same ease that sed, awk, grep and friends let you play with text.
Geschrieben von in Hacken, Internet um 21:00 | Kommentare (0) | Trackback (1)
◀ f r t ▶
Trackbacks
Trackback-URL für diesen Eintrag

Netz - Rettung - Recht am : Wellenreiten 02/2019

Wer als "Websurfer" metaphorisch auf den Wellen des Netzes reitet, findet dabei zwar keine paradiesischen Inseln, manchmal aber immerhin ganz interessante Lektüre. Im Februar 2019 kann ich u.a. folgende Fundstücke empfehlen und der werten Leserschaft ans
Kommentare
Kommentare dieses Artikels abonnieren (als RSS)
Ansicht der Kommentare: (Linear | Verschachtelt)

Noch keine Kommentare

Kommentar schreiben
Um über Antworten auf Deinen Kommentar informiert zu werden, abonniere bitte entweder den Kommentarfeed des ganzen Blogs oder den dieses Eintrages.