diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/14-https.md b/docs/design-document/14-https.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/14-https.md rename to docs/design-document/14-https.md diff --git a/docs/design-document/15-webhook.md b/docs/design-document/15-webhook.md new file mode 100644 index 0000000000..807b1a8ae9 --- /dev/null +++ b/docs/design-document/15-webhook.md @@ -0,0 +1,324 @@ +# Use Webhook to subscribe events + +## Webhook usage process + +### The first step: Configure Webhook related information in eventmesh and start + +Configuration: + +``` +# Whether to start the Webhook admin service +eventMesh.webHook.admin.start=true + +# Webhook event configuration storage mode. But currently only supports file and nacos +eventMesh.webHook.operationMode=file + +# The file path of fileMode. If you write #{eventMeshHome}, in the eventMesh root directory +eventMesh.webHook.fileMode.filePath= #{eventMeshHome}/webhook + +# The nacos storage mode. The configuration naming rule is eventMesh.webHook.nacosMode.{nacos native configuration key} For the specific configuration, please see [nacos github api](https://github.com/alibaba/nacos/blob/develop/api/src/main/java /com/alibaba/nacos/api/SystemPropertyKeyConst.java) +## address of nacos +eventMesh.webHook.nacosMode.serverAddr=127.0.0.1:8848 + +# Webhook CloudEvent sending mode. This property is the same as the eventMesh.storage.plugin.type configuration. +eventMesh.webHook.producer.connector=standalone +``` + +### The second step: Add Webhook configuration information + +Configuration information description: + +```java + /** + * The path called by the manufacturer. Manufacturer event call address, [http or https]://[domain or IP]:[port]/webhook/[callbackPath] + * for example: http://127.0.0.1:10504/webhook/test/event , The full url needs to be filled in the manufacturer call input + * callbackPath is the only + */ + private String callbackPath; + + /** + * manufacturer name, like github + */ + private String manufacturerName; + + /** + * manufacturer domain name, like www.github.com + */ + private String manufacturerDomain; + + /** + * Webhook event name, like rep-push + */ + private String manufacturerEventName; + + /** + * http header content type + */ + private String contentType = "application/json"; + + /** + * description of this WebHookConfig + */ + private String description; + + /** + * secret key, for authentication + */ + private String secret; + + /** + * userName, for HTTP authentication + */ + private String userName; + + /** + * password, for HTTP authentication + */ + private String password; + + + /** + * roll out event name, like topic to mq + */ + private String cloudEventName; + + /** + * roll out data format -> CloudEvent serialization mode + * If HTTP protocol is used, the request header contentType needs to be marked + */ + private String dataContentType = "application/json"; + + /** + * id of cloudEvent, like uuid/manufacturerEventId + */ + private String cloudEventIdGenerateMode; + +``` + +#### Add WebHook config + +path: /webhook/insertWebHookConfig + +method: POST + +contentType: application/json + +input params: + +| field | desc | type |　necessary | default　| +| -- | -- | -- | -- | -- | +| callbackPath | call address, unique address | string | Y　| null　| +| manufacturerName | manufacturer name | string | Y　| null　| +| manufacturerDomain | manufacturer domain name | string | Y　| null　| +| manufacturerEventName | manufacturer event name | string | Y　| null　| +| contentType | http connettype | string | N　| application/json　| +| description | configuration instructions | string | N　| null　| +| secret | signature string | string | N　| null　| +| userName | username | string | N　| null　| +| password | password | string | N　| null　| +| cloudEventName | cloudEvent name | string | Y　| null　| +| cloudEventIdGenerateMode | cloudEvent event object identification method, uuid or event id | string | N　|manufacturerEventId| + +E.g: + +```json +{ + "callbackPath":"/webhook/github/eventmesh/all", + "manufacturerName":"github", + "manufacturerDomain":"www.github.com", + "manufacturerEventName":"all", + "cloudEventName":"github-eventmesh" +} +``` + +Output params: 1 for success, 0 for failure + +#### Query WebHook config by callback path + +path: /webhook/queryWebHookConfigById + +method: POST + +contentType： application/json + +input params: + +| field | desc | type |　necessary | default　| +| -- | -- | -- | -- | -- | +| callbackPath | call address, unique address | string | Y　| null　| +| manufacturerName | the caller of this callbackPath belongs to | string | Y　| null　| + +E.g: + +```json +{ + "callbackPath":"/webhook/github/eventmesh/all", + "manufacturerName":"github" +} +``` + +Output params: + +| field | desc | type |　necessary | default　| +| -- | -- | -- | -- | -- | +| callbackPath | call address, unique address | string | Y　| null　| +| manufacturerName | manufacturer name | string | Y　| null　| +| manufacturerDomain | manufacturer domain name | string | Y　| null　| +| manufacturerEventName | manufacturer event name | string | Y　| null　| +| contentType | http connettype | string | N　| application/json　| +| description | configuration instructions | string | N　| null　| +| secret | signature key | string | N　| null　| +| userName | user name | string | N　| null　| +| password | password | string | N　| null　| +| cloudEventName | cloudEvent name | string | Y　| null　| +| cloudEventIdGenerateMode | cloudEvent event object identification method, uuid or event id | string | N　| manufacturerEventId　| + +#### Query WebHook config by manufacturer + +path: /webhook/queryWebHookConfigByManufacturer + +method: POST + +contentType： application/json + +input params: + +| field | desc | type |　necessary | default　| +| -- | -- | -- | -- | -- | +| manufacturerName | manufacturer name | string | Y　| null　| +| pageNum | page number of paging query | string | Y　| null　| +| pageSize | page size of each page | string | Y　| null　| + +E.g: + +```json +{ + "manufacturerName":"github", + "pageNum":1, + "pageSize":2 +} +``` + +Output params: + +| field | desc | type |　necessary | default　| +| -- | -- | -- | -- | -- | +| callbackPath | call address, unique address | string | Y　| null　| +| manufacturerName | manufacturer name | string | Y　| null　| +| manufacturerDomain | manufacturer domain name | string | Y　| null　| +| manufacturerEventName | manufacturer event name | string | Y　| null　| +| contentType | http connettype | string | N　| application/json　| +| description | configuration instructions | string | N　| null　| +| secret | signature key | string | N　| null　| +| userName | user name | string | N　| null　| +| password | password | string | N　| null　| +| cloudEventName | cloudEvent name | string | Y　| null　| +| cloudEventIdGenerateMode | cloudEvent event object identification method, uuid or event id | string | N　| manufacturerEventId　| + +#### Update WebHook config + +path: /webhook/updateWebHookConfig + +method: POST + +contentType: application/json + +input params: + +| field | desc | type | necessary | default | +| ------------------------ | ------------------------------------------------------------ | ------ | --------- | ------------------- | +| callbackPath | call address, unique address | string | Y | null | +| manufacturerName | manufacturer name | string | Y | null | +| manufacturerDomain | manufacturer domain name | string | Y | null | +| manufacturerEventName | manufacturer event name | string | Y | null | +| contentType | http connettype | string | N | application/json | +| description | configuration instructions | string | N | null | +| secret | signature string | string | N | null | +| userName | username | string | N | null | +| password | password | string | N | null | +| cloudEventName | cloudEvent name | string | Y | null | +| cloudEventIdGenerateMode | cloudEvent event object identification method, uuid or event id | string | N | manufacturerEventId | + +E.g: + +```json +{ + "callbackPath":"/webhook/github/eventmesh/all", + "manufacturerName":"github", + "manufacturerDomain":"www.github.com", + "manufacturerEventName":"all", + "cloudEventName":"github-eventmesh" +} +``` + +Output params: 1 for success, 0 for failure + +#### Delete WebHook config + +path: /webhook/deleteWebHookConfig + +method: POST + +contentType： application/json + +input params: + +| field | desc | type | necessary | default | +| ---------------- | ------------------------------------------ | ------ | --------- | ------- | +| callbackPath | call address, unique address | string | Y | null | +| manufacturerName | the caller of this callbackPath belongs to | string | Y | null | + +E.g: + +```json +{ + "callbackPath":"/webhook/github/eventmesh/all", + "manufacturerName":"github" +} +``` + +Output params: 1 for success, 0 for failure + +### The third step: Check if the configuration is successful + +1. file storage mode. Please go to the eventMesh.webHook.fileMode.filePath directory to view. The Filename is callbackPath. +2. nacos storage mode. Please go to the nacos service configured by eventMesh.webHook.nacosMode.serverAddr to see this. + +### The fourth step: Configure the consumer of cloudevent + +### The fifth step: Configure Webhook related information in the manufacturer + +> For manufacturer's operation, please refer to [Manufacturer's Webhook operation instructions](#Manufacturer's-Webhook-operation-instructions). + +## Manufacturer's Webhook operation instructions + +### github sign up + +#### The first step: Enter the corresponding project + +#### The second step: click setting + +![](/images/design-document/webhook/webhook-github-setting.png) + +#### The third step: click Webhooks + +![](/images/design-document/webhook/webhook-github-webhooks.png) + +#### The fourth step: Click on Add Webhook + +![](/images/design-document/webhook/webhook-github-add.png) + +#### The fifth step: Fill in the Webhook information + +![](/images/design-document/webhook/webhook-github-info.png) + +Payload URL: EventMesh service address and callbackPath, which must include the protocol header. For example, when the callback address `callbackPath` is `/webhook/github/eventmesh/all`, the Payload URL is `http://www.example.com:10105/webhook/github/eventmesh/all`. + +[http or https]://[domain or IP]:[port]/webhook/[callbackPath] + +Content type: http header content type + +Secret: signature string + + + diff --git a/docs/instruction/00-eclipse.md b/docs/instruction/00-eclipse.md new file mode 100644 index 0000000000..813c5dc71a --- /dev/null +++ b/docs/instruction/00-eclipse.md @@ -0,0 +1,38 @@ +# Import EventMesh into eclipse + +我们推荐使用 `Intellij IDEA` 进行开发，如果您希望使用 `Eclipse`，可以参考下面的步骤导入项目。 + +### 依赖 + +``` +64位JDK 1.8+; +Gradle至少为7.0, 推荐 7.0.* +eclipse 已安装gradle插件或者eclipse自带gradle插件 +``` + +### 下载源码 + +git init + +git clone + +### 项目编译eclipse环境 + +打开命令行终端，运行gradlew cleanEclipse eclipse + +### 配置修改 + +修改工程名称和settings.gradle 配置文件参数rootProject.name 参数一致 + +### 修改eclipse.init配置文件,配置lombok以1.18.8版本为例 + +-javaagent:lombok-1.18.8.jar +-XBootclasspath/a:lombok-1.18.8.jar + +### 202106版本eclipse,eclipse.init增加配置参数 + +--illegal-access=permit + +### 导入gradle + +打开eclipse,导入gradle项目到IDE里 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current.json b/i18n/zh/docusaurus-plugin-content-docs/current.json index 7c30b988b6..2cc8f90911 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current.json +++ b/i18n/zh/docusaurus-plugin-content-docs/current.json @@ -1,7 +1,7 @@ { "version.label": { "message": "Next", - "description": "The label for version current" + "description": "The label for current version" }, "sidebar.tutorialSidebar.category.Installation and Deployment": { "message": "安装与部署", diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/design-document/01-workflow.md b/i18n/zh/docusaurus-plugin-content-docs/current/design-document/01-workflow.md index 107ff6a99e..a92b4075fd 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/design-document/01-workflow.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/design-document/01-workflow.md @@ -1,4 +1,4 @@ -# EventMesh工作流 +# EventMesh 工作流 ## 业务场景 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/design-document/02-runtime-protocol.md b/i18n/zh/docusaurus-plugin-content-docs/current/design-document/02-runtime-protocol.md index a7cdc4786d..66615e53aa 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/design-document/02-runtime-protocol.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/design-document/02-runtime-protocol.md @@ -1,4 +1,4 @@ -# TCP协议文档 +# TCP 协议文档 #### 1. 协议格式 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/design-document/04-schema-registry.md b/i18n/zh/docusaurus-plugin-content-docs/current/design-document/04-schema-registry.md new file mode 100644 index 0000000000..7c5d228260 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/design-document/04-schema-registry.md @@ -0,0 +1,134 @@ +# EventMesh Schema Registry (OpenSchema) + +## Overview of Schema and Schema Registry + +### Schema + +A Schema stands for the description of serialization instances(string/stream/file/...) and has two properties. First, it is also in the format of serialization type. Second, it defines what requirements such serialized instances should satisfy. + +Besides describing a serialization instance, a Schema may also be used for validating whether an instance is legitimate. The reason is that it defines the ```type```(and other properties) of a serialized instance and inside keys. Taking JSON Schema for example, it could not only be referred when describing a JSON string, but also be used for validating whether a string satisfies properties defined in the schema[[1]](#References). + +Commonly, there are JSON Schema, Protobuf Schema, and Avro Schema. + +### Schema Registry + +Schema Registry is a server provides RESTful interfaces. It could receive and store Schemas from clients, as well as provide intrefaces for other clients to retrieve Schemas from it. + +It could be applied to validation process and (de-)serialization process. + +### Comparison of Schema Registry in Different Projects + +Project | Application +:---: | :--- +EMQ[[2]](#References) | Mainly in (de-)serialization process. Use "Schema Registry" and "Rule Matching" to transfer a message from one serialization format to another. +Pulsar[[3]](#References) | Mainly in validation process. Use "Schema Registry" to validate a message. +Confluentinc[[4]](#References) | In both validation and (de-)serialization process. + +## Overview of OpenSchema + +OpenSchema[[5]](#References) proposes a specification for data schema when exchanging the message and event in more and more modern cloud-native applications. It designs a RESTful interface for storing and retrieving such as Avro, JSON Schema, and Protobuf3 schemas from three aspects(subject/schema/compatibility). + +## Requirements(Goals) + +| Requirement ID | Requirement Description | Comments | +| :------------- | ------------------------------------------------------------ | ------------- | +| F-1 | In transmission, no message needs to contain schema information which bring efficiency. | Functionality | +| F-2 | The message content from producer could be validated whether serialized correctly according to schema. | Functionality | + +## Design Details + +### Architecture + +![OpenSchema](/images/design-document/schema-registry-architecture.png) + +### Process of Transferring Messages under Schema Registry + +![Process](/images/design-document/schema-registry-process.jpg) + +The highlevel process of messages transmission contains 10 steps as follows: + +- 1: Consumer subscribes "TOPIC" messages from EventMesh. +- 2: Producer registers a schema to EventMesh. +- 3: EventMesh registers a schema to Schema Registry. +- 4: Schema Registry returns the id of newly created schema; EventMesh caches such id and schema. +- 5: EventMesh returns the id of schema to Producer. +- 6: Producer patches the id in front of messages and send messages to EventMesh. +- 7: EventMesh validates the messages in the entry port and send it to EventStore; EventMesh retrieves messages from EventStore. +- 8: EventMesh unpatches the id and send it to Schema Registry(if such `` does not exists in local cache). +- 9: Schema Registry returns schema and EventMesh caches it. +- 10: EventMesh patches schema in front of messages and push it to consumer. + +## Current Progress + +### Status + +**Current state**: Developing + +**Discussion thread**: ISSUE #339 + +### Proposed Changes + +The proposal has two aspects. + +First is a separated Open Schema Registry, which includes storage and compatibility check for schema. +This proposal is under developing. + +Second is the integration of Open Schema in Eventmesh, which includes validation for schema. This proposal is to be developed. + +As for the first proposal, some developing statuses are as follows. + +#### Status Code and Exception Code + +No. | Status Code | Exception Code | Description | status +--- | :---: | :---: | :---: | :---: +1 | 401 | 40101 | Unauthorized Exception | ✔ +2 | 404 | 40401 | Schema Non- Exception | ✔ +3 | ^ | 40402 | Subject Non-exist Exception | ✔ +4 | ^ | 40403 | Version Non-exist Exception | ✔ +5 | 409 | 40901 | Compatibility Exception | ✔ +6 | 422 | 42201 | Schema Format Exception | ✔ +7 | ^ | 42202 | Subject Format Exception | ✔ +8 | ^ | 42203 | Version Format Exception | ✔ +9 | ^ | 42204 | Compatibility Format Exception | ✔ +10 | 500 | 50001 | Storage Service Exception | ✔ +11 | ^ | 50002 | Timeout Exception | ✔ + +#### API Development Status + +No. | Type | URL | response | exception | code | test +--- | --- | --- | --- | --- | --- | --- +1 | GET | /schemas/ids/{string: id} | `Schema.class` | 40101\40401\50001 | ✔ | ❌ +2 | GET | /schemas/ids/{string: id}/subjects | `SubjectAndVersion.class` | 40101\40401\50001 | ✔ | ❌ +3 | GET | /subjects | `List\` | 40101\50001 | ✔ | ❌ +4 | GET | /subjects/{string: subject}/versions | `List\` | 40101\40402\50001 | ✔ | ❌ +5 | DELETE | /subjects/(string: subject) | `List\` | 40101\40402\50001 | ✔ | ❌ +6 | GET | /subjects/(string: subject) | `Subject.class` | 40101\40402\50001 | ✔ | ❌ +7 | GET | /subjects/(string: subject)/versions/(version: version)/schema | `SubjectWithSchema.class` | 40101\40402\40403\50001 | ✔ | ❌ +8 | POST | /subjects/(string: subject)/versions | `SchemaIdResponse.class` | 40101\40901\42201\50001\50002 | - | ❌ +9 | POST | /subjects/(string: subject)/ | `Subject.class` | 40101\40901\42202\50001\50002 | ✔ | ❌ +10 | DELETE | /subjects/(string: subject)/versions/(version: version) | `int` | 40101\40402\40403\40901\50001| - | ❌ +11 | POST | /compatibility/subjects/(string: subject)/versions/(version: version) | `CompatibilityResultResponse.class` | 40101\40402\40403\42201\42203\50001| - | ❌ +12 | GET | /compatibility/(string: subject) | `Compatibility.class` | 40101\40402\50001 | ✔ | ❌ +13 | PUT | /compatibility/(string: subject) | `Compatibility.class` | 40101\40402\40901\42204\50001 | - | ❌ + +#### Overall Project Structure + +```SchemaController.java```+```SchemaService.java``` : ```OpenSchema 7.1.1~7.1.2 (API 1~2)``` + +```SubjectController.java```+```SubjectService.java``` : ```OpenSchema 7.2.1~7.2.8 (API 3~10)``` + +```CompatibilityController.java```+```CompatibilityService.java``` : ```OpenSchema 7.3.1~7.3.3 (API 11~13)``` + ```Check for Compatibility``` + +![Project Structure](/images/design-document/schema-registry-project-structure.png) + +## References + +[1] [schema validator (github.com)](https://github.com/search?q=schema+validator) + +[2] [EMQ: Schema Registry](https://www.jianshu.com/p/33e0655c642b) + +[3] [Pulsar: Schema Registry](https://mp.weixin.qq.com/s/PaB66-Si00cX80py5ig5Mw) + +[4] [confluentinc/schema-registry](https://github.com/confluentinc/schema-registry) + +[5] [openmessaging/openschema](https://github.com/openmessaging/openschema) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/design-document/15-webhook.md b/i18n/zh/docusaurus-plugin-content-docs/current/design-document/15-webhook.md index 6961725f0d..6d94efdf7e 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/design-document/15-webhook.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/design-document/15-webhook.md @@ -1,14 +1,16 @@ +# 使用 Webhook 订阅事件 +## Webhook 使用流程 -## webhook使用流程 -#### 第一步：在eventmesh配置webhook相关信息并且启动 +### 第一步：在 eventmesh 配置 Webhook 相关信息并且启动 + +配置说明： -##### 配置说明 ``` -# 是否启动webhook admin服务 +# 是否启动Webhook admin服务 eventMesh.webHook.admin.start=true -# webhook事件配置存储模式。目前只支持file与nacos +# Webhook事件配置存储模式。目前只支持file与nacos eventMesh.webHook.operationMode=file # 文件存储模式的文件存放路径，如果写上#{eventMeshHome}，在eventMesh根目录 eventMesh.webHook.fileMode.filePath= #{eventMeshHome}/webhook @@ -17,16 +19,18 @@ eventMesh.webHook.fileMode.filePath= #{eventMeshHome}/webhook ## nacos的地址 eventMesh.webHook.nacosMode.serverAddr=127.0.0.1:8848 -# webhook eventcloud 发送模式。与eventMesh.connector.plugin.type 配置一样 +# Webhook CloudEvent 发送模式。与 eventMesh.connector.plugin.type 配置一样 eventMesh.webHook.producer.connector=standalone ``` -#### 第二步：添加webhook配置信息 -配置信息说明 +### 第二步：添加 Webhook 配置信息 + +配置信息说明： + ```java /** - * 厂商调用的path。厂商事件调用地址、 [http or https ]://[域名 or IP 【厂商可以被调用】]:[端口]/webhook/[callbackPath] - * 比如：http://127.0.0.1:10504/webhook/test/event 需要把完整url填入callbackPath中 + * 厂商发送事件时调用的地址。[http or https]://[domain or IP]:[port]/webhook/[callbackPath] + * 在厂商的Webhook配置中需要填写完整url，比如：http://127.0.0.1:10504/webhook/test/event * callbackPath 唯一 * manufacturer callback path */ @@ -46,7 +50,7 @@ eventMesh.webHook.producer.connector=standalone /** * 厂商的事件名 - * webhook event name ,like rep-push + * Webhook event name ,like rep-push */ private String manufacturerEventName; @@ -83,7 +87,7 @@ eventMesh.webHook.producer.connector=standalone /** - * 事件发送到那个topic + * 事件发送到那个 topic * roll out event name ,like topic to mq */ private String cloudEventName; @@ -95,34 +99,39 @@ eventMesh.webHook.producer.connector=standalone private String dataContentType = "application/json"; /** - * cloudEvent事件对象唯一标识符识别方式，uuid或者manufacturerEventId(厂商id) + * cloudEvent 事件对象唯一标识符识别方式，uuid 或者 manufacturerEventId(厂商 id) * id of cloudEvent ,like uuid/manufacturerEventId */ private String cloudEventIdGenerateMode; ``` -##### 添加接口 +#### 添加接口 + 路径： /webhook/insertWebHookConfig -方法： POST + +方法：POST + contentType： application/json 输入参数： -| 字段 | 说明 | 类型 |　必须 | 默认值　| + +| 字段 | 说明 | 类型 | 必须 | 默认值 | | -- | -- | -- | -- | -- | -| callbackPath | 调用地址，唯一地址 | string | 是　| null　| -| manufacturerName | 厂商名 | string | 是　| null　| -| manufacturerDomain | 厂商的域名 | string | 是　| null　| -| manufacturerEventName | 厂商事件名 | string | 是　| null　| -| contentType | http connettype | string | 否　| application/json　| -| description | 配置说明 | string | 否　| null　| -| secret | 验签密钥 | string | 否　| null　| -| userName | 用户名 | string | 否　| null　| -| password | 用户密码 | string | 否　| null　| -| cloudEventName | 事件名 | string | 是　| null　| -| cloudEventIdGenerateMode | cloudEvent事件对象唯一标识符识别方式，uuid或者manufacturerEventId(厂商id) | string | 否　| manufacturerEventId　| - -列子： +| callbackPath | 调用地址，唯一地址 | string | 是 | null | +| manufacturerName | 厂商名 | string | 是 | null | +| manufacturerDomain | 厂商的域名 | string | 是 | null | +| manufacturerEventName | 厂商事件名 | string | 是 | null | +| contentType | http connettype | string | 否 | application/json | +| description | 配置说明 | string | 否 | null | +| secret | 验签密钥 | string | 否 | null | +| userName | 用户名 | string | 否 | null | +| password | 用户密码 | string | 否 | null | +| cloudEventName | 事件名 | string | 是 | null | +| cloudEventIdGenerateMode | cloudEvent 事件对象唯一标识符识别方式，uuid 或者 manufacturerEventId(厂商 id) | string | 否 | manufacturerEventId | + +例子： + ```json { "callbackPath":"/webhook/github/eventmesh/all", @@ -132,21 +141,24 @@ contentType： application/json "cloudEventName":"github-eventmesh" } ``` -输出参数：１　成功，０失败 -##### 通过callbackPath查询WebHookConfig +输出参数：1 成功，0 失败 + +#### 通过 callbackPath 查询 WebHookConfig + 路径： /webhook/queryWebHookConfigById -方法： POST + +方法：POST + contentType： application/json 输入参数： -| 字段 | 说明 | 类型 |　必须 | 默认值　| +| 字段 | 说明 | 类型 | 必须 | 默认值 | | -- | -- | -- | -- | -- | -| callbackPath | 调用地址，唯一地址 | string | 是　| null　| -| manufacturerName | 调用地址的提供方 | string | 是　| null　| - +| callbackPath | 调用地址，唯一地址 | string | 是 | null | +| manufacturerName | 调用地址的提供方 | string | 是 | null | -列子： +例子： ```json { @@ -155,37 +167,39 @@ contentType： application/json } ``` - 输出参数： -| 字段 | 说明 | 类型 |　必须 | 默认值　| + +| 字段 | 说明 | 类型 | 必须 | 默认值 | | -- | -- | -- | -- | -- | -| callbackPath | 调用地址，唯一地址 | string | 是　| null　| -| manufacturerName | 厂商名 | string | 是　| null　| -| manufacturerDomain | 厂商的域名 | string | 是　| null　| -| manufacturerEventName | 厂商事件名 | string | 是　| null　| -| contentType | http connettype | string | 否　| application/json　| -| description | 配置说明 | string | 否　| null　| -| secret | 验签密钥 | string | 否　| null　| -| userName | 用户名 | string | 否　| null　| -| password | 用户密码 | string | 否　| null　| -| cloudEventName | 事件名（） | string | 是　| null　| -| cloudEventIdGenerateMode | cloudEvent事件对象唯一标识符识别方式，uuid或者manufacturerEventId(厂商id) | string | 否　| manufacturerEventId　| - - -##### 通过manufacturer查询WebHookConfig列表 +| callbackPath | 调用地址，唯一地址 | string | 是 | null | +| manufacturerName | 厂商名 | string | 是 | null | +| manufacturerDomain | 厂商的域名 | string | 是 | null | +| manufacturerEventName | 厂商事件名 | string | 是 | null | +| contentType | http connettype | string | 否 | application/json | +| description | 配置说明 | string | 否 | null | +| secret | 验签密钥 | string | 否 | null | +| userName | 用户名 | string | 否 | null | +| password | 用户密码 | string | 否 | null | +| cloudEventName | 事件名（） | string | 是 | null | +| cloudEventIdGenerateMode | cloudEvent 事件对象唯一标识符识别方式，uuid 或者 manufacturerEventId(厂商 id) | string | 否 | manufacturerEventId | + +#### 通过 manufacturer 查询 WebHookConfig 列表 + 路径： /webhook/queryWebHookConfigByManufacturer -方法： POST + +方法：POST + contentType： application/json 输入参数： -| 字段 | 说明 | 类型 |　必须 | 默认值　| -| -- | -- | -- | -- | -- | -| manufacturerName | 厂商名 | string | 是　| null　| -| pageNum | 分页查询中的页数 | string | 是　| null　| -| pageSize | 每一页的结果数量 | string | 是　| null　| +| 字段 | 说明 | 类型 | 必须 | 默认值 | +| -- | -- | -- | -- | -- | +| manufacturerName | 厂商名 | string | 是 | null | +| pageNum | 分页查询中的页数 | string | 是 | null | +| pageSize | 每一页的结果数量 | string | 是 | null | -列子： +例子： ```json { @@ -195,26 +209,66 @@ contentType： application/json } ``` - 输出参数： -| 字段 | 说明 | 类型 |　必须 | 默认值　| + +| 字段 | 说明 | 类型 | 必须 | 默认值 | | -- | -- | -- | -- | -- | -| callbackPath | 调用地址，唯一地址 | string | 是　| null　| -| manufacturerName | 厂商名 | string | 是　| null　| -| manufacturerDomain | 厂商的域名 | string | 是　| null　| -| manufacturerEventName | 厂商事件名 | string | 是　| null　| -| contentType | http connettype | string | 否　| application/json　| -| description | 配置说明 | string | 否　| null　| -| secret | 验签密钥 | string | 否　| null　| -| userName | 用户名 | string | 否　| null　| -| password | 用户密码 | string | 否　| null　| -| cloudEventName | 事件名（） | string | 是　| null　| -| cloudEventIdGenerateMode | cloudEvent事件对象唯一标识符识别方式，uuid或者manufacturerEventId(厂商id) | string | 否　| manufacturerEventId　| - -##### 删除接口 +| callbackPath | 调用地址，唯一地址 | string | 是 | null | +| manufacturerName | 厂商名 | string | 是 | null | +| manufacturerDomain | 厂商的域名 | string | 是 | null | +| manufacturerEventName | 厂商事件名 | string | 是 | null | +| contentType | http connettype | string | 否 | application/json | +| description | 配置说明 | string | 否 | null | +| secret | 验签密钥 | string | 否 | null | +| userName | 用户名 | string | 否 | null | +| password | 用户密码 | string | 否 | null | +| cloudEventName | 事件名（） | string | 是 | null | +| cloudEventIdGenerateMode | cloudEvent 事件对象唯一标识符识别方式，uuid 或者 manufacturerEventId(厂商 id) | string | 否 | manufacturerEventId | + +#### 更新接口 + +路径： /webhook/updateWebHookConfig + +方法：POST + +contentType： application/json + +输入参数： + +| 字段 | 说明 | 类型 | 必须 | 默认值 | +| ------------------------ | ------------------------------------------------------------ | ------ | ---- | ------------------- | +| callbackPath | 调用地址，唯一地址 | string | 是 | null | +| manufacturerName | 厂商名 | string | 是 | null | +| manufacturerDomain | 厂商的域名 | string | 是 | null | +| manufacturerEventName | 厂商事件名 | string | 是 | null | +| contentType | http connettype | string | 否 | application/json | +| description | 配置说明 | string | 否 | null | +| secret | 验签密钥 | string | 否 | null | +| userName | 用户名 | string | 否 | null | +| password | 用户密码 | string | 否 | null | +| cloudEventName | 事件名 | string | 是 | null | +| cloudEventIdGenerateMode | cloudEvent 事件对象唯一标识符识别方式，uuid 或者 manufacturerEventId(厂商 id) | string | 否 | manufacturerEventId | + +例子： + +```json +{ + "callbackPath":"/webhook/github/eventmesh/all", + "manufacturerName":"github", + "manufacturerDomain":"www.github.com", + "manufacturerEventName":"all", + "cloudEventName":"github-eventmesh" +} +``` + +输出参数：1 成功，0 失败 + +#### 删除接口 路径： /webhook/deleteWebHookConfig -方法： POST + +方法：POST + contentType： application/json 输入参数： @@ -224,8 +278,7 @@ contentType： application/json | callbackPath | 调用地址，唯一地址 | string | 是 | null | | manufacturerName | 调用地址的提供方 | string | 是 | null | - -列子： +例子： ```json { @@ -234,36 +287,44 @@ contentType： application/json } ``` +输出参数：1 成功，0 失败 -输出参数：１　成功，０失败 +### 第三步：查看配置是否成功 -#### 第三步：查看配置是否成功 +1. file 存储模式。请到 eventMesh.webHook.fileMode.filePath 目录下查看。文件名为`/`转换为`.`的 callbackPath。 +2. nacos 存储模式。请到 eventMesh.webHook.nacosMode.serverAddr 配置的 nacos 服务中查看。 -1. file存储模式。请到eventMesh.webHook.fileMode.filePath 目录下查看。文件名为callbackPath转移后的 -2. nacos存储模式。请到eventMesh.webHook.nacosMode.serverAddr 配置的nacos服务去看 +### 第四步：配置 cloudevent 的消费者 -#### 第四步：配置cloudevent的消费者 +### 第五步：在厂商配置 Webhook 相关信息 -#### 第五步：在厂商配置webhook相关信息 -> 厂商操作请看【厂商webhook操作说明】 +> 厂商操作请看[厂商 Webhook 操作说明](#厂商-Webhook-操作说明) +## 厂商 Webhook 操作说明 -## 厂商webhook操作说明 ### github 注册 + #### 第一步：进入对应的项目 -#### 第二步：点击setting + +#### 第二步：点击 setting + ![](/images/design-document/webhook/webhook-github-setting.png) -#### 第三步：点击Webhooks + +#### 第三步：点击 Webhooks + ![](/images/design-document/webhook/webhook-github-webhooks.png) -#### 第四步：点击 Add webhook + +#### 第四步：点击 Add Webhook + ![](/images/design-document/webhook/webhook-github-add.png) -#### 第五步: 填写webhook信息 -![](/images/design-document/webhook/webhook-github-info.png) -Payload URL: 服务地址以及pahts。[http or https ]://[域名 or IP 【厂商可以被调用】]:[端口]/webhook/[callbackPath] -Content type：http header content type -secret: 验签字符串 +#### 第五步: 填写 Webhook 信息 + +![](/images/design-document/webhook/webhook-github-info.png) +Payload URL: EventMesh 服务地址和调用地址，需包含协议头。例如，当调用地址 `callbackPath` 为 `/webhook/github/eventmesh/all` 时，Payload URL 为 `http://www.example.com:10105/webhook/github/eventmesh/all` +Content Type: http header content type +Secret: 验签字符串 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/instruction/00-eclipse.md b/i18n/zh/docusaurus-plugin-content-docs/current/instruction/00-eclipse.md index c72c0bc6bb..0a01b02b23 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/instruction/00-eclipse.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/instruction/00-eclipse.md @@ -1,4 +1,6 @@ -# eventMesh 导入Eclipse 快速入门说明 +# 导入 Eclipse 快速入门说明 + +我们推荐使用 `Intellij IDEA` 进行开发，如果您希望使用 `Eclipse`，可以参考下面的步骤导入项目。 ### 依赖 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/instruction/01-store.md b/i18n/zh/docusaurus-plugin-content-docs/current/instruction/01-store.md index 6d520fb021..e9e82fdf66 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/instruction/01-store.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/instruction/01-store.md @@ -1,4 +1,4 @@ -# eventmesh-store 快速入门说明 +# 部署 EventMesh 的事件存储 ## 依赖 @@ -13,7 +13,7 @@ eventmesh在非standalone模式下，依赖RocketMQ作为存储层；若采用st ## 下载 -从[RocketMQ官方网站](https://rocketmq.apache.org/download/) 下载Binary代码（推荐使用4.9.*版本），这里以4.9.4为例 +从 [RocketMQ官方网站](https://rocketmq.apache.org/download/) 下载Binary代码（推荐使用4.9.*版本），这里以4.9.4为例 ``` unzip rocketmq-all-4.9.4-bin-release.zip diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/01-store-with-docker.md b/i18n/zh/docusaurus-plugin-content-docs/current/instruction/02-store-with-docker.md similarity index 96% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/01-store-with-docker.md rename to i18n/zh/docusaurus-plugin-content-docs/current/instruction/02-store-with-docker.md index 68125625b6..c6e347dcf4 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/01-store-with-docker.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/instruction/02-store-with-docker.md @@ -1,4 +1,4 @@ -# eventmesh-store 快速入门说明 +# 部署 EventMesh 的事件存储（使用 Docker） ## 依赖 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/instruction/02-runtime.md b/i18n/zh/docusaurus-plugin-content-docs/current/instruction/03-runtime.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/current/instruction/02-runtime.md rename to i18n/zh/docusaurus-plugin-content-docs/current/instruction/03-runtime.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/instruction/02-runtime-with-docker.md b/i18n/zh/docusaurus-plugin-content-docs/current/instruction/04-runtime-with-docker.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/current/instruction/02-runtime-with-docker.md rename to i18n/zh/docusaurus-plugin-content-docs/current/instruction/04-runtime-with-docker.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/instruction/03-demo.md b/i18n/zh/docusaurus-plugin-content-docs/current/instruction/05-demo.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/current/instruction/03-demo.md rename to i18n/zh/docusaurus-plugin-content-docs/current/instruction/05-demo.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/roadmap.md b/i18n/zh/docusaurus-plugin-content-docs/current/roadmap.md index a3d7695cca..33e405575a 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/roadmap.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/roadmap.md @@ -2,7 +2,7 @@ sidebar_position: 1 --- -# EventMesh产品路线图 +# EventMesh 产品路线图 下表列出了EventMesh的新特性和bug修复情况，详情请参考 [release notes](https://eventmesh.apache.org/events/release-notes/v1.4.0). diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/webhook.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/webhook.md deleted file mode 100644 index d526177cf3..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/webhook.md +++ /dev/null @@ -1,268 +0,0 @@ - - -## webhook使用流程 -#### 第一步：在eventmesh配置webhook相关信息并且启动 - -##### 配置说明 -``` -# 是否启动webhook admin服务 -eventMesh.webHook.admin.start=true - -# webhook事件配置存储模式。目前只支持file与nacos -eventMesh.webHook.operationMode=file -# 文件存储模式的文件存放路径，如果写上#{eventMeshHome}，在eventMesh根目录 -eventMesh.webHook.fileMode.filePath= #{eventMeshHome}/webhook - -# nacos存储模式，配置命名规则是eventMesh.webHook.nacosMode.{nacos 原生配置key} 具体的配置请看 [nacos github api](https://github.com/alibaba/nacos/blob/develop/api/src/main/java/com/alibaba/nacos/api/SystemPropertyKeyConst.java) -## nacos的地址 -eventMesh.webHook.nacosMode.serverAddr=127.0.0.1:8848 - -# webhook eventcloud 发送模式。与eventMesh.connector.plugin.type 配置一样 -eventMesh.webHook.producer.connector=standalone -``` - -#### 第二步：添加webhook配置信息 -配置信息说明 -```java - /** - * 厂商调用的path。厂商事件调用地址、 [http or https ]://[域名 or IP 【厂商可以被调用】]:[端口]/webhook/[callbackPath] - * 比如：http://127.0.0.1:10504/webhook/test/event 需要把全完url填入厂商调用输入中 - * callbackPath 是唯一 - * manufacturer callback path - */ - private String callbackPath; - - /** - * 厂商的名字 - * manufacturer name ,like github - */ - private String manufacturerName; - - /** - * 厂商的事件名 - * webhook event name ,like rep-push - */ - private String manufacturerEventName; - - /** - * - * http header content type - */ - private String contentType = "application/json"; - - /** - * 说明 - * description of this WebHookConfig - */ - private String description; - - /** - * 有一些厂商使用验签方式， - * secret key ,for authentication - */ - private String secret; - - /** - * 有一些厂商使用验签方式，使用账户密码方式 - * userName ,for HTTP authentication - */ - private String userName; - - /** - * 有一些厂商使用验签方式，使用账户密码方式 - * password ,for HTTP authentication - */ - private String password; - - - - /** - * 事件发送到那个topic - * roll out event name ,like topic to mq - */ - private String cloudEventName; - - /** - * roll out data format -> CloudEvent serialization mode - * If HTTP protocol is used, the request header contentType needs to be marked - */ - private String dataContentType = "application/json";; - - /** - * source of event - */ - private String cloudEventSource; - - /** - * cloudEvent事件对象唯一标识符识别方式，uuid或者manufacturerEventId(厂商id) - * id of cloudEvent ,like uuid/manufacturerEventId - */ - private String cloudEventIdGenerateMode; - -``` - -##### 添加接口 -路径： /webhook/insertWebHookConfig -方法： POST -contentType： application/json - -输入参数： -| 字段 | 说明 | 类型 |　必须 | 默认值　| -| -- | -- | -- | -- | -- | -| callbackPath | 调用地址，唯一地址 | string | 是　| null　| -| manufacturerName | 厂商名 | string | 是　| null　| -| manufacturerEventName | 厂商事件名 | string | 是　| null　| -| contentType | http connettype | string | 否　| application/json　| -| description | 配置说明 | string | 否　| null　| -| secret | 验签密钥 | string | 否　| null　| -| userName | 用户名 | string | 否　| null　| -| password | 用户密码 | string | 否　| null　| -| cloudEventName | 事件名（） | string | 是　| null　| -| cloudEventSource | 事件来源可以填写 | string | 是　| null　| -| cloudEventIdGenerateMode | cloudEvent事件对象唯一标识符识别方式，uuid或者manufacturerEventId(厂商id) | string | 否　| manufacturerEventId　| - -列子： -```json - -{ - "callbackPath":"/webhook/github/eventmesh/all", - "manufacturerName":"github", - "manufacturerEventName":"all", - "secret":"eventmesh", - "cloudEventName":"github-eventmesh", - "cloudEventSource":"github" -} - -``` -输出参数：１　成功，０失败 - -##### 删除接口 -路径： /webhook/deleteWebHookConfig -方法： POST -contentType： application/json - -输入参数： -| 字段 | 说明 | 类型 |　必须 | 默认值　| -| -- | -- | -- | -- | -- | -| callbackPath | 调用地址，唯一地址 | string | 是　| null　| - - -列子： - -```json - -{ - "callbackPath":"/webhook/github/eventmesh/all" -} - -``` - - -输出参数：１　成功，０失败 - -##### 通过callbackPath查询WebHookConfig -路径： /webhook/queryWebHookConfigById -方法： POST -contentType： application/json - -输入参数： -| 字段 | 说明 | 类型 |　必须 | 默认值　| -| -- | -- | -- | -- | -- | -| callbackPath | 调用地址，唯一地址 | string | 是　| null　| - - -列子： - -```json - -{ - "callbackPath":"/webhook/github/eventmesh/all" -} - -``` - - -输出参数： -| 字段 | 说明 | 类型 |　必须 | 默认值　| -| -- | -- | -- | -- | -- | -| callbackPath | 调用地址，唯一地址 | string | 是　| null　| -| manufacturerName | 厂商名 | string | 是　| null　| -| manufacturerEventName | 厂商事件名 | string | 是　| null　| -| contentType | http connettype | string | 否　| application/json　| -| description | 配置说明 | string | 否　| null　| -| secret | 验签密钥 | string | 否　| null　| -| userName | 用户名 | string | 否　| null　| -| password | 用户密码 | string | 否　| null　| -| cloudEventName | 事件名（） | string | 是　| null　| -| cloudEventSource | 事件来源可以填写 | string | 是　| null　| -| cloudEventIdGenerateMode | cloudEvent事件对象唯一标识符识别方式，uuid或者manufacturerEventId(厂商id) | string | 否　| manufacturerEventId　| - - -##### 通过manufacturer查询WebHookConfig列表 -路径： /webhook/queryWebHookConfigByManufacturer -方法： POST -contentType： application/json - -输入参数： -| 字段 | 说明 | 类型 |　必须 | 默认值　| -| -- | -- | -- | -- | -- | -| manufacturerName | 厂商名 | string | 是　| null　| - - -列子： - -```json - -{ - "manufacturerName":"github" -} - -``` - - -输出参数： -| 字段 | 说明 | 类型 |　必须 | 默认值　| -| -- | -- | -- | -- | -- | -| callbackPath | 调用地址，唯一地址 | string | 是　| null　| -| manufacturerName | 厂商名 | string | 是　| null　| -| manufacturerEventName | 厂商事件名 | string | 是　| null　| -| contentType | http connettype | string | 否　| application/json　| -| description | 配置说明 | string | 否　| null　| -| secret | 验签密钥 | string | 否　| null　| -| userName | 用户名 | string | 否　| null　| -| password | 用户密码 | string | 否　| null　| -| cloudEventName | 事件名（） | string | 是　| null　| -| cloudEventSource | 事件来源可以填写 | string | 是　| null　| -| cloudEventIdGenerateMode | cloudEvent事件对象唯一标识符识别方式，uuid或者manufacturerEventId(厂商id) | string | 否　| manufacturerEventId　| - - -#### 第三步：查看配置是否成功 -1. file存储模式。请到eventMesh.webHook.fileMode.filePath 目录下查看。文件名为callbackPath转移后的 -2. nacos存储模式。请到eventMesh.webHook.nacosMode.serverAddr 配置的nacos服务去看 - -#### 第四步：配置cloudevent的消费者 - - -#### 第五步：在厂商配置webhook相关信息 -> 厂商操作请看【厂商webhook操作说明】 - - -## 厂商webhook操作说明 -### github 注册 -#### 第一步：进入对应的项目 -#### 第二步：点击setting -![](/images/design-document/webhook/webhook-github-setting.png) -#### 第三步：点击Webhooks -![](/images/design-document/webhook/webhook-github-webhooks.png) -#### 第四步：点击 Add webhook -![](/images/design-document/webhook/webhook-github-add.png) -#### 第五步: 填写webhook信息 -![](/images/design-document/webhook/webhook-github-info.png) - -Payload URL: 服务地址以及pahts。[http or https ]://[域名 or IP 【厂商可以被调用】]:[端口]/webhook/[callbackPath] -Content type：http header content type -secret: 验签字符串 - - - - diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0.json b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0.json new file mode 100644 index 0000000000..913eb8be69 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0.json @@ -0,0 +1,22 @@ +{ + "version.label": { + "message": "1.9.0", + "description": "The label for current version" + }, + "sidebar.tutorialSidebar.category.Installation and Deployment": { + "message": "安装与部署", + "description": "The label for category Installation and Deployment in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.EventMesh SDK for Java": { + "message": "EventMesh SDK for Java", + "description": "The label for category EventMesh SDK for Java in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.Design Document": { + "message": "设计文档", + "description": "The label for category Design Document in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.Upgrade Guide": { + "message": "升级指南", + "description": "The label for category Upgrade Guide in sidebar tutorialSidebar" + } +} diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/01-workflow.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/01-workflow.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/01-workflow.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/01-workflow.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/02-runtime-protocol.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/02-runtime-protocol.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/02-runtime-protocol.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/02-runtime-protocol.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/03-stream.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/03-stream.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/03-stream.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/03-stream.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/05-metrics-export.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/05-metrics-export.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/05-metrics-export.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/05-metrics-export.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/06-cloudevents.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/06-cloudevents.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/06-cloudevents.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/06-cloudevents.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/07-tracing.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/07-tracing.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/07-tracing.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/07-tracing.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/08-spi.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/08-spi.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/08-spi.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/08-spi.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/09-event-bridge.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/09-event-bridge.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/09-event-bridge.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/09-event-bridge.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/10-knative-connector.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/10-knative-connector.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/10-knative-connector.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/10-knative-connector.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/11-prometheus.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/11-prometheus.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/11-prometheus.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/11-prometheus.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/12-zipkin.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/12-zipkin.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/12-zipkin.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/12-zipkin.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/13-jaeger.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/13-jaeger.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/13-jaeger.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/13-jaeger.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/design-document/https.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/14-https.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/current/design-document/https.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/14-https.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/15-webhook.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/15-webhook.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/15-webhook.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/15-webhook.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/_category_.json b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/_category_.json similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/_category_.json rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/_category_.json diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/https.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/https.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/design-document/https.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/https.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/design-document/webhook.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/webhook.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/current/design-document/webhook.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/design-document/webhook.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/00-eclipse.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/00-eclipse.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/00-eclipse.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/00-eclipse.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/instruction/01-store-with-docker.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/01-store-with-docker.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/current/instruction/01-store-with-docker.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/01-store-with-docker.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/01-store.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/01-store.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/01-store.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/01-store.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/02-runtime-with-docker.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/02-runtime-with-docker.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/02-runtime-with-docker.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/02-runtime-with-docker.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/02-runtime.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/02-runtime.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/02-runtime.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/02-runtime.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/03-demo.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/03-demo.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/03-demo.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/03-demo.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/_category_.json b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/_category_.json similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/instruction/_category_.json rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/instruction/_category_.json diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/introduction.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/introduction.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/introduction.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/introduction.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/roadmap.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/roadmap.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/roadmap.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/roadmap.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/sdk-java/01-intro.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/sdk-java/01-intro.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/sdk-java/01-intro.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/sdk-java/01-intro.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/sdk-java/02-http.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/sdk-java/02-http.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/sdk-java/02-http.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/sdk-java/02-http.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/sdk-java/03-tcp.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/sdk-java/03-tcp.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/sdk-java/03-tcp.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/sdk-java/03-tcp.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/sdk-java/04-grpc.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/sdk-java/04-grpc.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/sdk-java/04-grpc.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/sdk-java/04-grpc.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/sdk-java/_category_.json b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/sdk-java/_category_.json similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/sdk-java/_category_.json rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/sdk-java/_category_.json diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/upgrade-guide/01-upgrade-guide.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/upgrade-guide/01-upgrade-guide.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/upgrade-guide/01-upgrade-guide.md rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/upgrade-guide/01-upgrade-guide.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/upgrade-guide/_category_.json b/i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/upgrade-guide/_category_.json similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-v1.8.0/upgrade-guide/_category_.json rename to i18n/zh/docusaurus-plugin-content-docs/version-v1.9.0/upgrade-guide/_category_.json diff --git a/versioned_docs/version-v1.9.0/design-document/01-workflow.md b/versioned_docs/version-v1.9.0/design-document/01-workflow.md new file mode 100644 index 0000000000..eff287bad6 --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/01-workflow.md @@ -0,0 +1,261 @@ +# EventMesh Workflow + +## Business Problem + +Imaging you are building a simple Order Management System for an E-Commerce Store. The system should be able to receive and provision new orders from a store website. The provisioning process should be able to process all orders, handle payments, as well as process shipments. + +For high availability and high performance, you architect the system using event-driven architecture (EDA), and build microservice apps to handle store frontend, order management, payment processing, and shipment management. You deploy the whole system in a cloud environment. To handle high workloads, you leverage a messaging system to buffer the loads, and scale up multiple instances of microservices. The architecture could look similar to: + +![Workflow Use Case](/images/design-document/workflow-use-case.jpg) + +While each microservice is acting on its own event channels, EventMesh plays a crucial role of doing Event Orchestration. + +We use [CNCF Serverless Workflow](https://serverlessworkflow.io/) to describe this Event Workflow Orchestration. + +## CNCF Serverless Workflow + +CNCF Serverless Workflow defines a vendor-neutral, open-source, and fully community-driven ecosystem for defining and running DSL-based workflows that target the Serverless technology domain. + +Serverless Workflow defines a Domain Specific Language (DSL) to describe stateful and stateless workflow-based orchestrations of serverless functions and microservices. + +More details could be found in its [official github site](https://github.com/serverlessworkflow/specification) + +## EventMesh Workflow + +We leverage Serverless Workflow DSL to describe the EventMesh workflow. Based on its spec, the workflow is consists of a series of workflow states used to describe the control-flow logic. At this time we only support event related workflow states. See the supported states in [Workflow DSL Design](#workflow-dsl-design-wip). + +A `workflow state` can include applicable `actions`, or services/functions that should be invoked during workflow execution. These `actions` can reference reusable `function` definitions which define how these functions/services should be invoked. They can also reference events that trigger event-based service invocations, and events to wait for that denote completion of such event-based service invocation completion. + +In EDA solution, we usually defined our event-driven microservice using AsyncAPI. Serverless workflow `function` definitions support defining invocation semantics using AsyncAPI. See [Using Funtions for AsyncAPI Service](https://github.com/serverlessworkflow/specification/blob/main/specification.md#using-functions-for-async-api-service-invocations) for more information. + +### AsyncAPI + +AsyncAPI is an open source initiative that seeks to improve the current state of Event-Driven Architectures (EDA). +Our long-term goal is to make working with EDAs as easy as it is to work with REST APIs. +That goes from documentation to code generation, discovery to event management. +Most of the processes you apply to your REST APIs nowadays would be applicable to your event-driven/asynchronous APIs too. + +See AsyncAPI detail in the [official site](https://www.asyncapi.com/docs/guides) + +### Workflow Example + +In this example, we build the event-driven workflow of the Order management system above. + +First, we need to define AsyncAPI definitions for our microservice apps. + +- Online Store App + +```yaml +asyncapi: 2.2.0 +info: + title: Online Store application + version: '0.1.0' +channels: + store/order: + subscribe: + operationId: newStoreOrder + message: + $ref : '#/components/NewOrder' + +``` + +- Order Service + +```yaml +asyncapi: 2.2.0 +info: + title: Order Service + version: '0.1.0' +channels: + order/inbound: + publish: + operationId: sendOrder + message: + $ref : '#/components/Order' + order/outbound: + subscribe: + operationId: processedOrder + message: + $ref : '#/components/Order' +``` + +- Payment Service + +```yaml +asyncapi: 2.2.0 +info: + title: Payment Service + version: '0.1.0' +channels: + payment/inbound: + publish: + operationId: sendPayment + message: + $ref : '#/components/OrderPayment' + payment/outbound: + subscribe: + operationId: paymentReceipt + message: + $ref : '#/components/OrderPayment' +``` + +- Shipment Service + +```yaml +asyncapi: 2.2.0 +info: + title: Shipment Service + version: '0.1.0' +channels: + shipment/inbound: + publish: + operationId: sendShipment + message: + $ref : '#/components/OrderShipment' +``` + +Once that is defined, we define the order workflow that describes our Order Management business logic. + +```yaml +id: storeorderworkflow +version: '1.0' +specVersion: '0.8' +name: Store Order Management Workflow +states: + - name: Receive New Order Event + type: event + onEvents: + - eventRefs: + - NewOrderEvent + actions: + - eventRef: + triggerEventRef: OrderServiceSendEvent + resultEventRef: OrderServiceResultEvent + - eventRef: + triggerEventRef: PaymentServiceSendEvent + resultEventRef: PaymentServiceResultEvent + transition: Check Payment Status + - name: Check Payment Status + type: switch + dataConditions: + - name: Payment Successfull + condition: "${ .payment.status == 'success' }" + transition: Send Order Shipment + - name: Payment Denied + condition: "${ .payment.status == 'denied' }" + end: true + defaultCondition: + end: true + - name: Send Order Shipment + type: operation + actions: + - eventRef: + triggerEventRef: ShipmentServiceSendEvent + end: true +events: + - name: NewOrderEvent + source: file://onlineStoreApp.yaml#newStoreOrder + type: asyncapi + kind: consumed + - name: OrderServiceSendEvent + source: file://orderService.yaml#sendOrder + type: asyncapi + kind: produced + - name: OrderServiceResultEvent + source: file://orderService.yaml#processedOrder + type: asyncapi + kind: consumed + - name: PaymentServiceSendEvent + source: file://paymentService.yaml#sendPayment + type: asyncapi + kind: produced + - name: PaymentServiceResultEvent + source: file://paymentService.yaml#paymentReceipt + type: asyncapi + kind: consumed + - name: ShipmentServiceSendEvent + source: file://shipmentService.yaml#sendShipment + type: asyncapi + kind: produced +``` + +The corresponding workflow diagram is the following: + +![Workflow Diagram](/images/design-document/workflow-diagram.png) + +## EventMesh Workflow Engine + +In the following architecture diagram, the EventMesh Catalog, EventMesh Workflow Engine and EventMesh Runtime are running in three different processors. + +![Workflow Architecture](/images/design-document/workflow-architecture.jpg) + +The steps running the workflow is the followings: + +1. Deploy the Publisher and Subscriber Apps in the environment. + Describe the App APIs using AsyncAPI, generate the asyncAPI yaml. + Register the Publisher and Subscriber Apps in EventMesh Catalog using AsyncAPI. + +2. Register the Serverless Workflow DSL in EventMesh Workflow Engine. + +3. EventMesh Workflow Engine query the EventMesh Catalog for Publisher and Subscribers required in Workflow DSL `function` + +4. Event-driven Apps are publish events to EventMesh Runtime to trigger the Workflow. EventMesh Workflow Engine also publish and subscribe events for orchestrating the events. + +### EventMesh Catalog Design + +EventMesh Catalog store the Publisher, Subscriber and Channel metadata. consists of the following modules: + +- AsyncAPI Parser + + Using the SDK provided by AsyncAPI community (see [tool list](https://www.asyncapi.com/docs/community/tooling)), + parse and validated the AsyncAPI yaml inputs, and generate the AsyncAPI definition. + +- Publisher, Channel, Subscriber Modules + + From the AsyncAPI definition store the Publisher, Subscriber and Channel information. + +### EventMesh Workflow Engine Design + +EventMesh Workflow Engine consists of the following modules: + +- Workflow Parser + + Using the SDK provided by Serverless Workflow community (see supported [SDKs](https://github.com/serverlessworkflow/specification#sdks)), + parse and validated the workflow DSL inputs, and generate workflow definition. + +- Workflow Module + + It manages a workflow instance life cycle, from create, start, stop to destroy. + +- State Module + + It manages workflow state life cycle. We support the event-related states, and the supported state list below is Work-in-Progress. + + | Workflow State | Description | + | --- | --- | + | Operation | Execute the AsyncAPI functions defined in the Actions | + | Event | Check if the defined Event matched, if so execute the defined AsyncAPI functions | + | Switch | Check the event is matched with the event-conditions, and execute teh defined AsyncAPI functions | + | Parallel | Execute the defined AsyncAPI functions in parallel | + | ForEach | Iterate the inputCollection and execute the defined AsyncAPI functions | + +- Action Module + + It managed the functions inside the action. + +- Function Module + + It manages the AsyncAPI functions by creating the publisher and/or subscriber in EventMesh Runtime, and manage the publisher/subscriber life cycle. + + | AsyncAPI Operation | EventMesh Runtime | + | --- | --- | + | Publish | Publisher | + | Subscribe | Subscriber | + +- Event Module + + It manages the CloudEvents data model, including event filter, correlation and transformation using the rules defined in the workflow DSL. + +- Retry Module + + It manages the retry logic of the event publishing into EventMesh Runtime. diff --git a/versioned_docs/version-v1.9.0/design-document/02-runtime-protocol.md b/versioned_docs/version-v1.9.0/design-document/02-runtime-protocol.md new file mode 100644 index 0000000000..0b213b7e17 --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/02-runtime-protocol.md @@ -0,0 +1,401 @@ +# EventMesh Runtime Protocol + +## TCP Protocol + +### Protocol Format + +|Name|Size|Description| +|-|-|-| +|Magic Code|9 bytes|Default: `EventMesh`| +|Protocol Version|4 bytes|Default: `0000`| +|Message Size|4 bytes|The total length of the message| +|Header Size|4 bytes|The length of the message header| +|Message Body||The content of the message| + +### Message Object in the Business Logic Layer + +#### Message Composition + +The `Package` class in the [`Package.java` file](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-common/src/main/java/org/apache/eventmesh/common/protocol/tcp/Package.java) is the TCP message object used in business logic layer. The class contains the `header` and `body` fields. + +```java +public class Package { + private Header header; + private Object body; +} + +public class Header { + private Command cmd; + private int code; + private String msg; + private String seq; +} +``` + +#### Specification + +- Message Header (the `header` field): The `cmd` field in the `Header` class specifies the different types of messages. +- Message Body (the `body` field): The type of the message body should be defined based on `cmd` field in the `Header` class. + +|Command|Type of Body| +|-|-| +| HEARTBEAT_REQUEST, HEARTBEAT_RESPONSE, HELLO_RESPONSE, CLIENT_GOODBYE_REQUEST, CLIENT_GOODBYE_RESPONSE, SERVER_GOODBYE_REQUEST, SERVER_GOODBYE_RESPONSE, LISTEN_REQUEST, LISTEN_RESPONSE, UNSUBSCRIBE_REQUEST, SUBSCRIBE_RESPONSE, UNSUBSCRIBE_RESPONSE, ASYNC_MESSAGE_TO_SERVER_ACK, BROADCAST_MESSAGE_TO_SERVER_ACK|N/A| +|HELLO_REQUEST|UserAgent| +|SUBSCRIBE_REQUEST|Subscription| +| REQUEST_TO_SERVER, REQUEST_TO_CLIENT, RESPONSE_TO_SERVER, RESPONSE_TO_CLIENT, ASYNC_MESSAGE_TO_SERVER, ASYNC_MESSAGE_TO_CLIENT, BROADCAST_MESSAGE_TO_SERVER, BROADCAST_MESSAGE_TO_CLIENT, ASYNC_MESSAGE_TO_CLIENT_ACK, BROADCAST_MESSAGE_TO_CLIENT_ACK, RESPONSE_TO_CLIENT_ACK, REQUEST_TO_CLIENT_ACK|OpenMessage| +|REDIRECT_TO_CLIENT|RedirectInfo| + +### Example of Client-Server Interaction + +```java +public enum Command { + // Heartbeat + HEARTBEAT_REQUEST(0), // Client send heartbeat request to server + HEARTBEAT_RESPONSE(1), // Server reply heartbeat response to client + + // Hello + HELLO_REQUEST(2), // Client send connect request to server + HELLO_RESPONSE(3), // Server reply connect response to client + + // Disconncet + CLIENT_GOODBYE_REQUEST(4), // Client send disconnect request to server + CLIENT_GOODBYE_RESPONSE(5), // Server reply disconnect response to client + SERVER_GOODBYE_REQUEST(6), // Server send disconncet request to client + SERVER_GOODBYE_RESPONSE(7), // Client reply disconnect response to server + + // Subscribe and UnSubscribe + SUBSCRIBE_REQUEST(8), // Slient send subscribe request to server + SUBSCRIBE_RESPONSE(9), // Server reply subscribe response to client + UNSUBSCRIBE_REQUEST(10), // Client send unsubscribe request to server + UNSUBSCRIBE_RESPONSE(11), // Server reply unsubscribe response to client + + // Listen + LISTEN_REQUEST(12), // Client send listen request to server + LISTEN_RESPONSE(13), // Server reply listen response to client + + // Send sync message + REQUEST_TO_SERVER(14), // Client (Producer) send sync message to server + REQUEST_TO_CLIENT(15), // Server push sync message to client(Consumer) + REQUEST_TO_CLIENT_ACK(16), // Client (Consumer) send ack of sync message to server + RESPONSE_TO_SERVER(17), // Client (Consumer) send reply message to server + RESPONSE_TO_CLIENT(18), // Server push reply message to client(Producer) + RESPONSE_TO_CLIENT_ACK(19), // Client (Producer) send acknowledgement of reply message to server + + // Send async message + ASYNC_MESSAGE_TO_SERVER(20), // Client send async msg to server + ASYNC_MESSAGE_TO_SERVER_ACK(21), // Server reply ack of async msg to client + ASYNC_MESSAGE_TO_CLIENT(22), // Server push async msg to client + ASYNC_MESSAGE_TO_CLIENT_ACK(23), // Client reply ack of async msg to server + + // Send broadcast message + BROADCAST_MESSAGE_TO_SERVER(24), // Client send broadcast msg to server + BROADCAST_MESSAGE_TO_SERVER_ACK(25), // Server reply ack of broadcast msg to client + BROADCAST_MESSAGE_TO_CLIENT(26), // Server push broadcast msg to client + BROADCAST_MESSAGE_TO_CLIENT_ACK(27), // Client reply ack of broadcast msg to server + + // Redirect + REDIRECT_TO_CLIENT(30), // Server send redirect instruction to client +} +``` + +### Client-Initiated Interaction + +|Scene|Client Request|Server Response| +|-|-|-| +| Hello | HELLO_REQUEST | HELLO_RESPONSE | | +| Heartbeat | HEARTBEAT_REQUEST | HEARTBEAT_RESPONSE | | +| Subscribe | SUBSCRIBE_REQUEST | SUBSCRIBE_RESPONSE | | +| Unsubscribe | UNSUBSCRIBE_REQUEST | UNSUBSCRIBE_RESPONSE | | +| Listen | LISTEN_REQUEST | LISTEN_RESPONSE | | +| Send sync message | REQUEST_TO_SERVER | RESPONSE_TO_CLIENT | | +| Send the response of sync message| RESPONSE_TO_SERVER | N/A | | +| Send async message | ASYNC_MESSAGE_TO_SERVER | ASYNC_MESSAGE_TO_SERVER_ACK | | +| Send broadcast message | BROADCAST_MESSAGE_TO_SERVER | BROADCAST_MESSAGE_TO_SERVER_ACK | | +| Client start to disconnect | CLIENT_GOODBYE_REQUEST | CLIENT_GOODBYE_RESPONSE | | + +### Server-Initiated Interaction + +|Scene|Server Request|Client Response|Remark| +|-|-| ------------------------------- | ---- | +| Push sync message to client | REQUEST_TO_CLIENT | REQUEST_TO_CLIENT_ACK | | +| Push the response message of sync message to client | RESPONSE_TO_CLIENT | RESPONSE_TO_CLIENT_ACK | | +| Push async message to client | ASYNC_MESSAGE_TO_CLIENT | ASYNC_MESSAGE_TO_CLIENT_ACK | | +| Push broadcast message to client | BROADCAST_MESSAGE_TO_CLIENT | BROADCAST_MESSAGE_TO_CLIENT_ACK | | +| Server start to disconnect | SERVER_GOODBYE_REQUEST | -- | | +| Server send redirect | REDIRECT_TO_CLIENT | -- | | + +### Type of Message + +#### Sync Message + +![Sync Message](/images/design-document/sync-message.png) + +#### Async Message + +![Async Message](/images/design-document/async-message.png) + +#### Boardcast Message + +![Boardcast Message](/images/design-document/broadcast-message.png) + +## HTTP Protocol + +### Protocol Format + +The `EventMeshMessage` class in the [`EventMeshMessage.java` file](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-common/src/main/java/org/apache/eventmesh/common/EventMeshMessage.java) is the HTTP message definition of EventMesh Runtime. + +```java +public class EventMeshMessage { + private String bizSeqNo; + + private String uniqueId; + + private String topic; + + private String content; + + private Map prop; + + private final long createTime = System.currentTimeMillis(); +} +``` + +### HTTP Post Request + +#### Heartbeat Message + +##### Request Header + +| Key | Description | +| -------- | ---------------- | +| Env | Enviroment of Client | +| Region | Region of Client | +| Idc | IDC of Client | +| Dcn | DCN of Client | +| Sys | Subsystem ID of Client | +| Pid | Client Process ID | +| Ip | Client Ip | +| Username | Client username | +| Passwd | Client password | +| Version | Protocol version | +| Language | Develop language | +| Code | Request Code | + +##### Request Body + +|Key|Description| +|-|-| +|`clientType`|`ClientType.PUB` for Producer, `ClientType.SUB` for Consumer| +|`heartbeatEntities`|Topic, URL, etc.| + +#### Subscribe Message + +##### Request Header + +The request header of the Subscribe message is identical to the request header of the Heartbeat message. + +##### Request Body + +|Key|Description| +|-|-| +|`topic`|The topic that the client requested to subscribe to| +|`url`|The callback URL of the client| + +#### Unsubscribe Message + +##### Request Header + +The request header of the Unsubscribe message is identical to the request header of the Heartbeat message. + +##### Request Body + +The request body of the Unsubscribe message is identical to the request body of the Subscribe message. + +#### Send Async Message + +##### Request Header + +The request header of the Send Async message is identical to the request header of the Heartbeat message. + +##### Request Body + +|Key|Description| +|-|-| +|`topic`|Topic of the message| +|`content`|The content of the message| +|`ttl`|The time-to-live of the message| +|`bizSeqNo`|The biz sequence number of the message| +|`uniqueId`|The unique ID of the message| + +### Client-Initiated Interaction + +|Scene|Client Request|Server Response|Remark| +|-|-|-|-| +| Heartbeat | HEARTBEAT(203) | SUCCESS(0) or EVENTMESH_HEARTBEAT_ERROR(19) | | +| Subscribe | SUBSCRIBE(206) | SUCCESS(0) or EVENTMESH_SUBSCRIBE_ERROR(17) | | +| Unsubscribe | UNSUBSCRIBE(207) | SUCCESS(0) or EVENTMESH_UNSUBSCRIBE_ERROR(18) | | +| Send async message | MSG_SEND_ASYNC(104) | SUCCESS(0) or EVENTMESH_SEND_ASYNC_MSG_ERR(14) | | + +### Server-Initiated Interaction + +|Scene|Client Request|Server Response|Remark| +|-|-|-|-| +|Push async message to the client|HTTP_PUSH_CLIENT_ASYNC(105)|`retCode`|The push is successful if the `retCode` is `0`| + +## gRPC Protocol + +### Protobuf + +The `eventmesh-protocol-gprc` module contains the [protobuf definition file](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-protocol-plugin/eventmesh-protocol-grpc/src/main/proto/eventmesh-client.proto) of the Eventmesh client. The `gradle build` command generates the gRPC codes, which are located in `/build/generated/source/proto/main`. The generated gRPC codes are used in `eventmesh-sdk-java` module. + +### Data Model + +#### Message + +The message data model used by `publish()`, `requestReply()` and `broadcast()` APIs is defined as: + +```protobuf +message RequestHeader { + string env = 1; + string region = 2; + string idc = 3; + string ip = 4; + string pid = 5; + string sys = 6; + string username = 7; + string password = 8; + string language = 9; + string protocolType = 10; + string protocolVersion = 11; + string protocolDesc = 12; +} + +message SimpleMessage { + RequestHeader header = 1; + string producerGroup = 2; + string topic = 3; + string content = 4; + string ttl = 5; + string uniqueId = 6; + string seqNum = 7; + string tag = 8; + map properties = 9; +} + +message BatchMessage { + RequestHeader header = 1; + string producerGroup = 2; + string topic = 3; + + message MessageItem { + string content = 1; + string ttl = 2; + string uniqueId = 3; + string seqNum = 4; + string tag = 5; + map properties = 6; + } + + repeated MessageItem messageItem = 4; +} + +message Response { + string respCode = 1; + string respMsg = 2; + string respTime = 3; +} +``` + +#### Subscription + +The subscription data model used by `subscribe()` and `unsubscribe()` APIs is defined as: + +```protobuf +message Subscription { + RequestHeader header = 1; + string consumerGroup = 2; + + message SubscriptionItem { + enum SubscriptionMode { + CLUSTERING = 0; + BROADCASTING = 1; + } + + enum SubscriptionType { + ASYNC = 0; + SYNC = 1; + } + + string topic = 1; + SubscriptionMode mode = 2; + SubscriptionType type = 3; + } + + repeated SubscriptionItem subscriptionItems = 3; + string url = 4; +} +``` + +#### Heartbeat + +The heartbeat data model used by the `heartbeat()` API is defined as: + +```protobuf +message Heartbeat { + enum ClientType { + PUB = 0; + SUB = 1; + } + + RequestHeader header = 1; + ClientType clientType = 2; + string producerGroup = 3; + string consumerGroup = 4; + + message HeartbeatItem { + string topic = 1; + string url = 2; + } + + repeated HeartbeatItem heartbeatItems = 5; +} +``` + +### Service Definition + +#### Event Publisher Service + +```protobuf +service PublisherService { + // Async event publish + rpc publish(SimpleMessage) returns (Response); + + // Sync event publish + rpc requestReply(SimpleMessage) returns (Response); + + // Batch event publish + rpc batchPublish(BatchMessage) returns (Response); +} +``` + +#### Event Consumer Service + +```protobuf +service ConsumerService { + // The subscribed event will be delivered by invoking the webhook url in the Subscription + rpc subscribe(Subscription) returns (Response); + + // The subscribed event will be delivered through stream of Message + rpc subscribeStream(Subscription) returns (stream SimpleMessage); + + rpc unsubscribe(Subscription) returns (Response); +} +``` + +#### Client Hearthbeat Service + +```protobuf +service HeartbeatService { + rpc heartbeat(Heartbeat) returns (Response); +} +``` diff --git a/versioned_docs/version-v1.9.0/design-document/03-stream.md b/versioned_docs/version-v1.9.0/design-document/03-stream.md new file mode 100644 index 0000000000..7f2534a5d4 --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/03-stream.md @@ -0,0 +1,118 @@ +# EventMesh Stream + +## Overview of Event Streaming + +Event Streaming is an implementation of Pub/Sub architecture pattern,it consist of + +- Message or Event: Change of State. + +- Topic: Partition in messaging middle ware broker. + +- Consumer: Can subscribe to read events from broker topic. + +- Producer: Generate events + +Streaming of event is continuous flow of events in order to maintain order between events, events flow should be in a specific direction means from producers to consumers. + +## Requirements + +### Functional Requirements + +| Requirement ID | Requirement Description | Comments | +| -------------- | ----------------------- | -------- | +| F-1 | EventMesh users should be able to achieve Event Streaming functionality in EventMesh | Functionality | +| F-2 | EventMesh users can apply dynamic user specific logics for routing, filter, transformation etc | Functionality | + +## Design Details + +We are introduce EventMesh Stream component allow us to use programming model and binder abstractions +from Spring Cloud Stream natively within Apache Camel. + +[Spring-Cloud-Stream](https://spring.io/projects/spring-cloud-stream) Spring Cloud Stream is a framework for building +highly scalable event-driven microservices connected with shared messaging systems. + +[Apache Camel](https://camel.apache.org/) Camel is an Open Source integration framework that empowers you to quickly +and easily integrate various systems consuming or producing data. + +## Architecture + +![Stream Architecture](/images/design-document/stream-architecture.png) + +## Design + +### EventMesh-Stream Component + +- Event +- Event Channel +- Event EndPoint +- Event Pipes & Filters +- Event Routes +- Event Converter + +#### Event + +> A event is the smallest unit for transmitting data in system. It structure divided into headers, body and attachments. + +#### Event Channel + +> A event channel is a logical channel in system, we are achieving by Spring Cloud Stream programming model, it has abstract functionality around messaging channels(As of now Spring `MessageChannel`). + +#### Event EndPoint + +> A event endpoint is the interface between an application and a messaging system. We can define two types of endpoint + +- Consumer endpoint - Appears at start of a route and read incoming events from an incoming channel. +- Producer endpoint - Appears at end of a route and write incoming events to an outgoing channel. + +#### Event Pipes & Filters + +> We can construct a route by creating chain of filters( Apache Camel `Processor`), where the output of one filter is fed into input for next filter in the pipeline. +The main advantage of the pipeline is that you can create complex event processing logic. + +#### Event Routes + +> A event router, is a type of filter on consumer and redirect them to the appropriate target endpoint based on a decision criteria. + +#### Event Converter + +> The event converter that modifies the contents of a event, translating it to a different format(i.e cloudevents -> Event (Camel) -> Binder Message(Spring Message) and vice versa). + +## EventMesh-Stream Component Interfaces + +### Component + +Component interface is the primary entry point, you can use Component object as a factory to create EndPoint objects. + +![Stream Component Interface](/images/design-document/stream-component-interface.png) + +### EndPoint + +EndPoint which is act as factories for creating Consumer, Producer and Event objects. + +- `createConsumer()` — Creates a consumer endpoint, which represents the source endpoint at the beginning of a route. +- `createProducer()` — Creates a producer endpoint, which represents the target endpoint at the end of a route. + +![Stream Component Routes](/images/design-document/stream-component-routes.png) + +#### Producer + +User can create following types of producer +> Synchronous Producer-Processing thread blocks until the producer has finished the event processing. + +![Stream Sync Producer](/images/design-document/stream-sync-producer.png) + +In future Producer Types: + +- Asynchronous Producer - Producer process the event in a sub-thread. + +#### Consumer + +User can create following types of consumer +> Event-driven consumer-the processing of an incoming request is initiated when message binder call a method in consumer. + +![Stream Event-Driven Consumer](/images/design-document/stream-event-driven-consumer.png) + +In the Future + +- Scheduled poll consumer +- Custom polling consumer diff --git a/versioned_docs/version-v1.9.0/design-document/04-schema-registry.md b/versioned_docs/version-v1.9.0/design-document/04-schema-registry.md new file mode 100644 index 0000000000..7c5d228260 --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/04-schema-registry.md @@ -0,0 +1,134 @@ +# EventMesh Schema Registry (OpenSchema) + +## Overview of Schema and Schema Registry + +### Schema + +A Schema stands for the description of serialization instances(string/stream/file/...) and has two properties. First, it is also in the format of serialization type. Second, it defines what requirements such serialized instances should satisfy. + +Besides describing a serialization instance, a Schema may also be used for validating whether an instance is legitimate. The reason is that it defines the ```type```(and other properties) of a serialized instance and inside keys. Taking JSON Schema for example, it could not only be referred when describing a JSON string, but also be used for validating whether a string satisfies properties defined in the schema[[1]](#References). + +Commonly, there are JSON Schema, Protobuf Schema, and Avro Schema. + +### Schema Registry + +Schema Registry is a server provides RESTful interfaces. It could receive and store Schemas from clients, as well as provide intrefaces for other clients to retrieve Schemas from it. + +It could be applied to validation process and (de-)serialization process. + +### Comparison of Schema Registry in Different Projects + +Project | Application +:---: | :--- +EMQ[[2]](#References) | Mainly in (de-)serialization process. Use "Schema Registry" and "Rule Matching" to transfer a message from one serialization format to another. +Pulsar[[3]](#References) | Mainly in validation process. Use "Schema Registry" to validate a message. +Confluentinc[[4]](#References) | In both validation and (de-)serialization process. + +## Overview of OpenSchema + +OpenSchema[[5]](#References) proposes a specification for data schema when exchanging the message and event in more and more modern cloud-native applications. It designs a RESTful interface for storing and retrieving such as Avro, JSON Schema, and Protobuf3 schemas from three aspects(subject/schema/compatibility). + +## Requirements(Goals) + +| Requirement ID | Requirement Description | Comments | +| :------------- | ------------------------------------------------------------ | ------------- | +| F-1 | In transmission, no message needs to contain schema information which bring efficiency. | Functionality | +| F-2 | The message content from producer could be validated whether serialized correctly according to schema. | Functionality | + +## Design Details + +### Architecture + +![OpenSchema](/images/design-document/schema-registry-architecture.png) + +### Process of Transferring Messages under Schema Registry + +![Process](/images/design-document/schema-registry-process.jpg) + +The highlevel process of messages transmission contains 10 steps as follows: + +- 1: Consumer subscribes "TOPIC" messages from EventMesh. +- 2: Producer registers a schema to EventMesh. +- 3: EventMesh registers a schema to Schema Registry. +- 4: Schema Registry returns the id of newly created schema; EventMesh caches such id and schema. +- 5: EventMesh returns the id of schema to Producer. +- 6: Producer patches the id in front of messages and send messages to EventMesh. +- 7: EventMesh validates the messages in the entry port and send it to EventStore; EventMesh retrieves messages from EventStore. +- 8: EventMesh unpatches the id and send it to Schema Registry(if such `` does not exists in local cache). +- 9: Schema Registry returns schema and EventMesh caches it. +- 10: EventMesh patches schema in front of messages and push it to consumer. + +## Current Progress + +### Status + +**Current state**: Developing + +**Discussion thread**: ISSUE #339 + +### Proposed Changes + +The proposal has two aspects. + +First is a separated Open Schema Registry, which includes storage and compatibility check for schema. +This proposal is under developing. + +Second is the integration of Open Schema in Eventmesh, which includes validation for schema. This proposal is to be developed. + +As for the first proposal, some developing statuses are as follows. + +#### Status Code and Exception Code + +No. | Status Code | Exception Code | Description | status +--- | :---: | :---: | :---: | :---: +1 | 401 | 40101 | Unauthorized Exception | ✔ +2 | 404 | 40401 | Schema Non- Exception | ✔ +3 | ^ | 40402 | Subject Non-exist Exception | ✔ +4 | ^ | 40403 | Version Non-exist Exception | ✔ +5 | 409 | 40901 | Compatibility Exception | ✔ +6 | 422 | 42201 | Schema Format Exception | ✔ +7 | ^ | 42202 | Subject Format Exception | ✔ +8 | ^ | 42203 | Version Format Exception | ✔ +9 | ^ | 42204 | Compatibility Format Exception | ✔ +10 | 500 | 50001 | Storage Service Exception | ✔ +11 | ^ | 50002 | Timeout Exception | ✔ + +#### API Development Status + +No. | Type | URL | response | exception | code | test +--- | --- | --- | --- | --- | --- | --- +1 | GET | /schemas/ids/{string: id} | `Schema.class` | 40101\40401\50001 | ✔ | ❌ +2 | GET | /schemas/ids/{string: id}/subjects | `SubjectAndVersion.class` | 40101\40401\50001 | ✔ | ❌ +3 | GET | /subjects | `List\` | 40101\50001 | ✔ | ❌ +4 | GET | /subjects/{string: subject}/versions | `List\` | 40101\40402\50001 | ✔ | ❌ +5 | DELETE | /subjects/(string: subject) | `List\` | 40101\40402\50001 | ✔ | ❌ +6 | GET | /subjects/(string: subject) | `Subject.class` | 40101\40402\50001 | ✔ | ❌ +7 | GET | /subjects/(string: subject)/versions/(version: version)/schema | `SubjectWithSchema.class` | 40101\40402\40403\50001 | ✔ | ❌ +8 | POST | /subjects/(string: subject)/versions | `SchemaIdResponse.class` | 40101\40901\42201\50001\50002 | - | ❌ +9 | POST | /subjects/(string: subject)/ | `Subject.class` | 40101\40901\42202\50001\50002 | ✔ | ❌ +10 | DELETE | /subjects/(string: subject)/versions/(version: version) | `int` | 40101\40402\40403\40901\50001| - | ❌ +11 | POST | /compatibility/subjects/(string: subject)/versions/(version: version) | `CompatibilityResultResponse.class` | 40101\40402\40403\42201\42203\50001| - | ❌ +12 | GET | /compatibility/(string: subject) | `Compatibility.class` | 40101\40402\50001 | ✔ | ❌ +13 | PUT | /compatibility/(string: subject) | `Compatibility.class` | 40101\40402\40901\42204\50001 | - | ❌ + +#### Overall Project Structure + +```SchemaController.java```+```SchemaService.java``` : ```OpenSchema 7.1.1~7.1.2 (API 1~2)``` + +```SubjectController.java```+```SubjectService.java``` : ```OpenSchema 7.2.1~7.2.8 (API 3~10)``` + +```CompatibilityController.java```+```CompatibilityService.java``` : ```OpenSchema 7.3.1~7.3.3 (API 11~13)``` + ```Check for Compatibility``` + +![Project Structure](/images/design-document/schema-registry-project-structure.png) + +## References + +[1] [schema validator (github.com)](https://github.com/search?q=schema+validator) + +[2] [EMQ: Schema Registry](https://www.jianshu.com/p/33e0655c642b) + +[3] [Pulsar: Schema Registry](https://mp.weixin.qq.com/s/PaB66-Si00cX80py5ig5Mw) + +[4] [confluentinc/schema-registry](https://github.com/confluentinc/schema-registry) + +[5] [openmessaging/openschema](https://github.com/openmessaging/openschema) diff --git a/versioned_docs/version-v1.9.0/design-document/05-metrics-export.md b/versioned_docs/version-v1.9.0/design-document/05-metrics-export.md new file mode 100644 index 0000000000..bab18761e3 --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/05-metrics-export.md @@ -0,0 +1,47 @@ +# EventMesh Metrics (OpenTelemetry and Prometheus) + +## Introduction + +[EventMesh(incubating)](https://github.com/apache/incubator-eventmesh) is a dynamic cloud-native eventing infrastructure. + +## An overview of OpenTelemetry + +OpenTelemetry is a collection of tools, APIs, and SDKs. You can use it to instrument, generate, collect, and export telemetry data (metrics, logs, and traces) for analysis in order to understand your software's performance and behavior. + +## An overview of Prometheus + +Power your metrics and alerting with a leading open-source monitoring solution. + +- Dimensional data +- Powerful queries +- Great visualization +- Efficient storage +- Simple operation +- Precise alerting +- Many client libraries +- Many integrations + +## Requirements + +### Functional Requirements + +| Requirement ID | Requirement Description | Comments | +| :------------- | ------------------------------------------------------------ | ------------- | +| F-1 | EventMesh users should be able to observe HTTP metrics from Prometheus | Functionality | +| F-2 | EventMesh users should be able to observe TCP metrics from Prometheus | Functionality | + +## Design Details + +use the meter instrument provided by OpenTelemetry to observe the metrics exist in EventMesh then export to Prometheus. + +1、Initialize a meter instrument + +2、set the Prometheus server + +3、different metrics observer built + +## Appendix + +### References + + diff --git a/versioned_docs/version-v1.9.0/design-document/06-cloudevents.md b/versioned_docs/version-v1.9.0/design-document/06-cloudevents.md new file mode 100644 index 0000000000..bff91b4575 --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/06-cloudevents.md @@ -0,0 +1,106 @@ +# CloudEvents Integration + +## Introduction + +[CloudEvents](https://github.com/cloudevents/spec) is a specification for describing event data in common formats to provide interoperability across services, platforms and systems. + +As of May 2021, EventMesh contains the following major components: `eventmesh-runtime`, `eventmesh-sdk-java` and `eventmesh-connector-rocketmq`. +For a customer to use EventMesh, `eventmesh-runtime` can be deployed as microservices to transmit +customer's events between event producers and consumers. Customer's applications can then interact +with `eventmesh-runtime` using `eventmesh-sdk-java` to publish/subscribe for events on given topics. + +CloudEvents support has been a highly desired feature by EventMesh users. There are many reasons +for users to prefer using a SDK with CloudEvents support: + +- CloudEvents is a more widely accepted and supported way to describe events. `eventmesh-sdk-java` + currently uses the `LiteMessage` structure to describe events, which is less standardized. +- CloudEvents's Java SDK has a wider range of distribution methods. For example, EventMesh users + currently need to use the SDK tarball or build from source for every EventMesh release. With + CloudEvents support, it's easier for users to take a dependency on EventMesh's SDK using CloudEvents's public distributions (e.g. through a Maven configuration). +- CloudEvents's SDK supports multiple languages. Although EventMesh currently only supports a Java SDK, in future if more languages need to be supported, the extensions can be easier with experience on binding Java SDK with CloudEvents. + +## Requirements + +### Functional Requirements + +| Requirement ID | Requirement Description | Comments | +| -------------- | ----------------------- | -------- | +| F-1 | EventMesh users should be able to depend on a public SDK to publish/subscribe events in CloudEvents format | Functionality | +| F-2 | EventMesh users should continue to have access to existing EventMesh client features (e.g. load balancing) with an SDK that supports CloudEvent | Feature Parity | +| F-3 | EventMesh developers should be able to sync `eventmesh-sdk-java` and an SDK with CloudEvents support without much effort/pain | Maintainability | +| F-4 | EventMesh support pluggable protocols for developers integrate other protocols (e.g. CloudEvents\EventMesh Message\OpenMessage\MQTT ...) | Functionality | +| F-5 | EventMesh support the unified api for publish/subscribe events to/from event store | Functionality | + +### Performance Requirements + +| Requirement ID | Requirement Description | Comments | +| -------------- | ----------------------- | -------- | +| P-1 | Client side latency for SDK with CloudEvents support should be similar to current SDK | | + +## Design Details + +Binding with the CloudEvents Java SDK (similar to what Kafka already did, see Reference for more details) +should be an easy way to achieve the requirements. + +### Pluggable Protocols + +![Pluggable Protocols](/images/design-document/cloudevents-pluggable-protocols.png) + +### Process of CloudEvents under EventMesh + +#### For TCP + +##### SDK side for publish + +- add the CloudEvents identifier in `package` header +- use `CloudEventBuilder` build the CloudEvent and put it into the `package` body + +##### SDK side for subscribe + +- add `convert` function under the `ReceiveMsgHook` interface, for converting the `package` body to the specific protocol with the identifier in `package` header +- different protocols should implement the `ReceiveMsgHook` interface + +##### Server side for publish + +- design the protocol convert api contains `decodeMessage` interface which convert the package's body to CloudEvent +- update `Session.upstreamMsg()` in `MessageTransferTask` change the input parameter Message to CloudEvent, the CloudEvent use the last step `decodeMessage` api convert +- update `SessionSender.send()` change the input parameter `Message` to `CloudEvent` +- update `MeshMQProducer` api support send `CloudEvents` in runtime +- support the implementation in `connector-plugin` for send `CloudEvents` to EventStore + +##### Server side for subscribe + +- support change the `RocketMessage` to `CloudEvent` in connector-plugin + +- overwrite the `AsyncMessageListener.consume()` function, change the input parameter `Message` to `CloudEvent` + +- update the `MeshMQPushConsumer.updateOffset()` implementation change the the input parameter `Message` to `CloudEvent` + +- update `DownStreamMsgContext` , change the input parameter `Message` to `CloudEvent`, update the `DownStreamMsgContext.ackMsg` + +#### For HTTP + +##### SDK side for publish + +- support `LiteProducer.publish(cloudEvent)` +- add the CloudEvents identifier in http request header + +##### SDK side for subscribe + +##### Server side for publish + +- support build the `HttpCommand.body` by pluggable protocol plugins according the protocol type in `HttpCommand` header +- support publish the CloudEvent in message processors + +##### Server side for subscribe + +- update the `EventMeshConsumer.subscribe()` + +- update `HandleMsgContext` , change the input parameter `Message` to `CloudEvent` +- update `AsyncHttpPushRequest.tryHTTPRequest()` + +## Appendix + +### References + +- diff --git a/versioned_docs/version-v1.9.0/design-document/07-tracing.md b/versioned_docs/version-v1.9.0/design-document/07-tracing.md new file mode 100644 index 0000000000..1b191965da --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/07-tracing.md @@ -0,0 +1,87 @@ +# Distributed Tracing + +## Overview of OpenTelemetry + +OpenTelemetry is a collection of tools, APIs, and SDKs. You can use it to instrument, generate, collect, and export telemetry data (metrics, logs, and traces) for analysis in order to understand your software's performance and behavior. + +## Requirements + +- set tracer +- different exporter +- start and end span in server + +## Design Details + +- SpanProcessor: BatchSpanProcessor + +- Exporter: log(default), would be changed from properties + +```java +// Configure the batch spans processor. This span processor exports span in batches. +BatchSpanProcessor batchSpansProcessor = + BatchSpanProcessor.builder(exporter) + .setMaxExportBatchSize(512) // set the maximum batch size to use + .setMaxQueueSize(2048) // set the queue size. This must be >= the export batch size + .setExporterTimeout( + 30, TimeUnit.SECONDS) // set the max amount of time an export can run before getting + // interrupted + .setScheduleDelay(5, TimeUnit.SECONDS) // set time between two different exports + .build(); +OpenTelemetrySdk.builder() + .setTracerProvider( + SdkTracerProvider.builder().addSpanProcessor(batchSpansProcessor).build()) + .build(); +``` + +1. When using the method 'init()' of the class "EventMeshHTTPServer", the class "AbstractHTTPServer” will get the tracer + +```java +super.openTelemetryTraceFactory = new OpenTelemetryTraceFactory(eventMeshHttpConfiguration); +super.tracer = openTelemetryTraceFactory.getTracer(this.getClass().toString()); +super.textMapPropagator = openTelemetryTraceFactory.getTextMapPropagator(); +``` + +2. then the trace in class "AbstractHTTPServer” will work. + +## Problems + +### How to set different exporter in class 'OpenTelemetryTraceFactory'? (Solved) + +After I get the exporter type from properties, how to deal with it. + +The 'logExporter' only needs to new it. + +But the 'zipkinExporter' needs to new and use the "getZipkinExporter()" method. + +## Solutions + +### Solution of different exporter + +Use reflection to get an exporter. + +First of all, different exporter must implement the interface 'EventMeshExporter'. + +Then we get the exporter name from the configuration and reflect to the class. + +```java +//different spanExporter +String exporterName = configuration.eventMeshTraceExporterType; +//use reflection to get spanExporter +String className = String.format("org.apache.eventmesh.runtime.exporter.%sExporter",exporterName); +EventMeshExporter eventMeshExporter = (EventMeshExporter) Class.forName(className).newInstance(); +spanExporter = eventMeshExporter.getSpanExporter(configuration); +``` + +Additional, this will surround with try catch.If the specified exporter cannot be obtained successfully, the default exporter log will be used instead + +#### Improvement of different exporter + +SPI (To be completed) + +## Appendix + +### References + + + + diff --git a/versioned_docs/version-v1.9.0/design-document/08-spi.md b/versioned_docs/version-v1.9.0/design-document/08-spi.md new file mode 100644 index 0000000000..94da666e7f --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/08-spi.md @@ -0,0 +1,113 @@ +# Service Provider Interface + +## Introduction + +In order to improve scalability，EventMesh introduce the SPI（Service Provider Interface）mechanism, which can help to automatically find the concrete implementation +class of the extended interface at runtime and load it dynamically. In EventMesh, all extension modules are implemented by using plugin. +User can develop custom plugins by simply implementing extended interfaces, and select the plugin to be run at runtime by simply declare at configuration. + +## eventmesh-spi module + +The implementation of SPI is at eventmesh-spi module, there are three main classes `EventMeshSPI`, `EventMeshExtensionFactory` and `ExtensionClassLoader`. + +### EventMeshSPI + +EventMeshSPI is an SPI declaration annotation, all extended interface that want to be implemented should be declared by @EventMeshSPI. + +```java +@Documented +@Retention(RetentionPolicy.RUNTIME) +@Target({ElementType.TYPE}) +public @interface EventMeshSPI { + /** + * If true, the spi instance is singleton + */ + boolean isSingleton() default false; +} +``` + +Use annotation to declare the interface is an SPI extended interface can improve the readability of the code. +On the other hand, @EventMeshSPI contains a isSingleton attribute which used to declare whether the extension instance is a singleton. +If this attribute is true, that means the instance of this interface will be singleton. + +### EventMeshExtensionFactory + +EventMeshExtensionFactory is a factory used to get the SPI extension instance which contains a static method `getExtension(Class extensionType, String extensionName)`. + +```java +public enum EventMeshExtensionFactory { + /** + * @param extensionType extension plugin class type + * @param extensionName extension instance name + * @param the type of the plugin + * @return plugin instance + */ + public static T getExtension(Class extensionType, String extensionName) { + /* ... */ + } +} +``` + +If you want to get the extension instance, you should use EventMeshExtensionFactory. + +### ExtensionClassLoader + +ExtensionClassLoader is used to load extension instance classed, it has two subclass MetaInfExtensionClassLoader and JarExtensionClassLoader. + +```java +/** + * Load extension class + *
    + *
  • {@link MetaInfExtensionClassLoader}
    • + *
  • {@link JarExtensionClassLoader}
    • + *
