Metadata-Version: 1.1
Name: tcpnetlock
Version: 0.1.4
Summary: Network lock based on TCP sockets
Home-page: https://github.com/hgdeoro/tcpnetlock
Author: Horacio G. de Oro
Author-email: hgdeoro@gmail.com
License: GNU General Public License v3
Description: ==========
        TcpNetLock
        ==========
        
        
        .. image:: https://img.shields.io/pypi/v/tcpnetlock.svg
                :target: https://pypi.python.org/pypi/tcpnetlock
        
        .. image:: https://img.shields.io/travis/hgdeoro/tcpnetlock.svg
                :target: https://travis-ci.org/hgdeoro/tcpnetlock
        
        .. image:: https://readthedocs.org/projects/tcpnetlock/badge/?version=latest
                :target: https://tcpnetlock.readthedocs.io/en/latest/?badge=latest
                :alt: Documentation Status
        
        
        .. image:: https://pyup.io/repos/github/hgdeoro/tcpnetlock/shield.svg
             :target: https://pyup.io/repos/github/hgdeoro/tcpnetlock/
             :alt: Updates
        
        
        
        Network lock based on TCP sockets
        
        
        * Free software: GNU General Public License v3
        * Documentation: https://tcpnetlock.readthedocs.io.
        
        
        Why?
        ----
        
        While deploying applications to Kubernetes, I needed a way to make sure that
        some potential concurrent, distributed actions, are not executed concurrently.
        For example:
        
         * database migrations: just one Pod in the Kubernetes cluster should be able to apply the database migrations
         * for batch jobs, different workers could be working on the same resource, this can be avoided with this lock mechanism
        
        Of course, Zookeeper is a MUCH BETTER solution, but that's too much for my use cases...
        
        How it works
        ------------
        
        Assuming the server is running on localhost, let's get a lock using telnet::
        
            $ telnet localhost 7654
            Trying 127.0.0.1...
            Connected to localhost.
            Escape character is '^]'.
        
        To try to acquire a lock, send::
        
            lock,name:django-migrations
        
        Server responds with::
        
            ok
        
        From that point, and while the TCP connection is open, you have the lock.
        
        If you try the same in a different terminal, you will get::
        
            $ telnet localhost 7654
            Trying 127.0.0.1...
            Connected to localhost.
            Escape character is '^]'.
            lock,name:django-migrations        <= you write
            not-granted                        <= server response
            Connection closed by foreign host. <= server closed the connection
        
        Here the server responded with **not-granted** and closed the TCP connection. The lock was not granted to you.
        
        But, in real-life scenarios, you would use the provided utility **tcpnetlock_do**::
        
            $ tcpnetlock_do --lock-name django-migrations -- python manage.py migrate
        
        To test it, you will need the server running. To get the server running with Docker, just run::
        
            $ docker pull hgdeoro/tcpnetlock
            $ docker run -ti --rm -p 7654:7654 hgdeoro/tcpnetlock
        
        Alternatively, you can install the package in a virtualenv and launch the server::
        
            $ virtualenv -p python3.6 venv
            $ source venv/bin/activate
            $ pip install tcpnetlock
            $ tcpnetlock_server --info
            INFO:root:Started server listening on localhost:7654
        
        
        Features
        --------
        
        * Runs on Python 3.6 / Python 3.5
        * Do not require external libraries
        * Ready to use Docker image (based on Alpine)
        * Includes server and python client
        * Includes utility to run Linux commands while holding the lock
        * Simple protocol: you can get a lock even with *netcat*
        
        Appendix: netcat
        ----------------
        
        Since the protocol is just text over a TCP connection, you can get a lock just writing the
        right text overt the TCP connection and leaving that TCP connection open, and that's the default
        behaviour of netcat::
        
            $ echo 'lock,name:LOCK_NAME' | nc localhost 7654
        
        The first line uses netcat to open the TCP connection and tries to get the lock.
        
        The biggest problem would be to READ the response to the server (will be one of 'ok' or 'not-granted') while
        send `nc` to the background. We can use a `fifo` for that::
        
            $ echo 'lock,name:LOCK_NAME' | nc -v localhost 7654 | tee /tmp/.tcpnetlock &
            $ result=$(head -n 1 /tmp/.tcpnetlock)
        
        Even though this works, using one of the two existing python clients (`tnl_client` and `tnl_do`) would be much better.
        
        
        Credits
        -------
        
        This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
        
        .. _Cookiecutter: https://github.com/audreyr/cookiecutter
        .. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
        
        
        =======
        History
        =======
        
        0.1.4 (2018-06-26)
        ------------------
        
        * Implements retries for cli tnl_do
        
        
        0.1.3 (2018-06-22)
        ------------------
        
        * Server logs granted lock
        * Add description to CLI
        * Client use environment variables for host/port
        * Add __str__ to Action to have better logs in server
        
        0.1.2 (2018-06-21)
        ------------------
        
        * Update client & server to handle errors in a better way
        * Add tests
        * Update docs
        
        0.1.1 (2018-06-20)
        ------------------
        
        * Add .bashrc (for developers)
        * Fix setup.py
        
        0.1.0 (2018-06-19)
        ------------------
        
        * Docker start server with --info by default
        * Adds cloudbuild.yaml to facilitate building in GCP
        * Change in protocol to detect unintended uses
        * Detect invalid requests and always send response to client
        * BIG refactor of server and client classes
        * Add lot of tests (current coverage: 99%)
        
        
        0.0.8 (2018-06-18)
        ------------------
        
        * Refactor messy code from server, client and cli
        
        
        0.0.7 (2018-06-17)
        ------------------
        
        * Code cleanup and refactor
        * Add tests
        * Implements run_with_lock script to make really easy to use from shell scripts
        
        0.0.6 (2018-06-16)
        ------------------
        
        * Create shell script to be sourced, to facilitate use of tcpnetlock from shell scripts
        
        0.0.5 (2018-06-15)
        ------------------
        
        * Update CONTRIBUTING (documents commands for the full release process)
        * Disable upload to pypi from Travis-CI
        
        0.0.4 (2018-06-15)
        ------------------
        
        * Encapsulate Lock, adds client id and timestamp
        * Implement sending of keepalive from client
        * Remove use of 'click'
        * Start server from cli with configurable parameters (listen address, port, etc)
        * Use client id to identify who has the lock
        
        0.0.3 (2018-06-15)
        ------------------
        
        * Validate lock name in server
        * FIX client to handle RESPONSE_ERR response
        * Add unittests
        * Refactor locks into server class
        * Use threading for test server
        * Make code compatible with Python 3.5
        
        0.0.2 (2018-06-15)
        ------------------
        
        * Implements RELEASE of locks
        * FIX release of lock when client closes the connection
        * Validates lock name
        * Code refactoring
        
        0.0.1 (2018-06-15)
        ------------------
        
        * Add files from cookiecutter-pypackage
        * Migrate test cases to pytest
        
Keywords: tcpnetlock
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
