Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Mutation and Conflict Resolution



Introduction

introduction page anchor

Sync supports the standard HTTP If-Match(link takes you to an external page) and ETag(link takes you to an external page) headers for the purpose of conditional mutation. Every response containing a Sync object will return an ETag value, which currently corresponds 1:1 with revision in the object body. If you specify this value in some subsequent updates operation, that operation will only succeed if there has been no interleaving update.

In this guide we'll show you how to leverage ETags in REST API requests and also how these are exposed in our JavaScript SDK


REST API conflict walkthrough

rest-api-conflict-walkthrough page anchor

Let's walk through an example of updating a document through the REST API to understand how optimistic concurrency works.


_10
curl -X POST https://sync.twilio.com/v1/Sync/Services/ISxx/Documents \
_10
-d 'UniqueName=MyFirstDocument' \
_10
-d 'Data={firstName:Alice,lastName:Xavier}' \
_10
-u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

This will create a document with the following structure:


_15
{
_15
"account_sid": "ACxx",
_15
"service_sid": "ISxx",
_15
"sid": "ETxx",
_15
"unique_name": "MyFirstDocument",
_15
"revision": "0",
_15
"date_created": "2015-11-24T22:18:57Z",
_15
"date_updated": "2015-11-24T22:18:57Z",
_15
"created_by": "system",
_15
"url": "https://sync.twilio.com/v1/Services/ISxx/Documents/ETxx",
_15
"data": {
_15
"firstName":"Alice",
_15
"lastName":"Xavier"
_15
}
_15
}

Now let's update that object through the REST API.


_10
curl -X POST https://sync.twilio.com/v1/Sync/Services/ISxx/Documents/MyFirstDocument \
_10
-d 'Data={firstName:Bob,lastName:Xavier}' \
_10
-u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

We'll get a response back, and now the revision will be 1.

Similar to our counter example above, let's say there is an argument over whether the first name is Alice, Bob or someone else. Now we have two POST requests hitting Sync in quick succession:

POST A


_10
curl -X POST https://sync.twilio.com/v1/Sync/Services/ISxx/Documents/MyFirstDocument \
_10
-d 'Data={firstName:Charlie,lastName:Xavier}' \
_10
-u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

POST B


_10
curl -X POST https://sync.twilio.com/v1/Sync/Services/ISxx/Documents/MyFirstDocument \
_10
-d 'Data={firstName:Dave,lastName:Xavier}' \
_10
-u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

In the above case, it will be the last write wins. Post B will simply overwrite post A. Just like in the mutate example above, what if we want to make sure we are up to date before we make any changes?

The answer is to use the If-Match header mentioned above. First, we make sure we GET the document revision. Then we pass this revision as a value in the If-Match header when we post our update. This ensures that if we are not the most up to date revision, our update will be rejected.

POST B


_10
curl -X POST https://sync.twilio.com/v1/Sync/Services/ISxx/Documents/MyFirstDocument \
_10
--header 'If-Match':'1a' \
_10
-d 'Data={firstName:Dave,lastName:Xavier}' \
_10
-u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

Note the addition of the header If-Match. Now, this operation will fail unless the revision of our document is 1a. The error generated will be:

The revision of the Document does not match the expected revision


JavaScript SDK conflict walkthrough

javascript-sdk-conflict-walkthrough page anchor

Let's take the example of a counter, and we want each separate browser tab to increment the value. The JSON representation is:


_10
{ count:0 }

We will store this in a document called "counter":


_10
syncClient.document("counter").then(function(doc) {
_10
doc.set({count:1});
_10
});

The above works fine for the first count in the first browser tab, but all that will do is repeatedly set the count to 1 when executed. So let's extend the functionality:


_10
syncClient.document("counter").then(function(doc) {
_10
if(!doc.value.count) {
_10
doc.set({count:1});
_10
}
_10
else {
_10
var newCount = doc.value.count + 1;
_10
doc.set({count:newCount});
_10
}
_10
});

Now, each time the browser is loaded, the document is opened and the count is increased by 1. If we add a subscription to the document, then browsers which are already open will receive an update to the count themselves:


_13
syncClient.document("counter").then(function(doc) {
_13
if(!doc.value.count) {
_13
doc.set({count:1});
_13
}
_13
else {
_13
var newCount = doc.value.count + 1;
_13
doc.set({count:newCount});
_13
}
_13
_13
doc.on("updated", function(item) {
_13
console.log("count", item.count);
_13
});
_13
});

So now we have a system where we're counting each browser tab being opened. But now it gets interesting. What if two browser tabs open at the same time, so both of them increment the count at the same time. So let's say there are already 10 open.

Browser tab A opens at the same time as B. So this happens:


_10
A: 10 + 1 = 11 //I'm the 11th Tab!
_10
B: 10 + 1 = 11 //No... I'm the 11th Tab!

Using doc.set will mean that both browser tabs will attempt to write 11, and both will succeed. So now our count is wrong. So how do we fix this? Let's mutate, people.


_18
syncClient.document("counter").then(function (doc) {
_18
doc.mutate(function (remoteValue) {
_18
console.log("mutate", remoteValue.count);
_18
if (!remoteValue.count) {
_18
remoteValue.count = 1;
_18
} else {
_18
remoteValue.count += 1;
_18
}
_18
return remoteValue;
_18
}).then(function () {
_18
console.log("mutate_done", doc.value.count);
_18
});
_18
_18
doc.on("updated", function (item) {
_18
console.log("count", item.count);
_18
});
_18
_18
});

What's occurring? Using mutate allows us to specify that we want to modify the value only when the local copy of the value is synchronized. So if we use mutate, let's look at our problem again:


_10
A: 10 + 1 = 11 //I'm the 11th Tab!
_10
B: 10 + 1 = 11 //No... I'm the 11th Tab!

With mutate, B will try to execute, but the server will actually return an error, putting B into conflict. By using the mutate function instead of set, we instruct our client to keep trying the function passed to mutate until it can operate on an in-sync value. This means that even if browser tab C came into the picture at the same time, all three tabs would eventually increment the value correctly.


  • Revisions are strings, not integers. They are not designed to be programmatically comparable to numbers.
  • When posting updates via the REST API, a concurrency control check only occurs if the If-Match header is present. Posts without an If-Match header will overwrite any existing data.

In the client SDKs (JavaScript, iOS and Android) the above revision management is handled for you and managed through the SDK methods. In the REST API, using If-Match headers enables you to ensure you are operating on the most up to date versions of your data.


Racing Guarded & Unguarded Requests

racing-guarded--unguarded-requests page anchor

Unconditional updates (no If-Match header) will sometimes succeed even when a conditional update (with If-Match) ultimately squashes it. If you need to detect the winner of such a race, you will need to examine the final data. We recommend not racing conditional updates with unconditional ones.


Rate this page: