Merge pull request #90 from geeknam/topic_messaging

Added Topic Messaging support

Author: alibitek

README.rst

@@ -36,6 +36,7 @@ Features
 * Proxy support
 * Easily handle errors
 * Uses `requests` from version > 0.2
+* Topic Messaging `Reference <https://developers.google.com/cloud-messaging/topic-messaging>`__
 
 Usage
 ------------
@@ -65,6 +66,11 @@ Basic
        collapse_key='uptoyou', delay_while_idle=True, time_to_live=3600
    )
 
+   # Topic Messaging
+   topic = 'foo'
+   gcm.send_topic_message(topic=topic, data=data)
+
+
 Error handling
 
 .. code-block:: python

gcm/gcm.py

@@ -5,6 +5,7 @@
 import random
 from sys import version_info
 import logging
+import re
 
 GCM_URL = 'https://gcm-http.googleapis.com/gcm/send'
 
@@ -32,6 +33,11 @@ class GCMTooManyRegIdsException(GCMException):
 class GCMInvalidTtlException(GCMException):
     pass
 
+
+class GCMTopicMessageException(GCMException):
+    pass
+
+
 # Exceptions from Google responses
 
 
@@ -59,6 +65,10 @@ class GCMUnavailableException(GCMException):
     pass
 
 
+class GCMInvalidInputException(GCMException):
+    pass
+
+
 # TODO: Refactor this to be more human-readable
 # TODO: Use OrderedDict for the result type to be able to preserve the order of the messages returned by GCM server
 def group_response(response, registration_ids, key):
@@ -104,6 +114,8 @@ class Payload(object):
     # TTL in seconds
     GCM_TTL = 2419200
 
+    topicPattern = re.compile('/topics/[a-zA-Z0-9-_.~%]+')
+
     def __init__(self, **kwargs):
         self.validate(kwargs)
         self.__dict__.update(**kwargs)
@@ -121,7 +133,16 @@ def validate(self, options):
     def validate_time_to_live(self, value):
         if not (0 <= value <= self.GCM_TTL):
             raise GCMInvalidTtlException("Invalid time to live value")
-
+    
+    def validate_registration_ids(self, registration_ids):
+
+        if len(registration_ids) > 1000:
+            raise GCMTooManyRegIdsException("Exceded number of registration_ids")
+    
+    def validate_to(self, value):
+        if not re.match(Payload.topicPattern, value):
+            raise GCMInvalidInputException("Invalid topic name: {0}! Does not match the {1} pattern".format(value, Payload.topicPattern))
+    
     @property
     def body(self):
         raise NotImplementedError
@@ -221,6 +242,16 @@ def construct_payload(self, **kwargs):
         is_json = kwargs.pop('is_json', True)
 
         if is_json:
+            if 'topic' not in kwargs and 'registration_ids' not in kwargs:
+                raise GCMMissingRegistrationException("Missing registration_ids or topic")
+            elif 'topic' in kwargs and 'registration_ids' in kwargs :
+                raise GCMInvalidInputException("Invalid parameters! Can't have both 'registration_ids' and 'to' as input parameters")
+
+            if 'topic' in kwargs:
+                kwargs['to'] = '/topics/{}'.format(kwargs.pop('topic'))
+            elif 'registration_ids' not in kwargs:
+                    raise GCMMissingRegistrationException("Missing registration_ids")
+            
             payload = JsonPayload(**kwargs).body
         else:
             payload = PlaintextPayload(**kwargs).body
@@ -343,6 +374,12 @@ def handle_json_response(self, response, registration_ids):
 
         return info
 
+    def handle_topic_response(self, response):
+        error = response.get('error')
+        if error:
+            raise GCMTopicMessageException(error)
+        return response['message_id']
+
     def extract_unsent_reg_ids(self, info):
         if 'errors' in info and 'Unavailable' in info['errors']:
             return info['errors']['Unavailable']
@@ -354,11 +391,14 @@ def plaintext_request(self, **kwargs):
 
         :return dict of response body from Google including multicast_id, success, failure, canonical_ids, etc
         """
+        if 'registration_id' not in kwargs:
+            raise GCMMissingRegistrationException("Missing registration_id")
+        elif not kwargs['registration_id']:
+            raise GCMMissingRegistrationException("Empty registration_id")
 
         kwargs['is_json'] = False
         retries = kwargs.pop('retries', 5)
         payload = self.construct_payload(**kwargs)
-
         backoff = self.BACKOFF_INITIAL_DELAY
         info = None
         has_error = False
@@ -392,10 +432,14 @@ def json_request(self, **kwargs):
         """
         Makes a JSON request to GCM servers
 
