unicorn 0.92.0 → 0.93.0

data/.document

@@ -1,10 +1,12 @@
 README
 TUNING
 PHILOSOPHY
+HACKING
 DESIGN
 CONTRIBUTORS
 LICENSE
 SIGNALS
+KNOWN_ISSUES
 TODO
 NEWS
 ChangeLog

data/.gitignore

@@ -1,6 +1,7 @@
 *.bundle
 *.log
 *.so
+*.rbc
 .DS_Store
 /.config
 /InstalledFiles

data/Documentation/unicorn.1.txt

@@ -143,6 +143,15 @@ are never loaded by default.  If needed, they should be
 individually specified in the RACKUP_FILE, some frameworks do
 not require them.
 
+# ENVIRONMENT VARIABLES
+
+All application or library-specific environment variables (e.g. TMPDIR)
+may always be set in the Unicorn CONFIG_FILE in addition to the spawning
+shell.  When transparently upgrading Unicorn, all environment variables
+set in the old master process are inherited by the new master process.
+Unicorn only uses (and will overwrite) the UNICORN_FD environment
+variable internally when doing transparent upgrades.
+
 # SEE ALSO
 
 * unicorn_rails(1)

data/Documentation/unicorn_rails.1.txt

@@ -78,6 +78,12 @@ as much as possible.
     This option only exists for compatibility with the rackup(1) command,
     use of "-l"/"\--listen" switch is recommended instead.
 
+\--path PATH
+:   Mounts the Rails application at the given PATH (instead of "/").
+    This is equivalent to setting the RAILS_RELATIVE_URL_ROOT
+    environment variable.  This is only supported under Rails 2.3
+    or later at the moment.
+
 # RUBY OPTIONS
 -e, \--eval LINE
 :   Evaluate a LINE of Ruby code.  This evaluation happens
@@ -114,6 +120,19 @@ of the default middleware for performance.
 Embedded command-line options are mostly parsed for compatibility
 with rackup(1) but strongly discouraged.
 
+# ENVIRONMENT VARIABLES
+
+The RAILS_ENV variable is set by the aforementioned \-E switch.  The
+RAILS_RELATIVE_URL_ROOT is set by the aforementioned \--path switch.
+Either of these variables may also be set in the shell or the Unicorn
+CONFIG_FILE.  All application or library-specific environment variables
+(e.g. TMPDIR, RAILS_ASSET_ID) may always be set in the Unicorn
+CONFIG_FILE in addition to the spawning shell.  When transparently
+upgrading Unicorn, all environment variables set in the old master
+process are inherited by the new master process.  Unicorn only uses (and
+will overwrite) the UNICORN_FD environment variable internally when
+doing transparent upgrades.
+
 # SIGNALS
 
 The following UNIX signals may be sent to the master process:

data/GIT-VERSION-GEN

@@ -1,7 +1,7 @@
 #!/bin/sh
 
 GVF=GIT-VERSION-FILE
-DEF_VER=v0.92.0.GIT
+DEF_VER=v0.93.0.GIT
 
 LF='
 '

data/GNUmakefile

@@ -3,8 +3,7 @@ all:: test
 ruby = ruby
 rake = rake
 ragel = ragel
