JAMES-3775 Documentation for RSpamD extension (#1113)

server/apps/distributed-app/docs/modules/ROOT/pages/architecture/index.adoc

@@ -19,7 +19,7 @@ patterns. ElasticSearch throughtput do not however match the one of Cassandra th
  * *RabbitMQ* enables James nodes of a same cluster to collaborate together. It is used to implement connected protocols,
 notification patterns as well as distributed resilient work queues and mail queue.
  * *Tika* (optional) enables text extraction from attachments, thus improving full text search results.
- * *SpamAssassin* (optional) can be used for Spam detection and user feedback is supported.
+ * *link:https://spamassassin.apache.org/[SpamAssassin] or link:https://rspamd.com/[RSpamD]* (optional) can be used for Spam detection and user feedback is supported.
 
 xref:architecture/consistency-model.adoc[This page] further details Distributed James consistency model.
 
@@ -206,7 +206,7 @@ operations on the system, like:
 * Current quota calculation
 * Message indexation with ElasticSearch
 * Mailbox annotations cleanup
-* Ham/spam reporting to SpamAssassin
+* Ham/spam reporting to Spam filtering system
 * …
 
 ==== Deleted Messages Vault

server/apps/distributed-app/docs/modules/ROOT/pages/configure/index.adoc

@@ -60,7 +60,7 @@ By omitting these files, no extra behaviour is added.
 ** xref:configure/listeners.adoc[*listeners.xml*] enables configuration of Mailbox Listeners link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/listeners.xml[example]
 ** xref:configure/extensions.adoc[*extensions.properties*] allows to extend James behaviour by loading your extensions in it link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/extensions.properties[example]
 ** xref:configure/jvm.adoc[*jvm.properties*] lets you specify additional system properties without cluttering your command line
-** xref:configure/spam.adoc[This page] documents Anti-Spam setup with SpamAssassin.
+** xref:configure/spam.adoc[This page] documents Anti-Spam setup with SpamAssassin, RSpamD.
 ** xref:configure/remote-delivery-error-handling.adoc[This page] proposes a simple strategy for RemoteDelivery error handling.
 ** xref:configure/collecting-contacts.adoc[This page] documents contact collection
 ** xref:configure/collecting-events.adoc[This page] documents event collection

server/apps/distributed-app/docs/modules/ROOT/pages/configure/listeners.adoc

@@ -52,6 +52,27 @@ Example:
 Please note that a `spamassassin.properties` file is needed. Read also
 xref:configure/spam.adoc[this page] for extra configuration required to support this feature.
 
+=== RSpamDListener
+
+Provides HAM/SPAM feedback to a RSpamD server depending on user actions.
+
+This MailboxListener is supported.
+
+Example:
+
+....
+<listeners>
+  <!-- ... -->
+  <listener>
+    <class>org.apache.james.rspamd.RSpamDListener</class>
+  </listener>
+</listeners>
+....
+
+Please note that a `rspamd.properties` file is needed. Read also
+xref:configure/spam.adoc[this page] for extra configuration required to support this feature.
+
+
 === MailboxOperationLoggingListener
 
 Provides more insights on mailbox operationsby logging them.

server/apps/distributed-app/docs/modules/ROOT/pages/configure/spam.adoc

@@ -9,23 +9,27 @@ Anti-Spam system can be configured via two main different mechanisms:
 == AntiSpam SMTP Hooks
 
 "FastFail" SMTP Hooks acts to reject before spooling
-on the SMTP level. SpamAssasin hook can be used as a fastfail hook, therefore
-SpamAssassin must run as a server on the same machine as the Apache James Server.
+on the SMTP level. The Spam detector hook can be used as a fastfail hook, therefore
+Spam filtering system must run as a server on the same machine as the Apache James Server.
 
 SMTP Hooks for non-existent users, DSN filter, domains with invalid MX record,
 can also be configured.
 
 *SpamAssassinHandler* (experimental) also enables to classify the messages as spam or not
-with an configurable score threshold (`0.0`, non configurable). Only a global database is supported. Per user spam
+with a configurable score threshold (`0.0`, non-configurable). Only a global database is supported. Per user spam
 detection is not supported by this hook.
 
 == AntiSpam Mailets
 
-* *SpamAssassin* Mailet is designed to classify the messages as spam or not
-with an configurable score threshold. Usually a message will only be
+James' repository provide two AntiSpam mailets: SpamAssassin and RSpamDScanner.
+We can select one in them for filtering spam mail.
+
+* *SpamAssassin and RSpamDScanner* Mailet is designed to classify the messages as spam or not
+with a configurable score threshold. Usually a message will only be
 considered as spam if it matches multiple criteria; matching just a single test
 will not usually be enough to reach the threshold. Note that this mailet is executed on a per-user basis.
 
+=== SpamAssassin
 Here is an example of mailet pipeline conducting out SpamAssassin execution:
 
 ....
@@ -55,7 +59,7 @@ the table. Also, the correct approach is to send the original spam or non-spam
 as an attachment to another message sent to the feeder in order to avoid bias from the
 current sender's email header.
 
-== Feedback for SpamAssassin
+=== Feedback for SpamAssassin
 
 If enabled, the `SpamAssassinListener` will asynchronously report users mails moved to the `Spam` mailbox as Spam,
 and other mails as `Ham`, effectively populating the user database for per user spam detection. This enables a per-user
@@ -87,4 +91,46 @@ Example:
     <async>true</async>
   </listener>
 </listeners>
-....
+....
+
+== RSpamD
+
+The RSpamD extension (optional) requires an extra configuration file `rspamd.properties` to configure RSpamd connection
+
+.rspamd.properties content
+|===
+| Property name | explanation
+
+| rSpamDUrl
+| URL defining the RSpamD's server. Eg: http://rspamd:11334
+
+| rSpamDPassword
+| Password for pass authentication when request to RSpamD's server. Eg: admin
+|===
+
+
+Here is an example of mailet pipeline conducting out RSpamDScanner execution:
+
+....
+<mailet match="All" class="org.apache.james.rspamd.RSpamDScanner">
+</mailet>
+<mailet match="IsMarkedAsSpam=org.apache.james.rspamd.status" class="WithStorageDirective">
+    <targetFolderName>Spam</targetFolderName>
+</mailet>
+....
+
+=== Feedback for RSpamD
+If enabled, the `RSpamDListener` will base on the Mailbox event to detect the message is a spam or not, then James will send report `spam` or `ham` to RSpamD
+The RSpamD listener needs to explicitly be registered with xref:configure/listeners.adoc[listeners.xml].
+
+Example:
+
+....
+<listeners>
+    <listener>
+        <class>org.apache.james.rspamd.RSpamDListener</class>
+    </listener>
+</listeners>
+....
+
+For more detail about how to use RSpamD's extension: `third-party/rspamd/index.md`

third-party/rspamd/index.md

@@ -0,0 +1,50 @@
+# James' extensions for RSpamD
+
+This module is for developing and delivering extensions to James for the [RSpamD](https://rspamd.com/) (the spam filtering system) 
+
+## How to run
+
+- The RSpamD extension requires an extra configuration file `rspamd.properties` to configure RSpamd connection
+Configuration parameters:
+    - `rSpamDUrl` : URL defining the RSpamD's server. Eg: http://rspamd:11334
+    - `rSpamDPassword` : Password for pass authentication when request to RSpamD's server. Eg: admin
+
+- Declare the `extensions.properties` for this module.
+
+```
+guice.extension.module=org.apache.james.rspamd.module.RSpamDModule
+guice.extension.task=org.apache.james.rspamd.module.RSpamDTaskExtensionModule
+```
+
+- Declare the RSpamD mailbox listeners in `listeners.xml`. Eg:
+
+```
+<listener>
+    <class>org.apache.james.rspamd.RSpamDListener</class>
+</listener>
+```
+
+- Declare the RSpamD mailet for custom mail processing. Mailet pipeline Eg:
+
+```
+<mailet match="All" class="org.apache.james.rspamd.RSpamDScanner"></mailet>
+<mailet match="IsMarkedAsSpam=org.apache.james.rspamd.status" class="WithStorageDirective">
+    <targetFolderName>Spam</targetFolderName>
+</mailet>
+```
+
+- Declare the webadmin for RSpamD in `webadmin.properties`
+
+```
+extensions.routes=org.apache.james.rspamd.route.FeedMessageRoute
+```
+How to use admin endpoint, see more at [Additional webadmin endpoints](README.md)
+
+- Docker compose file example: [docker-compose.yml](docker-compose.yml) or [docker-compose-distributed.yml](docker-compose-distributed.yml)
+- The sample-configuration: [sample-configuration](sample-configuration)
+- For running docker-compose, first compile this project 
+
+```
+mvn clean install -DskipTests
+```
+then run it: `docker-compose up`