python: implement IoT3 Core SDK

[ymorin-orange]

---

Features;

• Implement IoT3 Core SDK:
  • MQTT client
  • OpenTelemetry client
  • telemetry sent for MQTT messages

Closes: #123
Closes: #122

---

How to test

1. Prepare an OpenTelemetry collector on localhost:

   $ docker container run \
       --rm \
       -p 16686:16686 \
       -p 4318:4318 \
       jaegertracing/all-in-one:1.58
   

   then open a browser on the Jaegger UI:

   http://localhost:16686/
   

2. Prepare an MQTT broker on localhost (adapt based on your distribution):

   $ sudo systemctl start mosquitto.service

   and then start an MQTT client to dump the messages on the broker:

   $ mosquitto_sub -V 5 -t '#' -F '%j' |jq .
   

3. Test IoT3 Core SDK:
   1. start an environment with python 3.11:

      $ docker container run \
          --rm \
          -ti \
          --network host \
          -e http_proxy \
          -e https_proxy \
          -e no_proxy \
          --user $(id -u):$(id -u) \
          --mount type=bind,source=$(pwd),destination=$(pwd) \
          --workdir $(pwd) \
          --entrypoint /bin/bash \
          python:3.11.9-slim-bookworm

   2. create a /venv/ in a writable location, and activate it:

      (docker) python3 -m venv /tmp/iot3
      (docker) . /tmp/iot3/bin/activate

   3. install the IoT3 Core SDK (notice the trailing dot .):

      (docker) pip3 --disable-pip-version-check install .

   4. Run the MQTT-only test:

      (docker) ./tests/test-iot3-core-mqtt

   5. Run the OpenTelemetry-only test:

      (docker) ./tests/test-iot3-core-otel

      then, in Jaegger, search for the traces for the test-service
      service.
   6. Run the MQTT with OpenTelemetry test:

      (docker) ./tests/test-iot3-core-all

      then, in Jaegger, search for the traces for the test-service
      service.
   7. Run the simple API test:

      (docker) ./tests/test-iot3-core

      then, in Jaegger, search for the traces for the my-service
      service.

---

Expected results:

1. The Jaegger UI is displayed in your browser
2. The mosquitto server is running
3. The IoT3 Core SDK works;
   1. the docker container runs
   2. the python /venv/ is created and activated
   3. the IoT3 Core SDK is installed
   4. the MQTT message is dumped by /mosquitto_sub/:

      {
        "tst": "2024-07-31T13:27:08.106723Z+0200",
        "topic": "foo/bar",
        "qos": 0,
        "retain": 0,
        "payloadlen": 5,
        "payload": "pouet"
      }

   5. the Jaegger UI finds two traces:
      • one with 6 spans, of which the last one is in error, reporting /Some failure/
      • one with a single span, which has a link to the root span
        of the first trace, above
   6. the MQTT message is dumped by /mosquitto_sub/:

      {
        "tst": "2024-07-31T13:42:33.339973Z+0200",
        "topic": "foo/bar/passed",
        "qos": 0,
        "retain": 0,
        "payloadlen": 6,
        "properties": {
          "user-properties": {
            "traceparent": "00-cb2e0b60496eca82dfb9420006759aff-ec4169b906b4a5cd-00"
          }
        },
        "payload": "passed"
      }

      then Jaegger UI finds three new traces, all with a single span:
      • the first is for the failed publish, and has a span:
        • of kind producer
        • with attributes:
          • test.iot3.core.mqtt.action=publish
          • test.iot3.core.mqtt.topic=foo/bar/dropped
        • with an error status reporting /The client is not currently connected./
      • the second is for the sucessful publish, and has a span:
        • of kind producer
        • with attributes:
          • test.iot3.core.mqtt.action=publish
          • test.iot3.core.mqtt.topic=foo/bar/passed
        • with an unset status
      • the third is for the receive, and has a span:
        • of kind consumer
        • with attributes:
          • test.iot3.core.mqtt.action=receive
          • test.iot3.core.mqtt.topic=foo/bar/passed
        • with an unset status
        • with a link to the span of the second trace, above
   7. the results are similar to those of step 6, above

[ymorin-orange]

• rebased on top of master after the merge of [its_quadkeys] Failure when trying to do .neighbours() on a "north-limit" quadkey #147
• really use zlib.compress() instead of gzip.compress()

[ymorin-orange]

See #149 for examples on how it can get used in our own applications (to be merged after).

[ymorin-orange]

Updated to account for black reformatting.

Bizarrely enough, black in the workflows did not catrch the issues, but it was caught locally... :-/

[tigroo]

tests ok:

(kvmk8371) kvmk8371@yd-89lzhs3:~/Workspace/its-client$ mosquitto_sub -V 5 -t '#' -F '%j' |jq .
{
  "tst": "2024-08-30T18:45:10.699818Z+0200",
  "topic": "foo/bar",
  "qos": 0,
  "retain": 0,
  "payloadlen": 5,
  "payload": "pouet"
}
{
  "tst": "2024-08-30T18:52:23.298143Z+0200",
  "topic": "foo/bar/passed",
  "qos": 0,
  "retain": 0,
  "payloadlen": 6,
  "properties": {
    "user-properties": {
      "traceparent": "00-7c3105bbd6f4b319c26da241e575359e-44e7dd9181bb0566-00"
    }
  },
  "payload": "passed"
}

[tigroo]

code ok, tests ok