sharedb 3.0.0 → 3.2.0

package/lib/agent.js

@@ -1,8 +1,9 @@
 var hat = require('hat');
+var ShareDBError = require('./error');
+var logger = require('./logger');
+var ACTIONS = require('./message-actions').ACTIONS;
 var types = require('./types');
 var util = require('./util');
-var logger = require('./logger');
-var ShareDBError = require('./error');
 
 var ERROR_CODE = ShareDBError.CODES;
 
@@ -58,7 +59,7 @@ function Agent(backend, stream) {
   this.custom = {};
 
   // Send the legacy message to initialize old clients with the random agent Id
-  this.send(this._initMessage('init'));
+  this.send(this._initMessage(ACTIONS.initLegacy));
 }
 module.exports = Agent;
 
@@ -174,7 +175,7 @@ Agent.prototype._subscribeToQuery = function(emitter, queryId, collection, query
 
   var agent = this;
   emitter.onExtra = function(extra) {
-    agent.send({a: 'q', id: queryId, extra: extra});
+    agent.send({a: ACTIONS.queryUpdate, id: queryId, extra: extra});
   };
 
   emitter.onDiff = function(diff) {
@@ -186,7 +187,7 @@ Agent.prototype._subscribeToQuery = function(emitter, queryId, collection, query
     }
     // Consider stripping the collection out of the data we send here
     // if it matches the query's collection.
-    agent.send({a: 'q', id: queryId, diff: diff});
+    agent.send({a: ACTIONS.queryUpdate, id: queryId, diff: diff});
   };
 
   emitter.onError = function(err) {
@@ -250,7 +251,7 @@ Agent.prototype.send = function(message) {
 
 Agent.prototype._sendOp = function(collection, id, op) {
   var message = {
-    a: 'op',
+    a: ACTIONS.op,
     c: collection,
     d: id,
     v: op.v,
@@ -354,22 +355,34 @@ Agent.prototype._open = function() {
 
 // Check a request to see if its valid. Returns an error if there's a problem.
 Agent.prototype._checkRequest = function(request) {
-  if (request.a === 'qf' || request.a === 'qs' || request.a === 'qu') {
+  if (
+    request.a === ACTIONS.queryFetch ||
+    request.a === ACTIONS.querySubscribe ||
+    request.a === ACTIONS.queryUnsubscribe
+  ) {
     // Query messages need an ID property.
     if (typeof request.id !== 'number') return 'Missing query ID';
-  } else if (request.a === 'op' || request.a === 'f' || request.a === 's' || request.a === 'u' || request.a === 'p') {
+  } else if (request.a === ACTIONS.op ||
+      request.a === ACTIONS.fetch ||
+      request.a === ACTIONS.subscribe ||
+      request.a === ACTIONS.unsubscribe ||
+      request.a === ACTIONS.presence) {
     // Doc-based request.
     if (request.c != null && typeof request.c !== 'string') return 'Invalid collection';
     if (request.d != null && typeof request.d !== 'string') return 'Invalid id';
 
-    if (request.a === 'op' || request.a === 'p') {
+    if (request.a === ACTIONS.op || request.a === ACTIONS.presence) {
       if (request.v != null && (typeof request.v !== 'number' || request.v < 0)) return 'Invalid version';
     }
 
-    if (request.a === 'p') {
+    if (request.a === ACTIONS.presence) {
       if (typeof request.id !== 'string') return 'Missing presence ID';
     }
-  } else if (request.a === 'bf' || request.a === 'bs' || request.a === 'bu') {
+  } else if (
+    request.a === ACTIONS.bulkFetch ||
+    request.a === ACTIONS.bulkSubscribe ||
+    request.a === ACTIONS.bulkUnsubscribe
+  ) {
     // Bulk request
     if (request.c != null && typeof request.c !== 'string') return 'Invalid collection';
     if (typeof request.b !== 'object') return 'Invalid bulk subscribe data';
@@ -383,28 +396,28 @@ Agent.prototype._handleMessage = function(request, callback) {
     if (errMessage) return callback(new ShareDBError(ERROR_CODE.ERR_MESSAGE_BADLY_FORMED, errMessage));
 
     switch (request.a) {
-      case 'hs':
+      case ACTIONS.handshake:
         if (request.id) this.src = request.id;
-        return callback(null, this._initMessage('hs'));
-      case 'qf':
+        return callback(null, this._initMessage(ACTIONS.handshake));
+      case ACTIONS.queryFetch:
         return this._queryFetch(request.id, request.c, request.q, getQueryOptions(request), callback);
-      case 'qs':
+      case ACTIONS.querySubscribe:
         return this._querySubscribe(request.id, request.c, request.q, getQueryOptions(request), callback);
-      case 'qu':
+      case ACTIONS.queryUnsubscribe:
         return this._queryUnsubscribe(request.id, callback);
-      case 'bf':
+      case ACTIONS.bulkFetch:
         return this._fetchBulk(request.c, request.b, callback);
-      case 'bs':
+      case ACTIONS.bulkSubscribe:
         return this._subscribeBulk(request.c, request.b, callback);
-      case 'bu':
+      case ACTIONS.bulkUnsubscribe:
         return this._unsubscribeBulk(request.c, request.b, callback);
-      case 'f':
+      case ACTIONS.fetch:
         return this._fetch(request.c, request.d, request.v, callback);
-      case 's':
+      case ACTIONS.subscribe:
         return this._subscribe(request.c, request.d, request.v, callback);
-      case 'u':
+      case ACTIONS.unsubscribe:
         return this._unsubscribe(request.c, request.d, callback);
-      case 'op':
+      case ACTIONS.op:
         // Normalize the properties submitted
         var op = createClientOp(request, this._src());
         if (op.seq >= util.MAX_SAFE_INTEGER) {
@@ -415,11 +428,11 @@ Agent.prototype._handleMessage = function(request, callback) {
         }
         if (!op) return callback(new ShareDBError(ERROR_CODE.ERR_MESSAGE_BADLY_FORMED, 'Invalid op message'));
         return this._submit(request.c, request.d, op, callback);
-      case 'nf':
+      case ACTIONS.snapshotFetch:
         return this._fetchSnapshot(request.c, request.d, request.v, callback);
-      case 'nt':
+      case ACTIONS.snapshotFetchByTimestamp:
         return this._fetchSnapshotByTimestamp(request.c, request.d, request.ts, callback);
-      case 'p':
+      case ACTIONS.presence:
         if (!this.backend.presenceEnabled) return;
         var presence = this._createPresence(request);
         if (presence.t && !util.supportsPresence(types.map[presence.t])) {
@@ -429,11 +442,13 @@ Agent.prototype._handleMessage = function(request, callback) {
           });
         }
         return this._broadcastPresence(presence, callback);
-      case 'ps':
+      case ACTIONS.presenceSubscribe:
         if (!this.backend.presenceEnabled) return;
         return this._subscribePresence(request.ch, request.seq, callback);
-      case 'pu':
+      case ACTIONS.presenceUnsubscribe:
         return this._unsubscribePresence(request.ch, request.seq, callback);
+      case ACTIONS.pingPong:
+        return this._pingPong(callback);
       default:
         callback(new ShareDBError(ERROR_CODE.ERR_MESSAGE_BADLY_FORMED, 'Invalid or unknown message'));
     }
@@ -527,6 +542,14 @@ Agent.prototype._querySubscribe = function(queryId, collection, query, options,
   });
 };
 
+Agent.prototype._pingPong = function(callback) {
+  var error = null;
+  var message = {
+    a: ACTIONS.pingPong
+  };
+  callback(error, message);
+};
+
 function getResultsData(results) {
   var items = [];
   for (var i = 0; i < results.length; i++) {
@@ -761,7 +784,7 @@ Agent.prototype._broadcastPresence = function(presence, callback) {
 
 Agent.prototype._createPresence = function(request) {
   return {
-    a: 'p',
+    a: ACTIONS.presence,
     ch: request.ch,
     src: this._src(),
     id: request.id, // Presence ID, not Doc ID (which is 'd')
@@ -813,7 +836,7 @@ Agent.prototype._requestPresence = function(channel, callback) {
 Agent.prototype._handlePresenceData = function(presence) {
   if (presence.src === this._src()) return;
 
-  if (presence.r) return this.send({a: 'pr', ch: presence.ch});
+  if (presence.r) return this.send({a: ACTIONS.presenceRequest, ch: presence.ch});
 
   var backend = this.backend;
   var context = {
@@ -824,7 +847,7 @@ Agent.prototype._handlePresenceData = function(presence) {
   backend.trigger(backend.MIDDLEWARE_ACTIONS.sendPresence, this, context, function(error) {
     if (error) {
       if (backend.doNotForwardSendPresenceErrorsToClient) backend.errorHandler(error, {agent: agent});
-      else agent.send({a: 'p', ch: presence.ch, id: presence.id, error: getReplyErrorObject(error)});
+      else agent.send({a: ACTIONS.presence, ch: presence.ch, id: presence.id, error: getReplyErrorObject(error)});
       return;
     }
     agent.send(presence);

package/lib/client/connection.js

@@ -6,6 +6,7 @@ var SnapshotVersionRequest = require('./snapshot-request/snapshot-version-reques
 var SnapshotTimestampRequest = require('./snapshot-request/snapshot-timestamp-request');
 var emitter = require('../emitter');
 var ShareDBError = require('../error');
+var ACTIONS = require('../message-actions').ACTIONS;
 var types = require('../types');
 var util = require('../util');
 var logger = require('../logger');
@@ -194,25 +195,25 @@ Connection.prototype.handleMessage = function(message) {
   // Switch on the message action. Most messages are for documents and are
   // handled in the doc class.
   switch (message.a) {
-    case 'init':
+    case ACTIONS.initLegacy:
       // Client initialization packet
       return this._handleLegacyInit(message);
-    case 'hs':
+    case ACTIONS.handshake:
       return this._handleHandshake(err, message);
-    case 'qf':
+    case ACTIONS.queryFetch:
       var query = this.queries[message.id];
       if (query) query._handleFetch(err, message.data, message.extra);
       return;
-    case 'qs':
+    case ACTIONS.querySubscribe:
       var query = this.queries[message.id];
       if (query) query._handleSubscribe(err, message.data, message.extra);
       return;
-    case 'qu':
+    case ACTIONS.queryUnsubscribe:
       // Queries are removed immediately on calls to destroy, so we ignore
       // replies to query unsubscribes. Perhaps there should be a callback for
       // destroy, but this is currently unimplemented
       return;
-    case 'q':
+    case ACTIONS.queryUpdate:
       // Query message. Pass this to the appropriate query object.
       var query = this.queries[message.id];
       if (!query) return;
@@ -221,37 +222,39 @@ Connection.prototype.handleMessage = function(message) {
       if (message.hasOwnProperty('extra')) query._handleExtra(message.extra);
       return;
 
-    case 'bf':
+    case ACTIONS.bulkFetch:
       return this._handleBulkMessage(err, message, '_handleFetch');
-    case 'bs':
-    case 'bu':
+    case ACTIONS.bulkSubscribe:
+    case ACTIONS.bulkUnsubscribe:
       return this._handleBulkMessage(err, message, '_handleSubscribe');
 
-    case 'nf':
-    case 'nt':
+    case ACTIONS.snapshotFetch:
+    case ACTIONS.snapshotFetchByTimestamp:
       return this._handleSnapshotFetch(err, message);
 
-    case 'f':
+    case ACTIONS.fetch:
       var doc = this.getExisting(message.c, message.d);
       if (doc) doc._handleFetch(err, message.data);
       return;
-    case 's':
-    case 'u':
+    case ACTIONS.subscribe:
+    case ACTIONS.unsubscribe:
       var doc = this.getExisting(message.c, message.d);
       if (doc) doc._handleSubscribe(err, message.data);
       return;
-    case 'op':
+    case ACTIONS.op:
       var doc = this.getExisting(message.c, message.d);
       if (doc) doc._handleOp(err, message);
       return;
-    case 'p':
+    case ACTIONS.presence:
       return this._handlePresence(err, message);
-    case 'ps':
+    case ACTIONS.presenceSubscribe:
       return this._handlePresenceSubscribe(err, message);
-    case 'pu':
+    case ACTIONS.presenceUnsubscribe:
       return this._handlePresenceUnsubscribe(err, message);
-    case 'pr':
+    case ACTIONS.presenceRequest:
       return this._handlePresenceRequest(err, message);
+    case ACTIONS.pingPong:
+      return this._handlePingPong(err);
 
     default:
       logger.warn('Ignoring unrecognized message', message);
@@ -416,7 +419,7 @@ Connection.prototype._sendBulk = function(action, collection, values) {
   }
 };
 
-Connection.prototype._sendAction = function(action, doc, version) {
+Connection.prototype._sendActions = function(action, doc, version) {
   // Ensure the doc is registered so that it receives the reply message
   this._addDoc(doc);
   if (this.bulk) {
@@ -434,22 +437,22 @@ Connection.prototype._sendAction = function(action, doc, version) {
 };
 
 Connection.prototype.sendFetch = function(doc) {
-  return this._sendAction('f', doc, doc.version);
+  return this._sendActions(ACTIONS.fetch, doc, doc.version);
 };
 
 Connection.prototype.sendSubscribe = function(doc) {
-  return this._sendAction('s', doc, doc.version);
+  return this._sendActions(ACTIONS.subscribe, doc, doc.version);
 };
 
 Connection.prototype.sendUnsubscribe = function(doc) {
-  return this._sendAction('u', doc);
+  return this._sendActions(ACTIONS.unsubscribe, doc);
 };
 
 Connection.prototype.sendOp = function(doc, op) {
   // Ensure the doc is registered so that it receives the reply message
   this._addDoc(doc);
   var message = {
-    a: 'op',
+    a: ACTIONS.op,
     c: doc.collection,
     d: doc.id,
     v: doc.version,
@@ -475,6 +478,19 @@ Connection.prototype.send = function(message) {
   this.socket.send(JSON.stringify(message));
 };
 
+Connection.prototype.ping = function() {
+  if (!this.canSend) {
+    throw new ShareDBError(
+      ERROR_CODE.ERR_CANNOT_PING_OFFLINE,
+      'Socket must be CONNECTED to ping'
+    );
+  }
+
+  var message = {
+    a: ACTIONS.pingPong
+  };
+  this.send(message);
+};
 
 /**
  * Closes the socket and emits 'closed'
@@ -553,7 +569,7 @@ Connection.prototype._destroyQuery = function(query) {
 // The callback should have the signature function(error, results, extra)
 // where results is a list of Doc objects.
 Connection.prototype.createFetchQuery = function(collection, q, options, callback) {
-  return this._createQuery('qf', collection, q, options, callback);
+  return this._createQuery(ACTIONS.queryFetch, collection, q, options, callback);
 };
 
 // Create a subscribe query. Subscribe queries return with the initial data
@@ -563,7 +579,7 @@ Connection.prototype.createFetchQuery = function(collection, q, options, callbac
 // If present, the callback should have the signature function(error, results, extra)
 // where results is a list of Doc objects.
 Connection.prototype.createSubscribeQuery = function(collection, q, options, callback) {
-  return this._createQuery('qs', collection, q, options, callback);
+  return this._createQuery(ACTIONS.querySubscribe, collection, q, options, callback);
 };
 
 Connection.prototype.hasPending = function() {
@@ -716,7 +732,7 @@ Connection.prototype._handleLegacyInit = function(message) {
 };
 
 Connection.prototype._initializeHandshake = function() {
-  this.send({a: 'hs', id: this.id});
+  this.send({a: ACTIONS.handshake, id: this.id});
 };
 
 Connection.prototype._handleHandshake = function(error, message) {
@@ -724,6 +740,11 @@ Connection.prototype._handleHandshake = function(error, message) {
   this._initialize(message);
 };
 
+Connection.prototype._handlePingPong = function(error) {
+  if (error) return this.emit('error', error);
+  this.emit('pong');
+};
+
 Connection.prototype._initialize = function(message) {
   if (this.state !== 'connecting') return;
 

package/lib/client/presence/local-presence.js

@@ -1,4 +1,5 @@
 var emitter = require('../../emitter');
+var ACTIONS = require('../../message-actions').ACTIONS;
 var util = require('../../util');
 
 module.exports = LocalPresence;
@@ -59,7 +60,7 @@ LocalPresence.prototype._ack = function(error, presenceVersion) {
 
 LocalPresence.prototype._message = function() {
   return {
-    a: 'p',
+    a: ACTIONS.presence,
     ch: this.presence.channel,
     id: this.presenceId,
     p: this.value,

package/lib/client/presence/presence.js

@@ -4,6 +4,7 @@ var RemotePresence = require('./remote-presence');
 var util = require('../../util');
 var async = require('async');
 var hat = require('hat');
+var ACTIONS = require('../../message-actions').ACTIONS;
 
 module.exports = Presence;
 function Presence(connection, channel) {
@@ -70,7 +71,7 @@ Presence.prototype.destroy = function(callback) {
 
 Presence.prototype._sendSubscriptionAction = function(wantSubscribe, callback) {
   this.wantSubscribe = !!wantSubscribe;
-  var action = this.wantSubscribe ? 'ps' : 'pu';
+  var action = this.wantSubscribe ? ACTIONS.presenceSubscribe : ACTIONS.presenceUnsubscribe;
   var seq = this.connection._presenceSeq++;
   this._subscriptionCallbacksBySeq[seq] = callback;
   if (this.connection.canSend) {

package/lib/client/query.js

@@ -1,4 +1,5 @@
 var emitter = require('../emitter');
+var ACTIONS = require('../message-actions').ACTIONS;
 var util = require('../util');
 
 // Queries are live requests to the database for particular sets of fields.
@@ -75,8 +76,8 @@ Query.prototype.send = function() {
 // Destroy the query object. Any subsequent messages for the query will be
 // ignored by the connection.
 Query.prototype.destroy = function(callback) {
-  if (this.connection.canSend && this.action === 'qs') {
-    this.connection.send({a: 'qu', id: this.id});
+  if (this.connection.canSend && this.action === ACTIONS.querySubscribe) {
+    this.connection.send({a: ACTIONS.queryUnsubscribe, id: this.id});
   }
   this.connection._destroyQuery(this);
   // There is a callback for consistency, but we don't actually wait for the

package/lib/client/snapshot-request/snapshot-timestamp-request.js

@@ -1,5 +1,6 @@
 var SnapshotRequest = require('./snapshot-request');
 var util = require('../../util');
+var ACTIONS = require('../../message-actions').ACTIONS;
 
 module.exports = SnapshotTimestampRequest;
 
@@ -17,7 +18,7 @@ SnapshotTimestampRequest.prototype = Object.create(SnapshotRequest.prototype);
 
 SnapshotTimestampRequest.prototype._message = function() {
   return {
-    a: 'nt',
+    a: ACTIONS.snapshotFetchByTimestamp,
     id: this.requestId,
     c: this.collection,
     d: this.id,

package/lib/client/snapshot-request/snapshot-version-request.js

@@ -1,5 +1,6 @@
 var SnapshotRequest = require('./snapshot-request');
 var util = require('../../util');
+var ACTIONS = require('../../message-actions').ACTIONS;
 
 module.exports = SnapshotVersionRequest;
 
@@ -17,7 +18,7 @@ SnapshotVersionRequest.prototype = Object.create(SnapshotRequest.prototype);
 
 SnapshotVersionRequest.prototype._message = function() {
   return {
-    a: 'nf',
+    a: ACTIONS.snapshotFetch,
     id: this.requestId,
     c: this.collection,
     d: this.id,

package/lib/error.js

@@ -16,6 +16,7 @@ ShareDBError.CODES = {
   ERR_APPLY_OP_VERSION_DOES_NOT_MATCH_SNAPSHOT: 'ERR_APPLY_OP_VERSION_DOES_NOT_MATCH_SNAPSHOT',
   ERR_APPLY_SNAPSHOT_NOT_PROVIDED: 'ERR_APPLY_SNAPSHOT_NOT_PROVIDED',
   ERR_CLIENT_ID_BADLY_FORMED: 'ERR_CLIENT_ID_BADLY_FORMED',
+  ERR_CANNOT_PING_OFFLINE: 'ERR_CANNOT_PING_OFFLINE',
   ERR_CONNECTION_SEQ_INTEGER_OVERFLOW: 'ERR_CONNECTION_SEQ_INTEGER_OVERFLOW',
   ERR_CONNECTION_STATE_TRANSITION_INVALID: 'ERR_CONNECTION_STATE_TRANSITION_INVALID',
   ERR_DATABASE_ADAPTER_NOT_FOUND: 'ERR_DATABASE_ADAPTER_NOT_FOUND',

package/lib/index.js

@@ -9,6 +9,7 @@ Backend.logger = require('./logger');
 Backend.MemoryDB = require('./db/memory');
 Backend.MemoryMilestoneDB = require('./milestone-db/memory');
 Backend.MemoryPubSub = require('./pubsub/memory');
+Backend.MESSAGE_ACTIONS = require('./message-actions').ACTIONS;
 Backend.MilestoneDB = require('./milestone-db');
 Backend.ot = require('./ot');
 Backend.projections = require('./projections');

package/lib/message-actions.js

@@ -0,0 +1,22 @@
+exports.ACTIONS = {
+  initLegacy: 'init',
+  handshake: 'hs',
+  queryFetch: 'qf',
+  querySubscribe: 'qs',
+  queryUnsubscribe: 'qu',
+  queryUpdate: 'q',
+  bulkFetch: 'bf',
+  bulkSubscribe: 'bs',
+  bulkUnsubscribe: 'bu',
+  fetch: 'f',
+  subscribe: 's',
+  unsubscribe: 'u',
+  op: 'op',
+  snapshotFetch: 'nf',
+  snapshotFetchByTimestamp: 'nt',
+  pingPong: 'pp',
+  presence: 'p',
+  presenceSubscribe: 'ps',
+  presenceUnsubscribe: 'pu',
+  presenceRequest: 'pr'
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sharedb",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "JSON OT database backend",
   "main": "lib/index.js",
   "dependencies": {
@@ -18,7 +18,7 @@
     "lolex": "^5.1.1",
     "mocha": "^8.2.1",
     "nyc": "^14.1.1",
-    "ot-json0-v2": "ottypes/json0",
+    "ot-json0-v2": "https://github.com/ottypes/json0#90a3ae26364c4fa3b19b6df34dad46707a704421",
     "ot-json1": "^0.3.0",
     "rich-text": "^4.1.0",
     "sharedb-legacy": "npm:sharedb@=1.1.0",

package/test/client/connection.js

@@ -124,6 +124,45 @@ describe('client connection', function() {
     });
   });
 
+  describe('ping/pong', function() {
+    it('pings the backend', function(done) {
+      var connection = this.backend.connect();
+
+      connection.on('pong', function() {
+        done();
+      });
+
+      connection.on('connected', function() {
+        connection.ping();
+      });
+    });
+
+    it('handles errors', function(done) {
+      this.backend.use('receive', function(request, next) {
+        var error = request.data.a === 'pp' && new Error('bad');
+        next(error);
+      });
+
+      var connection = this.backend.connect();
+
+      connection.on('error', function(error) {
+        expect(error.message).to.equal('bad');
+        done();
+      });
+
+      connection.on('connected', function() {
+        connection.ping();
+      });
+    });
+
+    it('throws if pinging offline', function() {
+      var connection = this.backend.connect();
+      expect(function() {
+        connection.ping();
+      }).to.throw('Socket must be CONNECTED to ping');
+    });
+  });
+
   describe('backend.agentsCount', function() {
     it('updates after connect and connection.close()', function(done) {
       var backend = this.backend;