README

   1 yahns - sleepy, multi-threaded, non-blocking application server for Ruby
   2 ------------------------------------------------------------------------
   3
   4 A Free Software, multi-threaded, non-blocking network application server
   5 designed for low _idle_ power consumption.  It is primarily optimized
   6 for applications with occasional users which see little or no traffic.
   7 yahns currently hosts Rack/HTTP applications, but may eventually support
   8 other application types.  Unlike some existing servers, yahns is
   9 extremely sensitive to fatal bugs in the applications it hosts.
  10
  11 Features
  12 --------
  13
  14 * _zero_ wakeups when all clients are idle
  15 * idle client connections may live forever if there is no FD pressure
  16 * suitable for slow clients, fast clients, or a mixture of both
  17 * HTTP/0.9 support
  18 * HTTP/1.1 persistent connections and pipelining
  19 * HTTPS for HTTP/1.1 support
  20 * decodes HTTP chunked encoding for requests
  21 * parses HTTP/1.1 trailers in requests
  22 * supports streaming responses with lazy buffering for slow clients
  23 * optional streaming input for fast clients
  24 * able to host multiple applications with different settings
  25 * uses epoll/kqueue to scale to many idle connections
  26 * abuses epoll/kqueue as a load balancer between threads within a process
  27 * optional multi-process support (in addition to threads)
  28 * fairly balances new clients between multiple processes (on Linux)
  29
  30 Disclaimer
  31 ----------
  32
  33 yahns is extremely sensitive to fatal bugs in the apps it hosts.  There
  34 is no (and never will be) any built-in "watchdog"-type feature to kill
  35 stuck processes/threads.  Each yahns process may be handling thousands
  36 of clients; unexpectedly killing the process will abort _all_ of those
  37 connections.  Lives may be lost!
  38
  39 yahns hackers are not responsible for your application/library bugs.
  40 Use an application server which is tolerant of buggy applications
  41 if you cannot be bothered to fix all your fatal bugs.
  42
  43 Supported Platforms
  44 -------------------
  45
  46 yahns is developed primarily for modern GNU/Linux systems.
  47
  48 We support kqueue on FreeBSD (and possibly OpenBSD and NetBSD).
  49 Non-Free systems/dependencies will never be supported.
  50
  51 Supported Ruby implementations:
  52 * (Matz) Ruby 2.0.0 and later (we develop (and host our website) on trunk)
  53
  54 Contact
  55 -------
  56
  57 We are happy to see feedback of all types via plain-text email.
  58 Please send comments, user/dev discussion, patches, bug reports,
  59 and pull requests to our public inbox at:
  60
  61         yahns-public@yhbt.net
  62
  63 Please use reply-to-all as we do not require any sort of subscription.
  64 We archive all of our mail publically at:
  65
  66         https://yhbt.net/yahns-public/
  67         nntp://news.public-inbox.org/inbox.comp.lang.ruby.yahns
  68
  69 Atom feed: https://yhbt.net/yahns-public/new.atom
  70
  71 This README is our homepage, we would rather be working on HTTP servers
  72 all day than worrying about the next browser vulnerability because
  73 HTML/CSS/JS is too complicated for us.
  74
  75 * https://yhbt.net/yahns.git/about/
  76
  77 Hacking
  78 -------
  79
  80 We use git and follow the same development model as git itself
  81 (email-oriented, benevolent dictator).
  82
  83         git clone https://yhbt.net/yahns.git
  84
  85 Please use git-format-patch(1) and git-send-email(1) distributed with
  86 the git(7) suite for generating and sending patches.  Please format
  87 pull requests with the git-request-pull(1) script (also distributed
  88 with git(7)) and send them via email.
  89
  90 See https://www.git-scm.com/ for more information on git.
  91
  92 Design
  93 ------
  94
  95 yahns is designed to optimally use multiple threads with non-blocking I/O.
  96 The event loop is not a traditional single-threaded design with a mutex
  97 slapped on as an afterthought, but designed from the beginning to utilize
  98 multiple threads.
  99
 100 * two classes of long-lived, persistent threads
 101   1. blocking acceptors
 102   2. non-blocking event loop workers
 103 * epoll (or kqueue) acts as a queue (by using one-shot notifications)
 104 * acceptors accept new clients and put them in the queue
 105 * workers pull clients off the queue, rearming them to epoll on EAGAIN
 106
 107 The end result is clients transition freely and fairly between threads
 108 and will always be able to find the next idle thread to run on.
 109
 110 The design inspiration from the name "kqueue" when working on another
 111 project.
 112
 113 In addition to multiple threads, yahns optionally supports multiple
 114 processes to work around low FD limits as well as contention in the:
 115
 116 * kernel (socket (de)allocation from accept/close, mmap/sbrk locks)
 117 * standard C library (malloc/free)
 118 * Ruby VM (GVL, GC)
 119 * application it hosts
 120
 121 Copyright
 122 ---------
 123
 124 Copyright 2013-2016, all contributors (see git repo).
 125 License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
 126
 127 yahns is copyrighted Free Software by all contributors, see logs in
 128 revision control for names and email addresses of all of them.  yahns
 129 contains code from Mongrel, unicorn, and Rainbows! which may also be
 130 licensed under the GPLv2 or later.
 131
 132 yahns is free software; you can redistribute it and/or modify it
 133 under the terms of the GNU General Public License as published by the
 134 Free Software Foundation; either version 3 of the License, or (at your
 135 option) any later version.
 136
 137 yahns is distributed in the hope that it will be useful, but WITHOUT ANY
 138 WARRANTY; without even the implied warranty of MERCHANTABILITY or
 139 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 140 for more details.
 141
 142 You should have received a copy of the GNU General Public License along
 143 with this program; if not, see https://www.gnu.org/licenses/gpl-3.0.txt
 144
 145 Additional permission under GNU GPL version 3 section 7:
 146
 147     If you modify this program, or any covered work, by linking or
 148     combining it with the OpenSSL project's OpenSSL library (or a
 149     modified version of that library), containing parts covered by the
 150     terms of the OpenSSL or SSLeay licenses, the copyright holder(s)
 151     grants you additional permission to convey the resulting work.
 152     Corresponding Source for a non-source form of such a combination
 153     shall include the source code for the parts of OpenSSL used as well
 154     as that of the covered work.
 155
 156 lrg nabgure ubeevoyl-anzrq freire :>