Add support for ssl configuration to addListener (#2243)

CHANGELOG.md

@@ -31,6 +31,7 @@ This release contains all changes from v2.22.0-beta.1 to v2.22.0-beta.2.
 * Updated React Native Android Builds to use Android Build Tools 3.2.1. ([#2103](https://github.com/realm/realm-js/issues/2103))
 * Improved performance and memory usage of `Realm.Sync.Adapter`. ([realm/realm-js-private#501](https://github.com/realm/realm-js-private/pull/501))
 * When an invalid/corrupt Realm file is opened, the error message will now contain the file name. ([realm/realm-core#3203](https://github.com/realm/realm-core/pull/3203))
+* New global notifier API introduced though `Realm.Sync.addListener(config, event, callback)`. This also adds support for configuring the SSL connection. The old API `Realm.Sync.AddListener(serverUrl, adminUser, filterRegex, event, event, callback)` is deprecated. ([#2243](https://github.com/realm/realm-js/pull/2243))  
 
 ### Fixed
 * `Realm.Sync.User.createConfiguration()` created an extra `:` if no port was defined.  ([#1980](https://github.com/realm/realm-js/issues/1980), since v2.8.0)

docs/sync.js

@@ -87,6 +87,15 @@
  * certificate has the highest depth. The certificate of highest depth will be presented first.
  */
 
+/**
+ * This describes the different options used when adding a Global Notifier listener.
+ * @typedef {Object} Realm.Sync~RealmListenerConfiguration
+ * @property {string} serverUrl - The sync server to listen to.
+ * @property {SyncUser} adminUser - an admin user obtained by calling {@linkcode Realm.Sync.User.login|User.login} with admin credentials.
+ * @property {string} filterRegex - A regular expression used to determine which changed Realms should trigger events. Use `.*` to match all Realms.
+ * @property {Realm.Sync.SSLConfiguration} sslConfiguration - SSL configuration used by the Realms being observed.
+ */
+
 /**
  * When opening a Realm created with Realm Mobile Platform v1.x, it is automatically
  * migrated to the v2.x format. In case this migration
@@ -125,9 +134,38 @@ class Sync {
      *    passed as an argument.
      *
      * Only available in the Enterprise Edition.
+     * @deprecated Use `addListener(config, eventName, changeCallback)` instead`.
      */
     static addListener(serverUrl, adminUser, filterRegex, name, changeCallback) {}
 
+    /**
+     * Add a sync listener to listen to changes across multiple Realms.
+     *
+     * @param {Realm.Sync.RealmListenerConfiguration} config - The configuration object for Realms being observed.
+     * @param {string} eventName - The name of the event to observe.
+     * @param {function(changeEvent)} changeCallback - The callback to invoke with the events.
+     *
+     * Registers the `changeCallback` to be called each time the given event occurs on the specified server.
+     * Only events on Realms with a _virtual path_ that matches the filter regex are emitted.
+     *
+     * Currently supported events:
+     *
+     *  * `'available'`: Emitted whenever there is a new Realm which has a virtual
+     *    path matching the filter regex, either due to the Realm being newly created
+     *    or the listener being added. The virtual path (i.e. the portion of the
+     *    URL after the protocol and hostname) is passed as an argument.
+     *  * `'change'`: Emitted whenever the data within a Realm matching the filter
+     *    regex has changed. A [ChangeEvent]{@link Realm.Sync.ChangeEvent} argument
+     *    is passed containing information about which Realm changed and what
+     *    objects within the Realm changed.
+     *  * `'delete'`: Emitted whenever a Realm matching the filter regex has been
+     *    deleted from the server. The virtual path of the Realm being deleted is
+     *    passed as an argument.
+     *
+     * Only available in the Enterprise Edition.
+     */
+    static addListener(config, eventName, changeCallback) {}
+
     /**
      * Add a sync listener to listen to changes across multiple Realms.
      *

lib/index.d.ts

@@ -544,8 +544,25 @@ declare namespace Realm.Sync {
         readonly realm: Realm;
     }
 
-    function addListener(serverURL: string, adminUser: Realm.Sync.User, regex: string, name: string, changeCallback: (changeEvent: ChangeEvent) => void): void;
-    function addListener(serverURL: string, adminUser: Realm.Sync.User, regex: string, name: string, changeCallback: (changeEvent: ChangeEvent) => Promise<void>): void;
+    type RealmListenerEventName = 'available' | 'change' | 'delete';
+
+    interface RealmListenerConfiguration {
+        serverUrl: string;
+        adminUser: User;
+        filterRegex: string;
+        sslConfiguration?: SSLConfiguration;
+    }
+
+    /**
+     * @deprecated, to be removed in future versions
+     */
+    function addListener(serverURL: string, adminUser: Realm.Sync.User, regex: string, name: RealmListenerEventName, changeCallback: (changeEvent: ChangeEvent) => void): void;
+    /**
+     * @deprecated, to be removed in future versions
+     */
+    function addListener(serverURL: string, adminUser: Realm.Sync.User, regex: string, name: RealmListenerEventName, changeCallback: (changeEvent: ChangeEvent) => Promise<void>): void;
+    function addListener(config: RealmListenerConfiguration, eventName: RealmListenerEventName, changeCallback: (changeEvent: ChangeEvent) => void): void;
+    function addListener(config: RealmListenerConfiguration, eventName: RealmListenerEventName, changeCallback: (changeEvent: ChangeEvent) => Promise<void>): void;
     function removeAllListeners(): Promise<void>;
     function removeListener(regex: string, name: string, changeCallback: (changeEvent: ChangeEvent) => void): Promise<void>;
     function setLogLevel(logLevel: 'all' | 'trace' | 'debug' | 'detail' | 'info' | 'warn' | 'error' | 'fatal' | 'off'): void;

lib/notifier.js

@@ -143,8 +143,8 @@ class OutOfProcListener {
 }
 
 class Listener {
-    constructor(Sync, server, user) {
-        this.notifier = Sync._createNotifier(server, user, (event, a1, a2) => this[event](a1, a2));
+    constructor(Sync, config) {
+        this.notifier = Sync._createNotifier(config.serverUrl, config.adminUser, (event, a1, a2) => this[event](a1, a2), config.sslConfiguration);
         this.initPromises = [];
         this.callbacks = [];
     }
@@ -256,10 +256,28 @@ class Listener {
 
 let listener;
 function addListener(server, user, regex, event, callback) {
+    // Assume the new API is used, but we cannot change the method signature without it being a breaking change.
+    let _config = server;
+    let _event = user;
+    let _callback = regex;
+
+    // If the old API is used, convert all arguments to the new API
+    // If `event` is a Worker, only 4 arguments are provided
+    if (arguments.length === 4 || arguments.length === 5) {
+        _config = {
+            serverUrl: server,
+            adminUser:  user,
+            filterRegex: regex
+            // SSL Configuration not supported in the old API
+        };
+        _event = event;
+        _callback = callback;
+    }
+
     if (!listener) {
-        listener = new Listener(this, server, user);
+        listener = new Listener(this, _config);
     }
-    return listener.add(regex, event, callback);
+    return listener.add(_config.filterRegex, _event, _callback);
 }
 
 function removeListener(regex, event, callback) {
@@ -298,4 +316,4 @@ module.exports = function(Realm) {
     Realm.Sync.addListener = addListener.bind(Realm.Sync);
     Realm.Sync.removeListener = removeListener;
     Realm.Sync.removeAllListeners = removeAllListeners;
-}
+};