stalin 0.0.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 1895ae07adb3fd17811e68a5762343a42a424c55
-  data.tar.gz: d703399879596243653ed8d4b2a1380fdbc64890
+SHA256:
+  metadata.gz: f573c1d3fa4d4b5247495ab63ef77a0c1f90471e5ab6efb232285c8321b33c82
+  data.tar.gz: 928cfad72a40b1f72b810520c42cc0e30a4f50d95da1cef3978892efada8dad5
 SHA512:
-  metadata.gz: fec5772f43ae44d775b5fce828f47d64555423eb2f271bcee8a006af8aeb0c53127b6d1091b840e85442c393d7cb41f4cc65aad7a363c7e1dfcfc4bf11736948
-  data.tar.gz: 1753c88baab75f9e0a77f1427b00f2f0d3194b973fcde1886f1d3eb4ef7d67ba7d68716d8e15595dc0696a2f4b9855d136c99d671e72623da501b95f6269bc7b
+  metadata.gz: 8120043d4aeab951066cb0ecc172d437e58072313feacbe2ba6442c7b69a25bb205c4d6c2f7802933ea67eac097c3c1cafa79bcc961adb0fde1d517e25aee0c8
+  data.tar.gz: ea0707661dbb0fcdb7efa233fd3950a219e59c53667bbaccaeb10e611b8fba8a07d597b7aaa76fa7d5bc8cb36ab444eee92cb38d705d13b92e85ebd5d9359e63

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,30 +18,73 @@ 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)
 
-# Installation
+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!
+
+# User's Guide
+
+## Installation
 
 Just include stalin in your Gemfile.
 
     gem 'stalin'
 
-# Usage
+## 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
+Because different app servers have different signal-handling and restart semantics, we
+must specialize Stalin's behavior; this is done with an abstract base class 
+(Stalin::Adapter::Rack) plus one derived class per supported application server.
+ 
+    # 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)
+    
+    # Use the Unicorn adapter to ensure we send Unicorn-friendly kill signals.
+    # Each worker will shutdown at some point between 192MB and 256MB of memory usage.
+    use Stalin::Adapter::Unicorn, (192*mb), (256*mb)
+
+## Tuning
+
+Consult the documentation for your adapter's `#initialize` to learn how to tune Stalin's behavior.
+
+# Developer's Guide
+
+This gem is a work in progress; the docs are okay, but test coverage is
+nonexistent. Whenever you make changes, please do some smoke tests by yourself.
+
+## Smoke Tests
+
+The `fixtures` subdirectory contains rackup files for both supported application
+servers; you can use these to test the three supported permutations.
+
+When you run puma or rainbows, it will begin listening on a port of its
+choosing; use curl or similar to send it Web requests and cause a large
+memory leak with every request. Each worker process should shutdown after the
+first request, because the leak is large and the hardcoded limit for puma is
+very small.
+
+Verify that stalin is restarting the app servers and that your requests all
+respond with 200 and not 502, 503 or other funny errors.
+
+### Unicorn
+
+    bundle exec unicorn fixtures/unicorn.ru 
+### Single-Process Puma
 
-# Tuning
+    bundle exec puma fixtures/puma.ru
+    
+### Multi-Process Puma
 
-TODO
+    bundle exec puma -w 1 fixtures/puma.ru
 
 # Special Thanks
 

data/Rakefile

@@ -9,6 +9,7 @@ Jeweler::Tasks.new do |gem|
   gem.description = %Q{Kill Web application workers based on arbitrary conditions.}
   gem.email = "xeger@xeger.net"
   gem.authors = ["Tony Spataro"]
+  gem.required_ruby_version = '~> 2.0'
   gem.files.exclude ".rspec"
   gem.files.exclude "Gemfile*"
   gem.files.exclude "fixtures/**/*"

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.2.1

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/adapter/puma.rb

