.. ansar-create documentation master file, created by sphinx-quickstart on Tue April 18 16:07:56 2021. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. ############# ansar-connect ############# The **ansar-connect** library is for anyone developing networking software. That software might be a pair of client-server processes on a single host, a group of peer processes distributed around a LAN, or a large collection of processes distributed around the Internet. For the full range of potential target scenarios this library makes many aspects of networking easier while not compromising on sophistication. It also brings significant new capabilities. A few highlights of the feature list include; * uniform messaging across multiple processes, multiple hosts and the Internet, * built-in public key cryptography, * automated management of network addresses, * support for mutiple instances of a networking product on the same physical network, * clear, concise and sophisticated network messaging. Sending messages around networks is the core function of **ansar-connect**. It presents the simplest possible interface, accepting a message and a destination as arguments. It then discreetly takes care of technical issues such as marshaling, encoding, efficient network I/O and error handling. Refer to paragraphs below for a small but complete example of a client-server message exchange. With **ansar-connect** it is possible to exchange messages between your development site and a remote weather station, or between a customer site and their mobile vehicle fleet. All of this can be achieved with little or no network administration (e.g. changing firewalls), and without regard to LAN infrastructure or public network providers (e.g. cellular networks). The only requirements are a Python environment and Internet connectivity at each end. Encryption is as easy as enabling a flag when establishing a connection. A state-of-the-art `encryption library `_ is used to bring security to any selected area of your software. Motivated by initiatives such as `Zeroconf `_ **ansar-connect** can sidestep the need for management of port numbers by using ephemeral ports. Combined with other techniques this makes it possible to run multiple instances of the same complex networking product, side-by-side. This has perhaps the most obvious value in development and testing but can equally benefit areas such as sales and training. At the same time that this library extends the scope of networking, it never forgets how difficult the implementation and maintenance of networking software can be. Design goals included ease of use, code clarity and effective technical support. Installation ************ **ansar-connect** can be installed from PyPI using *pip*; .. code:: $ cd $ python3 -m venv .env $ source .env/bin/activate $ pip3 install ansar-connect Features ******** * Easy-to-use listen and connect, * fully automated sending and receiving of complex types (i.e. no marshaling or encoding), * direct support for arrays, vectors, sets, deques and maps, * support for user-defined types and enumerations, * a rich set of built-in types such as world time (i.e. datetime) and UUIDs, * support for graphs, e.g. linked lists and trees, * support for networking sessions, * support for networking FSMs, * support for multiple connections and multiple listens in a single process, * automated connection recovery with backoff and randomization, * extensive support for publish-subscribe networking. For serialization **ansar-connect** uses `ansar-encode `_, inheriting all the related data-handling sophistication from there. The `ansar-create `_ library is used for the internal asynchronous engine. Refer to the relevant documentation for details. .. note:: For a bare minimum demonstration of messaging across the Internet, refer to :ref:`this ` section. A Very Quick Taste ****************** **ansar-connect** has a broad and ambitious scope. At the same time it looks after the simplest networking ambitions with a clean interface and some nice automatic behaviour, the latter assisting with development and support activities. Under the hood all the capabilities of the library are based on the :func:`~.listen` and :func:`~.connect` pair of functions that appear in the following code samples. A traditional, bare-bones server looks like; .. code-block:: python import ansar.connect as ar def server(self): ar.listen(self, ar.HostPort('127.0.0.1', 50101)) m = self.select(ar.Listening, ar.NotListening, ar.Stop) if isinstance(m, ar.NotListening): return m elif isinstance(m, ar.Stop): return ar.Aborted() while True: m = self.select(ar.Enquiry, ar.Stop) if isinstance(m, ar.Stop): return ar.Aborted() self.reply(ar.Ack()) # Respond to the Enquiry message. ar.bind(server) if __name__ == '__main__': ar.create_object(server) Save this code in the file ``server.py`` and run it with the command; .. code-block:: $ python3 server.py --debug-level=DEBUG A control-c terminates the server when it is no longer needed. The matching client looks like this; .. code-block:: python import ansar.connect as ar def client(self): ar.connect(self, ar.HostPort('127.0.0.1', 50101)) m = self.select(ar.Connected, ar.NotConnected, ar.Stop) if isinstance(m, ar.NotConnected): return m elif isinstance(m, ar.Stop): return ar.Aborted() self.reply(ar.Enquiry()) # Respond to the Connected message. m = self.select(ar.Ack, ar.Unknown, ar.Stop, seconds=3.0) if isinstance(m, ar.Stop): return ar.Aborted() elif isinstance(m, ar.SelectTimer): return ar.TimedOut(m) return m ar.bind(client) if __name__ == '__main__': ar.create_object(client) Running the client (the omission of debugging is deliberate) looks like this; .. code-block:: $ python3 client.py Ack() There has been a successful exchange of :class:`~.lifecycle.Enquiry` and :class:`~.lifecycle.Ack` messages between the client and server processes. The :func:`~.create_object` library function places a simple text rendering of the return value from the ``client()`` object (i.e. ``m``) on stdout. More information relating to connection establishment and message transfer is available in the logs. The more curious may also attempt to run the client when the server is not active. Modifying the server to ignore the requests (i.e. comment out the :meth:`~.Point.reply` call) will elicit another example of automated error handling in the client. .. note:: The :class:`~.lifecycle.Enquiry` and :class:`~.lifecycle.Ack` messages are pre-registered in the library and used here to simplify the code fragments. You can find an example of how to register your own custom messages :ref:`here `. The ``client()`` and ``server()`` objects are defined as functions for ease of reading but could equally be implemented as finite state machines. For an example of this style of operation look :ref:`here `. If you are unfamiliar with, or curious about asynchronous programming, you can find a solution to the Dining Philosophers problem :ref:`here `. This solution also uses FSMs. Documentation ************* Documentation for **ansar-connect** covers three major areas. Part one is devoted to the traditional combination of :func:`~.listen` and :func:`~.connect` while the second part introduces the publish-subscribe model of networking. Further support for this model is provided in a series of guides. The remainder of the documentation is reference material, including internal design and implementation details that may be significant to users. .. toctree:: :maxdepth: 1 listening-and-connecting publish-and-subscribe-networking composite-applications high-tech-laboratory remote-weather-stations odds-and-ends http-integration multi-tenanted-networking design-and-implementation ansar-command-reference classes-and-functions .. only: html * :ref:`genindex` Author ****** The **ansar-connect** library was developed by Scott Woods (scott.18.ansar@gmail.com). The library has evolved under the influence of several large projects and more recently has moved from C++ to Python. License ******* The ``ansar-connect`` library is released under the `MIT License `_.