GH-1153 Rework delay system with per-entry Instant TTL

eternalcore-api/src/main/java/com/eternalcode/core/delay/DefaultDelay.java

@@ -0,0 +1,63 @@
+package com.eternalcode.core.delay;
+
+import java.time.Duration;
+import java.time.Instant;
+
+/**
+ * Represents a delay mechanism with a predefined default duration.
+ * <p>
+ * A key can be marked either with the default duration or with a custom one.
+ *
+ * @param <T> the type of key used to identify the delay
+ */
+public interface DefaultDelay<T> {
+
+    /**
+     * Marks a delay for the given key using the predefined default duration.
+     *
+     * @param key the key to mark
+     */
+    void markDelay(T key);
+
+    /**
+     * Removes any existing delay for the given key.
+     *
+     * @param key the key to unmark
+     */
+    void unmarkDelay(T key);
+
+    /**
+     * Checks if the given key currently has an active delay.
+     *
+     * @param key the key to check
+     * @return true if the key has a delay, false otherwise
+     */
+    boolean hasDelay(T key);
+
+    /**
+     * Returns the remaining duration of the delay for the given key.
+     * Returns {@code Duration.ZERO} if no active delay exists.
+     *
+     * @param key the key to check
+     * @return remaining duration, or {@code Duration.ZERO} if none
+     */
+    Duration getRemaining(T key);
+
+    /**
+     * Returns the expiration time of the delay for the given key.
+     * Returns {@code null} if no active delay exists.
+     *
+     * @param key the key to check
+     * @return expiration instant, or {@code null} if none
+     */
+    Instant getExpireAt(T key);
+
+    /**
+     * Extends the delay for the given key by the specified extra duration.
+     * If no active delay exists, a new one is created starting now.
+     *
+     * @param key   the key to extend
+     * @param extra the duration to add
+     */
+    void extendDelay(T key, Duration extra);
+}

eternalcore-api/src/main/java/com/eternalcode/core/delay/Delay.java

@@ -1,50 +1,61 @@
 package com.eternalcode.core.delay;
 
-import com.google.common.cache.Cache;
-import com.google.common.cache.CacheBuilder;
-
 import java.time.Duration;
