{
    "info": {
        "author": "Micha\u0142 Pasternak",
        "author_email": "michal.dtz@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 2 - Pre-Alpha",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: MIT License",
            "Natural Language :: English",
            "Programming Language :: Python :: 3.7"
        ],
        "description": "django-nginx-push-stream\n------------------------\n\nDjango support library for `Nginx Push Stream Module`_.\n\n.. image:: https://travis-ci.org/mpasternak/django-nginx-push-stream.svg?branch=develop\n\t   :target: https://travis-ci.org/mpasternak/django-nginx-push-stream\n\n\t      \nQuick introduction\n==================\n\n1. `Nginx Push Stream Module`_ is a scalable module for Nginx, that provides pub-sub capabilities.\n\n2. You can install Nginx binaries which include it:\n\n   * on Ubuntu via `unofficial PPA`_,\n\n     .. code-block:: shell\n\n       $ sudo add-apt-repository ppa:dotz/nginx-with-push-stream-module\n       $ sudo apt-get update\n       $ sudo apt-get install nginx\n\n   * on macOS via `Homebrew`_ with `homebrew-nginx tap`_,\n\n     .. code-block:: shell\n\n       $ brew tap denji/nginx\n       $ brew install nginx-full --with-push-stream-module --with-auth-req\n\n   * possibly many more (help me improve this documentation, please).\n\n3. For development with `Docker`_, clone this repo and type ``docker-compose up``.\n   This command will build the Docker image containing Nginx with `Nginx Push Stream Module`_ and\n   start it up. By default, port 80 of Docker container is being mapped to port 9080 of your\n   local machine (see `docker-compose.yml`_ for details)\n\n4. This package, django-nginx-push-stream, is an attempt to unleash the power of the Nginx Push\n   Stream Module from Django application.\n\n5. There are various ways to achieve the goal of realtime push notifications in web browser. This approach\n   is one of many. Its benefits include not having to run a separate webserver just for handling\n   websockets and the ability to use the same address/port for realtime connections as for the rest\n   of the web page.\n\n6. This module is a very, very thin layer of code and configuration for Django. It was\n   created rather because of a need to clarify, document and sort-out things in general,\n   not because sending push messages via `Nginx Push Stream Module`_ is hard. It is not.\n\nDesign\n======\n\ndjango-nginx-push-stream consists of:\n\n* configuration settings in ``conf/settings.py``,\n* calls in the ``core.py`` module,\n* a small ``auth`` view defined in ``auth.py``, which can decide if an user is allowed to subscribe\n  to a channel\n* there's also an example nginx container (``docker/default`` and ``docker/Dockerfile-nginx``)\n* there's also an example project (``test_project``) that can be run.\n\ndjango-nginx-push-stream describes ways how to subscribe and then\nhow to send push notifications to Django's:\n\n* anonymous users,\n* logged-in sessions,\n* all authorised (looged-in) sessions.\n\nThere's a very bare example project provided. You can extend its functionality\nto fit it to a specific purpose. A project will be provided, that extends the\nbasic functionality in order to bring graphics notifications, progress dialogs\nand more as a separate module.\n\nBooting example infrastructure\n==============================\n\nRun docker server by typing ``docker-compose up -d`` in the root directory.\n\n  .. code-block:: shell\n\n    $  docker-compose up\n    Starting django-nginx-push-stream_appserver_1 ... done\n    Starting django-nginx-push-stream_webserver_1 ... done\n    Attaching to django-nginx-push-stream_appserver_1, django-nginx-push-stream_webserver_1\n    appserver_1  | [uwsgi-static] added mapping for /static => /app/test_project/staticroot\n    [... lots of text...]\n\nGo to http://127.0.0.1:9080/ to see the application in action. It is a simple chat application.\nType any message, press ENTER. It will broadcast the message to all the subscribers. You can\nsubscribe using other methods, than a web browser (see below). \n\nDetails\n=======\n\nHow to send the message to nginx pubsub queue\n---------------------------------------------\n\n.. code-block:: shell\n\n   $ cd test_project\n   $ python manage.py publish_message  -q __all__  -d '{\"message\": [\"Foobar\"]}'\n\nThis will send a short message to a queue called ``__all__`` which should include all\nusers of the site, logged-in or not.\n\nListening for messages\n----------------------\n\nYou can listen for messages sent in the above step. Assuming you have started the\ndefault configuration using ``docker-compose``:\n\n* with a browser: open http://127.0.0.1:9080 in your web browser to see the example app\n  in action.\n\n* with ``curl``:\n\n  .. code-block:: shell\n\n      $ curl -s -v --no-buffer 'http://localhost:9080/sub/my-app__all__'\n\n* with `websocket-client`_:\n\n  .. code-block:: shell\n\n      $ pip install websocket-client\n\n  then:\n\n  .. code-block:: python\n\n      from websocket import create_connection\n      ws = create_connection(\"ws://localhost:9080/ws/my-app__all__\")\n      print(\"Listening...\")\n      result = ws.recv()\n      print(\"Received '%s'\" % result)\n      ws.close()\n\nAs you probably already know, the ``__all__`` string portion of URL is the name of\na queue.\n\n``my-app`` is a prefix, that can be configured by changing\n``NGINX_PUSH_STREAM_PUB_PREFIX``.\n\n``curl(1)``? Great! So why do I need a Django app for, exactly?\n===============================================================\n\nThis package makes it easier to send information to specific sessions or all\nusers of your Django-based website:\n\n* send message to all users.\n\n* send message to a specific Django session: browser subscribes to a channel with\n  name based on session id (as shown in test_project),\n\n* send message to all logged-in users: make logged in users subscribe to a queue\n  for logged in users,\n\n* give an UUID for every single web page that gets rendered by your server and send\n  messages only to this page (with help of `django-template-uuid`_) - not yet shown\n  in examples (patches accepted!)\n\nSecurity\n========\n\nAnyone can subscribe to a queue with the default configuration. So, a malicous attacker\ncould subscribe and read users private information. How to avoid this? Nginx documentation\nhas a section about `Authentication based on subrequest result`_ .\n\nThe default example configuration also includes ``auth_request`` setup in nginx in\nsuch way, that it will internally ask the Django application if a given user has\nenough credentials to subscribe to a queue.\n\nWebSockets vs SSE\n=================\n\n`Nginx Push Stream Module`_ offers sending messages over both WebSockets and EventSource (SSE).\nYou can read about those two different methods in a great comment at `StackOverflow`_.\n\n.. _Nginx Push Stream Module: https://github.com/wandenberg/nginx-push-stream-module .\n.. _unofficial PPA: https://launchpad.net/~dotz/+archive/ubuntu/nginx-with-push-stream-module\n.. _Homebrew: https://github.com/denji/homebrew-nginx\n.. _Docker: https://www.docker.com/get-started\n.. _docker-compose.yml: https://github.com/mpasternak/django-nginx-push-stream/blob/master/docker-compose.yml\n.. _Foundation 6: https://foundation.zurb.com\n.. _websocket-client: https://pypi.org/project/websocket-client/\n.. _django-template-uuid: https://github.com/mpasternak/django-template-uuid\n.. _Authentication based on subrequest result: https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/\n.. _StackOverflow: https://stackoverflow.com/questions/5195452/websockets-vs-server-sent-events-eventsource#5326159\n.. _homebrew-nginx tap: https://denji.github.io/homebrew-nginx/\n\n\n0.0.1\n-----\n* first public release\n  \n",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/mpasternak/django-nginx-push-stream",
        "keywords": "",
        "license": "MIT license",
        "maintainer": "",
        "maintainer_email": "",
        "name": "django_nginx_push_stream",
        "package_url": "https://pypi.org/project/django_nginx_push_stream/",
        "platform": "",
        "project_url": "https://pypi.org/project/django_nginx_push_stream/",
        "project_urls": {
            "Homepage": "https://github.com/mpasternak/django-nginx-push-stream"
        },
        "release_url": "https://pypi.org/project/django_nginx_push_stream/0.0.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "nginx with http-push-stream module support for Django",
        "version": "0.0.1"
    },
    "last_serial": 4801835,
    "releases": {
        "0.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "b2acd26c0ac88edb0ea6182d7238d5cb",
                    "sha256": "7d69128eb07520e5ac6e11f3ab2ca074e9d88c82ba31a8cc77e336293438866b"
                },
                "downloads": -1,
                "filename": "django_nginx_push_stream-0.0.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "b2acd26c0ac88edb0ea6182d7238d5cb",
                "packagetype": "bdist_wheel",
                "python_version": "3.6",
                "requires_python": null,
                "size": 20110,
                "upload_time": "2019-02-10T10:26:53",
                "url": "https://files.pythonhosted.org/packages/69/d9/10a9c212af4d6466806caba452c42251400962de19bf4c818a6e3a6ca093/django_nginx_push_stream-0.0.1-py3-none-any.whl"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "b2acd26c0ac88edb0ea6182d7238d5cb",
                "sha256": "7d69128eb07520e5ac6e11f3ab2ca074e9d88c82ba31a8cc77e336293438866b"
            },
            "downloads": -1,
            "filename": "django_nginx_push_stream-0.0.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "b2acd26c0ac88edb0ea6182d7238d5cb",
            "packagetype": "bdist_wheel",
            "python_version": "3.6",
            "requires_python": null,
            "size": 20110,
            "upload_time": "2019-02-10T10:26:53",
            "url": "https://files.pythonhosted.org/packages/69/d9/10a9c212af4d6466806caba452c42251400962de19bf4c818a6e3a6ca093/django_nginx_push_stream-0.0.1-py3-none-any.whl"
        }
    ]
}