PM #19 - Use http.HTTPStatus for interacting with a remote server (#20)

docs/sources/changelog.rst

@@ -2,6 +2,9 @@
 Changelog
 =========
 
+* :release:`1.3.0 <2020-05-12>`
+* :feature:`19` Normalized http codes used for sending metrics to a remote server.
+
 * :release:`1.2.0 <2020-04-17>`
 * :feature:`13` Change default analysis scope to function.
 * :bug:`12 major` No execution contexts pushed when using a remote server.

docs/sources/index.rst

@@ -16,6 +16,7 @@ Contents:
    configuration
    run
    exploitation
+   remote
    contributing 
    changelog
 

docs/sources/remote.rst

@@ -0,0 +1,121 @@
+Use of a remote server
+======================
+
+You can easily send your metrics to a remote server. This can turn usefull when it comes to running
+tests in parallel with plugins such as *pytest-xdist* of *pytest-parallel*.
+To do so, instruct pytest with the remote server address to use:
+
+.. code-block:: shell
+
+   bash $> pytest --remote myremote.server.net:port 
+
+This way, *pytest-monitor* will automatically send and query the remote server as soon as it gets
+a need.  Note that *pytest-monitor* will revert to a normal behaviour if:
+
+- it cannot query the context or the session for existence
+- it cannot create a new context or a new session
+
+
+Implementing a remote server
+============================
+
+How pytest-monitor interacts with a remote server
+-------------------------------------------------
+
+The following sequence is used by *pytest-monitor* when using a remote server:
+
+1. Ask the remote server if the **Execution Context** is known.
+2. Insert the **Execution Context** if the server knows nothing about it.
+3. Ask the remote server if the **Session** is known.
+4. Insert the **Session** if the server knows nothing about it.
+5. Insert results once measures have been collected.
+
+Used HTTP codes
+---------------
+Two codes are used by *pytest-monitor* when asked to work with a remote server:
+
+- 200 (OK) is used to indicate that a query has led to a non-empty result.
+- 201 (CREATED) is expected by *pytest-monitor** when sending a new entry (**Execution Context**, **Session** or any **Metric**).
+- 204 (NO CONTENT) though not checked explicitely should be returned when a request leads to no results.
+
+Mandatory routes
+----------------
+The following routes are expected to be reachable:
+
+GET /contexts/<str:hash>
+
+    Query the system for a **Execution Context** with the given hash.
+
+    **Return Codes**: Must return *200* (*OK*) if the **Execution Context** exists, *204* (*NO CONTENT*) otherwise
+
+GET /sessions/<str:hash>
+
+    Query the system for a **Session** with the given hash.
+
+    **Return Codes**: Must return *200* (*OK*) if the **Session** exists, *204* (*NO CONTENT*) otherwise
+
+POST /contexts/
+
+    Request the system to create a new entry for the given **Execution Context**.
+    Data are sent using Json parameters:
+
+    .. code-block:: json
+
+        {
+            cpu_count: int, 
+            cpu_frequency: int, 
+            cpu_type: str, 
+            cpu_vendor: str, 
+            ram_tota: int,
+            machine_node: str, 
+            machine_type: str, 
+            machine_arch: str, 
+            system_info: str, 
+            python_info: str, 
+            h: str
+        }
+
+    **Return Codes**: Must return *201* (*CREATED*) if the **Execution Context** has been created
+
+
+POST /sessions/
+
+    Request the system to create a new entry for the given **Session**.
+    Data are sent using Json parameters:
+
+    .. code-block:: json
+       
+       {
+           session_h: str,
+           run_date: str,
+           scm_ref: str,
+           description: str
+       }
+
+    **Return Codes**: Must return *201* (*CREATED*) if the **Session** has been created
+
+POST /metrics/
+
+    Request the system to create a new **Metrics** entry. 
+    Data are sent using Json parameters:
+
+    .. code-block:: json
+
+        {
+            session_h: str, 
+            context_h: str, 
+            item_start_time: str,
+            item_path: str,
+            item: str,
+            item_variant: str,
+            item_fs_loc: str,
+            kind: str, 
+            component: str,
+            total_time: float,
+            user_time: float,
+            kernel_time: float,
+            cpu_usage: float,
+            mem_usage: float
+        }
+
+    **Return Codes**: Must return *201* (*CREATED*) if the **Metrics** has been created

pytest_monitor/session.py

@@ -1,3 +1,5 @@
+from http import HTTPStatus
+
 import datetime
 import hashlib
 import json
@@ -44,7 +46,7 @@ def get_env_id(self, env):
         if self.__remote:
             r = requests.get(f'{self.__remote}/contexts/{env.hash()}')
             remote = None
-            if r.status_code == 200:
+            if r.status_code == HTTPStatus.OK:
                 remote = json.loads(r.text)
                 if remote['contexts']:
                     remote = remote['contexts'][0]['h']
@@ -71,7 +73,7 @@ def compute_info(self, description):
                                         run_date=run_date,
                                         scm_ref=scm,
                                         description=description))
-            if r.status_code != 200:
+            if r.status_code != HTTPStatus.CREATED:
                 self.__remote = ''
                 msg = f"Cannot insert session in remote monitor server ({r.status_code})! Deactivating...')"
                 warnings.warn(msg)
@@ -85,7 +87,7 @@ def set_environment_info(self, env):
         if self.__remote and remote_id is None:
             # We must postpone that to be run at the end of the pytest session.
             r = requests.post(f'{self.__remote}/contexts/', json=env.to_dict())
-            if r.status_code != 200:
+            if r.status_code != HTTPStatus.CREATED:
                 warnings.warn(f'Cannot insert execution context in remote server (rc={r.status_code}! Deactivating...')
                 self.__remote = ''
             else:
@@ -129,7 +131,7 @@ def add_test_info(self, item, item_path, item_variant, item_loc, kind, component
                                         kernel_time=kernel_time,
                                         cpu_usage=cpu_usage,
                                         mem_usage=mem_usage))
-            if r.status_code != 200:
+            if r.status_code != HTTPStatus.CREATED:
                 self.__remote = ''
                 msg = f"Cannot insert values in remote monitor server ({r.status_code})! Deactivating...')"
                 warnings.warn(msg)