unicorn_relay 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bb391afaecdf7ee75869e6d86ef3bcf590e60471
-  data.tar.gz: 76fe237036b5be4b6e2275217b59c8f415a3e270
+  metadata.gz: 3690f55d5c212275a23edceb5b2f7f03482ba557
+  data.tar.gz: 454d018ead2c5a6855847700ed48def6b51f16ca
 SHA512:
-  metadata.gz: 283caa1b2bda67e62c2158f9dbdbfab85c4877c71a62648c444ae06b2605fcdd278eb4026fcd753b60ef758f0dc7cb5860ddde996a9b8a64f49e2209929da931
-  data.tar.gz: 37dc59b4bd7be89f5f30b15b73e7cb7fdda487fab3b9299a4e1a5afd9b78e1443926ab652823f05d550da273cb07248b74b63c3872d4e5a9c9f0f626d9921aad
+  metadata.gz: b54c0ba3380997c021aea076fd3d306ec077adc72252453513128143c6b48eec7aa2cb7b5003803568edad93ccd9bcb4301682943f68f09672e99e1955de048d
+  data.tar.gz: 6b0ff1f688f821778dfed34ac8ac63ffacc6862aa24cc134197a2756f41c86b5c13b8b1fd1f9e537b0d2873f9792cb5b0927de7eaa8638c4245d8b3ec73285f5

data/.gitignore

@@ -3,8 +3,10 @@
 .DS_Store
 .byebug_history
 .rvmrc
+.yardoc
 Gemfile.lock
 coverage
 errors.lst
 pkg
 tags
+yard

data/.travis.yml

@@ -0,0 +1,3 @@
+rvm:
+  - 2.3.1
+sudo: false

data/README.md

@@ -0,0 +1,90 @@
+# unicorn\_relay
+
+## Description
+
+The executable `unicorn_relay` contained in this gem allows you to supervise
+unicorn via runit by relaying signals to it while keep running under
+supervision and also handles the necessary work for handling pids, pid files,
+etc.
+
+## Usage
+
+You can start `unicorn_relay` in your runit run script like this:
+
+```
+#!/bin/sh
+
+# your ruby GC configuration variables: export UNICORN_GC=…
+export PID_FILE="/some/where/pids/unicorn.pid"
+
+cd "/some/where"
+exec 2>&1
+exec chpst -u my_user bundle exec unicorn_relay unicorn -c config/unicorn_config.rb
+```
+
+In your `unicorn_config.rb` configuration file you have to handle tearing down
+an eventual old unicorn master when a new worker starts by calling
+`UnicornRelay::Teardown#perform` as shown here:
+
+```
+before_fork do |server, worker|
+  UnicornRelay::Teardown.new(
+    pid_file: '/some/where/pids/unicorn.pid.oldbin',
+    server:   server
+  ).perform
+end
+```
+
+The following signals will just be relayed to the forked unicorn processes:
+
+```
+HUP
+USR1
+USR2
+TTIN
+TTOU
+WINCH
+```
+
+These signals will shutdown the supervised unicorn process:
+
+```
+QUIT
+TERM
+INT
+```
+
+In order to shutdown unicorn `unicorn_relay` just relays the `INT` and `QUIT`
+signals, but changes the `TERM` signal to `QUIT` and then waits for the forked
+processes to finish.
+
+Now you can stop unicorn gracefully with the command 
+
+```
+sv stop SERVICE
+```
+
+or w/o grace by executing:
+
+```
+sv interrupt SERVICE
+```
+
+If you run
+
+```
+sv 2 SERVICE
+```
+
+a new unicorn master is forked that is still controlled by the currently
+running and supervised `unicorn_relay` script. The latter enables you to load
+new code into your running app with a rolling restart behaviour, that is
+without interruptions of service.
+
+## Author
+
+[Florian Frank](mailto:flori@ping.de)
+
+## License
+
+This software is licensed under the Apache 2.0 license.

data/Rakefile

@@ -11,7 +11,8 @@ GemHadar do
   description 'Allow controlling unicorn via supervise by relaying signals to it'
   test_dir    'spec'
   ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', 'coverage', '.rvmrc',
-    '.AppleDouble', 'tags', '.byebug_history', '.DS_Store', 'errors.lst'
+    '.AppleDouble', 'tags', '.byebug_history', '.DS_Store', 'errors.lst',
+    '.yardoc', 'yard'
   readme      'README.md'
   title       "#{name.camelize} -- More Math in Ruby"
   licenses    << 'Apache-2.0'
