initial commit

.coveragerc

@@ -0,0 +1,4 @@
+# -*- mode: ini -*-
+# vim: set ft=ini
+[run]
+source = src/proxenos

.editorconfig

@@ -0,0 +1,22 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{bat,cmd,ps1}]
+end_of_line = crlf
+
+[*.{ini,py,rst,yml}]
+indent_style = space
+
+[*.{json,py,rst}]
+indent_size = 4
+
+[*.{cfg,ini,rst,yml}]
+indent_size = 2
+
+[{Makefile,**.json,**.mk}]
+indent_style = tab

.gitignore

@@ -0,0 +1,92 @@
+*.sublime-workspace
+.reqwire.lock
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/build/
+
+# PyBuilder
+target/
+
+# IPython Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# dotenv
+.env
+
+# virtualenv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+
+# Rope project settings
+.ropeproject

.travis.yml

@@ -0,0 +1,11 @@
+sudo: false
+language: python
+after_success:
+  - coveralls
+python:
+  - "2.7"
+  - "3.3"
+  - "3.4"
+  - "3.5"
+install: pip install python-coveralls tox-travis
+script: tox

CHANGELOG.rst

@@ -0,0 +1,20 @@
+=========
+Changelog
+=========
+
+.. contents::
+   :backlinks: none
+
+Unreleased_
+===========
+*Nothing yet.*
+
+0.1.0 - 2017-01-22
+==================
+
+- Initial release, with Consul mapper backend.
+- Very primitive command-line client, with regex filter support for
+  cluster node addresses.
+
+
+.. _Unreleased: https://github.com/darvid/proxenos/compare/v0.0.1...HEAD

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2017 David Gidwani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

MANIFEST.in

@@ -0,0 +1,18 @@
+global-exclude *.py[cod]
+global-exclude __pycache__
+
+graft docs
+graft requirements/lck
+graft src
+graft tests
+
+include .coveragerc
+include .editorconfig
+include .travis.yml
+include tox.ini
+
+include AUTHORS
+include CHANGELOG.rst
+include LICENSE
+include MANIFEST.in
+include README.rst

README.rst

@@ -0,0 +1,81 @@
+========
+proxenos
+========
+
+.. image:: https://img.shields.io/pypi/v/proxenos.svg
+   :target: https://pypi.python.org/pypi/proxenos
+
+.. image:: https://img.shields.io/pypi/pyversions/proxenos.svg
+   :target: https://pypi.python.org/pypi/proxenos
+
+.. image:: https://travis-ci.org/darvid/proxenos.svg?branch=master
+   :target: https://travis-ci.org/darvid/proxenos
+
+.. image:: https://img.shields.io/coveralls/darvid/proxenos.svg
+   :target: https://coveralls.io/github/darvid/proxenos
+
+.. image:: https://badges.gitter.im/python-proxenos/Lobby.svg
+   :alt: Join the chat at https://gitter.im/python-proxenos/Lobby
+   :target: https://gitter.im/python-proxenos/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+
+A Python toolkit for Rendezvous/Highest Random Weight (HRW) hash based routing.
+
+.. code-block:: pycon
+
+   >>> import proxenos.mappers.consul
+   >>> import proxenos.rendezvous
+   >>> mapper = proxenos.mappers.consul.ConsulClusterMapper(
+   ...     host='localhost', port=8500)
+   >>> mapper.update()
+   >>> mapper.cluster
+   {SocketAddress(host=IPAddress('::'), port=8000),
+    SocketAddress(host=IPAddress('::'), port=8001),
+    SocketAddress(host=IPAddress('::'), port=8300),
+    SocketAddress(host=IPAddress('::'), port=8500)}
+   >>> mapper.select('github.com', proxenos.rendezvous.HashMethod.SIPHASH)
+   SocketAddress(host=IPAddress('::'), port=8001)
+
+.. code-block:: shell
+
+   $ proxenos select -b consul -h localhost -p 8500 github.com
+   0.0.0.0:8300
+
+Features
+========
+
+* Support for multiple service discovery backends possible. *Currently
+  only support for Consul is implemented, but other backends coming
+  eventually.*
+* Supports many different hash functions and PRFs. The default hashing
+  method is the `SipHash <https://131002.net/siphash/>`_ PRF.
+* Provides a command-line interface for quickly testing/debugging
+  node selection.
+
+Installation
+============
+
+.. code-block:: shell
+
+   $ pip install proxenos
+   $ # If you'd like Murmur3 support, use:
+   $ pip install proxenos[murmur]
+
+Notes
+=====
+
+**proxenos** uses Python's PRNG for calculating the weight of nodes in
+a cluster, rather than using a linear congruential generator (LCG_)
+as described in the `original paper on Rendezvous hashing`__. Seeded
+weights generated are limited to ``sys.maxsize``, which means the
+resulting weights will differ depending on the platform architecture.
+
+.. _LCG: https://en.wikipedia.org/wiki/Linear_congruential_generator
+.. _thaler_ravishankar_1996: http://www.eecs.umich.edu/techreports/cse/96/CSE-TR-316-96.pdf
+
+__ thaler_ravishankar_1996_
+
+Similar projects
+================
+
+* `clandestined <https://github.com/ewdurbin/clandestined-python>`_
+* `nikhilgarg28/rendezvous <https://github.com/nikhilgarg28/rendezvous>`_