Sync

Channels/Data Routing

In the lesson on Access Control we discussed how the Couchbase Sync Gateway supports Authorization and Access Control functions. In this lesson we discuss how it can be used for Data Synchronization and Routing.

A Sync Gateway configuration file determines the runtime behavior of Sync Gateway, including server configuration and the database or set of databases with which a Sync Gateway instance can interact.

  • Sync Gateway uses channels to make it easy to share a database between a large number of users and control access to the database. Conceptually, a channel could be viewed as a tag. Every document in the database belongs to a set of channels, and a user is granted appropriate access a set of channels. A channel is used to

  • Partition the data set

  • Authorize users to access documents.

  • Minimize the amount of data synced down to devices.

In the "Installation" guide, we walked you through the steps to launch Sync Gateway with a specific config file. Open the sync-gateway-config-travelsample.json file located at https://github.com/couchbaselabs/mobile-travel-sample/blob/master/sync-gateway-config-travelsample.json. It includes the sync function which is a JavaScript function whose source code is stored in the Sync Gateway’s database configuration file.

/* Routing */
// Add doc to the user's channel.
channel("channel." + username);

XAttrs

Before you begin this lesson, confirm that you have the Sync Gateway up and running by following the instructions in the "Installation" section.

Starting with Sync Gateway 1.5 and Couchbase Server 5.0, mobile and server/web applications now have the ability to read and write to the same bucket. It is an opt-in feature can be enabled in the Sync Gateway configuration file. convergence

Prior to 1.5, sync metadata used by the Sync Gateway for replication with mobile clients was included within the documents as part of the \_sync property. In 1.5, the sync metadata is moved into the Extended Attributes or XAttrs associated with the document.

This can be enabled through a configuration setting in the sync gateway config file Open the sync-gateway-config-travelsample.json file located at https://github.com/couchbaselabs/mobile-travel-sample/blob/master/sync-gateway-config-travelsample.json

"import_docs": "continuous",
"enable_shared_bucket_access":true

You can specify the Couchbase Server documents that need to be imported and processed by the Sync Gateway. In our demo, we will only be synchornizing the "user" document. So every other document type is ignored.

"import_filter": `
function(doc) {
  /* Just ignore all the static travel-sample files */
  if (doc._deleted == true ) {
    return true;
   }
  if (doc.type == "landmark" || doc.type == "hotel" || doc.type == "airport" || doc.type =="airline" || doc.type == "route") {
    return false;
  }

  return true;
} `

Replication

Replication is the process by which clients running Couchbase Lite synchronize database changes with the remote (server) database.

  • Pull Replication is the process by which clients running Couchbase Lite download database changes from the remote (server) source database to the local target database

  • Push Replication is the process by which clients running Couchbase Lite upload database changes from the local source database to the remote (server) target database

Couchbase Mobile 2.0 introduces a brand new replication protocol which is implemented as a messaging protocol layered over WebSocket.

replication 2 0

The replication process can be “continuous” or “one shot"`. - In "`Continuous” replication mode, the changes are continually synchronized between the client and Sync Gateway.

  • In “One shot” mode, the changes are synchronized once and the connection between the client and server disconnects. When any future changes need to be pushed up or pulled down, the client must start a new replication.

Open the fileLoginModel.cs. We will review the method StartReplication(string username, string password, Database db)

private Replicator StartReplication(string username, string password, Database db)
  ...
}

First, Do some checks to confirm the validity of the user credentials

if (String.IsNullOrWhiteSpace(username) || String.IsNullOrWhiteSpace(password)){
  throw new InvalidOperationException("User credentials not provided");
}

Create the URL of the Sync Gateway

private static readonly Uri SyncUrl = new Uri("ws://localhost:4984");
var dbUrl = new Uri(SyncUrl, DbName);

The ReplicatorConfiguration is initialized with the local database and URL of the target DB on Sync Gateway. The ReplicatorType in the Replicator Config specifies the type of replication. In the code snippet in the Travel app, it is PushAndPull indicating that both push and pull replication is enabled. The Continuous mode is set to true in the Travel app.

var config = new ReplicatorConfiguration(db, new URLEndpoint(dbUrl)) {
  ReplicatorType = ReplicatorType.PushAndPull,
  Continuous = true,
  ...
};

The Replicator is configured with relevant authentication credentials. In the Travel app, the list of users that are permitted access is configured in the Sync Gateway configuration file as discussed in the Access Control section

var config = new ReplicatorConfiguration(db, dbUrl) {
    ...
    Authenticator = new BasicAuthenticator(username, password),
    ...
};

The Replicator is configured to only pull from current user’s channels. The list of channels that the user has access to is defined in the Sync Gateway configuration file as discussed in the Channels/ Data Routing section

var config = new ReplicatorConfiguration(db, dbUrl) {
    ...
    Channels = new[] {$"channel.{username}"}
};

The Replicator is initialized with the specified configuration

var repl = new Replicator(config);

A change listener callback block is registered to listen for replication changes. Every time, there is a push or pull change, the callback is invoked.

repl.AddChangeListener((sender, args) =>
{
  var s = args.Status;
  Debug.WriteLine(
      $"PushPull Replicator: {s.Progress.Completed}/{s.Progress.Total}, error {s.Error?.Message ?? "<none>"}, activity = {s.Activity}");

});

Start the Replication

repl.Start();

Try it out (Push Replication)

  • Log into the Travel Sample Mobile app as “demo” user and password as “password”

  • Tap on "+" button to make a flight reservation

  • Leave the default airport in the “From” field

  • Leave the default airport in the "To" field

  • Enter From and/or Return Dates

  • Tap "lookup" button

  • From list of flights, select the first flight listing

  • Select “Confirm Booking”

  • Access the Travel Sample Web app. The URL would be http://localhost:8080. If you did cloud based install, please replace localhost in the URL with the IP Address of the cloud instance of the web app.

  • Make sure that the "New User" checkbox is unchecked

  • Log into the web app as “demo” user with password as “password”

  • Confirm that you see the flight that you reserved via the mobile app in your list of flights in the web app

The screen recording is for UWP version of the app uwp push replication

Try it out (Pull Replication)

  • Access the Travel Sample Web app. The URL would be http://localhost:8080. If you did cloud based install, please replace localhost in the URL with the IP Address of the cloud instance of the web app.

  • Make sure that the "New User" checkbox is unchecked

  • Log into the web app as “demo” user with password as “password”

  • Make a flight reservation by clicking "booking" button.

  • Enter “From” airport as "JFK" and select the airport from drop down menu.

  • Enter “To” airport as "DTW" and select the airport from drop down menu.

  • Enter From and/or Return Travel Dates

  • Click on "Find Flights" button

  • From list of flights, select the first flight listing

  • Confirm the booking by clicking on the shopping cart icon and click on “Book” button

  • If you are not already logged into the mobile app, Log into the Travel Sample Mobile app as “demo” user and password as “password”

  • Confirm that you see the flight that you reserved via the web app in your list of flights in the mobile app

    The screen recording is for UWP version of the app uwp pull replication