Access Denied, or Access Lost? Some Tips on Sync Gateway

The plan for this blog post started out with wanting to clarify a particular detail about how Couchbase Mobile’s Sync Gateway component handles removing a client’s access to a document. I’m going to write a bit about Sync Gateway channels to provide a foundation. If you’re already familiar with Sync Gateway and channels, you might skim the first part.

Understanding Sync Gateway Channels

Sync Gateway, the “glue” portion of the Couchbase Mobile stack, has the ability to assign documents to something we call channels. Channels act as an organization and security mechanism.

This graphic may help you picture how channels work. It shows conceptually the idea of Sync Gateway feeding documents to channels during a replication.

You control assigning documents to channels through the Sync Gateway sync function. Each blue pipe in the diagram represents a channel. The green arrows illustrate the idea that the sync function can assign any individual document to any number of channels.

This allows you to group related documents, making it easy to organize information flow. For example, you might create a channel for each user of an app. You can change around your data model and documents all you want. Just tag each document with the user id.

Channels are so useful, that we made the default sync function create them automatically. It assigns a document to a set of channels based on the presence of a channels property in the document. Or, to put it another way, if you don’t supply a sync function, Sync Gateway uses the following equivalent:

(Sync functions are written in JavaScript. channel is a function defined by Sync Gateway.)

To use channels, a client simply asks for the ones it wants when setting up a replication. What about security, though? It wouldn’t do to have any client access whatever channel it wanted.

Sync Gateway will only send documents to authorized clients. This happens on a per channel basis. You can authorize a client based on an authenticated user id, or a role the user is assigned to.

This diagram gives a visual idea of how channel assignment (done by Sync Gateway), channel access requests (done by a client while running a replication), and authorization combine to determine what documents a client can pull.

The blue circle represents channels the sync function assigns a document to. The yellow circle represents the channels a client requests. Finally, the red circle represents the channels a user or role has authorization to access. The green section represents the documents the client will receive.

One, no wait, Two Tricky Bits

The description above may all seem very straight forward. There’s quite a bit more to understand about Sync Gateway and how it can be configured. I want to finish out by talking about two cases that tend to trip people up.

Read vs. Write Access

Notice the relationship between a client and Sync Gateway here isn’t symmetric. Sync Gateway takes care of feeding documents out based on channels. Clients don’t. This has the seemingly odd result that a client can push (write) a document that it can’t pull (read)! (We say push and pull to indicate a replication is happening, and the direction of data flow.)

Say we’re using the default sync function, and we authorize pulling based on user id. User Alice creates a document and puts “Bob” in the channels property. Once Alice pushes the document to Sync Gateway, she can no longer pull it. Sync Gateway assigns the new revision to Bob’s channel. Alice can’t pull the document, but Bob can.

Lost Access

Here’s another edge case. What happens if a client loses access to a document? As we just saw, the client might even have caused this.

Couchbase Mobile uses what’s known as multi-version concurrency control to handle all the nuances offline use and sophisticated synchronization produce. Losing access isn’t the same as the document getting deleted. Further, the client may already have an older version.

Couchbase handles this by creating a special revision of the document. It’s a tombstone revision, meaning it has no contents. Unlike a tombstone marking a deleted document, though, this kind marks the document as having been removed. (This shows up in the document meta-data.)

For most purposes, Couchbase Lite will behave as if the document doesn’t exist. It won’t show in queries, for example. There are still ways to retrieve it, though. You can check if a document has been removed by calling its .isGone() method. (Note the tombstone only gets created when a client like Couchbase Lite pulls the tombstone during a replication.)

Wrapping Up

Sync Gateway is a versatile piece of software in its own right. It’s a critical component of Couchbase Mobile, key to solving some of the tough problems that come with a data platform that fully supports offline use.

I hope I’ve given a flavor of one aspect of Sync Gateway (channels), along with a couple of important tips. To get the most out of Sync Gateway, take some time to explore the documentation.

Postscript

Check out more resources on our developer portal and follow us on Twitter @CouchbaseDev.

You can post questions on our forums. And we actively participate on Stack Overflow.

You can follow me personally at @HodGreeley