From f71dd06175af1481bf62a566ca2740daf88ded05 Mon Sep 17 00:00:00 2001 From: Yann Bouteiller Date: Sat, 19 Nov 2022 23:03:10 -0500 Subject: [PATCH] Quickstart guide and customization of the reconnection behaviour --- README.md | 5 ++- docs/source/index.rst | 10 ++++- docs/source/quickstart.rst | 90 ++++++++++++++++++++++++++++++++++++++ setup.py | 4 +- tlspyo/api.py | 16 ++++++- tlspyo/client.py | 14 +++++- 6 files changed, 130 insertions(+), 9 deletions(-) create mode 100644 docs/source/quickstart.rst diff --git a/README.md b/README.md index 543386c..4765d73 100644 --- a/README.md +++ b/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 diff --git a/docs/source/index.rst b/docs/source/index.rst index d8058bb..fdef02a 100644 --- a/docs/source/index.rst +++ b/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: diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst new file mode 100644 index 0000000..bf3476d --- /dev/null +++ b/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 by the ip of the "server" machine): + +.. code-block:: bash + + python -m tlspyo --retrieve 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="", # replace 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 = ("", "", "<...>") # use group names of your choice + + my_endpoint = Endpoint( + ip_server='', # replace by the ip of your server machine + port=6667, + password="", # same password as the Relay + groups=groups, + local_com_port=free_port + ) + + target_groups = ("", "<...>") # 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``. \ No newline at end of file diff --git a/setup.py b/setup.py index dcd2c9e..257667d 100644 --- a/setup.py +++ b/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, diff --git a/tlspyo/api.py b/tlspyo/api.py index 1078ffb..15ff123 100644 --- a/tlspyo/api.py +++ b/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)) diff --git a/tlspyo/client.py b/tlspyo/client.py index efde915..844e6b7 100644 --- a/tlspyo/client.py +++ b/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): """