-GIT_URL = $(shell git config --get remote.origin.url 2>/dev/null || \
-           echo git://git.bogomips.org/unicorn.git)
+GIT_URL = git://git.bogomips.org/unicorn.git
 RLFLAGS = -G2
 
 GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE
@@ -37,9 +36,12 @@ test_prefix = $(CURDIR)/test/install-$(RUBY_VERSION)
 ext := ext/unicorn_http
 c_files := $(ext)/unicorn_http.c $(wildcard $(ext)/*.h)
 rl_files := $(wildcard $(ext)/*.rl)
-bins := $(wildcard bin/*)
-rb_files := $(bins) $(shell find lib -type f -name '*.rb')
-inst_deps := $(c_files) $(rb_files)
+base_bins := unicorn unicorn_rails
+bins := $(addprefix bin/, $(base_bins))
+man1_bins := $(addsuffix .1, $(base_bins))
+man1_paths := $(addprefix man/man1/, $(man1_bins))
+rb_files := $(bins) $(shell find lib ext -type f -name '*.rb')
+inst_deps := $(c_files) $(rb_files) GNUmakefile test/test_helper.rb
 
 ragel: $(ext)/unicorn_http.c
 $(ext)/unicorn_http.c: $(rl_files)
@@ -56,7 +58,7 @@ http: lib/unicorn_http.$(DLEXT)
 
 $(test_prefix)/.stamp: $(inst_deps)
 	mkdir -p $(test_prefix)/.ccache
-	tar c `cat .manifest` | (cd $(test_prefix) && tar x)
+	tar c $(inst_deps) GIT-VERSION-GEN | (cd $(test_prefix) && tar x)
 	$(MAKE) -C $(test_prefix) clean
 	$(MAKE) -C $(test_prefix) http shebang
 	> $@
@@ -111,6 +113,7 @@ $(T): $(test_prefix)/.stamp
 
 install: $(bins) $(ext)/unicorn_http.c
 	$(prep_setup_rb)
+	$(RM) lib/unicorn_http.$(DLEXT)
 	$(RM) -r .install-tmp
 	mkdir .install-tmp
 	cp -p bin/* .install-tmp
@@ -132,10 +135,15 @@ clean:
 
 man:
 	$(MAKE) -C Documentation install-man
-.manifest: GIT-VERSION-FILE NEWS ChangeLog $(ext)/unicorn_http.c
-	$(MAKE) man
+
+pkg_extra := GIT-VERSION-FILE NEWS ChangeLog $(ext)/unicorn_http.c
+manifest: $(pkg_extra) man
+	$(RM) .manifest
+	$(MAKE) .manifest
+
+.manifest:
 	(git ls-files && \
-         for i in $@ $^ $(wildcard man/*/*.1); \
+         for i in $@ $(pkg_extra) $(man1_paths); \
 	 do echo $$i; done) | LC_ALL=C sort > $@+
 	cmp $@+ $@ || mv $@+ $@
 	$(RM) $@+
@@ -144,10 +152,12 @@ NEWS: GIT-VERSION-FILE
 	$(rake) -s news_rdoc > $@+
 	mv $@+ $@
 
+SINCE = 0.92.0
+ChangeLog: log_range = $(shell test -n "$(SINCE)" && echo v$(SINCE)..)
 ChangeLog: GIT-VERSION-FILE
-	@echo "ChangeLog from $(GIT_URL) ($(GIT_VERSION))" > $@+
+	@echo "ChangeLog from $(GIT_URL) ($(SINCE)..$(GIT_VERSION))" > $@+
 	@echo >> $@+
-	git log | sed -e 's/^/    /' >> $@+
+	git log $(log_range) | sed -e 's/^/    /' >> $@+
 	mv $@+ $@
 
 news_atom := http://unicorn.bogomips.org/NEWS.atom.xml
@@ -157,11 +167,12 @@ atom = <link rel="alternate" title="Atom feed" href="$(1)" \
 
 # using rdoc 2.4.1+
 doc: .document $(ext)/unicorn_http.c NEWS ChangeLog
-	> unicorn.1 && > unicorn_rails.1
+	for i in $(man1_bins); do > $$i; done
 	rdoc -Na -t "$(shell sed -ne '1s/^= //p' README)"
 	install -m644 $(shell grep '^[A-Z]' .document)  doc/
-	$(MAKE) -C Documentation install-html
-	cd doc && for i in unicorn unicorn_rails; do \
+	$(MAKE) -C Documentation install-html install-man
+	install -m644 $(man1_paths) doc/
+	cd doc && for i in $(base_bins); do \
 	  sed -e '/"documentation">/r man1/'$$i'.1.html' \
 		< $${i}_1.html > tmp && mv tmp $${i}_1.html; done
 	$(ruby) -i -p -e \
@@ -172,7 +183,7 @@ doc: .document $(ext)/unicorn_http.c NEWS ChangeLog
 	  doc/NEWS.html doc/README.html
 	$(rake) -s news_atom > doc/NEWS.atom.xml
 	cd doc && ln README.html tmp && mv tmp index.html
-	$(RM) unicorn.1 unicorn_rails.1
+	$(RM) $(man1_bins)
 
 rails_git_url = git://github.com/rails/rails.git
 rails_git := vendor/rails.git
@@ -217,14 +228,19 @@ verify:
 	test `git rev-parse --verify HEAD^0` = \
 	     `git rev-parse --verify refs/tags/v$(VERSION)^{}`
 
-$(pkggem): .manifest
+gem: $(pkggem)
+
+install-gem: $(pkggem)
+	gem install $(CURDIR)/$<
+
+$(pkggem): manifest
 	gem build $(rfpackage).gemspec
 	mkdir -p pkg
 	mv $(@F) $@
 
 $(pkgtgz): distdir = $(basename $@)
 $(pkgtgz): HEAD = v$(VERSION)
