reachable-watcher 1.0.125 → 1.0.126-1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reachable-watcher",
-  "version": "1.0.125",
+  "version": "1.0.126-1",
   "description": "Check status codes of web servers and sends notification e-mails",
   "keywords": [
     "reachable",
@@ -15,36 +15,35 @@
   "license": "CC-BY-3.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/thaibault/reachable-watcher"
+    "url": "git+https://github.com/thaibault/reachable-watcher.git"
   },
   "main": "reachable-watcher.sh",
-  "bin": "reachable-watcher.sh",
+  "bin": {
+    "reachable-watcher": "reachable-watcher.sh"
+  },
   "files": [
     "reachable-watcher.service"
   ],
   "scripts": {
     "clear": "rimraf apiDocumentation",
-    "document": "mkdir --parents apiDocumentation/reachable-watcher/latest && bashlink-document reachable-watcher 1>apiDocumentation/reachable-watcher/latest/index.html",
-    "document:show": "bashlink-document reachable-watcher",
-    "document:show:error": "bashlink-document reachable-watcher 1>/dev/null",
-    "lint": "hash shellcheck && shellcheck -x *.sh || echo Please install \"shellcheck\". || true",
+    "document": "mkdir --parents apiDocumentation/reachable-watcher/latest && bash ./node_modules/.bin/bashlink-document reachable-watcher 1>apiDocumentation/reachable-watcher/latest/index.html",
+    "document:show": "bash ./node_modules/.bin/bashlink-document reachable-watcher",
+    "document:show:error": "bash ./node_modules/.bin/bashlink-document reachable-watcher 1>/dev/null",
+    "lint": "shellcheck -x *.sh",
     "lint:given": "shellcheck -x",
-    "test": "./node_modules/.bin/bashlink-doctest --verbose ../../reachable-watcher",
+    "test": "bash ./node_modules/.bin/bashlink-doctest --verbose ../../reachable-watcher",
     "update:documentation": "web-documentation"
   },
   "devDependencies": {
-    "bashlink": "^1.0.282",
-    "rimraf": "^6.1.3",
+    "bashlink": "^1.0.292",
+    "rimraf": "^6.1.4",
     "shellcheck": "^4.1.0",
-    "web-documentation": "^1.0.65"
+    "web-documentation": "^1.0.72"
   },
   "engines": {
     "node": ">=26",
     "npm": ">=12",
     "yarn": ">=4"
   },
-  "webDocumentation": {
-    "trackingCode": "UA-40192634-15"
-  },
   "packageManager": "yarn@4.18.1+sha512.b2e1e7524f654f2749d32b4ebcb4622473cb5bcbc485df2007e12a154e50162a4d795526768bc5f5b8f81717bfd79deb2472813d86fb5ae2eb551fa9c872b08f"
 }

package/reachable-watcher.sh

