stalin 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1895ae07adb3fd17811e68a5762343a42a424c55
-  data.tar.gz: d703399879596243653ed8d4b2a1380fdbc64890
+  metadata.gz: 0a33b561b1435c293a784b49b327fd2a9ae097a6
+  data.tar.gz: ac36a422c5daff8765e4ef426bae938cdf1b5229
 SHA512:
-  metadata.gz: fec5772f43ae44d775b5fce828f47d64555423eb2f271bcee8a006af8aeb0c53127b6d1091b840e85442c393d7cb41f4cc65aad7a363c7e1dfcfc4bf11736948
-  data.tar.gz: 1753c88baab75f9e0a77f1427b00f2f0d3194b973fcde1886f1d3eb4ef7d67ba7d68716d8e15595dc0696a2f4b9855d136c99d671e72623da501b95f6269bc7b
+  metadata.gz: 66788da1669aee34f376f25242b212e620f38914b92fe3b13abac429478bcd54ca2958448d282df3e9437ac7296f8cb80d4ec322e5689c33b6985c7481ff4bc4
+  data.tar.gz: c34ca0a488667afc8023f68bb4514cc41b6df9a59016b787ddf38ec4fcd506c28b61ef7fb8f7011d31279bebde60f9bda092b09141b0bf0134b89016894049d4

data/README.md

@@ -4,7 +4,7 @@ Given Ruby's proclivity for heap fragmentation, Web application worker processes
 all available memory unless the server is restarted periodically. When all of the workers restart
 at once, downtime or bad request throughput may result.
 
-Stalin is a gem that gradually kills your workers before they cause swapping, resulting in better
+Stalin is a gem that gracefully kills your workers before they cause swapping, resulting in better
 availability for your application. Its design goals are modularity and compatibility with a range
 of platforms and app servers.
 
@@ -18,9 +18,13 @@ Data sources include:
 Supported app servers include:
   - Rainbows (via Rack middleware + SIGQUIT) 
   - Unicorn (via Rack middleware + SIGQUIT)
+  - Puma (via Rack middleware + SIGTERM/SIGUSR2 depending on execution model)
 
