Introduction

Synctos: The Syncmaker. A utility to aid with the process of designing well-structured sync functions for Couchbase Sync Gateway.

With this utility, you define all your JSON document types in a declarative JavaScript object format that eliminates much of the boilerplate normally required for sync functions with comprehensive validation of document contents and permissions. Not only is it invaluable in protecting the integrity of the documents that are stored in a Sync Gateway database, whenever a document fails validation, sync functions generated with synctos return specific, detailed error messages that make it easy for a client app developer to figure out exactly what went wrong. An included test fixture module also provides a simple framework to write unit tests for generated sync functions.

To learn more about Sync Gateway, check out Couchbase's comprehensive developer documentation. And, for a comprehensive introduction to synctos, see the post Validating your Sync Gateway documents with synctos on the official Couchbase blog.

For validation of documents in Apache CouchDB, see the couchster project.

Introduction
Table of Contents
Installation
Usage
Testing

Installation

Synctos is distributed as an npm package, and the minimum version of Node.js that it officially supports is v20. Both of these required components can be acquired at once by installing Node.js.

If your project does not already have an npm package.json file, run npm init to create one. Don't worry too much about the answers to the questions it asks right now; the file it produces can be updated as needed later.

Next, to install synctos locally (i.e. in your project's node_modules directory) and to add it to your project as a development dependency automatically, run npm install synctos --save-dev from the project's root directory.

For more info on npm package management, see the official npm documentation for How to install local packages and Working with package.json.

A note on JavaScript/ECMAScript compatibility:

Sync Gateway uses the otto JavaScript engine to execute sync functions from within its Go codebase. The version of otto, and thus the version of ECMAScript, that are supported varies depending on the version of Sync Gateway:

Sync Gateway 1.x is pinned to commit 5282a5a of otto, which does not support any of the features introduced in ECMAScript 2015 (aka ES6/ES2015). In fact, it does not promise compatibility with ECMAScript 5, offering only that "For now, otto is a hybrid ECMA3/ECMA5 interpreter. Parts of the specification are still works in progress."
Sync Gateway 2.x is pinned to commit a813c59 of otto, which also does not support any of the features introduced in ECMAScript 2015, but it does at least offer full compatibility with ECMAScript 5, aside from a handful of noted RegExp incompatibilities.

It is for compatibility with these specific versions of otto that synctos intentionally generates code that does not make use of many of the conveniences of modern JavaScript (e.g. let, const, for...of loops, arrow functions, spread operators, etc.). For the same reason, it is always best to verify sync functions that are generated by synctos or otherwise within a live instance of Sync Gateway before deploying to production to ensure that your own custom code is supported by the corresponding version of the otto JS interpreter.

As a convenience, otto - and, by extension, Sync Gateway - does support the Underscore.js utility belt library (specifically version 1.4.4), which provides a great many useful functions. As such, it may help to fill in some of the gaps that would otherwise be filled by a newer version of the ECMAScript specification.

Usage

Running

Once synctos is installed, you can run it from your project's directory as follows:

node_modules/.bin/synctos /path/to/my-document-definitions.js /path/to/my-generated-sync-function.js

Or as a custom script in your project's package.json as follows:

"scripts": {
  "build": "synctos /path/to/my-document-definitions.js /path/to/my-generated-sync-function.js"
}

This will take the sync document definitions that are defined in /path/to/my-document-definitions.js and build a new sync function that is output to /path/to/my-generated-sync-function.js. The generated sync function contents can then be inserted into the definition of a bucket/database in a Sync Gateway configuration file as a multi-line string surrounded with backquotes/backticks ( ` ).

Generated sync functions are compatible with Sync Gateway 1.x and 2.x.

NOTE: Due to a known issue in Sync Gateway versions up to and including 1.2.1, when specifying a bucket/database's sync function in a configuration file as a multi-line string, you will have to be sure to escape any literal backslash characters in the sync function body. For example, if your sync function contains a regular expression like new RegExp('\\w+'), you will have to escape the backslashes when inserting the sync function into the configuration file so that it becomes new RegExp('\\\\w+'). The issue has been resolved in Sync Gateway version 1.3.0 and later.

Validating

To validate that your document definitions file is structured correctly and does not contain any obvious semantic violations, execute the built in validation script as follows:

node_modules/.bin/synctos-validate /path/to/my-document-definitions.js

Or as a custom script in your project's package.json as follows:

"scripts": {
  "validate": "synctos-validate /path/to/my-document-definitions.js"
}

If the specified document definitions contain any violations, the utility will exit with a non-zero status code and output a list of the violations to standard error (stderr). Otherwise, if validation was successful, the utility will exit normally and will not output anything.

Be aware that the validation utility cannot verify the behaviour of custom functions (e.g. dynamic constraints, custom actions, custom validation functions) in a document definition. However, the Testing section of the README describes how to write test cases for such custom code.

Specifications

Document definitions must conform to the following specification. See the samples/ directory and Kashoo's official document definitions repository for some examples.

At the top level, the document definitions object contains a property for each document type that is to be supported by the Sync Gateway bucket. For example:

{
  myDocType1: {
    channels: ...,
    typeFilter: ...,
    propertyValidators: ...
  },
  myDocType2: {
    channels: ...,
    typeFilter: ...,
    propertyValidators: ...
  }
}

Document type definitions

Each document type is defined as an object with a number of properties that control authorization, content validation and access control.

Essential document constraints

The following properties include the basics necessary to build a document definition:

typeFilter: (required) A function that is used to identify document

Synctos

Install / Use

README