Wechaty Puppet Service

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#

When a Wechaty user is using a token with Wechaty, the Wechaty will use that token to connect to the specific puppet service.

The mechanism behind is the Puppet Service Discovery, which can resolve the IP of gGRPC service by the token, is implemented by the following steps:

construct a URL: https://api.chatie.io/v0/hosties/${TOKEN}
make a GET request to the URL, and expect to get the following json object:
{"ip":"1.2.3.4","port":1234}
the above 1.2.3.4 will be the gRPC server, and the port 1234 is the gRPC port.
if the token is not registered, then the GET request will get a HTTP 404 with the below object:
{"ip":"0.0.0.0","port":0}

That's the Wechaty Puppet Service Discovery.

For the Wechaty SDK, we should 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.

There at least have two way to do the registration to publish tokens:

By running a Wechaty docker command
By following the Wechaty Puppet Service Registration Protocol

1. Registration the Token with Docker#

We have an issue describing the steps in details:

Through the above steps, you can publish a token with any existing wechaty puppets.

Related issues:

2. Register the Token with Protocol#

The current process can be described as the following two steps:

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 https://github.com/wechaty/wechaty/blob/7e97620e2a92841227a6ae355efa615c5af95b32/src/io.ts#L236)
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 https://github.com/wechaty/wechaty/blob/7e97620e2a92841227a6ae355efa615c5af95b32/src/io.ts#L363)

You can learn more about the registration protocol via this discussion: Support rock puppet service provider. #98

Registration Process Discussion#

The current process can be described as the following two steps:

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 https://github.com/wechaty/wechaty/blob/7e97620e2a92841227a6ae355efa615c5af95b32/src/io.ts#L236)
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 https://github.com/wechaty/wechaty/blob/7e97620e2a92841227a6ae355efa615c5af95b32/src/io.ts#L363)

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: https://github.com/wechaty/wechaty-puppet-service/issues/98

Related Resources#

Wechaty Puppet Service gRPC: https://github.com/wechaty/grpc