reachable-watcher 1.0.128 → 1.0.129

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reachable-watcher",
-  "version": "1.0.128",
+  "version": "1.0.129",
   "description": "Check status codes of web servers and sends notification e-mails",
   "keywords": [
     "reachable",
@@ -12,7 +12,7 @@
     "online"
   ],
   "homepage": "https://tsickert.com/reachable-watcher",
-  "license": "CC-BY-3.0",
+  "license": "CC-BY-4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/thaibault/reachable-watcher.git"
@@ -34,8 +34,10 @@
     "test": "bash ./node_modules/.bin/bashlink-doctest --verbose ../../reachable-watcher",
     "update:documentation": "web-documentation"
   },
+  "dependencies": {
+    "bashlink": "^1.0.296"
+  },
   "devDependencies": {
-    "bashlink": "^1.0.293",
     "rimraf": "^6.1.4",
     "shellcheck": "^4.1.0",
     "web-documentation": "^1.0.74"
@@ -45,5 +47,12 @@
     "npm": ">=12",
     "yarn": ">=4"
   },
+  "webDocumentation": {
+    "languages": [
+      "enUS",
+      "deDE",
+      "frFR"
+    ]
+  },
   "packageManager": "yarn@4.18.1+sha512.b2e1e7524f654f2749d32b4ebcb4622473cb5bcbc485df2007e12a154e50162a4d795526768bc5f5b8f81717bfd79deb2472813d86fb5ae2eb551fa9c872b08f"
 }

package/reachable-watcher.service

@@ -1,12 +1,13 @@
 # -*- coding: utf-8 -*-
 # region header
-# Copyright Torben Sickert (t.sickert["~at~"]gmail.com) 16.12.2012
+# Copyright Torben Sickert (info["~at~"]tsickert.com) 16.12.2012
 
 # License
 # -------
 
 # This library written by Torben Sickert stands under a creative commons naming
-# 3.0 unported license. See https://creativecommons.org/licenses/by/3.0/deed.de
+# 4.0 international license.
+# See https://creativecommons.org/licenses/by/4.0/deed.de
 # endregion
 [Unit]
 Description=Checks server reachabilities.
@@ -17,7 +18,9 @@ After=network.target network-online.target
 [Service]
 Restart=always
 RestartSec=10
-ExecStart=/usr/bin/reachable-watcher
+# NOTE: A relative name is searched in "/usr/local/bin" and "/usr/bin" so that
+# global npm installations are found as well.
+ExecStart=reachable-watcher
 NotifyAccess=all
 
 [Install]

package/reachable-watcher.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # -*- coding: utf-8 -*-
 # region header
-# [Project page](https://tsickert.com/reachableWatcher)
+# [Project page](https://tsickert.com/reachable-watcher)
 
 # Copyright Torben Sickert (info["~at~"]tsickert.com) 16.12.2012
 
@@ -9,7 +9,8 @@
 # -------
 
 # This library written by Torben Sickert stands under a creative commons naming
-# 3.0 unported license. See https://creativecommons.org/licenses/by/3.0/deed.de
+# 4.0 international license.
+# See https://creativecommons.org/licenses/by/4.0/deed.de
 # endregion
 # shellcheck disable=SC1004,SC2016,SC2034,SC2155
 shopt -s expand_aliases
@@ -26,9 +27,16 @@ rw_download() {
     return $?
 }
 
-if [ -f "$(dirname "${BASH_SOURCE[0]}")/node_modules/bashlink/module.sh" ]; then
+# NOTE: Resolves symbolic links (e.g. "/usr/bin/reachable-watcher") to find
+# bashlink next to the real script location (installed via npm).
+declare -g RW_SCRIPT_PATH="$(
+    dirname "$(readlink --canonicalize "${BASH_SOURCE[0]}")")/"
+if [ -f "${RW_SCRIPT_PATH}node_modules/bashlink/module.sh" ]; then
     # shellcheck disable=SC1090
