README

   1 = Rainbows! - Rack app server for sleepy apps and slow clients
   2
   3 \Rainbows! is an HTTP server for sleepy Rack applications.  It is based on
   4 unicorn, but designed to handle applications that expect long
   5 request/response times and/or slow clients.
   6
   7 If you're on GNU/Linux and overwhelmed by options in \Rainbows!,
   8 consider {yahns}[https://yhbt.net/yahns/] as it has fewer options
   9 and more energy-efficient during non-peak traffic and may also
  10 be configured as a single worker process.
  11
  12 For Rack applications not heavily bound by slow external network
  13 dependencies, consider unicorn instead as it simpler and easier to
  14 debug.
  15
  16 == \Rainbows! is about Diversity
  17
  18 We aim to support as many concurrency models as we can because they all
  19 suck; differently.
  20
  21 For network concurrency, models we currently support are:
  22
  23 * {Coolio}[link:Rainbows/Coolio.html]
  24 * {CoolioFiberSpawn}[link:Rainbows/CoolioFiberSpawn.html]
  25 * {CoolioThreadPool}[link:Rainbows/CoolioThreadPool.html]
  26 * {CoolioThreadSpawn}[link:Rainbows/CoolioThreadSpawn.html]
  27 * {Epoll}[link:Rainbows/Epoll.html]
  28 * {EventMachine}[link:Rainbows/EventMachine.html]
  29 * {FiberPool}[link:Rainbows/FiberPool.html]
  30 * {FiberSpawn}[link:Rainbows/FiberSpawn.html]
  31 * {NeverBlock}[link:Rainbows/NeverBlock.html]
  32 * {Revactor}[link:Rainbows/Revactor.html]
  33 * {ThreadPool}[link:Rainbows/ThreadPool.html]
  34 * {ThreadSpawn}[link:Rainbows/ThreadSpawn.html]
  35 * {WriterThreadPool}[link:Rainbows/WriterThreadPool.html]
  36 * {WriterThreadSpawn}[link:Rainbows/WriterThreadSpawn.html]
  37 * {XEpoll}[link:Rainbows/XEpoll.html]
  38 * {XEpollThreadPool}[link:Rainbows/XEpollThreadPool.html]
  39 * {XEpollThreadSpawn}[link:Rainbows/XEpollThreadSpawn.html]
  40
  41 We have {many more on the way}[link:TODO.html] for handling network
  42 concurrency.  Additionally, we also use multiple processes (managed by
  43 Unicorn) for robustness and CPU/memory/disk concurrency.
  44
  45 We also provide Rainbows::AppPool Rack middleware for some network
  46 concurrency models for limiting application concurrency independently of
  47 network concurrency.
  48
  49 == Features
  50
  51 * Designed for {Rack}[http://rack.github.io/], the standard for
  52   modern Ruby HTTP applications.
  53
  54 * Built on {unicorn}[https://yhbt.net/unicorn/], inheriting its
  55   process/socket management features such as transparent upgrades and
  56   Ruby configuration DSL.
  57
  58 * As with Unicorn, it is able to stream large request bodies off the
  59   socket to the application while the client is still uploading.  Since
  60   \Rainbows! can handle slow clients, this feature is more useful than
  61   it is with Unicorn.
  62
  63 * Combines heavyweight concurrency (worker processes) with lightweight
  64   concurrency (Events/Fibers/Actors/Threads), allowing CPU/memory/disk to
  65   be scaled independently of client connections.  More concurrency models
  66   (listed in the TODO) will be supported as we find time for them.
  67
  68 * We give you {lots of options}[link:Summary.html] with more
  69   {on the way}[link:TODO.html].
  70
  71 == Applications
  72
  73 \Rainbows! is mainly designed for the odd things Unicorn sucks at:
  74
  75 * 3rd-party APIs (to services outside your control/LAN)
  76 * OpenID consumers (to providers outside your control/LAN)
  77 * Reverse proxy implementations with editing/censoring
  78   (to upstreams outside your control/LAN)
  79 * Comet
  80 * BOSH (with slow clients)
  81 * HTTP server push
  82 * Long polling
  83 * Reverse AJAX
  84
  85 \Rainbows! can also be used to service slow clients directly even with
  86 fast applications.
  87
  88 == License
  89
  90 \Rainbows! is copyright 2009,2010 by all contributors (see logs in git).
  91 \Rainbows! is licensed under the Ruby (1.8) license or the GPLv2 or later.
  92 See the included {LICENSE}[link:LICENSE.html] file for more details.
  93
  94 \Rainbows! is 100% Free Software.
  95
  96 == Install
  97
  98 You may install it via RubyGems on RubyGems.org:
  99
 100   gem install rainbows
 101
 102 == Usage
 103
 104 === for Rack applications
 105
 106 In APP_ROOT (where config.ru is located), run:
 107
 108   rainbows
 109
 110 \Rainbows! will bind to all interfaces on TCP port 8080 by default.
 111
 112 === Configuration File(s)
 113
 114 \Rainbows! will look for the config.ru file used by rackup in APP_ROOT.
 115
 116 For deployments, it can use a config file for Unicorn and
 117 \Rainbows!-specific options specified by the +--config-file/-c+
 118 command-line switch.  \Rainbows! accepts all options found in
 119 {Unicorn::Configurator}[https://yhbt.net/unicorn/Unicorn/Configurator.html]
 120 as well as the "\Rainbows!" block, so you can have the following in your
 121 config file:
 122
 123     worker_processes 4 # assuming four CPU cores
 124     Rainbows! do
 125       use :ThreadSpawn
 126       worker_connections 100
 127     end
 128
 129 See the {Rainbows! configuration}[link:Rainbows/Configurator.html]
 130 {documentation}[link:Rainbows/Configurator.html]
 131 for more details.
 132
 133 == Development
 134
 135 You can get the latest source via git from the following locations
 136 (these versions may not be stable):
 137
 138   https://yhbt.net/rainbows.git
 139   https://repo.or.cz/rainbows.git (mirror)
 140
 141 You may browse the code from the web and download the latest snapshot
 142 tarballs here:
 143
 144 * https://yhbt.net/rainbows.git
 145 * https://repo.or.cz/rainbows.git (gitweb)
 146
 147 Inline patches (from "git format-patch") to the mailing list are
 148 preferred because they allow code review and comments in the reply to
 149 the patch.
 150
 151 We will adhere to mostly the same conventions for patch submissions as
 152 git itself.  See the
 153 https://80x24.org/mirrors/git.git/tree/Documentation/SubmittingPatches?h=v2.20.1
 154 document distributed with git on on patch submission guidelines to follow.
 155 Just don't email the git mailing list or maintainer with \Rainbows! patches.
 156
 157 == Disclaimer
 158
 159 There is NO WARRANTY whatsoever if anything goes wrong, but let us know
 160 and we'll try our best to fix it.
 161
 162 Rainbows! is extremely sensitive to fatal bugs in the apps it hosts.
 163 Each Rainbows! worker process may be handling thousands of clients;
 164 unexpectedly killing the process will abort _all_ of those
 165 connections.  Lives may be lost!
 166
 167 Rainbows! hackers are not responsible for your application/library bugs.
 168 Use an application server which is tolerant of buggy applications
 169 if you cannot be bothered to fix all your fatal bugs.
 170
 171 == Contact
 172
 173 All feedback (bug reports, user/development discussion, patches, pull
 174 requests) go to the mailing list.  Patches must be sent inline
 175 (git format-patch -M + git send-email).  No subscription is necessary
 176 to post on the mailing list.  No top posting.
 177
 178 * email: mailto:rainbows-public@yhbt.net
 179 * subscribe: mailto:rainbows-public+subscribe@yhbt.net
 180 * archives: https://yhbt.net/rainbows-public/
 181   http://ou63pmih66umazou.onion/rainbows-public/
 182   nntp://news.public-inbox.org/inbox.comp.lang.ruby.rainbows
 183   nntp://ou63pmih66umazou.onion/inbox.comp.lang.ruby.rainbows
 184   nntp://news.gmane.io/gmane.comp.lang.ruby.rainbows.general