Implement restore-backup-content action

- Retrieve the partial backup from Restic.
- Import data into user's Maildir.
- Disable quota if limit is exceeded.

Added "restore-folder" command to Dovecot's container, and related
documentation.

dovecot/README.md

@@ -90,6 +90,25 @@ preference is stored in the _dict_ database file
 `/var/lib/dovecot/dict/uspamret.db`. See the dedicated section below to
 modify it.
 
+### `restore-folder`
+
+Import subdirectories of a Maildir++ structure (restored from backup)
+under the user's "Restored folder." Command syntax:
+
+    restore-folder {USER} {BACKUP_DIR} {FOLDER_PATH} [ROOT_FOLDER]
+
+- **USER**: The destination IMAP user name.
+- **BACKUP_DIR**: The source directory where backup contents were
+  extracted. Any subdirectory beginning with a "." (per the Maildir++
+  format) is imported.
+- **FOLDER_PATH**: The IMAP path for the restored folder. Unused path
+  ancestors are pruned.
+- **ROOT_FOLDER** (Optional): Defaults to "Restored folder" if
+  unspecified, under which contents are imported.
+
+The command disables the USER's quota if necessary to avoid an over-quota
+state.
+
 ## Storage
 
 Volumes are:

dovecot/usr/local/bin/restore-folder

@@ -0,0 +1,56 @@
+#!/bin/ash
+# shellcheck shell=bash
+
+#
+# Copyright (C) 2024 Nethesis S.r.l.
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+
+set -o pipefail
+set -e
+
+user="${1:?missing user argument}"
+restoredir="${2:?missing source dir path}"
+destfolder="${3:?missing destination folder name}"
+rootfolder="${4:-Restored folder}"
+basefolder="$(basename "${destfolder}")"
+rootprefix=$(doveadm mailbox path -u "${user}" "${rootfolder}")
+
+chown -c vmail:vmail "${restoredir}"
+cd "${restoredir}"
+
+read -r curquotalimit curquotamb < <(doveadm -f tab quota get -u "${user}" | awk -F $'\t' 'NR==2 {print $4 "\t" int($4/1024)}')
+if [ "${curquotalimit}" != "-" ]; then
+    # Temporarly disable the user's quota
+    doveadm dict set -u "${user}" fs:posix:prefix=/var/lib/dovecot/dict/uquota/ shared/"${user}" 0
+fi
+
+doveadm mailbox create    -u "${user}" "${rootfolder}" &>/dev/null || :
+doveadm mailbox subscribe -u "${user}" "${rootfolder}"
+doveadm mailbox delete    -u "${user}" -r -s "${rootfolder}/${basefolder}" &>/dev/null || :
+for folder in .* ; do
+    [ "${folder}" == "." ] && continue
+    [ "${folder}" == ".." ] && continue
+    [ ! -d "${folder}" ] && continue
+    if [ -e "${rootprefix}${folder}" ]; then
+        echo "WARNING! Found already existing destination path ${rootprefix}${folder}. Forcing removal." 1>&2
+        rm -rf "${rootprefix}${folder}"
+    fi
+    mv -v "${folder}" "${rootprefix}${folder}"
+done
+# Prune destfolder ancestors:
+doveadm mailbox rename    -u "${user}" -s "${rootfolder}/${destfolder}" "${rootfolder}/${basefolder}" || :
+doveadm index             -u "${user}" "${rootfolder}/${basefolder}"
+doveadm quota recalc      -u "${user}"
+
+read -r newquotavalue < <(doveadm -f tab quota get -u "${user}" | awk -F $'\t' 'NR==2 {print $3}')
+
+if [ "${curquotalimit}" == "-" ]; then
+    echo "QUOTA_UNCHANGED. Quota usage ${newquotavalue} KB. Quota is not limited, nothing to do."
+elif [ "${newquotavalue}" -lt "${curquotalimit}" ]; then
+    # Restore previous user's quota
+    doveadm dict set -u "${user}" fs:posix:prefix=/var/lib/dovecot/dict/uquota/ shared/"${user}" "${curquotamb}"
+    echo "QUOTA_UNCHANGED. Quota restored to ${curquotamb}"
+else
+    echo "QUOTA_DISABLED_BY_RESTORE. Original quota was insufficient for the restore of ${destfolder}. User quota is disabled now."
+fi

