Introduce enablePresence option. Closes share#128

Author: curran

README.md

@@ -76,6 +76,8 @@ default, ShareDB stores all operations forever - nothing is truly deleted.
 
 ## User presence synchronization
 
+ShareDB supports synchronization of user presence data. This feature is opt-in, not enabled by default. To enable this feature, pass the `enablePresence: true` option to the ShareDB constructor (e.g. `var share = new ShareDB({ enablePresence: true })`).
+
 Presence data represents a user and is automatically synchronized between all clients subscribed to the same document. Its format is defined by the document's [OT Type](https://github.com/ottypes/docs), for example it may contain a user ID and a cursor position in a text document. All clients can modify their own presence data and receive a read-only version of other client's data. Presence data is automatically cleared when a client unsubscribes from the document or disconnects. It is also automatically transformed against applied operations, so that it still makes sense in the context of a modified document, for example a cursor position may be automatically advanced when a user types at the beginning of a text document.
 
 ## Server API
@@ -96,6 +98,8 @@ __Options__
 * `options.pubsub` _(instance of `ShareDB.PubSub`)_
   Notify other ShareDB processes when data changes
   through this pub/sub adapter. Defaults to `ShareDB.MemoryPubSub()`.
+* `options.enablePresence` _(optional boolean)_
+  Enable user presence synchronization.
 
 #### Database Adapters
 * `ShareDB.MemoryDB`, backed by a non-persistent database with no queries

lib/backend.js

@@ -48,6 +48,8 @@ function Backend(options) {
   if (!options.disableSpaceDelimitedActions) {
     this._shimAfterSubmit();
   }
+
+  this.enablePresence = options.enablePresence;
 }
 module.exports = Backend;
 emitter.mixin(Backend);
@@ -155,6 +157,11 @@ Backend.prototype.connect = function(connection, req) {
   // not used internal to ShareDB, but it is handy for server-side only user
   // code that may cache state on the agent and read it in middleware
   connection.agent = agent;
+
+  // Pass through information on whether or not presence is enabled,
+  // so that Doc instances can use it.
+  connection.enablePresence = this.enablePresence;
+
   return connection;
 };
 

lib/client/doc.js

@@ -68,7 +68,7 @@ function Doc(connection, collection, id) {
   this.data = undefined;
 
   // Properties related to presence are grouped within this object.
-  this.presence = {
+  this.presence = connection.enablePresence && {
 
     // The current presence data.
     // Map of src -> presence data
@@ -158,14 +158,18 @@ Doc.prototype.destroy = function(callback) {
           if (callback) return callback(err);
           return doc.emit('error', err);
         }
-        doc.presence.received = {};
-        doc.presence.cachedOps.length = 0;
+        if (doc.presence) {
+          doc.presence.received = {};
+          doc.presence.cachedOps.length = 0;
+        }
         doc.connection._destroyDoc(doc);
         if (callback) callback();
       });
     } else {
-      doc.presence.received = {};
-      doc.presence.cachedOps.length = 0;
+      if (doc.presence) {
+        doc.presence.received = {};
+        doc.presence.cachedOps.length = 0;
+      }
       doc.connection._destroyDoc(doc);
       if (callback) callback();
     }
@@ -246,7 +250,11 @@ Doc.prototype.ingestSnapshot = function(snapshot, callback) {
   if (this.version > snapshot.v) return callback && callback();
 
   this.version = snapshot.v;
-  this.presence.cachedOps.length = 0;
+
+  if (this.presence) {
+    this.presence.cachedOps.length = 0;
+  }
+
   var type = (snapshot.type === undefined) ? types.defaultType : snapshot.type;
   this._setType(type);
   this.data = (this.type && this.type.deserialize) ?
@@ -276,8 +284,7 @@ Doc.prototype.hasPending = function() {
     this.inflightSubscribe.length ||
     this.inflightUnsubscribe.length ||
     this.pendingFetch.length ||
-    this.presence.inflight ||
-    this.presence.pending
+    this.presence && (this.presence.inflight || this.presence.pending)
   );
 };
 
@@ -522,6 +529,8 @@ Doc.prototype.flush = function() {
     this._sendOp();
   }
 
