mirror of
https://github.com/mailcow/mailcow-dockerized.git
synced 2026-11-15 21:00:14 +00:00
[Web][Dovecot] Add retention rules: nightly deletion of mail by folder and age for domains, groups and mailboxes
This commit is contained in:
36 files changed
+3013
-16
No files matched your search
@@ -0,0 +1,112 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Mailcow\Retention\Service;
|
||||
|
||||
use Mailcow\Retention\Model\Rule;
|
||||
|
||||
/**
|
||||
* What the rules of one mailbox delete: the most specific rule wins, per folder of the mailbox. The folders of the
|
||||
* rules become entries in order: a rule assigned to the mailbox before one of its groups before one of the whole
|
||||
* domain; then by what an entry matches (MATCHES, the folder itself first); then the longer period, then the lower
|
||||
* id. The runner gives every folder to the first entry that matches it.
|
||||
*/
|
||||
class Planner
|
||||
{
|
||||
public const LEVEL_DOMAIN = 1;
|
||||
public const LEVEL_GROUP = 2;
|
||||
public const LEVEL_MAILBOX = 3;
|
||||
|
||||
/**
|
||||
* What an entry matches, most specific first: the folder itself (a special folder, the inbox, an own folder
|
||||
* without *), an own folder name with *, the subfolders of a special folder or the inbox, all folders
|
||||
*/
|
||||
public const MATCHES = ['folder' => 3, 'pattern' => 2, 'subfolders' => 1, 'all' => 0];
|
||||
|
||||
/**
|
||||
* @param array<array{rule: Rule, level: int}> $candidates active rules of one mailbox with their assignment level
|
||||
* @return array[] in order: folder (key), match, days, keep_flagged, mode, rule_id, rule_name. Entries that never
|
||||
* win are left out: one matching the same folders as an entry before and everything after all folders.
|
||||
*/
|
||||
public static function actions(array $candidates): array
|
||||
{
|
||||
$entries = [];
|
||||
foreach ($candidates as $candidate) {
|
||||
foreach ($candidate['rule']->folders as $folder) {
|
||||
foreach (self::matches($folder) as $match) {
|
||||
// the lower id decides between equal rules, so the result does not depend on the order
|
||||
$entries[] = [
|
||||
'score' => [$candidate['level'], self::MATCHES[$match], $candidate['rule']->days, -(int)$candidate['rule']->id],
|
||||
'folder' => $folder,
|
||||
'match' => $match,
|
||||
'rule' => $candidate['rule'],
|
||||
];
|
||||
}
|
||||
}
|
||||
}
|
||||
usort($entries, fn(array $a, array $b): int => $b['score'] <=> $a['score']);
|
||||
$actions = [];
|
||||
foreach ($entries as $entry) {
|
||||
if (isset($actions[$entry['folder'] . "\n" . $entry['match']])) {
|
||||
continue;
|
||||
}
|
||||
$actions[$entry['folder'] . "\n" . $entry['match']] = self::action($entry['folder'], $entry['match'], $entry['rule']);
|
||||
if ($entry['match'] === 'all') {
|
||||
break;
|
||||
}
|
||||
}
|
||||
return array_values($actions);
|
||||
}
|
||||
|
||||
/**
|
||||
* The plan for people: the subfolders of a special folder or the inbox go with the folder (subfolders 1) when the
|
||||
* same rule decides both and no entry with * comes between them.
|
||||
*
|
||||
* @return array[] the entries of actions() with subfolders 0 or 1
|
||||
*/
|
||||
public static function describe(array $actions): array
|
||||
{
|
||||
$described = [];
|
||||
$folders = [];
|
||||
foreach ($actions as $action) {
|
||||
$key = $action['folder'] . "\n" . $action['rule_id'];
|
||||
if ($action['match'] === 'subfolders' && isset($folders[$key])) {
|
||||
$described[$folders[$key]]['subfolders'] = 1;
|
||||
continue;
|
||||
}
|
||||
if ($action['match'] === 'pattern') {
|
||||
$folders = [];
|
||||
} elseif ($action['match'] === 'folder') {
|
||||
$folders[$key] = count($described);
|
||||
}
|
||||
$described[] = $action + ['subfolders' => (int)($action['match'] === 'subfolders')];
|
||||
}
|
||||
return $described;
|
||||
}
|
||||
|
||||
/** @return string[] what the folder key of a rule matches */
|
||||
private static function matches(string $folder): array
|
||||
{
|
||||
if ($folder === 'all') {
|
||||
return ['all'];
|
||||
}
|
||||
if (str_starts_with($folder, Rule::OWN_FOLDER)) {
|
||||
return [str_contains($folder, '*') ? 'pattern' : 'folder'];
|
||||
}
|
||||
return ['folder', 'subfolders'];
|
||||
}
|
||||
|
||||
private static function action(string $folder, string $match, Rule $rule): array
|
||||
{
|
||||
return [
|
||||
'folder' => $folder,
|
||||
'match' => $match,
|
||||
'days' => $rule->days,
|
||||
'keep_flagged' => $rule->keepFlagged,
|
||||
'mode' => $rule->mode,
|
||||
'rule_id' => $rule->id,
|
||||
'rule_name' => $rule->name,
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,359 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Mailcow\Retention\Service;
|
||||
|
||||
use Mailcow\Core\AccessDenied;
|
||||
use Mailcow\Core\Context;
|
||||
use Mailcow\Core\Input;
|
||||
use Mailcow\Core\UserError;
|
||||
use Mailcow\Retention\Model\Rule;
|
||||
use Mailcow\Retention\Repository\RuleRepository;
|
||||
|
||||
/**
|
||||
* Use cases of retention rules.
|
||||
*
|
||||
* Read: admins all rules (also read-only API keys); domain admins with the `retention` ACL the rules of their
|
||||
* domains. Mailbox users see the rules that apply to their mailbox (effective()).
|
||||
* Edit: admins; domain admins with the ACL for rules of their domains. A rule is assigned to all mailboxes of its
|
||||
* domain or to mailboxes and groups of it. Groups need the `mailbox_groups` ACL as well: without it a domain
|
||||
* admin sees no groups and keeps the group assignments.
|
||||
*/
|
||||
class RuleService
|
||||
{
|
||||
private const MAX_FOLDERS = 50;
|
||||
private const MAX_MEMBERS = 500;
|
||||
private const MAX_DAYS = 36500;
|
||||
private const LOG_LIMIT = 1000;
|
||||
/** Mailboxes per page of the plan, and results per report of the runner */
|
||||
private const PLAN_PAGE = 500;
|
||||
private const MAX_RESULTS = 1000;
|
||||
|
||||
public function __construct(private RuleRepository $repo, private Context $context)
|
||||
{
|
||||
}
|
||||
|
||||
public function canRead(): bool
|
||||
{
|
||||
return $this->context->hasAdminRights()
|
||||
|| ($this->context->isDomainAdmin() && $this->context->hasAcl('retention'));
|
||||
}
|
||||
|
||||
/** @throws AccessDenied unless the caller may edit rules at all */
|
||||
public function requireEditor(): void
|
||||
{
|
||||
if (!$this->canRead() || $this->context->isReadOnlyApi()) {
|
||||
throw new AccessDenied();
|
||||
}
|
||||
}
|
||||
|
||||
public function get(int $id): ?Rule
|
||||
{
|
||||
$rule = $this->canRead() ? $this->repo->find($id) : null;
|
||||
return ($rule !== null && $this->visible($rule)) ? $rule : null;
|
||||
}
|
||||
|
||||
/** @return int[] */
|
||||
public function visibleIds(array $domains = []): array
|
||||
{
|
||||
return $this->canRead() ? $this->repo->visibleIds($this->context, $domains) : [];
|
||||
}
|
||||
|
||||
public function canEdit(Rule $rule): bool
|
||||
{
|
||||
return $this->canRead() && !$this->context->isReadOnlyApi() && $this->visible($rule);
|
||||
}
|
||||
|
||||
/** $lastRun: summary of the last nightly run, null = not run yet */
|
||||
public function toArray(Rule $rule, ?array $lastRun = null): array
|
||||
{
|
||||
return $rule->toArray() + ['can_edit' => (int)$this->canEdit($rule), 'last_run' => $lastRun];
|
||||
}
|
||||
|
||||
/** @return array<int, array> rule id => summary of its last nightly run */
|
||||
public function lastRuns(array $ruleIds): array
|
||||
{
|
||||
return $this->canRead() ? $this->repo->lastRuns($ruleIds) : [];
|
||||
}
|
||||
|
||||
/** @throws UserError */
|
||||
public function create(array $input): Rule
|
||||
{
|
||||
$this->requireEditor();
|
||||
$rule = new Rule();
|
||||
$rule->domain = $this->domainFor($input['domain'] ?? null);
|
||||
$this->apply($rule, $input);
|
||||
$this->repo->save($rule);
|
||||
return $rule;
|
||||
}
|
||||
|
||||
/** Attributes missing in $input keep their value @throws UserError */
|
||||
public function update(int $id, array $input): Rule
|
||||
{
|
||||
$rule = $this->editable($id);
|
||||
$this->apply($rule, $input);
|
||||
$this->repo->save($rule);
|
||||
return $rule;
|
||||
}
|
||||
|
||||
/** @throws UserError */
|
||||
public function delete(int $id): Rule
|
||||
{
|
||||
$rule = $this->editable($id);
|
||||
$this->repo->delete($id);
|
||||
return $rule;
|
||||
}
|
||||
|
||||
/** @return array[] id, name, domain, address of the groups in these domains (choices of the forms) */
|
||||
public function groupChoices(array $domains): array
|
||||
{
|
||||
return ($this->canRead() && $this->canUseGroups()) ? $this->repo->groupsIn($domains) : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* What the rules delete in a mailbox, per folder (see Planner): for the mailbox user, or for those who may read
|
||||
* the rules and access the mailbox.
|
||||
*
|
||||
* @return array[] actions of Planner::actions()
|
||||
* @throws AccessDenied
|
||||
*/
|
||||
public function effective(mixed $username): array
|
||||
{
|
||||
$username = strtolower((string)Input::text($username));
|
||||
$allowed = $this->context->isUser() ? $username === strtolower((string)$this->context->username)
|
||||
: ($this->canRead() && ($this->context->hasAdminRights() || $this->context->canAccessMailbox($username)));
|
||||
if ($username === '' || !$allowed) {
|
||||
throw new AccessDenied();
|
||||
}
|
||||
return Planner::actions($this->repo->candidates([$username])[$username] ?? []);
|
||||
}
|
||||
|
||||
/** @return array[] results of the nightly runs in the caller's domains, newest first; $limit 0 = LOG_LIMIT */
|
||||
public function log(int $limit = 0): array
|
||||
{
|
||||
return $this->canRead() ? $this->repo->log($this->context, [], ($limit > 0) ? min($limit, self::LOG_LIMIT * 10) : self::LOG_LIMIT) : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* A page of the plan of the nightly run (system context), mailboxes after $after in order
|
||||
*
|
||||
* @return array{mailboxes: array<string, array[]>, next: ?string} username => actions of Planner::actions() for
|
||||
* the mailboxes with rules; next: the $after of the next page, null after the last
|
||||
*/
|
||||
public function plan(string $after = '', int $limit = 0): array
|
||||
{
|
||||
$limit = ($limit > 0) ? min($limit, self::PLAN_PAGE) : self::PLAN_PAGE;
|
||||
$usernames = $this->repo->mailboxesWithRules($after, $limit);
|
||||
$plan = array_filter(array_map(fn(array $candidates): array => Planner::actions($candidates), $this->repo->candidates($usernames)));
|
||||
return ['mailboxes' => $plan, 'next' => (count($usernames) < $limit) ? null : (string)end($usernames)];
|
||||
}
|
||||
|
||||
/**
|
||||
* Results of the nightly run (system context): mailboxes with found mail or errors, a summary per rule and at
|
||||
* the end the whole run
|
||||
*
|
||||
* @throws UserError for more than MAX_RESULTS results
|
||||
*/
|
||||
public function report(array $results, array $summary, ?array $run = null): int
|
||||
{
|
||||
if (count($results) > self::MAX_RESULTS || count($summary) > self::MAX_RESULTS * 10) {
|
||||
throw new UserError('retention_entries_exceeded', [self::MAX_RESULTS]);
|
||||
}
|
||||
$results = array_filter($results, fn(mixed $result): bool => is_array($result) && is_string($result['username'] ?? null)
|
||||
&& is_numeric($result['rule_id'] ?? null) && is_string($result['folder'] ?? null));
|
||||
$summary = array_filter($summary, fn(mixed $runOfRule): bool => is_array($runOfRule) && is_numeric($runOfRule['rule_id'] ?? null));
|
||||
return $this->repo->addLog(array_values($results), array_values($summary), $run);
|
||||
}
|
||||
|
||||
/** The domain was deleted: its rules went with it (foreign key), the results of its runs go now */
|
||||
public function domainDeleted(string $domain): void
|
||||
{
|
||||
$this->repo->deleteLog($domain);
|
||||
}
|
||||
|
||||
private function visible(Rule $rule): bool
|
||||
{
|
||||
return $this->context->hasAdminRights() || $this->context->canAccessDomain($rule->domain);
|
||||
}
|
||||
|
||||
private function canUseGroups(): bool
|
||||
{
|
||||
return $this->context->hasAdminRights() || $this->context->hasAcl('mailbox_groups');
|
||||
}
|
||||
|
||||
/** @throws UserError */
|
||||
private function editable(int $id): Rule
|
||||
{
|
||||
$this->requireEditor();
|
||||
$rule = $this->get($id);
|
||||
if ($rule === null || !$this->canEdit($rule)) {
|
||||
throw new AccessDenied();
|
||||
}
|
||||
return $rule;
|
||||
}
|
||||
|
||||
/** @throws UserError */
|
||||
private function domainFor(mixed $value): string
|
||||
{
|
||||
$domain = strtolower((string)Input::text($value));
|
||||
if ($domain === '' || !$this->repo->isDomain($domain)) {
|
||||
throw new UserError('domain_not_found', [htmlspecialchars((string)Input::text($value))]);
|
||||
}
|
||||
if (!$this->context->hasAdminRights() && !$this->context->canAccessDomain($domain)) {
|
||||
throw new AccessDenied();
|
||||
}
|
||||
return $domain;
|
||||
}
|
||||
|
||||
/** @throws UserError */
|
||||
private function apply(Rule $rule, array $input): void
|
||||
{
|
||||
if (array_key_exists('name', $input) || $rule->id === null) {
|
||||
$name = Input::text($input['name'] ?? null);
|
||||
if ($name === null || $name === '' || mb_strlen($name) > 100 || preg_match('/[\x00-\x1f\x7f]/', $name)) {
|
||||
throw new UserError('retention_name_invalid');
|
||||
}
|
||||
if ($this->repo->nameExists($rule->domain, $name, $rule->id)) {
|
||||
throw new UserError('object_exists', [htmlspecialchars($name)]);
|
||||
}
|
||||
$rule->name = $name;
|
||||
}
|
||||
if (array_key_exists('description', $input)) {
|
||||
$description = Input::text($input['description']);
|
||||
if ($description === null || mb_strlen($description) > 255 || preg_match('/[\x00-\x1f\x7f]/', $description)) {
|
||||
throw new UserError('retention_description_invalid');
|
||||
}
|
||||
$rule->description = $description;
|
||||
}
|
||||
// the UI sends the special folders and the own folder names apart (own_folders, one per line or a list)
|
||||
if (array_key_exists('folders', $input) || array_key_exists('own_folders', $input)) {
|
||||
$folders = array_key_exists('folders', $input) ? self::values($input['folders'])
|
||||
: array_filter($rule->folders, fn(string $folder): bool => in_array($folder, Rule::FOLDERS, true));
|
||||
if (array_key_exists('own_folders', $input)) {
|
||||
$folders = array_filter($folders, fn(string $folder): bool => !str_starts_with($folder, Rule::OWN_FOLDER));
|
||||
$names = is_array($input['own_folders']) ? $input['own_folders'] : preg_split('/\r?\n/', (string)Input::text($input['own_folders']));
|
||||
foreach ($names as $name) {
|
||||
if (!is_string($name)) {
|
||||
throw new UserError('retention_folder_invalid', ['']);
|
||||
}
|
||||
if (trim($name) !== '') {
|
||||
$folders[] = Rule::OWN_FOLDER . trim($name);
|
||||
}
|
||||
}
|
||||
}
|
||||
$rule->folders = self::folders($folders);
|
||||
}
|
||||
if ($rule->folders === []) {
|
||||
throw new UserError('retention_folders_invalid');
|
||||
}
|
||||
if (array_key_exists('days', $input) || $rule->id === null) {
|
||||
$days = Input::intInRange($input['days'] ?? null, 1, self::MAX_DAYS);
|
||||
$rule->days = $days ?? throw new UserError('retention_days_invalid', [self::MAX_DAYS]);
|
||||
}
|
||||
if (array_key_exists('mode', $input)) {
|
||||
$mode = Input::text($input['mode']);
|
||||
$rule->mode = in_array($mode, Rule::MODES, true) ? $mode : throw new UserError('retention_mode_invalid');
|
||||
}
|
||||
foreach (['keep_flagged' => 'keepFlagged', 'all_mailboxes' => 'allMailboxes', 'active' => 'active'] as $key => $property) {
|
||||
if (array_key_exists($key, $input)) {
|
||||
$rule->$property = (int)self::flag($input[$key]);
|
||||
}
|
||||
}
|
||||
if (array_key_exists('mailboxes', $input)) {
|
||||
$rule->mailboxes = [];
|
||||
foreach (self::limited($input['mailboxes'], self::MAX_MEMBERS) as $username) {
|
||||
$username = strtolower($username);
|
||||
if ($this->repo->mailboxDomain($username) !== $rule->domain) {
|
||||
throw new UserError('retention_member_invalid', [htmlspecialchars($username)]);
|
||||
}
|
||||
$rule->mailboxes[$username] = $username;
|
||||
}
|
||||
$rule->mailboxes = array_values($rule->mailboxes);
|
||||
}
|
||||
// without access to groups the assignments stay; only sending them back unchanged is accepted
|
||||
$groupAccess = $this->canUseGroups();
|
||||
if (array_key_exists('groups', $input) && !$groupAccess && self::values($input['groups']) !== []) {
|
||||
$sent = array_values(array_unique(array_map('intval', self::values($input['groups']))));
|
||||
$stored = $rule->groups;
|
||||
sort($sent);
|
||||
sort($stored);
|
||||
if ($sent !== $stored) {
|
||||
throw new AccessDenied();
|
||||
}
|
||||
}
|
||||
if (array_key_exists('groups', $input) && $groupAccess) {
|
||||
$rule->groups = [];
|
||||
foreach (self::limited($input['groups'], self::MAX_MEMBERS) as $value) {
|
||||
$id = Input::intInRange($value, 1, PHP_INT_MAX);
|
||||
if ($id === null || $this->repo->groupDomain($id) !== $rule->domain) {
|
||||
throw new UserError('retention_member_invalid', [htmlspecialchars($value)]);
|
||||
}
|
||||
$rule->groups[$id] = $id;
|
||||
}
|
||||
$rule->groups = array_values($rule->groups);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Folders of a rule: keys of Rule::FOLDERS and folder:<name>, without repeats. Names are Dovecot folder names
|
||||
* (separator /, wildcard *), printable and at most 255 characters; INBOX is written in capitals like Dovecot does.
|
||||
*
|
||||
* @param string[] $values
|
||||
* @return string[]
|
||||
* @throws UserError
|
||||
*/
|
||||
private static function folders(array $values): array
|
||||
{
|
||||
$folders = [];
|
||||
foreach (self::limited($values, self::MAX_FOLDERS) as $folder) {
|
||||
if (str_starts_with($folder, Rule::OWN_FOLDER)) {
|
||||
$name = trim(substr($folder, strlen(Rule::OWN_FOLDER)), " \t/");
|
||||
if ($name === '' || mb_strlen($name) > 255 || preg_match('/[\x00-\x1f\x7f]/u', $name) || !mb_check_encoding($name, 'UTF-8')) {
|
||||
throw new UserError('retention_folder_invalid', [htmlspecialchars($folder)]);
|
||||
}
|
||||
$name = preg_replace('~^inbox(?=/|$)~i', 'INBOX', $name);
|
||||
$folder = Rule::OWN_FOLDER . $name;
|
||||
} elseif (!in_array($folder, Rule::FOLDERS, true)) {
|
||||
throw new UserError('retention_folder_invalid', [htmlspecialchars($folder)]);
|
||||
}
|
||||
$folders[$folder] = $folder;
|
||||
}
|
||||
return array_values($folders);
|
||||
}
|
||||
|
||||
/**
|
||||
* Values of a list field without repeats, at most $max (checked before anything is looked up)
|
||||
*
|
||||
* @return string[]
|
||||
* @throws UserError
|
||||
*/
|
||||
private static function limited(mixed $value, int $max): array
|
||||
{
|
||||
$values = array_values(array_unique(self::values($value)));
|
||||
if (count($values) > $max) {
|
||||
throw new UserError('retention_entries_exceeded', [$max]);
|
||||
}
|
||||
return $values;
|
||||
}
|
||||
|
||||
/**
|
||||
* Values of a list field: an array (multi-select, JSON) or a string separated by line breaks or commas.
|
||||
*
|
||||
* @return string[]
|
||||
*/
|
||||
private static function values(mixed $value): array
|
||||
{
|
||||
$values = is_array($value) ? $value : preg_split('/[\r\n,;]+/', (string)Input::text($value));
|
||||
return array_values(array_filter(array_map(fn(mixed $v): string => is_scalar($v) ? trim((string)$v) : '', $values), 'strlen'));
|
||||
}
|
||||
|
||||
/** Checkbox or API flag; a hidden "0" + checkbox pair arrives as ["0", "1"] when checked */
|
||||
private static function flag(mixed $value): bool
|
||||
{
|
||||
if (is_array($value)) {
|
||||
$value = end($value);
|
||||
}
|
||||
return filter_var($value, FILTER_VALIDATE_BOOLEAN);
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user