imageroot/actions/restore-backup-content/50restore_backup_content

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+
+#
+# Copyright (C) 2024 Nethesis S.r.l.
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+
+import json
+import sys
+import os
+import subprocess
+import agent
+import atexit
+
+request = json.load(sys.stdin)
+
+# Temporary path for restore. It is relative to Dovecot's vmail dir, the
+# default working directory for the dovecot container:
+tmp_restore_path = ".restore-backup-content." + os.environ["AGENT_TASK_ID"]
+# Transform the folder path into a filesystem directory name:
+_, maildir_path = subprocess.check_output([
+    'podman', 'exec', 'dovecot',
+    'doveadm', 'mailbox', 'path', '-u', request['user'], request['folder'],
+], text=True).strip().rsplit('/', 1)
+maildir_path_goescaped = maildir_path.replace("\\", "\\\\")
+restic_args = [
+    "restore",
+    f"{request['snapshot']}:volumes/dovecot-data/{request['user']}/Maildir",
+    f"--target=/srv/volumes/dovecot-data/{tmp_restore_path}",
+    f"--include={maildir_path_goescaped}*",
+]
+podman_args = ["--workdir=/srv"] + agent.agent.get_state_volume_args()
+
+def cleanup_tmp():
+    global tmp_restore_path
+    if tmp_restore_path:
+        agent.run_helper("podman", "exec", "dovecot", "rm", "-rf", tmp_restore_path)
+atexit.register(cleanup_tmp)
+
+proc_restore = agent.run_restic(agent.redis_connect(), request["destination"], request["repopath"], podman_args, restic_args, stdout=sys.stderr)
+if proc_restore.returncode != 0:
+    print(agent.SD_ERR + f"Restic restore command failed with exit code {proc_restore.returncode}.", file=sys.stderr)
+    sys.exit(1)
+
+# 1. Disable the user quota temporarly.
+# 2. Move the restored content under "Restored content" IMAP folder.
+#    Remove the destination if already exists.
+# 3. Reindex the destination folder.
+# 4. Restore the previous quota setting, if possible
+quota_disabled = False
+
+proc_import = subprocess.run(["podman", "exec", "-i", "dovecot",
+    "restore-folder", request["user"], f"/var/lib/vmail/{tmp_restore_path}", request['folder']],
+    stdout=subprocess.PIPE, text=True)
+if proc_import.returncode != 0:
+    print(agent.SD_ERR + f"Import script failed with exit code {proc_import.returncode}.", file=sys.stderr)
+    sys.exit(1)
+
+if 'QUOTA_DISABLED_BY_RESTORE' in proc_import.stdout:
+    quota_disabled = True
+
+json.dump({
+    "request": request,
+    "quota_disabled": quota_disabled,
+}, fp=sys.stdout)

imageroot/actions/restore-backup-content/validate-input.json

@@ -0,0 +1,52 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "restore-backup-content input",
+    "$id": "http://schema.nethserver.org/mail/restore-backup-content-input.json",
+    "description": "Restore the backup of a user's mail folder.",
+    "examples": [
+        {
+            "folder": "INBOX/Liste/Samba.org",
+            "user": "first.user",
+            "destination": "14030a59-a4e6-54cc-b8ea-cd5f97fe44c8",
+            "repopath": "mail/4372a5d5-0886-45d3-82e7-68d913716a4c",
+            "snapshot": "aee022f50fa0b494ee9b172d1395375d7d471e3b647b6238750008dba92d29f7"
+        },
+        {
+            "folder": "INBOX/Liste/Samba.org",
+            "user": "first.user",
+            "destination": "14030a59-a4e6-54cc-b8ea-cd5f97fe44c8",
+            "repopath": "mail/4372a5d5-0886-45d3-82e7-68d913716a4c",
+            "snapshot": "latest"
+        }
+    ],
+    "type": "object",
+    "required": [
+        "folder",
+        "destination",
+        "repopath",
+        "snapshot",
+        "user"
+    ],
+    "properties": {
+        "folder": {
+            "type": "string",
+            "description": "Absolute IMAP folder path to restore. Its subfolders will be restored as well."
+        },
+        "destination": {
+            "type": "string",
+            "description": "The UUID of the backup destination where the Restic repository resides."
+        },
+        "repopath": {
+            "type": "string",
+            "description": "Restic repository path, under the backup destination"
+        },
+        "snapshot": {
+            "type": "string",
+            "description": "Restic snapshot ID to restore"
+        },
+        "user": {
+            "type": "string",
+            "description": "Restore the content of this Dovecot IMAP user"
+        }
+    }
+}

imageroot/actions/restore-backup-content/validate-output.json

@@ -0,0 +1,33 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "restore-backup-content output",
+    "$id": "http://schema.nethserver.org/mail/restore-backup-content-output.json",
+    "description": "Restore the backup of a user's mail folder.",
+    "examples": [
+        {
+            "request": {
+                "destination": "14030a59-a4e6-54cc-b8ea-cd5f97fe44c8",
+                "folder": "INBOX/Liste/Samba.org",
+                "repopath": "mail/4372a5d5-0886-45d3-82e7-68d913716a4c",
+                "snapshot": "latest",
+                "user": "first.user"
+            },
+            "quota_disabled": false
+        }
+    ],
+    "type": "object",
+    "required": [
+        "quota_disabled"
+    ],
+    "properties": {
+        "quota_disabled": {
+            "title": "Quota disabled",
+            "type": "boolean",
+            "description": "If the restore has disabled the user's quota or not"
+        },
+        "request": {
+            "type": "object",
+            "title": "Original request object"
+        }
+    }
+}