Permalink
Browse files

Implement SPDY (v2) support

This is incompatible with Tornado 2.x applications, but users should be able to update their code
without too much trouble.

Changes, in no particular order:

* TLS NPN means that one of many protocols can be selected after a TCP connection is established. A
  layer of indirection was added to TCPServer to allow it to delegate handling of a TCP connection
  to whichever protocol handler was negotiated. If the `npn_protocols` parameter (a list of
  (name, handler) tuples in order of preference) was passed to the constructor, the connection is
  over TLS, and NPN succeeded, the handler for the chosen name will be called. Otherwise, the
  `protocol` constructor parameter will be called. For example, SPDYServer is essentially:

  class SPDYServer(TCPServer):
      def __init__(self, request_callback):
          http_protocol = HTTPServerProtocol(request_callback)
          TCPServer.__init__(self, http_protocol,
              npn_protocols=[
                  ('spdy/2', SPDYServerProtocol(request_callback)),
                  ('http/1.1', http_protocol)])

* TCPServer was moved from netutil to its own module, tcpserver.

* Since utilizing NPN support in Python 3.3 requires the `ssl.SSLContext` class, which isn't
  available in Python 2.x, the wrap_socket() top-level function was added to `netutil` to abstract
  away these details. In addition, the `SUPPORTS_NPN` constant was added as a convenience for
  determining if the system supported NPN.

* Previously, TCP connection timeout, premature connection termination, and any HTTP parsing errors
  were handled in the client by executing the request callback with a fake 599 response. The user
  would then (if they remembered) call response.rethrow() to raise an exception. Separating the TCP
  connection from response handling made this scheme impossible (aside from being un-Pythonic in the
  first place). Instead, stack_context.wrap() was refactored to return a callable with a restore()
  method that returned a context manager that restores the saved stack context within its block.
  The above-mentioned errors are raised within this context. Top-level save() and switch_contexts()
  functions were also added, in case someone finds them useful. This is the primary incompatibility
  with current Tornado applications. `HTTPResponse.rethrow` has been removed, but the `error`
  attribute has been converted to a boolean representing whether the status code isn't 2xx or 3xx.

* The SPDY standard is rapidly evolving. v3 has already been completed, and we're currently working
  on v4. To shield the user from this, the spdy* modules are actually directories that place their
  public interfaces in __init__.py, and their version-specific implementation in v2.py. This allows
  users to `import spdyserver`, and spdy* modules to `import spdyserver.v2`. Once v3 support is
  implemented, it will go in v3.py, and users won't notice the difference.

* Much of the functionality of SimpleAsyncHTTPClient was factored out into QueuedAsyncHTTPClient,
  to allow SPDYClient to take advantage of its queuing logic as well. Subclasses pass a `handler`
  argument to the `initialize` pseudo-constructor, which gets called when a request is ready to be
  processed. If the handler determines that a new TCP connection is needed, it can call the
  `_http_connect` method to open one and return a (conn, address) pair.

* Added push_callback, priority, force_connection, ssl_version attributes to httpclient.HTTPRequest.

* Added framing, associated_urls, associated_to_url attributes to httpclient.HTTPResponse. The
  latter is necessary for notifying the client which URLs the server has promised to push, since
  pushed streams can be finished after the original response stream has.

* Added framing, priority attributes to httpserver.HTTPRequest.

* Since SPDY sessions are long-lived and streams are bidirectional, logic common to both clients and
  servers (stream management) has been factored out into the spdysession module. Each frame type,
  stream finishing events, and stream adding events all provide hooks for subclasses to override
  with client/server-specific functionality.

* Previously, `web.RequestHandler` formatted the HTTP response itself and wrote it directly to the
  IOStream. To allow for SPDY framing, this responsibility has been moved to the
  HTTPRequest.connection object, which must provide the write_preamble() and write() methods - the
  former writes the response status line and headers, while the latter writes a chunk of the
  response body. In addition, the SPDYConnection object provides the push() method, which returns
  a new `SPDYConnection` that will push a resource to the client.

* Body argument-parsing code (application/x-www-form-urlencoded or multipart/form data) needed by
  spdyserver, httpserver, and wsgi (and which was duplicated in the latter two) has been factored
  out into httputil.parse_body_arguments.

* Although IOStream.connect() already takes a callback parameter, in SSLIOStream it's not called
  until the SSL handshake is completed (which contains TLS NPN) - and TCPServer, which doesn't call
  connect(), won't know which protocol handler to execute until that happens. To fix this, a
  set_connect_callback method was added to IOStream.

* Since both SPDYSession and SimpleAsyncHTTPClient find a gzip decompressor useful, a
  GzipDecompressor class was added to the util module.

