https://github.com/convergencelabs/convergence-proto
The Convergence Client-Server Protocol
https://github.com/convergencelabs/convergence-proto
convergence protocol protocol-buffers realtime
Last synced: 4 months ago
JSON representation
The Convergence Client-Server Protocol
- Host: GitHub
- URL: https://github.com/convergencelabs/convergence-proto
- Owner: convergencelabs
- License: apache-2.0
- Created: 2019-11-11T05:30:13.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-07-07T21:04:20.000Z (almost 3 years ago)
- Last Synced: 2025-10-24T06:51:32.742Z (8 months ago)
- Topics: convergence, protocol, protocol-buffers, realtime
- Language: Scala
- Homepage: https://convergence.io
- Size: 222 KB
- Stars: 13
- Watchers: 4
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Convergence Protocol
[](https://github.com/convergencelabs/convergence-proto/actions/workflows/scala-build.yml)
[](https://github.com/convergencelabs/convergence-proto/actions/workflows/js-build.yml)
This repository defines the Convergence client-server, realtime, WebSocket protocol. The protocol is specified using [Google Protocol Buffers](https://developers.google.com/protocol-buffers) version 3 messages. The protocol itself can be found in the [src/main/protobuf](src/main/protobuf) directory.
Convergence supplies a JavaScript client with the server implemented in Scala. Thus this project builds JavaScript and Scala bindings. The JavaScript bindings are provided by [protobuf.js](https://github.com/protobufjs/protobuf.js). The Scala bindings are provided by [ScalaPB](https://scalapb.github.io/).
# Dependencies
* [NodeJS](https://nodejs.org/) >= 16.0
* [protobuf.js](https://github.com/protobufjs/protobuf.js) = 6.11
* [sbt](https://www.scala-sbt.org/) >= 1.5
* [ScalaPB](https://scalapb.github.io/) = 0.11.0
# Installation
## JavaScript
To use the JavaScript protocol bindings use the following command:
```shell
npm i -D @convergence/convergence-proto
```
## Scala
To use the Scala protocol bindings add the following dependency:
```shell
libraryDependencies += "com.convergencelabs" %% "convergence-proto-scala" % "1.0.0"
```
Run `sbt publishLocal` to publish to a local repository for e.g. the [Convergence Server](https://github.com/convergencelabs/convergence-server) to reference.
# Building
There are different build commands for each language binding. They are as follows:
* **JavaScript**: `npm run dist`
* **Scala**: `sbt compile`
# Protocol
The Convergence client-server protocol is intended to be sent over a [WebSocket](https://en.wikipedia.org/wiki/WebSocket) connection between a Convergence client and the Convergence Server. Each message sent between the client and server is an instance of the [ConvergenceMessage](src/main/protobuf/convergenceMessage.proto) protocol buffer message. The rough structure of the message is as follows:
```proto
message ConvergenceMessage {
google.protobuf.Int32Value requestId = 1;
google.protobuf.Int32Value responseId = 2;
oneof body {
// messages
}
}
```
The body field will contain a specific message sent or received. WebSockets are an asynchronous, bi-directional streaming communication channel. However, Convergence has several request / response style exchanges. The ConvergenceMessage structure implements a correlation id strategy to enable request / response behavior over WebSockets.
The best way to understand the protocol is to simply view the `.proto` files in the [src/main/protobuf](src/main/protobuf) directory.
## License
The Convergence Protocol is licensed under the [Apache 2.0](LICENSE) license. Refer to the [LICENSE.txt](LICENSE) for the specific terms and conditions of the license.
The Convergence Protocol is also available under a Commercial License. If you are interested in a non-open source license please contact us at [Convergence Labs](https://convergencelabs.com).