This repository defines the Convergence client-server, realtime, WebSocket protocol. The protocol is specified using Google Protocol Buffers version 3 messages. The protocol itself can be found in the 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. The Scala bindings are provided by ScalaPB.

• NodeJS >= 16.0
• protobuf.js = 6.11
• sbt >= 1.5
• ScalaPB = 0.11.0

To use the JavaScript protocol bindings use the following command:

npm i -D @convergence/convergence-proto

To use the Scala protocol bindings add the following dependency:

libraryDependencies += "com.convergencelabs" %% "convergence-proto-scala" % "1.0.0"

Run sbt publishLocal to publish to a local repository for e.g. the Convergence Server to reference.

There are different build commands for each language binding. They are as follows:

• JavaScript: npm run dist
• Scala: sbt compile

The Convergence client-server protocol is intended to be sent over a WebSocket connection between a Convergence client and the Convergence Server. Each message sent between the client and server is an instance of the ConvergenceMessage protocol buffer message. The rough structure of the message is as follows:

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 directory.

The Convergence Protocol is licensed under the Apache 2.0 license. Refer to the LICENSE.txt 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.