Add serverless config (#75)

* fix: Potential conflict with duplicate Notification model
* fix: Potential related_name clash for custom models
*Make django_json_field optional (Suppress warnings)
* Add `pusher` provider
* docs: Update documentation
* feat: Producers and Consumers
* feat: Add serverless config

Author: danidee10

.flake8

@@ -0,0 +1,3 @@
+[flake8]
+# ignore = E226,E302,E41
+max-line-length = 88

.gitignore

@@ -11,3 +11,4 @@ htmlcov/
 .coverage.*
 coverage.xml
 *.cover
+node_modules/

.pycodestyle

@@ -0,0 +1,2 @@
+[pycodestyle]
+max-line-length = 88

.travis.yml

@@ -84,3 +84,7 @@ deploy:
     tags: true
     distributions: sdist bdist_wheel
     repo: danidee10/django-notifs
+
+
+services:
+  - redis

docs/_static/images/django-notifs-celery.png

@@ -4,6 +4,39 @@ Advanced usage
 .. _documentation: https://channels.readthedocs.io/en/stable/index.html
 .. _channels deployment documentation: https://channels.readthedocs.io/en/stable/deploying.html
 
+Tentative Notifications
+--------------------------------
+
+A tentative notification is a conditional notification that should only be sent if a criteria is met.
+
+An example is sending a notification if a user hasn't read a chat message in 30 minutes (as a reminder).
+
+You can acheive this by combining the ``countdown`` functionality with a custom provider::
+
+    # delay notification for 30 minutes
+    notify(**kwargs, countdown=1800)
+
+Custom provider::
+
+    from notifications.utils import get_notification_model
+    from notifications.providers import BaseNotificationProvider
+
+    class DelayedNotificationProvider(BaseNotificationProvider):
+
+        name = 'delayed_notifier'
+
+        def send(self, payload):
+            notification_id = self.payload['notification_id']
+
+            notification = get_notification_model().objects.get(id=self.notification_id)
+            if notification.read:
+                return
+
+            # send the notification
+
+In this example, we abort the notification if the notification has been read when the provider is executed.
+
+
 WebSockets
 ---------------------
 
@@ -42,37 +75,22 @@ Notification channels
 ---------------------
 A simple WebSocket channel is provided:
 
-- notifications.channels.WebSocketChannel
-
-This channel simply delivers notifications to the ``settings.NOTIFICATIONS_WEBSOCKET_EVENT_NAME`` group.
-
-Add the channel to ``settings.NOTIFICATION_CHANNELS``::
-
-    NOTIFICATION_CHANNELS = {
-        'websocket': 'notifications.channels.WebSocketChannel'
-    }
+``notifications.channels.DjangoWebSocketChannel``
 
 Sample usage::
 
-    from notifications import default_settings as notifs_settings
-    ...
-
     notif_args = {
-        'source': user,
-        'source_display_name': user.get_full_name(),
-        'category': 'MESSAGE', 'action': 'Sent',
-        'obj': obj.id,
-        'short_description': 'You a new message', 'silent': True,
-        'extra_data': {
-            notifs_settings.NOTIFICATIONS_WEBSOCKET_URL_PARAM: chat_session.uri,
-            'message': chat_session_message.to_json()
+        ...
+        extra_data: {
+            'context': {
+                'channel_layer': 'default',
+                'destination': 'group or channel_name',
+                'message': {'text': 'Hello world'}
+            }
         }
     }
     notify(**notif_args, channels=['websocket'])
 
-``notifs_settings.NOTIFICATIONS_WEBSOCKET_URL_PARAM`` is a required key. You can also override it in ``settings.py``
-and reference it through ``django.conf.settings.NOTIFICATIONS_WEBSOCKET_URL_PARAM``
-
 
 Running the WebSocket server
 ----------------------------
@@ -91,9 +109,9 @@ You listen to notifications by connecting to the WebSocket URL.
 
 The default URL is ``http://localhost:8000/<settings.NOTIFICATIONS_WEBSOCKET_URL_PARAM>``
 
-To connect to a WebSocket room (via JavaScript) for a user ``danidee`` you'll need to connect to::
+To connect to a WebSocket room (via JavaScript) for a user ``john_doe`` you'll need to connect to::
 
-    var websocket = new WebSocket('ws://localhost:8000/danidee')
+    var websocket = new WebSocket('ws://localhost:8000/john_doe')
 
 You can always change the default route by Importing the ``notifications.consumers.DjangoNotifsWebsocketConsumer``
 consumer and declaring another route. If you decide to do that, make sure you use the
@@ -125,12 +143,10 @@ if you don't make use of the standard Authentication backend.
 Testing and Debugging
 ---------------------
 
-django-notifs comes with an inbuilt console delivery channel that just prints out the notification arguments::
-
-
-    NOTIFICATIONS_CHANNELS = {
-        'console': 'notifications.channels.ConsoleChannel'
-    }
+django-notifs comes with an inbuilt ``'console'`` provider that just prints out the notification payload::
 
+    class MyNotificationChannel:
+        providers = ['console']
+        ...
 
-This can be helpful during development where you don't want notifications to be delivered.
+This can be helpful during development when it's used with the Synchronous backend.

docs/advanced-usage.rst

@@ -4,9 +4,11 @@ Backends
 .. _Celery settings in the repo: https://github.com/danidee10/django-notifs/blob/master/notifs/settings.py
 .. _django-rq: https://github.com/rq/django-rq
 .. _django-rq documentation: https://github.com/rq/django-rq
+.. _Serverless documentation for AWS: https://www.serverless.com/framework/docs/providers/aws
+.. _lambda worker repository: https://github.com/danidee10/django-notifs-lambda-worker
 
-The primary function of **a delivery backend** is to execute the code of the delivery channels.
-*Unlike delivery channels, you can only use one delivery backend at the same time.*
+The primary function of **a delivery backend** is to execute the code of the delivery channels and providers.
+*Unlike notification channels, you can only use one delivery backend at a time.*
 
 
 Celery
@@ -20,11 +22,11 @@ Enable it by setting ``NOTIFICATIONS_DELIVERY_BACKEND`` to ``notifications.backe
 
 Run celery with the command::
 
-    celery -A yourapp worker -l info -Q django_notifs
+    celery -A yourapp worker -l info -Q django-notifs
 
 Whenever a notification is created, it's automatically sent to celery and processed.
 
-**Make sure you see the queue and task (notifications.backends.celery.send_notification) in the terminal**
+Make sure you see the queue and task (``notifications.backends.celery.consume``) in the terminal.
 
 .. image:: _static/images/django-notifs-celery.png
 
@@ -105,6 +107,46 @@ Finally start the rq worker with::
 See the `django-rq documentation`_ for more details
 
 
+AwsLambda (with SQS)
+--------------------
+
+The setup for this backend is more involved but it's probably the cheapest and most scalable backend to use in production
+because the heavylifting and execution environment is handled by AWS.
+
+set ``NOTIFICATIONS_DELIVERY_BACKEND`` to ``notifications.backends.AwsSqsLambda``
+
+Clone the `lambda worker repository`_ and run::
+
+    npm install
+
+The ``sqs-lambda-worker`` folder includes four files that are of interest:
+
+``.env.example``
+
+You can use this file (after renaming it to ``.env``) to configure the environment variables for the autogenerated Lambda function.
+You can replace this step by:
+    - Configuring the environment variables in your CI/CD environment **(Recommended)**
+    - Exporting them in the current shell.
+This is useful if you want to test the serverless deployment locally before moving it to your CI/CD
+
+``requirements.txt``
+
+In order to keep the lambda function as lean as possible,
+you have to explicitly declare the requirements that are necessary
+for the lambda function. New providers (and their dependencies) are continuously added to django-notifs
+so it's not adviseable to install dependencies for providers that you don't need because this could impact
+the startup time of your Lambda function.
+
+``serverless.yml``
+
+The Serverless file. It contains a blueprint that deploys the simplest configuration possible but the configuration options
+are endless. see the `Serverless documentation for AWS`_ for more information.
+
+``settings.py``
+
+Declare the Django settings for the lambda function
+
+
 Synchronous
 -----------
 This is the default backend that sends notifications synchronously.

docs/backends.rst

@@ -55,7 +55,8 @@
 
 
 # Cusotm settings
-source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
 
 # Logo
 # html_logo = '_static/images/django-notifs.png'
+pygments_style = 'sphinx'

docs/conf.py

@@ -11,26 +11,6 @@ This setting is used override the default database Model for saving notification
 but it can be useful if you're trying to integrate django-notifs into an existing project that already has it's own Notificaiton model
 
 
-``NOTIFICATIONS_CHANNELS``
---------------------------
-
-``Default={}``
-
-A dictionary of notification channels.
-
-**Keys:** The softname of the notification channel which is used in your code
-
-**Values:**  The path to the notification channel's class.
-
-Example::
-
-    NOTIFICATIONS_CHANNELS = {
-        'console': 'notifications.channels.ConsoleChannel'
-    }
-
-django-notifs comes with an inbuilt console delivery channel that just prints out the notification arguments
-
-
 
 ``NOTIFICATIONS_DELIVERY_BACKEND``
 ----------------------------------
@@ -100,6 +80,6 @@ In most cases, you don't need to change this setting.
 
 ``Default = 'room_name'``
 
-The WebSocket URL param name. This setting **MUST** be used in the ``notify`` method's ``extra_data`` dictionary.
+The WebSocket URL param name.
 It's also used to construct the WebSocket URL.
 See the :ref:`Advanced usage <Notification channels>` section for more information.

docs/configuration.rst

@@ -14,4 +14,5 @@ Contents
    usage
    configuration
    backends
+   providers
    advanced-usage