From 1c74cbbc4ef21d5531d2486a2a57829a7e3546d6 Mon Sep 17 00:00:00 2001
From: Brian Gough <brian.gough@overleaf.com>
Date: Wed, 24 Jul 2019 15:41:25 +0100
Subject: [PATCH] add comments

---
 services/real-time/app/coffee/ChannelManager.coffee | 6 ++++++
 services/real-time/app/coffee/RoomManager.coffee    | 3 ++-
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/services/real-time/app/coffee/ChannelManager.coffee b/services/real-time/app/coffee/ChannelManager.coffee
index 1749ab2d58..3ea5c2e71e 100644
--- a/services/real-time/app/coffee/ChannelManager.coffee
+++ b/services/real-time/app/coffee/ChannelManager.coffee
@@ -17,6 +17,9 @@ module.exports = ChannelManager =
     subscribe: (rclient, baseChannel, id) ->
         clientChannelMap = @getClientMapEntry(rclient)
         channel = "#{baseChannel}:#{id}"
+        # we track pending subscribes because we want to be sure that the
+        # channel is active before letting the client join the doc or project,
+        # so that events are not lost.
         if clientChannelMap.has(channel)
             logger.warn {channel}, "subscribe already actioned"
             # return the existing subscribe promise, so we can wait for it to resolve
@@ -33,6 +36,9 @@ module.exports = ChannelManager =
     unsubscribe: (rclient, baseChannel, id) ->
         clientChannelMap = @getClientMapEntry(rclient)
         channel = "#{baseChannel}:#{id}"
+        # we don't need to track pending unsubscribes, because we there is no
+        # harm if events continue to arrive on the channel while the unsubscribe
+        # command in pending.
         if !clientChannelMap.has(channel)
             logger.error {channel}, "not subscribed - shouldn't happen"
         else
diff --git a/services/real-time/app/coffee/RoomManager.coffee b/services/real-time/app/coffee/RoomManager.coffee
index 152a290020..9f42083198 100644
--- a/services/real-time/app/coffee/RoomManager.coffee
+++ b/services/real-time/app/coffee/RoomManager.coffee
@@ -2,7 +2,7 @@ logger = require 'logger-sharelatex'
 {EventEmitter} = require 'events'
 
 IdMap = new Map() # keep track of whether ids are from projects or docs
-RoomEvents = new EventEmitter()
+RoomEvents = new EventEmitter() # emits {project,doc}-active and {project,doc}-empty events
 
 # Manage socket.io rooms for individual projects and docs
 #
@@ -49,6 +49,7 @@ module.exports = RoomManager =
         if beforeCount == 0
             logger.log {entity, id}, "room is now active"
             RoomEvents.once "#{entity}-subscribed-#{id}", (err) ->
+                # only allow the client to join when all the relevant channels have subscribed
                 logger.log {client: client.id, entity, id, beforeCount}, "client joined room after subscribing channel"
                 client.join id
                 callback(err)