Merge branch 'release/1.0.0'

praekeltfoundation · Jul 27, 2017 · 78d7ca6 · 78d7ca6
2 parents 3cfc475 + bea4d6e
commit 78d7ca6
Show file tree

Hide file tree

Showing 16 changed files with 923 additions and 161 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -6,6 +6,12 @@ cache:
   directories:
     - $HOME/.pip-cache/
 
+env:
+  - TZ=UTC
+  - TZ=US/Eastern
+  - TZ=Europe/Amsterdam
+  - TZ=Africa/Johannesburg
+
 services:
   - redis-server
 

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.1.0
+1.0.0
diff --git a/docs/index.rst b/docs/index.rst
@@ -37,19 +37,56 @@ Importing database files
 
    (ve)$ portia import porting-db path/to/file.csv
 
-Running the server
-------------------
+Running the web server
+======================
 
 ::
 
    (ve)$ portia run
+   2015-10-16 18:22:35+0200 [-] Log opened.
+   2015-10-16 18:22:35+0200 [-] Starting factory <txredisapi.RedisFactory instance at 0x105b3bea8>
+   2015-10-16 18:22:35+0200 [HiredisProtocol,client] Site starting on 8000
+   2015-10-16 18:22:35+0200 [-] Starting factory <twisted.web.server.Site instance at 0x105b6ef80>
+
+By default this will listen on ``localhost:8000``.
+
+Resolving
+---------
+
+Resolving an MNO can be done via the ``/resolve`` endpoint::
+
+   $ curl localhost:8000/resolve/27761234567
+   {
+      "entry": {
+        "ported-to-timestamp": "2015-10-16T19:26:41.943293",
+        "observed-network-timestamp": "2015-10-16T19:49:21.130930",
+        "ported-to": "CELLC",
+        "observed-network": "MTN"
+      },
+      "network": "MTN",
+      "strategy": "observed-network"
+    }
+
+The ``network`` key has the most likely network the MSISDN is homed on.
+The ``strategy`` is the strategy used to make that decision.
+The ``strategy`` is currently very naïve, it gets the most recent
+``observed-network`` or ``ported-to`` timestamp and returns that.
+
+If all else fails it falls back to guessing based on the prefix::
+
+   $ curl localhost:8000/resolve/27760000000
+   {
+     "entry": {},
+     "network": "VODACOM",
+     "strategy": "prefix-guess"
+   }
 
 Querying
 --------
 
 Looking up everything for a known phone number::
 
