yahns-rackup launcher

This should make it easier for Rack users to get started with yahns.

8 files changed, 225 insertions, 4 deletions

diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
index 482b5b1..b08a2a4 100644
--- a/Documentation/GNUmakefile
+++ b/Documentation/GNUmakefile
@@ -9,6 +9,7 @@ pandoc = $(PANDOC) $(PANDOC_OPTS)
 
 m1 =
 m1 += yahns
+m1 += yahns-rackup
 
 m5 =
 m5 += yahns_config
diff --git a/Documentation/yahns-rackup.txt b/Documentation/yahns-rackup.txt
new file mode 100644
index 0000000..269d013
--- /dev/null
+++ b/Documentation/yahns-rackup.txt
@@ -0,0 +1,152 @@
+% yahns-rackup(1) yahns user manual
+
+# NAME
+
+yahns-rackup - a rackup-like command to launch yahns
+
+# SYNOPSIS
+
+yahns-rackup [-E RACK_ENV] [-O worker_threads=NUM] [RACKUP_FILE]
+
+# DESCRIPTION
+
+A rackup(1)-like command to launch Rack applications using yahns.
+It is expected to start in your application root (APP_ROOT).
+
+# RACKUP FILE
+
+This defaults to \"config.ru\" in APP_ROOT.  It should be the same
+file used by rackup(1) and other Rack launchers, it uses the
+*Rack::Builder* DSL.
+
+# YAHNS OPTIONS
+-O client_timeout=SECONDS
+:   Defines the timeout expiring idle connections.
+
+    Increase this if your application takes longer to run than the
+    default timeout.  Lower this if you run out of FDs.
+
+    Default: 15 (seconds)
+
+-O listen=ADDRESS[,ADDRESS...]
+:   Listens on a given ADDRESS.  ADDRESS may be in the form of
+    HOST:PORT or PATH, HOST:PORT is taken to mean a TCP socket
+    and PATH is meant to be a path to a UNIX domain socket.
+    Defaults to "0.0.0.0:9292" (all addresses on TCP port 9292).
+    Multiple addresses may be separated with commas.
+
+-O stderr_path=PATHNAME
+:   Allow redirecting $stderr to a given path.  Unlike doing this from
+    the shell, this allows the yahns process to know the path its
+    writing to and rotate the file if it is used for logging.  The
+    file will be opened with the O_APPEND flag and writes
+    synchronized to the kernel (but not necessarily to _disk_) so
+    multiple processes can safely append to it.
+
+    If you are daemonizing and using the default logger, it is important
+    to specify this as errors will otherwise be lost to /dev/null.
+    Some applications/libraries may also triggering warnings that go to
+    stderr, and they will end up here.
+
+    Default: /dev/null if daemonized, controlling terminal if not
+
+-O stdout_path=PATH
+:   Same as stderr_path, except for $stdout.  Not many applications
+    write to $stdout, but any that do will have their output written here.
+    It is safe to point this to the same location a stderr_path.
+    Like stderr_path, this defaults to /dev/null when daemonized.
+
+    Default: /dev/null if daemonized, controlling terminal if not
+
+-O worker_threads=INTEGER
+:   This controls the number of threads for application processing.
+    Each queue has its own thread pool.  Increase this number if your
+    applications are able to use more threads effectively or if either
+    (or both) input/output buffering are disabled.  Lower this number if
+    you do not need multi-thread concurrency at all.
+
+    Default: 7
+
+# RACKUP OPTIONS
+-D, \--daemonize
+:   Run daemonized in the background.  The process is detached from
+    the controlling terminal and stdin is redirected to /dev/null.
+    Unless specified via stderr_path and stdout_path, stderr and stdout will
+    also be redirected to "/dev/null".
+
+-E, \--env RACK_ENV
+:   Run under the given RACK_ENV.  See the RACK ENVIRONMENT section
+    for more details.
+
+-o, \--host HOST
+:   Listen on a TCP socket belonging to HOST, default is
+    "0.0.0.0" (all addresses).
+    If specified multiple times on the command-line, only the
+    last-specified value takes effect.
+    This option only exists for compatibility with the rackup(1) command,
+    use of "-l"/"\--listen" switch is recommended instead.
+
+-p, \--port PORT
+:   Listen on the specified TCP PORT, default is 9292.
+    If specified multiple times on the command-line, only the last-specified
+    value takes effect.
+    This option only exists for compatibility with the rackup(1) command,
+    use of "-l"/"\--listen" switch is recommended instead.
+
+# RUBY OPTIONS
+-e, \--eval LINE
+:   Evaluate a LINE of Ruby code.  This evaluation happens
+    immediately as the command-line is being parsed.
+
+-d, \--debug
+:   Turn on debug mode, the $DEBUG variable is set to true.
+
+-w, \--warn
+:   Turn on verbose warnings, the $VERBOSE variable is set to true.
+
+-I, \--include PATH
+:   specify $LOAD_PATH.  PATH will be prepended to $LOAD_PATH.
+    The \':\' character may be used to delimit multiple directories.
+    This directive may be used more than once.  Modifications to
+    $LOAD_PATH take place immediately and in the order they were
+    specified on the command-line.
+
+-r, \--require LIBRARY
+:   require a specified LIBRARY before executing the application.  The
+    \"require\" statement will be executed immediately and in the order
+    they were specified on the command-line.
+
+# SIGNALS
+
+See yahns(1)
+
+# FILES
+
+See Rack documentation for a description of the rackup file format.
+
+# ENVIRONMENT VARIABLES
+
+The RACK_ENV variable is set by the aforementioned \-E switch.
+If RACK_ENV is already set, it will be used unless \-E is used.
+See rackup documentation for more details.
+
+# CONTACT
+
+All feedback welcome via plain-text mail to <yahns-public@rubyforge.org>\
+No subscription is necessary to post to the mailing list.
+
+# COPYRIGHT
+
+Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.\
+License: GPLv3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>
+
+# SEE ALSO
+
+yahns(1), yahns_config(5)
+
+* *Rack::Builder* ri/RDoc
+* [Rack RDoc][1]
+* [Rackup HowTo][2]
+
+[1]: http://rack.rubyforge.org/doc/
+[2]: http://wiki.github.com/rack/rack/tutorial-rackup-howto
diff --git a/Documentation/yahns.txt b/Documentation/yahns.txt
index 0725f49..362851f 100644
--- a/Documentation/yahns.txt
+++ b/Documentation/yahns.txt
@@ -65,4 +65,4 @@ License: GPLv3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>
 
 # SEE ALSO
 
