server-starter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6d6ac01d0b1513979bb1b7d44518ad974250ac2e
+  data.tar.gz: 5b5cf5cc27f280472e5c3008127141b665cb56b9
+SHA512:
+  metadata.gz: 2afe47513bde1c810d8c9d573cfb1f72c7a7cbbb62374afa4c378a73808d763161be574a5618e83a7d9628557608ffa3bb8e3bc49eb918725ca7af95d8b0520f
+  data.tar.gz: 7d384eb0e55be2d485f0739b323297ee69e610392769197750019ecf56300662458b17d450b445bfbe65a22353e494f2983b51190a9906ab3fd75f1a1464b4b6

data/.gitignore

@@ -0,0 +1,17 @@
+/*.gem
+~*
+#*
+*~
+.bundle
+Gemfile.lock
+.rbenv-version
+vendor
+doc/*
+tmp/*
+coverage
+.yardoc
+.ruby-version
+pkg/*
+.tags
+unicorn.stat
+start_server.pid

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+## 0.1.0 (2015/03/16)
+
+First version
+

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Naotoshi Seo
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,103 @@
+# ruby-server-starter
+
+a superdaemon for hot-deploying server programs (ruby port of [p5-Server-Starter](https://github.com/kazuho/p5-Server-Starter))
+
+# Description
+
+*note: this description is almost entirely taken from the original Server::Starter module*
+
+The ```start_server``` utility is a superdaemon for hot-deploying server programs.
+
+It is often a pain to write a server program that supports graceful restarts, with no resource leaks. Server::Starter solves the problem by splitting the task into two: ```start_server``` works as a superdaemon that binds to zero or more TCP ports or unix sockets, and repeatedly spawns the server program that actually handles the necessary tasks (for example, responding to incoming commenctions). The spawned server programs under ```start_server``` call accept(2) and handle the requests.
+
+To gracefully restart the server program, send SIGHUP to the superdaemon. The superdaemon spawns a new server program, and if (and only if) it starts up successfully, sends SIGTERM to the old server program.
+
+By using ```start_server``` it is much easier to write a hot-deployable server. Following are the only requirements a server program to be run under ```start_server``` should conform to:
+
+- receive file descriptors to listen to through an environment variable
+- perform a graceful shutdown when receiving SIGTERM
+
+# Unicorn
+
+Following is an example to run unicorn server under ```Server::Starter```.
+
+The command line example:
+
+```
+bundle exec start_server.rb --status-file=/path/to/app/log/unicorn.stat \
+  --port=10080 --signal-on-hup=CONT --dir=/path/to/app -- \
+  bundle exec --keep-file-descriptors unicorn -c config/unicorn.conf.rb config.ru
+```
+
+An example of unicorn.conf:
+
+```ruby
+worker_processes  4
+preload_app true
+ 
+APP_ROOT = File.expand_path('../..', __FILE__)
+status_file = File.join(APP_ROOT, 'log/unicorn.stat')
+ 
+if ENV.key?('SERVER_STARTER_PORT')
+  fds = ENV['SERVER_STARTER_PORT'].split(';').map { |x|
+    path_or_port, fd = x.split('=', 2)
+    fd
+  }
+  ENV['UNICORN_FD'] = fds.join(',')
+  ENV.delete('SERVER_STARTER_PORT')
+else
+  listen ENV['PORT'] || '10080'
+end
+ 
+before_fork do |server, worker|
+  defined?(ActiveRecord::Base) and ActiveRecord::Base.connection.disconnect!
+ 
+  # Throttle the master from forking too quickly by sleeping.  Due
+  # to the implementation of standard Unix signal handlers, this
+  # helps (but does not completely) prevent identical, repeated signals
+  # from being lost when the receiving process is busy.
+  sleep 1
+end
+ 
+after_fork do |server, worker|
+  defined?(ActiveRecord::Base) and ActiveRecord::Base.establish_connection
+ 
+  begin
+    # This allows a new master process to incrementally
+    # phase out the old master process with SIGTTOU to avoid a
+    # thundering herd (especially in the "preload_app false" case)
+    # when doing a transparent upgrade.  The last worker spawned
+    # will then kill off the old master process with a SIGQUIT.
+    pids = File.readlines(status_file).map {|_| _.chomp.split(':') }.to_h
+    old_gen = ENV['SERVER_STARTER_GENERATION'].to_i - 1
+    if old_pid = pids[old_gen.to_s]
+      sig = (worker.nr + 1) >= server.worker_processes ? :QUIT : :TTOU
+      Process.kill(sig, old_pid.to_i)
+    end
+  rescue Errno::ENOENT, Errno::ESRCH => e
+    $stderr.puts "#{e.class} #{e.message}"
+  end
+end
+```
+
+## See Also
+
+* [「Server::Starterに対応するとはどういうことか」の補足](http://blog.livedoor.jp/sonots/archives/40248661.html) (Japanese)
+* [Server::Starter で Unicorn を起動する場合の Slow Restart](http://blog.livedoor.jp/sonots/archives/42826057.html) (Japanese)
+
+## ChangeLog
+
+See [CHANGELOG.md](CHANGELOG.md) for details.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new [Pull Request](../../pull/new/master)
+
+## Copyright
+
+Copyright (c) 2015 Naotoshi Seo. See [LICENSE](LICENSE) for details.
+

data/Rakefile

@@ -0,0 +1,18 @@
+# encoding: utf-8
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+desc 'Run test_unit based test'
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = Dir["test/**/test_*.rb"].sort
+  t.verbose = true
+  #t.warning = true
+end
+task :default => :test
+
+desc 'Open an irb session preloaded with the gem library'
+task :console do
+    sh 'irb -rubygems -I lib'
+end
+task :c => :console