-import java.time.Instant;
-import java.util.function.Supplier;
-
-public class Delay<T> {
-
-    private final Cache<T, Instant> delays;
 
-    private final Supplier<Duration> delaySettings;
-
-    public Delay(Supplier<Duration> delayProvider) {
-        this.delaySettings = delayProvider;
-
-        this.delays = CacheBuilder.newBuilder()
-            .expireAfterWrite(delayProvider.get())
-            .build();
+/**
+ * Factory class for creating delay instances.
+ * <p>
+ * Naming convention:
+ * - withDefault(...) -> DefaultDelay (uses predefined Duration)
+ * - explicit(...) -> ExplicitDelay (requires explicit Duration each time)
+ */
+public final class Delay {
+
+    private Delay() {
+        throw new UnsupportedOperationException("Utility class - do not instantiate");
     }
 
-    public void markDelay(T key, Duration delay) {
-        this.delays.put(key, Instant.now().plus(delay));
+    /**
+     * Creates a DefaultDelay with the default cache size.
+     *
+     * @param defaultDelay the default duration used for delays
+     * @param <T> the key type
+     * @return DefaultDelay instance
+     */
+    public static <T> DefaultDelay<T> withDefault(Duration defaultDelay) {
+        return new GuavaDefaultDelay<>(defaultDelay);
     }
 
-    public void markDelay(T key) {
-        this.markDelay(key, this.delaySettings.get());
+    /**
+     * Creates a DefaultDelay with a custom maximum cache size.
+     *
+     * @param defaultDelay the default duration used for delays
+     * @param maximumSize maximum number of entries in the cache
+     * @param <T> the key type
+     * @return DefaultDelay instance
+     */
+    public static <T> DefaultDelay<T> withDefault(Duration defaultDelay, long maximumSize) {
+        return new GuavaDefaultDelay<>(defaultDelay, maximumSize);
     }
 
-    public void unmarkDelay(T key) {
-        this.delays.invalidate(key);
+    /**
+     * Creates an ExplicitDelay with the default cache size.
+     *
+     * @param <T> the key type
+     * @return ExplicitDelay instance
+     */
+    public static <T> ExplicitDelay<T> explicit() {
+        return new GuavaExplicitDelay<>();
     }
 
-    public boolean hasDelay(T key) {
-        Instant delayExpireMoment = this.getDelayExpireMoment(key);
-
-        return Instant.now().isBefore(delayExpireMoment);
+    /**
+     * Creates an ExplicitDelay with a custom maximum cache size.
+     *
+     * @param maximumSize maximum number of entries in the cache
+     * @param <T> the key type
+     * @return ExplicitDelay instance
+     */
+    public static <T> ExplicitDelay<T> explicit(long maximumSize) {
+        return new GuavaExplicitDelay<>(maximumSize);
     }
-
-    public Duration getDurationToExpire(T key) {
-        return Duration.between(Instant.now(), this.getDelayExpireMoment(key));
-    }
-
-    private Instant getDelayExpireMoment(T key) {
-        return this.delays.asMap().getOrDefault(key, Instant.MIN);
-    }
-
 }

eternalcore-api/src/main/java/com/eternalcode/core/delay/ExplicitDelay.java

@@ -0,0 +1,62 @@
+package com.eternalcode.core.delay;
+
+import java.time.Duration;
+import java.time.Instant;
+
+/**
+ * Represents a delay mechanism where each key must be marked with an explicit duration.
+ *
+ * @param <T> the type of key used to identify the delay
+ */
+public interface ExplicitDelay<T> {
+
+    /**
+     * Marks a delay for the given key with the specified duration.
+     *
+     * @param key the key to mark
+     * @param duration the duration of the delay
+     */
+    void markDelay(T key, Duration duration);
+
+    /**
+     * Removes any existing delay for the given key.
+     *
+     * @param key the key to unmark
+     */
+    void unmarkDelay(T key);
+
+    /**
+     * Checks if the given key currently has an active delay.
+     *
+     * @param key the key to check
+     * @return true if the key has a delay, false otherwise
+     */
+    boolean hasDelay(T key);
+
+    /**
+     * Returns the remaining duration of the delay for the given key.
+     * Returns {@code Duration.ZERO} if no active delay exists.
+     *
+     * @param key the key to check
+     * @return remaining duration, or {@code Duration.ZERO} if none
+     */
+    Duration getRemaining(T key);
+
+    /**
+     * Returns the expiration time of the delay for the given key.
+     * Returns {@code null} if no active delay exists.
+     *
+     * @param key the key to check
+     * @return expiration instant, or {@code null} if none
+     */
+    Instant getExpireAt(T key);
+
+    /**
+     * Extends the delay for the given key by the specified extra duration.
+     * If no active delay exists, a new one is created starting now.
+     *
+     * @param key the key to extend
+     * @param extra the duration to add
+     */
+    void extendDelay(T key, Duration extra);
+}

eternalcore-api/src/main/java/com/eternalcode/core/delay/GuavaDefaultDelay.java

@@ -0,0 +1,42 @@
+package com.eternalcode.core.delay;
+
+import java.time.Duration;
+
+/**
+ * DefaultDelay implementation backed by {@link GuavaDelay} using Guava cache.
+ * <p>
+ * Each key marked without explicit duration uses a predefined default delay.
+ *
+ * @param <T> the type of key used to identify the delay
+ */
+final class GuavaDefaultDelay<T> extends GuavaDelay<T> implements DefaultDelay<T> {
+
+    private final Duration defaultDelay;
+
+    /**
+     * Creates a new DefaultDelay with the specified default duration
+     * and the default maximum cache size.
+     *
+     * @param defaultDelay the default delay duration, must be positive
+     */
+    GuavaDefaultDelay(Duration defaultDelay) {
+        this(defaultDelay, DEFAULT_MAXIMUM_SIZE);
+    }
+
+    /**
+     * Creates a new DefaultDelay with the specified default duration
+     * and a custom maximum cache size.
+     *
+     * @param defaultDelay the default delay duration, must be positive
+     * @param maximumSize  maximum number of entries allowed in the cache
+     */
+    GuavaDefaultDelay(Duration defaultDelay, long maximumSize) {
+        super(defaultDelay, maximumSize);
+        this.defaultDelay = defaultDelay;
+    }
+
+    @Override
+    public void markDelay(T key) {
+        putDelay(key, this.defaultDelay);
+    }
+}