-yahns_config(5)
+yahns-rackup(1), yahns_config(5)
diff --git a/bin/yahns b/bin/yahns
index 5c4d34e..efa267a 100755
--- a/bin/yahns
+++ b/bin/yahns
@@ -2,8 +2,7 @@
 # -*- encoding: binary -*-
 # Copyright (C) 2013, Eric Wong <normalperson@yhbt.net> and all contributors
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
-$stdout.sync = $stderr.sync = true
-require 'yahns'
+require 'yahns/daemon'
 require 'optparse'
 config_file = daemonize = nil
 OptionParser.new("", 24, "  ") do |opts|
diff --git a/bin/yahns-rackup b/bin/yahns-rackup
new file mode 100755
index 0000000..baf110b
--- /dev/null
+++ b/bin/yahns-rackup
@@ -0,0 +1,9 @@
+#!/this/will/be/overwritten/or/wrapped/anyways/do/not/worry/ruby
+# -*- encoding: binary -*-
+# Copyright (C) 2013, Eric Wong <normalperson@yhbt.net> and all contributors
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+require 'yahns/rackup_handler'
+ARGV.grep(/\A(?:-s|--server)/)[0] and abort "--server has no effect for #$0"
+ARGV[0, 0] = %w(-s yahns)
+Rack::Handler.register('yahns', 'Yahns::RackupHandler')
+Rack::Server.start
diff --git a/lib/yahns.rb b/lib/yahns.rb
index 51a6c4c..b493dc2 100644
--- a/lib/yahns.rb
+++ b/lib/yahns.rb
@@ -1,5 +1,7 @@
 # Copyright (C) 2013, Eric Wong <normalperson@yhbt.net> and all contributors
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+$stdout.sync = $stderr.sync = true
+
 require 'unicorn' # pulls in raindrops, kgio, fcntl, etc, stringio, and logger
 require 'sleepy_penguin'
 