+ */ +public interface ExtensionClassLoader { + /** + * load + * + * @param extensionType extension type class + * @param extension type + * @return extension instance name to extension instance class + */ + Map> loadExtensionClass(Class extensionType); +} +``` + +MetaInfExtensionClassLoader used to load class from classPath, and JarExtensionClassLoader used to load class from extension jar on the plugin directory. +In the future, we might support the implementation to load from the maven repository. + +## SPI use case + +The following is an example of how to use the SPI to declare a plugin. + +First, we create an eventmesh-connector-api module, and define the extension interface MeshMQProducer, and we use @EventMeshSPI on the MeshMQProducer, +which indicates the MeshMQProducer is an SPI interface. + +```java +@EventMeshSPI(isSingleton = false) +public interface MeshMQProducer extends Producer { + /* ... */ +} +``` + +Then we create an eventmesh-connector-rocketmq module, which contains the concrete implementation named RocketMQProducerImpl. + +```java +public class RocketMQProducerImpl implements MeshMQProducer { + /* ... */ +} +``` + +At the same time, we need to create a file with the full qualified name of the SPI interface under the resource/META-INF/eventmesh directory +in the eventmesh-connector-rocketmq module. + +org.apache.eventmesh.api.producer.Producer + +The content of the file is the extension instance name and the corresponding instance full class name + +```properties +rocketmq=org.apache.eventmesh.connector.rocketmq.producer.RocketMQProducerImpl +``` + +At this point, an SPI expansion module is complete. We can use `EventMeshExtensionFactory.getExtension(MeshMQProducer.class, "rocketmq")` to get the `RocketMQProducerImpl` instance. diff --git a/versioned_docs/version-v1.9.0/design-document/09-event-bridge.md b/versioned_docs/version-v1.9.0/design-document/09-event-bridge.md new file mode 100644 index 0000000000..0bacec2808 --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/09-event-bridge.md @@ -0,0 +1,156 @@ +# Event Bridge + +![event-bridge](/images/eventmesh-bridge.png) + +Event Bridge 可以支持跨mesh集群的消息投递，下面展示这一功能的详细设计与体验步骤 + +![event-bridge-detail](/images/design-document/event-bridge-detail.png) + +> 注：在本地体验这一功能时需要启动两台eventmesh实例，同时要修改`eventmesh-runtime`目录下的`eventmesh.properties`文件中的端口配置，避免端口冲突。便于下文描述，event-bridge特性按照上图信息进行表述。 + +## 01 远程订阅 + +**描述**：向cluster2 eventmesh发起远程订阅指令，cluster2 eventmesh收到指令后会携带订阅信息调用cluster1 eventmesh的本地订阅接口 + +**URL**: http://{cluster2 address}/eventmesh/subscribe/remote + +**请求方式**：POST + +**请求参数：**application/json 格式 + +| 参数名 | 类型 | 是否必填 | 说明 | +| ------------- | ------ | -------- | ------------------------------------------------------------ | +| url | String | 是 | 标识订阅url信息，暂时无用，后续可移除，目前仅为强校验，实际会被（/eventmesh/bridge/publish）替换 | +| consumerGroup | String | 是 | 标识消费组信息，实际会被cluster2的eventmesh配置信息替换 | +| topic | List | 是 | 标识订阅信息列表 | +| mode | String | 是 | 标识消费模式，分为集群模式和广播模式 | +| topic | String | 是 | 标识订阅的topic | +| type | String | 是 | 标识消费类型，分为同步和异步 | +| remoteMesh | String | 否 | 标识远程mesh地址，优先根据topic从注册中心获取，获取不到使用该字段替换 | + +**请求样例：** + +```json +{ + "url": "http://127.0.0.1:8088/sub/test", + "consumerGroup": "TEST-GROUP", + "topic": [ + { + "mode": "CLUSTERING", + "topic": "TEST-TOPIC-HTTP-ASYNC", + "type": "ASYNC" + } + ], + "remoteMesh" : "http://127.0.0.1:10105/eventmesh/subscribe/local" +} +``` + +## 02 本地订阅 + +**描述**：向cluster2的EventMesh实例发起本地订阅指令，cluster2的EventMesh收到订阅指令后会启动本地监听从event store收下来的消息，并推送给订阅信息中的url。 + +**URL**: http://{cluster2 address}/eventmesh/subscribe/local + +**请求方式**：POST + +**请求参数：**application/json 格式 + +| 参数名 | 类型 | 是否必填 | 说明 | +| ------------- | ------ | -------- | ------------------------------------ | +| url | String | 是 | 标识订阅url信息 | +| consumerGroup | String | 是 | 标识消费组信息 | +| topic | List | 是 | 标识订阅信息列表 | +| mode | String | 是 | 标识消费模式，分为集群模式和广播模式 | +| topic | String | 是 | 标识订阅的topic | +| type | String | 是 | 标识消费类型，分为同步和异步 | + +**请求样例：** + +```JSON +{ + "url": "http://127.0.0.1:8088/sub/test", + "consumerGroup": "TEST-GROUP", + "topic": [ + { + "mode": "CLUSTERING", + "topic": "TEST-TOPIC-HTTP-ASYNC", + "type": "ASYNC" + } + ] +} +``` + +## 03 发送消息 + +**描述**：向cluster1的EventMesh实例发送消息，cluster1的EventMesh收到消息后会发送到event store，再从event store收下来消息推送给cluster2的EventMesh url `/eventmesh/bridge/publish`。 + +**URL**: http://{cluster1 address}/eventmesh/publish/TEST-TOPIC-HTTP-ASYNC + +**请求方式**：POST + +**请求参数：**application/json 格式 + +**请求样例：** + +```json +{ + "name":"test", + "age":"19" +} +``` + +## 04远程去订阅 + +**描述**：向cluster2的EventMesh实例发送去除订阅指令，cluster2的EventMesh收到指令后会发送cluster1的EventMesh，cluster1的EventMesh会本地执行去除订阅 + +**URL**: http://{cluster2 address}/eventmesh/unsubscribe/remote + +**请求方式**：POST + +**请求参数：**application/json 格式 + +| 参数名 | 类型 | 是否必填 | 说明 | +| ------------- | ------ | -------- | ------------------------------------------------------------ | +| url | String | 是 | 标识要去除订阅url信息，暂时无用，后续可移除，目前仅为强校验，实际会被（/eventmesh/bridge/publish）替换 | +| consumerGroup | String | 是 | 标识要去除的消费组信息，实际会使用EventMesh cluster2的group信息替换 | +| topic | List | 是 | 标识订阅topic信息列表 | + +**请求样例：** + +```json +{ + "consumerGroup": "EventMeshTest-consumerGroup", + "url": "http://127.0.0.1:8088/sub/test", + "topic": [ + "TEST-TOPIC-HTTP-ASYNC" + ] +} +``` + +## 05本地去订阅 + +**描述**：向cluster2的EventMesh实例发送去除订阅指令，cluster2的EventMesh收到指令后会本地执行去除订阅 + +**URL**: http://{cluster2 address}/eventmesh/unsubscribe/local + +**请求方式**：POST + +**请求参数：**application/json 格式 + +| 参数名 | 类型 | 是否必填 | 说明 | +| ------------- | ------ | -------- | ---------------------- | +| url | String | 是 | 标识要去除订阅url信息 | +| consumerGroup | String | 是 | 标识要去除的消费组信息 | +| topic | List | 是 | 标识订阅topic信息列表 | + +**请求样例：** + +```json +{ + "consumerGroup": "EventMeshTest-consumerGroup", + "url": "http://127.0.0.1:8088/sub/test", + "topic": [ + "TEST-TOPIC-HTTP-ASYNC" + ] +} +``` diff --git a/versioned_docs/version-v1.9.0/design-document/10-knative-connector.md b/versioned_docs/version-v1.9.0/design-document/10-knative-connector.md new file mode 100644 index 0000000000..2c98e147a8 --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/10-knative-connector.md @@ -0,0 +1,93 @@ +# Knative Connector + +## Prerequisite +### Create Knative Source and Sink +We use the *cloudevents-player* [Knative service](https://knative.dev/docs/serving/) as an example. If you do not know how to create *cloudevents-player* Knative service as source and sink, please follow the steps in this [link](https://knative.dev/docs/getting-started/first-source/#creating-your-first-source). + + +### Set up EventMesh Configuration +- Add the following lines to [eventmesh-starter/build.gradle](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-starter/build.gradle) file. +``` +plugins { + id 'application' +} + +application { + mainClass = project.hasProperty("mainClass") ? project.getProperty("mainClass") : 'org.apache.eventmesh.starter.StartUp' + applicationDefaultJvmArgs = [ + '-Dlog4j.configurationFile=../eventmesh-runtime/conf/log4j2.xml', '-Deventmesh.log.home=../eventmesh-runtime/logs', '-Deventmesh.home=../eventmesh-runtime', '-DconfPath=../eventmesh-runtime/conf' + ] +} + +dependencies { + implementation project(":eventmesh-connector-plugin:eventmesh-connector-knative") + implementation project(":eventmesh-runtime") +} +``` +- Add the following lines to [eventmesh-examples/build.gradle](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-examples/build.gradle) file. +``` +plugins { + id 'application' +} + +application { + mainClass = project.hasProperty("mainClass") ? project.getProperty("mainClass") : 'NULL' +} +``` +- Set ```eventMesh.connector.plugin.type=knative``` in [eventmesh-runtime/conf/eventmesh.properties](https://github.com/pchengma/incubator-eventmesh/blob/master/eventmesh-runtime/conf/eventmesh.properties) file. + +## Demo +### Publish an Event Message from Knative and Subscribe from EventMesh +#### Step 1: Start an Eventmesh-Runtime Server +```bash +$ cd eventmesh-starter +$ ../gradlew -PmainClass=org.apache.eventmesh.starter.StartUp run +``` + +#### Step 2: Publish an Event Message from Knative +```bash +$ curl -i http://cloudevents-player.default.127.0.0.1.sslip.io -H "Content-Type: application/json" -H "Ce-Id: 123456789" -H "Ce-Specversion: 1.0" -H "Ce-Type: some-type" -H "Ce-Source: command-line" -d '{"msg":"Hello CloudEvents!"}' +``` + +#### Step 3: Subscribe from an EventMesh +- Set ```public static final String EVENTMESH_HTTP_ASYNC_TEST_TOPIC = "messages";``` in [ExampleConstants.java](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-examples/src/main/java/org/apache/eventmesh/common/ExampleConstants.java) file. +```bash +$ cd eventmesh-examples +$ ../gradlew -PmainClass=org.apache.eventmesh.http.demo.sub.SpringBootDemoApplication run +``` + +#### Expected Result +The following message with ```data``` field as ```Hello CloudEvents!``` will be printed on the console of EventMesh server. +```bash +2022-09-05 16:37:58,237 INFO [eventMesh-clientManage-] DefaultConsumer(DefaultConsumer.java:60) - \ +[{"event":{"attributes":{"datacontenttype":"application/json","id":"123456789","mediaType":"application/json",\ +"source":"command-line","specversion":"1.0","type":"some-type"},"data":{"msg":"Hello CloudEvents!"},"extensions":{}},\ +"id":"123456789","receivedAt":"2022-09-05T10:37:49.537658+02:00[Europe/Madrid]","type":"RECEIVED"}] +``` + +### Publish an Event Message from EventMesh and Subscribe from Knative +#### Step 1: Start an Eventmesh-Runtime Server +```bash +$ cd eventmesh-starter +$ ../gradlew -PmainClass=org.apache.eventmesh.starter.StartUp run +``` + +#### Step 2: Publish an Event Message from EventMesh +We use a test program to demo this function. +```bash +$ cd eventmesh-connector-plugin/eventmesh-connector-knative +$ ../../gradlew clean test --tests KnativeProducerImplTest.testPublish +``` + +#### Step 3: Subscribe from Knative +```bash +$ curl http://cloudevents-player.default.127.0.0.1.sslip.io/messages +``` + +#### Expected Result +The following message with ```data``` field as ```Hello Knative from EventMesh!``` will be printed on the console of EventMesh server. +```bash +2022-09-05 16:52:41,633 INFO [eventMesh-clientManage-] DefaultConsumer(DefaultConsumer.java:60) - \ +[{"event":{"attributes":{"datacontenttype":"application/json","id":"1234","mediaType":"application/json",\ +"source":"java-client","specversion":"1.0","type":"some-type"},"data":{"msg":["Hello Knative from EventMesh!"]},"extensions":{}},"id":"1234","receivedAt":"2022-09-05T10:52:32.999273+02:00[Europe/Madrid]","type":"RECEIVED"}] +``` \ No newline at end of file diff --git a/versioned_docs/version-v1.9.0/design-document/11-prometheus.md b/versioned_docs/version-v1.9.0/design-document/11-prometheus.md new file mode 100644 index 0000000000..1bc6e0e554 --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/11-prometheus.md @@ -0,0 +1,24 @@ +# Observe Metrics with Prometheus + +## Prometheus + +[Prometheus](https://prometheus.io/docs/introduction/overview/) is an open-source system monitoring and alerting toolkit that collects and stores the metrics as time-series data. EventMesh exposes a collection of metrics data that could be scraped and analyzed by Prometheus. Please follow [the "First steps with Prometheus" tutorial](https://prometheus.io/docs/introduction/first_steps/) to download and install the latest release of Prometheus. + +## Edit Prometheus Configuration + +The `eventmesh-runtime/conf/prometheus.yml` configuration file specifies the port of the metrics HTTP endpoint. The default metrics port is `19090`. + +```properties +eventMesh.metrics.prometheus.port=19090 +``` + +Please refer to [the Prometheus configuration guide](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) to add the EventMesh metrics as a scrape target in the configuration file. Here's the minimum configuration that creates a job with the name `eventmesh` and the endpoint `http://localhost:19090`: + +```yaml +scrape_configs: + - job_name: "eventmesh" + static_configs: + - targets: ["localhost:19090"] +``` + +Please navigate to the Prometheus dashboard (e.g. `http://localhost:9090`) to view the list of metrics exported by EventMesh, which are prefixed with `eventmesh_`. diff --git a/versioned_docs/version-v1.9.0/design-document/12-zipkin.md b/versioned_docs/version-v1.9.0/design-document/12-zipkin.md new file mode 100644 index 0000000000..f4d07252d7 --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/12-zipkin.md @@ -0,0 +1,38 @@ +# Collect Trace with Zipkin + +## Zipkin + +Distributed tracing is a method used to profile and monitor applications built with microservices architecture. Distributed tracing helps pinpoint where failures occur and what causes poor performance. + +[Zipkin](https://zipkin.io) is a distributed tracing system that helps collect timing data needed to troubleshoot latency problems in service architectures. EventMesh exposes a collection of trace data that could be collected and analyzed by Zipkin. Please follow [the "Zipkin Quickstart" tutorial](https://zipkin.io/pages/quickstart.html) to download and install the latest release of Zipkin. + +## Configuration + +To enable the trace exporter of EventMesh Runtime, set the `eventMesh.server.trace.enabled` field in the `conf/eventmesh.properties` file to `true`. + +```conf +# Trace plugin +eventMesh.server.trace.enabled=true +eventMesh.trace.plugin=zipkin +``` + +To customize the behavior of the trace exporter such as timeout or export interval, edit the `exporter.properties` file. + +```conf +# Set the maximum batch size to use +eventmesh.trace.max.export.size=512 +# Set the queue size. This must be >= the export batch size +eventmesh.trace.max.queue.size=2048 +# Set the max amount of time an export can run before getting(TimeUnit=SECONDS) +eventmesh.trace.export.timeout=30 +# Set time between two different exports (TimeUnit=SECONDS) +eventmesh.trace.export.interval=5 +``` + +To send the exported trace data to Zipkin, edit the `eventmesh.trace.zipkin.ip` and `eventmesh.trace.zipkin.port` fields in the `conf/zipkin.properties` file to match the configuration of the Zipkin server. + +```conf +# Zipkin's IP and Port +eventmesh.trace.zipkin.ip=localhost +eventmesh.trace.zipkin.port=9411 +``` diff --git a/versioned_docs/version-v1.9.0/design-document/13-jaeger.md b/versioned_docs/version-v1.9.0/design-document/13-jaeger.md new file mode 100644 index 0000000000..e9452c3554 --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/13-jaeger.md @@ -0,0 +1,44 @@ +# Collect Trace with Jaeger + +## Jaeger + +[Jaeger](https://www.jaegertracing.io/), inspired by [Dapper](https://research.google.com/pubs/pub36356.html) and [OpenZipkin](https://zipkin.io/), is a distributed tracing platform created by [Uber Technologies](https://uber.github.io/) and donated to [Cloud Native Computing Foundation](https://cncf.io/). It can be used for monitoring microservices-based distributed systems. + +For the installation of Jaeger, you can refer to the [official documentation](https://www.jaegertracing.io/docs/latest/getting-started/) of Jaeger. It is recommended to use docker image `jaegertracing/all-in-one` to quickly build the environment for testing. + +## Configuration + +To enable the trace exporter of EventMesh Runtime, set the `eventMesh.server.trace.enabled` field in the `conf/eventmesh.properties` file to `true`. + +```conf +# Trace plugin +eventMesh.server.trace.enabled=true +eventMesh.trace.plugin=jaeger +``` + +To customize the behavior of the trace exporter such as timeout or export interval, edit the `exporter.properties` file. + +```conf +# Set the maximum batch size to use +eventmesh.trace.max.export.size=512 +# Set the queue size. This must be >= the export batch size +eventmesh.trace.max.queue.size=2048 +# Set the max amount of time an export can run before getting(TimeUnit=SECONDS) +eventmesh.trace.export.timeout=30 +# Set time between two different exports (TimeUnit=SECONDS) +eventmesh.trace.export.interval=5 +``` + +To send the exported trace data to Jaeger, edit the `eventmesh.trace.jaeger.ip` and `eventmesh.trace.jaeger.port` fields in the `conf/jaeger.properties` file to match the configuration of the Jaeger server. + +```conf +# Jaeger's IP and Port +eventmesh.trace.jaeger.ip=localhost +eventmesh.trace.jaeger.port=14250 +``` + +## Migrating from Zipkin + +Collector service exposes Zipkin compatible REST API `/api/v1/spans` which accepts both Thrift and JSON. Also there is `/api/v2/spans` for JSON and Proto. + +So you can also use the `eventmesh-trace-zipkin` plugin to collect trace with Jaeger. Please refer to the `eventmesh-trace-zipkin` documentation for the specific configuration. By default this feature in Jaeger is disabled. It can be enabled with `--collector.zipkin.host-port=:9411`. \ No newline at end of file diff --git a/docs/design-document/14-webhook.md b/versioned_docs/version-v1.9.0/design-document/14-webhook.md similarity index 80% rename from docs/design-document/14-webhook.md rename to versioned_docs/version-v1.9.0/design-document/14-webhook.md index eef5715985..302210fe12 100644 --- a/docs/design-document/14-webhook.md +++ b/versioned_docs/version-v1.9.0/design-document/14-webhook.md @@ -38,11 +38,6 @@ Configuration information description */ private String manufacturerName; - /** - * manufacturer domain name, like www.github.com - */ - private String manufacturerDomain; - /** * webhook event name, like rep-push */ @@ -83,7 +78,12 @@ Configuration information description * roll out data format -> CloudEvent serialization mode * If HTTP protocol is used, the request header contentType needs to be marked */ - private String dataContentType = "application/json"; + private String dataContentType = "application/json";; + + /** + * source of event + */ + private String cloudEventSource; /** * id of cloudEvent, like uuid/manufacturerEventId @@ -92,7 +92,7 @@ Configuration information description ``` -##### Add WebHook config +##### Add webhook config path: /webhook/insertWebHookConfig method: POST @@ -104,31 +104,58 @@ input params: | -- | -- | -- | -- | -- | | callbackPath | call address, unique address | string | Y　| null　| | manufacturerName | manufacturer name | string | Y　| null　| -| manufacturerDomain | manufacturer domain name | string | Y　| null　| -| manufacturerEventName | manufacturer event name | string | Y　| null　| +| manufacturerEventName | manufacturer EventName | string | Y　| null　| | contentType | http connettype | string | N　| application/json　| | description | configuration instructions | string | N　| null　| | secret | signature string | string | N　| null　| | userName | username | string | N　| null　| | password | password | string | N　| null　| | cloudEventName | cloudEvent name | string | Y　| null　| -| cloudEventIdGenerateMode | cloudEvent event object identification method, uuid or event id | string | N　|manufacturerEventId| +| cloudEventSource | cloudEvent source | string | Y　| null　| +| cloudEventIdGenerateMode | cloudEvent event object identification method, uuid or event id | string | N manufacturerEventId　| E.g: ```json + { - "callbackPath":"/webhook/github/eventmesh/all", - "manufacturerName":"github", - "manufacturerDomain":"www.github.com", - "manufacturerEventName":"all", - "cloudEventName":"github-eventmesh" + "callbackPath":"/webhook/github/eventmesh/all", + "manufacturerName":"github", + "manufacturerEventName":"all", + "secret":"eventmesh", + "cloudEventName":"github-eventmesh", + "cloudEventSource":"github" } + ``` Output params: 1 for success, 0 for failure -##### Query WebHook config by callback path +##### delete webhook config +path: /webhook/deleteWebHookConfig +method: POST +contentType： application/json + +input params: + +| field | desc | type |　necessary | default　| +| -- | -- | -- | -- | -- | +| callbackPath | call address, unique address | string | Y　| null　| + + +E.g: + +```json + +{ + "callbackPath":"/webhook/github/eventmesh/all" +} + +``` + +Output params: 1 for success, 0 for failure + +##### select WebHookConfig by callbackPath path: /webhook/queryWebHookConfigById method: POST contentType： application/json @@ -138,15 +165,15 @@ input params: | field | desc | type |　necessary | default　| | -- | -- | -- | -- | -- | | callbackPath | call address, unique address | string | Y　| null　| -| manufacturerName | the caller of this callbackPath belongs to | string | Y　| null　| E.g: ```json + { - "callbackPath":"/webhook/github/eventmesh/all", - "manufacturerName":"github" + "callbackPath":"/webhook/github/eventmesh/all" } + ``` Output params: @@ -155,7 +182,6 @@ Output params: | -- | -- | -- | -- | -- | | callbackPath | call address, unique address | string | Y　| null　| | manufacturerName | manufacturer name | string | Y　| null　| -| manufacturerDomain | manufacturer domain name | string | Y　| null　| | manufacturerEventName | manufacturer event name | string | Y　| null　| | contentType | http connettype | string | N　| application/json　| | description | configuration instructions | string | N　| null　| @@ -163,10 +189,11 @@ Output params: | userName | user name | string | N　| null　| | password | password | string | N　| null　| | cloudEventName | cloudEvent name | string | Y　| null　| +| cloudEventSource | cloudEvent source | string | Y　| null　| | cloudEventIdGenerateMode | cloudEvent event object identification method, uuid or event id | string | N　| manufacturerEventId　| -##### Query WebHook config by manufacturer +##### 通过manufacturer查询WebHookConfig列表 path: /webhook/queryWebHookConfigByManufacturer method: POST contentType： application/json @@ -176,18 +203,16 @@ input params: | field | desc | type |　necessary | default　| | -- | -- | -- | -- | -- | | manufacturerName | manufacturer name | string | Y　| null　| -| pageNum | page number of paging query | string | Y　| null　| -| pageSize | page size of each page | string | Y　| null　| E.g: ```json + { - "manufacturerName":"github", - "pageNum":1, - "pageSize":2 + "manufacturerName":"github" } + ``` Output params: @@ -196,7 +221,6 @@ Output params: | -- | -- | -- | -- | -- | | callbackPath | call address, unique address | string | Y　| null　| | manufacturerName | manufacturer name | string | Y　| null　| -| manufacturerDomain | manufacturer domain name | string | Y　| null　| | manufacturerEventName | manufacturer event name | string | Y　| null　| | contentType | http connettype | string | N　| application/json　| | description | configuration instructions | string | N　| null　| @@ -204,32 +228,9 @@ Output params: | userName | user name | string | N　| null　| | password | password | string | N　| null　| | cloudEventName | cloudEvent name | string | Y　| null　| +| cloudEventSource | cloudEvent source | string | Y　| null　| | cloudEventIdGenerateMode | cloudEvent event object identification method, uuid or event id | string | N　| manufacturerEventId　| -##### Delete WebHook config - -path: /webhook/deleteWebHookConfig -method: POST -contentType： application/json - -input params: - -| field | desc | type | necessary | default | -| ---------------- | ------------------------------------------ | ------ | --------- | ------- | -| callbackPath | call address, unique address | string | Y | null | -| manufacturerName | the caller of this callbackPath belongs to | string | Y | null | - - -E.g: - -```json -{ - "callbackPath":"/webhook/github/eventmesh/all", - "manufacturerName":"github" -} -``` - -Output params: 1 for success, 0 for failure #### The third step: Check if the configuration is successful @@ -271,3 +272,4 @@ secret: signature string + diff --git a/versioned_docs/version-v1.9.0/design-document/_category_.json b/versioned_docs/version-v1.9.0/design-document/_category_.json new file mode 100644 index 0000000000..f9283e2f00 --- /dev/null +++ b/versioned_docs/version-v1.9.0/design-document/_category_.json @@ -0,0 +1,5 @@ +{ + "position": 6, + "label": "Design Document", + "collapsed": false +} diff --git a/versioned_docs/version-v1.9.0/instruction/01-store-with-docker.md b/versioned_docs/version-v1.9.0/instruction/01-store-with-docker.md new file mode 100644 index 0000000000..f8f577b6ed --- /dev/null +++ b/versioned_docs/version-v1.9.0/instruction/01-store-with-docker.md @@ -0,0 +1,38 @@ +# Guidelines of eventmesh-store with Docker + +## Dependencies + +``` +64-bit OS，we recommend Linux/Unix； +64-bit JDK 1.8+; +Gradle 7.0+, we recommend 7.0.* +4g+ available disk to deploy eventmesh-store +If you choose standalone mode, you could skip this file and go to the next step: Start Eventmesh-Runtime; if not, you could choose RocketMQ as the store layer. +``` + +## Deploy + +Pull RocketMQ image from Docker Hub： + +```shell +#Pull rocketmq image +sudo docker pull apache/rocketmq:4.9.4 +``` + +Start namesrv and broker + +```shell +#Run namerv container +sudo docker run -d -p 9876:9876 -v `pwd`/data/namesrv/logs:/root/logs -v `pwd`/data/namesrv/store:/root/store --name rmqnamesrv apache/rocketmq:4.9.4 sh mqnamesrv + +#Run broker container +sudo docker run -d -p 10911:10911 -p 10909:10909 -v `pwd`/data/broker/logs:/root/logs -v `pwd`/data/broker/store:/root/store --name rmqbroker --link rmqnamesrv:namesrv -e "NAMESRV_ADDR=namesrv:9876" apache/rocketmq:4.9.4 sh mqbroker -c ../conf/broker.conf +``` + +Please note that the **rocketmq-broker ip** is **pod ip**. If you want to modify this ip, you can set it your custom value in **broker.conf**。 + +By now, the deployment of eventmesh-store has finished, please go to the next step: [Start Eventmesh-Runtime Using Docker](02-runtime-with-docker.md) + +## Reference + +For more details about RocketMQ，please refer to diff --git a/versioned_docs/version-v1.9.0/instruction/01-store.md b/versioned_docs/version-v1.9.0/instruction/01-store.md new file mode 100644 index 0000000000..89cf87c1bd --- /dev/null +++ b/versioned_docs/version-v1.9.0/instruction/01-store.md @@ -0,0 +1,42 @@ +# Guidelines of eventmesh-store + +## Dependencies + +```text +64-bit OS，we recommend Linux/Unix； +64-bit JDK 1.8+; +Gradle 7.0+, we recommend 7.0.* +4g+ available disk to deploy eventmesh-store +If you choose standalone mode, you could skip this file and go to the next step: Start Eventmesh-Runtime; if not, you could choose RocketMQ as the store layer. +``` + +## Download + +Download the Binary code (recommended: 4.9.*) from [RocketMQ Official](https://rocketmq.apache.org/download/). Here we take 4.9.4 as an example. + +``` +unzip rocketmq-all-4.9.4-bin-release.zip +cd rocketmq-4.9.4/ +``` + +## Deploy + +### Start Name Server + +```console +nohup sh bin/mqnamesrv & +tail -f ~/logs/rocketmqlogs/namesrv.log +``` + +### Start Broker + +```console +nohup sh bin/mqbroker -n localhost:9876 & +tail -f ~/logs/rocketmqlogs/broker.log +``` + +The deployment of eventmesh-store has finished, please go to the next step: [Start Eventmesh-Runtime](02-runtime.md) + +## Reference + +For more details about RocketMQ, please refer to diff --git a/versioned_docs/version-v1.9.0/instruction/02-runtime-with-docker.md b/versioned_docs/version-v1.9.0/instruction/02-runtime-with-docker.md new file mode 100644 index 0000000000..740c358c40 --- /dev/null +++ b/versioned_docs/version-v1.9.0/instruction/02-runtime-with-docker.md @@ -0,0 +1,106 @@ +# EventMesh Runtime (Docker) + +The documentation introduces the steps to install the latest release of EventMesh Runtime with Docker and connect to Apache RocketMQ. It's recommended to use a Linux-based system with [Docker Engine](https://docs.docker.com/engine/install/). Please follow the [Docker tutorial](https://docs.docker.com/get-started/) to get familiar with the basic concepts (registry, volume, etc.) and commands of Docker. + +## Dependencies + +``` +64-bit OS，we recommend Linux/Unix； +64-bit JDK 1.8+; +Gradle 7.0+, we recommend 7.0.* +4g+ available disk to deploy eventmesh-store +If you choose standalone mode, you could skip this file and go to the next step: Start Eventmesh-Runtime; if not, you could choose RocketMQ as the store layer. +``` + +## Pull EventMesh Image + +Download the pre-built image of [`eventmesh`](https://hub.docker.com/r/eventmesh/eventmesh) from Docker Hub with `docker pull`: + +```console +sudo docker pull eventmesh/eventmesh:v1.4.0 +``` + +To verify that the `eventmesh/eventmesh` image is successfully installed, list the downloaded images with `docker images`: + +```console +$ sudo docker images +eventmesh/eventmesh v1.4.0 6e2964599c78 2 weeks ago 937MB +``` + +## Edit Configuration + +Edit the `eventmesh.properties` to change the configuration (e.g. TCP port, client blacklist) of EventMesh Runtime. To integrate RocketMQ as a connector, these two configuration files should be created: `eventmesh.properties` and `rocketmq-client.properties`. + +```shell +sudo mkdir -p /data/eventmesh/rocketmq/conf +cd /data/eventmesh/rocketmq/conf +sudo touch eventmesh.properties +sudo touch rocketmq-client.properties +``` + +### `eventmesh.properties` + +The `eventmesh.properties` file contains the properties of EventMesh runtime environment and integrated plugins. Please refer to the [default configuration file](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-runtime/conf/eventmesh.properties) for the available configuration keys. + +```shell +sudo vim eventmesh.properties +``` + +| Configuration Key | Default Value | Description | +|-|-|-| +| `eventMesh.server.http.port` | 10105 | EventMesh HTTP server port | +| `eventMesh.server.tcp.port` | 10000 | EventMesh TCP server port | +| `eventMesh.server.grpc.port` | 10205 | EventMesh gRPC server port | + +### `rocketmq-client.properties` + +The `rocketmq-client.properties` file contains the properties of the Apache RocketMQ nameserver. + +```shell +sudo vim rocketmq-client.properties +``` + +Please refer to the [default configuration file](https://github.com/apache/incubator-eventmesh/blob/1.3.0/eventmesh-runtime/conf/rocketmq-client.properties) and change the value of `eventMesh.server.rocketmq.namesrvAddr` to the nameserver address of RocketMQ. + +| Configuration Key | Default Value | Description | +|-|-|-| +| `eventMesh.server.rocketmq.namesrvAddr` | `127.0.0.1:9876;127.0.0.1:9876` | The address of RocketMQ nameserver | + +## Run and Manage EventMesh Container + +Run an EventMesh container from the `eventmesh/eventmesh` image with the `docker run` command. The `-p` option of the command binds the container port with the host machine port. The `-v` option of the command mounts the configuration files from files in the host machine. + +```shell +sudo docker run -d -p 10000:10000 -p 10105:10105 \ +-v `pwd`/data/eventmesh/rocketmq/conf/eventmesh.properties:/data/app/eventmesh/conf/eventmesh.properties \ +-v `pwd`/data/eventmesh/rocketmq/conf/rocketmq-client.properties:/data/app/eventmesh/conf/rocketmq-client.properties \ +eventmesh/eventmesh:v1.4.0 +``` + +The `docker ps` command lists the details (id, name, status, etc.) of the running containers. The container id is the unique identifier of the container. + +```console +$ sudo docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + eventmesh/eventmesh:v1.4.0 "/bin/sh -c 'sh star…" About a minute ago Up About a minute 0.0.0.0:10000->10000/tcp, :::10000->10000/tcp, 0.0.0.0:10105->10105/tcp, :::10105->10105/tcp +``` + +To connect to the EventMesh container: + +```shell +sudo docker exec -it [container id or name] /bin/bash +``` + +To read the log of the EventMesh container: + +```shell +tail -f ../logs/eventmesh.out +``` + +To stop or remove the container: + +```shell +sudo docker stop [container id or name] + +sudo docker rm -f [container id or name] +``` diff --git a/versioned_docs/version-v1.9.0/instruction/02-runtime.md b/versioned_docs/version-v1.9.0/instruction/02-runtime.md new file mode 100644 index 0000000000..3f398d8af8 --- /dev/null +++ b/versioned_docs/version-v1.9.0/instruction/02-runtime.md @@ -0,0 +1,107 @@ +# EventMesh Runtime + +EventMesh Runtime is the core component of Apache EventMesh (Incubating). It is the middleware that transmits events between producers and consumers. The documentation introduces the step to install and start the latest release of EventMesh Runtime in the local or test environment. The EventMesh Runtime requires a Linux-based system with JDK (Java Development Kit) 8+. + +Here, we take JDK 8 as an example. JDK 8 could be installed with the system package manager or the [openjdk:8-jdk](https://hub.docker.com/_/openjdk) Docker image. + +## 1 Run on your local machine + +### 1.1 Dependencies + +``` +64-bit OS，we recommend Linux/Unix； +64-bit JDK 1.8+; +Gradle 7.0+, we recommend 7.0.* +4g+ available disk to deploy eventmesh-store +If you choose standalone mode, you could skip this file and go to the next step: Start Eventmesh-Runtime; if not, you could choose RocketMQ as the store layer. +``` + +### 1.2 Download Source Code + +Gradle is the build automation tool used by Apache EventMesh (Incubating). Please refer to the [offical guide](https://docs.gradle.org/current/userguide/installation.html) to install the latest release of Gradle. + +Download and extract the source code of the latest release from [EventMesh download](https://eventmesh.apache.org/download). + +```console +wget https://dlcdn.apache.org/incubator/eventmesh/{version}-incubating/apache-eventmesh-{version}-incubating-source.tar.gz + +tar -xvzf apache-eventmesh-1.5.0-incubating-source.tar.gz +``` + +Build the source code with Gradle. + +```console +cd apache-eventmesh-1.5.0-incubating-source +gradle clean dist +``` + +Edit the `eventmesh.properties` to change the configuration (e.g. TCP port, client blacklist) of EventMesh Runtime. + +```console +cd dist +vim conf/eventmesh.properties +``` + +Execute the `start.sh` script to start the EventMesh Runtime server. + +```console +bash bin/start.sh +``` + +### 1.3 Build and Load Plugins + +Apache EventMesh (Incubating) introduces the SPI (Service Provider Interface) mechanism, which enables EventMesh to discover and load the plugins at runtime. The plugins could be installed with these methods: + +- Gradle Dependencies: Declare the plugins as the build dependencies in `eventmesh-starter/build.gradle`. + +```gradle +dependencies { + implementation project(":eventmesh-runtime") + + // Example: Load the RocketMQ plugin + implementation project(":eventmesh-connector-plugin:eventmesh-connector-rocketmq") +} +``` + +- Plugin directory: EventMesh loads the plugins in the `dist/plugin` directory based on `eventmesh.properties`. The `installPlugin` task of Gradle builds and moves the plugins into the `dist/plugin` directory. + +```console +gradle installPlugin +``` + +## 2 Remote deployment + +### 2.1 Dependencies + +``` +64-bit OS，we recommend Linux/Unix； +64-bit JDK 1.8+; +Gradle 7.0+, we recommend 7.0.* +4g+ available disk to deploy eventmesh-store +If you choose standalone mode, you could skip this file and go to the next step: Start Eventmesh-Runtime; if not, you could choose RocketMQ as the store layer. +``` + +### 2.2 Download + +Download and extract the executable binaries of the latest release from [EventMesh download](https://eventmesh.apache.org/download). + +```console +wget https://dlcdn.apache.org/incubator/eventmesh/1.5.0-incubating/apache-eventmesh-1.5.0-incubating-bin.tar.gz + +tar -xvzf apache-eventmesh-1.5.0-incubating-bin.tar.gz +``` + +### 2.3 Deploy + +Edit the `eventmesh.properties` to change the configuration (e.g. TCP port, client blacklist) of EventMesh Runtime. The executable binaries contain all plugins in the bundle, thus there's no need to build them from source code. + +```console +cd apache-eventmesh-1.5.0-incubating +vim conf/eventmesh.properties +``` + +Execute the `start.sh` script to start the EventMesh Runtime server. + +```console +bash bin/start.sh +``` diff --git a/versioned_docs/version-v1.9.0/instruction/03-demo.md b/versioned_docs/version-v1.9.0/instruction/03-demo.md new file mode 100644 index 0000000000..4b7a33baa4 --- /dev/null +++ b/versioned_docs/version-v1.9.0/instruction/03-demo.md @@ -0,0 +1,152 @@ +# Run our demos + +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.apache.eventmesh/eventmesh-sdk-java/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.apache.eventmesh/eventmesh-sdk-java) + +> EventMesh-sdk-java as the client，and comminucate with eventmesh-runtime，to finish the message sub and pub +> +> EventMesh-sdk-java support both async and broadcast. +> +> EventMesh-sdk-java support HTTP, TCP and gRPC. + +The test demos of TCP, HTTP 和 GRPC are in the module **eventmesh-examples** + +## 1 TCP DEMO + +### 1.1 ASYNC + +- Start consumer to subscribe the topic (we have created the TEST-TOPIC-TCP-ASYNC by default, you can also create other topic to test) + +``` +Run the main method of org.apache.eventmesh.tcp.demo.sub.eventmeshmessage.AsyncSubscribe +``` + +- Start producer to publish async message + +``` +Run the main method of org.apache.eventmesh.tcp.demo.pub.eventmeshmessage.AsyncPublish +``` + +### 1.2 BROADCAST + +- Start subscriber to subscribe the topic (we have created the TEST-TOPIC-TCP-BROADCAST by default, you can also create other topic to test) + +``` +Run the main method of org.apache.eventmesh.tcp.demo.sub.eventmeshmessage.AsyncSubscribeBroadcast +``` + +- Start publisher to publish async message + +``` +Run the main method of org.apache.eventmesh.tcp.demo.pub.eventmeshmessage.AsyncPublishBroadcast +``` + +More information about EventMesh-TCP, please refer to [EventMesh TCP](../sdk-java/03-tcp.md) + + +## 2 HTTP DEMO + + +### 2.1 ASYNC + +- The subscriber is a SpringBoot demo, so run this demo to start subscriber (we have created the topic TEST-TOPIC-HTTP-ASYNC by default, you can also create other topic to test) + +``` +Run the main method of org.apache.eventmesh.http.demo.sub.SpringBootDemoApplication +``` + +- Start publisher to publish message + +``` +Run the main method of org.apache.eventmesh.http.demo.pub.eventmeshmessage.AsyncPublishInstance +``` +More information about EventMesh-HTTP, please refer to [EventMesh HTTP](../sdk-java/02-http.md) + +## 3 GRPC DEMO + +### 3.1 ASYNC PUBLISH & WEBHOOK SUBSCRIBE + +- Start publisher to publish message (we have created the topic TEST-TOPIC-GRPC-ASYNC by default, you can also create other topic to test) + +``` +Run the main method of org.apache.eventmesh.grpc.pub.eventmeshmessage.AsyncPublishInstance +``` + +- Start webhook subscriber + +``` +Run the main method of org.apache.eventmesh.grpc.sub.app.SpringBootDemoApplication +``` + +### 3.2 SYNC PUBLISH & STREAM SUBSCRIBE + +- Start Request-Reply publisher to publish message (we have created the topic TEST-TOPIC-GRPC-RR by default, you can also create other topic to test) + +``` +Run the main method of org.apache.eventmesh.grpc.pub.eventmeshmessage.RequestReplyInstance +``` + +- Start stream subscriber + +``` +Run the main method of org.apache.eventmesh.grpc.sub.EventmeshAsyncSubscribe +``` + +### 3.3 PUBLISH BATCH MESSAGE + +- Start publisher to publish batch message (we have created the TEST-TOPIC-GRPC-ASYNC by default, you can also create other topic to test) + +``` +Run the main method of org.apache.eventmesh.grpc.pub.eventmeshmessage.BatchPublishInstance +``` + +More information about EventMesh-gRPC, please refer to [EventMesh gRPC](../sdk-java/04-grpc.md) + +## 4 Run these demos by yourself + +Please refer to [EventMesh Store](./01-store.md) and [EventMesh Runtime](./02-runtime.md) to finish the necessary deployment before try our demo + +After finishing the deployment of store and runtime, you can run our demos in module `eventmesh-examples`: + +### TCP Sub + + ```shell + cd bin + sh tcp_eventmeshmessage_sub.sh + ``` + +### TCP Pub + + ```shell + cd bin + sh tcp_pub_eventmeshmessage.sh + ``` + +### TCP Sub Broadcast + + ```shell + cd bin + sh tcp_sub_eventmeshmessage_broadcast.sh + ``` + +### TCP Pub Broadcast + + ```shell + cd bin + sh tcp_pub_eventmeshmessage_broadcast.sh + ``` + +### HTTP Sub + + ```shell + cd bin + sh http_sub.sh + ``` + +### HTTP Pub + + ```shell + cd bin + sh http_pub_eventmeshmessage.sh + ``` + +You can review the log in the folder `/logs` diff --git a/versioned_docs/version-v1.9.0/instruction/_category_.json b/versioned_docs/version-v1.9.0/instruction/_category_.json new file mode 100644 index 0000000000..690c6eb204 --- /dev/null +++ b/versioned_docs/version-v1.9.0/instruction/_category_.json @@ -0,0 +1,5 @@ +{ + "position": 2, + "label": "Installation and Deployment", + "collapsed": false +} diff --git a/versioned_docs/version-v1.9.0/introduction.md b/versioned_docs/version-v1.9.0/introduction.md new file mode 100644 index 0000000000..42ccefe6a0 --- /dev/null +++ b/versioned_docs/version-v1.9.0/introduction.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 0 +--- + +# Introduction to EventMesh + +[![CI status](https://img.shields.io/github/workflow/status/apache/incubator-eventmesh/Continuous%20Integration?logo=github&style=for-the-badge)](https://github.com/apache/incubator-eventmesh/actions/workflows/ci.yml) +[![CodeCov](https://img.shields.io/codecov/c/gh/apache/incubator-eventmesh/master?logo=codecov&style=for-the-badge)](https://codecov.io/gh/apache/incubator-eventmesh) +[![License](https://img.shields.io/github/license/apache/incubator-eventmesh?style=for-the-badge)](https://www.apache.org/licenses/LICENSE-2.0.html) +[![GitHub Release](https://img.shields.io/github/v/release/apache/eventmesh?style=for-the-badge)](https://github.com/apache/incubator-eventmesh/releases) +[![Slack Status](https://img.shields.io/badge/slack-join_chat-blue.svg?logo=slack&style=for-the-badge)](https://join.slack.com/t/apacheeventmesh/shared_invite/zt-1vpgrvm5u-hh~5H9Aj4TGThaP9tusFfw) + +**Apache EventMesh** is a fully serverless platform used to build distributed [event-driven](https://en.wikipedia.org/wiki/Event-driven_architecture) applications. + +## 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](https://cloudevents.io) specification. +- Rapidly extensible language sdk around [gRPC](https://grpc.io) protocols. +- Rapidly extensible middleware by connectors 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), [Pravega](https://cncf.pravega.io), and [RDMS](https://en.wikipedia.org/wiki/Relational_database)(in progress) using [JDBC](https://en.wikipedia.org/wiki/Java_Database_Connectivity). +- Rapidly extensible controller 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. diff --git a/versioned_docs/version-v1.9.0/roadmap.md b/versioned_docs/version-v1.9.0/roadmap.md new file mode 100644 index 0000000000..7b8ac04623 --- /dev/null +++ b/versioned_docs/version-v1.9.0/roadmap.md @@ -0,0 +1,51 @@ +--- +sidebar_position: 1 +--- + +# Development Roadmap + +The development roadmap of Apache EventMesh is an overview of the planned features and milestones involved in the next several releases. The recent features and bug fixes are documented in the [release notes](https://eventmesh.apache.org/events/release-notes/v1.4.0). The order of the features listed below doesn't correspond to their priorities. + +## List of Features and Milestones + +| Status | Description | Reference | +|-------------------------------------------|---------------------------------| --- | +| **Implemented in 1.0.0** | Support HTTP | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.0.0** | Support TCP | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.0.0** | Support Pub/Sub Event | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.1.1** | Provide Java SDK | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.1.1** | Support HTTPS | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.2.0** | Support RocketMQ as EventStore | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.2.0** | Support Heartbeat | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.3.0** | Integrate with OpenSchema | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.3.0** | Integrate with OpenTelemetry | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.3.0** | Support CloudEvents | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.4.0** | Support gRPC | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.5.0** | Provide Golang SDK | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.5.0** | Support Nacos Registry | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.5.0** | Support Mesh Bridge | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.5.0** | Support Federal Government | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.5.0** | Support Mesh Bridge | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.6.0** | Integrate with Consul | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.6.0** | Support Webhook | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.6.0** | Support etcd | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.7.0** | Support Knative Eventing Infrastructure | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/790), [GSoC '22](https://issues.apache.org/jira/browse/COMDEV-463) | +| **Implemented in 1.7.0** | Support Pravega as EventStore | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/270) | +| **Implemented in 1.7.0** | Support Kafka as EventStore | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/676) | +| **Implemented in 1.7.0** | Support Pulsar as EventStore | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/676) | +| **Implemented in 1.7.0** | Support CNCF Serverless Workflow| [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.7.0** | Support Redis | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.7.0** | Provide Rust SDK | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/815) | +| **Implemented in 1.7.0** | Support Zookeeper | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| **Implemented in 1.7.0** | Support RabbitMQ as EventStore | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/1553) | +| **Implemented in 1.8.0** | Provide Dashboard | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/700), [GSoC '22](https://issues.apache.org/jira/browse/COMDEV-465) +| **In Progress** | Source/Sink Connector | [GitHub Issue](https://github.com/apache/eventmesh/issues/3492) | +| **In Progress** | K8s integration | [GitHub Issue](https://github.com/apache/eventmesh/issues/3327) | +| **In Progress** | OpenFunction integration | [GitHub Issue](https://github.com/apache/eventmesh/issues/2040) | +| **In Progress** | OpenSergo integration | [GitHub Issue](https://github.com/apache/eventmesh/issues/2805) | +| Planned | Transaction Event | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/697) | +| Planned | Provide NodeJS SDK | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/417) | +| Planned | Provide PHP SDK | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/1193) | +| Planned | Event Query Language (EQL) | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/778) | +| Planned | WebAssembly Runtime | [GitHub Issue](https://github.com/apache/incubator-eventmesh/issues/576) | + diff --git a/versioned_docs/version-v1.9.0/sdk-java/01-intro.md b/versioned_docs/version-v1.9.0/sdk-java/01-intro.md new file mode 100644 index 0000000000..33bf9856f5 --- /dev/null +++ b/versioned_docs/version-v1.9.0/sdk-java/01-intro.md @@ -0,0 +1,41 @@ +# Installation + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.apache.eventmesh/eventmesh-sdk-java/badge.svg?style=for-the-badge)](https://maven-badges.herokuapp.com/maven-central/org.apache.eventmesh/eventmesh-sdk-java) + +EventMesh SDK for Java is a collection of Java libraries to integrate EventMesh in a Java application. The SDK supports sending and receiving synchronous messages, asynchronous messages, and broadcast messages in TCP, HTTP, and gRPC protocols. The SDK implements EventMesh Message, CloudEvents, and OpenMessaging formats. The demo project is available in the [`eventmesh-example`](https://github.com/apache/incubator-eventmesh/tree/master/eventmesh-examples) module. + + + + +​ To install EventMesh SDK for Java with Gradle, declare `org.apache.eventmesh:eventmesh-sdk-java` as `implementation` in the dependencies block of the module's `build.gradle` file. + +```groovy +dependencies { + implementation 'org.apache.eventmesh:eventmesh-sdk-java:1.4.0' +} +``` + + + + + + +To install EventMesh SDK for Java with Maven, declare `org.apache.eventmesh:eventmesh-sdk-java` as a dependency in the dependencies block of the project's `pom.xml` file. + +```xml + + + org.apache.eventmesh + eventmesh-sdk-java + 1.4.0 + + +``` + + + + + diff --git a/versioned_docs/version-v1.9.0/sdk-java/02-http.md b/versioned_docs/version-v1.9.0/sdk-java/02-http.md new file mode 100644 index 0000000000..bf2e5c6efa --- /dev/null +++ b/versioned_docs/version-v1.9.0/sdk-java/02-http.md @@ -0,0 +1,115 @@ +# HTTP Protocol + +EventMesh SDK for Java implements the HTTP producer and consumer of asynchronous messages. Both the producer and consumer require an instance of `EventMeshHttpClientConfig` class that specifies the configuration of EventMesh HTTP client. The `liteEventMeshAddr`, `userName`, and `password` fields should match the `eventmesh.properties` file of EventMesh runtime. + +```java +import org.apache.eventmesh.client.http.conf.EventMeshHttpClientConfig; +import org.apache.eventmesh.common.utils.IPUtils; +import org.apache.eventmesh.common.utils.ThreadUtils; + +public class HTTP { + public static void main(String[] args) throws Exception { + EventMeshHttpClientConfig eventMeshClientConfig = EventMeshHttpClientConfig.builder() + .liteEventMeshAddr("localhost:10105") + .producerGroup("TEST_PRODUCER_GROUP") + .env("env") + .idc("idc") + .ip(IPUtils.getLocalAddress()) + .sys("1234") + .pid(String.valueOf(ThreadUtils.getPID())) + .userName("eventmesh") + .password("password") + .build(); + /* ... */ + } +} +``` + +## HTTP Consumer + +The `EventMeshHttpConsumer` class implements the `heartbeat`, `subscribe`, and `unsubscribe` methods. The `subscribe` method accepts a list of `SubscriptionItem` that defines the topics to be subscribed and a callback URL. + +```java +import org.apache.eventmesh.client.http.consumer.EventMeshHttpConsumer; +import org.apache.eventmesh.common.protocol.SubscriptionItem; +import org.apache.eventmesh.common.protocol.SubscriptionMode; +import org.apache.eventmesh.common.protocol.SubscriptionType; +import com.google.common.collect.Lists; + +public class HTTP { + final String url = "http://localhost:8080/callback"; + final List topicList = Lists.newArrayList( + new SubscriptionItem("eventmesh-async-topic", SubscriptionMode.CLUSTERING, SubscriptionType.ASYNC) + ); + + public static void main(String[] args) throws Exception { + /* ... */ + eventMeshHttpConsumer = new EventMeshHttpConsumer(eventMeshClientConfig); + eventMeshHttpConsumer.heartBeat(topicList, url); + eventMeshHttpConsumer.subscribe(topicList, url); + /* ... */ + eventMeshHttpConsumer.unsubscribe(topicList, url); + } +} +``` + +The EventMesh runtime will send a POST request that contains the message in the [CloudEvents format](https://github.com/cloudevents/spec) to the callback URL. The [`SubController.java` file](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-examples/src/main/java/org/apache/eventmesh/http/demo/sub/controller/SubController.java) implements a Spring Boot controller that receives and parses the callback messages. + +## HTTP Producer + +The `EventMeshHttpProducer` class implements the `publish` method. The `publish` method accepts the message to be published and an optional timeout value. The message should be an instance of either of these classes: + +- `org.apache.eventmesh.common.EventMeshMessage` +- `io.cloudevents.CloudEvent` +- `io.openmessaging.api.Message` + +```java +import org.apache.eventmesh.client.http.producer.EventMeshHttpProducer; +import org.apache.eventmesh.client.tcp.common.EventMeshCommon; +import org.apache.eventmesh.common.Constants; +import org.apache.eventmesh.common.utils.JsonUtils; + +import io.cloudevents.CloudEvent; +import io.cloudevents.core.builder.CloudEventBuilder; + +public class HTTP { + public static void main(String[] args) throws Exception { + /* ... */ + EventMeshHttpProducer eventMeshHttpProducer = new EventMeshHttpProducer(eventMeshClientConfig); + Map content = new HashMap<>(); + content.put("content", "testAsyncMessage"); + + CloudEvent event = CloudEventBuilder.v1() + .withId(UUID.randomUUID().toString()) + .withSubject("eventmesh-async-topic") + .withSource(URI.create("/")) + .withDataContentType("application/cloudevents+json") + .withType(EventMeshCommon.CLOUD_EVENTS_PROTOCOL_NAME) + .withData(JsonUtils.serialize(content).getBytes(StandardCharsets.UTF_8)) + .withExtension(Constants.EVENTMESH_MESSAGE_CONST_TTL, String.valueOf(4 * 1000)) + .build(); + eventMeshHttpProducer.publish(event); + } +} +``` + +## Using Curl Command + +You can also publish/subscribe event without eventmesh SDK. + +### Publish + +```shell +curl -H "Content-Type:application/json" -X POST -d '{"name": "admin", "pass":"12345678"}' http://127.0.0.1:10105/eventmesh/publish/TEST-TOPIC-HTTP-ASYNC +``` + +After you start the eventmesh runtime server, you can use the curl command publish the event to the specific topic with the HTTP POST method and the package body must be in JSON format. The publish url like (http://127.0.0.1:10105/eventmesh/publish/TEST-TOPIC-HTTP-ASYNC), and you will get the publish successful result. + +### Subscribe + +```shell +curl -H "Content-Type:application/json" -X POST -d '{"url": "http://127.0.0.1:8088/sub/test", "consumerGroup":"TEST-GROUP", "topic":[{"mode":"CLUSTERING","topic":"TEST-TOPIC-HTTP-ASYNC","type":"ASYNC"}]}' http://127.0.0.1:10105/eventmesh/subscribe/local +``` + +After you start the eventmesh runtime server, you can use the curl command to subscribe the specific topic list with the HTTP POST method, and the package body must be in JSON format. The subscribe url like (http://127.0.0.1:10105/eventmesh/subscribe/local), and you will get the subscribe successful result. You should pay attention to the `url` field in the package body, which means you need to set up an HTTP service at the specified URL, you can see the example in the `eventmesh-examples` module. + diff --git a/versioned_docs/version-v1.9.0/sdk-java/03-tcp.md b/versioned_docs/version-v1.9.0/sdk-java/03-tcp.md new file mode 100644 index 0000000000..1643a41dca --- /dev/null +++ b/versioned_docs/version-v1.9.0/sdk-java/03-tcp.md @@ -0,0 +1,118 @@ +# TCP Protocol + +EventMesh SDK for Java implements the TCP producer and consumer of synchronous, asynchronous, and broadcast messages. Both the producer and consumer require an instance of `EventMeshTCPClientConfig` class that specifies the configuration of EventMesh TCP client. The `host` and `port` fields should match the `eventmesh.properties` file of EventMesh runtime. + +```java +import org.apache.eventmesh.client.tcp.conf.EventMeshTCPClientConfig; +import org.apache.eventmesh.client.tcp.common.ReceiveMsgHook; +import io.cloudevents.CloudEvent; + +public class AsyncSubscribe implements ReceiveMsgHook { + public static void main(String[] args) throws InterruptedException { + EventMeshTCPClientConfig eventMeshTcpClientConfig = EventMeshTCPClientConfig.builder() + .host(eventMeshIp) + .port(eventMeshTcpPort) + .userAgent(userAgent) + .build(); + /* ... */ + } +} +``` + +## TCP Consumer + +The consumer should implement the `ReceiveMsgHook` class, which is defined in [`ReceiveMsgHook.java`](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-sdk-java/src/main/java/org/apache/eventmesh/client/tcp/common/ReceiveMsgHook.java). + +```java +public interface ReceiveMsgHook { + Optional handle(ProtocolMessage msg); +} +``` + +The `EventMeshTCPClient` class implements the `subscribe` method. The `subscribe` method accepts the topic, the `SubscriptionMode`, and the `SubscriptionType`. The `handle` method will be invoked when the consumer receives a message from the topic it subscribes. If the `SubscriptionType` is `SYNC`, the return value of `handle` will be sent back to the producer. + +```java +import org.apache.eventmesh.client.tcp.EventMeshTCPClient; +import org.apache.eventmesh.client.tcp.EventMeshTCPClientFactory; +import org.apache.eventmesh.client.tcp.common.ReceiveMsgHook; +import org.apache.eventmesh.common.protocol.SubscriptionMode; +import org.apache.eventmesh.common.protocol.SubscriptionType; +import io.cloudevents.CloudEvent; + +public class TCPConsumer implements ReceiveMsgHook { + public static TCPConsumer handler = new TCPConsumer(); + private static EventMeshTCPClient client; + + public static void main(String[] args) throws Exception { + client = EventMeshTCPClientFactory.createEventMeshTCPClient( + eventMeshTcpClientConfig, + CloudEvent.class + ); + client.init(); + + client.subscribe( + "eventmesh-sync-topic", + SubscriptionMode.CLUSTERING, + SubscriptionType.SYNC + ); + + client.registerSubBusiHandler(handler); + client.listen(); + } + + @Override + public Optional handle(CloudEvent message) { + log.info("Messaged received: {}", message); + return Optional.of(message); + } +} +``` + +## TCP Producer + +### Asynchronous Producer + +The `EventMeshTCPClient` class implements the `publish` method. The `publish` method accepts the message to be published and an optional timeout value and returns the response message from the consumer. + +```java +/* ... */ +client = EventMeshTCPClientFactory.createEventMeshTCPClient(eventMeshTcpClientConfig, CloudEvent.class); +client.init(); + +CloudEvent event = CloudEventBuilder.v1() + .withId(UUID.randomUUID().toString()) + .withSubject(ExampleConstants.EVENTMESH_GRPC_ASYNC_TEST_TOPIC) + .withSource(URI.create("/")) + .withDataContentType(ExampleConstants.CLOUDEVENT_CONTENT_TYPE) + .withType(EventMeshCommon.CLOUD_EVENTS_PROTOCOL_NAME) + .withData(JsonUtils.serialize(content).getBytes(StandardCharsets.UTF_8)) + .withExtension(Constants.EVENTMESH_MESSAGE_CONST_TTL, String.valueOf(4 * 1000)) + .build(); +client.publish(event, 1000); +``` + +### Synchronous Producer + +The `EventMeshTCPClient` class implements the `rr` method. The `rr` method accepts the message to be published and an optional timeout value and returns the response message from the consumer. + +```java +/* ... */ +client = EventMeshTCPClientFactory.createEventMeshTCPClient(eventMeshTcpClientConfig, CloudEvent.class); +client.init(); + +CloudEvent event = CloudEventBuilder.v1() + .withId(UUID.randomUUID().toString()) + .withSubject(ExampleConstants.EVENTMESH_GRPC_ASYNC_TEST_TOPIC) + .withSource(URI.create("/")) + .withDataContentType(ExampleConstants.CLOUDEVENT_CONTENT_TYPE) + .withType(EventMeshCommon.CLOUD_EVENTS_PROTOCOL_NAME) + .withData(JsonUtils.serialize(content).getBytes(StandardCharsets.UTF_8)) + .withExtension(Constants.EVENTMESH_MESSAGE_CONST_TTL, String.valueOf(4 * 1000)) + .build(); + +Package response = client.rr(event, 1000); +CloudEvent replyEvent = EventFormatProvider + .getInstance() + .resolveFormat(JsonFormat.CONTENT_TYPE) + .deserialize(response.getBody().toString().getBytes(StandardCharsets.UTF_8)); +``` diff --git a/versioned_docs/version-v1.9.0/sdk-java/04-grpc.md b/versioned_docs/version-v1.9.0/sdk-java/04-grpc.md new file mode 100644 index 0000000000..81f03a8d83 --- /dev/null +++ b/versioned_docs/version-v1.9.0/sdk-java/04-grpc.md @@ -0,0 +1,174 @@ +# gRPC Protocol + +EventMesh SDK for Java implements the gRPC producer and consumer of synchronous, asynchronous, and broadcast messages. Both the producer and consumer require an instance of `EventMeshGrpcClientConfig` class that specifies the configuration of EventMesh gRPC client. The `liteEventMeshAddr`, `userName`, and `password` fields should match the `eventmesh.properties` file of EventMesh runtime. + +```java +import org.apache.eventmesh.client.grpc.config.EventMeshGrpcClientConfig; +import org.apache.eventmesh.client.grpc.consumer.ReceiveMsgHook; +import io.cloudevents.CloudEvent; + +public class CloudEventsAsyncSubscribe implements ReceiveMsgHook { + public static void main(String[] args) throws InterruptedException { + EventMeshGrpcClientConfig eventMeshClientConfig = EventMeshGrpcClientConfig.builder() + .serverAddr("localhost") + .serverPort(10205) + .consumerGroup(ExampleConstants.DEFAULT_EVENTMESH_TEST_CONSUMER_GROUP) + .env("env").idc("idc") + .sys("1234").build(); + /* ... */ + } +} +``` + +## gRPC Consumer + +### Stream Consumer + +The EventMesh runtime sends the message from producers to the stream consumer as a series of event streams. The consumer should implement the `ReceiveMsgHook` class, which is defined in [`ReceiveMsgHook.java`](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-sdk-java/src/main/java/org/apache/eventmesh/client/grpc/consumer/ReceiveMsgHook.java). + +```java +public interface ReceiveMsgHook { + Optional handle(T msg) throws Throwable; + String getProtocolType(); +} +``` + +The `EventMeshGrpcConsumer` class implements the `registerListener`, `subscribe`, and `unsubscribe` methods. The `subscribe` method accepts a list of `SubscriptionItem` that defines the topics to be subscribed to. The `registerListener` accepts an instance of a class that implements the `ReceiveMsgHook`. The `handle` method will be invoked when the consumer receives a message from the topic it subscribes. If the `SubscriptionType` is `SYNC`, the return value of `handle` will be sent back to the producer. + +```java +import org.apache.eventmesh.client.grpc.consumer.EventMeshGrpcConsumer; +import org.apache.eventmesh.client.grpc.consumer.ReceiveMsgHook; +import org.apache.eventmesh.client.tcp.common.EventMeshCommon; +import org.apache.eventmesh.common.protocol.SubscriptionItem; +import org.apache.eventmesh.common.protocol.SubscriptionMode; +import org.apache.eventmesh.common.protocol.SubscriptionType; +import io.cloudevents.CloudEvent; + +public class CloudEventsAsyncSubscribe implements ReceiveMsgHook { + public static CloudEventsAsyncSubscribe handler = new CloudEventsAsyncSubscribe(); + public static void main(String[] args) throws InterruptedException { + /* ... */ + SubscriptionItem subscriptionItem = new SubscriptionItem( + "eventmesh-async-topic", + SubscriptionMode.CLUSTERING, + SubscriptionType.ASYNC + ); + EventMeshGrpcConsumer eventMeshGrpcConsumer = new EventMeshGrpcConsumer(eventMeshClientConfig); + + eventMeshGrpcConsumer.init(); + eventMeshGrpcConsumer.registerListener(handler); + eventMeshGrpcConsumer.subscribe(Collections.singletonList(subscriptionItem)); + /* ... */ + eventMeshGrpcConsumer.unsubscribe(Collections.singletonList(subscriptionItem)); + } + + @Override + public Optional handle(CloudEvent message) { + log.info("Messaged received: {}", message); + return Optional.empty(); + } + + @Override + public String getProtocolType() { + return EventMeshCommon.CLOUD_EVENTS_PROTOCOL_NAME; + } +} +``` + +### Webhook Consumer + +The `subscribe` method of the `EventMeshGrpcConsumer` class accepts a list of `SubscriptionItem` that defines the topics to be subscribed and an optional callback URL. If the callback URL is provided, the EventMesh runtime will send a POST request that contains the message in the [CloudEvents format](https://github.com/cloudevents/spec) to the callback URL. The [`SubController.java` file](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-examples/src/main/java/org/apache/eventmesh/grpc/sub/app/controller/SubController.java) implements a Spring Boot controller that receives and parses the callback messages. + +```java +import org.apache.eventmesh.client.grpc.consumer.EventMeshGrpcConsumer; +import org.apache.eventmesh.client.grpc.consumer.ReceiveMsgHook; +import org.apache.eventmesh.client.tcp.common.EventMeshCommon; +import org.apache.eventmesh.common.protocol.SubscriptionItem; +import org.apache.eventmesh.common.protocol.SubscriptionMode; +import org.apache.eventmesh.common.protocol.SubscriptionType; + +@Component +public class SubService implements InitializingBean { + final String url = "http://localhost:8080/callback"; + + public void afterPropertiesSet() throws Exception { + /* ... */ + eventMeshGrpcConsumer = new EventMeshGrpcConsumer(eventMeshClientConfig); + eventMeshGrpcConsumer.init(); + + SubscriptionItem subscriptionItem = new SubscriptionItem( + "eventmesh-async-topic", + SubscriptionMode.CLUSTERING, + SubscriptionType.ASYNC + ); + + eventMeshGrpcConsumer.subscribe(Collections.singletonList(subscriptionItem), url); + /* ... */ + eventMeshGrpcConsumer.unsubscribe(Collections.singletonList(subscriptionItem), url); + } +} +``` + +## gRPC Producer + +### Asynchronous Producer + +The `EventMeshGrpcProducer` class implements the `publish` method. The `publish` method accepts the message to be published and an optional timeout value. The message should be an instance of either of these classes: + +- `org.apache.eventmesh.common.EventMeshMessage` +- `io.cloudevents.CloudEvent` + +```java +/* ... */ +EventMeshGrpcProducer eventMeshGrpcProducer = new EventMeshGrpcProducer(eventMeshClientConfig); +eventMeshGrpcProducer.init(); + +Map content = new HashMap<>(); +content.put("content", "testAsyncMessage"); + +CloudEvent event = CloudEventBuilder.v1() + .withId(UUID.randomUUID().toString()) + .withSubject(ExampleConstants.EVENTMESH_GRPC_ASYNC_TEST_TOPIC) + .withSource(URI.create("/")) + .withDataContentType(ExampleConstants.CLOUDEVENT_CONTENT_TYPE) + .withType(EventMeshCommon.CLOUD_EVENTS_PROTOCOL_NAME) + .withData(JsonUtils.serialize(content).getBytes(StandardCharsets.UTF_8)) + .withExtension(Constants.EVENTMESH_MESSAGE_CONST_TTL, String.valueOf(4 * 1000)) + .build(); +eventMeshGrpcProducer.publish(event); +``` + +### Synchronous Producer + +The `EventMeshGrpcProducer` class implements the `requestReply` method. The `requestReply` method accepts the message to be published and an optional timeout value. The method returns the message returned from the consumer. The message should be an instance of either of these classes: + +- `org.apache.eventmesh.common.EventMeshMessage` +- `io.cloudevents.CloudEvent` + +### Batch Producer + +The `EventMeshGrpcProducer` class overloads the `publish` method, which accepts a list of messages to be published and an optional timeout value. The messages in the list should be an instance of either of these classes: + +- `org.apache.eventmesh.common.EventMeshMessage` +- `io.cloudevents.CloudEvent` + +```java +/* ... */ +List cloudEventList = new ArrayList<>(); +for (int i = 0; i < 5; i++) { + CloudEvent event = CloudEventBuilder.v1() + .withId(UUID.randomUUID().toString()) + .withSubject(ExampleConstants.EVENTMESH_GRPC_ASYNC_TEST_TOPIC) + .withSource(URI.create("/")) + .withDataContentType(ExampleConstants.CLOUDEVENT_CONTENT_TYPE) + .withType(EventMeshCommon.CLOUD_EVENTS_PROTOCOL_NAME) + .withData(JsonUtils.serialize(content).getBytes(StandardCharsets.UTF_8)) + .withExtension(Constants.EVENTMESH_MESSAGE_CONST_TTL, String.valueOf(4 * 1000)) + .build(); + + cloudEventList.add(event); +} + +eventMeshGrpcProducer.publish(cloudEventList); +/* ... */ +``` diff --git a/versioned_docs/version-v1.9.0/sdk-java/_category_.json b/versioned_docs/version-v1.9.0/sdk-java/_category_.json new file mode 100644 index 0000000000..e93d4cdd8a --- /dev/null +++ b/versioned_docs/version-v1.9.0/sdk-java/_category_.json @@ -0,0 +1,5 @@ +{ + "position": 3, + "label": "EventMesh SDK for Java", + "collapsed": false +} diff --git a/versioned_docs/version-v1.9.0/upgrade-guide/01-upgrade-guide.md b/versioned_docs/version-v1.9.0/upgrade-guide/01-upgrade-guide.md new file mode 100644 index 0000000000..e300cdf57e --- /dev/null +++ b/versioned_docs/version-v1.9.0/upgrade-guide/01-upgrade-guide.md @@ -0,0 +1,15 @@ +# EventMesh Upgrade Guide + +> This article briefly introduces the precautions for upgrading EventMesh from version 1.2.0 to the latest version. + +## 1. Precautions + +**If you are using EventMesh for the first time, you can ignore this chapter.** + +## 2. Service upgrade installation + +The upgrade and startup of the EventMesh runtime module can be done in accordance with the [deployment guide](https://eventmesh.apache.org/docs/instruction/runtime). + +For differences and changes between versions, please refer to the [release notes](https://eventmesh.apache.org/events/release-notes) of different versions. Compatibility between versions can be achieved. + +If you need to use the latest features, follow the release note to upgrade to the corresponding version That’s it, and different plug-in module components can be packaged and configured separately. You can refer to the corresponding [feature design documents and guidelines](https://eventmesh.apache.org/docs/design-document/) diff --git a/versioned_docs/version-v1.9.0/upgrade-guide/_category_.json b/versioned_docs/version-v1.9.0/upgrade-guide/_category_.json new file mode 100644 index 0000000000..af764643e9 --- /dev/null +++ b/versioned_docs/version-v1.9.0/upgrade-guide/_category_.json @@ -0,0 +1,5 @@ +{ + "position": 7, + "label": "Upgrade Guide", + "collapsed": false +} diff --git a/versioned_sidebars/version-v1.9.0-sidebars.json b/versioned_sidebars/version-v1.9.0-sidebars.json new file mode 100644 index 0000000000..caea0c03ba --- /dev/null +++ b/versioned_sidebars/version-v1.9.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/versions.json b/versions.json index 3196821eb6..d0e522b67f 100644 --- a/versions.json +++ b/versions.json @@ -1,4 +1,5 @@ [ + "v1.9.0", "v1.8.0", "v1.7.0", "v1.6.0",