data/bin/start_server.rb

@@ -0,0 +1,292 @@
+#!/usr/bin/ruby
+
+require 'optparse'
+require_relative '../lib/server/starter'
+
+opts = {
+  :port => [],
+  :path => [],
+  :interval => 1,
+}
+OptionParser.new do |opt|
+  opt.on(
+    '--port=(port|host:port),(port|host:port),...',
+    'TCP port to listen to (if omitted, will not bind to any ports)',
+    Array
+  ) {|v| opts[:port] = v }
+  opt.on(
+    '--path=path,path,...',
+    'path at where to listen using unix socket (optional)',
+    Array,
+  ) {|v| opts[:path] = v }
+  opt.on(
+    '--dir=path',
+    'working directory, start_server do chdir to before exec (optional)',
+  ) {|v| opts[:dir] = v }
+  opt.on(
+    '--interval=seconds',
+    'minimum interval to respawn the server program (default: 1)',
+  ) {|v| opts[:interval] = v.to_i }
+  opt.on(
+    '--signal-on-hup=SIGNAL',
+    'name of the signal to be sent to the server process when start_server receives a SIGHUP (default: SIGTERM). If you use this option, be sure to also use `--signal-on-term` below.',
+  ) {|v| opts[:signal_on_hup] = v }
+  opt.on(
+    '--signal-on-term=SIGNAL',
+    'name of the signal to be sent to the server process when start_server receives a SIGTERM (default: SIGTERM)',
+  ) {|v| opts[:signal_on_term] = v }
+  opt.on(
+    '--pid-file=filename',
+    'if set, writes the process id of the start_server process to the file',
+  ) {|v| opts[:pid_file] = v }
+  opt.on(
+    '--status-file=filename',
+    'if set, writes the status of the server process(es) to the file',
+  ) {|v| opts[:status_file] = v }
+  opt.on(
+    '--envdir=ENVDIR',
+    'directory that contains environment variables to the server processes. It is intended for use with `envdir` in `daemontools`. This can be overwritten by environment variable `ENVDIR`.',
+  ) {|v| opts[:envdir] = v }
+  opt.on(
+    '--enable-auto-restart',
+    'enables automatic restart by time. This can be overwritten by environment variable `ENABLE_AUTO_RESTART`.',
+  ) {|v| opts[:enable_auto_restart] = v }
+  opt.on(
+    '--auto-restart-interval=seconds',
+    'automatic restart interval (default 360). It is used with `--enable-auto-restart` option. This can be overwritten by environment variable `AUTO_RESTART_INTERVAL`.',
+  ) {|v| opts[:auto_restart_interval] = v.to_i }
+  opt.on(
+    '--kill-old-delay=seconds',
+    'time to suspend to send a signal to the old worker. The default value is 5 when `--enable-auto-restart` is set, 0 otherwise. This can be overwritten by environment variable `KILL_OLD_DELAY`.'
+  ) {|v| opts[:kill_old_delay] = v.to_i }
+  opt.on(
+    '--restart',
+    'this is a wrapper command that reads the pid of the start_server process from --pid-file, sends SIGHUP to the process and waits until the server(s) of the older generation(s) die by monitoring the contents of the --status-file'
+  ) {|v| opts[:restart] = v }
+  opt.on(
+    '--backlog=num',
+    'specifies a listen backlog parameter, whose default is SOMAXCONN (usually 128 on Linux). While SOMAXCONN is enough for most loads, large backlog is required for heavy loads.',
+  ) {|v| opts[:backlog] = v.to_i }
+  opt.on(
+    '--version',
+    'print version',
+  ) {|v| puts Server::Starter::VERSION; exit 0 }
+  
+  opt.parse!(ARGV)
+end
+
+starter = Server::Starter.new
+
+if opts[:restart]
+  starter.restart_server(opts)
+  exit 0;
+end
+
+# validate options
+if ARGV.empty?
+  $stderr.puts "server program not specified"
+  exit 1
+end
+
+starter.start_server(opts.merge({:exec => ARGV}))
+
+__END__
+#! /usr/bin/perl
+
+use strict;
+use warnings;
+
+use Getopt::Long;
+use Pod::Usage;
+use Server::Starter qw(start_server restart_server);
+
+my %opts = (
+    port => [],
+    path => [],
+);
+
+GetOptions(
+    map {
+        $_ => do {
+            my $name = (split '=', $_, 2)[0];
+            $name =~ s/-/_/g;
+            $opts{$name} ||= undef;
+            ref($opts{$name}) ? $opts{$name} : \$opts{$name};
+        },
+    } qw(port=s path=s interval=i log-file=s pid-file=s dir=s signal-on-hup=s signal-on-term=s
+         backlog=i envdir=s enable-auto-restart=i auto-restart-interval=i kill-old-delay=i
+         status-file=s restart help version),
+) or exit 1;
+pod2usage(
+    -exitval => 0,
+    -verbose => 1,
+) if $opts{help};
+if ($opts{version}) {
+    print "$Server::Starter::VERSION\n";
+    exit 0;
+}
+
+if ($opts{restart}) {
+    restart_server(%opts);
+    exit 0;
+}
+
+# validate options
+die "server program not specified\n"
+    unless @ARGV;
+
+start_server(
+    %opts,
+    exec => \@ARGV,
+);
+__END__
+
+#! /usr/bin/perl
+
+use strict;
+use warnings;
+
+use Getopt::Long;
+use Pod::Usage;
+use Server::Starter qw(start_server restart_server);
+
+my %opts = (
+    port => [],
+    path => [],
+);
+
+GetOptions(
+    map {
+        $_ => do {
+            my $name = (split '=', $_, 2)[0];
+            $name =~ s/-/_/g;
+            $opts{$name} ||= undef;
+            ref($opts{$name}) ? $opts{$name} : \$opts{$name};
+        },
+    } qw(port=s path=s interval=i log-file=s pid-file=s dir=s signal-on-hup=s signal-on-term=s
+         backlog=i envdir=s enable-auto-restart=i auto-restart-interval=i kill-old-delay=i
+         status-file=s restart help version),
+) or exit 1;
+pod2usage(
+    -exitval => 0,
+    -verbose => 1,
+) if $opts{help};
+if ($opts{version}) {
+    print "$Server::Starter::VERSION\n";
+    exit 0;
+}
+
+if ($opts{restart}) {
+    restart_server(%opts);
+    exit 0;
+}
+
+# validate options
+die "server program not specified\n"
+    unless @ARGV;
+
+start_server(
+    %opts,
+    exec => \@ARGV,
+);
+
+__END__
+
+=head1 NAME
+
+start_server - a superdaemon for hot-deploying server programs
+
+=head1 SYNOPSIS
+
+  start_server [options] -- server-prog server-arg1 server-arg2 ...
+
+  # start Plack using Starlet listening at TCP port 8000
+  start_server --port=8000 -- plackup -s Starlet --max-workers=100 index.psgi
+
+=head1 DESCRIPTION
+
+This script is a frontend of L<Server::Starter>.  For more information please refer to the documentation of the module.
+
+=head1 OPTIONS
+
+=head2 --port=(port|host:port)
+
+TCP port to listen to (if omitted, will not bind to any ports)
+
+=head2 --path=path
+
+path at where to listen using unix socket (optional)
+
+=head2 --dir=path
+
+working directory, start_server do chdir to before exec (optional)
+
+=head2 --interval=seconds
+
+minimum interval to respawn the server program (default: 1)
+
+=head2 --signal-on-hup=SIGNAL
+
+name of the signal to be sent to the server process when start_server receives a SIGHUP (default: SIGTERM). If you use this option, be sure to also use C<--signal-on-term> below.
+
+=head2 --signal-on-term=SIGNAL
+
+name of the signal to be sent to the server process when start_server receives a SIGTERM (default: SIGTERM)
+
+=head2 --pid-file=filename
+
+if set, writes the process id of the start_server process to the file
+
+=head2 --status-file=filename
+
+if set, writes the status of the server process(es) to the file
+
+=head2 --envdir=ENVDIR
+
+directory that contains environment variables to the server processes.
+It is intended for use with C<envdir> in C<daemontools>.
+This can be overwritten by environment variable C<ENVDIR>.
+
+=head2 --enable-auto-restart
+
+enables automatic restart by time.
+This can be overwritten by environment variable C<ENABLE_AUTO_RESTART>.
+
+=head2 --auto-restart-interval=seconds
+
+automatic restart interval (default 360). It is used with C<--enable-auto-restart> option.
+This can be overwritten by environment variable C<AUTO_RESTART_INTERVAL>.
+
+=head2 --kill-old-delay=seconds
+
+time to suspend to send a signal to the old worker. The default value is 5 when C<--enable-auto-restart> is set, 0 otherwise.
+This can be overwritten by environment variable C<KILL_OLD_DELAY>.
+
+=head2 --restart
+
+this is a wrapper command that reads the pid of the start_server process from --pid-file, sends SIGHUP to the process and waits until the server(s) of the older generation(s) die by monitoring the contents of the --status-file
+
+=head2 --backlog
+specifies a listen backlog parameter, whose default is SOMAXCONN (usually 128 on Linux). While SOMAXCONN is enough for most loads, large backlog is required for heavy loads.
+
+=head2 --help
+
+prints this help
+
+=head2 --version
+
+prints the version number
+
+=head1 AUTHOR
+
+Kazuho Oku
+
+=head1 SEE ALSO
+
+L<Server::Starter>
+
+=head1 LICENSE
+
+This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
+
+=cut

