Adding Signaling functionality (#128)

* Add signaling API

Author: normanargueta

README.rst

@@ -210,6 +210,27 @@ Note that you can also create an automatically archived session, by passing in
 For more information on archiving, see the
 `OpenTok archiving <https://tokbox.com/opentok/tutorials/archiving/>`_ programming guide.
 
+Sending Signals
+~~~~~~~~~~~~~~~~~~~~~
+
+Once a Session is created, you can send signals to everyone in the session or to a specific connection. You can send a signal by calling the ``signal(session_id, payload)`` method of the ``OpenTok`` class. The ``payload`` parameter is a dictionary used to set the ``type``, ``data`` fields. Ỳou can also call the method with the parameter ``connection_id`` to send a signal to a specific connection ``signal(session_id, data, connection_id)``.
+
+.. code:: python
+
+  # payload structure
+  payload = {
+      'type': 'type', #optional
+      'data': 'signal data' #required
+  }
+
+  connection_id = '2a84cd30-3a33-917f-9150-49e454e01572'
+
+  # To send a signal to everyone in the session:
+  opentok.signal(session_id, payload)
+
+  # To send a signal to a specific connection in the session:
+  opentok.signal(session_id, payload, connection_id)
+
 
 Samples
 -------

opentok/exceptions.py

@@ -30,3 +30,8 @@ class ArchiveError(OpenTokException):
     of the requested archive is invalid.
     """
     pass
+
+class SignalingError(OpenTokException):
+    """Indicates that there was a signaling specific problem, one of the parameter
+    is invalid or the type|data string doesn't have a correct size"""
+    pass

opentok/opentok.py

@@ -21,7 +21,7 @@
 from .version import __version__
 from .session import Session
 from .archives import Archive, ArchiveList, OutputModes
-from .exceptions import OpenTokException, RequestError, AuthError, NotFoundError, ArchiveError
+from .exceptions import OpenTokException, RequestError, AuthError, NotFoundError, ArchiveError, SignalingError
 
 class Roles(Enum):
     """List of valid roles for a token."""
@@ -293,7 +293,7 @@ def headers(self):
             'X-OPENTOK-AUTH': self._create_jwt_auth_header()
         }
 
-    def archive_headers(self):
+    def json_headers(self):
         """For internal use."""
         result = self.headers()
         result['Content-Type'] = 'application/json'
@@ -311,6 +311,17 @@ def archive_url(self, archive_id=None):
             url = url + '/' + archive_id
         return url
 
+    def signaling_url(self, session_id, connection_id=None):
+        """For internal use."""
+        url = self.api_url + '/v2/project/' + self.api_key + '/session/' + session_id
+
+        if connection_id:
+            url += '/connection/' + connection_id
+
+        url += '/signal'
+
+        return url
+
     def start_archive(self, session_id, has_audio=True, has_video=True, name=None, output_mode=OutputModes.composed, resolution=None):
         """
         Starts archiving an OpenTok session.
@@ -361,7 +372,7 @@ def start_archive(self, session_id, has_audio=True, has_video=True, name=None, o
                    'resolution': resolution,
         }
 
-        response = requests.post(self.archive_url(), data=json.dumps(payload), headers=self.archive_headers(), proxies=self.proxies, timeout=self.timeout)
+        response = requests.post(self.archive_url(), data=json.dumps(payload), headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
 
         if response.status_code < 300:
             return Archive(self, response.json())
@@ -394,7 +405,7 @@ def stop_archive(self, archive_id):
 
         :rtype: The Archive object corresponding to the archive being stopped.
         """
