From 7fb2f58706a09ed07ac456c6a764b08a71053948 Mon Sep 17 00:00:00 2001 From: "Rui L. Lopes" Date: Tue, 17 Nov 2026 16:44:43 +0000 Subject: [PATCH 1/3] fix(server): stop interrupted event consumers from busy-spinning An interrupted EventConsumer now fails its stream with InternalError and closes its queue, instead of polling again with the interrupt flag set. InMemoryQueueManager.close(taskId) now also closes the task's child queues, as the QueueManager.close contract states, so closing a task queue ends its consumers. consumeOne now wraps the spec InternalError, not java.lang.InternalError. This fixes #1345 --- .../sdk/server/events/EventConsumer.java | 15 +++ .../sdk/server/events/EventQueue.java | 3 +- .../server/events/InMemoryQueueManager.java | 5 +- .../sdk/server/events/EventConsumerTest.java | 93 ++++++++++++++++++- .../events/InMemoryQueueManagerTest.java | 13 +++ 5 files changed, 126 insertions(+), 3 deletions(-) diff --git a/server-common/src/main/java/org/a2aproject/sdk/server/events/EventConsumer.java b/server-common/src/main/java/org/a2aproject/sdk/server/events/EventConsumer.java index a4379fb09..307f45bf8 100644 --- a/server-common/src/main/java/org/a2aproject/sdk/server/events/EventConsumer.java +++ b/server-common/src/main/java/org/a2aproject/sdk/server/events/EventConsumer.java @@ -6,6 +6,7 @@ import org.a2aproject.sdk.spec.A2AError; import org.a2aproject.sdk.spec.A2AServerException; import org.a2aproject.sdk.spec.Event; +import org.a2aproject.sdk.spec.InternalError; import org.a2aproject.sdk.spec.Message; import org.a2aproject.sdk.spec.Task; import org.a2aproject.sdk.spec.TaskState; @@ -129,6 +130,20 @@ public Flow.Publisher consumeAll() { System.identityHashCode(queue), error, agentCompleted); item = queue.dequeueEventItem(QUEUE_WAIT_MILLISECONDS); if (item == null) { + // An interrupted dequeue returns null with the interrupt flag set, so every + // later poll returns at once: polling again would busy-spin (#1345). + if (Thread.currentThread().isInterrupted()) { + LOGGER.warn("EventConsumer polling thread interrupted, exiting polling loop for queue {}", System.identityHashCode(queue)); + completed = true; + tube.fail(new InternalError("EventConsumer polling thread was interrupted")); + // The close can read the task store, which can throw on an interrupted thread + try { + queue.close(true); + } catch (RuntimeException e) { + LOGGER.warn("Failed to close the queue {} of an interrupted EventConsumer", System.identityHashCode(queue), e); + } + return; + } int queueSize = queue.size(); boolean awaitingFinal = queue.isAwaitingFinalEvent(); LOGGER.debug("EventConsumer poll timeout (null item), agentCompleted={}, queue.size()={}, awaitingFinalEvent={}, timeoutCount={}, awaitingTimeoutCount={}", diff --git a/server-common/src/main/java/org/a2aproject/sdk/server/events/EventQueue.java b/server-common/src/main/java/org/a2aproject/sdk/server/events/EventQueue.java index c35d35cab..5496be107 100644 --- a/server-common/src/main/java/org/a2aproject/sdk/server/events/EventQueue.java +++ b/server-common/src/main/java/org/a2aproject/sdk/server/events/EventQueue.java @@ -331,7 +331,8 @@ public void enqueueEventLocalOnly(Event event) { *

