Metadata-Version: 2.1
Name: Flask-Firehose
Version: 0.2.2
Summary: HTTP/2 Server Push for your Flask apps.
Home-page: https://github.com/shreyanshk/flask-firehose
Author: Shreyansh Khajanchi
Author-email: hello@shreyanshja.in
License: MIT
Platform: any
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: Flask (>=0.10)

Flask-Firehose
==============

HTTP/2 Server Push for your Flask apps.


Installation
------------

.. code-block:: python

    pip install flask-firehose


Usage
-----
Initialization
~~~~~~~~~~~~~~

Direct initialization:

.. code-block:: python

    app = Flask(__name__)
    Firehose(app)

With application factories:

.. code-block:: python

    firehose = Firehose()

    def create_app():
        app = Flask(__name__)
        firehose.init_app(app)
        return app


Pushing resources
~~~~~~~~~~~~~~~~~

Let the HTML template writer decide what to push:

.. code-block:: jinja

    {% extends 'base.html' %}
    {% block body %}
        <link rel="stylesheet" href="{{ push('/static/css/main.css', as='style', rel='preload') }}">
        This is some document.
    {% endblock %}


Let the backend developer decide what to push:

.. code-block:: python

    from flask_firehose import push

    @app.route('/someroute')
    def render_someroute():
        push('/static/css/main.css', as='style', rel='preload')
        return render_template('some_template')


Tracking pushed resources
~~~~~~~~~~~~~~~~~~~~~~~~~

Ideally, resources already pushed during a session shouldn't be pushed again. So, Flask-Firehose includes a simple utility class to track pushed resources using session variable 'h2-pushed'.
Additionally, Flask-Firehose can also work with external code to track pushed resources in case the provided implementation is unsuitable.

.. code-block:: python

    class Custom_connector():

        def get_pushed(self):
            """Returns a set of items that have been already pushed to client.

            Returns
            -------
            set
                Set of items that are pushed.

            """
            # your code here

        def set_pushed(self, inset):
            """Update client state after pushing more items at the end of request.

            Parameters
            ----------
            inset : set
                A set of URLs of pushed items.
            """
            # your code here


Using custom connector with Firehose

.. code-block:: python

    firehose = Firehose(connector=Custom_connector())
    firehose.init_app(app)


Configure NGINX
---------------

.. code-block:: nginx

    location = /myapp {
        proxy_pass http://upstream;
        http2_push_preload on;
    }


Read more at: https://www.nginx.com/blog/nginx-1-13-9-http2-server-push/


Testing
-------

To initialize a development environment in ./venv:

.. code-block:: bash

    make devenv

To run unit tests:

.. code-block:: bash

    make test

To run integration testing with NGINX with docker:

.. code-block:: bash

    make dockertest