-        response = requests.post(self.archive_url(archive_id) + '/stop', headers=self.archive_headers(), proxies=self.proxies, timeout=self.timeout)
+        response = requests.post(self.archive_url(archive_id) + '/stop', headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
 
         if response.status_code < 300:
             return Archive(self, response.json())
@@ -417,7 +428,7 @@ def delete_archive(self, archive_id):
 
         :param String archive_id: The archive ID of the archive to be deleted.
         """
-        response = requests.delete(self.archive_url(archive_id), headers=self.archive_headers(), proxies=self.proxies, timeout=self.timeout)
+        response = requests.delete(self.archive_url(archive_id), headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
 
         if response.status_code < 300:
             pass
@@ -435,7 +446,7 @@ def get_archive(self, archive_id):
 
         :rtype: The Archive object.
         """
-        response = requests.get(self.archive_url(archive_id), headers=self.archive_headers(), proxies=self.proxies, timeout=self.timeout)
+        response = requests.get(self.archive_url(archive_id), headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
 
         if response.status_code < 300:
             return Archive(self, response.json())
@@ -464,7 +475,7 @@ def get_archives(self, offset=None, count=None):
         if count is not None:
             params['count'] = count
 
-        response = requests.get(self.archive_url() + "?" + urlencode(params), headers=self.archive_headers(), proxies=self.proxies, timeout=self.timeout)
+        response = requests.get(self.archive_url() + "?" + urlencode(params), headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
 
         if response.status_code < 300:
             return ArchiveList(self, response.json())
@@ -475,6 +486,42 @@ def get_archives(self, offset=None, count=None):
         else:
             raise RequestError("An unexpected error occurred", response.status_code)
 
+    def signal(self, session_id, payload, connection_id=None):
+        """
+        Send signals to all participants in an active OpenTok session or to a specific client
+        connected to that session.
+
+        :param String session_id: The session ID of the OpenTok session that receives the signal
+
+        :param Dictionary payload: Structure that contains both the type and data fields. These
+        correspond to the type and data parameters passed in the client signal received handlers
+
+        :param String connection_id: The connection_id parameter is an optional string used to
+        specify the connection ID of a client connected to the session. If you specify this value,
+        the signal is sent to the specified client. Otherwise, the signal is sent to all clients
+        connected to the session
+        """
+        response = requests.post(
+            self.signaling_url(session_id, connection_id),
+            data=json.dumps(payload),
+            headers=self.json_headers(),
+            proxies=self.proxies,
+            timeout=self.timeout
+        )
+
+        if response.status_code == 204:
+            pass
+        elif response.status_code == 400:
+            raise SignalingError('One of the signal properties - data, type, sessionId or connectionId - is invalid.')
+        elif response.status_code == 403:
+            raise AuthError('You are not authorized to send the signal. Check your authentication credentials.')
+        elif response.status_code == 404:
+            raise SignalingError('The client specified by the connectionId property is not connected to the session.')
+        elif response.status_code == 413:
+            raise SignalingError('The type string exceeds the maximum length (128 bytes), or the data string exceeds the maximum size (8 kB).')
+        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_signal.py

@@ -0,0 +1,76 @@
+import unittest
+from six import text_type, u, b, PY2, PY3
+from opentok import OpenTok, Session, __version__
+import httpretty
+import json
+import textwrap
+from expects import *
+
+from .validate_jwt import validate_jwt_header
+
+class OpenTokSignalTest(unittest.TestCase):
+    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')
+
+    @httpretty.activate
+    def test_signal(self):
+        data = {
+            u('type'): u('type test'),
+            u('data'): u('test data')
+        }
+
+        httpretty.register_uri(httpretty.POST, u('https://api.opentok.com/v2/project/{0}/session/{1}/signal').format(self.api_key, self.session_id),
+                               body=textwrap.dedent(u("""\
+                                       {
+                                          "type": "type test",
+                                          "data": "test data"
+                                        }""")),
+                               status=204,
+                               content_type=u('application/json'))
+
+        self.opentok.signal(self.session_id, data)
+
+        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')))
+        # non-deterministic json encoding. have to decode to test it properly
+        if PY2:
+            body = json.loads(httpretty.last_request().body)
+        if PY3:
+            body = json.loads(httpretty.last_request().body.decode('utf-8'))
+        expect(body).to(have_key(u('type'), u('type test')))
+        expect(body).to(have_key(u('data'), u('test data')))
+
+    @httpretty.activate
+    def test_signal_with_connection_id(self):
+        data = {
+            u('type'): u('type test'),
+            u('data'): u('test data')
+        }
+
+        connection_id = u('da9cb410-e29b-4c2d-ab9e-fe65bf83fcaf')
+
+        httpretty.register_uri(httpretty.POST, u('https://api.opentok.com/v2/project/{0}/session/{1}/connection/{2}/signal').format(self.api_key, self.session_id, connection_id),
+                               body=textwrap.dedent(u("""\
+                                       {
+                                          "type": "type test",
+                                          "data": "test data"
+                                        }""")),
+                               status=204,
+                               content_type=u('application/json'))
+
+        self.opentok.signal(self.session_id, data, 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')))
+        # non-deterministic json encoding. have to decode to test it properly
+        if PY2:
+            body = json.loads(httpretty.last_request().body)
+        if PY3:
+            body = json.loads(httpretty.last_request().body.decode('utf-8'))
+        expect(body).to(have_key(u('type'), u('type test')))
+        expect(body).to(have_key(u('data'), u('test data')))