This is an automated email from the ASF dual-hosted git repository.
qqeasonchen pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/eventmesh.git
The following commit(s) were added to refs/heads/develop by this push:
new e526c760d docs: refine README & redesign architecture diagram
e526c760d is described below
commit e526c760de2b57e408b7e1bf612572b7bb31104b
Author: qqeasonchen <[email protected]>
AuthorDate: Mon Jul 13 19:00:12 2026 +0800
docs: refine README & redesign architecture diagram
---
README.md | 164 ++++++++++++++++++++++-----------
README.zh-CN.md | 143 ++++++++++++++++++++++++----
resources/eventmesh-architecture-7.png | Bin 0 -> 94211 bytes
3 files changed, 235 insertions(+), 72 deletions(-)
diff --git a/README.md b/README.md
index a82a7479f..e6207c504 100644
--- a/README.md
+++ b/README.md
@@ -27,27 +27,33 @@
### EventMesh Architecture
-
+
+
+EventMesh adopts a unified **CloudEvents-over-MQ** architecture. The message
queue (MQ) acts as a pure write-ahead log (WAL) for durable storage only —
there are no consumer groups, no tags, and no broker-side subscription
semantics. Instead, the stateless EventMesh Runtime owns all delivery logic:
its **SubscriptionManager** maintains the subscription registry and offset
tracking, and dispatches events with load-balance, broadcast, and multicast
semantics. Applications interact through [...]
## 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:
+Apache EventMesh is packed with features that help users build event-driven
applications with ease. Here are the highlights that set EventMesh apart:
+
+**Core architecture**
-- Built around the [CloudEvents](https://cloudevents.io) specification.
-- Rapidty extendsible interconnector layer
[connectors](https://github.com/apache/eventmesh/tree/master/eventmesh-connectors)
using
[openConnect](https://github.com/apache/eventmesh/tree/master/eventmesh-openconnect)
such as the source or sink of Saas, CloudService, and Database etc.
-- Rapidty extendsible storage layer such as [Apache
RocketMQ](https://rocketmq.apache.org), [Apache
Kafka](https://kafka.apache.org), [Apache Pulsar](https://pulsar.apache.org),
[RabbitMQ](https://rabbitmq.com), [Redis](https://redis.io).
-- Rapidty extendsible meta such as [Consul](https://consulproject.org/en/),
[Nacos](https://nacos.io), [ETCD](https://etcd.io) and
[Zookeeper](https://zookeeper.apache.org/).
-- Guaranteed at-least-once delivery.
-- Deliver events between multiple EventMesh deployments.
-- Event schema management by catalog service.
-- Powerful event orchestration by [Serverless
workflow](https://serverlessworkflow.io/) engine.
-- Powerful event filtering and transformation.
-- Rapid, seamless scalability.
-- Easy Function develop and framework integration.
+- **CloudEvents-native, end to end** — built entirely around the
[CloudEvents](https://cloudevents.io) 1.0 specification, so events stay
vendor-neutral and portable.
+- **Lightweight, language-agnostic SDK** — just three operations over plain
HTTP (`publish`, `subscribe`, `unsubscribe`); no heavyweight client, no vendor
lock-in.
+- **Runtime-owned subscription & dispatch** — subscription state and delivery
semantics (load-balance / broadcast / multicast) are managed by EventMesh
itself, not the underlying MQ, giving you consistent behavior across any
storage backend.
+- **MQ as a pure write-ahead log (WAL)** — append-only, no consumer groups, no
tags; the broker is reduced to durable storage, dramatically simplifying
operations.
+- **Guaranteed at-least-once delivery** — EventMesh owns reliability through
self-managed offsets and explicit ACK.
+- **Multiple delivery transports** — subscribers choose HTTP long-polling,
Server-Sent Events (SSE), or WebSocket push, with request-reply support.
+- **Effortless horizontal scaling** — stateless Runtime instances scale out
seamlessly with no rebalancing cost.
-## Roadmap
+**Extensibility & ecosystem**
-Please go to the [roadmap](https://eventmesh.apache.org/docs/roadmap) to get
the release history and new features of Apache EventMesh.
+- **Agent-to-Agent (A2A) collaboration** — a built-in [A2A
protocol](docs/a2a-protocol/README_EN.md) turns EventMesh into an agent
collaboration bus, bridging synchronous MCP / JSON-RPC 2.0 tool calls and
asynchronous event-driven pub/sub for LLM and multi-agent systems.
+- **Pluggable storage layer** — [Apache
RocketMQ](https://rocketmq.apache.org), [Apache
Kafka](https://kafka.apache.org), [Apache Pulsar](https://pulsar.apache.org),
[RabbitMQ](https://rabbitmq.com), [Redis](https://redis.io), and more.
+- **Pluggable interconnector layer** —
[connectors](https://github.com/apache/eventmesh/tree/master/eventmesh-connectors)
run as standalone processes acting as the source or sink of SaaS,
CloudService, Database, etc.
+- **Pluggable meta service** — [Consul](https://consulproject.org/en/),
[Nacos](https://nacos.io), [ETCD](https://etcd.io), and
[Zookeeper](https://zookeeper.apache.org/).
+- **Event schema management** via catalog service.
+- **Powerful event orchestration** through the [Serverless
workflow](https://serverlessworkflow.io/) engine.
+- **Powerful event filtering and transformation.**
## Subprojects
@@ -76,60 +82,106 @@ sudo docker pull apache/eventmesh:latest
Use the following command to start the EventMesh container:
```shell
-sudo docker run -d --name eventmesh -p 10000:10000 -p 10105:10105 -p
10205:10205 -p 10106:10106 -t apache/eventmesh:latest
+sudo docker run -d --name eventmesh -p 8080:8080 -p 8081:8081 -p 8082:8082 -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
+
+> Ports: `8080` = traffic HTTP (`/events/*` CloudEvents API), `8081` = admin
HTTP (`/admin/*`), `8082` = WebSocket push (opt-in). The connector runtime
image exposes `8083` for its optional admin port.
+#### 3. Publishing a CloudEvent
+
+Applications talk to EventMesh over the `/events/*` HTTP endpoints using
standard [CloudEvents](https://cloudevents.io) 1.0. Publish an event with an
HTTP POST (`202 Accepted` means the event was written to the WAL):
+
```shell
-POST /eventmesh/topic/create HTTP/1.1
-Host: localhost:10105
-Content-Type: application/json
-
-{
- "topic": "example-topic"
+POST /events/publish HTTP/1.1
+Host: localhost:8080
+Content-Type: application/cloudevents+json
+
+{
+ "specversion": "1.0",
+ "id": "89010a5a-3c6f-4a1e-9b2d-0f7c1f2e3a4b",
+ "source": "/example/producer",
+ "type": "com.example.order.created",
+ "subject": "orders",
+ "datacontenttype": "application/json",
+ "data": {
+ "content": "Hello, EventMesh!"
+ }
}
```
-#### 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.
+
+#### 4. Subscribing to a Topic
+
+Subscriptions are registered with EventMesh (there are no consumer groups or
tags). Provide a `clientId`, the topic, and a distribution `mode`
(`LOAD_BALANCE`, `BROADCAST`, `MULTICAST`, or `LOAD_BALANCE_STICKY`). The
response returns a `subscriptionId`:
```shell
-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"
- }
- ]
+POST /events/subscribe HTTP/1.1
+Host: localhost:8080
+Content-Type: application/json
+
+{
+ "clientId": "order-svc",
+ "topic": "orders",
+ "mode": "LOAD_BALANCE"
}
```
-#### 5. Sending Messages
-EventMesh provides multiple message sending methods, including asynchronous
sending, synchronous sending, and batch sending.
+
+#### 5. Receiving Events
+
+Subscribers can receive dispatched events through three transports. Pick
whichever fits your workload — all of them deliver the same CloudEvents and
honor EventMesh's ACK / at-least-once semantics.
+
+**a) HTTP Long-Polling** — pull events; the request blocks until events arrive
or the timeout elapses:
+
```shell
-POST /eventmesh/publish HTTP/1.1
-Host: localhost:10105
-Content-Type: application/json
-eventmesh-message-topic: example-topic
-{
- "content": "Hello, EventMesh!"
+GET /events/poll?clientId=order-svc&topics=orders&timeout=30000 HTTP/1.1
+Host: localhost:8080
+```
+
+After processing the delivered events, acknowledge them so the offset advances
(at-least-once delivery):
+
+```shell
+POST /events/ack HTTP/1.1
+Host: localhost:8080
+Content-Type: application/json
+
+{
+ "subId": "sub-123",
+ "clientId": "order-svc",
+ "topic": "orders",
+ "partition": 0,
+ "offset": 42
}
```
+
+**b) Server-Sent Events (SSE)** — server push over a long-lived HTTP
connection; the client does not poll:
+
+```shell
+GET /events/stream?clientId=order-svc&topics=orders HTTP/1.1
+Host: localhost:8080
+Accept: text/event-stream
+```
+
+**c) WebSocket** — full-duplex server push over a dedicated WebSocket port:
+
+```shell
+GET /events/stream HTTP/1.1
+Host: localhost:8082
+Upgrade: websocket
+Connection: Upgrade
+```
+
+> Long-polling, SSE, and WebSocket are interchangeable delivery transports — a
subscriber chooses one. SSE and WebSocket are pushed by the server (no polling
loop), while long-polling is client-driven. Request-reply (`POST
/events/request` + `POST /events/reply`) is also supported. The
`CloudEventsClient` Java SDK wraps all of these (`subscribe` / `subscribeSse` /
`subscribeWs`); see the [CloudEvents client
guide](docs/eventmesh-cloudevents-client-guide.md).
+
#### 6. Unsubscribing
-When you no longer need to receive messages for a topic, you can unsubscribe.
+
+When you no longer need to receive events for a topic, unsubscribe by
`clientId` (optionally with the `subscriptionId`):
+
```shell
-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"]
+POST /events/unsubscribe HTTP/1.1
+Host: localhost:8080
+Content-Type: application/json
+
+{
+ "clientId": "order-svc",
+ "topic": "orders"
}
```
## Contributing
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 9aebab3bf..700eee8d1 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -27,28 +27,34 @@
### EventMesh 架构
-
+
+
+EventMesh 采用统一的 **CloudEvents-over-MQ**
架构。消息队列（MQ）仅作为持久化的预写日志（WAL）存储层——没有消费者组（consumer group）、没有 Tag，也不承担 Broker
端的订阅语义。所有投递逻辑由无状态的 EventMesh Runtime 掌控：其中的 **SubscriptionManager**
负责维护订阅注册表与位点（offset）跟踪，并以负载均衡（load-balance）、广播（broadcast）、多播（multicast）等语义分发事件。应用通过轻量的
**HTTP + CloudEvents 1.0** SDK（`publish` / `subscribe` /
`unsubscribe`）接入，与外部系统的集成则通过 connector SPI 在独立进程的 Connector Runtime 中运行。
## 特性
-Apache EventMesh提供了许多功能来帮助用户实现他们的目标，以下是一些EventMesh的关键特点：
+Apache EventMesh 提供了丰富的能力，帮助用户轻松构建事件驱动应用。以下是让 EventMesh 与众不同的核心亮点：
+
+**核心架构**
-- 基于 [CloudEvents](https://cloudevents.io) 规范构建。
--
快速可扩展的Connector，[connectors](https://github.com/apache/eventmesh/tree/master/eventmesh-connectors)，例如作为Saas、CloudService和数据库等的source
或sink。.
-- 快速可扩展的存储层，使用
[JDBC](https://en.wikipedia.org/wiki/Java_Database_Connectivity)和[Apache
RocketMQ](https://rocketmq.apache.org), [Apache
Kafka](https://kafka.apache.org), [Apache Pulsar](https://pulsar.apache.org),
[RabbitMQ](https://rabbitmq.com), [Redis](https://redis.io),
[Pravega](https://cncf.pravega.io), 和
[RDMS](https://en.wikipedia.org/wiki/Relational_database)（正在进行中）集成。
-- 快速可扩展的控制器，例如 [Consul](https://consulproject.org/en/),
[Nacos](https://nacos.io), [ETCD](https://etcd.io) 和
[Zookeeper](https://zookeeper.apache.org/)。
-- 至少一次的可靠性投递。
-- 在多个EventMesh部署之间传递事件。
-- 通过目录服务进行事件模式管理。
-- 通过 [Serverless workflow](https://serverlessworkflow.io/) 引擎实现强大的事件编排。
-- 强大的事件过滤和转换功能。
-- 快速、无缝的可扩展性。
-- 易于函数开发和框架集成。
+- **全链路 CloudEvents 原生** —— 完全基于 [CloudEvents](https://cloudevents.io) 1.0
规范构建，事件天然厂商中立、可移植。
+- **轻量、语言无关的 SDK** —— 纯 HTTP 上仅需 `publish`、`subscribe`、`unsubscribe`
三个操作，无重客户端、无厂商锁定。
+- **订阅与分发由 Runtime 掌控** —— 订阅状态与投递语义（负载均衡 / 广播 / 多播）由 EventMesh 自主管理，而非底层
MQ，无论后端是哪种存储，行为都保持一致。
+- **MQ 仅作纯预写日志（WAL）** —— 仅追加写入，无消费者组、无 Tag；Broker 退化为纯持久化存储，大幅简化运维。
+- **保证至少一次（at-least-once）投递** —— 可靠性由 EventMesh 通过自管 offset + 显式 ACK 掌控。
+- **多种下发通道** —— 订阅者可自由选择 HTTP 长轮询、Server-Sent Events（SSE）或 WebSocket
推送，并支持请求-应答（request-reply）。
+- **轻松水平扩展** —— 无状态 Runtime 实例可无缝扩容，无重平衡成本。
-## 路线图
+**扩展性与生态**
-请前往[路线图](https://eventmesh.apache.org/docs/roadmap)查看Apache
EventMesh的版本历史和新功能。.
+- **智能体协作（A2A）** —— 内置的 [A2A 协议](docs/a2a-protocol/README.md) 将 EventMesh
打造成智能体协作总线，打通同步的 MCP / JSON-RPC 2.0
工具调用与异步的事件驱动发布订阅，原生支撑大模型（LLM）与多智能体（Multi-Agent）场景。
+- **可插拔存储层** —— [Apache RocketMQ](https://rocketmq.apache.org)、[Apache
Kafka](https://kafka.apache.org)、[Apache
Pulsar](https://pulsar.apache.org)、[RabbitMQ](https://rabbitmq.com)、[Redis](https://redis.io)
等。
+- **可插拔互联层（Connector）** ——
[connectors](https://github.com/apache/eventmesh/tree/master/eventmesh-connectors)
作为独立进程运行，可充当 SaaS、CloudService、数据库等的 source 或 sink。
+- **可插拔元数据服务** ——
[Consul](https://consulproject.org/en/)、[Nacos](https://nacos.io)、[ETCD](https://etcd.io)
和 [Zookeeper](https://zookeeper.apache.org/)。
+- **事件模式管理** —— 通过目录（catalog）服务实现。
+- **强大的事件编排** —— 基于 [Serverless workflow](https://serverlessworkflow.io/) 引擎。
+- **强大的事件过滤与转换能力。**
## 子项目
@@ -119,9 +125,11 @@ sudo docker pull apache/eventmesh:latest
使用以下命令启动 EventMesh 容器：
```shell
-sudo docker run -d --name eventmesh -p 10000:10000 -p 10105:10105 -p
10205:10205 -p 10106:10106 -t apache/eventmesh:latest
+sudo docker run -d --name eventmesh -p 8080:8080 -p 8081:8081 -p 8082:8082 -t
apache/eventmesh:latest
```
+> 端口说明：`8080` = 流量 HTTP（`/events/*` CloudEvents API），`8081` = 管理
HTTP（`/admin/*`），`8082` = WebSocket 推送（按需开启）。Connector 运行时镜像另暴露 `8083`
作为其可选的管理端口。
+
进入容器：
```shell
@@ -174,6 +182,109 @@ eventmesh-operator-59c59f4f7b-nmmlm 1/1 Running 0
3m12s
eventmesh-runtime-0-a-0 1/1 Running 0 15s
```
+### 使用 EventMesh API
+
+应用通过 `/events/*` HTTP 端点以标准 [CloudEvents](https://cloudevents.io) 1.0 与
EventMesh 交互，仅需 `publish` / `subscribe` / `unsubscribe` 等操作。订阅与分发由 EventMesh
自主管理，无需消费者组或 Tag。
+
+#### 1. 发布 CloudEvent
+
+以 CloudEvents 1.0 格式通过 HTTP POST 发布事件（返回 `202 Accepted` 表示事件已写入 WAL）：
+
+```shell
+POST /events/publish HTTP/1.1
+Host: localhost:8080
+Content-Type: application/cloudevents+json
+
+{
+ "specversion": "1.0",
+ "id": "89010a5a-3c6f-4a1e-9b2d-0f7c1f2e3a4b",
+ "source": "/example/producer",
+ "type": "com.example.order.created",
+ "subject": "orders",
+ "datacontenttype": "application/json",
+ "data": {
+ "content": "Hello, EventMesh!"
+ }
+}
+```
+
+#### 2. 订阅 Topic
+
+向 EventMesh 注册订阅（无消费者组、无 Tag）。提供 `clientId`、`topic` 以及分发模式
`mode`（`LOAD_BALANCE`、`BROADCAST`、`MULTICAST` 或 `LOAD_BALANCE_STICKY`），响应返回
`subscriptionId`：
+
+```shell
+POST /events/subscribe HTTP/1.1
+Host: localhost:8080
+Content-Type: application/json
+
+{
+ "clientId": "order-svc",
+ "topic": "orders",
+ "mode": "LOAD_BALANCE"
+}
+```
+
+#### 3. 接收事件
+
+订阅者可通过三种传输方式接收下发的事件，按业务场景任选其一——它们下发相同的 CloudEvents，并遵循 EventMesh 的 ACK /
至少一次语义。
+
+**a) HTTP 长轮询** —— 主动拉取，请求会阻塞直到有事件或超时：
+
+```shell
+GET /events/poll?clientId=order-svc&topics=orders&timeout=30000 HTTP/1.1
+Host: localhost:8080
+```
+
+处理完事件后，进行 ACK 以推进 offset（至少一次投递）：
+
+```shell
+POST /events/ack HTTP/1.1
+Host: localhost:8080
+Content-Type: application/json
+
+{
+ "subId": "sub-123",
+ "clientId": "order-svc",
+ "topic": "orders",
+ "partition": 0,
+ "offset": 42
+}
+```
+
+**b) Server-Sent Events（SSE）** —— 服务端经长连接主动推送，客户端无需轮询：
+
+```shell
+GET /events/stream?clientId=order-svc&topics=orders HTTP/1.1
+Host: localhost:8080
+Accept: text/event-stream
+```
+
+**c) WebSocket** —— 经独立 WebSocket 端口的全双工服务端推送：
+
+```shell
+GET /events/stream HTTP/1.1
+Host: localhost:8082
+Upgrade: websocket
+Connection: Upgrade
+```
+
+> 长轮询、SSE、WebSocket 是可互换的下发传输——订阅者任选其一。SSE 与 WebSocket
由服务端推送（无需轮询循环），长轮询则由客户端驱动。此外还支持请求-应答（`POST /events/request` + `POST
/events/reply`）。`CloudEventsClient` Java SDK 封装了以上全部方式（`subscribe` /
`subscribeSse` / `subscribeWs`），用法见[CloudEvents
客户端使用指引](docs/eventmesh-cloudevents-client-guide.md)。
+
+#### 4. 取消订阅
+
+当不再需要接收某 Topic 的事件时，按 `clientId` 取消订阅（可选带 `subscriptionId`）：
+
+```shell
+POST /events/unsubscribe HTTP/1.1
+Host: localhost:8080
+Content-Type: application/json
+
+{
+ "clientId": "order-svc",
+ "topic": "orders"
+}
+```
+
## 贡献
每个贡献者在推动 Apache EventMesh 的健康发展中都发挥了重要作用。我们真诚感谢所有为代码和文档作出贡献的贡献者。
diff --git a/resources/eventmesh-architecture-7.png
b/resources/eventmesh-architecture-7.png
new file mode 100644
index 000000000..2770ea563
Binary files /dev/null and b/resources/eventmesh-architecture-7.png differ
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