-    source "$(dirname "${BASH_SOURCE[0]}")/node_modules/bashlink/module.sh"
+    source "${RW_SCRIPT_PATH}node_modules/bashlink/module.sh"
+elif [ -f "${RW_SCRIPT_PATH}../bashlink/module.sh" ]; then
+    # shellcheck disable=SC1090
+    source "${RW_SCRIPT_PATH}../bashlink/module.sh"
 elif [ -f "/usr/lib/bashlink/module.sh" ]; then
     # shellcheck disable=SC1091
     source "/usr/lib/bashlink/module.sh"
@@ -40,6 +48,8 @@ else
     if ! (
         [ -f "${BL_MODULE_REMOTE_MODULE_CACHE_PATH}/module.sh" ] || \
         rw.download \
+            --show-error \
+            --silent \
             https://raw.githubusercontent.com/thaibault/bashlink/main/module.sh \
                 >"${BL_MODULE_REMOTE_MODULE_CACHE_PATH}/module.sh"
     ); then
@@ -126,7 +136,7 @@ declare -gr RW__DOCTEST_SETUP__='
 # Maps each url to its expected status code followed by its recipients.
 declare -Ag RW_URLS_TO_CHECK=()
 # Wait for 5 minutes (60 * 5 = 300).
-declare -ig RW_DELAY_BETWEEN_TWO_CONSEQUTIVE_REQUESTS_IN_SECONDS=300
+declare -ig RW_DELAY_BETWEEN_TWO_CONSECUTIVE_REQUESTS_IN_SECONDS=300
 declare -g RW_DATE_TIME_FORMAT='%T:%N at %d.%m.%Y'
 declare -g RW_SENDER_E_MAIL_ADDRESS=''
 # Falls back to the sender address when empty.
