README

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