-(As you can see, we are far short of our _goal_ to support many servers! More to come as needed;
-I'm happy to take your contributions.)
+Servers known NOT to work:
+  - Thin (no supervisor process; need an adapter that execs or something)
+
+As you can see, we are far short of our _goal_ to support many servers! More to come as needed;
+let me know what you need!
 
 # Installation
 
@@ -30,14 +34,24 @@ Just include stalin in your Gemfile.
 
 # Usage
 
-Add these lines near the top of your `config.ru`
+Decide on which application server you will use. Add some lines to your `config.ru` to
+install a suitable Stalin middleware.
 
-    # Unicorn self-process killer
+    # Gem that kills app processes when their heap becomes too fragmented.
     require 'stalin'
 
     # Max memory size (RSS) per worker
     mb = 1024**2
-    use Stalin::Adapter::Rack, (192*mb), (256*mb)
+    
+    # Or Stalin::Adapter::Puma
+    use Stalin::Adapter::Unicorn, (192*mb), (256*mb)
+
+If you instantiate Stalin::Adapter::Rack directly, you have two choices:
+  - Pass three parameters (app, graceful-shutdown signal and abrupt-shutdown signal) to decide on signalling behavior yourself
+  - Pass one parameter (app) to let Stalin decide which adapter to use based on which server is resident in memory
+  
+Instantiating the Rack middleware with one parameter is deprecated; we'd much rather you be
+explicit about your application server than rely on our heuristic!
 
 # Tuning
 

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.1.0

data/lib/stalin/adapter/puma.rb

@@ -0,0 +1,28 @@
+module Stalin::Adapter
+  # A Stalin adapter that is suitable for use in Puma worker processes. Puma uses SIGTERM
+  # to initiate orderly shutdown and seems to respond to SIGQUIT with an abrupt shutdown.
+  class Puma < Rack
+    # Create a middleware instance.
+    #
+    # @param [#call] app inner Rack application
+    # @param [Integer] min lower-bound worker memory consumption before restart
+    # @param [Integer] max upper-bound worker memory consumption before restart
+    # @param [Integer] cycle how frequently to check memory consumption (# requests)
+    # @param [Boolean] verbose log extra information
+    def initialize(app, min=1024**3, max=2*1024**3, cycle=16, verbose=false)
+      cli = nil
+      ObjectSpace.each_object(::Puma::CLI) { |o| cli = o }
+
+      raise RuntimeError, "Puma does not appear to be active; no instances of Puma::CLI reside in memory" unless cli
+
+      if cli.clustered? && cli.options[:workers] > 0
+        # We're clustered, so workers can SIGTERM themselves to cause a restart
+        super(app, :TERM, :QUIT, min, max, cycle, verbose)
+      else
+        # We're running in single mode; our one-and-only process must USR2 to restart
+        # itself
+        super(app, :USR2, :USR1, min, max, cycle, verbose)
+      end
+    end
+  end
+end

data/lib/stalin/adapter/rack.rb

@@ -1,24 +1,65 @@
 module Stalin::Adapter
   # A low-tech but reliable solution that invokes stalin using Rack middleware.
-  # This is suitable for servers that handle SIGQUIT gracefully and spawn new
-  # worker processes as needed.
+  # This is suitable for application srvers that use a master-and-workers
+  # process architecture, wohse workers respond to a graceful shutdown signal,
+  # and whose masters spawn new workers as needed.
+  #
+  # This functions as a base class for server-specific middlewares, and can be used if
+  # there is an app server that uses a signalling strategy not explicitly supported by Stalin.
   class Rack
     # Conversion constant for human-readable memory amounts in log messages.
     MB = Float(1024**2)
 
+    # Construct a new middleware. If all six arguments are passed, construct an instance
+    # of this class; otherwise, use a heuristic to construct an instance of a suitable
+    # derived class.
+    #
+    # @raise [ArgumentError] if an incorrect number of arguments is passed
+    # @raise [RuntimeError] if 0..5 arguments and the heuristic can't figure out which signals to use
+    def self.new(*args)
+      case args.length
+      when 7
+        # Construct an instance of this (or a derived) class with signals explicitly specified.
+        super
+      when 3..6
+        # Warn that this shim will go away in v2
+        warn "Rack.new with fewer than 7 arguments is deprecated; please instantiate a derived class e.g. Unicorn.new or Puma.new"
+
+        # Use a heuristic to decide on the correct adapter and instantiate a derived class.
+        if defined?(::Unicorn)
+          middleware = Unicorn.allocate
+        elsif defined?(::Puma)
+          middleware = Puma.allocate
+        else
+          raise RuntimeError, "Cannot determine a suitable Stalin adapter; please instantiate this class with six arguments"
+        end
+
+        # Initialize our new object (ugh)
+        middleware.instance_eval { initialize(*args) }
+        middleware
+      else
+        raise ArgumentError, "Wrong number of arguments (#{args.length} for 3..7)"
+      end
+    end
+
     # Create a middleware instance.
     #
-    # @param [#call] app
+    # @param [#call] app inner Rack application
+    # @param [Symbol] graceful name of graceful-shutdown signal
+    # @param [Symbol] abrupt name of abrupt-shutdown signal
     # @param [Integer] min lower-bound worker memory consumption before restart
     # @param [Integer] max upper-bound worker memory consumption before restart
     # @param [Integer] cycle how frequently to check memory consumption (# requests)
     # @param [Boolean] verbose log extra information
-    def initialize(app, min=1024**3, max=2*1024**3, cycle=16, verbose=false)
-      @app     = app
-      @min     = min
-      @max     = max
-      @cycle   = cycle
-      @verbose = verbose
+    # @param [Array] signals pair of two Symbol signal-names: one for "graceful shutdown please" and one for "terminate immediately"
+    def initialize(app, graceful, abrupt, min=1024**3, max=2*1024**3, cycle=16, verbose=false)
+      @app      = app
+      @graceful = graceful
+      @abrupt   = abrupt
+      @min      = min
+      @max      = max
+      @cycle    = cycle
+      @verbose  = verbose
     end
 
     def call(env)
@@ -34,7 +75,7 @@ module Stalin::Adapter
         if @req % @cycle == 0
           @req = 0
           @watcher ||= ::Stalin::Watcher.new(Process.pid)
-          @killer  ||= ::Stalin::Killer.new(Process.pid)
+          @killer  ||= ::Stalin::Killer.new(Process.pid, @graceful, @abrupt)
           if (used = @watcher.watch) > @lim
             sig = @killer.kill
             @watcher.watch

data/lib/stalin/adapter/unicorn.rb

@@ -0,0 +1,15 @@
+module Stalin::Adapter
+  # A Stalin adapter that is suitable for use in Unicorn worker processes.
+  class Unicorn < Rack
+    # Create a middleware instance.
+    #
+    # @param [#call] app inner Rack application
+    # @param [Integer] min lower-bound worker memory consumption before restart
+    # @param [Integer] max upper-bound worker memory consumption before restart
+    # @param [Integer] cycle how frequently to check memory consumption (# requests)
+    # @param [Boolean] verbose log extra information
+    def initialize(app, min=1024**3, max=2*1024**3, cycle=16, verbose=false)
+      super(app, :QUIT, :TERM, min, max, cycle, verbose)
+    end
+  end
+end

data/lib/stalin/adapter.rb

@@ -5,3 +5,5 @@ module Stalin
 end
 
 require 'stalin/adapter/rack'
+require 'stalin/adapter/unicorn'
+require 'stalin/adapter/puma'

data/lib/stalin/killer.rb

@@ -1,26 +1,28 @@
 module Stalin
   # Kill a process by sending SIGQUIT several times, then SIGTERM, and finally SIGKILL.
   class Killer
-    # Number of cumulative tries to send SIGQUIT before we escalate to SIGTERM
-    MAX_QUIT = 10
-    # Number of cumulative tries before we escalate to SIGKILL
-    MAX_TERM = 15
+    # Number of cumulative shutdown tries before we escalate to abrupt-shutdown
+    MAX_GRACEFUL = 10
+    # Number of cumulative shutdown tries before we escalate to untrappable SIGKILL
+    MAX_ABRUPT = 15
 
     # @param [Integer] pid target process ID
-    def initialize(pid)
-      @pid = pid
-      @tries = 0
+    def initialize(pid, graceful, abrupt)
+      @pid      = pid
+      @graceful = graceful
+      @abrupt   = abrupt
+      @tries    = 0
     end
 
     # Try to kill the target process by sending it a shutdown signal.
     #
-    # @return [:QUIT,:TERM,:KILL] name of signal that we sent
+    # @return [Symbol] name of signal that we sent
     def kill
       case @tries
-      when (0...MAX_QUIT)
-        sig = :QUIT
-      when (MAX_QUIT...MAX_TERM)
-        sig = :TERM
+      when (0...MAX_GRACEFUL)
+        sig = @graceful
+      when (MAX_GRACEFUL...MAX_ABRUPT)
+        sig = @abrupt
       else
         sig = :KILL
       end
@@ -30,4 +32,4 @@ module Stalin
       sig
     end
   end
-end
+end

data/stalin.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: stalin 0.0.2 ruby lib
+# stub: stalin 0.1.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "stalin"
-  s.version = "0.0.2"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Tony Spataro"]
-  s.date = "2015-02-10"
+  s.date = "2015-04-17"
   s.description = "Kill Web application workers based on arbitrary conditions."
   s.email = "xeger@xeger.net"
   s.extra_rdoc_files = [
@@ -27,7 +27,9 @@ Gem::Specification.new do |s|
     "VERSION",
     "lib/stalin.rb",
     "lib/stalin/adapter.rb",
+    "lib/stalin/adapter/puma.rb",
     "lib/stalin/adapter/rack.rb",
+    "lib/stalin/adapter/unicorn.rb",
     "lib/stalin/killer.rb",
     "lib/stalin/watcher.rb",
     "lib/stalin/watcher/linux_proc_statm.rb",
@@ -47,17 +49,23 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<rspec>, ["~> 3.0"])
       s.add_development_dependency(%q<sinatra>, ["~> 1.4"])
       s.add_development_dependency(%q<unicorn>, ["~> 4.8"])
+      s.add_development_dependency(%q<thin>, ["~> 1.6"])
+      s.add_development_dependency(%q<puma>, ["~> 2.11"])
     else
       s.add_dependency(%q<jeweler>, ["~> 2.0"])
       s.add_dependency(%q<rspec>, ["~> 3.0"])
       s.add_dependency(%q<sinatra>, ["~> 1.4"])
       s.add_dependency(%q<unicorn>, ["~> 4.8"])
+      s.add_dependency(%q<thin>, ["~> 1.6"])
+      s.add_dependency(%q<puma>, ["~> 2.11"])
     end
   else
     s.add_dependency(%q<jeweler>, ["~> 2.0"])
     s.add_dependency(%q<rspec>, ["~> 3.0"])
     s.add_dependency(%q<sinatra>, ["~> 1.4"])
     s.add_dependency(%q<unicorn>, ["~> 4.8"])
+    s.add_dependency(%q<thin>, ["~> 1.6"])
+    s.add_dependency(%q<puma>, ["~> 2.11"])
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stalin
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Tony Spataro
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-12 00:00:00.000000000 Z
+date: 2015-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jeweler
@@ -66,6 +66,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.8'
+- !ruby/object:Gem::Dependency
+  name: thin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.11'
 description: Kill Web application workers based on arbitrary conditions.
 email: xeger@xeger.net
 executables: []
@@ -82,7 +110,9 @@ files:
 - VERSION
 - lib/stalin.rb
 - lib/stalin/adapter.rb
+- lib/stalin/adapter/puma.rb
 - lib/stalin/adapter/rack.rb
+- lib/stalin/adapter/unicorn.rb
 - lib/stalin/killer.rb
 - lib/stalin/watcher.rb
 - lib/stalin/watcher/linux_proc_statm.rb