[ANN/RFC] LMGTWTY - Web Sockets for Rack+Rainbows!

[Eric Wong <normalperson@yhbt.net>]

Hi all,

I've started getting Web Sockets going for Rainbows! (git version-only).

If people like it, maybe this can be put into Rack itself (and it'll
have a better name and more exposure).

=== Demo first

Just grab the echo_client.py from pywebsocket here:
  http://pywebsocket.googlecode.com/svn/trunk/src/example/echo_client.py
  (tested with r139)

And run:
$ python echo_client.py -p 9999 -s yhbt.net
$ python echo_client.py -p 9999 -s yhbt.net -m "hello,world"
...

== Code

  http://git.bogomips.org/cgit/lmgtwty.git
  git://git.bogomips.org/lmgtwty.git
  # s/lmgtwty/rainbows/ to get rainbows.git

The only change Rainbows! I made is to expose the client IO object via:

  # if it becomes part of the Rack spec, then s/h/r/ :>
  env["hack.io"] = client

Right now, env["hack.io"] needs to respond to #readpartial and #write
(so it's compatible with core Ruby IO objects and also with
Rainbows::Fiber::IO).

== LMGTWTY code walk-through

The entirety of LMGTWTY was done on a whim way past my normal bedtime.
Feedback on design/code/semantics would be greatly appreciated.

=== Lmgtwty::IO is a wrapper for the "raw" env["hack.io"] object

It responds to #gets and #write while encoding/decoding the
WebSocket framing transparently to the application.

For reading, Lmgtwty::IO#gets() returns a single web socket frame.
So it removes the first and last bytes of (\x00 frame \xff)

For writing, Lmgtwty::IO#write(buf) - writes the contents of +buf+ to
the client socket, transparently framing it with "\x00" and "\xff"
bytes.

=== Lmgtwty::Request is a subclass of Rack::Request

It adds a few helper methods to handle handshaking and using
Lmgtwty::IO.

Handshaking/responses can't be reliably done with the normal Rack
resmost Rack servers/handlers yet because client (and last I checked,
the RFC) currently rely on a hard-coded response where case-sensitivity
and header order matters(!).

Web Sockets does NOT use HTTP chunked encoding, so the normal TeeInput
class in Unicorn/Rainbows! won't work.  Also the rewindable requirement
of "rack.input" gives it unnecessary overhead for long-running requests.

The handshake uses the "raw" env["hack.io"] object for writes,
afterwards using the Lmgtwty::IO-wrapped version of env["hack.io"] is
required for framing/deframing Web Socket messages.

== Caveats

* Web Sockets is still evolving quickly and may change incompatibly...

* iobuffer is a C extension gem dependency, I expect replacing it with
  a pure Ruby Array of Strings with minimal/no performance loss since
  the Strings are expected to be short anyways.

* I've only tested this with the python command-line client.  I
  avoid GUIs as much as possible and using Chrome at this stage
  (without a Vimperator equivalent) would cause me too much pain.

-- 
Eric Wong