Sunshowers: Web Sockets for Ruby, Rack+Rainbows!

This project is currently unmaintained. We will pick it up again when the WebSockets protocol is stable, finalized and implemented on major browsers. Otherwise don’t waste your time.

Sunshowers is a Ruby library for Web Sockets. It exposes an easy-to-use API that may be used in both clients and servers. On the server side, it is designed to work with Rack::Request and Rainbows! (<= 3.0.0) concurrency models that expose a synchronous application flow. On the client side, it may be used as a standalone wrapper for IO-like objects.

Features

• supports reads and writes of both UTF-8 and binary Web Socket frames

• compatible with Revactor, Rainbows::Fiber::IO and core Ruby IO objects

• pure Ruby implementation, should be highly portable, tested under 1.9

License

Sunshowers is copyright 2009 by all contributors (see logs in git).

Sunshowers is 100% Free Software and licensed under the same terms as Ruby (GPL2 + Ruby License). See the LICENSE file for more details.

Install

You may download the tarball from the Rainbows! project page on Rubyforge and run setup.rb after unpacking it:

rubyforge.org/frs/?group_id=8977

You may also install it via RubyGems on Gemcutter:

gem install sunshowers

Usage

Make sure you’re using the Rainbows! (or Zbatery) web server with one of the following concurrency models:

• FiberSpawn

• FiberPool

• Revactor

• ThreadSpawn

• ThreadPool

• RevFiberSpawn

  # A simple echo server example
  require "sunshowers"
  use Rack::ContentLength
  use Rack::ContentType
  run lambda { |env|
    req = Sunshowers::Request.new(env)
    if req.ws?
      req.ws_handshake!
      ws_io = req.ws_io
      ws_io.each do |record|
        ws_io.write_utf8(record)
        break if record == "Goodbye"
      end
      req.ws_quit! # Rainbows! should handle this quietly
    end
    [404, {}, []]
  }

Already using a Rack::Request-derived class? Sunshowers::WebSocket may also be included in any Rack::Request-derived class, so you can just open it up and include it:

class Sinatra::Request < Rack::Request
  include Sunshowers::WebSocket
end

See the examples/ directory in the source tree for a client example.

Disclaimer

There is NO WARRANTY whatsoever if anything goes wrong, but let us know and we’ll try our best to fix it.

This API is highly unstable and designed on a whim, so it may be completely replaced.

Development

git://git.bogomips.org/sunshowers.git
git://repo.or.cz/sunshowers.git (mirror)

You may browse the code from the web and download the latest snapshot tarballs here:

• git.bogomips.org/cgit/sunshowers.git (cgit)

• repo.or.cz/w/sunshowers.git (gitweb)

Inline patches (from “git format-patch”) to the mailing list are preferred because they allow code review and comments in the reply to the patch.

We will adhere to mostly the same conventions for patch submissions as git itself. See the Documentation/SubmittingPatches document distributed with git on on patch submission guidelines to follow. Just don’t email the git mailing list or maintainer with Sunshowers patches.

Contact

All feedback (bug reports, user/development discussion, patches, pull requests) go to the mailing list/newsgroup. Do not send HTML mail, do not top post.

• sunshowers@librelist.com

[Validate]

Generated with the Darkfish Rdoc Generator 2.