* * @param waitMilliSeconds the maximum time to wait in milliseconds - * @return the EventQueueItem, or null if timeout occurs + * @return the EventQueueItem, or null if timeout occurs or the wait is interrupted + * (in which case the thread's interrupt flag is set) * @throws EventQueueClosedException if the queue is closed and empty * @throws UnsupportedOperationException if called on MainQueue */ diff --git a/server-common/src/main/java/org/a2aproject/sdk/server/events/InMemoryQueueManager.java b/server-common/src/main/java/org/a2aproject/sdk/server/events/InMemoryQueueManager.java index 27a42b668..f0154563f 100644 --- a/server-common/src/main/java/org/a2aproject/sdk/server/events/InMemoryQueueManager.java +++ b/server-common/src/main/java/org/a2aproject/sdk/server/events/InMemoryQueueManager.java @@ -89,8 +89,11 @@ public void close(String taskId) { if (existing == null) { throw new NoTaskQueueException(); } - // Close the queue to stop EventConsumer polling loop LOGGER.debug("Closing queue {} for task {}", System.identityHashCode(existing), taskId); + // A graceful MainQueue close leaves its children open, and EventConsumers poll the children + if (existing instanceof EventQueue.MainQueue mainQueue) { + mainQueue.closeChildren(); + } existing.close(); } diff --git a/server-common/src/test/java/org/a2aproject/sdk/server/events/EventConsumerTest.java b/server-common/src/test/java/org/a2aproject/sdk/server/events/EventConsumerTest.java index d290a2dcf..696681c2c 100644 --- a/server-common/src/test/java/org/a2aproject/sdk/server/events/EventConsumerTest.java +++ b/server-common/src/test/java/org/a2aproject/sdk/server/events/EventConsumerTest.java @@ -2,6 +2,7 @@ import static org.a2aproject.sdk.jsonrpc.common.json.JsonUtil.fromJson; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertSame; @@ -11,6 +12,8 @@ import java.util.ArrayList; import java.util.List; import java.util.concurrent.CountDownLatch; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; import java.util.concurrent.Flow; import java.util.concurrent.TimeUnit; import java.util.concurrent.atomic.AtomicReference; @@ -18,10 +21,12 @@ import org.a2aproject.sdk.jsonrpc.common.json.JsonProcessingException; import org.a2aproject.sdk.server.tasks.InMemoryTaskStore; import org.a2aproject.sdk.server.tasks.PushNotificationSender; +import org.a2aproject.sdk.server.tasks.TaskStateProvider; import org.a2aproject.sdk.spec.A2AError; import org.a2aproject.sdk.spec.A2AServerException; import org.a2aproject.sdk.spec.Artifact; import org.a2aproject.sdk.spec.Event; +import org.a2aproject.sdk.spec.InternalError; import org.a2aproject.sdk.spec.Message; import org.a2aproject.sdk.spec.Task; import org.a2aproject.sdk.spec.TaskArtifactUpdateEvent; @@ -32,6 +37,8 @@ import org.junit.jupiter.api.AfterEach; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; public class EventConsumerTest { @@ -139,7 +146,8 @@ public void testConsumeOneJsonRpcErrorEvent() throws Exception { @Test public void testConsumeOneQueueEmpty() throws A2AServerException { - assertThrows(A2AServerException.class, () -> eventConsumer.consumeOne()); + A2AServerException exception = assertThrows(A2AServerException.class, () -> eventConsumer.consumeOne()); + assertInstanceOf(InternalError.class, exception.getCause()); } @Test @@ -589,6 +597,89 @@ public void onComplete() { assertEquals(0, receivedEvents.size(), "QueueClosedEvent should be intercepted, not delivered"); } + @ParameterizedTest(name = "agentCompleted={0}") + @ValueSource(booleans = {false, true}) + public void testConsumeAllStopsWhenPollingThreadIsInterrupted(boolean agentCompleted) throws Exception { + assertInterruptedConsumerFailsAndClosesQueue(eventQueue, agentCompleted); + } + + @Test + public void testInterruptedConsumerFailsWithInternalErrorWhenClosingItsQueueThrows() throws Exception { + EventQueue childQueue = EventQueueUtil.getEventQueueBuilder(mainEventBus) + .taskId(TASK_ID) + .mainEventBus(mainEventBus) + .taskStateProvider(new TaskStateProvider() { + @Override + public boolean isTaskActive(String taskId) { + return true; + } + + @Override + public boolean isTaskFinalized(String taskId) { + // As a JDBC pool does when it must wait for a connection on an interrupted thread + if (Thread.currentThread().isInterrupted()) { + throw new IllegalStateException("Interrupted while acquiring"); + } + return false; + } + }) + .build().tap(); + assertInterruptedConsumerFailsAndClosesQueue(childQueue, false); + } + + private void assertInterruptedConsumerFailsAndClosesQueue(EventQueue queue, boolean agentCompleted) throws Exception { + ExecutorService executor = Executors.newSingleThreadExecutor(); + EventConsumer consumer = new EventConsumer(queue, executor); + if (agentCompleted) { + consumer.createAgentRunnableDoneCallback().done(new EnhancedRunnable() { + @Override + public void run() { + } + }); + } + AtomicReference error = new AtomicReference<>(); + CountDownLatch terminated = new CountDownLatch(1); + + consumer.consumeAll().subscribe(new Flow.Subscriber<>() { + @Override + public void onSubscribe(Flow.Subscription subscription) { + subscription.request(Long.MAX_VALUE); + } + + @Override + public void onNext(EventQueueItem item) { + } + + @Override + public void onError(Throwable throwable) { + error.set(throwable); + terminated.countDown(); + } + + @Override + public void onComplete() { + terminated.countDown(); + } + }); + + try { + queue.awaitQueuePollerStart(); + executor.shutdownNow(); + + assertTrue(terminated.await(5, TimeUnit.SECONDS), + "Interrupted consumer should stop instead of polling again"); + assertInstanceOf(InternalError.class, error.get()); + // The consumer closes its queue after it fails the stream + assertTrue(executor.awaitTermination(5, TimeUnit.SECONDS)); + assertTrue(queue.isClosed(), "Interrupted consumer should close its queue"); + } finally { + // A loop that ignores the interrupt only ends when the queue closes; close it so the executor can terminate. + queue.close(); + executor.shutdownNow(); + assertTrue(executor.awaitTermination(5, TimeUnit.SECONDS)); + } + } + private void enqueueAndConsumeOneEvent(Event event) throws Exception { // Use callback to wait for event processing waitForEventProcessing(() -> eventQueue.enqueueEvent(event)); diff --git a/server-common/src/test/java/org/a2aproject/sdk/server/events/InMemoryQueueManagerTest.java b/server-common/src/test/java/org/a2aproject/sdk/server/events/InMemoryQueueManagerTest.java index ced36e695..5039c76a2 100644 --- a/server-common/src/test/java/org/a2aproject/sdk/server/events/InMemoryQueueManagerTest.java +++ b/server-common/src/test/java/org/a2aproject/sdk/server/events/InMemoryQueueManagerTest.java @@ -119,6 +119,19 @@ public void testCloseExistingQueue() { assertNull(result); } + @Test + public void testCloseClosesChildQueues() { + String taskId = "close_children_task_id"; + EventQueue first = queueManager.createOrTap(taskId); + EventQueue second = queueManager.tap(taskId); + assertNotNull(second); + + queueManager.close(taskId); + + assertTrue(first.isClosed(), "close(taskId) should close the ChildQueues that consumers poll"); + assertTrue(second.isClosed(), "close(taskId) should close the ChildQueues that consumers poll"); + } + @Test public void testCloseNonexistentQueueThrowsException() { assertThrows(NoTaskQueueException.class, () -> { From 130bbe1bc94541b85754a92cb86debe0fae44c9f Mon Sep 17 00:00:00 2001 From: "Rui L. Lopes" Date: Tue, 17 Nov 2026 16:51:01 +0000 Subject: [PATCH 2/3] docs(server): explain why an interrupted poll ends the event consumer --- .../java/org/a2aproject/sdk/server/events/EventConsumer.java | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/server-common/src/main/java/org/a2aproject/sdk/server/events/EventConsumer.java b/server-common/src/main/java/org/a2aproject/sdk/server/events/EventConsumer.java index 307f45bf8..1b3054009 100644 --- a/server-common/src/main/java/org/a2aproject/sdk/server/events/EventConsumer.java +++ b/server-common/src/main/java/org/a2aproject/sdk/server/events/EventConsumer.java @@ -130,8 +130,9 @@ public Flow.Publisher consumeAll() { System.identityHashCode(queue), error, agentCompleted); item = queue.dequeueEventItem(QUEUE_WAIT_MILLISECONDS); if (item == null) { - // An interrupted dequeue returns null with the interrupt flag set, so every - // later poll returns at once: polling again would busy-spin (#1345). + // dequeueEventItem returns null on a timeout and also on an interrupt, with the + // interrupt flag still set. Only an interrupt ends this consumer: while the flag + // is set, each later poll returns at once, so polling again would spin. if (Thread.currentThread().isInterrupted()) { LOGGER.warn("EventConsumer polling thread interrupted, exiting polling loop for queue {}", System.identityHashCode(queue)); completed = true; From ba53a57fb6dff57ffca0c7b20a02b352254c0fab Mon Sep 17 00:00:00 2001 From: "Rui L. Lopes" Date: Tue, 17 Nov 2026 21:47:45 +0000 Subject: [PATCH 3/3] fix(server): skip MainQueue close callbacks when already closed --- .../main/java/org/a2aproject/sdk/server/events/EventQueue.java | 3 +++ 1 file changed, 3 insertions(+) diff --git a/server-common/src/main/java/org/a2aproject/sdk/server/events/EventQueue.java b/server-common/src/main/java/org/a2aproject/sdk/server/events/EventQueue.java index 5496be107..82904bf4e 100644 --- a/server-common/src/main/java/org/a2aproject/sdk/server/events/EventQueue.java +++ b/server-common/src/main/java/org/a2aproject/sdk/server/events/EventQueue.java @@ -850,6 +850,9 @@ StreamCloseHandle getStreamCloseHandle() { @Override protected void doClose(boolean immediate) { + if (isClosed()) { + return; + } // Invoke all callbacks BEFORE closing, so they can still enqueue events if (!onCloseCallbacks.isEmpty()) { LOGGER.debug("Invoking {} onClose callbacks for task {} BEFORE closing", onCloseCallbacks.size(), taskId);