RetryingTelegramBotExecutor implementation (#102)

Author: ksilisk

telegram-bot-core/README.md

@@ -240,6 +240,24 @@ Core abstracts Telegram API execution behind:
 
 This allows multiple HTTP client implementations without leaking details into handlers.
 
+### **Retry support**
+
+Core also provides retry abstractions for Telegram Bot API calls:
+- RetryRule
+- RetryDelayStrategy
+- RetryingTelegramBotExecutor
+
+Retry behavior is intentionally split into small extension points:
+- rules decide whether a failed request may be retried
+- delay strategies decide how long to wait before the next attempt
+- the retrying executor decorates another TelegramBotExecutor
+
+Default reusable implementations include:
+- CompositeRetryRule
+- MaxAttemptsRetryRule
+- RetryableMethodsRetryRule
+- FixedRetryDelayStrategy
+
 ### **TelegramBotFileClient**
 
 TelegramBotFileClient provides a focused API for downloading files from Telegram via the Bot API.

telegram-bot-core/src/main/java/io/ksilisk/telegrambot/core/executor/retry/RetryDelayStrategy.java

@@ -0,0 +1,23 @@
+package io.ksilisk.telegrambot.core.executor.retry;
+
+import com.pengrad.telegrambot.request.BaseRequest;
+
+import java.time.Duration;
+
+/**
+ * Strategy interface that calculates the delay before the next retry attempt.
+ *
+ * <p>Implementations may use a fixed delay, exponential backoff,
+ * jitter, or any custom retry timing policy.
+ */
+public interface RetryDelayStrategy {
+    /**
+     * Returns the delay to wait before the next retry attempt.
+     *
+     * @param request the original Telegram Bot API request
+     * @param error the failure raised during request execution
+     * @param attempt the current attempt number, starting from {@code 1}
+     * @return the delay before the next retry attempt
+     */
+    Duration nextDelay(BaseRequest<?, ?> request, Throwable error, int attempt);
+}

telegram-bot-core/src/main/java/io/ksilisk/telegrambot/core/executor/retry/RetryRule.java

@@ -0,0 +1,29 @@
+package io.ksilisk.telegrambot.core.executor.retry;
+
+import com.pengrad.telegrambot.request.BaseRequest;
+import io.ksilisk.telegrambot.core.order.CoreOrdered;
+
+/**
+ * Strategy interface that decides whether a failed Telegram Bot API request
+ * should be retried.
+ *
+ * <p>Implementations typically evaluate the request type, thrown error,
+ * current attempt number, or any combination of these factors.
+ *
+ * <p>Rules are usually combined through a composite implementation.
+ * If a rule returns {@code false}, retry is rejected.
+ *
+ * <p>This contract also extends {@link CoreOrdered}, so multiple rules
+ * can be evaluated in a deterministic order.
+ */
+public interface RetryRule extends CoreOrdered {
+    /**
+     * Determines whether the given failed request should be retried.
+     *
+     * @param request the original Telegram Bot API request
+     * @param error the failure raised during request execution
+     * @param attempt the current attempt number, starting from {@code 1}
+     * @return {@code true} if retry is allowed, otherwise {@code false}
+     */
+    boolean shouldRetry(BaseRequest<?, ?> request, Throwable error, int attempt);
+}

telegram-bot-core/src/main/java/io/ksilisk/telegrambot/core/executor/retry/RetryingTelegramBotExecutor.java

@@ -0,0 +1,65 @@
+package io.ksilisk.telegrambot.core.executor.retry;
+
+import com.pengrad.telegrambot.request.BaseRequest;
+import com.pengrad.telegrambot.response.BaseResponse;
+import io.ksilisk.telegrambot.core.exception.request.TelegramRequestException;
+import io.ksilisk.telegrambot.core.executor.TelegramBotExecutor;
+import io.ksilisk.telegrambot.core.executor.retry.impl.CompositeRetryRule;
+
+import java.time.Duration;
+
+/**
+ * {@link TelegramBotExecutor} decorator that retries failed Telegram Bot API
+ * requests according to the configured {@link RetryRule} and
+ * {@link RetryDelayStrategy}.
+ *
+ * <p>This executor delegates request execution to another
+ * {@link TelegramBotExecutor}. When execution fails, it evaluates the retry
+ * rule and, if retry is allowed, waits for the configured delay before
+ * performing the next attempt.
+ *
+ * <p>This decorator does not define retry policy by itself. Retry decisions
+ * are fully delegated to the provided {@link RetryRule} implementation.
+ */
+public class RetryingTelegramBotExecutor implements TelegramBotExecutor {
+    private final TelegramBotExecutor delegate;
+    private final CompositeRetryRule retryRule;
+    private final RetryDelayStrategy retryDelayStrategy;
+
+    public RetryingTelegramBotExecutor(TelegramBotExecutor delegate,
+                                       CompositeRetryRule retryRule,
+                                       RetryDelayStrategy retryDelayStrategy) {
+        this.delegate = delegate;
+        this.retryRule = retryRule;
+        this.retryDelayStrategy = retryDelayStrategy;
+    }
+
+    @Override
+    public <T extends BaseRequest<T, R>, R extends BaseResponse> R execute(BaseRequest<T, R> request)
+            throws TelegramRequestException {
+        int attempt = 1;
+
+        while (true) {
+            try {
+                return delegate.execute(request);
+            } catch (Exception ex) {
+                if (!retryRule.shouldRetry(request, ex, attempt)) {
+                    throw ex;
+                }
+
+                Duration delay = retryDelayStrategy.nextDelay(request, ex, attempt);
+                sleep(delay);
+                attempt++;
+            }
+        }
+    }
+
+    private void sleep(Duration delay) {
+        try {
+            Thread.sleep(delay.toMillis());
+        } catch (InterruptedException ex) {
+            Thread.currentThread().interrupt();
+            throw new IllegalStateException("Retry sleep was interrupted", ex);
+        }
+    }
+}

telegram-bot-core/src/main/java/io/ksilisk/telegrambot/core/executor/retry/impl/CompositeRetryRule.java

@@ -0,0 +1,32 @@
+package io.ksilisk.telegrambot.core.executor.retry.impl;
+
+import com.pengrad.telegrambot.request.BaseRequest;
+import io.ksilisk.telegrambot.core.executor.retry.RetryRule;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.List;
+
+public class CompositeRetryRule implements RetryRule {
+    private static final Logger log = LoggerFactory.getLogger(CompositeRetryRule.class);
+
+    private final List<RetryRule> rules;
+
+    public CompositeRetryRule(List<RetryRule> rules) {
+        this.rules = List.copyOf(rules);
+    }
+
+    @Override
+    public boolean shouldRetry(BaseRequest<?, ?> request, Throwable error, int attempt) {
+        for (RetryRule rule : rules) {
+            if (!rule.shouldRetry(request, error, attempt)) {
+                log.debug("Retry rejected by [{}] for Telegram method [{}], attempt [{}]",
+                        rule.getClass().getSimpleName(),
+                        request.getMethod(),
+                        attempt);
+                return false;
+            }
+        }
+        return true;
+    }
+}

telegram-bot-core/src/main/java/io/ksilisk/telegrambot/core/executor/retry/impl/FixedRetryDelayStrategy.java

@@ -0,0 +1,23 @@
+package io.ksilisk.telegrambot.core.executor.retry.impl;
+
+import com.pengrad.telegrambot.request.BaseRequest;
+import io.ksilisk.telegrambot.core.executor.retry.RetryDelayStrategy;
+
+import java.time.Duration;
+
+/**
+ * {@link RetryDelayStrategy} that always returns the same fixed delay
+ * between retry attempts.
+ */
+public class FixedRetryDelayStrategy implements RetryDelayStrategy {
+    private final Duration delay;
+
+    public FixedRetryDelayStrategy(Duration delay) {
+        this.delay = delay;
+    }
+
+    @Override
+    public Duration nextDelay(BaseRequest<?, ?> request, Throwable error, int attempt) {
+        return delay;
+    }
+}

telegram-bot-core/src/main/java/io/ksilisk/telegrambot/core/executor/retry/impl/MaxAttemptsRetryRule.java

@@ -0,0 +1,21 @@
+package io.ksilisk.telegrambot.core.executor.retry.impl;
+
+import com.pengrad.telegrambot.request.BaseRequest;
+import io.ksilisk.telegrambot.core.executor.retry.RetryRule;
+
+/**
+ * {@link RetryRule} that rejects retry when the configured maximum number
+ * of attempts has been reached.
+ */
+public class MaxAttemptsRetryRule implements RetryRule {
+    private final int maxAttempts;
+
+    public MaxAttemptsRetryRule(int maxAttempts) {
+        this.maxAttempts = maxAttempts;
+    }
+
+    @Override
+    public boolean shouldRetry(BaseRequest<?, ?> request, Throwable error, int attempt) {
+        return attempt < maxAttempts;
+    }
+}

telegram-bot-core/src/main/java/io/ksilisk/telegrambot/core/executor/retry/impl/RetryableMethodsRetryRule.java

@@ -0,0 +1,32 @@
+package io.ksilisk.telegrambot.core.executor.retry.impl;
+
+import com.pengrad.telegrambot.request.BaseRequest;
+import io.ksilisk.telegrambot.core.executor.retry.RetryRule;
+
+import java.util.Set;
+
+/**
+ * {@link RetryRule} that allows retry only for Telegram Bot API methods
+ * explicitly configured as retryable.
+ *
+ * <p>This rule acts as a method allow-list. If the request method is not
+ * included in the configured retryable methods set, retry is rejected.
+ */
+public class RetryableMethodsRetryRule implements RetryRule {
+    private final Set<String> retryableMethods;
+
+    public RetryableMethodsRetryRule(Set<String> retryableMethods) {
+        this.retryableMethods = retryableMethods;
+    }
+
+    @Override
+    public boolean shouldRetry(BaseRequest<?, ?> request, Throwable error, int attempt) {
+        String method = request.getMethod();
+
+        if (method == null || method.isBlank()) {
+            return false;
+        }
+
+        return retryableMethods.contains(method);
+    }
+}

telegram-bot-core/src/main/java/io/ksilisk/telegrambot/core/properties/ClientRetryProperties.java

@@ -0,0 +1,72 @@
+package io.ksilisk.telegrambot.core.properties;
+
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+
+import java.time.Duration;
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * Configuration properties for Telegram Bot API client retry support.
+ */
+public class ClientRetryProperties {
+    private static final boolean DEFAULT_RETRY_ENABLED = false;
+    private static final int DEFAULT_MAX_ATTEMPTS = 3;
+    private static final Duration DEFAULT_RETRY_DELAY = Duration.ofSeconds(1);
+
+    /**
+     * Enables retry decorator for TelegramBotExecutor.
+     */
+    private boolean enabled = DEFAULT_RETRY_ENABLED;
+
+    /**
+     * Total number of attempts including the first one.
+     */
+    @Min(1)
+    @Max(Integer.MAX_VALUE)
+    private int maxAttempts = DEFAULT_MAX_ATTEMPTS;
+
+    /**
+     * Explicit allow-list of Bot API method names.
+     * Example: getMe, getFile, sendMessage
+     */
+    private Set<String> retryableMethods = new HashSet<>();
+
+    /**
+     * Initial delay before the next retry.
+     */
+    private Duration delay = DEFAULT_RETRY_DELAY;
+
+    public boolean getEnabled() {
+        return enabled;
+    }
+
+    public void setEnabled(boolean enabled) {
+        this.enabled = enabled;
+    }
+
+    public int getMaxAttempts() {
+        return maxAttempts;
+    }
+
+    public void setMaxAttempts(int maxAttempts) {
+        this.maxAttempts = maxAttempts;
+    }
+
+    public Set<String> getRetryableMethods() {
+        return retryableMethods;
+    }
+
+    public void setRetryableMethods(Set<String> retryableMethods) {
+        this.retryableMethods = retryableMethods;
+    }
+
+    public Duration getDelay() {
+        return delay;
+    }
+
+    public void setDelay(Duration delay) {
+        this.delay = delay;
+    }
+}