refactor: relay.sh (#3845)

* chore: `relay.sh` helper - Reference user config paths via variables

* chore: Better document postfix helper `_vhost_collect_postfix_domains()`

The functionality is effectively the same for the two configs for the most part when it comes to parsing out a domain from the target value.

Virtual aliases is more flexible in value, which may not have a domain-part present (manual user edit).

* chore: `check-for-change.sh` - Support VHOST change visibility

- Moves the "handle changes" logic into it's own scoped function, out of the main change detection loop logic.
- This will be benefit a future commit change that will rely on `VHOST_UPDATED=1`.

* chore: `relay.sh` - Minor revisions to minimize diff noise

- Better phrasing of the current logic comments.
- Regex patterns assigned to variables (easier to grok intention)
- Bulk of the logic for generating `/etc/postfix/relayhost_map` wrapped into a separate function with Postfix config setting handled separately.

* refactor: `relay.sh` opt-out logic

- Split the two distinct features that configure `/etc/postfix/relayhost_map` into separate functions (_`MATCH_VALID` var no longer needed for legacy support_).
- Instead of extracting domains from `postfix-accounts.cf` + `postfix-virtual.cf`, this has already been handled at `/etc/postfix/vhost`, sourcing from there is far less complicated.
- Rename loop var `DOMAIN_PART`to `SENDER_DOMAIN` for better context of what it represents when appended to the config file.
- Revised maintenance notes + guidance towards a future refactor of this relayhost feature support.

* docs: `relay.sh` - Additional comment revisions

* feat: `DEFAULT_RELAY_HOST` can now also use relay credentials ENV

- Remove comment regarding `smtp_sasl_password_maps = static:${RELAY_USER}:${RELAY_PASSWORD}`, it could be used but `main.cf` presently has `644` permissions vs the `sasl_passwd` file permissions of `600`, less secure at preventing leaking of secrets (ignoring the ENV exposure itself).
- Move the `main.cf` settings specific to relayhost credentials support / security into to the relevant function scope instead. This also allows for the configuration to be applied by a change detection event without container restart requirement.
- Outer functions for setup and change detection to call have a clearer config dependency guard, as does the `_legacy_support()`.
- These changes now support `DEFAULT_RELAY_HOST` to leverage the relay credentials ENV as well.
- `DATABASE_RELAYHOSTS` is available in scope to the functions called here that reference it.

* docs: Revised ENV docs on relay host config

Better quality guidance on configuring relay hosts.

* chore: Add entry to `CHANGELOG.md`

* fix: `relay.sh` - `grep` regex compatibility with `+` requires `-E`

* chore: `postfix.sh` - `FIRST_FIELD` => More descriptive field name

target/scripts/helpers/postfix.sh

@@ -43,21 +43,28 @@ function _vhost_collect_postfix_domains() {
   local DATABASE_VIRTUAL='/tmp/docker-mailserver/postfix-virtual.cf'
   local DOMAIN UNAME
 
-  # getting domains FROM mail accounts
+  # Extract domains from mail accounts:
   if [[ -f ${DATABASE_ACCOUNTS} ]]; then
-    while IFS=$'|' read -r LOGIN _; do
-      DOMAIN=$(echo "${LOGIN}" | cut -d @ -f2)
+    while IFS=$'|' read -r MAIL_ACCOUNT _; do
+      # It is expected valid lines have the format local-part@domain-part:
+      DOMAIN=$(cut -d '@' -f 2 <<< "${MAIL_ACCOUNT}")
+
       echo "${DOMAIN}" >>"${TMP_VHOST}"
     done < <(_get_valid_lines_from_file "${DATABASE_ACCOUNTS}")
   fi
 
-  # getting domains FROM mail aliases
+  # TODO: Consider if virtual aliases should be configured to the same vhost file:
+  # https://github.com/docker-mailserver/docker-mailserver/issues/2813#issuecomment-1272394563
+  # Extract domains from virtual alias config:
+  # Aliases may have the forms: 'local-part@domain-part', only 'local-part', or '@domain-part' (wildcard catch-all)
   if [[ -f ${DATABASE_VIRTUAL} ]]; then
-    while read -r FROM _; do
-      UNAME=$(echo "${FROM}" | cut -d @ -f1)
-      DOMAIN=$(echo "${FROM}" | cut -d @ -f2)
+    while read -r ALIAS_FIELD _; do
+      UNAME=$(cut -d '@' -f 1 <<< "${ALIAS_FIELD}")
+      DOMAIN=$(cut -d '@' -f 2 <<< "${ALIAS_FIELD}")
 
-      # if they are equal it means the line looks like: "user1     other@domain.tld"
+      # Only add valid domain-parts found:
+      # The '@' is optional for an alias key (eg: "user1     other@domain.tld"),
+      # but cut with -f2 would output the same value as it would -f1 when '@' is missing.
       [[ ${UNAME} != "${DOMAIN}" ]] && echo "${DOMAIN}" >>"${TMP_VHOST}"
     done < <(_get_valid_lines_from_file "${DATABASE_VIRTUAL}")
   fi