diff --git a/docusaurus/docs/specs/service.md b/docusaurus/docs/specs/service.md index 508407f5fbf..bace2027717 100644 --- a/docusaurus/docs/specs/service.md +++ b/docusaurus/docs/specs/service.md @@ -2,12 +2,9 @@ title: Wechaty Puppet Service sidebar_label: Service --- +This section is all about the Wechaty Puppet Service Registration & Discovery, which is the core system for our **token**. -Recently, the Wechaty community has grown fast, we have more and more multi-language Wechaty (Python, Go, .NET, Java, PHP, Scala, etc) and puppet service providers (WXWork, Donut, Rock, PadLocal, etc). - -To make our ecosystem keep clean and healthy, I'd like to write this post as a draft specification for the Wechaty Puppet Service Registration & Discovery, which is the core system for support our **token**. - -## The Discovery +## The Puppet Service Discovery When a Wechaty user is using a **token** with Wechaty, the Wechaty will use that **token** to connect to the specific puppet service. @@ -16,71 +13,69 @@ The mechanism behind is the **Puppet Service Discovery**, which can resolve the 1. construct a URL: `https://api.chatie.io/v0/hosties/${TOKEN}` 1. make a GET request to the URL, and expect to get the following json object: - ```json - {"host":"1.2.3.4","port":5678} - ``` +```json +{"host":"1.2.3.4","port":1234} +``` -1. the above `1.2.3.4` will be the gRPC server, and the port `5678` is the gRPC port. -1. if the token is not registered, then the GET request will get a HTTP 404 with the below object: +**the above `1.2.3.4` will be the gRPC server, and the port `1234` is the gRPC port.** - ```json - {"host":"0.0.0.0","port":0} - ``` - -That's the Wechaty Puppet Service Discovery. +1. if the token is not registered, then the GET request will get a HTTP 404 with the below object: -For the Wechaty SDK, we should support the following environment variables so that the users can switch between different languages without any changes: +```json +{"host":"0.0.0.0","port":0} +``` -1. `export WECHATY_PUPPET_SERVICE_TOKEN=${TOKEN}` +1. For the Wechaty SDK, we support the following environment variables so that the users can switch between different languages without any changes: +`export WECHATY_PUPPET_SERVICE_TOKEN=${TOKEN}` ## The Registration -In order to publish a Wechaty Puppet Service Token to the Wechaty community, we need to register this token by following the Wechaty Puppet Service Registration process. +In order to publish a Wechaty Puppet Service Token to the Wechaty community, you need to register this token by following the Wechaty Puppet Service Registration process. -There at least have two way to do the registration to publish tokens: +There are two ways to do the registration to publish the tokens: 1. By running a Wechaty docker command -1. By following the Wechaty Puppet Service Registration Protocol +2. By following the Wechaty Puppet Service Registration Protocol ### 1. Registration the Token with Docker -We have an issue describing the steps in details: +You can visit the links below which gives a more detailed step by step description about registration of token using Docker. 1. [How to create your own Wechaty Puppet Service Token with the Web Protocol #1986](https://github.com/wechaty/wechaty/issues/1986) -1. [Using your Puppet PadPlus token with Python, Java, and Go Wechaty #1985](https://github.com/wechaty/wechaty/issues/1985) +2. [Using your Puppet PadPlus token with Python, Java, and Go Wechaty #1985](https://github.com/wechaty/wechaty/issues/1985) Through the above steps, you can publish a token with any existing wechaty puppets. - -Related issues: +Other Related issues are listed below : 1. -1. -1. +2. +3. ### 2. Register the Token with Protocol -The current process can be described as the following two steps: +The current process can be described as the following steps: -1. The `puppet server` sends a WebSocket connection to `wss://api.chatie.io/v0/websocket`, with an HTTP authorization header `Token rock_token_here`. After the connection has been established, the `api.chatie.io` service will register your token online. (refer to the source code at ) -1. When a puppet service discovery query has been sent to `api.chatie.io` like `https://api.chatie.io/v0/hosties/puppet_rock_token` has been visited, the `api.chatie.io` will send a JSONRPC to you via the WebSocket connection, with the method name `hostieGrpcPort`, and you need to return your service port so that it can be returned to the user. (refer to the source code at ) +1. The `puppet server` sends a WebSocket connection to `wss://api.chatie.io/v0/websocket`, with an HTTP authorization header `Token rock_token_here`. After the connection has been established, the `api.chatie.io` service will register your token online.See the +[source code](https://github.com/wechaty/wechaty/blob/7e97620e2a92841227a6ae355efa615c5af95b32/src/io.ts#L236) +2. When a puppet service discovery query has been sent to `api.chatie.io` like `https://api.chatie.io/v0/hosties/puppet_rock_token` has been visited, the `api.chatie.io` will send a JSONRPC to you via the WebSocket connection, with the method name `hostieGrpcPort`, and you need to return your service port so that it can be returned to the user.See the [source code](https://github.com/wechaty/wechaty/blob/7e97620e2a92841227a6ae355efa615c5af95b32/src/io.ts#L363) +3. You can learn more about the registration protocol via this discussion: [Support rock puppet service provider. #98](https://github.com/wechaty/wechaty-puppet-service/issues/98) +The following is a pictorial representation that describes the process above. -You can learn more about the registration protocol via this discussion: [Support rock puppet service provider. #98](https://github.com/wechaty/wechaty-puppet-service/issues/98) +![Sequence Diagram](../../static/img/docs/wechaty-sequence-diagram.webp "Registration Protocol") ## Registration Process Discussion The current process can be described as the following two steps: -1. The `Wechaty Puppet Server` sends a WebSocket connection to `wss://api.chatie.io/v0/websocket`, with an HTTP authorization header `Token puppet_servcie_token_here`. After the connection has been established, the `api.chatie.io` service will register your token online. (refer to the source code at ) -1. When a Wechaty Puppet Service Discovery Query has been sent to `api.chatie.io` like `https://api.chatie.io/v0/hosties/puppet_service_token` has been visited, the `api.chatie.io` will send a JSONRPC to you via the WebSocket connection, with the method name `hostieGrpcPort`, and you need to return your service port so that it can be returned to the user. (refer to the source code at ) - -The above two steps are the current way we are working with our service. So please feel free to read the source code from the links above, then I believe you can register multiple rock puppet token to our service with the same IP and Port without any problem. - -See: +1. The `Wechaty Puppet Server` sends a WebSocket connection to `wss://api.chatie.io/v0/websocket`, with an HTTP authorization header `Token puppet_servcie_token_here`. After the connection has been established, the `api.chatie.io` service will register your token online.Refer to the [source code](https://github.com/wechaty/wechaty/blob/7e97620e2a92841227a6ae355efa615c5af95b32/src/io.ts#L236) +2. When a Wechaty Puppet Service Discovery Query has been sent to `api.chatie.io` like `https://api.chatie.io/v0/hosties/puppet_service_token` has been visited, the `api.chatie.io` will send a JSONRPC to you via the WebSocket connection, with the method name `hostieGrpcPort`, and you need to return your service port so that it can be returned to the user.Refer to the [source code](https://github.com/wechaty/wechaty/blob/7e97620e2a92841227a6ae355efa615c5af95b32/src/io.ts#L363) +3. Wechaty allows to register multiple rock puppet token to the service with the same IP and Port without any problem. +for more information checkout the [link](https://github.com/wechaty/wechaty-puppet-service/issues/98). ## Related Resources -1. Wechaty Puppet Service gRPC: +- [Wechaty Puppet Service gRPC](https://github.com/wechaty/grpc) ## Blogs -1. [Introducing Wechaty Puppet Service (Providers), @huan, Jan 14, 2021](https://wechaty.js.org/2021/01/14/wechaty-puppet-service/) +- [Introducing Wechaty Puppet Service (Providers), @huan, Jan 14, 2021](https://wechaty.js.org/2021/01/14/wechaty-puppet-service/) diff --git a/docusaurus/static/img/docs/wechaty-sequence-diagram.webp b/docusaurus/static/img/docs/wechaty-sequence-diagram.webp new file mode 100644 index 00000000000..38cce05c60d Binary files /dev/null and b/docusaurus/static/img/docs/wechaty-sequence-diagram.webp differ