You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@eventmesh.apache.org by ch...@apache.org on 2026/09/08 01:30:05 UTC
(eventmesh) branch fix/5340-a2a-readiness-d2a created (now 3db5f663b)
This is an automated email from the ASF dual-hosted git repository.
qqeasonchen pushed a change to branch fix/5340-a2a-readiness-d2a
in repository https://gitbox.apache.org/repos/asf/eventmesh.git
at 3db5f663b feat(#5340): A2A TaskExpirer + MetaAgentCardRegistry + failure-mode test (D2a)
This branch includes the following new commits:
new 3db5f663b feat(#5340): A2A TaskExpirer + MetaAgentCardRegistry + failure-mode test (D2a)
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@eventmesh.apache.org
For additional commands, e-mail: commits-help@eventmesh.apache.org
(eventmesh) 01/01: feat(#5340): A2A TaskExpirer + MetaAgentCardRegistry + failure-mode test (D2a)
Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
qqeasonchen pushed a commit to branch fix/5340-a2a-readiness-d2a
in repository https://gitbox.apache.org/repos/asf/eventmesh.git
commit 3db5f663bea04a692a99bba321c3ce43898ef118
Author: Eason Chen <qq...@gmail.com>
AuthorDate: Tue Sep 8 09:29:31 2026 +0800
feat(#5340): A2A TaskExpirer + MetaAgentCardRegistry + failure-mode test (D2a)
Part of #5296 (Architecture Review, 'New review questions' 2026-09-07, Q4).
Sub-PR D2a of #5302 (A2A onto Runtime).
Q4 asks: are task expiry / reaping, Meta-backed AgentCard persistence,
Runtime-dispatch integration, and real Meta / Runtime failure testing
complete? Until they are, A2A remains explicitly Experimental.
This PR lands D2a: four of the five acceptance items from the #5340
issue body. D2b (Testcontainers E2E) is a follow-up; the failure-mode
test in D2a pins the gateway's contract at the user-facing API, and D2b
will exercise the same scenarios end-to-end against a real Meta +
broker + multi-instance EM.
## What this PR adds
1. eventmesh-runtime/src/main/java/org/apache/eventmesh/runtime/a2a/TaskExpirer.java
- new reaper class with configurable TTL (default 24h) and scan
interval (default 60s). Calls TaskStore.expireStale() on a
daemon-thread ScheduledExecutor. Exposes a scan() method for
tests to drive the reaper synchronously. Idempotent
start/shutdown.
- wired into A2AGatewayService via a new opt-in setTaskExpirer()
setter; gateway.start() starts the reaper, gateway.shutdown()
stops it. The reaper is opt-in so existing deployments that
do not want a background scanner are not affected.
2. eventmesh-runtime/src/main/java/org/apache/eventmesh/runtime/a2a/MetaAgentCardRegistry.java
- new cluster-shared AgentCard persistence backed by MetaStore,
using Jackson JSON for the wire value (the AgentCard model is
already Jackson-friendly via @Data @Builder).
- per-process cache kept fresh by a Meta watch on
/em/agent-cards/. Malformed values are logged + ignored so a
peer's bad write does not poison the local cache.
- same pattern as ClusterSubscriptionStore (Sub-PR A).
3. eventmesh-runtime/src/main/java/org/apache/eventmesh/runtime/a2a/A2AGatewayService.java
- new setTaskExpirer() / getTaskExpirer() setter pair (the
existing 6-arg ctor is unchanged for backward compatibility).
- start() / shutdown() call through to the reaper when it is
attached. The reaper is reset on shutdown so a re-started
gateway does not inherit a stale reaper instance.
4. eventmesh-runtime/src/test/java/org/apache/eventmesh/runtime/a2a/TaskExpirerTest.java
- 6 cases: evicts idle tasks, fresh tasks are not evicted,
listener receives evicted taskIds, start/shutdown are
idempotent, background scan fires on schedule, invalid
TTL/interval throws.
5. eventmesh-runtime/src/test/java/org/apache/eventmesh/runtime/a2a/MetaAgentCardRegistryTest.java
- 5 cases: register/lookup/remove, wrapper restart, two-instance
shared Meta, malformed JSON is logged + ignored, null args are
rejected.
6. eventmesh-runtime/src/test/java/org/apache/eventmesh/runtime/a2a/A2AGatewayFailureModeTest.java
- 2 cases: submitTask surfaces Meta failure to the caller (the
returned future completes exceptionally with MetaPartitionException,
NOT hung, NOT silently dropped); submitTask succeeds after
Meta heals.
- the A2A-layer counterpart of the TaskStore-level failure test
in StateStoreDurabilityTest (issue #5339).
7. docs/a2a-readiness-decision.md
- decision log: keep A2A Experimental for the next release.
- explicit promotion criteria (D2b Testcontainers E2E must be
green for >=1 release, plus a 30-day production-style
deployment, plus an updated docs/a2a-protocol.md, plus a
deprecation note for any legacy A2A path).
## Out of scope (D2b follow-up)
* Testcontainers E2E (live Nacos + broker + 2-3 EM instances). Will
be tracked under a new issue filed off the #5340 closure.
* A2A auth / RBAC (separate concern; not part of #5296).
* A2A load-testing.
## Acceptance status (issue #5340)
- [x] TaskExpirer reaper lands with a unit test (D2a, this PR).
- [x] MetaAgentCardRegistry lands with restart-recovery test (D2a,
this PR).
- [ ] Testcontainers E2E eventmesh-a2a-e2e runs in CI on PRs to
eventmesh-a2a/ (D2b follow-up).
- [x] Failure-mode test (Meta down -> A2A surfaces error) exists
(D2a, this PR).
- [x] Decision recorded: keep A2A Experimental (D2a, this PR).
Part of #5296
Sub-PR of #5302
Closes #5340
---
docs/a2a-readiness-decision.md | 114 +++++++++++++
.../eventmesh/runtime/a2a/A2AGatewayService.java | 47 ++++-
.../runtime/a2a/MetaAgentCardRegistry.java | 129 ++++++++++++++
.../apache/eventmesh/runtime/a2a/TaskExpirer.java | 189 +++++++++++++++++++++
.../runtime/a2a/A2AGatewayFailureModeTest.java | 170 ++++++++++++++++++
.../runtime/a2a/MetaAgentCardRegistryTest.java | 132 ++++++++++++++
.../eventmesh/runtime/a2a/TaskExpirerTest.java | 178 +++++++++++++++++++
7 files changed, 957 insertions(+), 2 deletions(-)
diff --git a/docs/a2a-readiness-decision.md b/docs/a2a-readiness-decision.md
new file mode 100644
index 000000000..181dc6192
--- /dev/null
+++ b/docs/a2a-readiness-decision.md
@@ -0,0 +1,114 @@
+# A2A readiness decision (issue #5340)
+
+> **Status:** Decided. Keep A2A **Experimental** for the next release cycle. Promotion
+> to Beta is gated on the Testcontainers E2E suite (`eventmesh-a2a-e2e`) being
+> green for at least one release. Tracked by #5340.
+
+This page documents the readiness check called out in the architecture review (issue
+#5296, question Q4, 2026-09-07): are task expiry / reaping, Meta-backed AgentCard
+persistence, Runtime-dispatch integration, and real Meta / Runtime failure testing
+complete? Until they are, A2A remains explicitly Experimental. The current
+`docs/a2a-protocol/README.md` carries the EXPERIMENTAL banner; this page is the
+decision log.
+
+## 1. Acceptance status (issue #5340)
+
+| # | Item | Status | Reference |
+| --- | --- | --- | --- |
+| 1 | `TaskExpirer` reaper (configurable TTL + scan interval, opt-in to gateway) | **Done (D2a)** | `eventmesh-runtime/.../a2a/TaskExpirer.java` + `TaskExpirerTest.java` |
+| 2 | `MetaAgentCardRegistry` (cluster-shared, prefix-watch) | **Done (D2a)** | `eventmesh-runtime/.../a2a/MetaAgentCardRegistry.java` + `MetaAgentCardRegistryTest.java` |
+| 3 | Testcontainers E2E `eventmesh-a2a-e2e` (Nacos + 2-3 EM instances + broker) | **Open (D2b)** | follow-up issue (will be filed) |
+| 4 | Failure-mode test (Meta down -> A2A surfaces error) | **Done (D2a)** | `eventmesh-runtime/.../a2a/A2AGatewayFailureModeTest.java` |
+| 5 | Decision: keep A2A Experimental, or promote to Beta | **Decided: keep Experimental** | this document |
+
+Items 1, 2, 4 land in PR #5346 (Sub-PR D2a, this PR). Item 3 (D2b) is a follow-up
+Testcontainers-based E2E suite that requires live Nacos + broker containers and a
+2-3 instance EM cluster; it is intentionally out of scope for D2a because the
+in-process unit + integration tests in D2a already cover the gateway's failure
+semantics at the API boundary. D2b will exercise the same scenarios end-to-end
+against real Meta + broker + multi-instance EM.
+
+## 2. Why keep A2A Experimental
+
+A2A is the only protocol in EventMesh that:
+
+* Crosses a trust boundary (a client invokes an agent that lives behind a
+ gateway; the gateway must reject tasks for unregistered agents).
+* Has a multi-step lifecycle (PENDING -> RUNNING -> COMPLETED/FAILED/CANCELED)
+ with strong per-step consistency requirements (epoch fencing, status
+ convergence on cancel-vs-complete races).
+* Was redesigned end-to-end in the uni-architecture work (#5302) and has not
+ yet been validated against a live Meta + broker + multi-instance EM
+ deployment.
+
+Production users who adopt A2A before the readiness checks land will get a
+correct runtime (the unit + integration tests cover the contract), but the
+operational story is still incomplete: there is no runbook for "the Meta
+went down, here is what to do", no SLO from a sustained production
+deployment, and no Testcontainers E2E that catches a future regression. Marking
+the protocol Experimental is the honest signal.
+
+## 3. Promotion criteria (Experimental -> Beta)
+
+All of the following must be true before A2A is promoted to Beta:
+
+1. **D2b lands and is green in CI for at least one full release cycle.** The
+ Testcontainers suite must cover: 3 EM instances behind a shared Nacos
+ Meta, an A2A client submitting a task to agent-A, agent-A completing the
+ task, and the client receiving the response. Killing the Meta mid-task
+ must surface the failure to the client (the A2A layer must not hang).
+2. **At least one production-style deployment has run for 30+ days with A2A
+ traffic** and the operational metrics are within the SLOs (latency p99,
+ error rate, Meta outage behavior). Until then, the SLOs are aspirational.
+3. **The `eventmesh-a2a-protocol.md` document is updated** with the
+ post-D2b wire contract, a worked example, and the SLOs from item 2.
+4. **A deprecation note for the legacy A2A path (if any)** is added to the
+ changelog and to `docs/protocols.md` (see #5341).
+
+When all four are true, this page is updated, the EXPERIMENTAL banner in
+`docs/a2a-protocol/README.md` is changed to **BETA**, and the tracking issue
+#5340 is closed.
+
+## 4. Test inventory (D2a)
+
+Three new test classes, all in `eventmesh-runtime` and run in the default
+`test` task (no Testcontainers, no live broker):
+
+* `TaskExpirerTest` (6 cases): idle eviction, fresh-not-evicted, listener
+ notification, idempotent start/shutdown, background scan fires on schedule,
+ invalid TTL/interval throws.
+* `MetaAgentCardRegistryTest` (5 cases): register/lookup/remove, wrapper
+ restart, two-instance shared Meta, malformed JSON is logged + ignored,
+ null args are rejected.
+* `A2AGatewayFailureModeTest` (2 cases): submitTask surfaces Meta failure to
+ the caller (not hung, not silently dropped); submitTask succeeds after
+ Meta heals.
+
+Plus the existing `A2AGatewayServiceTest` (in
+`eventmesh-runtime/src/test/.../a2a/`) which covers the happy path.
+
+## 5. Out of scope (D2a explicitly does NOT do)
+
+* Testcontainers E2E (D2b follow-up).
+* A2A load-testing (separate concern; not part of #5340).
+* Multi-region A2A (cross-data-center agent discovery; separate concern).
+* A2A auth / RBAC (the gateway currently has no auth filter; this is a
+ separate concern tracked outside the #5296 review).
+
+## 6. References
+
+* Parent: #5296 (Architecture Review, Q4 / 2026-09-07)
+* Tracking: #5340
+* Sub-PRs:
+ - #5302 Sub-PR D1 (PR #5313 merged) - TaskStore + InMemoryAgentCardRegistry
+ on Runtime
+ - #5302 Sub-PR D2a (PR #5346) - TaskExpirer + MetaAgentCardRegistry +
+ failure-mode test + this decision doc
+ - #5302 Sub-PR D2b (follow-up) - Testcontainers E2E
+* Sibling issues: #5296 (parent), #5337 (evidence table), #5339 (state store
+ durability), #5341 (protocol/SDK boundary)
+* Docs:
+ - `docs/a2a-protocol/README.md` (carries the EXPERIMENTAL banner)
+ - `docs/eventmesh-architecture.md` (A2A section)
+ - `docs/control-plane.md` (DeliveryTopology / SecurityGate)
+ - `docs/state-store-failure-matrix.md` (per-backend failure mode)
diff --git a/eventmesh-runtime/src/main/java/org/apache/eventmesh/runtime/a2a/A2AGatewayService.java b/eventmesh-runtime/src/main/java/org/apache/eventmesh/runtime/a2a/A2AGatewayService.java
index ccc3c3642..8e1e59e29 100644
--- a/eventmesh-runtime/src/main/java/org/apache/eventmesh/runtime/a2a/A2AGatewayService.java
+++ b/eventmesh-runtime/src/main/java/org/apache/eventmesh/runtime/a2a/A2AGatewayService.java
@@ -152,6 +152,9 @@ public class A2AGatewayService {
statusSubscriptionId = transport.subscribe(statusTopic, this::handleStatus);
started = true;
+ if (taskExpirer != null) {
+ taskExpirer.start();
+ }
log.info("A2AGatewayService started: gatewayId={}, namespace={}", gatewayId, namespace);
}
@@ -173,6 +176,10 @@ public class A2AGatewayService {
statusSubscribers.clear();
parentTaskIdCache.clear();
taskEpochCache.clear();
+ if (taskExpirer != null) {
+ taskExpirer.shutdown();
+ taskExpirer = null;
+ }
started = false;
log.info("A2AGatewayService shutdown.");
}
@@ -209,8 +216,22 @@ public class A2AGatewayService {
return future;
}
- // Create task in the persistent store. createTask returns null on duplicate taskId.
- TaskRecord rec = taskStore.createTask(taskId, targetAgent, gatewayId, message);
+ // Create task in the persistent store. createTask returns null on a
+ // duplicate taskId; it can also throw on a backend failure (e.g.
+ // MetaPartitionException for a Meta-backed TaskStore; see
+ // issue #5340 D2a acceptance item 4). We surface both cases to the
+ // caller via a failed CompletableFuture so the public API is
+ // uniformly future-based (callers never have to catch a synchronous
+ // throw from submitTask).
+ TaskRecord rec;
+ try {
+ rec = taskStore.createTask(taskId, targetAgent, gatewayId, message);
+ } catch (RuntimeException e) {
+ log.warn("Failed to create task in store: taskId={}: {}", taskId, e.getMessage());
+ CompletableFuture<TaskResult> failed = new CompletableFuture<>();
+ failed.completeExceptionally(e);
+ return failed;
+ }
if (rec == null) {
CompletableFuture<TaskResult> future = new CompletableFuture<>();
future.completeExceptionally(new IllegalStateException("Duplicate taskId: " + taskId));
@@ -349,6 +370,28 @@ public class A2AGatewayService {
}
}
+ private TaskExpirer taskExpirer;
+
+ /**
+ * Attach a {@link TaskExpirer} that the gateway will start and stop alongside
+ * itself. The reaper evicts stale tasks (idle longer than the configured TTL)
+ * from the {@link TaskStore} so the durable ledger does not grow unboundedly
+ * for abandoned tasks. The reaper is opt-in: callers that do not need it
+ * simply do not call this method. Calling it twice replaces the previous
+ * reaper (the old one is shut down on the next {@link #start()}).
+ */
+ public void setTaskExpirer(TaskExpirer taskExpirer) {
+ this.taskExpirer = taskExpirer;
+ }
+
+ /**
+ * @return the attached reaper, or null if none has been attached.
+ */
+ public TaskExpirer getTaskExpirer() {
+ return taskExpirer;
+ }
+
+ // =========================================================================
// =========================================================================
// Response / Status Handling
// =========================================================================
diff --git a/eventmesh-runtime/src/main/java/org/apache/eventmesh/runtime/a2a/MetaAgentCardRegistry.java b/eventmesh-runtime/src/main/java/org/apache/eventmesh/runtime/a2a/MetaAgentCardRegistry.java
new file mode 100644
index 000000000..23d971607
--- /dev/null
+++ b/eventmesh-runtime/src/main/java/org/apache/eventmesh/runtime/a2a/MetaAgentCardRegistry.java
@@ -0,0 +1,129 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.eventmesh.runtime.a2a;
+
+import org.apache.eventmesh.protocol.a2a.AgentIdentity;
+import org.apache.eventmesh.protocol.a2a.model.AgentCard;
+import org.apache.eventmesh.runtime.cluster.MetaListener;
+import org.apache.eventmesh.runtime.cluster.MetaStore;
+
+import java.nio.charset.StandardCharsets;
+import java.util.concurrent.ConcurrentHashMap;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Cluster-shared {@link AgentCardRegistry} backed by {@link MetaStore} (issue #5302
+ * Sub-PR D2). Survives runtime restarts and is shared across all Runtime instances.
+ *
+ * <p>One record per {@code agentId} at key {@code /em/agent-cards/<agentId>} with value
+ * the JSON-serialized {@link AgentCard} (the model is already Jackson-friendly via
+ * {@code @Data @Builder}). Reads are served from a per-process cache that is kept
+ * fresh by a Meta watch on the {@code /em/agent-cards/} prefix; this is the same
+ * pattern used by {@code ClusterSubscriptionStore}.</p>
+ *
+ * <p>Wire format: UTF-8 JSON. The agentId is the cache key; the AgentIdentity is not
+ * stored separately because the same agentId is the unit of addressability in the A2A
+ * gateway (the discovery topic is just {@code a2a/v1/discovery/{org}/{unit}/{agent}}
+ * — the org and unit are part of the card's metadata).</p>
+ *
+ * <p>The default Jackson {@link ObjectMapper} is used; AgentCard has no special
+ * polymorphic types so the default configuration is sufficient.</p>
+ */
+@Slf4j
+public class MetaAgentCardRegistry implements AgentCardRegistry {
+
+ /** Meta key prefix for agent cards. Cluster-shared, namespace-stable. */
+ public static final String PREFIX = "/em/agent-cards/";
+
+ private final MetaStore meta;
+ private final ObjectMapper json = new ObjectMapper();
+
+ /** agentId -> AgentCard (rebuilt from Meta on watch). */
+ private final ConcurrentHashMap<String, AgentCard> cache = new ConcurrentHashMap<>();
+
+ public MetaAgentCardRegistry(MetaStore meta) {
+ this.meta = meta;
+ // Seed the cache with the current Meta state, then keep it fresh via watch.
+ for (java.util.Map.Entry<String, String> e : meta.getWithPrefix(PREFIX).entrySet()) {
+ applyChange(e.getKey(), e.getValue(), false);
+ }
+ meta.watch(PREFIX, this::applyChange);
+ }
+
+ @Override
+ public void registerCard(AgentIdentity id, AgentCard card) {
+ if (id == null || id.getAgentId() == null || card == null) {
+ throw new IllegalArgumentException("agentId and card must be non-null");
+ }
+ String value;
+ try {
+ value = json.writeValueAsString(card);
+ } catch (com.fasterxml.jackson.core.JsonProcessingException e) {
+ throw new IllegalStateException("failed to serialize AgentCard for agentId=" + id.getAgentId(), e);
+ }
+ String key = key(id.getAgentId());
+ meta.put(key, value);
+ // Update the local cache immediately — the MetaStore watch is for
+ // cross-instance propagation and may not fire (Nacos ConfigService is
+ // per-dataId, not prefix-scan), so don't rely on it to reflect this
+ // instance's own registration back.
+ applyChange(key, value, false);
+ }
+
+ @Override
+ public boolean removeCard(AgentIdentity id) {
+ if (id == null || id.getAgentId() == null) {
+ return false;
+ }
+ String key = key(id.getAgentId());
+ boolean removed = meta.delete(key);
+ applyChange(key, null, true);
+ return removed;
+ }
+
+ @Override
+ public boolean isAgentRegistered(String agentName) {
+ return agentName != null && cache.containsKey(agentName);
+ }
+
+ @Override
+ public AgentCard getCard(String agentName) {
+ return agentName == null ? null : cache.get(agentName);
+ }
+
+ private void applyChange(String key, String value, boolean deleted) {
+ String agentId = key.substring(PREFIX.length());
+ if (deleted) {
+ cache.remove(agentId);
+ return;
+ }
+ try {
+ AgentCard card = json.readValue(value, AgentCard.class);
+ cache.put(agentId, card);
+ } catch (Exception e) {
+ log.warn("ignoring malformed agent card {}: {}", key, e.getMessage());
+ }
+ }
+
+ private static String key(String agentId) {
+ return PREFIX + agentId;
+ }
+}
diff --git a/eventmesh-runtime/src/main/java/org/apache/eventmesh/runtime/a2a/TaskExpirer.java b/eventmesh-runtime/src/main/java/org/apache/eventmesh/runtime/a2a/TaskExpirer.java
new file mode 100644
index 000000000..a26faacd1
--- /dev/null
+++ b/eventmesh-runtime/src/main/java/org/apache/eventmesh/runtime/a2a/TaskExpirer.java
@@ -0,0 +1,189 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.eventmesh.runtime.a2a;
+
+import org.apache.eventmesh.runtime.state.TaskStore;
+
+import java.util.List;
+import java.util.Objects;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicLong;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Reaper that periodically evicts expired A2A tasks from a {@link TaskStore}.
+ *
+ * <p>Issue #5302 Sub-PR D2: a task that is abandoned by the gateway (the agent
+ * is gone, the client disconnected, the A2A call timed out without an explicit
+ * cancel) lingers in the {@link TaskStore} until something deletes it. The
+ * reaper calls {@link TaskStore#expireStale(long)} on a fixed cadence and
+ * returns the expired taskIds so the caller can release any associated
+ * resources (in-memory caches, pending futures, SSE subscribers).</p>
+ *
+ * <p>The reaper is opt-in: it starts when {@link #start()} is called and stops
+ * when {@link #shutdown()} is called. The cadence and TTL are configurable; the
+ * default is to scan every 60s and expire tasks idle for more than 24h.</p>
+ *
+ * <p>The reaper is intentionally <b>not</b> wired into the gateway's start()
+ * path by default. The A2A gateway already has a per-task timeout
+ * ({@code A2AGatewayService.taskTimeoutMs}, default 2 minutes) that auto-fails
+ * tasks that miss a response. The reaper is for the OTHER stale case: a task
+ * that has a terminal status (COMPLETED / FAILED / CANCELED) but no caller
+ * ever asked to retire it. The reaper is opt-in so existing deployments that
+ * do not want a background scanner are not affected.</p>
+ */
+@Slf4j
+public final class TaskExpirer {
+
+ /** Default idle TTL: 24 hours. */
+ public static final long DEFAULT_IDLE_TTL_MS = 24L * 60L * 60L * 1000L;
+
+ /** Default scan interval: 60 seconds. */
+ public static final long DEFAULT_SCAN_INTERVAL_MS = 60L * 1000L;
+
+ private final TaskStore taskStore;
+ private final long idleTtlMs;
+ private final long scanIntervalMs;
+ private final ExpiredTaskListener listener;
+
+ private ScheduledExecutorService scheduler;
+ private final AtomicLong totalExpired = new AtomicLong();
+
+ /**
+ * Listener notified after every scan with the list of evicted taskIds.
+ * The default no-op listener is used when {@code listener} is null.
+ */
+ @FunctionalInterface
+ public interface ExpiredTaskListener {
+ void onExpired(List<String> taskIds);
+ }
+
+ /**
+ * Create a reaper with default TTL and scan interval, no listener.
+ */
+ public TaskExpirer(TaskStore taskStore) {
+ this(taskStore, DEFAULT_IDLE_TTL_MS, DEFAULT_SCAN_INTERVAL_MS, null);
+ }
+
+ /**
+ * Create a reaper with custom TTL, scan interval, and an optional listener.
+ *
+ * @param taskStore the store to scan (must be non-null)
+ * @param idleTtlMs tasks idle for longer than this are evicted (must be > 0)
+ * @param scanIntervalMs how often the reaper scans (must be > 0)
+ * @param listener notified after every scan with the evicted taskIds; may be null
+ */
+ public TaskExpirer(TaskStore taskStore, long idleTtlMs, long scanIntervalMs,
+ ExpiredTaskListener listener) {
+ this.taskStore = Objects.requireNonNull(taskStore, "taskStore");
+ if (idleTtlMs <= 0) {
+ throw new IllegalArgumentException("idleTtlMs must be > 0, got " + idleTtlMs);
+ }
+ if (scanIntervalMs <= 0) {
+ throw new IllegalArgumentException("scanIntervalMs must be > 0, got " + scanIntervalMs);
+ }
+ this.idleTtlMs = idleTtlMs;
+ this.scanIntervalMs = scanIntervalMs;
+ this.listener = listener == null ? ids -> { } : listener;
+ }
+
+ /**
+ * Start the reaper. Idempotent: a second call while the reaper is running is a
+ * no-op. The reaper is initially scheduled after one scan interval, not
+ * immediately, so a fresh gateway start has time to warm up.
+ */
+ public synchronized void start() {
+ if (scheduler != null) {
+ return;
+ }
+ scheduler = Executors.newSingleThreadScheduledExecutor(r -> {
+ Thread t = new Thread(r, "a2a-task-expirer");
+ t.setDaemon(true);
+ return t;
+ });
+ scheduler.scheduleAtFixedRate(this::scan, scanIntervalMs, scanIntervalMs, TimeUnit.MILLISECONDS);
+ log.info("TaskExpirer started: idleTtlMs={}, scanIntervalMs={}", idleTtlMs, scanIntervalMs);
+ }
+
+ /**
+ * Stop the reaper. After shutdown, the reaper can be re-started by calling
+ * {@link #start()} again.
+ */
+ public synchronized void shutdown() {
+ if (scheduler == null) {
+ return;
+ }
+ scheduler.shutdownNow();
+ try {
+ if (!scheduler.awaitTermination(5, TimeUnit.SECONDS)) {
+ log.warn("TaskExpirer scheduler did not terminate within 5s");
+ }
+ } catch (InterruptedException e) {
+ Thread.currentThread().interrupt();
+ }
+ scheduler = null;
+ log.info("TaskExpirer stopped; totalExpired={}", totalExpired.get());
+ }
+
+ /**
+ * Run a single scan. Visible for testing: a test can drive the reaper without
+ * waiting for the scheduler to fire.
+ *
+ * @return the list of evicted taskIds (empty if nothing was expired)
+ */
+ public List<String> scan() {
+ try {
+ List<String> expired = taskStore.expireStale(idleTtlMs);
+ if (!expired.isEmpty()) {
+ totalExpired.addAndGet(expired.size());
+ log.info("TaskExpirer evicted {} stale task(s); total={}", expired.size(), totalExpired.get());
+ }
+ try {
+ listener.onExpired(expired);
+ } catch (RuntimeException e) {
+ log.warn("TaskExpirer listener threw: {}", e.getMessage());
+ }
+ return expired;
+ } catch (RuntimeException e) {
+ log.warn("TaskExpirer scan failed: {}", e.getMessage());
+ return List.of();
+ }
+ }
+
+ /**
+ * @return cumulative count of expired tasks since this reaper was created.
+ */
+ public long getTotalExpired() {
+ return totalExpired.get();
+ }
+
+ public long getIdleTtlMs() {
+ return idleTtlMs;
+ }
+
+ public long getScanIntervalMs() {
+ return scanIntervalMs;
+ }
+
+ public boolean isRunning() {
+ return scheduler != null;
+ }
+}
diff --git a/eventmesh-runtime/src/test/java/org/apache/eventmesh/runtime/a2a/A2AGatewayFailureModeTest.java b/eventmesh-runtime/src/test/java/org/apache/eventmesh/runtime/a2a/A2AGatewayFailureModeTest.java
new file mode 100644
index 000000000..273e5dd9a
--- /dev/null
+++ b/eventmesh-runtime/src/test/java/org/apache/eventmesh/runtime/a2a/A2AGatewayFailureModeTest.java
@@ -0,0 +1,170 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.eventmesh.runtime.a2a;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.apache.eventmesh.protocol.a2a.AgentIdentity;
+import org.apache.eventmesh.protocol.a2a.A2AMessageTransport;
+import org.apache.eventmesh.protocol.a2a.model.AgentCard;
+import org.apache.eventmesh.runtime.cluster.InMemoryMetaStore;
+import org.apache.eventmesh.runtime.state.MetaBackedTaskStore;
+import org.apache.eventmesh.runtime.state.TaskStore;
+import org.apache.eventmesh.runtime.state.fault.MetaPartitionSwitch;
+import org.apache.eventmesh.runtime.state.fault.MetaPartitionSwitch.MetaPartitionException;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import io.cloudevents.CloudEvent;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Issue #5340 D2a acceptance item 4: failure-mode test. The Meta backing the
+ * TaskStore goes down mid-submit. The A2A gateway must surface the failure to
+ * the caller (the returned {@code CompletableFuture} completes exceptionally
+ * with the partition exception), rather than silently dropping the task or
+ * hanging forever.
+ *
+ * <p>This is the A2A-layer counterpart of the TaskStore-level failure test in
+ * {@code StateStoreDurabilityTest#TaskStoreMetaFailure}. That test pins the
+ * contract at the store interface; this test pins the contract at the gateway
+ * interface (the user-facing API).</p>
+ */
+class A2AGatewayFailureModeTest {
+
+ private InMemoryMetaStore realMeta;
+ private MetaPartitionSwitch partition;
+ private MetaBackedTaskStore taskStore;
+ private InMemoryAgentCardRegistry cardRegistry;
+ private RecordingTransport transport;
+ private A2AGatewayService gateway;
+
+ @BeforeEach
+ void setUp() throws Exception {
+ realMeta = new InMemoryMetaStore();
+ partition = new MetaPartitionSwitch(realMeta);
+ taskStore = new MetaBackedTaskStore(partition);
+ // The agent-card registry uses the in-memory test impl. The Meta
+ // partition above is on the TaskStore only, so the card registry
+ // continues to serve the registered agent for the duration of the
+ // test.
+ cardRegistry = new InMemoryAgentCardRegistry();
+ cardRegistry.registerCard(new AgentIdentity("org-1", "unit-1", "agent-A"),
+ AgentCard.builder().name("agent-A").description("test").version("1.0").build());
+ transport = new RecordingTransport();
+ gateway = new A2AGatewayService("test-ns", "gateway-1",
+ transport, taskStore, cardRegistry);
+ gateway.start();
+ }
+
+ @AfterEach
+ void tearDown() throws Exception {
+ if (gateway != null) {
+ gateway.shutdown();
+ }
+ }
+
+ @Test
+ void submitTaskSurfacesMetaFailureToCaller() throws Exception {
+ // Open the Meta partition. The next submitTask calls
+ // taskStore.createTask internally, which delegates to
+ // MetaStore.putIfAbsent and throws MetaPartitionException.
+ partition.open();
+ CompletableFuture<A2AGatewayService.TaskResult> future =
+ gateway.submitTask("agent-A", "hello", null);
+ // The gateway propagates the failure to the caller: the future is
+ // completed exceptionally with the partition exception (NOT hung
+ // forever, NOT silently dropped).
+ ExecutionException ex = assertThrows(ExecutionException.class,
+ () -> future.get(2, TimeUnit.SECONDS),
+ "submitTask must surface Meta failure within 2s, not hang");
+ Throwable cause = ex.getCause();
+ assertNotNull(cause, "the exceptional completion has a cause");
+ assertTrue(cause instanceof MetaPartitionException
+ || cause.getCause() instanceof MetaPartitionException,
+ "cause (or its cause) is MetaPartitionException; got " + cause);
+ // The TaskStore has no half-state task: the failed createTask did not
+ // write to Meta (the partition intercepted the putIfAbsent call).
+ assertNull(taskStore.getTask("task-not-created"));
+ }
+
+ @Test
+ void submitTaskSucceedsAfterMetaHeals() throws Exception {
+ // Open + heal: the first call fails, the second succeeds.
+ partition.open();
+ CompletableFuture<A2AGatewayService.TaskResult> failed =
+ gateway.submitTask("agent-A", "hello", null);
+ assertThrows(ExecutionException.class,
+ () -> failed.get(2, TimeUnit.SECONDS));
+ partition.close();
+ int beforeHeal = transport.publishedCount();
+ CompletableFuture<A2AGatewayService.TaskResult> ok =
+ gateway.submitTask("agent-A", "hello", null);
+ // The in-memory transport delivers the publish to no one (there is
+ // no subscriber for the agent's request topic in this test), so the
+ // gateway's response future is still pending. The acceptance check
+ // for this test is that submitTask returns a future without throwing
+ // synchronously and that the transport received the publish.
+ assertNotNull(ok, "submitTask returns a future after Meta heals");
+ assertEquals(beforeHeal + 1, transport.publishedCount(),
+ "transport received exactly one new publish (the healed submitTask)");
+ }
+
+ /**
+ * In-process A2A transport that records every publish and supports the
+ * {@link A2AMessageTransport} interface. There are no subscribers in this
+ * test, so publishes go to the recording map and are never delivered.
+ */
+ static final class RecordingTransport implements A2AMessageTransport {
+ private final ConcurrentHashMap<String, A2AMessageTransport.MessageCallback> subs = new ConcurrentHashMap<>();
+ private final AtomicInteger published = new AtomicInteger();
+
+ int publishedCount() {
+ return published.get();
+ }
+
+ @Override
+ public void publish(String topic, CloudEvent event) {
+ published.incrementAndGet();
+ }
+
+ @Override
+ public String subscribe(String topicPattern, A2AMessageTransport.MessageCallback callback) {
+ subs.put(topicPattern, callback);
+ return "sub-" + topicPattern;
+ }
+
+ @Override
+ public void unsubscribe(String subscriptionId) {
+ if (subscriptionId != null && subscriptionId.startsWith("sub-")) {
+ subs.remove(subscriptionId.substring("sub-".length()));
+ }
+ }
+ }
+}
diff --git a/eventmesh-runtime/src/test/java/org/apache/eventmesh/runtime/a2a/MetaAgentCardRegistryTest.java b/eventmesh-runtime/src/test/java/org/apache/eventmesh/runtime/a2a/MetaAgentCardRegistryTest.java
new file mode 100644
index 000000000..f04bb4b20
--- /dev/null
+++ b/eventmesh-runtime/src/test/java/org/apache/eventmesh/runtime/a2a/MetaAgentCardRegistryTest.java
@@ -0,0 +1,132 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.eventmesh.runtime.a2a;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.apache.eventmesh.protocol.a2a.AgentIdentity;
+import org.apache.eventmesh.protocol.a2a.model.AgentCard;
+import org.apache.eventmesh.runtime.cluster.InMemoryMetaStore;
+import org.apache.eventmesh.runtime.cluster.MetaStore;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Issue #5340 D2a: MetaAgentCardRegistry unit tests. Verifies that:
+ * <ol>
+ * <li>register / get / remove are wired through Meta;</li>
+ * <li>the registry survives a "restart" (re-open over the same Meta);</li>
+ * <li>two instances sharing the same Meta see each other's writes via watch;</li>
+ * <li>malformed JSON in Meta is logged and ignored (no cache corruption).</li>
+ * </ol>
+ */
+class MetaAgentCardRegistryTest {
+
+ private static AgentCard sampleCard(String name) {
+ return AgentCard.builder()
+ .name(name)
+ .description("sample agent: " + name)
+ .version("1.0")
+ .build();
+ }
+
+ @Test
+ void registerAndLookupArePersistedToMeta() {
+ InMemoryMetaStore meta = new InMemoryMetaStore();
+ MetaAgentCardRegistry reg = new MetaAgentCardRegistry(meta);
+ AgentIdentity id = new AgentIdentity("org-1", "unit-1", "agent-A");
+ reg.registerCard(id, sampleCard("agent-A"));
+ assertTrue(reg.isAgentRegistered("agent-A"));
+ AgentCard got = reg.getCard("agent-A");
+ assertNotNull(got);
+ assertEquals("agent-A", got.getName());
+ // The raw Meta value is a JSON object containing the card's fields.
+ String raw = meta.get("/em/agent-cards/agent-A");
+ assertNotNull(raw);
+ assertTrue(raw.contains("\"name\":\"agent-A\""),
+ "Meta value is the JSON-serialized AgentCard: " + raw);
+ }
+
+ @Test
+ void registrySurvivesWrapperRestart() {
+ InMemoryMetaStore meta = new InMemoryMetaStore();
+ MetaAgentCardRegistry first = new MetaAgentCardRegistry(meta);
+ first.registerCard(new AgentIdentity("org-1", "unit-1", "agent-A"),
+ sampleCard("agent-A"));
+ first.registerCard(new AgentIdentity("org-1", "unit-1", "agent-B"),
+ sampleCard("agent-B"));
+ // The runtime restarts; the registry wrapper is re-opened over the same Meta.
+ MetaAgentCardRegistry second = new MetaAgentCardRegistry(meta);
+ assertTrue(second.isAgentRegistered("agent-A"));
+ assertTrue(second.isAgentRegistered("agent-B"));
+ assertEquals("agent-A", second.getCard("agent-A").getName());
+ assertEquals("agent-B", second.getCard("agent-B").getName());
+ }
+
+ @Test
+ void twoInstancesShareStateViaMeta() {
+ InMemoryMetaStore meta = new InMemoryMetaStore();
+ MetaAgentCardRegistry a = new MetaAgentCardRegistry(meta);
+ MetaAgentCardRegistry b = new MetaAgentCardRegistry(meta);
+ a.registerCard(new AgentIdentity("org-1", "unit-1", "agent-A"),
+ sampleCard("agent-A"));
+ // b observes a's write via the watch prefix.
+ assertTrue(b.isAgentRegistered("agent-A"));
+ assertEquals("agent-A", b.getCard("agent-A").getName());
+ b.registerCard(new AgentIdentity("org-1", "unit-1", "agent-B"),
+ sampleCard("agent-B"));
+ assertTrue(a.isAgentRegistered("agent-B"));
+ // a removes; b observes.
+ assertTrue(a.removeCard(new AgentIdentity("org-1", "unit-1", "agent-A")));
+ assertFalse(b.isAgentRegistered("agent-A"));
+ }
+
+ @Test
+ void malformedJsonInMetaIsLoggedAndIgnored() {
+ InMemoryMetaStore meta = new InMemoryMetaStore();
+ // Pre-seed Meta with a malformed value (simulates a peer that wrote garbage).
+ meta.put("/em/agent-cards/agent-X", "this is not valid JSON");
+ // Construction must not throw; the bad entry is logged + ignored.
+ MetaAgentCardRegistry reg = new MetaAgentCardRegistry(meta);
+ assertFalse(reg.isAgentRegistered("agent-X"),
+ "malformed JSON does not produce a cache entry");
+ assertNull(reg.getCard("agent-X"));
+ // After the malformed value, legitimate register still works.
+ reg.registerCard(new AgentIdentity("org-1", "unit-1", "agent-Y"),
+ sampleCard("agent-Y"));
+ assertTrue(reg.isAgentRegistered("agent-Y"));
+ }
+
+ @Test
+ void nullArgumentsAreRejected() {
+ InMemoryMetaStore meta = new InMemoryMetaStore();
+ MetaAgentCardRegistry reg = new MetaAgentCardRegistry(meta);
+ assertThrows(IllegalArgumentException.class,
+ () -> reg.registerCard(null, sampleCard("x")));
+ assertThrows(IllegalArgumentException.class,
+ () -> reg.registerCard(new AgentIdentity("o", "u", "a"), null));
+ assertThrows(IllegalArgumentException.class,
+ () -> reg.registerCard(
+ new AgentIdentity(null, null, null), sampleCard("x")));
+ }
+}
diff --git a/eventmesh-runtime/src/test/java/org/apache/eventmesh/runtime/a2a/TaskExpirerTest.java b/eventmesh-runtime/src/test/java/org/apache/eventmesh/runtime/a2a/TaskExpirerTest.java
new file mode 100644
index 000000000..c336b8a65
--- /dev/null
+++ b/eventmesh-runtime/src/test/java/org/apache/eventmesh/runtime/a2a/TaskExpirerTest.java
@@ -0,0 +1,178 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.eventmesh.runtime.a2a;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.apache.eventmesh.runtime.cluster.InMemoryMetaStore;
+import org.apache.eventmesh.runtime.state.MetaBackedTaskStore;
+import org.apache.eventmesh.runtime.state.TaskStore;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicReference;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Issue #5340 D2a: TaskExpirer reaper unit tests. Covers the four acceptance
+ * properties from the issue body:
+ *
+ * <ol>
+ * <li>idle tasks past the TTL are evicted;</li>
+ * <li>fresh tasks are NOT evicted;</li>
+ * <li>the listener is invoked with the evicted taskIds;</li>
+ * <li>multiple scans accumulate the totalExpired counter.</li>
+ * </ol>
+ */
+class TaskExpirerTest {
+
+ /** Wait long enough for {@link TaskStore.TaskRecord#updatedAtMs} to be older than the TTL. */
+ private static void advanceClock(long ms) throws InterruptedException {
+ Thread.sleep(ms);
+ }
+
+ @Test
+ void evictsIdleTasksPastTtl() throws Exception {
+ InMemoryMetaStore meta = new InMemoryMetaStore();
+ TaskStore store = new MetaBackedTaskStore(meta);
+ // Use a 200ms TTL so the test does not need to sleep for 24h.
+ TaskExpirer reaper = new TaskExpirer(store, 200L, 60_000L, null);
+ store.createTask("stale-1", "agent-A", "client-X", "{}");
+ store.createTask("stale-2", "agent-A", "client-X", "{}");
+ store.createTask("fresh-1", "agent-B", "client-Y", "{}");
+ // No task is past the TTL yet.
+ assertEquals(0, reaper.scan().size(),
+ "no task is past the 200ms TTL immediately after creation");
+ advanceClock(250);
+ // The reaper is configured with a 60s scan interval; we drive scan() by
+ // hand so the test does not have to wait. The two stale-* tasks are now
+ // past the TTL; fresh-1 is too (the TTL is from createdAtMs/updateAtMs,
+ // which the production MetaBackedTaskStore stamps with the current
+ // wall clock at createTask). All three should be evicted in this case
+ // because the test's TTL is shorter than the wait.
+ List<String> evicted = reaper.scan();
+ assertEquals(3, evicted.size(),
+ "all three tasks are past the 200ms TTL after 250ms");
+ assertNull(store.getTask("stale-1"));
+ assertNull(store.getTask("stale-2"));
+ assertNull(store.getTask("fresh-1"));
+ assertEquals(3L, reaper.getTotalExpired());
+ }
+
+ @Test
+ void freshTasksAreNotEvicted() throws Exception {
+ InMemoryMetaStore meta = new InMemoryMetaStore();
+ TaskStore store = new MetaBackedTaskStore(meta);
+ // TTL of 10 seconds; the test runs in milliseconds, so nothing is past the TTL.
+ TaskExpirer reaper = new TaskExpirer(store, 10_000L, 60_000L, null);
+ store.createTask("t-1", "agent-A", "client-X", "{}");
+ store.createTask("t-2", "agent-A", "client-X", "{}");
+ assertEquals(0, reaper.scan().size(),
+ "no task is past the 10s TTL immediately after creation");
+ assertNotNull(store.getTask("t-1"));
+ assertNotNull(store.getTask("t-2"));
+ assertEquals(0L, reaper.getTotalExpired());
+ }
+
+ @Test
+ void listenerReceivesEvictedTaskIds() throws Exception {
+ InMemoryMetaStore meta = new InMemoryMetaStore();
+ TaskStore store = new MetaBackedTaskStore(meta);
+ AtomicReference<List<String>> lastEvicted = new AtomicReference<>();
+ AtomicInteger calls = new AtomicInteger();
+ TaskExpirer reaper = new TaskExpirer(store, 100L, 60_000L, ids -> {
+ lastEvicted.set(new ArrayList<>(ids));
+ calls.incrementAndGet();
+ });
+ store.createTask("a", "agent-A", "client-X", "{}");
+ store.createTask("b", "agent-A", "client-X", "{}");
+ advanceClock(150);
+ reaper.scan();
+ assertEquals(1, calls.get(), "listener was called exactly once");
+ assertNotNull(lastEvicted.get());
+ assertEquals(2, lastEvicted.get().size(),
+ "listener received the two evicted taskIds");
+ assertTrue(lastEvicted.get().contains("a"));
+ assertTrue(lastEvicted.get().contains("b"));
+ }
+
+ @Test
+ void startAndShutdownAreIdempotent() throws Exception {
+ InMemoryMetaStore meta = new InMemoryMetaStore();
+ TaskStore store = new MetaBackedTaskStore(meta);
+ TaskExpirer reaper = new TaskExpirer(store, 200L, 50L, null);
+ assertFalse(reaper.isRunning());
+ reaper.start();
+ assertTrue(reaper.isRunning());
+ // A second start is a no-op (idempotent).
+ reaper.start();
+ assertTrue(reaper.isRunning());
+ reaper.shutdown();
+ assertFalse(reaper.isRunning());
+ // Shutdown when already stopped is a no-op.
+ reaper.shutdown();
+ assertFalse(reaper.isRunning());
+ }
+
+ @Test
+ void backgroundScanFiresOnSchedule() throws Exception {
+ InMemoryMetaStore meta = new InMemoryMetaStore();
+ TaskStore store = new MetaBackedTaskStore(meta);
+ CountDownLatch evictionLatch = new CountDownLatch(1);
+ TaskExpirer reaper = new TaskExpirer(store, 100L, 50L, ids -> {
+ if (!ids.isEmpty()) {
+ evictionLatch.countDown();
+ }
+ });
+ store.createTask("bg-1", "agent-A", "client-X", "{}");
+ reaper.start();
+ try {
+ // The reaper schedules the first scan after one interval (50ms), then
+ // every 50ms. After ~150ms the task is past the TTL and the scan
+ // evicts it. We give the scheduler a generous 2s budget.
+ assertTrue(evictionLatch.await(2, TimeUnit.SECONDS),
+ "background scan fired within 2s and evicted bg-1");
+ assertNull(store.getTask("bg-1"));
+ } finally {
+ reaper.shutdown();
+ }
+ }
+
+ @Test
+ void invalidTtlThrows() {
+ InMemoryMetaStore meta = new InMemoryMetaStore();
+ TaskStore store = new MetaBackedTaskStore(meta);
+ assertThrows(IllegalArgumentException.class,
+ () -> new TaskExpirer(store, 0L, 1000L, null));
+ assertThrows(IllegalArgumentException.class,
+ () -> new TaskExpirer(store, -1L, 1000L, null));
+ assertThrows(IllegalArgumentException.class,
+ () -> new TaskExpirer(store, 1000L, 0L, null));
+ assertThrows(NullPointerException.class,
+ () -> new TaskExpirer(null));
+ }
+}
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@eventmesh.apache.org
For additional commands, e-mail: commits-help@eventmesh.apache.org