This is an automated email from the ASF dual-hosted git repository. btellier pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 4b32f130d7afb9de1cfe5b9c21f9ec7ecb113b6e Author: Tung Van TRAN <[email protected]> AuthorDate: Fri Feb 11 12:42:08 2022 +0700 JAMES-3711 Document for Requeue mailet --- .../docs/modules/ROOT/pages/extending/index.adoc | 6 +++- .../apache/james/transport/mailets/Requeue.java | 28 +++++++++++++++++ server/mailet/rate-limiter/README.adoc | 35 +++++++++++++++++++++- 3 files changed, 67 insertions(+), 2 deletions(-) diff --git a/server/apps/distributed-app/docs/modules/ROOT/pages/extending/index.adoc b/server/apps/distributed-app/docs/modules/ROOT/pages/extending/index.adoc index fc41d97..67bd512 100644 --- a/server/apps/distributed-app/docs/modules/ROOT/pages/extending/index.adoc +++ b/server/apps/distributed-app/docs/modules/ROOT/pages/extending/index.adoc @@ -157,4 +157,8 @@ size, size * recipients) size, size * recipients) Depending on their positions and the matcher they are being combined with, those rate limiting rules could be applied to -submitted emails, received emails or emitted email being relayed to third parties. \ No newline at end of file +submitted emails, received emails or emitted email being relayed to third parties. + +==== Throttling +Can use combine with `Requeue` mailet for a throttler by re-enqueue mail. +link:https://github.com/apache/james-project/tree/master/server/mailet/rate-limiter#throttling[link] diff --git a/server/mailet/mailets/src/main/java/org/apache/james/transport/mailets/Requeue.java b/server/mailet/mailets/src/main/java/org/apache/james/transport/mailets/Requeue.java index 59525a1..19288b8 100644 --- a/server/mailet/mailets/src/main/java/org/apache/james/transport/mailets/Requeue.java +++ b/server/mailet/mailets/src/main/java/org/apache/james/transport/mailets/Requeue.java @@ -39,6 +39,34 @@ import org.apache.mailet.base.GenericMailet; import com.github.fge.lambdas.Throwing; import com.google.common.base.Preconditions; +/** + * <p><b>Requeue</b> puts back the email in a queue. + * It can be used for throttling when combined with rate limiting mailet. {@link org.apache.james.transport.mailets.PerSenderRateLimit}</p> + * + * <ul>Here are supported configuration parameters: + * <li><b>queue</b>: a Mail Queue name (optional, default to spool).</li> + * <li><b>processor</b>: a target processor (optional, defaults to root).</li> + * <li><b>delay</b>: a delay when en-queueing mail (optional, defaults to none). Supported units include: s (second), m (minute), h (hour), d (day).</li> + * <li><b>consume</b>: a boolean. true will consume the mail: no further processing would be done on the mail (default) + * while false will continue the processing of the email in addition to the requeue operation, which effectively duplicates the email.</li> + * </ul> + * + * <p>For instance, to apply all the examples given above:</p> + * + * <pre><code> + * <mailet matcher="All" class="Requeue"> + * <queue>spool</queue> + * <processor>root</processor> + * <delay>2h</delay> + * <consume>true</consume> + * </mailet> + * </code></pre> + * + * <p>Note that this is a naive approach: if you have a large number of emails (say N) submitted at once, + * you would need O(N) re-queues to eventually send all your emails, + * where the constant is the number of mail allowed over the time window. + * So this gives an overall complexity of O(N2). </p> + */ public class Requeue extends GenericMailet { private final MailQueueFactory<?> mailQueueFactory; diff --git a/server/mailet/rate-limiter/README.adoc b/server/mailet/rate-limiter/README.adoc index 2f18b16..4e6d520 100644 --- a/server/mailet/rate-limiter/README.adoc +++ b/server/mailet/rate-limiter/README.adoc @@ -148,4 +148,37 @@ For instance, to apply all the examples given above: </mailet> ---- -When the rate is exceeded, a new mail with recipients that are exceeded recipients will be moved to processor *tooMuchMails* which send a bounce message notifies that the rate limit exceeded. \ No newline at end of file +When the rate is exceeded, a new mail with recipients that are exceeded recipients will be moved to processor *tooMuchMails* which send a bounce message notifies that the rate limit exceeded. + +=== Throttling + +It's possible to combine RateLimit mailet with `Requeue` mailet to allow for a (very basic) throttler and smoothing the traffic to the expected rate. +The throttler work by re-enqueue mail. + +The supported configuration parameters for the `Requeue` mailet are: + +- *queue*: a Mail Queue name (optional, default to spool). +- *processor*: a target processor (optional, defaults to root). +- *delay*: a delay when en-queueing mail (optional, defaults to none). Supported units include: s (second), m (minute), h (hour), d (day). +- *consume*: a processor to which current email should be redirected to (optional, defaults to ghost). + +For instance, throttle senders to 10 mails per hour, smoothing the traffic as required: + +---- +<processor name="root"> + <mailet matcher="All" class="PerSenderRateLimit"> + <duration>1h</duration> + <count>10</count> + <exceededProcessor>tooMuchEmails</exceededProcessor> + </mailet> + <!-- Go to transport for instance --> +</processor> + +<processor name="tooMuchEmails"> + <mailet matcher="All" class="Requeue"> + <queue>spool</spool> + <processor>root</processor> + <delay>1h</delay> + </mailet> +</processor> +---- \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
