Issues/177: Fix a bug that prevented enquire_link and deliver_sm from been sent

CHANGELOG.md

@@ -2,6 +2,11 @@
 most recent version is listed first.
 
 
+## **version:** v0.7.4
+- Fix a bug that prevented `enquire_link` and `deliver_sm` from been sent: https://github.com/komuw/naz/pull/179  
+- Enforce `naz` message protocol in code : https://github.com/komuw/naz/pull/179
+
+
 ## **version:** v0.7.3
 - make `naz.SimpleCorrelater.delete_after_ttl()` private: https://github.com/komuw/naz/pull/172
 - rename `naz.broker.BaseOutboundQueue` to `naz.broker.BaseBroker`: https://github.com/komuw/naz/pull/174     

README.md

@@ -98,7 +98,7 @@ finally:
     loop.stop()
 ```
 **NB:**      
-(a) For more information about all the parameters that `naz.Client` can take, consult the [documentation here](https://github.com/komuw/naz/blob/master/documentation/config.md)            
+(a) For more information about all the parameters that `naz.Client` can take, consult the [documentation here](https://komuw.github.io/naz/client.html)            
 (b) More [examples can be found here](https://github.com/komuw/naz/tree/master/examples)         
 (c) if you need a SMSC server/gateway to test with, you can use the [docker-compose file in this repo](https://github.com/komuw/naz/blob/master/docker-compose.yml) to bring up an SMSC simulator.        
 That docker-compose file also has a redis and rabbitMQ container if you would like to use those as your broker.
@@ -130,8 +130,8 @@ class ExampleBroker(naz.broker.BaseBroker):
     def __init__(self):
         loop = asyncio.get_event_loop()
         self.queue = asyncio.Queue(maxsize=1000, loop=loop)
-    async def enqueue(self, item):
-        self.queue.put_nowait(item)
+    async def enqueue(self,  message):
+        self.queue.put_nowait(message)
     async def dequeue(self):
         return await self.queue.get()
 ```
