feat(events): opt-in async @eventhandler retries with backoff (#108) (#390)

* feat(events): opt-in async @eventhandler retries with backoff (#108)

* refactor(events): single-literal retry emit; parameterize the invalid-retry compile-error tests (#108)

---------

Co-authored-by: Tomáš Samek <jerry.samek@gmail.com>

Author: tomas-samek

docs/events.md

@@ -143,6 +143,26 @@ If the handler runs longer than the budget, its worker thread is interrupted, th
 - **Async-only:** `timeout` requires `async = true`. A timeout on a synchronous handler is a **compile-time error** — a sync handler runs on the publisher's thread (and its unit-of-work scope), which cannot be preempted; time-boxing requires the off-thread, own-scope execution that `async = true` provides.
 - **Best-effort:** interruption can only stop a handler that respects `Thread.interrupt()` (e.g. is blocked on I/O or checks the flag). A handler running a tight uninterruptible loop will keep going — the timeout is reported, but Java cannot force-stop the thread.
 
+### Retries with backoff
+
+An async handler can retry on failure with `retries` + `backoff` + `backoffStrategy`:
+
+```java
+@EventHandler(async = true, retries = 3, backoff = "PT0.1S", backoffStrategy = BackoffStrategy.EXPONENTIAL)
+public void onPayment(PaymentEvent event) {
+    // re-invoked up to 3 times if it throws; 100ms, then 200ms, then 400ms apart
+}
+```
+
+`retries = 3` means one initial call plus up to three retries (four attempts total). The first attempt that returns normally wins — no error is routed. Once the budget is exhausted, a **single** `EventHandlerError` is routed whose `attempts()` is the total number of attempts made (here, `4`). Backoff is `FIXED` (constant delay) or `EXPONENTIAL` (doubling) and is *scheduled*, so it never ties up an executor thread while waiting.
+
+- **Opt-in:** the default is no retries (`retries = 0`).
+- **Async-only:** `retries` requires `async = true` (a **compile-time error** otherwise) — retrying waits for the backoff between attempts, which would block the publisher's thread.
+- **ISO-8601 backoff:** `backoff` is a `Duration` string (`"PT0.1S"`), like `timeout`.
+- **Composes with `timeout`:** if both are set, each attempt is time-boxed and a timed-out attempt counts as a failed attempt to be retried.
+- **Errors are not retried:** an `Error` (vs an `Exception`) stops the loop and is logged, never retried.
+- **Idempotency is your responsibility** — a retried handler runs its side effects more than once. Make the work safe to repeat.
+
 ## Graceful shutdown drain
 
 When `Container.shutdown()` runs, in-flight async event handlers are allowed to

tiko-api/src/main/java/io/tiko/EventHandlerError.java

@@ -3,9 +3,23 @@
 /**
  * Error context raised when an {@code @EventHandler} method throws — sync or async.
  *
- * @param handler identifies which handler method threw
- * @param event   the event instance the handler was processing
- * @param cause   the throwable thrown by the handler ({@code CompletionException}
- *                already unwrapped to the user's original throwable)
+ * @param handler  identifies which handler method threw
+ * @param event    the event instance the handler was processing
+ * @param cause    the throwable thrown by the handler ({@code CompletionException}
+ *                 already unwrapped to the user's original throwable)
+ * @param attempts the number of times the handler was invoked before this error was raised —
+ *                 {@code 1} for a non-retrying handler, or the exhausted total for a handler with
+ *                 {@code @EventHandler(retries = ...)} (#108)
  */
-public record EventHandlerError(EventHandlerInfo handler, Object event, Throwable cause) implements ErrorContext {}
+public record EventHandlerError(EventHandlerInfo handler, Object event, Throwable cause, int attempts)
+        implements ErrorContext {
+
+    /**
+     * Single-attempt error — the common case (no retries). Delegates to the canonical constructor
+     * with {@code attempts = 1}, so every existing call site and exhaustive {@code switch} over
+     * {@link ErrorContext} keeps compiling.
+     */
+    public EventHandlerError(EventHandlerInfo handler, Object event, Throwable cause) {
+        this(handler, event, cause, 1);
+    }
+}

tiko-api/src/main/java/io/tiko/annotations/BackoffStrategy.java

@@ -0,0 +1,20 @@
+package io.tiko.annotations;
+
+/**
+ * How the delay between {@code @EventHandler(retries = ...)} attempts grows (#108).
+ *
+ * <p>The base delay is {@code @EventHandler(backoff = ...)}; this strategy decides how it
+ * scales across successive retries. Both are honoured only for asynchronous handlers —
+ * retries are async-only (see {@link EventHandler#retries()}).
+ */
+public enum BackoffStrategy {
+
+    /** Same delay before every retry: {@code backoff}, {@code backoff}, {@code backoff}, … */
+    FIXED,
+
+    /**
+     * Delay doubles each retry: {@code backoff}, {@code 2 × backoff}, {@code 4 × backoff}, …
+     * Eases pressure on a struggling downstream by spacing retries out geometrically.
+     */
+    EXPONENTIAL
+}

tiko-api/src/main/java/io/tiko/annotations/EventHandler.java

@@ -136,4 +136,48 @@
      * @return an ISO-8601 duration string, or empty for no timeout
      */
     String timeout() default "";
+
+    /**
+     * Optional retry count for an asynchronous handler (#108). When greater than zero and the
+     * handler throws, it is re-invoked up to this many times before the final failure is routed
+     * to the {@link io.tiko.ErrorHandler} — so {@code retries = 3} means one initial call plus up
+     * to three retries (four attempts total). On the first attempt that succeeds, no error is
+     * routed; once the budget is exhausted a single {@link io.tiko.EventHandlerError} is routed
+     * whose {@code attempts()} is the total number of attempts made.
+     *
+     * <p><strong>Requires {@code async = true}.</strong> Retries wait for {@link #backoff()}
+     * between attempts; doing that on the publisher's thread would block it. Like {@link #timeout()},
+     * a retry on a synchronous handler is a compile-time error. If both {@code timeout} and
+     * {@code retries} are set, each attempt is time-boxed and a timed-out attempt counts as a
+     * failed attempt. Errors (as opposed to exceptions) are never retried.
+     *
+     * <p><strong>Idempotency is the handler's responsibility</strong> — a retried handler may run
+     * its side effects more than once.
+     *
+     * <p>Default: {@code 0} (no retries — opt-in).
+     *
+     * @return the number of retries after the initial attempt, or 0 for none
+     */
+    int retries() default 0;
+
+    /**
+     * Base delay between retry attempts, as an ISO-8601 {@link java.time.Duration} string
+     * (e.g. {@code "PT0.1S"}). Scaled across attempts per {@link #backoffStrategy()}. Only
+     * meaningful when {@link #retries()} is greater than zero.
+     *
+     * <p>Default: {@code ""} (retry immediately, no delay).
+     *
+     * @return an ISO-8601 duration string, or empty for no delay
+     */
+    String backoff() default "";
+
+    /**
+     * How {@link #backoff()} grows across successive retries. Only meaningful when
+     * {@link #retries()} is greater than zero.
+     *
+     * <p>Default: {@link BackoffStrategy#FIXED}.
+     *
+     * @return the backoff growth strategy
+     */
+    BackoffStrategy backoffStrategy() default BackoffStrategy.FIXED;
 }

tiko-processor/src/main/java/io/tiko/processor/TikoAnnotationProcessor.java

@@ -878,6 +878,11 @@ private EventHandlerModel buildEventHandlerModel(ExecutableElement methodElement
             return null; // a timeout validation error was reported; skip this handler
         }
 
+        long backoffNanos = resolveHandlerBackoffNanos(methodElement, annotation);
+        if (backoffNanos < 0 || !validateRetries(methodElement, annotation)) {
+            return null; // a retry validation error was reported; skip this handler
+        }
+
         return EventHandlerModel.builder()
                 .methodElement(methodElement)
                 .declaringClass(declaringClass)
@@ -887,10 +892,76 @@ private EventHandlerModel buildEventHandlerModel(ExecutableElement methodElement
                 .async(annotation.async())
                 .hasEventWrapper(hasEventWrapper)
                 .timeoutNanos(timeoutNanos)
+                .retries(annotation.retries())
+                .backoffNanos(backoffNanos)
+                .backoffStrategy(annotation.backoffStrategy())
                 .eventTriggers(eventTriggers)
                 .build();
     }
 
+    /**
+     * Validates {@code @EventHandler(retries = ...)} (#108): retries are async-only (they wait for
+     * the backoff between attempts, which would block the publisher's thread) and the count cannot
+     * be negative. Returns {@code false} (and reports a compile error) when invalid.
+     */
+    private boolean validateRetries(ExecutableElement methodElement, EventHandler annotation) {
+        int retries = annotation.retries();
+        if (retries == 0) {
+            return true;
+        }
+        if (retries < 0) {
+            context.getErrorReporter()
+                    .error(
+                            methodElement,
+                            "@EventHandler retries '" + retries + "' must not be negative",
+                            "Use a non-negative retry count, e.g. retries = 3");
+            return false;
+        }
+        if (!annotation.async()) {
+            context.getErrorReporter()
+                    .error(
+                            methodElement,
+                            "@EventHandler retries requires async = true: retrying with backoff on the"
+                                    + " publisher's thread would block it",
+                            "Add async = true to retry off-thread",
+                            "Or remove retries");
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * Resolves {@code @EventHandler(backoff = ...)} (#108) to a non-negative nanosecond base delay,
+     * or {@code 0} when no backoff is declared. Returns {@code -1} (and reports a compile error)
+     * when the value is not an ISO-8601 {@link java.time.Duration} or is negative.
+     */
+    private long resolveHandlerBackoffNanos(ExecutableElement methodElement, EventHandler annotation) {
+        String backoff = annotation.backoff();
+        if (backoff == null || backoff.isBlank()) {
+            return 0L;
+        }
+        java.time.Duration duration;
+        try {
+            duration = java.time.Duration.parse(backoff.trim());
+        } catch (java.time.format.DateTimeParseException badFormat) {
+            context.getErrorReporter()
+                    .error(
+                            methodElement,
+                            "@EventHandler backoff '" + backoff + "' is not a valid ISO-8601 Duration",
+                            "Use an ISO-8601 duration such as \"PT0.1S\" (100 ms) or \"PT2S\" (2 seconds)");
+            return -1L;
+        }
+        if (duration.isNegative()) {
+            context.getErrorReporter()
+                    .error(
+                            methodElement,
+                            "@EventHandler backoff '" + backoff + "' must not be negative",
+                            "Use a non-negative duration such as \"PT0.1S\"");
+            return -1L;
+        }
+        return duration.toNanos();
+    }
+
     /**
      * Resolves {@code @EventHandler(timeout = ...)} (#107) to a positive nanosecond budget, or
      * {@code 0} when no timeout is declared. Returns {@code -1} (and reports a compile error) when

tiko-processor/src/main/java/io/tiko/processor/generator/EventRegistryGenerator.java

@@ -222,7 +222,25 @@ private MethodSpec createDispatcherMethod(EventHandlerModel handler, int index)
             runBody.addStatement("$T.exit(__asyncPrev)", CHAIN_CONTEXT);
             runBody.endControlFlow();
 
-            if (handler.hasTimeout()) {
+            if (handler.hasRetries()) {
+                // Retry dispatch (#108): re-invoke on failure up to the budget, with backoff
+                // scheduled between attempts and (when a timeout is also set) each attempt
+                // time-boxed. The helper routes a single EventHandlerError carrying the attempt
+                // count once the budget is exhausted. Composes the #107 timeout per attempt.
+                method.addCode(CodeBlock.builder()
+                        .add(
+                                "$T.runAsyncWithRetry(() -> {\n$L}, new $T($L, $LL, $T.$L, $LL), __exec, __err, HANDLER_INFO_$L, event);\n",
+                                CHAIN_CONTEXT,
+                                runBody.build(),
+                                ClassName.get("io.tiko.runtime", "RetryPolicy"),
+                                handler.getRetries(),
+                                handler.getBackoffNanos(),
+                                ClassName.get("io.tiko.annotations", "BackoffStrategy"),
+                                handler.getBackoffStrategy().name(),
+                                handler.getTimeoutNanos(),
+                                index)
+                        .build());
+            } else if (handler.hasTimeout()) {
                 // Timed dispatch (#107): run the invocation under a wall-clock budget. The runtime
                 // helper submits the body to the executor as an interruptible Future, interrupts it
                 // on breach (best-effort), frees the slot, and routes an EventHandlerError whose

tiko-processor/src/main/java/io/tiko/processor/model/EventHandlerModel.java

@@ -1,5 +1,6 @@
 package io.tiko.processor.model;
 
+import io.tiko.annotations.BackoffStrategy;
 import java.util.ArrayList;
 import java.util.List;
 import javax.lang.model.element.ExecutableElement;
@@ -19,6 +20,9 @@ public final class EventHandlerModel {
     private final boolean async;
     private final boolean hasEventWrapper; // Second parameter is Event<?> wrapper
     private final long timeoutNanos; // 0 = no timeout (#107); async-only, validated at build time
+    private final int retries; // 0 = no retries (#108); async-only, validated at build time
+    private final long backoffNanos; // base retry delay; 0 = immediate
+    private final BackoffStrategy backoffStrategy;
     private final List<EventTriggerModel> eventTriggers;
 
     private EventHandlerModel(Builder builder) {
@@ -30,6 +34,9 @@ private EventHandlerModel(Builder builder) {
         this.async = builder.async;
         this.hasEventWrapper = builder.hasEventWrapper;
         this.timeoutNanos = builder.timeoutNanos;
+        this.retries = builder.retries;
+        this.backoffNanos = builder.backoffNanos;
+        this.backoffStrategy = builder.backoffStrategy;
         this.eventTriggers = List.copyOf(builder.eventTriggers);
     }
 
@@ -75,6 +82,26 @@ public boolean hasTimeout() {
         return timeoutNanos > 0;
     }
 
+    /** Retry count after the initial attempt, or {@code 0} for none (#108). Always async-only. */
+    public int getRetries() {
+        return retries;
+    }
+
+    /** Base retry backoff in nanoseconds, or {@code 0} for immediate retries. */
+    public long getBackoffNanos() {
+        return backoffNanos;
+    }
+
+    /** How the backoff grows across retries. */
+    public BackoffStrategy getBackoffStrategy() {
+        return backoffStrategy;
+    }
+
+    /** True when this handler declared {@code @EventHandler(retries > 0)}. */
+    public boolean hasRetries() {
+        return retries > 0;
+    }
+
     public List<EventTriggerModel> getEventTriggers() {
         return eventTriggers;
     }
@@ -95,6 +122,9 @@ public static final class Builder {
         private boolean async = false;
         private boolean hasEventWrapper = false;
         private long timeoutNanos = 0L;
+        private int retries = 0;
+        private long backoffNanos = 0L;
+        private BackoffStrategy backoffStrategy = BackoffStrategy.FIXED;
         private List<EventTriggerModel> eventTriggers = new ArrayList<>();
 
         private Builder() {}
@@ -139,6 +169,21 @@ public Builder timeoutNanos(long timeoutNanos) {
             return this;
         }
 
+        public Builder retries(int retries) {
+            this.retries = retries;
+            return this;
+        }
+
+        public Builder backoffNanos(long backoffNanos) {
+            this.backoffNanos = backoffNanos;
+            return this;
+        }
+
+        public Builder backoffStrategy(BackoffStrategy backoffStrategy) {
+            this.backoffStrategy = backoffStrategy;
+            return this;
+        }
+
         public Builder eventTriggers(List<EventTriggerModel> eventTriggers) {
             this.eventTriggers = new ArrayList<>(eventTriggers);
             return this;