-   $ curl http://localhost:8000/lookup/27123456780
+   $ curl http://localhost:8000/entry/27123456780
    {
      "ported-to-timestamp": "2015-10-11T00:00:00",
      "ported-from": "MNO1",
@@ -59,7 +96,7 @@ Looking up everything for a known phone number::
 
 Looking up a single key for a phone number::
 
-   $ curl http://localhost:8000/lookup/27123456780/ported-to
+   $ curl http://localhost:8000/entry/27123456780/ported-to
    {
      "ported-to": "MNO2",
      "ported-to-timestamp": "2015-10-11T00:00:00"
@@ -77,10 +114,10 @@ Portia has a number of defined annotations that it supports, these are:
 
 Adding an observed network annotation for a phone number::
 
-   $ curl -XPUT -d MNO3 http://localhost:8000/annotate/27123456780/observed-network
+   $ curl -XPUT -d MNO3 http://localhost:8000/entry/27123456780/observed-network
    "MNO3"
 
-   $ curl http://localhost:8000/lookup/27123456780/observed-network
+   $ curl http://localhost:8000/entry/27123456780/observed-network
    {
      "ported-to": "MNO2",
      "ported-to-timestamp": "2015-10-11T00:00:00",
@@ -92,5 +129,58 @@ Adding an observed network annotation for a phone number::
 
 Custom annotations are allowed if the key is prefixed with ``X-``::
 
-   $ curl -XPUT -d bar http://localhost:8000/annotate/27123456780/X-foo
+   $ curl -XPUT -d bar http://localhost:8000/entry/27123456780/X-foo
    "bar"
+
+Running the TCP socket server
+=============================
+
+::
+
+   (ve)$ portia run --tcp
+   2015-10-16 18:22:51+0200 [-] Log opened.
+   2015-10-16 18:22:51+0200 [-] Starting factory <txredisapi.RedisFactory instance at 0x10a969ea8>
+   2015-10-16 18:22:51+0200 [HiredisProtocol,client] JsonProtocolFactory starting on 8001
+   2015-10-16 18:22:51+0200 [-] Starting factory <portia.protocol.JsonProtocolFactory instance at 0x10a99cf38>
+   2015-10-16 18:22:51+0200 [HiredisProtocol,client] Site starting on 8000
+   2015-10-16 18:22:51+0200 [-] Starting factory <twisted.web.server.Site instance at 0x10a9a03b0>
+
+By default this will listen on ``localhost:8001``. You can specify a different
+endpoint with ``--tcp-endpoint=tcp:8080:interface=127.0.0.1`` as an example
+
+JSON is used for the socket protocol. It uses ``\r\n`` as a delimiter
+
+.. note::   The timestamp values are all in ISO 8601 format. Timezone naive
+            timestamps are assumed to be in UTC and will be stored internally
+            as such.
+
+Get
+---
+
+::
+
+   $ telnet localhost 8001
+   > {"cmd": "get", "id": 1, "version": "0.1.0", "request": {"msisdn": "27761234567"}}
+   < {"status": "ok", "cmd": "reply", "version": "0.1.0", "reference_id": 1, "response": {"ported-to-timestamp": "2015-10-16T19:26:41.943293", "ported-to": "CELLC", "X-Foo-timestamp": "2015-10-19T18:37:36.294939", "observed-network": "MTN", "observed-network-timestamp": "2015-10-16T19:49:21.130930"}, "reference_cmd": "get"}
+
+Annotate
+--------
+
+::
+
+   $ telnet localhost 8001
+   > {"cmd": "annotate", "id": 2, "version": "0.1.0", "request": {"msisdn": "27761234567", "key": "X-Foo", "value": "bar"}}
+   < {"status": "ok", "cmd": "reply", "version": "0.1.0", "reference_id": 2, "response": "OK", "reference_cmd": "annotate"}
+
+   $ telnet localhost 8001
+   > {"cmd": "get", "id": 3, "version": "0.1.0", "request": {"msisdn": "27761234567"}}
+   < {"status": "ok", "cmd": "reply", "version": "0.1.0", "reference_id": 3, "response": {"ported-to-timestamp": "2015-10-16T19:26:41.943293", "ported-to": "CELLC", "X-Foo-timestamp": "2015-10-19T18:44:33.710381", "observed-network": "MTN", "X-Foo": "bar", "observed-network-timestamp": "2015-10-16T19:49:21.130930"}, "reference_cmd": "get"}
+
+Resolve
+-------
+
+::
+
+   $ telnet localhost 8001
+   > {"cmd": "resolve", "id": 4, "version": "0.1.0", "request": {"msisdn": "27761234567"}}
+   < {"status": "ok", "cmd": "reply", "version": "0.1.0", "reference_id": 4, "response": {"entry": {"ported-to-timestamp": "2015-10-16T19:26:41.943293", "ported-to": "CELLC", "X-Foo-timestamp": "2015-10-19T18:44:33.710381", "observed-network": "MTN", "X-Foo": "bar", "observed-network-timestamp": "2015-10-16T19:49:21.130930"}, "network": "MTN", "strategy": "observed-network"}, "reference_cmd": "resolve"}
diff --git a/portia/assets/mappings/NG.mapping.json b/portia/assets/mappings/NG.mapping.json
@@ -0,0 +1,73 @@
+{
+  "234": {
+    "23470": {
+      "234700": "ALPHA TECHNOLOGIES",
+      "234701": "AIRTEL",
+      "234702": {
+        "2347020": "SMILE",
+        "2347021": "NITEL",
+        "2347022": {
+          "23470221": "NITEL",
+          "23470222": "NITEL",
+          "23470223": "NITEL",
+          "23470224": "NITEL",
+          "23470225": "NITEL"
+        },
+        "2347023": "ZOOM",
+        "2347023": "PRESTEL",
+        "2347025": "VISAFONE",
+        "2347026": "VISAFONE",
+        "2347027": "MULTILINKS",
+        "2347028": "STARCOMMS",
+        "2347029": "STARCOMMS"
+      },
+      "234703": "MTN",
+      "234704": {
+        "2347041": "VISAFONE",
+        "2347042": "VISAFONE",
+        "2347043": "VISAFONE",
+        "2347044": "VISAFONE",
+        "2347045": "VISAFONE",
+        "2347046": "VISAFONE"
+      },
+      "234705": "GLO",
+      "234706": "MTN",
+      "234708": "AIRTEL",
+      "234709": "MULTILINKS"
+    },
+    "23480": {
+      "234800": "ALPHA TECHNOLOGIES",
+      "234801": {
+        "2348010": "MEGATECH",
+        "2348011": "MEGATECH"
+      },
+      "234802": "AIRTEL",
+      "234803": "MTN",
+      "234804": "MTEL",
+      "234805": "GLO",
+      "234806": "MTN",
+      "234807": "GLO",
+      "234808": "AIRTEL",
+      "234809": "ETISALAT"
+    },
+    "23481": {
+      "234810": "MTN",
+      "234811": "GLO",
+      "234812": "AIRTEL",
+      "234813": "MTN",
+      "234814": "MTN",
+      "234815": "GLO",
+      "234816": "MTN",
+      "234817": "ETISALAT",
+      "234818": "ETISALAT",
+      "234819": "STARCOMMS"
+    },
+    "23490": {
+      "234902": "AIRTEL",
+      "234903": "MTN",
+      "234905": "GLO",
+      "234908": "ETISALAT",
+      "234909": "ETISALAT"
+    }
+  }
+}
diff --git a/portia/assets/mappings/ZA.mapping.json b/portia/assets/mappings/ZA.mapping.json
@@ -0,0 +1,41 @@
+{
+  "27": {
+    "2771": {
+      "27710": "MTN",
+      "27711": "VODACOM",
+      "27712": "VODACOM",
+      "27713": "VODACOM",
+      "27714": "VODACOM",
+      "27715": "VODACOM",
+      "27716": "VODACOM",
+      "27717": "MTN",
+      "27719": "MTN"
+    },
+    "2772": "VODACOM",
+    "2773": "MTN",
+    "2774": {
+      "27740": "CELLC",
+      "27741": "VIRGIN",
+      "27742": "CELLC",
+      "27743": "CELLC",
+      "27744": "CELLC",
+      "27745": "CELLC",
+      "27746": "CELLC",
+      "27747": "CELLC",
+      "27748": "CELLC",
+      "27749": "CELLC"
+    },
+    "2776": "VODACOM",
+    "2778": "MTN",
+    "2779": "VODACOM",
+    "2781": {
+      "27811": "TELKOM",
+      "27812": "TELKOM",
+      "27813": "TELKOM",
+      "27814": "TELKOM"
+    },
+    "2782": "VODACOM",
+    "2783": "MTN",
+    "2784": "CELLC"
+  }
+}