-$(pkgtgz): .manifest
+$(pkgtgz): manifest
 	@test -n "$(distdir)"
 	$(RM) -r $(distdir)
 	mkdir -p $(distdir)
@@ -239,6 +255,9 @@ release: verify package $(release_notes) $(release_changes)
 	  $(rfproject) $(rfpackage) $(VERSION) $(pkggem)
 	rubyforge add_file \
 	  $(rfproject) $(rfpackage) $(VERSION) $(pkgtgz)
+else
+gem install-gem: GIT-VERSION-FILE
+	$(MAKE) $@ VERSION=$(GIT_VERSION)
 endif
 
-.PHONY: .FORCE-GIT-VERSION-FILE doc $(T) $(slow_tests) .manifest man
+.PHONY: .FORCE-GIT-VERSION-FILE doc $(T) $(slow_tests) manifest man

data/HACKING

@@ -0,0 +1,113 @@
+= Unicorn Hacker's Guide
+
+== Polyglot Infrastructure
+
+Like Mongrel, we use Ruby where it makes sense, and Ragel with C where
+it helps performance.  All of the code that actually runs your Rack
+application is written Ruby, Ragel or C.
+
+As far as tests and documentation goes, we're not afraid to embrace Unix
+and use traditional Unix tools where they make sense and get the job
+done.
+
+=== Tests
+
+Tests are good, but slow tests make development slow, so we make tests
+faster (in parallel) with GNU make (instead of Rake) and avoiding
+Rubygems.
+
+Since we don't load RubyGems by default, loading Rack properly requires
+setting up RUBYLIB to point to where Rack is located.  Not loading
+Rubygems drastically lowers the time to run the full test suite.  You
+may setup a "local.mk" file in the top-level working directory to setup
+your RUBYLIB and any other environment variables.  A "local.mk.sample"
+file is provided for reference.
+
+Running the entire test suite with 4 tests in parallel:
+
+  make -j4 test
+
+Running just one unit test:
+
+  make test/unit/test_http_parser.rb
+
+Running just one test case in a unit test:
+
+  make test/unit/test_http_parser.rb--test_parse_simple.n
+
+=== HttpServer
+
+We strive to write as little code as possible while still maintaining
+readability.  However, readability and flexibility may be sacrificed for
+performance in hot code paths.  For Ruby, less code generally means
+faster code.
+
+Memory allocation should be minimized as much as practically possible.
+Buffers for IO#readpartial are preallocated in the hot paths to avoid
+building up garbage.  Hash assignments use frozen strings to avoid the
+duplication behind-the-scenes.
+
+We spend as little time as possible inside signal handlers and instead
+defer handling them for predictability and robustness.  Most of the
+Unix-specific things are in the Unicorn::HttpServer class.  Unix systems
+programming experience will come in handy (or be learned) here.
+
+=== Documentation
+
+We use RDoc 2.4.x with Darkfish for documentation as much as possible,
+if you're on Ruby 1.8 you want to install the latest "rdoc" gem.  Due to
+the lack of RDoc-to-manpage converters we know about, we're writing
+manpages in Markdown and converting to troff/HTML with Pandoc.
+
+=== Ruby/C Compatibility
+
+We target Ruby 1.8.6+, 1.9 and will target Rubinius as it becomes
+production-ready.  We need the Ruby implementation to support fork,
+exec, pipe, UNIX signals, access to integer file descriptors and
+ability to use unlinked files.
+
+All of our C code is OS-independent and should run on compilers
+supported by the versions of Ruby we target.
+
+=== Ragel Compatibility
+
+We target the latest released version of Ragel and will update our code
+to keep up with new releases.  Packaged tarballs and gems include the
+generated source code so they will remain usable if compatibility is
+broken.
+
+== Contributing
+
+Contributions are welcome in the form of patches, pull requests, code
+review, testing, documentation, user support or any other feedback is
+welcome.  The mailing list is the central coordination point for all
+user and developer feedback and bug reports.
+
+=== Submitting Patches
+
+Follow conventions already established in the code and do not exceed 80
+characters per line.
+
+Inline patches (from "git format-patch") to the mailing list are
+preferred because they allow code review and comments in the reply to
+the patch.
+
+We will adhere to mostly the same conventions for patch submissions as
+git itself.  See the Documentation/SubmittingPatches document
+distributed with git on on patch submission guidelines to follow.  Just
+don't email the git mailing list or maintainer with Unicorn patches :)
+
+== Running Development Versions
+
+It is easy to install the contents of your git working directory:
+
+Via RubyGems (RubyGems 1.3.5+ recommended for prerelease versions):
+
+  make install-gem
+
+Without RubyGems (via setup.rb):
+
+  make install
+
+It is not at all recommended to mix a RubyGems installation with an
+installation done without RubyGems, however.