* A new RequestHandler.push() method has been added that takes a relative URL as a parameter and
  opens a new push stream for it the next time flush() is called. A new HTTPRequest is constructed
  and passed to the RequestHandler's Application instance, just like normal - the only difference
  is that the response will be written to the pushed stream. Since SPDY forbids servers from
  pushing streams after any of the response body has been written to the network to avoid race
  conditions, calling this method after flush() has been called results in an exception.

* The UIModule constructor now takes a `push_files` parameter that determines whether its
  Javascript and CSS files are automatically pushed when the UIModule is rendered. Also, the
  static_url() function provided to templates now takes an optional `push` parameter, which
  likewise causes the resulting URL to be pushed. Since the default for both of these parameters is
  easily overridden and users are aware that this patch introduces incompatibilities, I am
  confident enough to have both of these parameters default to `True`, but could be convinced
  otherwise.

* Gzip body encoding is automatically chosen if the `gzip` Application setting is `True` and the
  connection framing is SPDY, regardless of the request's Accept-Encoding header. SPDY specifically
  allows this.

* The boolean `spdy` Application parameter was added to cause RequestHandler to add an
  "Alternate-Protocol: 443:npn-spdy" header to all responses if the connection framing is not
  already SPDY.

* AsyncSSLTestCase has been added to the testing module as a base class for all tests that require
  SSL connections.

* Since the websocket module has been updated to use the new HTTPConnection interface, it should,
  in theory, support SPDY framing. However, Chrome 19 crashes whenever I start it with
  --enable-websocket-over-spdy, so we'll need to work with the Chromium team to get this fixed.
  If there were unit tests for the websocket module, I would have updated them.

* The spdyutil module, the bulk of which is in its v2 submodule, provides data structures
  representing SPDY frames (which can serialize themselves), as well as a non-blocking parse_frame
  function.

