Presence 2

.gitignore

@@ -34,4 +34,5 @@ coverage
 # Dependency directories
 node_modules
 package-lock.json
+yarn.lock
 jspm_packages

README.md

@@ -19,6 +19,7 @@ tracker](https://github.com/share/sharedb/issues).
 
 - Realtime synchronization of any JSON document
 - Concurrent multi-user collaboration
+- Realtime synchronization of any ephemeral "presence" data
 - Synchronous editing API with asynchronous eventual consistency
 - Realtime query subscriptions
 - Simple integration with any database - [MongoDB](https://github.com/share/sharedb-mongo), [PostgresQL](https://github.com/share/sharedb-postgres) (experimental)
@@ -73,6 +74,22 @@ initial data. Then you can submit editing operations on the document (using
 OT). Finally you can delete the document with a delete operation. By
 default, ShareDB stores all operations forever - nothing is truly deleted.
 
+## User Presence Synchronization
+
+ShareDB supports synchronization of user presence data such as cursor positions and text selections. This feature is opt-in, not enabled by default. To enable this feature, pass a presence implementation as the `presence` option to the ShareDB constructor.
+
+ShareDB includes an implementation of presence called `StatelessPresence`. This provides an implementation of presence that works out of the box, but it has some scalability problems. Each time a client joins a document, this implementation requests current presence information from all other clients, via the server. This approach may be problematic in terms of performance when a large number of users are present on the same document simultaneously. If you don't expect too many simultaneous users per document, `StatelessPresence` should work well. The server does not store any state at all regarding presence (it exists only in clients), hence the name "Stateless Presence".
+
+In `StatelessPresence`, 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) (specifically, by [`transformPresence`, `createPresence`, and `comparePresence`](https://github.com/teamwork/ot-docs#optional-properties)). 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.
+
+To use `StatelessPresence`, pass it into the ShareDB constructor like this:
+
+```js
+var ShareDB = require('sharedb');
+var statelessPresence = require('sharedb/lib/presence/stateless');
+var share = new ShareDB({ presence: statelessPresence })`).
+```
+
 ## Server API
 
 ### Initialization
@@ -91,6 +108,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.presence` _(implementation of presence classes)_
+  Enable user presence synchronization. The value of `options.presence` option is expected to contain implementations of the classes `DocPresence`, `ConnectionPresence`, `AgentPresence`, and `BackendPresence`. Logic related to presence is encapsulated within these classes, so it is possible develop additional third party presence implementations external to ShareDB.
 
 #### Database Adapters
 * `ShareDB.MemoryDB`, backed by a non-persistent database with no queries
@@ -308,6 +327,9 @@ Unique document ID
 `doc.data` _(Object)_
 Document contents. Available after document is fetched or subscribed to.
 
+`doc.presence` _(Object)_
+Each property under `doc.presence` contains presence data shared by a client subscribed to this document. The property name is an empty string for this client's data and connection IDs for other clients' data. The structure of the presence object is defined by the OT type of the document (for example, in [ot-rich-text](https://github.com/Teamwork/ot-rich-text#presence) and [@datavis-tech/json0](https://github.com/datavis-tech/json0#presence)).
+
 `doc.fetch(function(err) {...})`
 Populate the fields on `doc` with a snapshot of the document from the server.
 
@@ -337,6 +359,9 @@ An operation was applied to the data. `source` will be `false` for ops received
 `doc.on('del', function(data, source) {...})`
 The document was deleted. Document contents before deletion are passed in as an argument. `source` will be `false` for ops received from the server and defaults to `true` for ops generated locally.
 
+`doc.on('presence', function(srcList, submitted) {...})`
+Presence data has changed. `srcList` is an Array of `doc.presence` property names for which values have changed. `submitted` is `true`, if the event is the result of new presence data being submitted by the local or remote user, otherwise it is `false` - eg if the presence data was transformed against an operation or was cleared on unsubscribe, disconnect or roll-back.
+
 `doc.on('error', function(err) {...})`
 There was an error fetching the document or applying an operation.
 
@@ -370,6 +395,11 @@ Invokes the given callback function after
 
 Note that `whenNothingPending` does NOT wait for pending `model.query()` calls.
 
+`doc.submitPresence(presenceData[, function(err) {...}])`
+Set local presence data and publish it for other clients.
+`presenceData` structure depends on the document type.
+Presence is synchronized only when subscribed to the document.
+
 ### Class: `ShareDB.Query`
 
 `query.ready` _(Boolean)_
@@ -467,6 +497,9 @@ Additional fields may be added to the error object for debugging context dependi
 * 4022 - Database adapter does not support queries
 * 4023 - Cannot project snapshots of this type
 * 4024 - Invalid version
+* 4025 - Not subscribed to document
+* 4026 - Presence data superseded
+* 4027 - OT Type does not support presence
 
 ### 5000 - Internal error
 

lib/agent.js

@@ -2,6 +2,7 @@ var hat = require('hat');
 var util = require('./util');
 var types = require('./types');
 var logger = require('./logger');
+var ShareDBError = require('./error');
 
 /**
  * Agent deserializes the wire protocol messages received from the stream and
@@ -26,6 +27,8 @@ function Agent(backend, stream) {
   // Map from queryId -> emitter
   this.subscribedQueries = {};
 
+  this._agentPresence = new backend.presence.AgentPresence(this);
+
   // We need to track this manually to make sure we don't reply to messages
   // after the stream was closed.
   this.closed = false;
@@ -106,6 +109,10 @@ Agent.prototype._subscribeToStream = function(collection, id, stream) {
       logger.error('Doc subscription stream error', collection, id, data.error);
       return;
     }
+    if (agent._agentPresence.isPresenceMessage(data)) {
+      agent._agentPresence.processPresenceData(data);
+      return;
+    }
     if (agent._isOwnOp(collection, data)) return;
     agent._sendOp(collection, id, data);
   });
@@ -117,6 +124,7 @@ Agent.prototype._subscribeToStream = function(collection, id, stream) {
     if (util.hasKeys(streams)) return;
     delete agent.subscribedDocs[collection];
   });
+  this._agentPresence.subscribeToStream(collection, id, stream);
 };
 
 Agent.prototype._subscribeToQuery = function(emitter, queryId, collection, query) {
@@ -288,6 +296,8 @@ Agent.prototype._checkRequest = function(request) {
     // Bulk request
     if (request.c != null && typeof request.c !== 'string') return 'Invalid collection';
     if (typeof request.b !== 'object') return 'Invalid bulk subscribe data';
+  } else {
+    return this._agentPresence.checkRequest(request);
   }
 };
 
@@ -325,6 +335,9 @@ Agent.prototype._handleMessage = function(request, callback) {
       case 'nt':
         return this._fetchSnapshotByTimestamp(request.c, request.d, request.ts, callback);
       default:
+        if (this._agentPresence.isPresenceMessage(request)) {
+          return this._agentPresence.handlePresenceMessage(request, callback);
+        }
         callback({code: 4000, message: 'Invalid or unknown message'});
     }
   } catch (err) {

lib/backend.js

@@ -12,6 +12,7 @@ var Snapshot = require('./snapshot');
 var StreamSocket = require('./stream-socket');
 var SubmitRequest = require('./submit-request');
 var types = require('./types');
+var dummyPresence = require('./presence/dummy');
 
 var warnDeprecatedDoc = true;
 var warnDeprecatedAfterSubmit = true;
@@ -48,6 +49,10 @@ function Backend(options) {
   if (!options.disableSpaceDelimitedActions) {
     this._shimAfterSubmit();
   }
+
+  this.presence = options.presence || dummyPresence;
+
+  this._backendPresence = new this.presence.BackendPresence(this);
 }
 module.exports = Backend;
 emitter.mixin(Backend);
@@ -155,6 +160,13 @@ 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;
+
+  // Expose the DocPresence passed in through the constructor
+  // to the Doc class, which has access to the connection.
+  connection.DocPresence = this.presence.DocPresence;
+
+  connection._connectionPresence = new this.presence.ConnectionPresence(connection);
+
   return connection;
 };
 
@@ -720,6 +732,10 @@ Backend.prototype._buildSnapshotFromOps = function (id, startingSnapshot, ops, c
   callback(error, snapshot);
 };
 
+Backend.prototype.sendPresence = function(presence, callback) {
+  this._backendPresence.sendPresence(presence, callback);
+};
+
 function pluckIds(snapshots) {
   var ids = [];
   for (var i = 0; i < snapshots.length; i++) {

lib/client/connection.js

@@ -255,6 +255,9 @@ Connection.prototype.handleMessage = function(message) {
       return;
 
     default:
+      if (this._connectionPresence.isPresenceMessage(message)) {
+        return this._connectionPresence.handlePresenceMessage(err, message);
+      }
       logger.warn('Ignoring unrecognized message', message);
   }
 };
@@ -424,6 +427,9 @@ Connection.prototype.sendOp = function(doc, op) {
   this.send(message);
 };
 
+Connection.prototype.sendPresence = function(doc, data, requestReply) {
+  this._connectionPresence.sendPresence(doc, data, requestReply);
+};
 
 /**
  * Sends a message down the socket