.:::: .::
.:: .:: .::
.:: .::.: .::: .:: .::
.:: .:: .:: .:: .:: .:: .::
.:: .:: .:: .: .::.:: .::
.:: .:: .:: .: .::.:: .::
.:::: .::: .:: .:: .:: .:::
Orda (or ordu, ordo, or ordon) means the Mongolian mobile tent or place tent. As stated in Civilization WIKI, Orda (or Ordu) was the center of the tribe for the nomadic Mongolians. Orda project is a multi-device data synchronization platform based on MongoDB (which could be other document databases such as CouchBase). Orda is based on CRDT(conflict-free data types), which enables operation-based synchronization.
This project is mainly based on these two papers.
- Hyun-Gul Roh et al. Replicated abstract data types: Building blocks for collaborative applications , JPDC, March, 2011.
- Hyun-Gul Roh et al. Kaleido: Implementing a Novel Data System for Multi-Device Synchronization , IEEE MDM, July, 2017.
- Using Orda SDKs, you can allow multiple users to synchronize any document in a collection of DocumentDB.
- Any field can be added, removed and updated using JSON operations.
- For example, Orda-JSONEditor implemented with Orda-js allows multiple users concurrently to edit any document in a collection of MongoDB as the following picture.
-
You can see the full video of the example usage of Orda JSONEditor At YouTube here.
-
The documents in the MongoDB collection can be used for the analytics or read-only workloads. It is not recommended modifying them directly.
- go 1.18
- docker latest, docker-compose (for building and deploying local orda-server)
- protobuf / grpc / grpc-gateway
- MongoDB latest
- MQTT: EQM
- Redis latest
- Maybe work on lower versions of them
$ git clone https://github.com/orda-io/orda.git
$ cd orda
$ make init # generate builder container
$ make protoc-gen # generate protobuf codes
- You can run orda server with docker-compose.
$ make build-docker-server
$ make docker-up
$ docker ps
- Port mapping in docker-compose
- To make Orda clients connect to Orda server, a
collection
should be prepared in MongoDB. - The
collection
is going to create a real collection of MongoDB. - It can be created by restful API:
curl -X GET http://<SERVER_ADDR>/api/v1/collections/<COLLECTION_NAME>
- The collections can be created and reset by the swagger.
$ curl -s -X PUT http://localhost:19861/api/v1/collections/hello_world
Created collection 'hello_world(1)'
- An Orda client manages the connection with the Orda server and synchronization of Orda datatypes.
- An Orda client participates in a collection of MongoDB, which means that the snapshot of any created datatype is written to the collection of MongoDB.
- The orda client package should be imported as follows.
$ cd YOUR_PORJECT_PACKAGE
$ go get -u github.com/orda-io/orda/client
- To create client, you
clientConf := &orda.ClientConfig{
ServerAddr: "localhost:19061", // Orda Server address.
NotificationAddr: "localhost:11883", // notification server address.
CollectionName: "hello_world", // the collection name of MongoDB which the client participates in.
SyncType: model.SyncType_REALTIME, // syncType that is notified in real-time from notification server.
}
client1 := orda.NewClient(clientConf, "client1") // create a client with alias "client1".
if err := client1.Connect(); err != nil { // connect to Orda server
_ = fmt.Errorf("fail client to connect an Orda server: %v", err.Error())
return
}
defer func() {
if err := client1.Close(); err != nil { // close the client
_ = fmt.Errorf("fail to close client: %v", err.Error())
}
}()
- For using datatypes, a client should create or subscribe datatypes.
- A datatype has a key which is used as a document ID; i.e., `_id' of MongoDB document.
- There are three ways to use a datatype. For a type of datatype
XXXX
,XXXX
cam be one of IntCounter, HashMap, List...
// CreateXXXX() is used to create a new datatype.
// If there already exists a datatype for the key, it returns an error via error handler.
Counter := client.CreateCounter("key", orda.NewHandlers(...)
// SubscribeXXXX() is used to subscribe an existing datatype.
// If there exists no datatype for the key, it returns an error via error handler
Counter := client.SubscribeCounter("key", orda.NewHandlers(...)
// SubscribeOrCreateXXXX() is used to subscribe an existing datatype.
// If no datatype exists for the key, a new datatype is created.
// It is recommended to use this method to shorten code lines.
Counter := client.SubscribeOrCreateCounter("key", orda.NewHandlers(...)
// Client should sync with Orda server.
if err := client.Sync(); err !=nil {
panic(err)
}
We always welcome your participation. Please see contributing doc.
If you're also interested in writing academic papers with our orda implementations such as JSON CRDTs, feel free contact
us:
Orda is licensed under Apache 2.0 License that can be found in the LICENSE file.