unicorn-shopify 4.8.2.5.23

data/ISSUES

@@ -0,0 +1,100 @@
+= Issues
+
+mailto:unicorn-public@bogomips.org is the best place to report bugs,
+submit patches and/or obtain support after you have searched the
+{email archives}[http://bogomips.org/unicorn-public/] and
+{documentation}[http://unicorn.bogomips.org/].
+
+* No subscription will ever be required to email the public inbox.
+* Cc: all participants in a thread or commit, as subscription is optional
+* Do not {top post}[http://catb.org/jargon/html/T/top-post.html] in replies
+* Quote as little as possible of the message you're replying to
+* Do not send HTML mail, it will likely be flagged as spam
+
+If your issue is of a sensitive nature or you're just shy in public,
+then feel free to email us privately at mailto:unicorn@bogomips.org
+instead and your issue will be handled discreetly.
+
+If you don't get a response within a few days, we may have forgotten
+about it so feel free to ask again.
+
+== Bugs in related projects
+
+unicorn is sometimes affected by bugs in its dependencies.  Bugs
+triggered by unicorn in mainline Ruby, rack, GNU C library (glibc),
+or the Linux kernel will be reported upstream and fixed.
+
+For bugs in Ruby itself, we may forward bugs to
+https://bugs.ruby-lang.org/ and discuss+fix them on the ruby-core
+list at mailto:ruby-core@ruby-lang.org
+Subscription to post is required to ruby-core, unfortunately:
+mailto:ruby-core-request@ruby-lang.org?subject=subscribe
+
+For uncommon bugs in Rack, we may forward bugs to
+mailto:rack-devel@googlegroups.com and discuss there.
+Subscription (without any web UI or Google account) is possible via:
+mailto:rack-devel+subscribe@googlegroups.com
+Note: not everyone can use the proprietary bug tracker used by Rack,
+but their mailing list remains operational.
+
+Uncommon bugs we encounter in the Linux kernel should be Cc:-ed to the
+Linux kernel mailing list (LKML) at mailto:linux-kernel@vger.kernel.org
+and subsystem maintainers such as mailto:netdev@vger.kernel.org
+(for networking issues).  It is expected practice to Cc: anybody
+involved with any problematic commits (including those in the
+Signed-off-by: and other trailer lines).  No subscription is necessary,
+and the our mailing list follows the same conventions as LKML for
+interopability.  There is a kernel.org Bugzilla instance, but it is
+ignored by most developers.
+
+Likewise for any rare glibc bugs we might encounter, we should Cc:
+mailto:libc-alpha@sourceware.org
+Keep in mind glibc upstream does use Bugzilla for tracking bugs:
+https://sourceware.org/bugzilla/
+
+== Submitting Patches
+
+See the HACKING document (and additionally, the
+{SubmittingPatches}[https://git.kernel.org/cgit/git/git.git/tree/Documentation/SubmittingPatches]
+document distributed with git) on guidelines for patch submission.
+
+== Contact Info
+
+* public: mailto:unicorn-public@bogomips.org
+* private: mailto:unicorn@bogomips.org
+
+We operate a {public-inbox}[http://public-inbox.org/] which
+feeds the mailing list.  You may subscribe either using
+{ssoma}[http://ssoma.public-inbox.org/] or by sending a mail
+to mailto:unicorn-public+subscribe@bogomips.org
+
+ssoma is a mail archiver/fetcher using git.  It operates in a similar
+fashion to tools such as slrnpull, fetchmail, or getmail.  ssoma
+subscription instructions:
+
+	URL=git://bogomips.org/unicorn-public
+	LISTNAME=unicorn
+
+	# to initialize a maildir (this may be a new or existing maildir,
+	# ssoma will not touch existing messages)
+	# If you prefer mbox, use mbox:/path/to/mbox as the last argument
+	# You may also use imap://$MAILSERVER/INBOX for an IMAP account
+	# or imaps:// for an IMAPS account, as well.
+	ssoma add $LISTNAME $URL maildir:/path/to/maildir
+
+	# read with your favorite MUA (only using mutt as an example)
+	mutt -f /path/to/maildir # (or /path/to/mbox)
+
+	# to keep your mbox or maildir up-to-date, periodically run the following:
+	ssoma sync $LISTNAME
+
+	# your MUA may modify and delete messages from the maildir or mbox,
+	# this does not affect ssoma functionality at all
+
+	# to sync all your ssoma subscriptions
+	ssoma sync
+
+	# You may wish to sync in your cronjob
+	ssoma sync --cron
+
+HTML archives are available here: http://bogomips.org/unicorn-public/

data/KNOWN_ISSUES

@@ -0,0 +1,79 @@
+= Known Issues
+
+Occasionally odd {issues}[link:ISSUES.html] arise without a transparent or
+acceptable solution.  Those issues are documented here.
+
+* Some libraries/applications may install signal handlers which conflict
+  with signal handlers unicorn uses.  Leaving "preload_app false"
+  (the default) will allow unicorn to always override existing signal
+  handlers.
+
+* Issues with FreeBSD jails can be worked around as documented by Tatsuya Ono:
+  http://mid.gmane.org/CAHBuKRj09FdxAgzsefJWotexw-7JYZGJMtgUp_dhjPz9VbKD6Q@mail.gmail.com
+
+* PRNGs (pseudo-random number generators) loaded before forking
+  (e.g. "preload_app true") may need to have their internal state
+  reset in the after_fork hook.  Starting with \Unicorn 3.6.1, we
+  have builtin workarounds for Kernel#rand and OpenSSL::Random users,
+  but applications may use other PRNGs.
+
+* For notes on sandboxing tools such as Bundler or Isolate,
+  see the {Sandbox}[link:Sandbox.html] page.
+
+* nginx with "sendfile on" under FreeBSD 8 is broken when
+  uploads are buffered to disk.  Disabling sendfile is required to
+  work around this bug which should be fixed in newer versions of FreeBSD.
+
+* When using "preload_app true", with apps using background threads
+  need to restart them in the after_fork hook because threads are never
+  shared with child processes.  Additionally, any synchronization
+  primitives (Mutexes, Monitors, ConditionVariables) should be
+  reinitialized in case they are held during fork time to avoid
+  deadlocks.  The core Ruby Logger class needlessly uses a MonitorMutex
+  which can be disabled with a {monkey patch}[link:examples/logger_mp_safe.rb]
+
+== Known Issues (Old)
+
+* Under some versions of Ruby 1.8, it is necessary to call +srand+ in an
+  after_fork hook to get correct random number generation.  We have a builtin
+  workaround for this starting with \Unicorn 3.6.1
+
+  See http://redmine.ruby-lang.org/issues/show/4338
+
+* On Ruby 1.8 prior to Ruby 1.8.7-p248, *BSD platforms have a broken
+  stdio that causes failure for file uploads larger than 112K.  Upgrade
+  your version of Ruby or continue using Unicorn 1.x/3.4.x.
+
+* Under Ruby 1.9.1, methods like Array#shuffle and Array#sample will
+  segfault if called after forking.  Upgrade to Ruby 1.9.2 or call
+  "Kernel.rand" in your after_fork hook to reinitialize the random
+  number generator.
+
+  See http://redmine.ruby-lang.org/issues/show/2962 for more details
+
+* Rails 2.3.2 bundles its own version of Rack.  This may cause subtle
+  bugs when simultaneously loaded with the system-wide Rack Rubygem
+  which Unicorn depends on.  Upgrading to Rails 2.3.4 (or later) is
+  strongly recommended for all Rails 2.3.x users for this (and security
+  reasons).  Rails 2.2.x series (or before) did not bundle Rack and are
+  should be unnaffected.  If there is any reason which forces your
+  application to use Rails 2.3.2 and you have no other choice, then
+  you may edit your Unicorn gemspec and remove the Rack dependency.
+
+  ref: http://mid.gmane.org/20091014221552.GA30624@dcvr.yhbt.net
+  Note: the workaround described in the article above only made
+  the issue more subtle and we didn't notice them immediately.
+
+* WONTFIX: code reloading and restarts with Sinatra 0.3.x (and likely older
+  versions) apps is broken.  The workaround is to force production
+  mode to disable code reloading as well as disabling "run" in your
+  Sinatra application:
+    set :env, :production
+    set :run, false
+  Since this is no longer an issue with Sinatra 0.9.x apps, this will not be
+  fixed on our end.  Since Unicorn is itself the application launcher, the
+  at_exit handler used in old Sinatra always caused Mongrel to be launched
+  whenever a Unicorn worker was about to exit.
+
+  Also remember we're capable of replacing the running binary without dropping
+  any connections regardless of framework :)

data/LICENSE

@@ -0,0 +1,67 @@
+Unicorn is copyrighted free software by all contributors, see logs in
+revision control for names and email addresses of all of them.
+
+You can redistribute it and/or modify it under either the terms of the
+GNU General Public License (GPL) as published by the Free Software
+Foundation (FSF), either version 2 of the License, or (at your option)
+any later version.  We currently prefer the GPLv3 or later for
+derivative works, but the GPLv2 is fine.
+
+The complete texts of the GPLv2 and GPLv3 are below:
+GPLv2 - http://www.gnu.org/licenses/gpl-2.0.txt
+GPLv3 - http://www.gnu.org/licenses/gpl-3.0.txt
+
+You may (against our _preference_) also use the Ruby 1.8 license terms
+which we inherited from the original Mongrel project when we forked it:
+
+=== Ruby 1.8-specific terms (if you're not using the GPL)
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise make them
+       Freely Available, such as by posting said modifications to Usenet or an
+       equivalent medium, or by allowing the author to include your
+       modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict with
+       standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+       together with instructions (in the manual page or equivalent) on where
+       to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of the
+       software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under this terms.
+
+  5. The scripts and library files supplied as input to or produced as
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them,
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/Links

@@ -0,0 +1,59 @@
+= Related Projects
+
+If you're interested in \Unicorn, you may be interested in some of the projects
+listed below.  If you have any links to add/change/remove, please tell us at
+mailto:unicorn-public@bogomips.org!
+
+== Disclaimer
+
+The \Unicorn project is not responsible for the content in these links.
+Furthermore, the \Unicorn project has never, does not and will never endorse:
+
+* any for-profit entities or services
+* any non-{Free Software}[http://www.gnu.org/philosophy/free-sw.html]
+
+The existence of these links does not imply endorsement of any entities
+or services behind them.
+
+=== For use with \Unicorn
+
+* {Bluepill}[https://github.com/arya/bluepill] -
+  a simple process monitoring tool written in Ruby
+
+* {golden_brindle}[https://github.com/simonoff/golden_brindle] - tool to
+  manage multiple \Unicorn instances/applications on a single server
+
+* {raindrops}[http://raindrops.bogomips.org/] - real-time stats for
+  preforking Rack servers
+
+* {UnXF}[http://bogomips.org/unxf/]  Un-X-Forward* the Rack environment,
+  useful since unicorn is designed to be deployed behind a reverse proxy.
+
+=== \Unicorn is written to work with
+
+* {Rack}[http://rack.github.io/] - a minimal interface between webservers
+  supporting Ruby and Ruby frameworks
+
+* {Ruby}[http://www.ruby-lang.org/] - the programming language of Rack and \Unicorn
+
+* {nginx}[http://nginx.org/] - the reverse proxy for use with \Unicorn
+
+* {kgio}[http://bogomips.org/kgio/] - the I/O library written for \Unicorn
+
+=== Derivatives
+
+* {Green Unicorn}[http://gunicorn.org/] - a Python version of \Unicorn
+
+* {Rainbows!}[http://rainbows.bogomips.org/] - \Unicorn for sleepy
+  apps and slow clients (historical).
+
+* {yahns}[http://yahns.yhbt.net/] - like Rainbows!, but with fewer options
+  and designed for energy efficiency on idle sites.
+
+=== Prior Work
+
+* {Mongrel}[http://rubygems.org/gems/mongrel] - the awesome webserver
+  unicorn is based on
+
+* {david}[http://bogomips.org/david.git] - a tool to explain why you need
+  nginx in front of \Unicorn

data/PHILOSOPHY

@@ -0,0 +1,145 @@
+= The Philosophy Behind unicorn
+
+Being a server that only runs on Unix-like platforms, unicorn is
+strongly tied to the Unix philosophy of doing one thing and (hopefully)
+doing it well.  Despite using HTTP, unicorn is strictly a _backend_
+application server for running Rack-based Ruby applications.
+
+== Avoid Complexity
+
+Instead of attempting to be efficient at serving slow clients, unicorn
+relies on a buffering reverse proxy to efficiently deal with slow
+clients.
+
+unicorn uses an old-fashioned preforking worker model with blocking I/O.
+Our processing model is the antithesis of more modern (and theoretically
+more efficient) server processing models using threads or non-blocking
+I/O with events.
+
+=== Threads and Events Are Hard
+
+...to many developers.  Reasons for this is beyond the scope of this
+document.  unicorn avoids concurrency within each worker process so you
+have fewer things to worry about when developing your application.  Of
+course unicorn can use multiple worker processes to utilize multiple
+CPUs or spindles.  Applications can still use threads internally, however.
+
+== Slow Clients Are Problematic
+
+Most benchmarks we've seen don't tell you this, and unicorn doesn't
+care about slow clients... but <i>you</i> should.
+
+A "slow client" can be any client outside of your datacenter.  Network
+traffic within a local network is always faster than traffic that
+crosses outside of it.  The laws of physics do not allow otherwise.
+
+Persistent connections were introduced in HTTP/1.1 reduce latency from
+connection establishment and TCP slow start.  They also waste server
+resources when clients are idle.
+
+Persistent connections mean one of the unicorn worker processes
+(depending on your application, it can be very memory hungry) would
+spend a significant amount of its time idle keeping the connection alive
+<i>and not doing anything else</i>.  Being single-threaded and using
+blocking I/O, a worker cannot serve other clients while keeping a
+connection alive.  Thus unicorn does not implement persistent
+connections.
+
+If your application responses are larger than the socket buffer or if
+you're handling large requests (uploads), worker processes will also be
+bottlenecked by the speed of the *client* connection.  You should
+not allow unicorn to serve clients outside of your local network.
+
+== Application Concurrency != Network Concurrency
+
+Performance is asymmetric across the different subsystems of the machine
+and parts of the network.  CPUs and main memory can process gigabytes of
+data in a second; clients on the Internet are usually only capable of a
+tiny fraction of that.  unicorn deployments should avoid dealing with
+slow clients directly and instead rely on a reverse proxy to shield it
+from the effects of slow I/O.
+
+== Improved Performance Through Reverse Proxying
+
+By acting as a buffer to shield unicorn from slow I/O, a reverse proxy
+will inevitably incur overhead in the form of extra data copies.
+However, as I/O within a local network is fast (and faster still
+with local sockets), this overhead is negligible for the vast majority
+of HTTP requests and responses.
+
+The ideal reverse proxy complements the weaknesses of unicorn.
+A reverse proxy for unicorn should meet the following requirements:
+
+1. It should fully buffer all HTTP requests (and large responses).
+   Each request should be "corked" in the reverse proxy and sent
+   as fast as possible to the backend unicorn processes.  This is
+   the most important feature to look for when choosing a
+   reverse proxy for unicorn.
+
+2. It should spend minimal time in userspace.  Network (and disk) I/O
+   are system-level tasks and usually managed by the kernel.
+   This may change if userspace TCP stacks become more popular in the
+   future; but the reverse proxy should not waste time with
+   application-level logic.  These concerns should be separated
+
+3. It should avoid context switches and CPU scheduling overhead.
+   In many (most?) cases, network devices and their interrupts are
+   only be handled by one CPU at a time.  It should avoid contention
+   within the system by serializing all network I/O into one (or few)
+   userspace processes.  Network I/O is not a CPU-intensive task and
+   it is not helpful to use multiple CPU cores (at least not for GigE).
+
+4. It should efficiently manage persistent connections (and
+   pipelining) to slow clients.  If you care to serve slow clients
+   outside your network, then these features of HTTP/1.1 will help.
+
+5. It should (optionally) serve static files.  If you have static
+   files on your site (especially large ones), they are far more
+   efficiently served with as few data copies as possible (e.g. with
+   sendfile() to completely avoid copying the data to userspace).
+
+nginx is the only (Free) solution we know of that meets the above
+requirements.
+
+Indeed, the folks behind unicorn have deployed nginx as a reverse-proxy not
+only for Ruby applications, but also for production applications running
+Apache/mod_perl, Apache/mod_php and Apache Tomcat.  In every single
+case, performance improved because application servers were able to use
+backend resources more efficiently and spend less time waiting on slow
+I/O.
+
+== Worse Is Better
+
+Requirements and scope for applications change frequently and
+drastically.  Thus languages like Ruby and frameworks like Rails were
+built to give developers fewer things to worry about in the face of
+rapid change.
+
+On the other hand, stable protocols which host your applications (HTTP
+and TCP) only change rarely.  This is why we recommend you NOT tie your
+rapidly-changing application logic directly into the processes that deal
+with the stable outside world.  Instead, use HTTP as a common RPC
+protocol to communicate between your frontend and backend.
+
+In short: separate your concerns.
+
+Of course a theoretical "perfect" solution would combine the pieces
+and _maybe_ give you better performance at the end of the day, but
+that is not the Unix way.
+
+== Just Worse in Some Cases
+
+unicorn is not suited for all applications.  unicorn is optimized for
+applications that are CPU/memory/disk intensive and spend little time
+waiting on external resources (e.g. a database server or external API).
+
+unicorn is highly inefficient for Comet/reverse-HTTP/push applications
+where the HTTP connection spends a large amount of time idle.
+Nevertheless, the ease of troubleshooting, debugging, and management of
+unicorn may still outweigh the drawbacks for these applications.
+
+The {Rainbows!}[http://rainbows.bogomips.org/] aims to fill the gap for
+odd corner cases where the nginx + unicorn combination is not enough.
+While Rainbows! management/administration is largely identical to
+unicorn, Rainbows! is far more ambitious and has seen little real-world
+usage.