data/example/Gemfile

@@ -0,0 +1,6 @@
+source "http://rubygems.org"
+
+gem 'server-starter', path: '../'
+gem 'unicorn'
+gem 'pry'
+gem 'pry-nav'

data/example/config/unicorn.conf

@@ -0,0 +1,46 @@
+worker_processes  2
+preload_app true
+ 
+APP_ROOT = File.expand_path('../..', __FILE__)
+status_file = File.join(APP_ROOT, 'log/unicorn.stat')
+ 
+if ENV.key?('SERVER_STARTER_PORT')
+  fds = ENV['SERVER_STARTER_PORT'].split(';').map { |x|
+    path_or_port, fd = x.split('=', 2)
+    fd
+  }
+  ENV['UNICORN_FD'] = fds.join(',')
+  ENV.delete('SERVER_STARTER_PORT')
+else
+  listen ENV['PORT'] || '10080'
+end
+ 
+before_fork do |server, worker|
+  defined?(ActiveRecord::Base) and ActiveRecord::Base.connection.disconnect!
+ 
+  # Throttle the master from forking too quickly by sleeping.  Due
+  # to the implementation of standard Unix signal handlers, this
+  # helps (but does not completely) prevent identical, repeated signals
+  # from being lost when the receiving process is busy.
+  sleep 1
+end
+ 
+after_fork do |server, worker|
+  defined?(ActiveRecord::Base) and ActiveRecord::Base.establish_connection
+ 
+  begin
+    # This allows a new master process to incrementally
+    # phase out the old master process with SIGTTOU to avoid a
+    # thundering herd (especially in the "preload_app false" case)
+    # when doing a transparent upgrade.  The last worker spawned
+    # will then kill off the old master process with a SIGQUIT.
+    pids = File.readlines(status_file).map {|_| _.chomp.split(':') }.to_h
+    old_gen = ENV['SERVER_STARTER_GENERATION'].to_i - 1
+    if old_pid = pids[old_gen.to_s]
+      sig = (worker.nr + 1) >= server.worker_processes ? :QUIT : :TTOU
+      Process.kill(sig, old_pid.to_i)
+    end
+  rescue Errno::ENOENT, Errno::ESRCH => e
+    $stderr.puts "#{e.class} #{e.message}"
+  end
+end

