Metadata-Version: 1.1
Name: django-portmaster
Version: 0.0.1
Summary: A Django microservice for network port allocation
Home-page: https://github.com/miljank/django-portmaster
Author: Miljan Karadzic
Author-email: miljank@gmail.com
License: BSD
Download-URL: https://github.com/miljank/django-portmaster/archive/0.0.1.tar.gz
Description-Content-Type: UNKNOWN
Description: Django Portmaster
        =================
        
        Django Portmaster is a network port allocation and management
        microservice. With Portmaster, you can assign port ranges to different
        services and register ports to different instances of those service.
        This way you can prevent assigning the same port twice, thus preventing
        assignement collision.
        
        Installation
        ------------
        
        1. Install using PIP.
        
        ::
        
            pip install django-portmaster
        
        2. Add app to your Django project's settings file and include offer
           cleanup middleware.
        
        .. code:: python
        
            INSTALLED_APPS = [
                [..]
                'django_portmaster'
            ]
        
            MIDDLEWARE = [
                [..]
                'django_portmaster.middleware.CleanOldOffersMiddleware'
            ]
        
        3. Include Portmaster's URLs into your Django project's urls file.
        
        .. code:: python
        
            from django_portmaster.urls import portmaster_urlpatterns
            urlpatterns += portmaster_urlpatterns
        
        4. Optionally, you can override the time offers are kept before they are
           deleted. Add the following code to you settings.py file.
        
        .. code:: python
        
            # Default value is 30 minutes
            PM_DELETE_OFFERS_AFTER_MINUTES = 10
        
        API
        ---
        
        -  Define port range by creating a service.
        
        .. code:: javascript
        
            POST /v1/services
        
            {
               "name": "django",
               "description": "Django service",
               "start": 5000,
               "end": 10000
            }
        
        -  Request a port from the range by providing a service instance name.
        
        .. code:: javascript
        
            POST /v1/services/django/offers
        
            {
                "name": "web-01"
            }
        
        Response
        
        .. code:: javascript
        
            {
                "service": "django",
                "name": "web-01",
                "port": 5000,
                "secret": "6f8ffc86-d98a-49ba-848a-a7cbaaea9360",
                "created": "2017-09-08T14:16:39.277408Z"
            }
        
        -  Port will not be allocated immediately. Instead it will be reserved
           until the client accepts the port by posting to the dedicated URL
           using the provided secret code:
        
        .. code:: javascript
        
            POST /v1/services/django/offers/6f8ffc86-d98a-49ba-848a-a7cbaaea9360/accept
        
        Response
        
        .. code:: javascript
        
            {
                "service": "django",
                "name": "web-01",
                "port": 5000,
                "created": "2017-09-08T14:18:04.094357Z"
            }
        
        -  Alternatively, you can reject the offer. Offers that are not accepted
           are automatically deleted by Portmaster middleware after they reach
           threshold set by ``PM_DELETE_OFFERS_AFTER_MINUTES`` setting (default
           value is 30 minutes).
        
        .. code:: javascript
        
            POST /v1/services/django/offers/6f8ffc86-d98a-49ba-848a-a7cbaaea9360/reject
        
        -  You can list all port alocations for a particular service.
        
        .. code:: javascript
        
            GET /v1/services/django/ports
        
        -  Find one by port number
        
        .. code:: javascript
        
            GET /v1/services/django/ports/5000
        
        -  Or find one by service instance name
        
        .. code:: javascript
        
            GET /v1/services/django/ports/web-01
        
        Safe guards
        -----------
        
        Portmaster includes multiple error checks and corner case handlers, so:
        
        -  Service name needs to be unique
        -  Port ranges can not overlap
        -  Port range can not overlap with privileged ports (<1024) or IANA
           defined ephemeral port range (>49152)
        -  Port can be assigned only once at any given time
        -  Service instance name needs to be unique
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.8
Classifier: Framework :: Django :: 1.9
Classifier: Framework :: Django :: 1.10
Classifier: Framework :: Django :: 1.11
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Internet :: WWW/HTTP
