[ISSUE #5259] Add A2A Gateway: REST API, SSE streaming, Task lifecycle, Java SDK and tests (#5260)

* [EVENTMESH-xxx] Add A2A Gateway: REST API, SSE streaming, Task lifecycle, Java SDK and tests

## What's New

### A2A Gateway Runtime (eventmesh-runtime)
- A2AGatewayServer: standalone HTTP server entry point
- A2AGatewayService: core gateway logic with task timeout, agent validation,
  cancel notification, and concurrent-safe status subscribers
- A2AGatewayHttpHandler: Netty-based REST handler with CORS, SSE streaming,
  health check, task list pagination, and precise error codes
- TaskRegistry: in-memory task lifecycle management with TTL cleanup,
  CopyOnWriteArrayList for parent-child concurrency safety
- InMemoryA2AMessageTransport: default transport implementation
- A2ACardHttpHandler: enhanced with CORS headers

### A2A Protocol Plugin (eventmesh-protocol-a2a)
- A2AClient: typed Java SDK with sync/async task send, SSE streaming
  (streamTaskStatus), agent discovery, heartbeat, and SSE-aware socket timeout
- A2AMessageTransport: transport abstraction interface
- A2ATopicFactory: A2A topic convention standardization
- A2ATopicFactoryTest: unit tests

### Examples
- A2AGatewayDemo: end-to-end HTTP client demo

### Tests (all passing)
- A2AGatewayServiceTest: 15+ tests covering timeout, agent validation,
  cancel, SSE, pagination
- TaskRegistryTest: TTL, concurrent child creation, lifecycle transitions
- A2AClientServerIntegrationTest: full client-server integration with
  SSE streaming, CORS, health, heartbeat
- A2AGatewayEndToEndTest: end-to-end pipeline verification
- InMemoryA2AMessageTransportTest: transport unit tests

### Documentation (7 files updated)
- eventmesh-a2a-design.md, ARCHITECTURE.md, IMPLEMENTATION_SUMMARY.md,
  IMPLEMENTATION_SUMMARY_EN.md, TEST_RESULTS.md, README.md, README_EN.md

### Key Engineering Decisions
- Task timeout: auto-fail non-terminal tasks after configurable threshold
- SSE: heartbeat mechanism + socketTimeout(0) for long-lived connections
- Concurrency: CopyOnWriteArrayList + ConcurrentHashMap throughout
- CORS: Access-Control-Allow-Origin on all A2A endpoints
- Agent validation: reject tasks for unregistered agents

* fix: fix Javadoc bad use of '>' in A2AGatewayDemo flow diagram

Replace '-->' arrow notation with HTML entity '&gt;' in Javadoc <pre> block
to fix javadoc compilation error: 'bad use of ">".

The '>' character inside <pre> blocks in Javadoc must be escaped as '&gt;'
when it appears after '-' characters (forming '-->' which Java parser
misinterprets as an HTML comment end marker).

Fixes: CodeQL Analyze (java) and all Build CI failures in PR #5260.

* fix: escape '>' in TaskRegistry Javadoc state machine diagram

Replace '->' with '-&gt;' in Javadoc <pre> block to avoid
javadoc 'bad use of >' compilation error. The Java parser
interprets '>' in <pre> blocks as HTML tag closers.

Fixes: remaining CI build failure in PR #5260 after first fix.

* fix: resolve all checkstyle violations in A2A module

checkstyleMain (4 files, 8 violations):
- Remove unused imports (ArrayList, Objects)
- Fix import ordering per project convention: static first, then
  org.apache.eventmesh, org.apache, java, io, org.junit, com
- Replace Unicode escape (\u00b0) with literal degree symbol
- Add missing Javadoc for StatusSubscriber interface

checkstyleTest (5 files, 9 violations):
- Move static imports to top (option=top in checkstyle config)
- Fix import group ordering (io before org per groups config)
- Remove unused import (assertNull)
- Fix VariableDeclarationUsageDistance by moving declarations
  closer to first usage

Fixes: third round of CI failures in PR #5260 after javadoc fixes.

* fix: correct import group ordering in A2A module

checkstyle groups order: org.apache.eventmesh,org.apache,java,javax,org,io,net,junit,com,lombok

- Move org.junit.jupiter.* (org group) before io.cloudevents.* (io group) in test files
- Separate com.fasterxml and lombok into their own groups with blank lines in A2AGatewayService

Fixes: 4th round checkstyle violations in PR #5260

* fix: stabilize flaky testHeartbeatRefreshesTtl test

Increase TTL from 200ms to 500ms and cleanup interval from 100ms to 250ms
to prevent race condition on slow CI runners (macOS). Add assertion messages
for better debugging.

The test was flaky because Thread.sleep(100) could exceed 100ms on overloaded
CI runners, causing the cleanup to expire the card before heartbeat check.

Fixes: 5th round CI failure on macOS in PR #5260

* fix: resolve checkstyle violations in protocol-a2a module

- A2AMessageTransport.java: add Javadoc for MessageCallback interface
- A2AClient.java: remove unused java.util.function.Consumer import
- A2AClient.java: fix import order (org.apache.eventmesh, org.apache,
  java, org, io, com per checkstyle groups)
- A2AClient.java: add Javadoc for RequestHandler interface

Fixes: 6th round CI failure (protocol-a2a checkstyle) in PR #5260

* fix: static import ordering in A2ATopicFactoryTest

- Move static imports to top (option=top in checkstyle)
- Fix alphabetical order: assertFalse before assertNotNull

Fixes: 7th round CI failure (protocol-a2a checkstyleTest) in PR #5260
27 files changed
tree: 3d145e3ce975f03682c89c44842c909d4672264c
  1. .github/
  2. docker/
  3. docs/
  4. eventmesh-admin-server/
  5. eventmesh-common/
  6. eventmesh-connectors/
  7. eventmesh-examples/
  8. eventmesh-function/
  9. eventmesh-meta/
  10. eventmesh-metrics-plugin/
  11. eventmesh-openconnect/
  12. eventmesh-operator/
  13. eventmesh-protocol-plugin/
  14. eventmesh-registry/
  15. eventmesh-retry/
  16. eventmesh-runtime/
  17. eventmesh-runtime-v2/
  18. eventmesh-sdks/
  19. eventmesh-security-plugin/
  20. eventmesh-spi/
  21. eventmesh-starter/
  22. eventmesh-storage-plugin/
  23. eventmesh-trace-plugin/
  24. gradle/
  25. resources/
  26. style/
  27. tools/
  28. .asf.yaml
  29. .dockerignore
  30. .gitattributes
  31. .gitignore
  32. .gitmodules
  33. .licenserc.yaml
  34. build.gradle
  35. gradle.properties
  36. gradlew
  37. gradlew.bat
  38. install.sh
  39. LICENSE
  40. maturity.md
  41. NOTICE
  42. README.md
  43. README.zh-CN.md
  44. settings.gradle
README.md




CI status CodeCov Code Quality: Java Total Alerts

License GitHub Release Slack Status

đŸ“Ļ Documentation | 📔 Examples | âš™ī¸ Roadmap | 🌐 įŽ€äŊ“中文

Apache EventMesh

Apache EventMesh is a new generation serverless event middleware for building distributed event-driven applications.

EventMesh Architecture

EventMesh Architecture

Features

Apache EventMesh has a vast amount of features to help users achieve their goals. Let us share with you some of the key features EventMesh has to offer:

  • Built around the CloudEvents specification.
  • Rapidty extendsible interconnector layer connectors using openConnect such as the source or sink of Saas, CloudService, and Database etc.
  • Rapidty extendsible storage layer such as Apache RocketMQ, Apache Kafka, Apache Pulsar, RabbitMQ, Redis.
  • Rapidty extendsible meta such as Consul, Nacos, ETCD and Zookeeper.
  • Guaranteed at-least-once delivery.
  • Deliver events between multiple EventMesh deployments.
  • Event schema management by catalog service.
  • Powerful event orchestration by Serverless workflow engine.
  • Powerful event filtering and transformation.
  • Rapid, seamless scalability.
  • Easy Function develop and framework integration.

Roadmap

Please go to the roadmap to get the release history and new features of Apache EventMesh.

Subprojects

Quick start

This section of the guide will show you the steps to deploy EventMesh from Local, Docker, K8s.

This section guides the launch of EventMesh according to the default configuration, if you need more detailed EventMesh deployment steps, please visit the EventMesh official document.

1. Pull EventMesh Image

Use the following command line to download the latest version of EventMesh:

sudo docker pull apache/eventmesh:latest

2. Run EventMesh Runtime

Use the following command to start the EventMesh container:

sudo docker run -d --name eventmesh -p 10000:10000 -p 10105:10105 -p 10205:10205 -p 10106:10106 -t apache/eventmesh:latest

3. Creating Topics

Creating a topic is the first step in using EventMesh. You need to send an HTTP POST request to create a topic. Example Request

POST /eventmesh/topic/create HTTP/1.1  
Host: localhost:10105  
Content-Type: application/json  
  
{  
  "topic": "example-topic"  
}

4. Subscribing to Topics

After creating a topic, you can subscribe to it to receive messages. EventMesh provides two subscription methods: local subscription and remote subscription.

POST /eventmesh/subscribe/local HTTP/1.1  
Host: localhost:10105  
Content-Type: application/json  
{  
  "url": "http://localhost:8080/callback",  
  "consumerGroup": "example-consumer-group",  
  "topic": [  
    {  
      "topic": "example-topic",  
      "mode": "CLUSTERING",  
      "type": "SYNC"  
    }  
  ]  
}

5. Sending Messages

EventMesh provides multiple message sending methods, including asynchronous sending, synchronous sending, and batch sending.

POST /eventmesh/publish HTTP/1.1  
Host: localhost:10105  
Content-Type: application/json    
eventmesh-message-topic: example-topic 
{  
  "content": "Hello, EventMesh!"  
}

6. Unsubscribing

When you no longer need to receive messages for a topic, you can unsubscribe.

POST /eventmesh/unsubscribe/local HTTP/1.1  
Host: localhost:10105  
Content-Type: application/json  
{  
  "url": "http://localhost:8080/callback",  
  "consumerGroup": "example-consumer-group",  
  "topics": ["example-topic"]  
}

Contributing

GitHub repo Good Issues for newbies GitHub Help Wanted issues GitHub Help Wanted PRs GitHub repo Issues

Each contributor has played an important role in promoting the robust development of Apache EventMesh. We sincerely appreciate all contributors who have contributed code and documents.

CNCF Landscape

Apache EventMesh enriches the CNCF Cloud Native Landscape.

License

Apache EventMesh is licensed under the Apache License, Version 2.0.

Community

WeChat AssistantWeChat Public AccountSlack
Join Slack Chat(Please open an issue if this link is expired)

Bi-weekly meeting : #Tencent meeting : 346-6926-0133

Bi-weekly meeting record : bilibili

Mailing List

NameDescriptionSubscribeUnsubscribeArchive
UsersUser discussionSubscribeUnsubscribeMail Archives
DevelopmentDevelopment discussion (Design Documents, Issues, etc.)SubscribeUnsubscribeMail Archives
CommitsCommits to related repositoriesSubscribeUnsubscribeMail Archives
IssuesIssues or PRs comments and reviewsSubscribeUnsubscribeMail Archives