rate-limit

core/build.gradle.kts

@@ -20,6 +20,7 @@ codegen {
 
 dependencies {
     api(VertxLibs.core)
+    api(project(":ratelimit:api"))
     compileOnly(JacksonLibs.annotations)
     compileOnly(JacksonLibs.databind)
     compileOnly(UtilLibs.jetbrainsAnnotations)

core/src/main/java/io/github/zero88/schedulerx/impl/AbstractScheduler.java

@@ -34,6 +34,8 @@
 import io.github.zero88.schedulerx.trigger.TriggerCondition.ReasonCode;
 import io.github.zero88.schedulerx.trigger.TriggerContext;
 import io.github.zero88.schedulerx.trigger.TriggerEvaluator;
+import io.github.zero88.schedulerx.trigger.policy.TriggerRateLimitConfig;
+import io.github.zero88.schedulerx.trigger.policy.TriggerRateLimitRepository;
 import io.github.zero88.schedulerx.trigger.rule.TriggerRule;
 import io.vertx.core.Future;
 import io.vertx.core.Promise;
@@ -69,6 +71,8 @@ public abstract class AbstractScheduler<IN, OUT, T extends Trigger>
     private boolean didStart = false;
     private boolean didTriggerValidation = false;
     private IllegalArgumentException invalidTrigger;
+    private Object policyKey;
+    private TriggerRateLimitRepository repository;
 
     protected AbstractScheduler(Vertx vertx, TimeClock clock, SchedulingMonitor<OUT> monitor, Job<IN, OUT> job,
                                 JobData<IN> jobData, TimeoutPolicy timeoutPolicy, T trigger,
@@ -108,14 +112,23 @@ protected AbstractScheduler(Vertx vertx, TimeClock clock, SchedulingMonitor<OUT>
     @Override
     @SuppressWarnings({ "java:S1193", "unchecked" })
     public final @NotNull T trigger() {
+        if (didTriggerValidation) {
+            if (invalidTrigger == null) { return trigger; }
+            throw invalidTrigger;
+        }
         lock.lock();
         try {
-            if (didTriggerValidation) {
-                if (invalidTrigger == null) { return trigger; }
-                throw invalidTrigger;
-            }
             try {
-                return (T) this.trigger.validate();
+                final T theTrigger = (T) this.trigger.validate();
+                final TriggerRateLimitConfig rateLimitConfig = theTrigger.ratelimitConfig();
+                if (rateLimitConfig != null) {
+                    if (rateLimitConfig.keyGenerator().requireExternalKey() && jobData().externalId() == null) {
+                        throw new IllegalArgumentException(
+                            "The external id is required to make rate-limit policy works properly");
+                    }
+                    this.policyKey = rateLimitConfig.keyGenerator().generate(theTrigger, jobData().externalId());
+                }
+                return theTrigger;
             } catch (Exception ex) {
                 if (ex instanceof IllegalArgumentException) {
                     this.invalidTrigger = (IllegalArgumentException) ex;

core/src/main/java/io/github/zero88/schedulerx/trigger/Trigger.java

@@ -7,6 +7,7 @@
 import org.jetbrains.annotations.Nullable;
 
 import io.github.zero88.schedulerx.Job;
+import io.github.zero88.schedulerx.trigger.policy.TriggerRateLimitConfig;
 import io.github.zero88.schedulerx.trigger.repr.TriggerRepresentation;
 import io.github.zero88.schedulerx.trigger.repr.TriggerRepresentationServiceLoader;
 import io.github.zero88.schedulerx.trigger.rule.TriggerRule;
@@ -35,6 +36,18 @@ public interface Trigger extends HasTriggerType, TriggerRepresentation {
         return TriggerRule.NOOP;
     }
 
+    /**
+     * Defines the rate-limit configuration
+     *
+     * @return the rate-limit configuration or {@code null} means restrict one execution per trigger that can be run
+     *     in a certain time
+     * @see TriggerRateLimitConfig
+     * @since 2.0.0
+     */
+    default @Nullable TriggerRateLimitConfig ratelimitConfig() {
+        return null;
+    }
+
     /**
      * Do validate trigger in runtime.
      *
@@ -73,6 +86,7 @@ public interface Trigger extends HasTriggerType, TriggerRepresentation {
     default JsonObject toJson() {
         JsonObject json = JsonObject.of("type", type());
         if (rule() != TriggerRule.NOOP) { json.put("rule", rule()); }
+        if (ratelimitConfig() != null) { json.put("ratelimit", ratelimitConfig().toJson()); }
         return json;
     }
 

core/src/main/java/io/github/zero88/schedulerx/trigger/TriggerCondition.java

@@ -73,6 +73,7 @@ class ReasonCode {
         public static final String STOP_BY_JOB = "ForceStop";
         public static final String STOP_BY_CONFIG = "StopByTriggerConfig";
         public static final String JOB_IS_RUNNING = "JobIsRunning";
+        public static final String RATE_LIMIT = "RateLimit";
         public static final String UNEXPECTED_ERROR = "UnexpectedError";
 
         private ReasonCode() { }

core/src/main/java/io/github/zero88/schedulerx/trigger/policy/TriggerRateLimitConfig.java

@@ -0,0 +1,17 @@
+package io.github.zero88.schedulerx.trigger.policy;
+
+import org.jetbrains.annotations.NotNull;
+
+import io.github.zero88.ratelimit.RateLimitConfig;
+
+/**
+ * A rate-limit mechanism to control the number of execution rounds of one trigger can be run in parallel in a certain
+ * period.
+ *
+ * @since 2.0.0
+ */
+public interface TriggerRateLimitConfig extends RateLimitConfig {
+
+    @NotNull TriggerRateLimitKeyGenerator keyGenerator();
+
+}

core/src/main/java/io/github/zero88/schedulerx/trigger/policy/TriggerRateLimitHelper.java

@@ -0,0 +1,7 @@
+package io.github.zero88.schedulerx.trigger.policy;
+
+public interface TriggerRateLimitHelper {
+
+    boolean isUnlimited();
+
+}

core/src/main/java/io/github/zero88/schedulerx/trigger/policy/TriggerRateLimitKeyGenerator.java

@@ -0,0 +1,26 @@
+package io.github.zero88.schedulerx.trigger.policy;
+
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import io.github.zero88.ratelimit.RateLimitKeyGenerator;
+import io.github.zero88.schedulerx.JobData;
+import io.github.zero88.schedulerx.trigger.Trigger;
+
+public interface TriggerRateLimitKeyGenerator extends RateLimitKeyGenerator {
+
+    boolean requireExternalKey();
+
+    /**
+     * Generate rate-limit policy key for the trigger
+     *
+     * @param trigger     the trigger.
+     * @param externalKey the external trigger key. See {@link JobData#externalId()}
+     * @return the unique key in the rate-limit system
+     * @apiNote to identify a trigger to apply rate-limiting, the concrete key generator can combine some properties
+     *     such as {@code externalKey}, {@code triggerType} and/or {@code triggerContextInfo}.
+     * @see Trigger
+     */
+    @NotNull Object generate(@NotNull Trigger trigger, @Nullable Object externalKey);
+
+}

core/src/main/java/io/github/zero88/schedulerx/trigger/policy/TriggerRateLimitRepository.java

@@ -0,0 +1,16 @@
+package io.github.zero88.schedulerx.trigger.policy;
+
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import io.github.zero88.ratelimit.RateLimitPolicyRepository;
+import io.github.zero88.ratelimit.RateLimitResult;
+import io.github.zero88.schedulerx.trigger.TriggerContext;
+import io.vertx.core.Future;
+
+public interface TriggerRateLimitRepository extends RateLimitPolicyRepository<TriggerContext> {
+
+    @NotNull Future<RateLimitResult<TriggerContext>> increase(@NotNull Object policyKey,
+                                                              @Nullable TriggerContext eventContext);
+
+}

ratelimit/README.md

@@ -0,0 +1,2 @@
+# Rate-limit
+

ratelimit/api/build.gradle.kts

@@ -0,0 +1,10 @@
+oss {
+    title.set("The rate-limit API")
+}
+
+dependencies {
+    api(VertxLibs.core)
+    compileOnly(JacksonLibs.annotations)
+    compileOnly(JacksonLibs.databind)
+    compileOnly(UtilLibs.jetbrainsAnnotations)
+}

ratelimit/api/gradle.properties

@@ -0,0 +1,3 @@
+# Project properties --------------------------
+title=The rate-limit API
+description=The rate-limit API

ratelimit/api/src/main/java/io/github/zero88/ratelimit/Connector.java

@@ -0,0 +1,10 @@
+package io.github.zero88.ratelimit;
+
+/**
+ * Represents for a thing which links two or more thing together
+ */
+public interface Connector {
+
+    ConnectorConfig config();
+
+}

ratelimit/api/src/main/java/io/github/zero88/ratelimit/ConnectorConfig.java

@@ -0,0 +1,3 @@
+package io.github.zero88.ratelimit;
+
+public interface ConnectorConfig { }

ratelimit/api/src/main/java/io/github/zero88/ratelimit/LimitConfig.java

@@ -0,0 +1,42 @@
+package io.github.zero88.ratelimit;
+
+import java.time.Duration;
+
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents for the rate-limit configuration that enables you to manage the event traffic for your specific purpose,
+ * such as limit the access to REST APIs, throttle event-bus messages on specific address.
+ * <p/>
+ * When the first event is going to start. This event fixes the time window. Each event consumes quota from the
+ * current window until the time expires. When quota is exhausted, the resulting action depends on the policy:
+ * <ul>
+ * <li>Rate limiting rejects the event.</li>
+ * <li>Throttling queues the event for retry.</li>
+ * </ul>
+ * When the time window closes, quota is reset and a new window of the same fixed size starts.
+ *
+ * @since 1.0.0
+ */
+public interface LimitConfig {
+
+    /**
+     * @return The maximum number of event that can be run in parallel during the sliding time window in
+     *     {@link #timeWindow()}
+     */
+    int limit();
+
+    /**
+     * @return the sliding time window during which the number of allowed events should not exceed the value
+     *     specified in {@link #limit()}
+     */
+    @NotNull Duration timeWindow();
+
+    /**
+     * @return The throttle configuration
+     * @see ThrottleConfig
+     */
+    @Nullable ThrottleConfig throttleConfig();
+
+}

ratelimit/api/src/main/java/io/github/zero88/ratelimit/RateLimitAction.java

@@ -0,0 +1,19 @@
+package io.github.zero88.ratelimit;
+
+/**
+ * @since 1.0.0
+ */
+public enum RateLimitAction {
+    /**
+     * Accept to process new event
+     */
+    ACCEPTED,
+    /**
+     * Reject to process new event
+     */
+    REJECTED,
+    /**
+     * Move the new event into queue for retry later
+     */
+    THROTTLING
+}

ratelimit/api/src/main/java/io/github/zero88/ratelimit/RateLimitConfig.java

@@ -0,0 +1,42 @@
+package io.github.zero88.ratelimit;
+
+import java.time.Duration;
+import java.util.List;
+
+import org.jetbrains.annotations.NotNull;
+
+import io.vertx.core.json.JsonObject;
+
+/**
+ * A rate-limit mechanism to control the maximum number of events can be processed in parallel in a certain period.
+ *
+ * @since 1.0.0
+ */
+public interface RateLimitConfig {
+
+    /**
+     * Declares the set of limit configuration
+     *
+     * @return the limit configuration
+     * @see LimitConfig
+     */
+    @NotNull List<LimitConfig> limits();
+
+    /**
+     * Declares a request timeout when increasing the rate-limit counter
+     *
+     * @return the timeout
+     */
+    @NotNull Duration timeout();
+
+    /**
+     * Declares the generator to generate the rate-limit policy key.
+     *
+     * @return the key generator
+     * @see RateLimitKeyGenerator
+     */
+    @NotNull RateLimitKeyGenerator keyGenerator();
+
+    @NotNull JsonObject toJson();
+
+}

ratelimit/api/src/main/java/io/github/zero88/ratelimit/RateLimitException.java

@@ -0,0 +1,13 @@
+package io.github.zero88.ratelimit;
+
+public class RateLimitException extends RuntimeException {
+
+    private final RateLimitResult<Object> result;
+
+    public RateLimitException(RateLimitResult<Object> result) { this.result = result; }
+
+    public RateLimitResult<Object> getResult() {
+        return result;
+    }
+
+}

ratelimit/api/src/main/java/io/github/zero88/ratelimit/RateLimitKeyGenerator.java

@@ -0,0 +1,14 @@
+package io.github.zero88.ratelimit;
+
+/**
+ * Represents for a generator to generate a rate-limit policy key.
+ * <p/>
+ * The rate-limit policy key is a unique id of the thing for which to apply the rate-limit in one rate-limit policy
+ * repository,
+ *
+ * @since 1.0.0
+ * @see RateLimitPolicyRepository
+ */
+public interface RateLimitKeyGenerator {
+
+}

ratelimit/api/src/main/java/io/github/zero88/ratelimit/RateLimitPolicy.java

@@ -0,0 +1,42 @@
+package io.github.zero88.ratelimit;
+
+import org.jetbrains.annotations.NotNull;
+
+import io.vertx.core.Future;
+import io.vertx.core.Vertx;
+
+/**
+ * A rate-limit mechanism to control the maximum number of events can be processed in parallel in a certain period.
+ *
+ * @since 1.0.0
+ */
+public interface RateLimitPolicy {
+
+    @NotNull Object policeKey();
+
+    @NotNull RateLimitConfig config();
+
+    /**
+     * Set up the rate-limit policy
+     *
+     * @param vertx Vertx
+     * @return a reference to this for fluent API
+     */
+    @NotNull Future<RateLimitPolicy> initialize(@NotNull Vertx vertx);
+
+    Future<Void> destroy();
+
+    /**
+     * Increase the event counter before new event is processed by the system
+     *
+     * @return a rate-limit result
+     * @see RateLimitResult
+     */
+    @NotNull <T> Future<RateLimitResult<T>> increase(T context);
+
+    /**
+     * Decrease the event counter when the event is finished
+     */
+    void decrease();
+
+}