Make the RemoteConnection private under RemoteConnections and document the setup

You’d never instantiate it on its own.

2 files changed, 50 insertions, 33 deletions

diff --git a/lib/action_cable/remote_connection.rb b/lib/action_cable/remote_connection.rb
deleted file mode 100644
index e2e2786dc1..0000000000
--- a/lib/action_cable/remote_connection.rb
+++ /dev/null
@@ -1,33 +0,0 @@
-module ActionCable
-  class RemoteConnection
-    class InvalidIdentifiersError < StandardError; end
-
-    include Connection::Identification, Connection::InternalChannel
-
-    def initialize(server, ids)
-      @server = server
-      set_identifier_instance_vars(ids)
-    end
-
-    def disconnect
-      server.broadcast internal_redis_channel, type: 'disconnect'
-    end
-
-    def identifiers
-      server.connection_identifiers
-    end
-
-    private
-      attr_reader :server
-
-      def set_identifier_instance_vars(ids)
-        raise InvalidIdentifiersError unless valid_identifiers?(ids)
-        ids.each { |k,v| instance_variable_set("@#{k}", v) }
-      end
-
-      def valid_identifiers?(ids)
-        keys = ids.keys
-        identifiers.all? { |id| keys.include?(id) }
-      end
-  end
-end
diff --git a/lib/action_cable/remote_connections.rb b/lib/action_cable/remote_connections.rb
index f9d7c49a27..df390073de 100644
--- a/lib/action_cable/remote_connections.rb
+++ b/lib/action_cable/remote_connections.rb
@@ -1,4 +1,18 @@
 module ActionCable
+  # If you need to disconnect a given connection, you go through the RemoteConnections. You find the connections you're looking for by
+  # searching the identifier declared on the connection. Example:
+  #
+  #   module ApplicationCable
+  #     class Connection < ActionCable::Connection::Base
+  #       identified_by :current_user
+  #       ....
+  #     end
+  #   end
+  #
+  #   ActionCable.server.remote_connections.where(current_user: User.find(1)).disconnect
+  #
+  # That will disconnect all the connections established for User.find(1) across all servers running on all machines (because it uses
+  # the internal channel that all these servers are subscribed to).
   class RemoteConnections
     attr_reader :server
 
@@ -9,5 +23,41 @@ module ActionCable
     def where(identifier)
       RemoteConnection.new(server, identifier)
     end
+
+    private
+      # Represents a single remote connection found via ActionCable.server.remote_connections.where(*). 
+      # Exists for the solely for the purpose of calling #disconnect on that connection.
+      class RemoteConnection
+        class InvalidIdentifiersError < StandardError; end
+
+        include Connection::Identification, Connection::InternalChannel
+
+        def initialize(server, ids)
+          @server = server
+          set_identifier_instance_vars(ids)
+        end
+
+        # Uses the internal channel to disconnect the connection.
+        def disconnect
+          server.broadcast internal_redis_channel, type: 'disconnect'
+        end
+
+        def identifiers
+          server.connection_identifiers
+        end
+
+        private
+          attr_reader :server
+
+          def set_identifier_instance_vars(ids)
+            raise InvalidIdentifiersError unless valid_identifiers?(ids)
+            ids.each { |k,v| instance_variable_set("@#{k}", v) }
+          end
+
+          def valid_identifiers?(ids)
+            keys = ids.keys
+            identifiers.all? { |id| keys.include?(id) }
+          end
+      end
   end
 end