@@ -152,7 +152,7 @@ run:
 ```              
 
 **NB:**      
-(a) For more information about the `naz` config file, consult the [documentation here](https://github.com/komuw/naz/blob/master/documentation/config.md)             
+(a) For more information about the `naz` config file, consult the [documentation here](https://komuw.github.io/naz/client.html)             
 (b) More [examples can be found here](https://github.com/komuw/naz/tree/master/examples). As an example, start the SMSC simulator(`docker-compose up`) then in another terminal run, `naz-cli --client examples.example_config.client`
 
 To see help:
@@ -337,18 +337,7 @@ cli = naz.Client(
 It's via a broker interface. Your application queues messages to a broker, `naz` consumes from that broker and then `naz` sends those messages to SMSC/server.       
 You can implement the broker mechanism any way you like, so long as it satisfies the `BaseBroker` interface as [defined here](https://github.com/komuw/naz/blob/master/naz/broker.py)             
 Your application should call that class's `enqueue` method to -you guessed it- enqueue messages to the queue while `naz` will call the class's `dequeue` method to consume from the broker.         
-Your application should enqueue a dictionary/json object with any parameters but the following are mandatory:              
-```bash
-{
-    "version": "1",
-    "smpp_command": naz.SmppCommand.SUBMIT_SM,
-    "short_message": string,
-    "log_id": string,
-    "source_addr": string,
-    "destination_addr": string
-}
-```  
-For more information about all the parameters that are needed in the enqueued json object, consult the [documentation here](https://github.com/komuw/naz/blob/master/documentation/config.md)      
+
 
 `naz` ships with a simple broker implementation called [`naz.broker.SimpleBroker`](https://github.com/komuw/naz/blob/master/naz/broker.py).                     
 An example of using that;

benchmarks/redis_broker.py

@@ -1,5 +1,4 @@
 import os
-import json
 import asyncio
 
 import naz
@@ -50,16 +49,16 @@ async def _get_redis(self):
         )
         return self._redis
 
-    async def enqueue(self, item):
+    async def enqueue(self, message: naz.protocol.Message) -> None:
         _redis = await self._get_redis()
-        await _redis.lpush(self.queue_name, json.dumps(item))
+        await _redis.lpush(self.queue_name, message.to_json())
 
-    async def dequeue(self):
+    async def dequeue(self) -> naz.protocol.Message:
         _redis = await self._get_redis()
         while True:
             item = await _redis.brpop(self.queue_name, timeout=self.timeout)
             if item:
-                dequed_item = json.loads(item[1].decode())
-                return dequed_item
+                dequed_item = item[1].decode()
+                return naz.protocol.Message.from_json(dequed_item)
             else:
                 await asyncio.sleep(5)

docs/_modules/index.html

@@ -8,7 +8,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
-  <title>Overview: module code &mdash; naz v0.7.3 documentation</title>
+  <title>Overview: module code &mdash; naz v0.7.4 documentation</title>
 
 
 
@@ -60,7 +60,7 @@
 
 
               <div class="version">
-                v0.7.3
+                v0.7.4
               </div>
 
 
@@ -90,6 +90,7 @@
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../client.html">Client</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../protocol.html">protocol</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../correlater.html">correlater</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../hooks.html">hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../nazcodec.html">nazcodec</a></li>
@@ -166,6 +167,7 @@ <h1>All modules for which code is available</h1>
 <li><a href="naz/hooks.html">naz.hooks</a></li>
 <li><a href="naz/log.html">naz.log</a></li>
 <li><a href="naz/nazcodec.html">naz.nazcodec</a></li>
+<li><a href="naz/protocol.html">naz.protocol</a></li>
 <li><a href="naz/ratelimiter.html">naz.ratelimiter</a></li>
 <li><a href="naz/sequence.html">naz.sequence</a></li>
 <li><a href="naz/state.html">naz.state</a></li>

docs/_modules/naz/broker.html

@@ -8,7 +8,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
-  <title>naz.broker &mdash; naz v0.7.3 documentation</title>
+  <title>naz.broker &mdash; naz v0.7.4 documentation</title>
 
 
 
@@ -60,7 +60,7 @@
 
 
               <div class="version">
-                v0.7.3
+                v0.7.4
               </div>
 
 
@@ -90,6 +90,7 @@
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../../client.html">Client</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../protocol.html">protocol</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../correlater.html">correlater</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../hooks.html">hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../nazcodec.html">nazcodec</a></li>
@@ -164,7 +165,8 @@
   <h1>Source code for naz.broker</h1><div class="highlight"><pre>
 <span></span><span class="kn">import</span> <span class="nn">abc</span>
 <span class="kn">import</span> <span class="nn">asyncio</span>
-<span class="kn">import</span> <span class="nn">typing</span>
+
+<span class="kn">from</span> <span class="nn">.</span> <span class="k">import</span> <span class="n">protocol</span>
 
 
 <div class="viewcode-block" id="BaseBroker"><a class="viewcode-back" href="../../broker.html#naz.broker.BaseBroker">[docs]</a><span class="k">class</span> <span class="nc">BaseBroker</span><span class="p">(</span><span class="n">abc</span><span class="o">.</span><span class="n">ABC</span><span class="p">):</span>
@@ -177,22 +179,28 @@ <h1>Source code for naz.broker</h1><div class="highlight"><pre>
 <span class="sd">    &quot;&quot;&quot;</span>
 
 <div class="viewcode-block" id="BaseBroker.enqueue"><a class="viewcode-back" href="../../broker.html#naz.broker.BaseBroker.enqueue">[docs]</a>    <span class="nd">@abc</span><span class="o">.</span><span class="n">abstractmethod</span>
-    <span class="k">async</span> <span class="k">def</span> <span class="nf">enqueue</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">item</span><span class="p">:</span> <span class="nb">dict</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
+    <span class="k">async</span> <span class="k">def</span> <span class="nf">enqueue</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message</span><span class="p">:</span> <span class="n">protocol</span><span class="o">.</span><span class="n">Message</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
         <span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        enqueue/save an item.</span>
 
 <span class="sd">        Parameters:</span>
 <span class="sd">            item: The item to be enqueued/saved</span>
+<span class="sd">                  The item/message is a `naz.protocol.Message` class instance;</span>
+<span class="sd">                  It is up to the broker implementation to do the serialization(if neccesary) in order to be able to store it.</span>
+<span class="sd">                  `naz.protocol.Message` has a `to_json()` method that you can use to serialize a `naz.protocol.Message` class instance into json.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="k">raise</span> <span class="ne">NotImplementedError</span><span class="p">(</span><span class="s2">&quot;enqueue method must be implemented.&quot;</span><span class="p">)</span></div>
 
 <div class="viewcode-block" id="BaseBroker.dequeue"><a class="viewcode-back" href="../../broker.html#naz.broker.BaseBroker.dequeue">[docs]</a>    <span class="nd">@abc</span><span class="o">.</span><span class="n">abstractmethod</span>
-    <span class="k">async</span> <span class="k">def</span> <span class="nf">dequeue</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">typing</span><span class="o">.</span><span class="n">Dict</span><span class="p">[</span><span class="n">typing</span><span class="o">.</span><span class="n">Any</span><span class="p">,</span> <span class="n">typing</span><span class="o">.</span><span class="n">Any</span><span class="p">]:</span>
+    <span class="k">async</span> <span class="k">def</span> <span class="nf">dequeue</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">protocol</span><span class="o">.</span><span class="n">Message</span><span class="p">:</span>
         <span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        dequeue an item.</span>
 
 <span class="sd">        Returns:</span>
-<span class="sd">            item that was dequeued</span>
+<span class="sd">            item that was dequeued.</span>
+<span class="sd">            The item has to be returned as a `naz.protocol.Message` class instance.</span>
+<span class="sd">            It is up to the broker implementation to do the de-serialization(if neccesary).</span>
+<span class="sd">            `naz.protocol.Message` has a `from_json()` method that you can use to de-serialize a json string into `naz.protocol.Message` class instance.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="k">raise</span> <span class="ne">NotImplementedError</span><span class="p">(</span><span class="s2">&quot;dequeue method must be implemented.&quot;</span><span class="p">)</span></div></div>
 
@@ -215,10 +223,10 @@ <h1>Source code for naz.broker</h1><div class="highlight"><pre>
             <span class="p">)</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">queue</span><span class="p">:</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">queues</span><span class="o">.</span><span class="n">Queue</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">Queue</span><span class="p">(</span><span class="n">maxsize</span><span class="o">=</span><span class="n">maxsize</span><span class="p">)</span></div>
 
-<div class="viewcode-block" id="SimpleBroker.enqueue"><a class="viewcode-back" href="../../broker.html#naz.broker.SimpleBroker.enqueue">[docs]</a>    <span class="k">async</span> <span class="k">def</span> <span class="nf">enqueue</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">item</span><span class="p">:</span> <span class="nb">dict</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">queue</span><span class="o">.</span><span class="n">put_nowait</span><span class="p">(</span><span class="n">item</span><span class="p">)</span></div>
+<div class="viewcode-block" id="SimpleBroker.enqueue"><a class="viewcode-back" href="../../broker.html#naz.broker.SimpleBroker.enqueue">[docs]</a>    <span class="k">async</span> <span class="k">def</span> <span class="nf">enqueue</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message</span><span class="p">:</span> <span class="n">protocol</span><span class="o">.</span><span class="n">Message</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">queue</span><span class="o">.</span><span class="n">put_nowait</span><span class="p">(</span><span class="n">message</span><span class="p">)</span></div>
 
-<div class="viewcode-block" id="SimpleBroker.dequeue"><a class="viewcode-back" href="../../broker.html#naz.broker.SimpleBroker.dequeue">[docs]</a>    <span class="k">async</span> <span class="k">def</span> <span class="nf">dequeue</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">typing</span><span class="o">.</span><span class="n">Dict</span><span class="p">[</span><span class="n">typing</span><span class="o">.</span><span class="n">Any</span><span class="p">,</span> <span class="n">typing</span><span class="o">.</span><span class="n">Any</span><span class="p">]:</span>
+<div class="viewcode-block" id="SimpleBroker.dequeue"><a class="viewcode-back" href="../../broker.html#naz.broker.SimpleBroker.dequeue">[docs]</a>    <span class="k">async</span> <span class="k">def</span> <span class="nf">dequeue</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">protocol</span><span class="o">.</span><span class="n">Message</span><span class="p">:</span>
         <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">queue</span><span class="o">.</span><span class="n">get</span><span class="p">()</span></div></div>
 </pre></div>