* Mark Nottingham's `c_zlib` module has been borrowed (stolen) from his old nbhttp
  (https://github.com/mnot/nbhttp/tree/spdy/src) project, since the Python standard library's
  `zlib` module lacks pre-set dictionary support, which SPDY uses for header compression.
  • Loading branch information...
1 parent 1359890 commit d29d3669a37c8a69635c4ef05851616b0bbfaf76 @alekstorm committed Jun 3, 2012
View
@@ -42,7 +42,9 @@
distutils.core.setup(
name="tornado",
version=version,
- packages = ["tornado", "tornado.test", "tornado.platform"],
+ packages = ["tornado", "tornado.test", "tornado.platform",
+ "tornado.spdyclient", "tornado.spdyserver",
+ "tornado.spdysession", "tornado.spdyutil"],
package_data = {
"tornado": ["ca-certificates.crt"],
"tornado.test": ["README", "test.crt", "test.key", "static/robots.txt",
View
@@ -150,8 +150,7 @@ def _openid_args(self, callback_uri, ax_attrs=[], oauth_scope=None):
def _on_authentication_verified(self, callback, response):
if response.error or b("is_valid:true") not in response.body:
- logging.warning("Invalid OpenID response: %s", response.error or
- response.body)
+ logging.warning("Invalid OpenID response: %s", response.body)
callback(None)
return
@@ -539,7 +538,7 @@ def _on_post(self, new_entry):
def _on_twitter_request(self, callback, response):
if response.error:
- logging.warning("Error response %s fetching %s", response.error,
+ logging.warning("Error response %s fetching %s", response.body,
response.request.url)
callback(None)
return
@@ -661,7 +660,7 @@ def _on_post(self, new_entry):
def _on_friendfeed_request(self, callback, response):
if response.error:
- logging.warning("Error response %s fetching %s", response.error,
+ logging.warning("Error response %s fetching %s", response.body,
response.request.url)
callback(None)
return
@@ -922,7 +921,7 @@ def _on_get_user_info(self, callback, session, users):
def _parse_response(self, callback, response):
if response.error:
- logging.warning("HTTP error from Facebook: %s", response.error)
+ logging.warning("HTTP error from Facebook: %s", response.body)
callback(None)
return
try:
@@ -1082,7 +1081,7 @@ def _on_post(self, new_entry):
def _on_facebook_request(self, callback, response):
if response.error:
- logging.warning("Error response %s fetching %s", response.error,
+ logging.warning("Error response %s fetching %s", response.body,
response.request.url)
callback(None)
return
View
@@ -0,0 +1,137 @@
+#!/usr/bin/env python
+#
+# Copyright (c) 2009 Mark Nottingham <mnot@pobox.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""zlib for Python using ctypes.
+
+This is a quick and nasty implementation of zlib using Python ctypes, in order
+to expose the ability to set a compression dictionary (which isn't available
+in the zlib module).
+"""
+
+import ctypes as C
+from ctypes import util
+
+from tornado.util import b
+
+_zlib = C.cdll.LoadLibrary(util.find_library('z'))
+
+class _z_stream(C.Structure):
+ _fields_ = [
+ ("next_in", C.POINTER(C.c_ubyte)),
+ ("avail_in", C.c_uint),
+ ("total_in", C.c_ulong),
+ ("next_out", C.POINTER(C.c_ubyte)),
+ ("avail_out", C.c_uint),
+ ("total_out", C.c_ulong),
+ ("msg", C.c_char_p),
+ ("state", C.c_void_p),
+ ("zalloc", C.c_void_p),
+ ("zfree", C.c_void_p),
+ ("opaque", C.c_void_p),
+ ("data_type", C.c_int),
+ ("adler", C.c_ulong),
+ ("reserved", C.c_ulong),
+ ]
+
+# TODO: get zlib version with ctypes
+ZLIB_VERSION = C.c_char_p(b("1.2.3"))
+Z_NULL = 0x00
+Z_OK = 0x00
+Z_STREAM_END = 0x01
+Z_NEED_DICT = 0x02
+Z_BUF_ERR = -0x05
+
+Z_NO_FLUSH = 0x00
+Z_SYNC_FLUSH = 0x02
+Z_FINISH = 0x04
+
+CHUNK = 1024 * 128 # FIXME: need to be smarter than this.
+
+class Compressor(object):
+ def __init__(self, level=-1, dictionary=None):
+ self.level = level
+ self.st = _z_stream()
+ err = _zlib.deflateInit_(C.byref(self.st), self.level, ZLIB_VERSION, C.sizeof(self.st))
+ assert err == Z_OK, err # FIXME: specific error
+ if dictionary:
+ err = _zlib.deflateSetDictionary(
+ C.byref(self.st),
+ C.cast(C.c_char_p(dictionary), C.POINTER(C.c_ubyte)),
+ len(dictionary)
+ )
+ assert err == Z_OK, err # FIXME: more specific error
+
+ def __call__(self, input):
+ outbuf = C.create_string_buffer(CHUNK)
+ self.st.avail_in = len(input)
+ self.st.next_in = C.cast(C.c_char_p(input), C.POINTER(C.c_ubyte))
+ self.st.next_out = C.cast(outbuf, C.POINTER(C.c_ubyte))
+ self.st.avail_out = CHUNK
+ err = _zlib.deflate(C.byref(self.st), Z_SYNC_FLUSH)
+ if err in [Z_OK, Z_STREAM_END]:
+ return outbuf[:CHUNK-self.st.avail_out]
+ else:
+ raise AssertionError, err # FIXME: more specific errors?
+
+ def __del__(self):
+ if _zlib:
+ err = _zlib.deflateEnd(C.byref(self.st))
+# assert err == Z_OK, err # FIXME: more specific error
+
+class Decompressor(object):
+ def __init__(self, dictionary=None):
+ self.dictionary = dictionary
+ self.st = _z_stream()
+ err = _zlib.inflateInit2_(C.byref(self.st), 15, ZLIB_VERSION, C.sizeof(self.st))
+ assert err == Z_OK, err # FIXME: more specific error
+
+ def __call__(self, input):
+ outbuf = C.create_string_buffer(CHUNK)
+ self.st.avail_in = len(input)
+ self.st.next_in = C.cast(C.c_char_p(input), C.POINTER(C.c_ubyte))
+ self.st.avail_out = CHUNK
+ self.st.next_out = C.cast(outbuf, C.POINTER(C.c_ubyte))
+ err = _zlib.inflate(C.byref(self.st), Z_SYNC_FLUSH)
+ if err == Z_NEED_DICT:
+ assert self.dictionary, "no dictionary provided" # FIXME: more specific error
+ dict_id = _zlib.adler32(
+ 0L,
+ C.cast(C.c_char_p(self.dictionary), C.POINTER(C.c_ubyte)),
+ len(self.dictionary)
+ )
+# assert dict_id == self.st.adler, 'incorrect dictionary (%s != %s)' % (dict_id, self.st.adler)
+ err = _zlib.inflateSetDictionary(
+ C.byref(self.st),
+ C.cast(C.c_char_p(self.dictionary), C.POINTER(C.c_ubyte)),
+ len(self.dictionary)
+ )
+ assert err == Z_OK, err # FIXME: more specific error
+ err = _zlib.inflate(C.byref(self.st), Z_SYNC_FLUSH)
+ if err in [Z_OK, Z_STREAM_END]:
+ return outbuf[:CHUNK-self.st.avail_out]
+ else:
+ raise AssertionError, err # FIXME: more specific error
+
+ def __del__(self):
+ if _zlib:
+ err = _zlib.inflateEnd(C.byref(self.st))
+ assert err == Z_OK, err # FIXME: more specific error
Oops, something went wrong.

0 comments on commit d29d366

Please sign in to comment.