@@ -162,10 +172,10 @@ rw_is_status_valid() {
         1
 
         >>> rw.is_status_valid "000" 200; echo $?
-        0
+        1
 
         >>> rw.is_status_valid "000" 206; echo $?
-        0
+        1
 
         >>> rw.is_status_valid 206 "000"; echo $?
         1
@@ -191,14 +201,12 @@ rw_is_status_valid() {
     # NOTE: Given state "000" resolves to "0" as interpreted integer.
     local -ir expected_status_code=$1
     local -ir given_status_code=$2
-    local -ar valid_ok_codes=(0 200 206)
+    # NOTE: Status code "000" indicates that the url is not reachable and is
+    # therefore only valid if expected explicitly.
+    local -ar valid_ok_codes=(200 206)
     if (( expected_status_code == given_status_code )); then
         return 0
     fi
-    # NOTE: Status code "000" indicates that the url is not reachable.
-    if (( given_status_code == 0 )); then
-        return 1
-    fi
     if \
         bl.array.contains "$expected_status_code" "${valid_ok_codes[@]}" &&
         bl.array.contains "$given_status_code" "${valid_ok_codes[@]}"
@@ -411,8 +419,8 @@ rw_main() {
         for url in "${!RW_URLS_TO_CHECK[@]}"; do
             rw.check_url "$url"
         done
-        bl.logging.debug "Wait for $RW_DELAY_BETWEEN_TWO_CONSEQUTIVE_REQUESTS_IN_SECONDS seconds until next check."
-        sleep "$RW_DELAY_BETWEEN_TWO_CONSEQUTIVE_REQUESTS_IN_SECONDS"
+        bl.logging.debug "Wait for $RW_DELAY_BETWEEN_TWO_CONSECUTIVE_REQUESTS_IN_SECONDS seconds until next check."
+        sleep "$RW_DELAY_BETWEEN_TWO_CONSECUTIVE_REQUESTS_IN_SECONDS"
     done
 }
 # endregion

package/readme.md

@@ -7,11 +7,13 @@ License
 -------
 
 This library written by Torben Sickert stands under a creative commons naming
-3.0 unported license. See https://creativecommons.org/licenses/by/3.0/deed.de
+4.0 international license.
+See https://creativecommons.org/licenses/by/4.0/deed.de
 endregion -->
 
 <!--|deDE:Projektstatus-->
-Project Status
+<!--|frFR:Statut du projet-->
+Project status
 --------------
 
 [![npm](https://img.shields.io/npm/v/reachable-watcher?color=%23d55e5d&label=npm%20package%20version&logoColor=%23d55e5d&style=for-the-badge)](https://www.npmjs.com/package/reachable-watcher)
@@ -25,14 +27,27 @@ Project Status
 [![deploy web documentation](https://img.shields.io/github/actions/workflow/status/thaibault/reachable-watcher/deploy-web-documentation.yaml?label=deploy%20web%20documentation&style=for-the-badge)](https://github.com/thaibault/reachable-watcher/actions/workflows/deploy-web-documentation.yaml)
 [![web documentation](https://img.shields.io/website-up-down-green-red/https/tsickert.com/reachable-watcher.svg?label=web-documentation&style=for-the-badge)](https://tsickert.com/reachable-watcher)
 
-<!--|deDE:Verwendung-->
+<!--|deDE:Einsatzmöglichkeiten-->
+<!--|frFR:Cas d'utilisation-->
 Use case
 --------
 
-This module checks reachability of webservers. You can map a list of urls to
-their expected http status codes and a list of email addresses to inform if one
-of the url does not return the expected status code. A check interval is also
-configurable.
+Watches the reachability of web servers with a single Bash script. Each
+configured URL is mapped to its expected HTTP status code and to e-mail
+addresses, which get notified as soon as the URL stops responding as expected
+and again when it recovers.
+<!--deDE:
+    Überwacht die Erreichbarkeit von Webservern mit einem einzigen
+    Bash-Skript. Jede konfigurierte URL wird ihrem erwarteten HTTP-Statuscode
+    und E-Mail-Adressen zugeordnet, die benachrichtigt werden, sobald die URL
+    nicht mehr wie erwartet antwortet, und erneut, wenn sie sich erholt.
+-->
+<!--frFR:
+    Surveille l'accessibilité de serveurs web avec un seul script Bash.
+    Chaque URL configurée est associée à son code de statut HTTP attendu et
+    à des adresses e-mail, qui sont notifiées dès que l'URL ne répond plus
+    comme prévu, puis à nouveau lorsqu'elle se rétablit.
+-->
 
 <div class="wd-table-of-contents">
     <h2 id="content">Content<!--deDE:Inhalt--><!--frFR:Contenu--></h2>
@@ -42,68 +57,202 @@ configurable.
 Installation
 ------------
 
-You can install via package manager, simply download the compiled version as
-zip file here and inject or request via CDN in HTML:
+On Arch Linux, build and install the "PKGBUILD" of this repository (it needs
+the "bashlink" package) and enable the service:
 <!--deDE:
-    Sie können das Paket über den Paketmanager installieren oder einfach die
-    kompilierte Version als ZIP-Datei hier herunterladen und in HTML einbinden
-    oder über ein CDN abrufen:
+    Unter Arch Linux bauen und installieren Sie das "PKGBUILD" dieses
+    Repositorys (es benötigt das Paket "bashlink") und aktivieren den
+    Dienst:
 -->
 <!--frFR:
-    Vous pouvez installer le paquet via le gestionnaire de paquets ou
-    simplement télécharger ici la version compilée sous forme de fichier ZIP,
-    puis l'intégrer dans une page HTML ou la récupérer via un CDN:
+    Sous Arch Linux, construisez et installez le "PKGBUILD" de ce dépôt (il
+    nécessite le paquet "bashlink") et activez le service:
 -->
 
 ```bash
-npm install reachable-watcher
+makepkg --install --syncdeps
+systemctl enable --now reachable-watcher
 ```
 
-Features
---------
+Anywhere else, install it globally via npm, which brings its library
+[bashlink](https://tsickert.com/bashlink) along, and link the shipped unit:
+<!--deDE:
+    Überall sonst installieren Sie es global über npm, das seine Bibliothek
+    [bashlink](https://tsickert.com/bashlink) mitbringt, und verlinken die
+    mitgelieferte Unit:
+-->
+<!--frFR:
+    Partout ailleurs, installez-le globalement via npm, qui apporte sa
+    bibliothèque [bashlink](https://tsickert.com/bashlink), et liez l'unité
+    fournie:
+-->
 
-- Configurable interval to check for expected http status codes
-- Can be run on any linux machine (minimal dependencies)
-- Configure an email address to get notified if any resource doesn't work as
-  expected or isn't even available.
+```bash
+npm install --global reachable-watcher
+systemctl link \
+    "$(npm root --global)/reachable-watcher/reachable-watcher.service"
+systemctl enable --now reachable-watcher
+```
 
-<!--|deDE:Beispiel-->
-<!--|frFR:Exemple-->
-Example
--------
+The unit starts "reachable-watcher" from "/usr/local/bin" or "/usr/bin". The
+script alone works as well: it needs "bash" and "curl" and downloads bashlink
+on its first start if it is missing. E-mails need "msmtp".
+`journalctl -u reachable-watcher` shows what the service does.
+<!--deDE:
+    Die Unit startet "reachable-watcher" aus "/usr/local/bin" oder
+    "/usr/bin". Das Skript allein funktioniert ebenfalls: Es benötigt "bash"
+    und "curl" und lädt bashlink beim ersten Start herunter, wenn es fehlt.
+    E-Mails benötigen "msmtp". `journalctl -u reachable-watcher` zeigt, was
+    der Dienst tut.
+-->
+<!--frFR:
+    L'unité démarre "reachable-watcher" depuis "/usr/local/bin" ou
+    "/usr/bin". Le script seul fonctionne aussi: il nécessite "bash" et
+    "curl" et télécharge bashlink à son premier démarrage s'il manque. Les
+    e-mails nécessitent "msmtp". `journalctl -u reachable-watcher` montre ce
+    que fait le service.
+-->
+
+Configuration
+-------------
 
-Run this script to initialize the watcher.
+"/etc/reachableWatcher" is a Bash file which overrides the defaults. At least
+the URLs to check and the sender address have to be set. Each URL maps to its
+expected status code, followed by the e-mail addresses to notify:
+<!--deDE:
+    "/etc/reachableWatcher" ist eine Bash-Datei, die die Standardwerte
+    überschreibt. Mindestens die zu prüfenden URLs und die Absenderadresse
+    müssen gesetzt werden. Jede URL wird ihrem erwarteten Statuscode
+    zugeordnet, gefolgt von den zu benachrichtigenden E-Mail-Adressen:
+-->
+<!--frFR:
+    "/etc/reachableWatcher" est un fichier Bash qui remplace les valeurs par
+    défaut. Il faut au minimum définir les URL à vérifier et l'adresse de
+    l'expéditeur. Chaque URL est associée à son code de statut attendu,
+    suivi des adresses e-mail à notifier:
+-->
 
-```sh
-./reachableWatcher.sh
+```bash
+RW_SENDER_E_MAIL_ADDRESS=watcher@example.com
+declare -A RW_URLS_TO_CHECK=(
+    ['https://example.com']='200 admin@example.com'
+    ['https://example.com/missing']='404 admin@example.com dev@example.com'
+)
+# Optional settings with their defaults:
+RW_DELAY_BETWEEN_TWO_CONSECUTIVE_REQUESTS_IN_SECONDS=300
+RW_NAME=NODE_NAME
+RW_REPLIER_E_MAIL_ADDRESS="$RW_SENDER_E_MAIL_ADDRESS"
+RW_VERBOSE=false
 ```
 
-or after installation:
+"RW_NAME" names this machine in the e-mail subjects, "RW_VERBOSE=true" logs
+every state change. Run "reachable-watcher" once by hand to check the
+configuration.
+<!--deDE:
+    "RW_NAME" benennt diesen Rechner in den E-Mail-Betreffs,
+    "RW_VERBOSE=true" protokolliert jeden Zustandswechsel. Führen Sie
+    "reachable-watcher" einmal von Hand aus, um die Konfiguration zu prüfen.
+-->
+<!--frFR:
+    "RW_NAME" nomme cette machine dans les objets des e-mails,
+    "RW_VERBOSE=true" journalise chaque changement d'état. Lancez
+    "reachable-watcher" une fois à la main pour vérifier la configuration.
+-->
 
-```sh
-reachable-watcher
-```
+<!--|deDE:Statuscodes-->
+<!--|frFR:Codes de statut-->
+### Status codes
 
-Configuration
--------------
+Every interval each URL is requested via "HEAD" (certificates are not
+verified). The response is valid if:
+<!--deDE:
+    In jedem Intervall wird jede URL per "HEAD" angefragt (Zertifikate werden
+    nicht geprüft). Die Antwort ist gültig, wenn:
+-->
+<!--frFR:
+    À chaque intervalle, chaque URL est demandée via "HEAD" (les certificats
+    ne sont pas vérifiés). La réponse est valide si:
+-->
+
+- its status code equals the expected one or<!--deDE:ihr Statuscode dem erwarteten entspricht oder--><!--frFR:son code de statut est égal à celui attendu ou-->
+- both are one of "200" and "206".<!--deDE:beide einer von "200" und "206" sind.--><!--frFR:les deux font partie de "200" et "206".-->
+
+An unreachable URL results in "000", which is only valid if "000" is expected,
+e.g. to make sure that an internal service stays hidden.
+<!--deDE:
+    Eine nicht erreichbare URL ergibt "000", was nur gültig ist, wenn "000"
+    erwartet wird, z. B. um sicherzustellen, dass ein interner Dienst
+    verborgen bleibt.
+-->
+<!--frFR:
+    Une URL inaccessible donne "000", ce qui n'est valide que si "000" est
+    attendu, par exemple pour s'assurer qu'un service interne reste caché.
+-->
+
+Recipients are only notified when the state of a URL changes, from valid to
+invalid or back. A URL which is valid on the first check sends nothing.
+<!--deDE:
+    Empfänger werden nur benachrichtigt, wenn sich der Zustand einer URL
+    ändert, von gültig zu ungültig oder zurück. Eine URL, die bei der ersten
+    Prüfung gültig ist, verschickt nichts.
+-->
+<!--frFR:
+    Les destinataires ne sont notifiés que lorsque l'état d'une URL change,
+    de valide à invalide ou inversement. Une URL valide lors de la première
+    vérification n'envoie rien.
+-->
+
+<!--|deDE:E-Mails-->
+<!--|frFR:E-mails-->
+### E-mails
 
-Simply edit the constants region of the provided shell script.
+E-mails are sent via "msmtp", so it needs a working "~/.msmtprc" or
+"/etc/msmtprc", e.g.:
+<!--deDE:
+    E-Mails werden über "msmtp" verschickt, es braucht also eine
+    funktionierende "~/.msmtprc" oder "/etc/msmtprc", z. B.:
+-->
+<!--frFR:
+    Les e-mails sont envoyés via "msmtp", il faut donc un "~/.msmtprc" ou un
+    "/etc/msmtprc" fonctionnel, par exemple:
+-->
 
-Installation (under systemd)
-----------------------------
+```
+defaults
+auth           on
+tls            on
+tls_starttls   on
+tls_trust_file /etc/ssl/certs/ca-certificates.crt
+logfile        /tmp/msmtpLog
 
-Copy the script file "reachableWatcher.sh" to "/usr/bin/reachable-watcher" and
-the provided service file ("reachableWatcher.service") to
-"/etc/systemd/system/reachable-watcher.service" run:
+account        mail
+host           smtp.example.com
+port           587
+from           watcher@example.com
+user           watcher@example.com
+password       PASSWORD
 
-```sh
-systemctl enable reachable-watcher
+account        default : mail
 ```
 
-to enable the checking logic. After running:
+<!--|deDE:Entwicklung-->
+<!--|frFR:Développement-->
+Development
+-----------
 
-```sh
-systemctl start reachable-watcher
+```bash
+yarn install
+yarn lint
+yarn test
 ```
 
-you can see the worker running in your system logs.
+"yarn test" runs the examples in the script's documentation as tests,
+"yarn document" renders this documentation as HTML.
+<!--deDE:
+    "yarn test" führt die Beispiele aus der Dokumentation des Skripts als
+    Tests aus, "yarn document" erzeugt diese Dokumentation als HTML.
+-->
+<!--frFR:
+    "yarn test" exécute les exemples de la documentation du script comme
+    tests, "yarn document" génère cette documentation en HTML.
+-->