+  if (!this.presence) return;
+
   if (this.subscribed && !this.presence.inflight && this.presence.pending && !this.hasWritePending()) {
     this.presence.inflight = this.presence.pending;
     this.presence.inflightSeq = this.connection.seq;
@@ -923,7 +932,10 @@ Doc.prototype.resume = function() {
 Doc.prototype._opAcknowledged = function(message) {
   if (this.inflightOp.create) {
     this.version = message.v;
-    this.presence.cachedOps.length = 0;
+
+    if (this.presence) {
+      this.presence.cachedOps.length = 0;
+    }
 
   } else if (message.v !== this.version) {
     // We should already be at the same version, because the server should
@@ -995,8 +1007,10 @@ Doc.prototype._hardRollback = function(err) {
 
   // Apply the same technique for presence, cleaning up as we go.
   var pendingPresence = [];
-  if (this.presence.inflight) pendingPresence.push(this.presence.inflight);
-  if (this.presence.pending) pendingPresence.push(this.presence.pending);
+  if (this.presence) {
+    if (this.presence.inflight) pendingPresence.push(this.presence.inflight);
+    if (this.presence.pending) pendingPresence.push(this.presence.pending);
+  }
 
   // Cancel all pending ops and reset if we can't invert
   this._setType(null);
@@ -1005,22 +1019,24 @@ Doc.prototype._hardRollback = function(err) {
   this.pendingOps = [];
 
   // Reset presence-related properties.
-  this.presence.inflight = null;
-  this.presence.inflightSeq = 0;
-  this.presence.pending = null;
-  this.presence.cachedOps.length = 0;
-  this.presence.received = {};
-  this.presence.requestReply = true;
-
-  var srcList = Object.keys(this.presence.current);
-  var changedSrcList = [];
-  for (var i = 0; i < srcList.length; i++) {
-    var src = srcList[i];
-    if (this._setPresence(src, null)) {
-      changedSrcList.push(src);
+  if (this.presence) {
+    this.presence.inflight = null;
+    this.presence.inflightSeq = 0;
+    this.presence.pending = null;
+    this.presence.cachedOps.length = 0;
+    this.presence.received = {};
+    this.presence.requestReply = true;
+
+    var srcList = Object.keys(this.presence.current);
+    var changedSrcList = [];
+    for (var i = 0; i < srcList.length; i++) {
+      var src = srcList[i];
+      if (this._setPresence(src, null)) {
+        changedSrcList.push(src);
+      }
     }
+    this._emitPresence(changedSrcList, false);
   }
-  this._emitPresence(changedSrcList, false);
 
   // Fetch the latest version from the server to get us back into a working state
   var doc = this;
@@ -1247,6 +1263,7 @@ Doc.prototype._processReceivedPresence = function(src, emit) {
 };
 
 Doc.prototype._processAllReceivedPresence = function() {
+  if (!this.presence) return;
   var srcList = Object.keys(this.presence.received);
   var changedSrcList = [];
   for (var i = 0; i < srcList.length; i++) {
@@ -1270,6 +1287,7 @@ Doc.prototype._transformPresence = function(src, op) {
 };
 
 Doc.prototype._transformAllPresence = function(op) {
+  if (!this.presence) return;
   var srcList = Object.keys(this.presence.current);
   var changedSrcList = [];
   for (var i = 0; i < srcList.length; i++) {
@@ -1282,6 +1300,8 @@ Doc.prototype._transformAllPresence = function(op) {
 };
 
 Doc.prototype._pausePresence = function() {
+  if (!this.presence) return;
+
   if (this.presence.inflight) {
     this.presence.pending = this.presence.pending
       ? this.presence.inflight.concat(this.presence.pending)
@@ -1331,6 +1351,7 @@ Doc.prototype._emitPresence = function(srcList, submitted) {
 };
 
 Doc.prototype._cacheOp = function(op) {
+  if (!this.presence) return;
   // Remove the old ops.
   var oldOpTime = Date.now() - this.presence.cachedOpsTimeout;
   var i;

test/client/presence.js

@@ -11,6 +11,15 @@ types.register(presenceType.type);
 types.register(presenceType.type2);
 types.register(presenceType.type3);
 
+describe('client presence', function() {
+  it('does not expose doc.presence if enablePresence is false', function() {
+    var backend = new Backend();
+    var connection = backend.connect();
+    var doc = connection.get('dogs', 'fido');
+    expect(typeof doc.presence).to.equal('undefined');
+  });
+});
+
 [
   'wrapped-presence-no-compare',
   'wrapped-presence-with-compare',
@@ -22,7 +31,7 @@ types.register(presenceType.type3);
 
   describe('client presence (' + typeName + ')', function() {
     beforeEach(function() {
-      this.backend = new Backend();
+      this.backend = new Backend({ enablePresence: true });
       this.connection = this.backend.connect();
       this.connection2 = this.backend.connect();
       this.doc = this.connection.get('dogs', 'fido');