@@ -22,6 +23,7 @@ GemHadar do
   development_dependency 'rake'
   development_dependency 'simplecov'
   development_dependency 'rspec'
+  development_dependency 'yard'
 end
 
 task :default => :spec

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.1.0

data/lib/unicorn_relay.rb

@@ -1,6 +1,7 @@
 require 'tins/xt'
 require 'mize'
 
+# All classes used by unicorn_relay are defined under this namespace.
 module UnicornRelay
 end
 

data/lib/unicorn_relay/forker.rb

@@ -1,8 +1,17 @@
+# This class forks a child unicorn process and handles relaying of signals to
+# it.
 class UnicornRelay::Forker
+
+  # This exception is caught in the start_control_loop method and stops its
+  # execution.
   class StopException < StandardError; end
 
-  def initialize(script_path: $0, pid_file: nil, argv: ARGV, env: ENV)
-    @name             = File.basename(script_path)
+  # @param name [ String ] The process name used in output and error messages (default is the basename of $0)
+  # @param pid_file [ String ] The path to the pid file of the unicorn master process
+  # @param argv [ Array ] The arguments for the forked unicorn process including the command itself (defaults to ARGV)
+  # @param env [ Hash ] The environment variables as a Hash used to fork the unicorn process (defaults to ENV)
+  def initialize(name: nil, pid_file: nil, argv: ARGV, env: ENV)
+    @name             = name ? name : File.basename($0)
     @pid_file         = pid_file
     @argv             = argv
     @env              = env
@@ -14,11 +23,17 @@ class UnicornRelay::Forker
     }
   end
 
+  # First attempts to handle unicorn process where the pid was given in
+  # pid_file, that is interrupts them. Then starts the control loop that reacts
+  # to signals and relays them to the newly forked processes.
   def start
     handle_old_pid_file
     start_control_loop
   end
 
+  # Stops the control loop if called in its context by raising a
+  # UnicornRelay::Forker::StopException. You usally never have to/should do
+  # this.
   def stop
     stop_control_loop
   end
@@ -127,10 +142,15 @@ class UnicornRelay::Forker
     pgid
   end
 
+  # @param signal [ Integer | Symbol | String ] a UNIX signal specifier
+  #
+  # Sends +signal+ to the controller unicorn processes.
   def signal_process_group(signal)
     Process.kill signal, -@pgid
   end
 
+  # Check if a shutdown signal is pending, that is still to be sent to the
+  # forked unicorn processes.
   def shutdown_signal_pending?
     @shutdown_signal && !@shutdown_signal_sent_at
   end
@@ -142,6 +162,8 @@ class UnicornRelay::Forker
     signal_process_group @shutdown_signal
   end
 
+  # Check if a shutdown signal was already sent a sufficient time ago and it
+  # might be time to try again.
   def shutdown_signal_sent_before?
     @shutdown_signal_sent_at && @shutdown_signal_sent_at - Time.now > 60
   end

data/lib/unicorn_relay/teardown.rb

@@ -1,11 +1,15 @@
 # Before forking anew, kill the unicorn master process that belongs to the
 # .oldbin PID. This enables 0 downtime deploys.
 class UnicornRelay::Teardown
+  # @param server [ Unicorn::HttpServer ] an instance of a unicorn server
+  # @param pid_file [ String ] the path to the old unicorn master's pid file (usually ending in ".oldbin")
   def initialize(server:, pid_file:)
     @server   = server
     @pid_file = pid_file
   end
 
+  # Peforms the teardown of the old unicorn master from one of the workers
+  # forked by the new master, if the new master has a different pid file.
   def perform
     server_has_new_pid_file? && pid and kill_pid
   end

data/lib/unicorn_relay/version.rb

@@ -1,6 +1,6 @@
 module UnicornRelay
   # UnicornRelay version
-  VERSION         = '0.0.0'
+  VERSION         = '0.1.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/spec/forker_spec.rb

@@ -11,7 +11,7 @@ describe UnicornRelay::Forker do
 
   let :forker do
     described_class.new(
-      script_path: 'foo/bar/unicorn_relay',
+      name:         'unicorn_relay',
       pid_file:     pid_file
     )
   end

data/unicorn_relay.gemspec

@@ -1,19 +1,19 @@
 # -*- encoding: utf-8 -*-