@@ -19,7 +19,7 @@ rw_download() {
     local -r __documentation__='
         Simply downloads missing modules.
 
-        >>> br.download --silent https://domain.tld/path/to/file.ext; echo $?
+        >>> rw.download --silent https://domain.tld/path/to/file.ext; echo $?
         6
     '
     command curl --insecure "$@"
@@ -53,8 +53,10 @@ else
     # shellcheck disable=SC1091
     source "${BL_MODULE_REMOTE_MODULE_CACHE_PATH}/module.sh"
 fi
+# NOTE: Shortens this module's scope to "rw_*" and "RW_*" names.
+BL_MODULE_FUNCTION_SCOPE_REWRITES+=('^reachable\.watcher$/rw/')
+BL_MODULE_GLOBAL_SCOPE_REWRITES+=('^REACHABLE_WATCHER$/RW/')
 bl.module.import bashlink.array
-bl.module.import bashlink.dictionary
 bl.module.import bashlink.exception
 bl.module.import bashlink.logging
 bl.module.import bashlink.tools
@@ -106,30 +108,45 @@ declare -agr RW__DEPENDENCIES__=(
     bash
     curl
     date
-    grep
     msmtp
     sleep
 )
-BL_MODULE_FUNCTION_SCOPE_REWRITES+=('^reachableWatcher([._][a-zA-Z_-]+)?$/rw\1/')
-BL_MODULE_GLOBAL_SCOPE_REWRITES+=('^REACHABLE_WATCHER(_[a-zA-Z_-]+)?$/RW\1/')
+declare -gr RW__DOCTEST_SETUP__='
+    # Mocks the status code request (configurable via
+    # "RW_DOCTEST_STATUS_CODE") and prints only the receiver and subject of
+    # each sent e-mail.
+    curl() {
+        echo -n "${RW_DOCTEST_STATUS_CODE:-200}"
+    }
+    msmtp() {
+        command grep --extended-regexp "^(To|Subject):"
+    }
+'
 ## region default options
-declare -ag RW_URLS_TO_CHECK=()
+# 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 -g RW_DATE_TIME_FORMAT='%T:%N at %d.%m.%Y'
 declare -g RW_SENDER_E_MAIL_ADDRESS=''
-declare -g RW_REPLIER_E_MAIL_ADDRESS="$RW_SENDER_E_MAIL_ADDRESS"
+# Falls back to the sender address when empty.
+declare -g RW_REPLIER_E_MAIL_ADDRESS=''
 declare -g RW_VERBOSE=false
 declare -g RW_NAME=NODE_NAME
 ## endregion
 ## region load options if present
-if [ -f /etc/reachableWatcher ]; then
+if \
+    [ "${BL_DOCTEST_RUNNING:-false}" != true ] && \
+    [ -f /etc/reachableWatcher ]
+then
     # shellcheck disable=SC1091
     source /etc/reachableWatcher
 fi
 ## endregion
+# Last determined state ("valid" or "invalid") of each checked url.
+declare -Ag RW_STATES=()
 # endregion
-# region functions
+# region helper
 alias rw.is_status_valid=rw_is_status_valid
 rw_is_status_valid() {
     local -r __documentation__='
@@ -139,10 +156,10 @@ rw_is_status_valid() {
         0
 
         >>> rw.is_status_valid 200 "000"; echo $?
-        0
+        1
 
         >>> rw.is_status_valid 200 0; echo $?
-        0
+        1
 
         >>> rw.is_status_valid "000" 200; echo $?
         0
@@ -151,6 +168,9 @@ rw_is_status_valid() {
         0
 
         >>> rw.is_status_valid 206 "000"; echo $?
+        1
+
+        >>> rw.is_status_valid "000" "000"; echo $?
         0
 
         >>> rw.is_status_valid 206 200; echo $?
@@ -172,12 +192,13 @@ rw_is_status_valid() {
     local -ir expected_status_code=$1
     local -ir given_status_code=$2
     local -ar valid_ok_codes=(0 200 206)
-    if \
-        (( expected_status_code == given_status_code )) || \
-        (( given_status_code == 0 ))
-    then
+    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[@]}"
@@ -186,95 +207,214 @@ rw_is_status_valid() {
     fi
     return 1
 }
-## region controller
-alias rw.main=rw_main
-rw_main() {
+alias rw.get_expected_status_code=rw_get_expected_status_code
+rw_get_expected_status_code() {
     local -r __documentation__='
-        Main entry point.
+        Determines the expected status code of given url configuration.
+
+        >>> rw.get_expected_status_code "200 a@domain.tld b@domain.tld"
+        200
+
+        >>> rw.get_expected_status_code "  206   a@domain.tld"
+        206
+
+        >>> rw.get_expected_status_code 404
+        404
     '
-    $RW_VERBOSE && \
-        bl.logging.set_level info
-    while true; do
-        local url_to_check
-        for url_to_check in "${!RW_URLS_TO_CHECK[@]}"; do
-            local -i expected_status_code="$(
-                echo "${RW_URLS_TO_CHECK[$url_to_check]}" | \
-                    grep '^[^ ]+' --only-matching --extended-regexp)"
-            bl.logging.debug "Check url \"$url_to_check\" for status code $expected_status_code."
-            local -i given_status_code="$(
-                curl \
-                    --head \
-                    --insecure \
-                    --output /dev/null \
-                    --silent \
-                    --write-out '%{http_code}' \
-                    "$url_to_check"
-            )"
-            local normalized_url_to_check="$(
-                echo "$url_to_check" | sed 's/[:/.]/_/g')"
-            if rw.is_status_valid \
-                "$expected_status_code" \
-                "$given_status_code"
-            then
-                local message="Requested URL \"$url_to_check\" returns valid status code $given_status_code on $(date +"$RW_DATE_TIME_FORMAT")."
-                bl.logging.debug "$message"
-                if [ "$(bl.dictionary.get state "$normalized_url_to_check")" = invalid ]; then
-                    bl.logging.info "Status has changed to \"valid\" for \"$url_to_check\". Do notification."
-                    local e_main_address
-                    for e_mail_address in $(
-                        echo "${RW_URLS_TO_CHECK[$url_to_check]}" | \
-                            grep ' .+$' --only-matching --extended-regexp)
-                    do
-                        msmtp -t <<EOF
-From: $RW_SENDER_E_MAIL_ADDRESS
-To: $e_mail_address
-Reply-To: $RW_REPLIER_E_MAIL_ADDRESS
-Date: $(date)
-Subject: $RW_NAME registers: "$url_to_check" responses with valid status code $given_status_code.
+    local -a parts
+    read -r -a parts <<<"$1"
+    echo "${parts[0]}"
+}
+alias rw.get_recipients=rw_get_recipients
+rw_get_recipients() {
+    local -r __documentation__='
+        Determines all recipients of given url configuration (one per line).
 
-$message
+        >>> rw.get_recipients "200 a@domain.tld  b@domain.tld"
+        a@domain.tld
+        b@domain.tld
 
-EOF
-                    done
-                    bl.dictionary.set state "$normalized_url_to_check" valid
-                else
-                    bl.logging.debug "Status unchanged."
-                fi
-            else
-                local message="Requested URL \"$url_to_check\" returns status code $given_status_code (instead of \"$expected_status_code\") on $(date +"$RW_DATE_TIME_FORMAT")."
-                bl.logging.debug "$message"
-                if \
-                    [ "$(bl.dictionary.get state "$normalized_url_to_check")" = valid ] ||
-                    [ "$(bl.dictionary.get state "$normalized_url_to_check")" = '' ]
-                then
-                    bl.logging.info "Status has changed to \"invalid for \"$url_to_check\". Do notification."
-                    local e_main_address
-                    for e_mail_address in $(
-                        echo "${RW_URLS_TO_CHECK[$url_to_check]}" | \
-                            grep ' .+$' --only-matching --extended-regexp)
-                    do
-                        msmtp -t <<EOF
+        >>> rw.get_recipients 200 | wc --lines
+        0
+    '
+    local -a parts
+    read -r -a parts <<<"$1"
+    if (( ${#parts[@]} > 1 )); then
+        printf '%s\n' "${parts[@]:1}"
+    fi
+}
+alias rw.request_status_code=rw_request_status_code
+rw_request_status_code() {
+    local -r __documentation__='
+        Requests given url and prints the resulting status code ("000" if no
+        response could be retrieved).
+
+        >>> rw.request_status_code https://domain.tld
+        200
+
+        >>> RW_DOCTEST_STATUS_CODE=503
+        >>> rw.request_status_code https://domain.tld
+        503
+
+        >>> unset -f curl
+        >>> rw.request_status_code http://127.0.0.1:1
+        000
+    '
+    # NOTE: Declaring and assigning at once ignores the exit code of failing
+    # requests so that they do not trigger an exception.
+    local -r status_code="$(
+        curl \
+            --head \
+            --insecure \
+            --output /dev/null \
+            --silent \
+            --write-out '%{http_code}' \
+            "$1"
+    )"
+    echo "$status_code"
+}
+alias rw.notify=rw_notify
+rw_notify() {
+    local -r __documentation__='
+        Sends an e-mail with given subject and message to given recipient.
+
+        >>> msmtp() { cat; }
+        >>> RW_SENDER_E_MAIL_ADDRESS=sender@domain.tld
+        >>> rw.notify a@domain.tld "A subject" "A message." | \
+        >>>     grep --invert-match --extended-regexp "^(Date:.*)?$"
+        From: sender@domain.tld
+        To: a@domain.tld
+        Reply-To: sender@domain.tld
+        Subject: A subject
+        A message.
+
+        >>> msmtp() { grep "^Reply-To:"; }
+        >>> RW_SENDER_E_MAIL_ADDRESS=sender@domain.tld
+        >>> RW_REPLIER_E_MAIL_ADDRESS=replier@domain.tld
+        >>> rw.notify a@domain.tld "A subject" "A message."
+        Reply-To: replier@domain.tld
+    '
+    local -r recipient="$1"
+    local -r subject="$2"
+    local -r message="$3"
+    msmtp -t <<EOF
 From: $RW_SENDER_E_MAIL_ADDRESS
-To: $e_mail_address
-Reply-To: $RW_REPLIER_E_MAIL_ADDRESS
+To: $recipient
+Reply-To: ${RW_REPLIER_E_MAIL_ADDRESS:-$RW_SENDER_E_MAIL_ADDRESS}
 Date: $(date)
-Subject: $RW_NAME registers: "$url_to_check" responses with invalid status code $given_status_code!
+Subject: $subject
 
 $message
 
 EOF
-                    done
-                    bl.dictionary.set state "$normalized_url_to_check" invalid
-                else
-                    bl.logging.debug "Status unchanged."
-                fi
-            fi
+}
+# endregion
+# region controller
+alias rw.check_url=rw_check_url
+rw_check_url() {
+    local -r __documentation__='
+        Checks given url once and notifies all its recipients if its state has
+        changed. An initially valid state is not notified.
+
+        >>> RW_URLS_TO_CHECK=(["https://domain.tld"]="200 a@domain.tld")
+        >>> rw.check_url https://domain.tld
+        >>> echo "${RW_STATES[https://domain.tld]}"
+        valid
+
+        >>> RW_URLS_TO_CHECK=(["https://domain.tld"]="200 a@domain.tld")
+        >>> RW_DOCTEST_STATUS_CODE=503
+        >>> rw.check_url https://domain.tld
+        >>> echo "${RW_STATES[https://domain.tld]}"
+        To: a@domain.tld
+        Subject: NODE_NAME registers: "https://domain.tld" responses with invalid status code 503!
+        invalid
+
+        >>> RW_URLS_TO_CHECK=(["https://domain.tld"]="200 a@domain.tld")
+        >>> RW_DOCTEST_STATUS_CODE=000
+        >>> rw.check_url https://domain.tld
+        >>> echo "${RW_STATES[https://domain.tld]}"
+        To: a@domain.tld
+        Subject: NODE_NAME registers: "https://domain.tld" is not reachable!
+        invalid
+
+        >>> RW_URLS_TO_CHECK=(
+        >>>     ["https://domain.tld/?a=b&c"]="200 a@domain.tld b@domain.tld"
+        >>> )
+        >>> rw.check_url "https://domain.tld/?a=b&c"
+        >>> RW_DOCTEST_STATUS_CODE=500
+        >>> rw.check_url "https://domain.tld/?a=b&c"
+        >>> rw.check_url "https://domain.tld/?a=b&c"
+        >>> RW_DOCTEST_STATUS_CODE=206
+        >>> rw.check_url "https://domain.tld/?a=b&c"
+        >>> rw.check_url "https://domain.tld/?a=b&c"
+        To: a@domain.tld
+        Subject: NODE_NAME registers: "https://domain.tld/?a=b&c" responses with invalid status code 500!
+        To: b@domain.tld
+        Subject: NODE_NAME registers: "https://domain.tld/?a=b&c" responses with invalid status code 500!
+        To: a@domain.tld
+        Subject: NODE_NAME registers: "https://domain.tld/?a=b&c" responses with valid status code 206.
+        To: b@domain.tld
+        Subject: NODE_NAME registers: "https://domain.tld/?a=b&c" responses with valid status code 206.
+    '
+    local -r url="$1"
+    local -r configuration="${RW_URLS_TO_CHECK[$url]}"
+    local -ir expected_status_code="$(
+        rw.get_expected_status_code "$configuration")"
+    bl.logging.debug "Check url \"$url\" for status code $expected_status_code."
+    local -ir given_status_code="$(rw.request_status_code "$url")"
+    local -r now="$(date +"$RW_DATE_TIME_FORMAT")"
+    local state message subject
+    if rw.is_status_valid "$expected_status_code" "$given_status_code"; then
+        state=valid
+        message="Requested URL \"$url\" returns valid status code $given_status_code on ${now}."
+        subject="$RW_NAME registers: \"$url\" responses with valid status code ${given_status_code}."
+    elif (( given_status_code == 0 )); then
+        state=invalid
+        message="Requested URL \"$url\" is not reachable (instead of returning status code \"$expected_status_code\") on ${now}."
+        subject="$RW_NAME registers: \"$url\" is not reachable!"
+    else
+        state=invalid
+        message="Requested URL \"$url\" returns status code $given_status_code (instead of \"$expected_status_code\") on ${now}."
+        subject="$RW_NAME registers: \"$url\" responses with invalid status code ${given_status_code}!"
+    fi
+    bl.logging.debug "$message"
+    local -r last_state="${RW_STATES[$url]:-valid}"
+    RW_STATES[$url]="$state"
+    if [ "$state" = "$last_state" ]; then
+        bl.logging.debug "Status unchanged."
+        return 0
+    fi
+    bl.logging.info "Status has changed to \"$state\" for \"$url\". Do notification."
+    local recipient
+    for recipient in $(rw.get_recipients "$configuration"); do
+        rw.notify "$recipient" "$subject" "$message"
+    done
+}
+alias rw.main=rw_main
+rw_main() {
+    local -r __documentation__='
+        Main entry point: Checks all configured urls periodically.
+
+        >>> RW_URLS_TO_CHECK=(
+        >>>     ["https://a.tld"]="200 a@domain.tld"
+        >>>     ["https://b.tld"]="404 b@domain.tld"
+        >>> )
+        >>> sleep() { exit; }
+        >>> rw.main
+        To: b@domain.tld
+        Subject: NODE_NAME registers: "https://b.tld" responses with invalid status code 200!
+    '
+    $RW_VERBOSE && \
+        bl.logging.set_level info
+    while true; do
+        local url
+        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"
     done
 }
-## endregion
 # endregion
 if bl.tools.is_main; then
     bl.exception.activate

package/readme.md

@@ -19,6 +19,9 @@ Project Status
 
 [![build push package](https://img.shields.io/github/actions/workflow/status/thaibault/reachable-watcher/build-package-and-push.yaml?label=build%20push%20package&style=for-the-badge)](https://github.com/thaibault/reachable-watcher/actions/workflows/build-package-and-push.yaml)
 
+[![lint](https://img.shields.io/github/actions/workflow/status/thaibault/reachable-watcher/lint.yaml?label=lint&style=for-the-badge)](https://github.com/thaibault/reachable-watcher/actions/workflows/lint.yaml)
+[![test](https://img.shields.io/github/actions/workflow/status/thaibault/reachable-watcher/test.yaml?label=test&style=for-the-badge)](https://github.com/thaibault/reachable-watcher/actions/workflows/test.yaml)
+
 [![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)