Terminate user connections feature (#190)

* Terminate user connections feature

* Bump to version 3.3.0

* Update readme

Co-authored-by: Pusher CI <[email protected]>

Author: sonologico

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 3.3.0
+
+- [ADDED] terminate_user_connections method
+
 ## 3.2.0 2022-01-25
 
 * [FIXED] An issue where payload size wasn't being calculated properly

README.md

@@ -28,6 +28,7 @@ In order to use this library, you need to have a free account on <http://pusher.
   - [Getting Information For A Specific Channel](#getting-information-for-a-specific-channel)
   - [Getting User Information For A Presence Channel](#getting-user-information-for-a-presence-channel)
 - [Authenticating Channel Subscription](#authenticating-channel-subscription)
+- [Terminating User Connections](#terminating-user-connections)
 - [End-to-end Encryption](#end-to-end-encryption)
 - [Receiving Webhooks](#receiving-webhooks)
 - [Request Library Configuration](#request-library-configuration)
@@ -287,6 +288,18 @@ auth = pusher_client.authenticate(
 # return `auth` as a response
 ```
 
+## Terminating user connections
+
+TIn order to terminate a user's connections, the user must have been authenticated. Check the [Server user authentication docs](http://pusher.com/docs/authenticating_users) for the information on how to create a user authentication endpoint.
+
+To terminate all connections established by a given user, you can use the `terminate_user_connections` function:
+
+```python
+pusher_client.terminate_user_connections(userId)
+```
+
+Please note, that it only terminates the user's active connections. This means, if nothing else is done, the user will be able to reconnect. For more information see: [Terminating user connections docs](https://pusher.com/docs/channels/server_api/terminating-user-connections/).
+
 ## End to End Encryption
 
 This library supports end to end encryption of your private channels. This
@@ -400,6 +413,7 @@ Get the list of channels in an application | *&#10004;*
 Get the state of a single channel          | *&#10004;*
 Get a list of users in a presence channel  | *&#10004;*
 WebHook validation                         | *&#10004;*
+Terminate user connections                 | *&#10004;*
 Heroku add-on support                      | *&#10004;*
 Debugging & Logging                        | *&#10004;*
 Cluster configuration                      | *&#10004;*

pusher/pusher.py

@@ -154,7 +154,6 @@ def trigger(self, channels, event_name, data, socket_id=None):
     def trigger_batch(self, batch=[], already_encoded=False):
         return self._pusher_client.trigger_batch(batch, already_encoded)
 
-
     @doc_string(PusherClient.channels_info.__doc__)
     def channels_info(self, prefix_filter=None, attributes=[]):
         return self._pusher_client.channels_info(prefix_filter, attributes)
@@ -164,11 +163,13 @@ def channels_info(self, prefix_filter=None, attributes=[]):
     def channel_info(self, channel, attributes=[]):
         return self._pusher_client.channel_info(channel, attributes)
 
-
     @doc_string(PusherClient.users_info.__doc__)
     def users_info(self, channel):
         return self._pusher_client.users_info(channel)
 
+    @doc_string(PusherClient.terminate_user_connections.__doc__)
+    def terminate_user_connections(self, user_id):
+        return self._pusher_client.terminate_user_connections(user_id)
 
     @doc_string(AuthenticationClient.authenticate.__doc__)
     def authenticate(self, channel, socket_id, custom_data=None):

pusher/pusher_client.py

@@ -24,6 +24,7 @@
     ensure_text,
     validate_channel,
     validate_socket_id,
+    validate_user_id,
     join_attributes,
     data_to_string)
 
@@ -113,7 +114,6 @@ def trigger(self, channels, event_name, data, socket_id=None):
 
         return Request(self, POST, "/apps/%s/events" % self.app_id, params)
 
-
     @request_method
     def trigger_batch(self, batch=[], already_encoded=False):
         """Trigger multiple events with a single HTTP call.
@@ -142,7 +142,6 @@ def trigger_batch(self, batch=[], already_encoded=False):
         return Request(
             self, POST, "/apps/%s/batch_events" % self.app_id, params)
 
-
     @request_method
     def channels_info(self, prefix_filter=None, attributes=[]):
         """Get information on multiple channels, see:
@@ -187,3 +186,9 @@ def users_info(self, channel):
 
         return Request(
             self, GET, "/apps/%s/channels/%s/users" % (self.app_id, channel))
+
+    @request_method
+    def terminate_user_connections(self, user_id):
+        validate_user_id(user_id)
+        return Request(
+            self, POST, "/users/{}/terminate_connections".format(user_id), {})

pusher/util.py

@@ -67,6 +67,21 @@ def is_base64(s):
     except Exception as e:
         return False
 
+def validate_user_id(user_id):
+    user_id = ensure_text(user_id, "user_id")
+
+    length = len(user_id)
+    if length == 0:
+        raise ValueError("User id is empty")
+
+    if length > 200:
+        raise ValueError("User id too long: '{}'".format(user_id))
+
+    if not channel_name_re.match(user_id):
+        raise ValueError("Invalid user id: '{}'".format(user_id))
+
+    return user_id
+
 def validate_channel(channel):
     channel = ensure_text(channel, "channel")
 

pusher/version.py

@@ -1,2 +1,2 @@
 # Don't change the format of this line: the version is extracted by ../setup.py
-VERSION = '3.2.0'
+VERSION = '3.3.0'

pusher_tests/test_pusher_client.py

@@ -15,7 +15,7 @@
 import base64
 
 from pusher.pusher_client import PusherClient
-from pusher.http import GET
+from pusher.http import GET, POST
 from pusher.crypto import *
 
 try:
@@ -57,7 +57,7 @@ def test_trigger_with_channels_list_success_case(self):
             request = self.pusher_client.trigger.make_request([u'some_channel'], u'some_event', {u'message': u'hello world'})
 
             self.assertEqual(request.path, u'/apps/4/events')
-            self.assertEqual(request.method, u'POST')
+            self.assertEqual(request.method, POST)
 
             expected_params = {
                 u'channels': [u'some_channel'],
@@ -366,6 +366,16 @@ def test_user_info_success_case(self):
         self.assertEqual(request.path, u'/apps/4/channels/presence-channel/users')
         self.assertEqual(request.params, {})
 
+    def test_terminate_user_connection_success_case(self):
+        request = self.pusher_client.terminate_user_connections.make_request('123')
+        self.assertEqual(request.path, u'/users/123/terminate_connections')
+        self.assertEqual(request.method, POST)
+        self.assertEqual(request.params, {})
+
+    def test_terminate_user_connection_fail_case_invalid_user_id(self):
+        with self.assertRaises(ValueError):
+            self.pusher_client.terminate_user_connections("")
+
 
 if __name__ == '__main__':
     unittest.main()

pusher_tests/test_util.py

@@ -0,0 +1,18 @@
+import unittest
+
+import pusher.util
+
+class TestUtil(unittest.TestCase):
+    def test_validate_user_id(self):
+        valid_user_ids = ["1", "12", "abc", "ab12", "ABCDEFG1234"]
+        invalid_user_ids = ["", "x" * 201, "abc%&*"]
+
+        for user_id in valid_user_ids:
+            self.assertEqual(user_id, pusher.util.validate_user_id(user_id))
+
+        for user_id in invalid_user_ids:
+            with self.assertRaises(ValueError):
+                pusher.util.validate_user_id(user_id)
+
+if __name__ == '__main__':
+    unittest.main()