Rename EventErrorPolicy values: STOP→PROPAGATE, CONTINUE→SUPPRESS (Spring-style)

Co-authored-by: brunoborges <129743+brunoborges@users.noreply.github.com>

Author: Copilot

CHANGELOG.md

@@ -41,10 +41,10 @@ session.setEventErrorHandler((event, exception) -> {
 ```
 
 #### EventErrorPolicy for Dispatch Control
-Added `EventErrorPolicy` enum to control whether event dispatch continues or stops when a handler throws an exception. The default policy is `CONTINUE` (existing behavior). Set `STOP` to short-circuit dispatch on the first error:
+Added `EventErrorPolicy` enum to control whether event dispatch continues or stops when a handler throws an exception. The default policy is `SUPPRESS` (existing behavior). Set `PROPAGATE` to stop dispatch on the first error:
 
 ```java
-session.setEventErrorPolicy(EventErrorPolicy.STOP);
+session.setEventErrorPolicy(EventErrorPolicy.PROPAGATE);
 ```
 
 The `EventErrorHandler` is always invoked regardless of the policy. When no error handler is set, exceptions are silently consumed (no logging).

src/main/java/com/github/copilot/sdk/CopilotSession.java

@@ -96,7 +96,7 @@ public final class CopilotSession implements AutoCloseable {
     private final AtomicReference<UserInputHandler> userInputHandler = new AtomicReference<>();
     private final AtomicReference<SessionHooks> hooksHandler = new AtomicReference<>();
     private volatile EventErrorHandler eventErrorHandler;
-    private volatile EventErrorPolicy eventErrorPolicy = EventErrorPolicy.CONTINUE;
+    private volatile EventErrorPolicy eventErrorPolicy = EventErrorPolicy.SUPPRESS;
 
     /**
      * Creates a new session with the given ID and RPC client.
@@ -200,10 +200,10 @@ public void setEventErrorHandler(EventErrorHandler handler) {
      * preceding listener throws an exception.
      *
      * <ul>
-     * <li>{@link EventErrorPolicy#CONTINUE} (default) — dispatch to all remaining
-     * listeners regardless of errors</li>
-     * <li>{@link EventErrorPolicy#STOP} — stop dispatching after the first
-     * error</li>
+     * <li>{@link EventErrorPolicy#SUPPRESS} (default) — suppress the error and
+     * dispatch to all remaining listeners regardless</li>
+     * <li>{@link EventErrorPolicy#PROPAGATE} — propagate the error effect by
+     * stopping dispatch after the first error</li>
      * </ul>
      *
      * <p>
@@ -214,14 +214,14 @@ public void setEventErrorHandler(EventErrorHandler handler) {
      * <b>Example:</b>
      *
      * <pre>{@code
-     * // Opt-in to short-circuit on first error
-     * session.setEventErrorPolicy(EventErrorPolicy.STOP);
+     * // Opt-in to propagate errors (stop dispatch on first error)
+     * session.setEventErrorPolicy(EventErrorPolicy.PROPAGATE);
      * session.setEventErrorHandler(
      * 		(event, ex) -> logger.error("Handler failed, stopping dispatch: {}", ex.getMessage(), ex));
      * }</pre>
      *
      * @param policy
-     *            the error policy (default is {@link EventErrorPolicy#CONTINUE})
+     *            the error policy (default is {@link EventErrorPolicy#SUPPRESS})
      * @see EventErrorPolicy
      * @see #setEventErrorHandler(EventErrorHandler)
      * @since 1.0.8
@@ -465,9 +465,10 @@ public <T extends AbstractSessionEvent> Closeable on(Class<T> eventType, Consume
      * handler is invoked in its own try/catch block. Whether dispatch continues
      * after a handler error depends on the configured {@link EventErrorPolicy}:
      * <ul>
-     * <li>{@link EventErrorPolicy#CONTINUE} (default) — remaining handlers still
+     * <li>{@link EventErrorPolicy#SUPPRESS} (default) — remaining handlers still
      * execute</li>
-     * <li>{@link EventErrorPolicy#STOP} — dispatch stops after the first error</li>
+     * <li>{@link EventErrorPolicy#PROPAGATE} — dispatch stops after the first
+     * error</li>
      * </ul>
      * <p>
      * The configured {@link EventErrorHandler} is always invoked (if set),
@@ -494,7 +495,7 @@ void dispatchEvent(AbstractSessionEvent event) {
                         break; // error handler itself failed — stop regardless of policy
                     }
                 }
-                if (eventErrorPolicy == EventErrorPolicy.STOP) {
+                if (eventErrorPolicy == EventErrorPolicy.PROPAGATE) {
                     break;
                 }
             }

src/main/java/com/github/copilot/sdk/EventErrorPolicy.java

@@ -19,14 +19,19 @@
  * continues after the error handler has been called.
  *
  * <p>
+ * The naming follows the convention used by Spring Framework's
+ * {@code TaskUtils.LOG_AND_SUPPRESS_ERROR_HANDLER} and
+ * {@code TaskUtils.LOG_AND_PROPAGATE_ERROR_HANDLER}.
+ *
+ * <p>
  * <b>Example:</b>
  *
  * <pre>{@code
- * // Default: continue dispatching despite errors
- * session.setEventErrorPolicy(EventErrorPolicy.CONTINUE);
+ * // Default: suppress errors and continue dispatching
+ * session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS);
  *
- * // Opt-in to short-circuit on first error
- * session.setEventErrorPolicy(EventErrorPolicy.STOP);
+ * // Opt-in to propagate errors (stop dispatch on first error)
+ * session.setEventErrorPolicy(EventErrorPolicy.PROPAGATE);
  * }</pre>
  *
  * @see CopilotSession#setEventErrorPolicy(EventErrorPolicy)
@@ -36,18 +41,21 @@
 public enum EventErrorPolicy {
 
     /**
-     * Stop dispatching on first listener error.
+     * Suppress errors and continue dispatching to remaining listeners (default).
      * <p>
-     * When a handler throws an exception, no further handlers are invoked. The
-     * configured {@link EventErrorHandler} is still called before dispatch stops.
+     * When a handler throws an exception, remaining handlers still execute. The
+     * configured {@link EventErrorHandler} is called for each error. This is
+     * analogous to Spring's {@code LOG_AND_SUPPRESS_ERROR_HANDLER} behavior.
      */
-    STOP,
+    SUPPRESS,
 
     /**
-     * Continue dispatching to remaining listeners despite errors (default).
+     * Propagate the error effect by stopping dispatch on first listener error.
      * <p>
-     * When a handler throws an exception, remaining handlers still execute. The
-     * configured {@link EventErrorHandler} is called for each error.
+     * When a handler throws an exception, no further handlers are invoked. The
+     * configured {@link EventErrorHandler} is still called before dispatch stops.
+     * This is analogous to Spring's {@code LOG_AND_PROPAGATE_ERROR_HANDLER}
+     * behavior.
      */
-    CONTINUE
+    PROPAGATE
 }

src/site/markdown/advanced.md

@@ -498,12 +498,12 @@ session.setEventErrorHandler(null);
 
 ### Event Error Policy
 
-By default, the SDK continues dispatching to remaining handlers after an error
-(`EventErrorPolicy.CONTINUE`). You can opt in to **short-circuit** behavior so
-that the first handler error stops dispatch:
+By default, the SDK suppresses errors and continues dispatching to remaining
+handlers (`EventErrorPolicy.SUPPRESS`). You can opt in to **propagate** errors
+so that the first handler error stops dispatch:
 
 ```java
-session.setEventErrorPolicy(EventErrorPolicy.STOP);
+session.setEventErrorPolicy(EventErrorPolicy.PROPAGATE);
 ```
 
 The `EventErrorHandler` (if set) is always invoked regardless of the policy —
@@ -512,26 +512,26 @@ handler returns.
 
 | Policy | Behavior |
 |---|---|
-| `CONTINUE` (default) | All remaining handlers execute despite errors |
-| `STOP` | Dispatch halts after the first handler error |
+| `SUPPRESS` (default) | Suppress the error; all remaining handlers execute |
+| `PROPAGATE` | Propagate the error effect; dispatch halts after the first error |
 
 You can combine both for full control:
 
 ```java
-// Log errors and stop dispatch on first failure
-session.setEventErrorPolicy(EventErrorPolicy.STOP);
+// Log errors and propagate (stop dispatch on first failure)
+session.setEventErrorPolicy(EventErrorPolicy.PROPAGATE);
 session.setEventErrorHandler((event, ex) ->
     logger.error("Handler failed, stopping: {}", ex.getMessage(), ex));
 ```
 
 Or switch policies dynamically:
 
 ```java
-// Start lenient
-session.setEventErrorPolicy(EventErrorPolicy.CONTINUE);
+// Start lenient (suppress errors)
+session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS);
 
-// Later, switch to strict mode
-session.setEventErrorPolicy(EventErrorPolicy.STOP);
+// Later, switch to strict mode (propagate errors)
+session.setEventErrorPolicy(EventErrorPolicy.PROPAGATE);
 ```
 
 See [EventErrorPolicy](apidocs/com/github/copilot/sdk/EventErrorPolicy.html) and [EventErrorHandler](apidocs/com/github/copilot/sdk/EventErrorHandler.html) Javadoc for details.

src/test/java/com/github/copilot/sdk/SessionEventHandlingTest.java

@@ -556,19 +556,19 @@ void testDefaultPolicyContinuesOnError() {
 
         dispatchEvent(createAssistantMessageEvent("Test"));
 
-        // All handlers should have been called (CONTINUE is default)
+        // All handlers should have been called (SUPPRESS is default)
         assertEquals(1, handler1Called.get());
         assertEquals(1, handler2Called.get());
         assertEquals(1, handler3Called.get());
     }
 
     @Test
-    void testStopPolicyStopsOnFirstError() {
+    void testPropagatePolicyStopsOnFirstError() {
         var handler1Called = new AtomicInteger(0);
         var handler2Called = new AtomicInteger(0);
         var errorHandlerCalls = new AtomicInteger(0);
 
-        session.setEventErrorPolicy(EventErrorPolicy.STOP);
+        session.setEventErrorPolicy(EventErrorPolicy.PROPAGATE);
         session.setEventErrorHandler((event, exception) -> {
             errorHandlerCalls.incrementAndGet();
         });
@@ -586,17 +586,17 @@ void testStopPolicyStopsOnFirstError() {
 
         dispatchEvent(createAssistantMessageEvent("Test"));
 
-        // Only one handler should have been called (STOP policy)
+        // Only one handler should have been called (PROPAGATE policy)
         assertEquals(1, errorHandlerCalls.get());
         int totalCalls = handler1Called.get() + handler2Called.get();
-        assertEquals(1, totalCalls, "Only one handler should execute with STOP policy");
+        assertEquals(1, totalCalls, "Only one handler should execute with PROPAGATE policy");
     }
 
     @Test
-    void testStopPolicyErrorHandlerAlwaysInvoked() {
+    void testPropagatePolicyErrorHandlerAlwaysInvoked() {
         var errorHandlerCalls = new AtomicInteger(0);
 
-        session.setEventErrorPolicy(EventErrorPolicy.STOP);
+        session.setEventErrorPolicy(EventErrorPolicy.PROPAGATE);
         session.setEventErrorHandler((event, exception) -> {
             errorHandlerCalls.incrementAndGet();
         });
@@ -607,16 +607,16 @@ void testStopPolicyErrorHandlerAlwaysInvoked() {
 
         dispatchEvent(createAssistantMessageEvent("Test"));
 
-        // Error handler should be called even with STOP policy
+        // Error handler should be called even with PROPAGATE policy
         assertEquals(1, errorHandlerCalls.get());
     }
 
     @Test
-    void testContinuePolicyWithMultipleErrors() {
+    void testSuppressPolicyWithMultipleErrors() {
         var errorHandlerCalls = new AtomicInteger(0);
         var successfulHandlerCalls = new AtomicInteger(0);
 
-        session.setEventErrorPolicy(EventErrorPolicy.CONTINUE);
+        session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS);
         session.setEventErrorHandler((event, exception) -> {
             errorHandlerCalls.incrementAndGet();
         });
@@ -660,29 +660,29 @@ void testSwitchPolicyDynamically() {
             throw new RuntimeException("error");
         });
 
-        // With CONTINUE, both should fire
-        session.setEventErrorPolicy(EventErrorPolicy.CONTINUE);
+        // With SUPPRESS, both should fire
+        session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS);
         dispatchEvent(createAssistantMessageEvent("Test1"));
         assertEquals(1, handler1Called.get());
         assertEquals(1, handler2Called.get());
 
         handler1Called.set(0);
         handler2Called.set(0);
 
-        // Switch to STOP — only one should fire
-        session.setEventErrorPolicy(EventErrorPolicy.STOP);
+        // Switch to PROPAGATE — only one should fire
+        session.setEventErrorPolicy(EventErrorPolicy.PROPAGATE);
         dispatchEvent(createAssistantMessageEvent("Test2"));
         int totalCalls = handler1Called.get() + handler2Called.get();
-        assertEquals(1, totalCalls, "Only one handler should execute after switching to STOP");
+        assertEquals(1, totalCalls, "Only one handler should execute after switching to PROPAGATE");
     }
 
     @Test
-    void testStopPolicyNoErrorHandlerSilentlyStops() {
+    void testPropagatePolicyNoErrorHandlerSilentlyStops() {
         var handler1Called = new AtomicInteger(0);
         var handler2Called = new AtomicInteger(0);
 
-        // No error handler set, STOP policy
-        session.setEventErrorPolicy(EventErrorPolicy.STOP);
+        // No error handler set, PROPAGATE policy
+        session.setEventErrorPolicy(EventErrorPolicy.PROPAGATE);
 
         session.on(AssistantMessageEvent.class, msg -> {
             handler1Called.incrementAndGet();
@@ -696,9 +696,9 @@ void testStopPolicyNoErrorHandlerSilentlyStops() {
 
         assertDoesNotThrow(() -> dispatchEvent(createAssistantMessageEvent("Test")));
 
-        // STOP policy should stop after first error, even without error handler
+        // PROPAGATE policy should stop after first error, even without error handler
         int totalCalls = handler1Called.get() + handler2Called.get();
-        assertEquals(1, totalCalls, "Only one handler should execute with STOP policy and no error handler");
+        assertEquals(1, totalCalls, "Only one handler should execute with PROPAGATE policy and no error handler");
     }
 
     @Test
@@ -711,8 +711,8 @@ void testErrorHandlerThrowingStopsRegardlessOfPolicy() {
         sessionLogger.setLevel(Level.OFF);
 
         try {
-            // CONTINUE policy, but error handler throws
-            session.setEventErrorPolicy(EventErrorPolicy.CONTINUE);
+            // SUPPRESS policy, but error handler throws
+            session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS);
             session.setEventErrorHandler((event, exception) -> {
                 throw new RuntimeException("error handler broke");
             });
@@ -729,10 +729,10 @@ void testErrorHandlerThrowingStopsRegardlessOfPolicy() {
 
             assertDoesNotThrow(() -> dispatchEvent(createAssistantMessageEvent("Test")));
 
-            // Error handler threw — should stop regardless of CONTINUE policy
+            // Error handler threw — should stop regardless of SUPPRESS policy
             int totalCalls = handler1Called.get() + handler2Called.get();
             assertEquals(1, totalCalls,
-                    "Only one handler should execute when error handler throws, even with CONTINUE policy");
+                    "Only one handler should execute when error handler throws, even with SUPPRESS policy");
         } finally {
             sessionLogger.setLevel(originalLevel);
         }