data/KNOWN_ISSUES

@@ -0,0 +1,27 @@
+= Known Issues
+
+* Installing "unicorn" as a system-wide Rubygem and using the
+  {isolate}[http://github.com/jbarnette/isolate] gem may cause issues if
+  you're using any of the bundled application-level libraries in
+  unicorn/app/* (for compatibility with CGI-based applications, Rails <=
+  2.2.2, or ExecCgi).  For now workarounds include:
+
+  * installing the same version of unicorn as a system-wide Rubygem
+    _and_ isolating unicorn as well.
+  * explicitly setting RUBYLIB or $LOAD_PATH to include any gem path
+    where the unicorn gem is installed (e.g.
+    /usr/lib/ruby/gems/1.8/gems/unicorn-VERSION/lib)
+
+* 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/README

@@ -1,5 +1,11 @@
 = Unicorn: Rack HTTP server for Unix and fast clients
 
+Unicorn is a HTTP server for Rack applications designed to take
+advantage of features in Unix/Unix-like kernels and only serve fast
+clients on low-latency, high-bandwidth connections.  Slow clients should
+only be served by placing a reverse proxy capable of fully-buffering
+both the the request and response in between Unicorn and slow clients.
+
 == Features
 
 * Designed for Rack, Unix, fast clients, and ease-of-debugging.  We
@@ -51,12 +57,6 @@
   notification to be implemented as well as being able to tunnel
   arbitrary stream-based protocols over HTTP.
 
-== Versions
-
-{Current v0.92.0}[http://git.bogomips.org/cgit/unicorn.git/tag/?id=v0.92.0]
-
-{Old Stable v0.8.4}[http://git.bogomips.org/cgit/unicorn.git/tag/?id=v0.8.4]
-
 == License
 
 Unicorn is copyright 2009 Eric Wong and contributors.
@@ -138,22 +138,6 @@ Unicorn is designed to only serve fast clients either on the local host
 or a fast LAN.  See the PHILOSOPHY and DESIGN documents for more details
 regarding this.
 
-== Known Issues
-
-* 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 :)
-
 == Contact
 
 All feedback (bug reports, user/development dicussion, patches, pull

data/Rakefile

@@ -93,9 +93,7 @@ desc "print release notes for Rubyforge"
 task :release_notes do
   require 'rubygems'
 
-  git_url = ENV['GIT_URL'] ||
-            `git config --get remote.origin.url 2>/dev/null`.chomp! ||
-            'git://git.bogomips.org/unicorn.git'
+  git_url = ENV['GIT_URL'] || 'git://git.bogomips.org/unicorn.git'
 
   spec = Gem::Specification.load('unicorn.gemspec')
   puts spec.description.strip

data/SIGNALS

@@ -2,7 +2,10 @@
 
 In general, signals need only be sent to the master process.  However,
 the signals Unicorn uses internally to communicate with the worker
-processes are documented here as well.
+processes are documented here as well.  With the exception of TTIN/TTOU,
+signal handling matches the behavior of {nginx}[http://nginx.net/] so it
+should be possible to easily share process management scripts between
+Unicorn and nginx.
 
 === Master Process
 

data/TUNING

@@ -12,6 +12,12 @@ See Unicorn::Configurator for details on the config file format.
   directives can allow failover to happen more quickly if your
   cluster is configured for it.
 
+* If you're doing extremely simple benchmarks and getting connection
+  errors under high request rates, increasing your :backlog parameter
+  above the already-generous default of 1024 can help avoid connection
+  errors.  Keep in mind this is not recommended for real traffic if
+  you have another machine to failover to (see above).
+
 * :rcvbuf and :sndbuf parameters generally do not need to be set for TCP
   listeners under Linux 2.6 because auto-tuning is enabled.  UNIX domain
   sockets do not have auto-tuning buffer sizes; so increasing those will
@@ -45,7 +51,8 @@ WARNING: Do not change system parameters unless you know what you're doing!
 
 * For load testing/benchmarking with UNIX domain sockets, you should
   consider increasing net.core.somaxconn or else nginx will start
-  failing to connect under heavy load.
+  failing to connect under heavy load.  You may also consider setting
+  a higher :backlog to listen on as noted earlier.
 
 * If you're running out of local ports, consider lowering
   net.ipv4.tcp_fin_timeout to 20-30 (default: 60 seconds).  Also