Pausable response streams (#1179)

* This commit adds handlers for the asyncio/uvloop protocol callbacks for pause_writing and resume_writing.
These are needed for the correct functioning of built-in tcp flow-control provided by uvloop and asyncio.
This is somewhat of a breaking change, because the `write` function in user streaming callbacks now must be `await`ed.
This is necessary because it is possible now that the http protocol may be paused, and any calls to write may need to wait on an async event to be called to become unpaused.

Updated examples and tests to reflect this change.

This change does not apply to websocket connections. A change to websocket connections may be required to match this change.

* Fix a couple of PEP8 errors caused by previous rebase.

* update docs

add await syntax to response.write in response-streaming docs.

* remove commented out code from a test file

sanic/response.py

@@ -46,7 +46,7 @@ class BaseHTTPResponse:
 
 class StreamingHTTPResponse(BaseHTTPResponse):
     __slots__ = (
-        'transport', 'streaming_fn', 'status',
+        'protocol', 'streaming_fn', 'status',
         'content_type', 'headers', '_cookies'
     )
 
@@ -58,7 +58,7 @@ class StreamingHTTPResponse(BaseHTTPResponse):
         self.headers = CIMultiDict(headers or {})
         self._cookies = None
 
-    def write(self, data):
+    async def write(self, data):
         """Writes a chunk of data to the streaming response.
 
         :param data: bytes-ish data to be written.
@@ -66,8 +66,9 @@ class StreamingHTTPResponse(BaseHTTPResponse):
         if type(data) != bytes:
             data = self._encode_body(data)
 
-        self.transport.write(
+        self.protocol.push_data(
             b"%x\r\n%b\r\n" % (len(data), data))
+        await self.protocol.drain()
 
     async def stream(
             self, version="1.1", keep_alive=False, keep_alive_timeout=None):
@@ -77,10 +78,12 @@ class StreamingHTTPResponse(BaseHTTPResponse):
         headers = self.get_headers(
             version, keep_alive=keep_alive,
             keep_alive_timeout=keep_alive_timeout)
-        self.transport.write(headers)
-
+        self.protocol.push_data(headers)
+        await self.protocol.drain()
         await self.streaming_fn(self)
-        self.transport.write(b'0\r\n\r\n')
+        self.protocol.push_data(b'0\r\n\r\n')
+        # no need to await drain here after this write, because it is the
+        # very last thing we write and nothing needs to wait for it.
 
     def get_headers(
             self, version="1.1", keep_alive=False, keep_alive_timeout=None):
@@ -298,13 +301,13 @@ async def file_stream(location, status=200, chunk_size=4096, mime_type=None,
                     if len(content) < 1:
                         break
                     to_send -= len(content)
-                    response.write(content)
+                    await response.write(content)
             else:
                 while True:
                     content = await _file.read(chunk_size)
                     if len(content) < 1:
                         break
-                    response.write(content)
+                    await response.write(content)
         finally:
             await _file.close()
         return  # Returning from this fn closes the stream

sanic/server.py

@@ -55,7 +55,8 @@ class HttpProtocol(asyncio.Protocol):
         # connection management
         '_total_request_size', '_request_timeout_handler',
         '_response_timeout_handler', '_keep_alive_timeout_handler',
-        '_last_request_time', '_last_response_time', '_is_stream_handler')
+        '_last_request_time', '_last_response_time', '_is_stream_handler',
+        '_not_paused')
 
     def __init__(self, *, loop, request_handler, error_handler,
                  signal=Signal(), connections=set(), request_timeout=60,
@@ -82,6 +83,7 @@ class HttpProtocol(asyncio.Protocol):
         self.request_class = request_class or Request
         self.is_request_stream = is_request_stream
         self._is_stream_handler = False
+        self._not_paused = asyncio.Event(loop=loop)
         self._total_request_size = 0
         self._request_timeout_handler = None
         self._response_timeout_handler = None
@@ -96,6 +98,7 @@ class HttpProtocol(asyncio.Protocol):
         if 'requests_count' not in self.state:
             self.state['requests_count'] = 0
         self._debug = debug
+        self._not_paused.set()
 
     @property
     def keep_alive(self):
@@ -124,6 +127,12 @@ class HttpProtocol(asyncio.Protocol):
         if self._keep_alive_timeout_handler:
             self._keep_alive_timeout_handler.cancel()
 
+    def pause_writing(self):
+        self._not_paused.clear()
+
+    def resume_writing(self):
+        self._not_paused.set()
+
     def request_timeout_callback(self):
         # See the docstring in the RequestTimeout exception, to see
         # exactly what this timeout is checking for.
@@ -351,6 +360,12 @@ class HttpProtocol(asyncio.Protocol):
                 self._last_response_time = current_time
                 self.cleanup()
 
+    async def drain(self):
+        await self._not_paused.wait()
+
+    def push_data(self, data):
+        self.transport.write(data)
+
     async def stream_response(self, response):
         """
         Streams a response to the client asynchronously. Attaches
@@ -360,9 +375,10 @@ class HttpProtocol(asyncio.Protocol):
         if self._response_timeout_handler:
             self._response_timeout_handler.cancel()
             self._response_timeout_handler = None
+
         try:
             keep_alive = self.keep_alive
-            response.transport = self.transport
+            response.protocol = self
             await response.stream(
                 self.request.version, keep_alive, self.keep_alive_timeout)
             self.log_response(response)