[james-project] 04/04: JAMES-3758 Documentation of deleting old messages via Web Admin interface, and companion Expires mailet.

[ka...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

kao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git

commit 93a32bb5e73b23c2e7d7ffd1debcd675227d9336
Author: Karsten Otto <ka...@akquinet.de>
AuthorDate: Mon May 23 14:00:27 2022 +0200

    JAMES-3758 Documentation of deleting old messages via Web Admin interface, and companion Expires mailet.
---
 .../docs/modules/ROOT/pages/configure/mailets.adoc |  2 +
 .../docs/modules/ROOT/pages/operate/webadmin.adoc  | 57 ++++++++++++++++++++++
 .../docs/modules/ROOT/partials/Expires.adoc        | 34 +++++++++++++
 3 files changed, 93 insertions(+)

diff --git a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/mailets.adoc b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/mailets.adoc
index f5df5a0f7f..d069f1fd4c 100644
--- a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/mailets.adoc
+++ b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/mailets.adoc
@@ -26,6 +26,8 @@ include::partial$DKIMVerify.adoc[]
 
 include::partial$DSNBounce.adoc[]
 
+include::partial$Expires.adoc[]
+
 include::partial$ExtractMDNOriginalJMAPMessageId.adoc[]
 
 include::partial$Forward.adoc[]
diff --git a/server/apps/distributed-app/docs/modules/ROOT/pages/operate/webadmin.adoc b/server/apps/distributed-app/docs/modules/ROOT/pages/operate/webadmin.adoc
index 47ec81b266..d7ccfd3324 100644
--- a/server/apps/distributed-app/docs/modules/ROOT/pages/operate/webadmin.adoc
+++ b/server/apps/distributed-app/docs/modules/ROOT/pages/operate/webadmin.adoc
@@ -1206,6 +1206,63 @@ This task could be run safely online and can be scheduled on a recurring
 basis outside of peak traffic by an admin to ensure Cassandra message
 consistency.
 
+=== Deleting old messages of all users
+
+*Note:*
+Consider enabling the xref:configure/vault.adoc[Deleted Messages Vault]
+if you use this feature.
+
+Old messages tend to pile up in user INBOXes. An admin might want to delete
+these on behalf of the users, e.g. all messages older than 30 days:
+....
+curl -XDELETE http://ip:port/messages?olderThan=30d
+....
+
+link:#_endpoints_returning_a_task[More details about endpoints returning a task].
+
+The `olderThan` parameter should be expressed in the following format: `Nunit`.
+`N` should be strictly positive. `unit` could be either in the short form
+(`d`, `w`, `y` etc.), or in the long form (`days`, `weeks`, `months`, `years`).
+The default unit is `days`.
+
+Response codes:
+
+* 201: Success. Corresponding task id is returned.
+* 400: Error in the request. Details can be found in the reported error.
+
+The scheduled task will have the type `ExpireMailboxTask` and the following `additionalInformation`:
+
+....
+{
+  "type": "ExpireMailboxTask"
+  "mailboxesExpired": 5,
+  "mailboxesFailed": 2,
+  "mailboxesProcessed": 10,
+  "messagesDeleted": 23,
+}
+....
+
+To delete old mails from a different mailbox than INBOX, e.g. a mailbox
+named "Archived" :
+....
+curl -XDELETE http://ip:port/messages?mailbox=Archived&olderThan=30d
+....
+
+Since this is a somewhat expensive operation, the task is throttled to one user
+per second. You may speed it up via `usersPerSecond=10` for example. But keep
+in mind that a high rate might overwhelm your database or blob store.
+
+*Scanning search only:* (unsupported for Lucene and ElasticSearch search implementations) +
+Some mail clients can add an `Expires` header (RFC 4021) to their messages.
+Instead of specifying an absolute age, you may choose to delete only such
+messages where the expiration date from this header lies in the past:
+....
+curl -XDELETE http://ip:port/messages?byExpiresHeader
+....
+In this case you should also add the xref:configure/mailets.adoc[mailet]
+`Expires` to your mailet container, which can sanitize expiration date headers.
+
+
 == Administrating user mailboxes
 
 === Creating a mailbox
diff --git a/server/apps/distributed-app/docs/modules/ROOT/partials/Expires.adoc b/server/apps/distributed-app/docs/modules/ROOT/partials/Expires.adoc
new file mode 100644
index 0000000000..c11ee5da7c
--- /dev/null
+++ b/server/apps/distributed-app/docs/modules/ROOT/partials/Expires.adoc
@@ -0,0 +1,34 @@
+=== Expires
+
+Sanitizes or adds an expiration date to a message, in the form of an `Expires`
+header (RFC 4021).
+
+The mailet can force an existing expiration date to be within the bounds
+given by `minAge`, `maxAge`, or both. `minAge` specifies the minimum time
+the date must lie in the future, while `maxAge` specifies a maximum.
+
+If a message has no expiration date, the mailet can add one according to
+the optional `defaultAge` parameter.
+
+All parameter values should be expressed in the following format: `Nunit`.
+`N` should be positive. `unit` could be either in the short form
+(`h`, `d`, `w`, `y` etc.), or in the long form (`hours`, days`, `weeks`,
+`months`, `years`). The default unit is `days`.
+
+Sample configuration:
+
+....
+<mailet match="All" class="Expires">
+    <minAge>12h</minAge>
+    <defaultAge>7d</defaultAge>
+    <maxAge>8w</maxAge>
+</mailet>
+....
+
+By itself the `Expires` header is informational only. But some variants of James
+will let you delete expired messages through the 
+xref:operate/webadmin.adoc#_administrating_messages[WebAdmin] interface:
+
+....
+curl -XDELETE http://ip:port/messages?byExpiresHeader
+....


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org