@@ -68,7 +70,6 @@ require_relative 'yahns/config'
 require_relative 'yahns/tmpio'
 require_relative 'yahns/worker'
 require_relative 'yahns/sigevent'
-require_relative 'yahns/daemon'
 require_relative 'yahns/socket_helper'
 require_relative 'yahns/server'
 require_relative 'yahns/fdmap'
diff --git a/lib/yahns/daemon.rb b/lib/yahns/daemon.rb
index df8b573..f6cdf47 100644
--- a/lib/yahns/daemon.rb
+++ b/lib/yahns/daemon.rb
@@ -1,6 +1,8 @@
 # -*- encoding: binary -*-
 # Copyright (C) 2013, Eric Wong <normalperson@yhbt.net> and all contributors
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+require 'yahns'
+
 module Yahns::Daemon # :nodoc:
   # We don't do a lot of standard daemonization stuff:
   #   * umask is whatever was set by the parent process at startup
diff --git a/lib/yahns/rackup_handler.rb b/lib/yahns/rackup_handler.rb
new file mode 100644
index 0000000..9fbebbf
--- /dev/null
+++ b/lib/yahns/rackup_handler.rb
@@ -0,0 +1,57 @@
+# Copyright (C) 2013, Eric Wong <normalperson@yhbt.net> and all contributors
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+require 'yahns'
+
+module Yahns::RackupHandler # :nodoc:
+  def self.default_host
+    environment  = ENV['RACK_ENV'] || 'development'
+    environment == 'development' ? '127.0.0.1' : '0.0.0.0'
+  end
+
+  def self.run(app, o)
+    cfg = Yahns::Config.new
+    cfg.instance_eval do
+      app(:rack, app) do
+        addr = o[:listen] || "#{o[:Host]||default_host}:#{o[:Port]||8080}"
+        # allow listening to multiple addresses
+        if addr =~ /,/
+          addr.split(/,/).each { |l| listen(l) }
+        else
+          listen addr
+        end
+
+        val = o[:client_timeout] and client_timeout(val)
+      end
+
+      queue do
+        wt = o[:worker_threads] and worker_threads(wt)
+      end
+
+      %w(stderr_path stdout_path).each do |x|
+        x = x.to_sym
+        val = o[x] and __send__(x, val)
+      end
+
+      # we need this because "rackup -D" sends us to "/", which might be
+      # fine for most apps, but we have SIGUSR2 restarts to support
+      working_directory(Yahns::START[:cwd])
+    end
+    Yahns::Server.new(cfg).start.join
+  end
+
+  def self.valid_options
+    # these should be the most common options
+    {
+      "listen=ADDRESS" => "address(es) to listen on (e.g. /tmp/sock)",
+      "worker_threads=NUM" => "number of worker threads to run",
+
+      # this affects how quickly graceful shutdown goes
+      "client_timeout=SECONDS" => "timeout for idle clients",
+
+      # I don't want these here, but rackup supports daemonize and
+      # we lose useful information when that sends stdout/stderr to /dev/null
+      "stderr_path=PATH" => "stderr destination",
+      "stdout_path=PATH" => "stdout destination",
+    }
+  end
+end