-        :param registration_ids: list of the registration ids
-        :param data: dict mapping of key-value pairs of messages
+        :param kwargs: dict mapping of key-value pairs of parameters
         :return dict of response body from Google including multicast_id, success, failure, canonical_ids, etc
         """
+        if 'registration_ids' not in kwargs:
+            raise GCMMissingRegistrationException("Missing registration_ids")
+        elif not kwargs['registration_ids']:
+            raise GCMMissingRegistrationException("Empty registration_ids")
+
         args = dict(**kwargs)
 
         retries = args.pop('retries', 5)
@@ -440,3 +484,40 @@ def json_request(self, **kwargs):
             raise IOError("Could not make request after %d attempts" % retries)
 
         return info
+
+    def send_topic_message(self, **kwargs):
+        """
+        Publish Topic Messaging to GCM servers
+        Ref: https://developers.google.com/cloud-messaging/topic-messaging
+
+        :param kwargs: dict mapping of key-value pairs of parameters
+        :return message_id
+        :raises GCMInvalidInputException: if the topic is empty
+        """
+
+        if 'topic' not in kwargs:
+            raise GCMInvalidInputException("Topic name missing!")
+        elif not kwargs['topic']:
+            raise GCMInvalidInputException("Topic name cannot be empty!")
+
+        retries = kwargs.pop('retries', 5)
+        payload = self.construct_payload(**kwargs)
+        backoff = self.BACKOFF_INITIAL_DELAY
+
+        for attempt in range(retries):
+            try:
+                response = self.make_request(payload, is_json=True)
+                return self.handle_topic_response(response)
+            except GCMUnavailableException:
+                sleep_time = backoff / 2 + random.randrange(backoff)
+                time.sleep(float(sleep_time) / 1000)
+                if 2 * backoff < self.MAX_BACKOFF_DELAY:
+                    backoff *= 2
+        else:
+            raise IOError("Could not make request after %d attempts" % retries)
+
+    def send_device_group_message(self, **kwargs):
+        raise NotImplementedError
+
+    def send_downstream_message(self, **kwargs):
+        return self.json_request(**kwargs)

gcm/test.py

@@ -106,6 +106,42 @@ def test_plaintext_payload(self):
         self.assertIn('data.param1', result)
         self.assertIn('data.param2', result)
 
+    def test_topic_payload(self):
+        topic = 'foo'
+        json_payload = self.gcm.construct_payload(topic=topic,
+                                                  data=self.data)
+        payload = json.loads(json_payload)
+
+        self.assertEqual(payload['data'], self.data)
+        self.assertEqual(payload.get('to'), '/topics/foo')
+
+    def test_invalid_registration_ids_and_topic(self):
+        with self.assertRaises(GCMMissingRegistrationException):
+            self.gcm.construct_payload()
+
+        with self.assertRaises(GCMInvalidInputException):
+            reg_ids = ['12', '145', '56']
+            topic = 'foo'
+            self.gcm.construct_payload(registration_ids=reg_ids,
+                                       topic=topic)
+
+    def test_limit_reg_ids(self):
+        reg_ids = range(1003)
+        self.assertTrue(len(reg_ids) > 1000)
+        with self.assertRaises(GCMTooManyRegIdsException):
+            self.gcm.json_request(registration_ids=reg_ids, data=self.data)
+
+    def test_missing_reg_id(self):
+        with self.assertRaises(GCMMissingRegistrationException):
+            self.gcm.json_request(registration_ids=[], data=self.data)
+
+        with self.assertRaises(GCMMissingRegistrationException):
+            self.gcm.plaintext_request(registration_id=None, data=self.data)
+
+    def test_empty_topic(self):
+        with self.assertRaises(GCMInvalidInputException):
+            self.gcm.send_topic_message(topic='', data=self.data)
+
     def test_invalid_ttl(self):
         with self.assertRaises(GCMInvalidTtlException):
             self.gcm.construct_payload(
@@ -192,6 +228,15 @@ def test_handle_plaintext_response(self):
         res = self.gcm.handle_plaintext_response(response)
         self.assertEqual(res, '3456')
 
+    def test_handle_topic_response(self):
+        response = {'error': 'TopicsMessageRateExceeded'}
+        with self.assertRaises(GCMTopicMessageException):
+            self.gcm.handle_topic_response(response)
+
+        response = {'message_id': '10'}
+        res = self.gcm.handle_topic_response(response)
+        self.assertEqual('10', res)
+
     @patch('requests.post')
     def test_make_request_header(self, mock_request):
         """ Test plaintext make_request. """
@@ -310,12 +355,22 @@ def test_retry_json_request_fail(self):
         self.assertIn('Unavailable', res['errors'])
         self.assertEqual(res['errors']['Unavailable'][0], '1')
 
-    def test_retry_json_request_unavailable(self):
-        returns = [GCMUnavailableException(), GCMUnavailableException(), GCMUnavailableException()]
+    def test_retry_topic_request_ok(self):
+        message_id = '123456789'
+        returns = [GCMUnavailableException(), GCMUnavailableException(), {'message_id': message_id}]
 
         self.gcm.make_request = MagicMock(side_effect=create_side_effect(returns))
+        res = self.gcm.send_topic_message(topic='foo', data=self.data)
+
+        self.assertEqual(res, message_id)
+        self.assertEqual(self.gcm.make_request.call_count, 3)
+
+    def test_retry_topic_request_fail(self):
+        returns = [GCMUnavailableException(), GCMUnavailableException(), GCMUnavailableException()]
+        self.gcm.make_request = MagicMock(side_effect=create_side_effect(returns))
+        
         with self.assertRaises(IOError):
-            self.gcm.json_request(registration_ids=['1', '2'], data=self.data, retries=2)
+            self.gcm.send_topic_message(topic='foo', data=self.data, retries=2)
 
         self.assertEqual(self.gcm.make_request.call_count, 2)