Add gevent example (#1201)

Author: lewoudar

README.rst

@@ -27,8 +27,10 @@ You use it like this:
 .. code-block:: python
 
     import h2.connection
+    import h2.config
 
-    conn = h2.connection.H2Connection()
+    config = h2.config.H2Configuration()
+    conn = h2.connection.H2Connection(config=config)
     conn.send_headers(stream_id=stream_id, headers=headers)
     conn.send_data(stream_id, data)
     socket.sendall(conn.data_to_send())

docs/source/examples.rst

@@ -14,6 +14,7 @@ Example Servers
    asyncio-example
    twisted-example
    eventlet-example
+   gevent-example
    curio-example
    tornado-example
    wsgi-example

docs/source/gevent-example.rst

@@ -0,0 +1,20 @@
+Gevent Example Server
+=====================
+
+This example is a basic HTTP/2 server written using `gevent`_, a powerful
+coroutine-based Python networking library that uses `greenlet`_
+to provide a high-level synchronous API on top of the `libev`_ or `libuv`_
+event loop.
+
+This example is inspired by the curio one and also demonstrates the correct use
+of HTTP/2 flow control with Hyper-h2 and how gevent can be simple to use.
+
+.. literalinclude:: ../../examples/gevent/gevent-server.py
+   :language: python
+   :linenos:
+   :encoding: utf-8
+
+.. _gevent: http://www.gevent.org/
+.. _greenlet: https://greenlet.readthedocs.io/en/latest/
+.. _libev: http://software.schmorp.de/pkg/libev.html
+.. _libuv: http://libuv.org/

examples/gevent/gevent-server.py

@@ -0,0 +1,186 @@
+# -*- coding: utf-8 -*-
+"""
+gevent-server.py
+================
+
+A simple HTTP/2 server written for gevent serving static files from a directory specified as input.
+If no directory is provided, the current directory will be used.
+"""
+import mimetypes
+import sys
+from functools import partial
+from pathlib import Path
+from typing import Tuple, Dict, Optional
+
+from gevent import socket, ssl
+from gevent.event import Event
+from gevent.server import StreamServer
+from h2 import events
+from h2.config import H2Configuration
+from h2.connection import H2Connection
+
+
+def get_http2_tls_context() -> ssl.SSLContext:
+    ctx = ssl.create_default_context(purpose=ssl.Purpose.CLIENT_AUTH)
+    ctx.options |= (
+            ssl.OP_NO_SSLv2 | ssl.OP_NO_SSLv3 | ssl.OP_NO_TLSv1 | ssl.OP_NO_TLSv1_1
+    )
+
+    ctx.options |= ssl.OP_NO_COMPRESSION
+    ctx.set_ciphers('ECDHE+AESGCM:ECDHE+CHACHA20:DHE+AESGCM:DHE+CHACHA20')
+    ctx.load_cert_chain(certfile='localhost.crt', keyfile='localhost.key')
+    ctx.set_alpn_protocols(['h2'])
+    try:
+        ctx.set_npn_protocols(['h2'])
+    except NotImplementedError:
+        pass
+
+    return ctx
+
+
+class H2Worker:
+
+    def __init__(self, sock: socket, address: Tuple[str, str], source_dir: str = None):
+        self._sock = sock
+        self._address = address
+        self._flow_control_events: Dict[int, Event] = {}
+        self._server_name = 'gevent-h2'
+        self._connection: Optional[H2Connection] = None
+        self._read_chunk_size = 8192  # The maximum amount of a file we'll send in a single DATA frame
+
+        self._check_sources_dir(source_dir)
+        self._sources_dir = source_dir
+
+        self._run()
+
+    def _initiate_connection(self):
+        config = H2Configuration(client_side=False, header_encoding='utf-8')
+        self._connection = H2Connection(config=config)
+        self._connection.initiate_connection()
+        self._sock.sendall(self._connection.data_to_send())
+
+    @staticmethod
+    def _check_sources_dir(sources_dir: str) -> None:
+        p = Path(sources_dir)
+        if not p.is_dir():
+            raise NotADirectoryError(f'{sources_dir} does not exists')
+
+    def _send_error_response(self, status_code: str, event: events.RequestReceived) -> None:
+        self._connection.send_headers(
+            stream_id=event.stream_id,
+            headers=[
+                (':status', status_code),
+                ('content-length', '0'),
+                ('server', self._server_name),
+            ],
+            end_stream=True
+        )
+        self._sock.sendall(self._connection.data_to_send())
+
+    def _handle_request(self, event: events.RequestReceived) -> None:
+        headers = dict(event.headers)
+        if headers[':method'] != 'GET':
+            self._send_error_response('405', event)
+            return
+
+        file_path = Path(self._sources_dir) / headers[':path'].lstrip('/')
+        if not file_path.is_file():
+            self._send_error_response('404', event)
+            return
+
+        self._send_file(file_path, event.stream_id)
+
+    def _send_file(self, file_path: Path, stream_id: int) -> None:
+        """
+        Send a file, obeying the rules of HTTP/2 flow control.
+        """
+        file_size = file_path.stat().st_size
+        content_type, content_encoding = mimetypes.guess_type(str(file_path))
+        response_headers = [
+            (':status', '200'),
+            ('content-length', str(file_size)),
+            ('server', self._server_name)
+        ]
+        if content_type:
+            response_headers.append(('content-type', content_type))
+        if content_encoding:
+            response_headers.append(('content-encoding', content_encoding))
+
+        self._connection.send_headers(stream_id, response_headers)
+        self._sock.sendall(self._connection.data_to_send())
+
+        with file_path.open(mode='rb', buffering=0) as f:
+            self._send_file_data(f, stream_id)
+
+    def _send_file_data(self, file_obj, stream_id: int) -> None:
+        """
+        Send the data portion of a file. Handles flow control rules.
+        """
+        while True:
+            while self._connection.local_flow_control_window(stream_id) < 1:
+                self._wait_for_flow_control(stream_id)
+
+            chunk_size = min(self._connection.local_flow_control_window(stream_id), self._read_chunk_size)
+            data = file_obj.read(chunk_size)
+            keep_reading = (len(data) == chunk_size)
+
+            self._connection.send_data(stream_id, data, not keep_reading)
+            self._sock.sendall(self._connection.data_to_send())
+
+            if not keep_reading:
+                break
+
+    def _wait_for_flow_control(self, stream_id: int) -> None:
+        """
+        Blocks until the flow control window for a given stream is opened.
+        """
+        event = Event()
+        self._flow_control_events[stream_id] = event
+        event.wait()
+
+    def _handle_window_update(self, event: events.WindowUpdated) -> None:
+        """
+        Unblock streams waiting on flow control, if needed.
+        """
+        stream_id = event.stream_id
+
+        if stream_id and stream_id in self._flow_control_events:
+            g_event = self._flow_control_events.pop(stream_id)
+            g_event.set()
+        elif not stream_id:
+            # Need to keep a real list here to use only the events present at this time.
+            blocked_streams = list(self._flow_control_events.keys())
+            for stream_id in blocked_streams:
+                g_event = self._flow_control_events.pop(stream_id)
+                g_event.set()
+
+    def _run(self) -> None:
+        self._initiate_connection()
+
+        while True:
+            data = self._sock.recv(65535)
+            if not data:
+                break
+
+            h2_events = self._connection.receive_data(data)
+            for event in h2_events:
+                if isinstance(event, events.RequestReceived):
+                    self._handle_request(event)
+                elif isinstance(event, events.DataReceived):
+                    self._connection.reset_stream(event.stream_id)
+                elif isinstance(event, events.WindowUpdated):
+                    self._handle_window_update(event)
+
+            data_to_send = self._connection.data_to_send()
+            if data_to_send:
+                self._sock.sendall(data_to_send)
+
+
+if __name__ == '__main__':
+    files_dir = sys.argv[1] if len(sys.argv) > 1 else f'{Path().cwd()}'
+    server = StreamServer(('127.0.0.1', 8080), partial(H2Worker, source_dir=files_dir),
+                          ssl_context=get_http2_tls_context())
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        server.close()

examples/gevent/localhost.crt

@@ -0,0 +1,20 @@
+-----BEGIN CERTIFICATE-----
+MIIDVDCCAjwCCQC1RoAIsDX89zANBgkqhkiG9w0BAQsFADBsMQswCQYDVQQGEwJG
+UjEWMBQGA1UECAwNSWxlLWRlLUZyYW5jZTEOMAwGA1UEBwwFUGFyaXMxITAfBgNV
+BAoMGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDESMBAGA1UEAwwJbG9jYWxob3N0
+MB4XDTE5MDgzMDAzNDcwN1oXDTIwMDgyOTAzNDcwN1owbDELMAkGA1UEBhMCRlIx
+FjAUBgNVBAgMDUlsZS1kZS1GcmFuY2UxDjAMBgNVBAcMBVBhcmlzMSEwHwYDVQQK
+DBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQxEjAQBgNVBAMMCWxvY2FsaG9zdDCC
+ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANexqhW+b7Mx2lj5csv7Uq7T
+St6RWEocEUtuwBUsQ3VGOUTjN0dRxGeeZdDvZYrVsKhMwT1EeoXYlleQJPSEgW1d
+E5Mx6t4okWtG5D8YbIDMLRqLMpOqGSH1VZDU6l9ZN2UCTBtIVZN+Mg/q36cQOkwE
+Rp+BBiOU4dgKKms5d5QfOi3wPNEdeU0z77qxOuI9WmnMxvxM+vySkt2mHV/ptW4w
+XZDZ9QC/IHhXhjkSlQuL/TUptJ2UtlEXtn5NcNAWROl7xTMVHfIiFVW4oW39KIrA
+zGH5qYlJG/gUhJBTU7K5N5J1c/Y3FyNIeOgHMQr6MnKugV7JyOZYxjXGgdXOUNMC
+AwEAATANBgkqhkiG9w0BAQsFAAOCAQEAUuGdTOWJ0SspGs6zU50lt+GxXo5xO8HE
+y7RiOnorJVE23dgVAyaDDcnIfsF+usobACHRlqirn2jvY5A7TIEM7Wlw5c1zrCAW
+bDzPJS0h6Hub05WQQmU734Ro1et7WFUrFRlDQUHJADgEAXRhXlm2Uk7Ay1PlCIz9
+802neyhWErL6bb7zxV5fWTu7RA3XUAX2ZrYO3XLhcsK7SnpT0whoBI06c1GxDkgV
+wFeYv8PBH5iQWhIft8EeTrNvNa+dusnppuM21sWWzItRnFef+ATixdDGIpDitAfs
+cfIUalb3BBdn4PXamN7EhWzHJlcME1cerjQ4YoEynWmT2blk1XUg9A==
+-----END CERTIFICATE-----

examples/gevent/localhost.key

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDXsaoVvm+zMdpY
++XLL+1Ku00rekVhKHBFLbsAVLEN1RjlE4zdHUcRnnmXQ72WK1bCoTME9RHqF2JZX
+kCT0hIFtXROTMereKJFrRuQ/GGyAzC0aizKTqhkh9VWQ1OpfWTdlAkwbSFWTfjIP
+6t+nEDpMBEafgQYjlOHYCiprOXeUHzot8DzRHXlNM++6sTriPVppzMb8TPr8kpLd
+ph1f6bVuMF2Q2fUAvyB4V4Y5EpULi/01KbSdlLZRF7Z+TXDQFkTpe8UzFR3yIhVV
+uKFt/SiKwMxh+amJSRv4FISQU1OyuTeSdXP2NxcjSHjoBzEK+jJyroFeycjmWMY1
+xoHVzlDTAgMBAAECggEBAKqtYIxyNAtVMJVlVmyJBAVpFv6FfpquGRVans5iR0L+
+fYTAU1axIjxoP+MT/ILe0zpp+iNUE6vkFhtV6Zg/Xfc/RqUcQ+DlsyRzZVt0JS/J
+4Qr3CN+GIvsXGk1P3eHzQ/0+0yBnnafnnQ+xaKbXFXpfi87dlxEC169PY/+S6see
+dcPYw8LB8rI+mIIPvM/V2VtobZb9BFUsN4Dq8H1tRR97ST4TRbwov66o17Fvn5ww
+mXUwHjhdgxaJLtxJwppMhhSuST64mwoNY8XNWE0PlaB5jxKCNuWYYurjEJLJcBa7
+3lYadsRTucoiRbsTcqpivsa3KWxNRJcZERWVN4LVQvkCgYEA+E5zgVHbKfjCGs9x
+Xv1uVLjpdsh2S/7Zkx95vc4rBoLe8ii1uSpcLHytB7F5bPZV3Tiivu8OpW3E+8n6
+8mxQHSomSioxTE+xXF4JMf5XY2l9Tvz/60mo/dxk9Yo9k79OIJDUJrnpc18iYtRp
+B3X2g7JfqpT/RbG0bs2YVa/R3z8CgYEA3mCIm0Y0b6mpTxQNk6fcH2YXe1mdRp5Y
+9O+wVTNwmwB2vZZVm/K/wmOstsO1P+/PzwJ/WcBV9TlLlZRxxs/yNNU8NM7+7l3O
+e0ucCNRqhi9P19SA7l18FroOtOv2DatvXpNJTM6fXgE7dPQm5NKrNKK6nv03OUzQ
+BLLBBtzv/W0CgYEA6LU9cvkwGQnVgCLh8VA6UpRp2LTOiTJy3nslMUlC8Xs9Tl3w
+0XRtphPCZe9iCUhj+EvX2nFYnJlff0owMXppKqwR7nfUc9xMMHDA1WW0qKp4kcpy
+XiROiHxA8g144DruEX8qFJEvxLxoEY9YT3GycoJ9PfUduEdu/lkYZ1W7rykCgYB0
+mw/mw9hpGQDzu2MnIuUU/dagUqxaxFuHDExdUNziGkspPLRlUtPknZmKOHNJNHm2
+ZevbZzRrowCUTcOfaZjqxUmNs2EQItZL5qjKJIA7HoHyfbahxxlzXVqq2fQq1NNQ
+N1E/WjVM+L5xpDjk0eb+cboD9mlHvZRycj0vWRjqvQKBgQDP1xotkMqYwnMnpoRQ
+e3bqhIQFeoqIehsl2e/F+5yZ43plvEXavxshNJS3gGr1MflexcjqEaiHdfdK84zL
+mJuPYn0Uz5fP336aepzVsxK78tW4ilZri2mPbpBYgJskc6Ud7ue5zhBtuQnu5rV4
+zcuL1QjSQA+KW88b4DU/Usp6Eg==
+-----END PRIVATE KEY-----

setup.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-import codecs
 import os
 import re
 import sys