data/example/config.ru

@@ -0,0 +1,11 @@
+class SimpleApp
+  def call(env)
+    [
+      200,
+      {'Content-Type' => 'text/html'},
+      ['Hello World']
+    ]
+  end
+end
+
+run SimpleApp.new

data/example/env/TEST

@@ -0,0 +1 @@
+foo

data/example/restart_server

@@ -0,0 +1,2 @@
+#!/bin/sh
+bundle exec start_server.rb --restart --pid-file=log/start_server.pid --status-file=log/unicorn.stat

data/example/start_server

@@ -0,0 +1,16 @@
+#!/bin/sh
+bundle exec start_server.rb \
+  --port=0.0.0.0:10080 \
+  --dir=$(pwd) \
+  --interval=1 \
+  --signal-on-hup=CONT \
+  --signal-on-TERM=TERM \
+  --pid-file=$(pwd)/log/start_server.pid \
+  --status-file=$(pwd)/log/unicorn.stat \
+  --envdir=env \
+  --enable-auto-restart \
+  --auto-restart-interval=100 \
+  --kill-old-delay=1 \
+  --backlog=100 \
+  -- \
+  bundle exec --keep-file-descriptors unicorn -c config/unicorn.conf config.ru 2>&1

data/lib/server/starter/helper.rb

