chore(housekeeping): Create helpers/change-detection.sh (#2610)

* chore: Extract change-detection method to it's own helper

This doesn't really belong in `helpers/ssl.sh`. Moving to it's own helper script.

* chore: Co-locate related change-detection method from container startup

It seems relevant to migrate the related support during startup for the change detection feature into this helper.

I opted to move the call from `start-mailserver.sh` into the `_setup` call at the end for a more explicit/visible location.

* chore: Move `CHKSUM_FILE` into `helpers/change-detection.sh`

It belongs there, not in `helpers/index.sh`.

* chore: Revise inline documentation

* tests(fix): Ensure correct functionality

Presently `test/test_helper.bats` is using it's own  `CHKSUM_FILE` instead of sourcing the var for the filepath.

`test_helper/common.bash` was calling a method to check for changes, but this helper may not correctly detect letsencrypt related changes as these are not ENV rely on, but global vars handled by `helpers/dns.sh`, so that should be run first like it is for `check-for-changes.sh`.

* tests(chore): Use `CHKSUM_FILE` var from helper

* chore: `addmailuser` should use `CHKSUM_FILE` var

* chore: Update `check-for-changes.sh` log message with correct path

target/scripts/helpers/change-detection.sh

@@ -0,0 +1,78 @@
+#! /bin/bash
+
+# This helper supports the changedetector service. Used by:
+# - check-for-changes.sh
+# - test/test_helper/common.bash:wait_for_changes_to_be_detected_in_container()
+# - test/test_helper.bats
+# - start-mailserver.sh --> setup-stack.sh (to initialize the CHKSUM_FILE state)
+
+# Global checksum file used to track when monitored files have changed in content:
+# shellcheck disable=SC2034
+CHKSUM_FILE=/tmp/docker-mailserver-config-chksum
+
+# Once container startup scripts complete, take a snapshot of
+# the config state via storing a list of files content hashes.
+function _prepare_for_change_detection
+{
+  _log 'debug' 'Setting up configuration checksum file'
+
+  if [[ -d /tmp/docker-mailserver ]]
+  then
+    _log 'trace' "Creating '${CHKSUM_FILE}'"
+    _monitored_files_checksums >"${CHKSUM_FILE}"
+  else
+    # We could just skip the file, but perhaps config can be added later?
+    # If so it must be processed by the check for changes script
+    _log 'trace' "Creating empty '${CHKSUM_FILE}' (no config)"
+    touch "${CHKSUM_FILE}"
+  fi
+}
+
+# Returns a list of changed files, each line is a value pair of:
+# <SHA-512 content hash> <changed file path>
+function _monitored_files_checksums
+{
+  local DMS_DIR=/tmp/docker-mailserver
+  [[ -d ${DMS_DIR} ]] || return 1
+
+  # If a wildcard path pattern (or an empty ENV) would yield an invalid path
+  # or no results, `shopt -s nullglob` prevents it from being added.
+  shopt -s nullglob
+  declare -a STAGING_FILES CHANGED_FILES
+
+  STAGING_FILES=(
+    "${DMS_DIR}/postfix-accounts.cf"
+    "${DMS_DIR}/postfix-virtual.cf"
+    "${DMS_DIR}/postfix-aliases.cf"
+    "${DMS_DIR}/dovecot-quotas.cf"
+    "${DMS_DIR}/dovecot-masters.cf"
+  )
+
+  if [[ ${SSL_TYPE:-} == 'manual' ]]
+  then
+    # When using "manual" as the SSL type,
+    # the following variables may contain the certificate files
+    STAGING_FILES+=(
+      "${SSL_CERT_PATH:-}"
+      "${SSL_KEY_PATH:-}"
+      "${SSL_ALT_CERT_PATH:-}"
+      "${SSL_ALT_KEY_PATH:-}"
+    )
+  elif [[ ${SSL_TYPE:-} == 'letsencrypt' ]]
+  then
+    # React to any cert changes within the following LetsEncrypt locations:
+    STAGING_FILES+=(
+      /etc/letsencrypt/acme.json
+      /etc/letsencrypt/live/"${SSL_DOMAIN}"/*.pem
+      /etc/letsencrypt/live/"${HOSTNAME}"/*.pem
+      /etc/letsencrypt/live/"${DOMAINNAME}"/*.pem
+    )
+  fi
+
+  for FILE in "${STAGING_FILES[@]}"
+  do
+    [[ -f "${FILE}" ]] && CHANGED_FILES+=("${FILE}")
+  done
+
+  sha512sum -- "${CHANGED_FILES[@]}"
+}