From 410b504e85d248308a81c2def545e401769aaa81 Mon Sep 17 00:00:00 2001
From: David Heinemeier Hansson <david@loudthinking.com>
Date: Tue, 7 Jul 2015 22:53:58 +0200
Subject: Make the RemoteConnection private under RemoteConnections and
 document the setup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

You’d never instantiate it on its own.
---
 lib/action_cable.rb                    |  1 -
 lib/action_cable/remote_connection.rb  | 33 ----------------------
 lib/action_cable/remote_connections.rb | 50 ++++++++++++++++++++++++++++++++++
 3 files changed, 50 insertions(+), 34 deletions(-)
 delete mode 100644 lib/action_cable/remote_connection.rb

diff --git a/lib/action_cable.rb b/lib/action_cable.rb
index 1fd95f76fa..5f1f3bec35 100644
--- a/lib/action_cable.rb
+++ b/lib/action_cable.rb
@@ -23,7 +23,6 @@ module ActionCable
   autoload :Connection, 'action_cable/connection'
   autoload :Channel, 'action_cable/channel'
 
-  autoload :RemoteConnection, 'action_cable/remote_connection'
   autoload :RemoteConnections, 'action_cable/remote_connections'
   autoload :Broadcaster, 'action_cable/broadcaster'
 
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
-- 
cgit v1.2.3