Using External Javascript Functions

      +

      How to use Javascript functions to customize data sync between cloud-and-edge.

      Introduction

      Sync Gateway supports the use of Javascript functions to customize the sync process. These functions are referenced from within the Sync Gateway Configuration and may be provided either as:

      • An inline Javascript function

      • An external Javascript file

      • An external HTTP/HTTPS endpoint serving a JS function [1].

      Operation

      During database setup, Sync Gateway inspects the database configuration to identify and provision:

      • Any inline JavaScript defined against any of the eligible configuration options

      • Any external file or HTTP/S endpoint specified against any of the eligible configuration options that resolves to a Javascript function.

      Eligible Options

      Inline or external Javascript functions can be provided for any or all of the following configurable options:

      • Sync Function

      • Import Filter

      • Custom Conflict Resolver

      • Webhook Filter

      Configuration

      Sync gateway 3.x configuration of Javascript functions is done using the Admin REST API; specifically the Access Control and /{db}/_config/import_filter endpoints.

      Prior to this, configuration was done within the database configuration file — see: Example 1

      • Inline Javascript functions provided within the database configuration must be enclosed by a backtick pair (``).

      • To use an external Javascript function for any of the eligible options, you need to specify the absolute path to the Javascript. The format and content of the external Javascript is the same as that provided inline.

        You must register a CA certificate for the appropriate server if external Javascript functions are hosted on HTTPS endpoints.
        For testing purposes you may use the unsupported configuration option unsupported.remote_config_tls_skip_verify. Setting this true will side-step essential security checks. Do not use in Production deployments.
      Example 1. Configuring a Javascript Sync Function

      This example shows the different ways you might provide a Javascript Sync Function. Although the example uses the Sync Function, the same approach applies wherever a Javascript function is valid (including with Import Filter, Webhook and Custom Conflict Resolver).

      curl -X PUT 'http://localhost:4985/db1/_config' \
      --header 'Accept: application/json' \
      --header 'Content-Type: application/json' \
      --data-raw '{
               "sync": "/opt/couchbase-sync-gateway/sync.js" (1)
            },
          }
      }'
      
      
        curl -X PUT 'http://localhost:4985/db2/_config' \
      --header 'Accept: application/json' \
      --header 'Content-Type: application/json' \
      --data-raw '{
               "sync": "https://localhost/sync/func2" (2)
            }
         }
      }
      
      
      curl -X PUT 'http://localhost:4985/db3/_config' \
      --header 'Accept: application/json' \
      --header 'Content-Type: application/json' \
      --data-raw '{
               "sync": `function(doc,oldDoc, meta){ if (doc.published) { channel("public");} }`
            } (3)
         }
      }
      1 Here we specify an external file sync.js as containing the external function to be provisioned
      2 Here we specify a HTTPS endpoint as resolving to a Javascript function to be provisioned
      3 Here we specify inline Javascript (surrounded by a pair of backticks (``) as the function to be provisioned