@@ -0,0 +1,32 @@
+module Stalin::Adapter
+  # A Stalin adapter that is suitable for use in Puma worker processes. Puma has two
+  # execution models.
+  # - "Cluster" spawns N worker processes; each responds to SIGTERM with graceful shutdown and SIGQUIT with abrupt shutdown
+  # - "Single" runs a server in the one-and-only master process; it responds to SIGUSR2 with graceflu restart
+  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)
+      # Puma has no singletons, so we need to grab a reference to its CLI object.
+      # The CLI will not exist if puma was invoked through rackup.
+      #
+      # Since the master forks its workers, the CLI object also exists in workers.
+      # By the time this code runs, we'll always be in a worker.
+      cli = nil
+      ObjectSpace.each_object(::Puma::CLI) { |o| cli = o } if defined?(::Puma::CLI)
+
+      if cli && cli.clustered? && cli.options[:workers] > 0
+        # Multiprocess model: send ourselves SIGTERM
+        super(app, :TERM, :QUIT, min, max, cycle, verbose)
+      else
+        # Single-process model ("rackup," or "puma -w 0")
+        super(app, :USR2, :USR1, min, max, cycle, verbose)
+      end
+    end
+  end
+end

data/lib/stalin/adapter/rack.rb

@@ -1,24 +1,29 @@
 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.
+  # Abstract base class for server-specific Rack middlewares.
+  # 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)
 
     # 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, max, cycle, verbose)
+      @app      = app
+      @graceful = graceful
+      @abrupt   = abrupt
+      @min      = min
+      @max      = max
+      @cycle    = cycle
+      @verbose  = verbose
+      @req      = 0
     end
 
     def call(env)
@@ -27,22 +32,26 @@ module Stalin::Adapter
       logger = logger_for(env)
 
       begin
-        @lim     ||= @min + randomize(@max - @min + 1)
-        @req     ||= 0
-        @req     += 1
+        if @req == 0
+          # First-time initialization. Deferred until first request so we can
+          # ensure that init-time log output goes to the right place.
+          @lim     = @min + randomize(@max - @min + 1)
+          @req     = 0
+          @watcher = ::Stalin::Watcher.new(Process.pid)
+          @killer  = ::Stalin::Killer.new(Process.pid, @graceful, @abrupt)
+          logger.info "stalin (pid: %d) startup; limit=%.1f MB, graceful=SIG%s (abrupt=SIG%s after %d tries)" %
+                        [Process.pid, @lim / MB, @graceful, @abrupt, Stalin::Killer::MAX_GRACEFUL]
+        end
+
+        @req += 1
 
         if @req % @cycle == 0
-          @req = 0
-          @watcher ||= ::Stalin::Watcher.new(Process.pid)
-          @killer  ||= ::Stalin::Killer.new(Process.pid)
           if (used = @watcher.watch) > @lim
             sig = @killer.kill
-            @watcher.watch
-            logger.info "stalin (pid: %d) send SIG%s; memory usage %.1f MB > %.1f MB" %
+            logger.info "stalin (pid: %d) send SIG%s; %.1f MB > %.1f MB" %
                           [Process.pid, sig, used / MB, @lim / MB]
-            @cycle = 2
           elsif @verbose
-            logger.info "stalin (pid: %d) soldiers on; memory usage %.1f MB < %.1f MB" %
+            logger.info "stalin (pid: %d) soldiers on; %.1f MB < %.1f MB" %
                            [Process.pid, used / MB, @lim / MB]
           end
         end
@@ -57,7 +66,7 @@ module Stalin::Adapter
     private
 
     def randomize(integer)
-      RUBY_VERSION > "1.9" ? Random.rand(integer.abs) : rand(integer)
+      Random.rand(integer.abs)
     end
 
     def logger_for(env)

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, :TERM, :QUIT, min, max, cycle, verbose)
+    end
+  end
+end

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.2.1 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "stalin"
-  s.version = "0.0.2"
+  s.version = "0.2.1"
 
   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 = "2020-06-11"
   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",
@@ -36,7 +38,8 @@ Gem::Specification.new do |s|
   ]
   s.homepage = "https://github.com/xeger/stalin"
   s.licenses = ["MIT"]
-  s.rubygems_version = "2.2.2"
+  s.required_ruby_version = Gem::Requirement.new("~> 2.0")
+  s.rubygems_version = "2.5.1"
   s.summary = "Kill rack"
 
   if s.respond_to? :specification_version then
@@ -47,17 +50,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.2.1
 platform: ruby
 authors:
 - Tony Spataro
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-12 00:00:00.000000000 Z
+date: 2020-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jeweler
@@ -66,6 +66,20 @@ 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'
 description: Kill Web application workers based on arbitrary conditions.
 email: xeger@xeger.net
 executables: []
@@ -82,7 +96,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
@@ -98,17 +114,16 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Kill rack