-# stub: unicorn_relay 0.0.0 ruby lib
+# stub: unicorn_relay 0.1.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "unicorn_relay".freeze
-  s.version = "0.0.0"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["Florian Frank".freeze]
-  s.date = "2016-10-11"
+  s.date = "2016-10-13"
   s.description = "Allow controlling unicorn via supervise by relaying signals to it".freeze
   s.email = "flori@ping.de".freeze
   s.executables = ["unicorn_relay".freeze]
   s.extra_rdoc_files = ["README.md".freeze, "lib/unicorn_relay.rb".freeze, "lib/unicorn_relay/forker.rb".freeze, "lib/unicorn_relay/teardown.rb".freeze, "lib/unicorn_relay/version.rb".freeze]
-  s.files = [".gitignore".freeze, ".rspec".freeze, ".utilsrc".freeze, "Gemfile".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "bin/unicorn_relay".freeze, "bin/unocorn".freeze, "lib/unicorn_relay.rb".freeze, "lib/unicorn_relay/forker.rb".freeze, "lib/unicorn_relay/teardown.rb".freeze, "lib/unicorn_relay/version.rb".freeze, "spec/forker_spec.rb".freeze, "spec/spec_helper.rb".freeze, "spec/teardown_spec.rb".freeze, "unicorn_relay.gemspec".freeze]
+  s.files = [".gitignore".freeze, ".rspec".freeze, ".travis.yml".freeze, ".utilsrc".freeze, "Gemfile".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "bin/unicorn_relay".freeze, "bin/unocorn".freeze, "lib/unicorn_relay.rb".freeze, "lib/unicorn_relay/forker.rb".freeze, "lib/unicorn_relay/teardown.rb".freeze, "lib/unicorn_relay/version.rb".freeze, "spec/forker_spec.rb".freeze, "spec/spec_helper.rb".freeze, "spec/teardown_spec.rb".freeze, "unicorn_relay.gemspec".freeze]
   s.homepage = "http://flori.github.com/unicorn_relay".freeze
   s.licenses = ["Apache-2.0".freeze]
   s.rdoc_options = ["--title".freeze, "UnicornRelay -- More Math in Ruby".freeze, "--main".freeze, "README.md".freeze]
@@ -25,25 +25,28 @@ Gem::Specification.new do |s|
     s.specification_version = 4
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.8.0"])
+      s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.9.1"])
       s.add_development_dependency(%q<rake>.freeze, [">= 0"])
       s.add_development_dependency(%q<simplecov>.freeze, [">= 0"])
       s.add_development_dependency(%q<rspec>.freeze, [">= 0"])
+      s.add_development_dependency(%q<yard>.freeze, [">= 0"])
       s.add_runtime_dependency(%q<tins>.freeze, ["~> 1.0"])
       s.add_runtime_dependency(%q<mize>.freeze, [">= 0"])
     else
-      s.add_dependency(%q<gem_hadar>.freeze, ["~> 1.8.0"])
+      s.add_dependency(%q<gem_hadar>.freeze, ["~> 1.9.1"])
       s.add_dependency(%q<rake>.freeze, [">= 0"])
       s.add_dependency(%q<simplecov>.freeze, [">= 0"])
       s.add_dependency(%q<rspec>.freeze, [">= 0"])
+      s.add_dependency(%q<yard>.freeze, [">= 0"])
       s.add_dependency(%q<tins>.freeze, ["~> 1.0"])
       s.add_dependency(%q<mize>.freeze, [">= 0"])
     end
   else
-    s.add_dependency(%q<gem_hadar>.freeze, ["~> 1.8.0"])
+    s.add_dependency(%q<gem_hadar>.freeze, ["~> 1.9.1"])
     s.add_dependency(%q<rake>.freeze, [">= 0"])
     s.add_dependency(%q<simplecov>.freeze, [">= 0"])
     s.add_dependency(%q<rspec>.freeze, [">= 0"])
+    s.add_dependency(%q<yard>.freeze, [">= 0"])
     s.add_dependency(%q<tins>.freeze, ["~> 1.0"])
     s.add_dependency(%q<mize>.freeze, [">= 0"])
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unicorn_relay
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Florian Frank
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-11 00:00:00.000000000 Z
+date: 2016-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gem_hadar
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.8.0
+        version: 1.9.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.8.0
+        version: 1.9.1
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: tins
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +122,7 @@ extra_rdoc_files:
 files:
 - ".gitignore"
 - ".rspec"
+- ".travis.yml"
 - ".utilsrc"
 - Gemfile
 - README.md