@@ -0,0 +1,52 @@
+class Server
+  class Starter
+    module Helper
+      def warn(msg)
+        $stderr.puts msg
+      end
+
+      def croak(msg)
+        $stderr.puts msg
+        exit 1
+      end
+
+      def die(*args)
+        if args.size == 2
+          e, msg = args[0], args[1]
+          $stderr.puts "#{msg}:#{e.class} #{e.message}"
+        else
+          msg = args[0]
+          $stderr.puts msg
+        end
+        exit 1
+      end
+
+      def with_local_env(local_env, &block)
+        orig_env = local_env.keys.map {|k| [k, ENV[k]] }.to_h
+        ENV.update(local_env)
+        yield
+      ensure
+        ENV.update(orig_env)
+      end
+
+      def bundler_with_clean_env(&block)
+        if defined?(Bundler)
+          begin
+            # Bundler.with_clean_env resets ENV to initial env on loading ruby
+            orig_env = ENV.to_hash
+            ENV.delete_if { |k,_| k[0,7] == 'BUNDLE_' }
+            if ENV.has_key? 'RUBYOPT'
+              ENV['RUBYOPT'] = ENV['RUBYOPT'].sub '-rbundler/setup', ''
+            end
+            %w[RUBYLIB GEM_HOME].each {|key| ENV.delete(key) }
+            yield
+          ensure
+            ENV.replace(orig_env)
+          end
+        else
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/server/starter/version.rb

@@ -0,0 +1,5 @@
+class Server
+  class Starter
+    VERSION = '0.1.0'
+  end
+end