✨ Add ping/pong

lib/agent.js

@@ -447,6 +447,8 @@ Agent.prototype._handleMessage = function(request, callback) {
         return this._subscribePresence(request.ch, request.seq, callback);
       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'));
     }
@@ -540,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++) {

lib/client/connection.js

@@ -253,6 +253,8 @@ Connection.prototype.handleMessage = function(message) {
       return this._handlePresenceUnsubscribe(err, message);
     case ACTIONS.presenceRequest:
       return this._handlePresenceRequest(err, message);
+    case ACTIONS.pingPong:
+      return this._handlePingPong(err);
 
     default:
       logger.warn('Ignoring unrecognized message', message);
@@ -476,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'
@@ -725,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;
 

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',

lib/message-actions.js

@@ -14,6 +14,7 @@ exports.ACTIONS = {
   op: 'op',
   snapshotFetch: 'nf',
   snapshotFetchByTimestamp: 'nt',
+  pingPong: 'pp',
   presence: 'p',
   presenceSubscribe: 'ps',
   presenceUnsubscribe: 'pu',

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;