Adding 'force_disconnect()' method (#132)

*Add force_disconnect API

Author: normanargueta

README.rst

@@ -259,6 +259,19 @@ The method return a Stream object that contains information of an OpenTok stream
   print stream.name #stream name
   print stream.layoutClassList #['full']
 
+Force Disconnect
+~~~~~~~~~~~~~~~~~~~~~
+
+Your application server can disconnect a client from an OpenTok session by calling the force_disconnect(session_id, connection_id) method of the OpenTok class, or the force_disconnect(connection_id) method of the Session class.
+
+.. code:: python
+
+  session_id = 'SESSIONID'
+  connection_id = 'CONNECTIONID'
+
+  # To send a request to disconnect a client:
+  opentok.force_disconnect(session_id, connection_id)
+
 Samples
 -------
 

opentok/__init__.py

@@ -1,6 +1,6 @@
 from .opentok import OpenTok, Roles, MediaModes, ArchiveModes
 from .session import Session
 from .archives import Archive, ArchiveList, OutputModes
-from .exceptions import OpenTokException
+from .exceptions import OpenTokException, AuthError, ForceDisconnectError
 from .version import __version__
 from .stream import Stream

opentok/endpoints.py

@@ -30,3 +30,10 @@ def get_stream_url(self, session_id, stream_id):
         url = self.api_url + '/v2/project/' + self.api_key + '/session/' + session_id + '/stream/' + stream_id
         return url
 
+    def force_disconnect_url(self, session_id, connection_id):
+        """ this method returns the force disconnect url endpoint """
+        url = (
+            self.api_url + '/v2/project/' + self.api_key + '/session/' +
+            session_id + '/connection/' + connection_id
+        )
+        return url

opentok/exceptions.py

@@ -40,3 +40,11 @@ class GetStreamError(OpenTokException):
     """Indicates that the data in the request is invalid, or the session_id or stream_id
     are invalid"""
     pass
+
+class ForceDisconnectError(OpenTokException):
+    """
+    Indicates that there was a force disconnect specific problem:
+    One of the arguments is invalid or the client specified by the connectionId property
+    is not connected to the session
+    """
+    pass

opentok/opentok.py

@@ -30,7 +30,8 @@
     NotFoundError,
     ArchiveError,
     SignalingError,
-    GetStreamError
+    GetStreamError,
+    ForceDisconnectError
 )
 
 class Roles(Enum):
@@ -534,6 +535,31 @@ def get_stream(self, session_id, stream_id):
         else:
             raise RequestError('An unexpected error occurred', response.status_code)
 
+    def force_disconnect(self, session_id, connection_id):
+        """
+        Sends a request to disconnect a client from an OpenTok session
+
+        :param String session_id: The session ID of the OpenTok session from which the
+        client will be disconnected
+
+        :param String connection_id: The connection ID of the client that will be disconnected
+        """
+        endpoint = self.endpoints.force_disconnect_url(session_id, connection_id)
+        response = requests.delete(
+            endpoint, headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout
+        )
+
+        if response.status_code == 204:
+            pass
+        elif response.status_code == 400:
+            raise ForceDisconnectError('One of the arguments - sessionId or connectionId - is invalid.')
+        elif response.status_code == 403:
+            raise AuthError('You are not authorized to forceDisconnect, check your authentication credentials.')
+        elif response.status_code == 404:
+            raise ForceDisconnectError('The client specified by the connectionId property is not connected to the session.')
+        else:
+            raise RequestError('An unexpected error occurred', response.status_code)
+
     def _sign_string(self, string, secret):
         return hmac.new(secret.encode('utf-8'), string.encode('utf-8'), hashlib.sha1).hexdigest()
 

tests/test_force_disconnect.py

@@ -0,0 +1,82 @@
+import unittest
+from six import u
+from expects import *
+import httpretty
+
+from opentok import OpenTok, __version__, AuthError, ForceDisconnectError
+from .validate_jwt import validate_jwt_header
+
+class OpenTokForceDisconnectTest(unittest.TestCase):
+    """" Class that contains test for force disconnect functionality """
+
+    def setUp(self):
+        self.api_key = u('123456')
+        self.api_secret = u('1234567890abcdef1234567890abcdef1234567890')
+        self.opentok = OpenTok(self.api_key, self.api_secret)
+        self.session_id = u('SESSIONID')
+        self.connection_id = u('CONNECTIONID')
+
+    @httpretty.activate
+    def test_force_disconnect(self):
+        """ Method to test force disconnect functionality using an OpenTok instance """
+
+        httpretty.register_uri(
+            httpretty.DELETE,
+            u('https://api.opentok.com/v2/project/{0}/session/{1}/connection/{2}').format(
+                self.api_key,
+                self.session_id,
+                self.connection_id
+            ),
+            status=204,
+            content_type=u('application/json')
+        )
+
+        self.opentok.force_disconnect(self.session_id, self.connection_id)
+
+        validate_jwt_header(self, httpretty.last_request().headers[u('x-opentok-auth')])
+        expect(httpretty.last_request().headers[u('user-agent')]).to(contain(u('OpenTok-Python-SDK/')+__version__))
+        expect(httpretty.last_request().headers[u('content-type')]).to(equal(u('application/json')))
+
+    @httpretty.activate
+    def test_throws_force_disconnect_exception(self):
+        """ This method should throw a ForceDisconnectError """
+
+        httpretty.register_uri(
+            httpretty.DELETE,
+            u('https://api.opentok.com/v2/project/{0}/session/{1}/connection/{2}').format(
+                self.api_key,
+                self.session_id,
+                self.connection_id
+            ),
+            status=400,
+            content_type=u('application/json')
+        )
+
+        self.assertRaises(
+            ForceDisconnectError,
+            self.opentok.force_disconnect,
+            self.session_id,
+            self.connection_id
+        )
+
+    @httpretty.activate
+    def test_throws_auth_exception(self):
+        """ This method should throw an AuthError """
+
+        httpretty.register_uri(
+            httpretty.DELETE,
+            u('https://api.opentok.com/v2/project/{0}/session/{1}/connection/{2}').format(
+                self.api_key,
+                self.session_id,
+                self.connection_id
+            ),
+            status=403,
+            content_type=u('application/json')
+        )
+
+        self.assertRaises(
+            AuthError,
+            self.opentok.force_disconnect,
+            self.session_id,
+            self.connection_id
+        )