Skip to content

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

Open
qqeasonchen wants to merge 8 commits into
apache:masterfrom
qqeasonchen:feat/a2a-gateway-enhancement
Open

[ISSUE #5259] Add A2A Gateway: REST API, SSE streaming, Task lifecycle, Java SDK and tests#5260
qqeasonchen wants to merge 8 commits into
apache:masterfrom
qqeasonchen:feat/a2a-gateway-enhancement

Conversation

@qqeasonchen

@qqeasonchen qqeasonchen commented Jun 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

#5259

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

Fixes #issue_id

Motivation

Explain the content here.
Explain why you want to make the changes and what problem you're trying to solve.

Modifications

Describe the modifications you've done.

Documentation

  • Does this pull request introduce a new feature? (yes / no)
  • If yes, how is the feature documented? (not applicable / docs / JavaDocs / not documented)
  • If a feature is not applicable for documentation, explain why?
  • If a feature is not documented yet in this PR, please create a followup issue for adding the documentation

@qqeasonchen
[EVENTMESH-xxx] Add A2A Gateway: REST API, SSE streaming, Task lifecy…
840b95b 
…cle, 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
@qqeasonchen qqeasonchen changed the title [ISSUE #5259] Add A2A Gateway: REST API, SSE streaming, Task lifecy… [ISSUE #5259] Add A2A Gateway: REST API, SSE streaming, Task lifecycle, Java SDK and tests Jun 28, 2026
@qqeasonchen
fix: fix Javadoc bad use of '>' in A2AGatewayDemo flow diagram
0443091 
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 apache#5260.
@qqeasonchen
fix: escape '>' in TaskRegistry Javadoc state machine diagram
eb9c6bb 
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 apache#5260 after first fix.
@qqeasonchen
fix: resolve all checkstyle violations in A2A module
a41f429 
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 apache#5260 after javadoc fixes.
@qqeasonchen
fix: correct import group ordering in A2A module
78aeaa2 
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 apache#5260
@qqeasonchen
fix: stabilize flaky testHeartbeatRefreshesTtl test
70923e5 
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 apache#5260
@qqeasonchen
fix: resolve checkstyle violations in protocol-a2a module
e5d2811 
- 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 apache#5260
@qqeasonchen
fix: static import ordering in A2ATopicFactoryTest
aca2519 
- 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 apache#5260
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@qqeasonchen