Merge pull request #31 from cloudblue/lite-18056-retry-docs

LITE-18056 Added CQRS retry docs

Author: maxipavlovic

docs/_static/css/custom.css

@@ -0,0 +1,14 @@
+/*
+    Copyright © 2021 Ingram Micro Inc. All rights reserved.
+*/
+.wy-table-responsive table {
+    width: 100%;
+}
+
+.wy-table-responsive table td {
+    white-space: normal;
+}
+
+.wy-nav-content{
+    max-width: 1000px;
+}

docs/_static/img/lifecycle.png

@@ -1,3 +1,5 @@
+#  Copyright © 2021 Ingram Micro Inc. All rights reserved.
+
 import os
 import sys
 from datetime import datetime
@@ -15,7 +17,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'django-cqrs'
-copyright = '{}, CloudBlue Inc.'.format(datetime.now().year)
+copyright = '{}, Ingram Micro Inc.'.format(datetime.now().year)
 author = 'CloudBlue'
 
 # The full version, including alpha/beta/rc tags
@@ -56,3 +58,9 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = [
+    'css/custom.css',
+]

docs/conf.py

@@ -35,6 +35,7 @@ and that's okay for non-critical business transactions.
    custom_serialization
    track_fields_changes
    transports
+   lifecycle
    utilities
    reference
 

docs/index.rst

@@ -0,0 +1,129 @@
+.. _lifecycle:
+
+Message lifecycle
+=================
+.. warning::
+
+    Expiration, retrying and dead letter supports only ``RabbitMQTransport`` (on by default).
+
+`django-cqrs` since version 1.11 provides mechanism for reliable message delivery.
+
+.. image:: _static/img/lifecycle.png
+   :scale: 50 %
+   :alt: Message lifecycle
+
+Expiration
+----------
++------------------+------------+--------------------------------------------------------------------------------------------------+
+| Name             | Default    | Description                                                                                      |
++==================+============+==================================================================================================+
+| CQRS_MESSAGE_TTL | 86400      | Limits message lifetime in **seconds**, after that period it will be moved to dead letter queue. |
++------------------+------------+--------------------------------------------------------------------------------------------------+
+
+.. code-block:: python
+
+    # settings.py
+
+    CQRS = {
+        ...
+        'master': {
+            'CQRS_MESSAGE_TTL': 86400, # 1 day
+        },
+    }
+
+Fail
+----
+Message is failed when consume raises any exception or returns negative boolean value (False, None).
+
+.. code-block:: python
+
+    # models.py
+
+    class Example(ReplicaMixin, models.Model):
+        CQRS_ID = 'example'
+        ...
+
+        @classmethod
+        def cqrs_create(cls, sync, mapped_data, previous_data=None):
+            raise Exception("Some issue during create") # exception could be caught at should_retry_cqrs method
+
+        @classmethod
+        def cqrs_update(self, sync, mapped_data, previous_data=None):
+            return None # returning negative boolean triggers retrying
+
+Retrying
+--------
++----------------------+----------+----------------------------------------------------------------------------+
+| Name                 | Default  | Description                                                                |
++======================+==========+============================================================================+
+| CQRS_MAX_RETRIES     | 30       | Maximum number of retry attempts. Infinite if None, 0 for retry disabling. |
++----------------------+----------+----------------------------------------------------------------------------+
+| CQRS_RETRY_DELAY     | 2        | Constant delay in **seconds** between message fail and requeue.            |
++----------------------+----------+----------------------------------------------------------------------------+
+| delay_queue_max_size | None     | Maximum number of delayed messages per worker. Infinite if None.           |
++----------------------+----------+----------------------------------------------------------------------------+
+
+.. code-block:: python
+
+    # settings.py
+
+    CQRS = {
+        ...
+        'replica': {
+            'CQRS_MAX_RETRIES': 30, # attempts
+            'CQRS_RETRY_DELAY': 2,  # seconds
+            'delay_queue_max_size': None, # infinite
+        },
+    }
+
+Customization
+^^^^^^^^^^^^^
+The :class:`dj_cqrs.mixins.ReplicaMixin` allows to set retrying behaviour manually.
+
+.. code-block:: python
+
+    # models.py
+
+    class Example(ReplicaMixin, models.Model):
+        CQRS_ID = 'example'
+        ...
+
+        @classmethod
+        def get_cqrs_retry_delay(cls, current_retry=0):
+            # Linear delay growth
+            return (current_retry + 1) * 60
+
+        @classmethod
+        def should_retry_cqrs(cls, current_retry, exception=None):
+            # Retry 10 times or until we have troubles with database
+            return (
+                current_retry < 10
+                or isinstance(exception, django.db.OperationalError)
+            )
+
+Dead letter
+-----------
+Expired or failed messages which should not be retried moved to dead letter queue.
+
++-------------------+------------------------+----------------------------------------------------+
+| Name              | Default                | Description                                        |
++===================+========================+====================================================+
+| dead_letter_queue | dead_letter + queue    | Queue name for dead letter messages.               |
++-------------------+------------------------+----------------------------------------------------+
+| dead_message_ttl  | 864000                 | Expiration **seconds**. Infinite if None.          |
++-------------------+------------------------+----------------------------------------------------+
+
+.. code-block:: python
+
+    # settings.py
+
+    CQRS = {
+        ...
+        'queue': 'example',
+        'replica': {
+            ...
+            'dead_letter_queue': 'dead_letter_example', # generates from CQRS.queue
+            'dead_message_ttl': 864000, # 10 days
+        },
+    }
+