Quickstart guide and customization of the reconnection behaviour

README.md

@@ -2,11 +2,12 @@
 
 :computer: :globe_with_meridians: :computer:
 
-**A library for secure transfer of python objects over network.**
+**A library for easy and secure transfer of python objects over network.**
 
 [![Python package](https://github.com/MISTLab/tls-python-object/actions/workflows/python-package.yml/badge.svg)](https://github.com/MISTLab/tls-python-object/actions/workflows/python-package.yml)
 [![Documentation Status](https://readthedocs.org/projects/tlspyo/badge/?version=latest)](https://tlspyo.readthedocs.io/en/latest/?badge=latest)
 
+:rocket: [Quickstart guide and API documentation](https://tlspyo.readthedocs.io/en/latest/)
 
 `tlspyo` provides a simple API to transfer python objects in a robust and safe way via [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security), between several machines (and/or processes) called `Endpoints`.
 
@@ -19,6 +20,7 @@
 
 ## Quick links
 
+- [Documentation](https://tlspyo.readthedocs.io/en/latest/)
 - [Principle](#principle)
 - [Example usage](#example-usage)
 - [Getting started](#getting-started)
@@ -27,7 +29,6 @@
   - [Producer-consumer example](#a-simple-producer-consumer-example)
 - [Security](#security)
 - [Custom serialization](#custom-serialization)
-- [API documentation](https://tlspyo.readthedocs.io/en/latest/)
 
 
 ## Principle

docs/source/index.rst

@@ -6,8 +6,7 @@ Welcome to the ``tlspyo`` API documentation!
 
 ``tlspyo`` enables easy and secure transfer of python objects over your network.
 
-This documentation is useful for advanced usage.
-If you are discovering ``tlspyo``, you will find an introduction on the project's `GitHub page`_.
+If you are discovering ``tlspyo``, follow the Quickstart guide, or find a more detailed introduction on the project's `GitHub page`_.
 
 .. _`GitHub page`: https://github.com/MISTLab/tls-python-object
 
@@ -20,6 +19,13 @@ In common applications, there are only two classes you need to use: ``Relay`` an
 These classes are defined in the ``tlspyo.api`` module.
 
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Quickstart:
+
+   quickstart
+
+
 .. toctree::
    :maxdepth: 1
    :caption: Getting started:

docs/source/quickstart.rst

@@ -0,0 +1,90 @@
+TLSPYO in 5 minutes
+===================
+
+*(Note: You can do everything on a single machine by using ip_server="127.0.0.1")*
+
+On all your machines:
+---------------------
+
+* Install ``tlspyo`` (preferably using the same version of python everywhere):
+
+.. code-block:: bash
+
+   pip install tlspyo
+
+On your "server" machine:
+-------------------------
+
+* If your other machines are not in the same network, route port 7776 to this machine.
+* Generate TLS credentials and broadcast your public certificate via TCP (port 7776 is used by default):
+
+.. code-block:: bash
+
+   python -m tlspyo --generate --broadcast
+
+On all your "client" machines:
+------------------------------
+
+* Retrieve your public TLS certificate (via TCP, using port 7776 by default; please replace <server ip> by the ip of the "server" machine):
+
+.. code-block:: bash
+
+   python -m tlspyo --retrieve ip=<server ip>
+
+On your "server" machine:
+-------------------------
+
+* Close the TLS certificate broadcasting server (e.g., close the terminal).
+* Create a ``tlspyo Relay`` in a python script (adapt and execute this script):
+
+.. code-block:: python
+
+   from tlspyo import Relay
+   import time
+
+   if __name__=="__main__":
+
+       my_relay = Relay(
+            port=6667,
+            password="<password>",  # replace <password> by a strong password of your choice
+            local_com_port=3001
+       )
+       while True:
+           time.sleep(1.0)
+
+On your "client" machines:
+--------------------------
+
+* Create a ``tlspyo Endpoint`` that sends and receive objects from a python script (adapt and execute this script):
+
+.. code-block:: python
+
+   from tlspyo import Endpoint
+   import time
+
+   if __name__=="__main__":
+
+       free_port = 3002  # adapt this if you use several Endpoints on the same machine
+       groups = ("<group1>", "<group2>", "<...>")  # use group names of your choice
+
+       my_endpoint = Endpoint(
+       ip_server='<ip server>', # replace <ip server> by the ip of your server machine
+       port=6667,
+       password="<password>",  # same password as the Relay
+       groups=groups,
+       local_com_port=free_port
+       )
+
+       target_groups = ("<group1>", "<...>")  # replace by group names of your choice
+       my_object = f"This object is for groups {target_groups}"
+
+       my_endpoint.send_object(obj=my_object, destination=target_groups)
+
+       while True:
+           received_list = my_endpoint.receive_all(blocking=True)
+           print(f"I am an Endpoint of groups {groups}, I received {received_list}")
+
+On your chair:
+--------------
+
+* Contemplatively watch your ``Endpoints`` transfer your python objects to each other via your ``Relay``.

setup.py

@@ -14,8 +14,8 @@
 
 setup(name='tlspyo',
       packages=[package for package in find_packages()],
-      version='0.2.1',
-      download_url='https://github.com/MISTLab/tls-python-object/archive/refs/tags/v0.2.1.tar.gz',
+      version='0.2.2',
+      download_url='https://github.com/MISTLab/tls-python-object/archive/refs/tags/v0.2.2.tar.gz',
       license='MIT',
       description='Secure transport of python objects using TLS encryption',
       long_description=long_description,

tlspyo/api.py

@@ -128,7 +128,11 @@ def __init__(self,
                  keys_dir: str = None,
                  hostname: str = "default",
                  serializer=None,
-                 deserializer=None):
+                 deserializer=None,
+                 recon_max_delay=60.0,
+                 recon_initial_delay=10.0,
+                 recon_factor=1.5,
+                 recon_jitter=0.1):
         """
         ``tlspyo`` Endpoint.
 
@@ -148,6 +152,10 @@ def __init__(self,
                 None disables TLS, do not use None on a public network unless you know what you are doing!
             serializer (callable): custom serializer that outputs a bytestring from a python object
             deserializer (callable): custom deserializer that outputs a python object from a bytestring
+            recon_max_delay (float): in case of network failure, maximum delay between reconnection attempts
+            recon_initial_delay (float): in case of network failure, initial delay between reconnection attempts
+            recon_factor (float): in case of network failure, delay will increase by this factor between attempts
+            recon_jitter (float): in case of network failure, jitter factor of the delay between attempts
         """
 
         assert security in (None, "TLS"), f"Unsupported security: {security}"
@@ -187,7 +195,11 @@ def __init__(self,
                               header_size=header_size,
                               security=security,
                               keys_dir=keys_dir,
-                              hostname=hostname)
+                              hostname=hostname,
+                              recon_max_delay=recon_max_delay,
+                              recon_initial_delay=recon_initial_delay,
+                              recon_factor=recon_factor,
+                              recon_jitter=recon_jitter)
 
         # start local server and Twisted process
         self._local_com_srv.bind(('127.0.0.1', self._local_com_port))

tlspyo/client.py

@@ -101,6 +101,10 @@ def __init__(self, client):
         self._groups = client.groups
         self._header_size = client.header_size
         self._client = client
+        self.maxDelay = self._client.recon_max_delay
+        self.initialDelay = self._client.recon_initial_delay
+        self.factor = self._client.recon_factor
+        self.jitter = self._client.recon_jitter
 
     def startedConnecting(self, connector):
         logger.info('Started to connect.')
@@ -134,7 +138,11 @@ def __init__(self,
                  local_com_port=2097,
                  security="TLS",
                  keys_dir=None,
-                 hostname='default'):
+                 hostname='default',
+                 recon_max_delay=60.0,
+                 recon_initial_delay=10.0,
+                 recon_factor=1.5,
+                 recon_jitter=0.1):
 
         self.serializer = serializer
         self.deserializer = deserializer
@@ -154,6 +162,10 @@ def __init__(self,
         self._security = security
         self._keys_dir = keys_dir
         self._hostname = hostname
+        self.recon_max_delay = recon_max_delay
+        self.recon_initial_delay = recon_initial_delay
+        self.recon_factor = recon_factor
+        self.recon_jitter = recon_jitter
 
     def run(self):
         """