Metadata-Version: 2.1
Name: tcpnetlock
Version: 0.1.2
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
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

==========
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 `nc`

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.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


