README

   1 = Sunshowers: Web Sockets for Ruby, Rack+Rainbows!
   2
   3 Sunshowers is a Ruby library for Web Sockets.  It exposes an easy-to-use
   4 API that may be used in both clients and servers.  On the server side,
   5 it is designed to work with Rack::Request and Rainbows! concurrency
   6 models that expose a synchronous application flow.  On the client side,
   7 it may be used as a standalone wrapper for IO-like objects.
   8
   9 It appears works well with the echo_client.py example shipped with
  10 pywebsocket.  It has not been tested against normal web browsers, though
  11 there's no reason it shouldn't work.
  12
  13 == Features
  14
  15 * supports reads and writes of both UTF-8 and binary Web Socket frames
  16
  17 * compatible with Revactor, Rainbows::Fiber::IO and core Ruby IO objects
  18
  19 * pure Ruby implementation, should be highly portable, tested under 1.9
  20
  21 == License
  22
  23 Sunshowers is copyright 2009 by all contributors (see logs in git).
  24
  25 Sunshowers is 100% Free Software and licensed under the same terms
  26 as Ruby (GPL2 + Ruby License).  See the LICENSE file for more
  27 details.
  28
  29 == Install
  30
  31 You may download the tarball from the Rainbows! project page on Rubyforge
  32 and run setup.rb after unpacking it:
  33
  34 http://rubyforge.org/frs/?group_id=8977
  35
  36 You may also install it via RubyGems on Gemcutter:
  37
  38   gem install sunshowers
  39
  40 == Usage
  41
  42 Make sure you're using one of the following concurrency models
  43 for Rainbows!:
  44
  45 * FiberSpawn
  46 * FiberPool
  47 * Revactor
  48 * ThreadSpawn
  49 * ThreadPool
  50 * RevFiberSpawn (Rainbows! v0.90.0 or later)
  51
  52     # A simple echo server example
  53     require "sunshowers"
  54     use Rack::ContentLength
  55     use Rack::ContentType
  56     run lambda { |env|
  57       req = Sunshowers::Request.new(env)
  58       if req.ws?
  59         req.ws_handshake!
  60         ws_io = req.ws_io
  61         ws_io.each do |record|
  62           ws_io.write_utf8(record)
  63           break if record == "Goodbye"
  64         end
  65         req.ws_quit! # Rainbows! should handle this quietly
  66       end
  67       [404, {}, []]
  68     }
  69
  70 Already using a Rack::Request-derived class?  Sunshowers::WebSocket may
  71 also be included in any Rack::Request-derived class, so you can just
  72 open it up and include it:
  73
  74   class Sinatra::Request < Rack::Request
  75     include Sunshowers::WebSocket
  76   end
  77
  78 See the examples/ directory in the source tree for a client example.
  79
  80 == Disclaimer
  81
  82 There is NO WARRANTY whatsoever if anything goes wrong, but let us know
  83 and we'll try our best to fix it.
  84
  85 This API is highly unstable and designed on a whim, so it may be
  86 completely replaced.
  87
  88 == Development
  89
  90   git://git.bogomips.org/sunshowers.git
  91   git://repo.or.cz/sunshowers.git (mirror)
  92
  93 You may browse the code from the web and download the latest snapshot
  94 tarballs here:
  95
  96 * http://git.bogomips.org/cgit/sunshowers.git (cgit)
  97 * http://repo.or.cz/w/sunshowers.git (gitweb)
  98
  99 Inline patches (from "git format-patch") to the mailing list are
 100 preferred because they allow code review and comments in the reply to
 101 the patch.
 102
 103 We will adhere to mostly the same conventions for patch submissions as
 104 git itself.  See the Documentation/SubmittingPatches document
 105 distributed with git on on patch submission guidelines to follow.  Just
 106 don't email the git mailing list or maintainer with Sunshowers patches.
 107
 108 == Contact
 109
 110 All feedback (bug reports, user/development discussion, patches, pull
 111 requests) go to the mailing list/newsgroup.  Do not send HTML mail,
 112 do not top post.
 113
 114 * mailto:sunshowers@librelist.com