rack-nackmode 0.1.0

data/README.markdown

@@ -0,0 +1,63 @@
+# Rack::NackMode
+
+Middleware enabling zero-downtime maintenance behind a load balancer.
+
+## Overview
+
+`Rack::NackMode` adds a health check endpoint to your app that enables it to
+communicate to a load balancer its ability (or lack thereof) to serve requests.
+It supports a "NACK Mode" protocol, so that when your app wants to shut down, it
+makes sure the load balancer knows to stop sending it requests before doing so.
+It does this by responding to the health check request with a <em>n</em>egative
+<em>ack</em>nowledgement (NACK) until the load balancer marks it as down.  The app can
+(and should) continue to serve requests until that point.
+
+To make this work, your app needs to inform the middleware when it wants to shut
+down, and the middleware will call back when it's safe to do so.
+
+## Usage
+
+Basic example:
+
+```ruby
+class MyApp < Sinatra::Base
+  use Rack::NackMode do |health_check|
+    # store the middleware instance for calling #shutdown below
+    @health_check = health_check
+  end
+
+  class << self
+    def shutdown
+      if @health_check # see note below
+        @health_check.shutdown { exit 0 }
+      else
+        exit 0
+      end
+    end
+  end
+end
+```
+
+N.B. because Rack waits to initialise middleware until it receives an HTTP
+request, it's possible to shut down before the middleware is initialised.
+That's unlikely to be a problem, because having not received any HTTP requests,
+we've obviously not received any *health check* requests either, meaning the
+load balancer should already believe we're down: so it should be safe to
+shutdown immediately, as in the above example.
+
+### Configuration
+
+The `use` statement to initialise the middleware takes the following options:
+
+ * `:path` &ndash; path for the health check endpoint (default `/admin`)
+ * Customising whether the health check reports healthy or sick (except while
+   shutting down, when it will always report sick):
+     * `:healthy_if` &ndash; callback that should return `true` if your app is
+       able to serve requests, and `false` otherwise.
+     * `:sick_if` &ndash; callback that should return `false` if your app is
+       able to serve requests, and `true` otherwise.
+ * `:nacks_before_shutdown` &ndash; how many times the app should tell the load
+   balancer it's going down before it can safely do so.  Defaults to 3, which
+   matches e.g. haproxy's default for how many failed checks it needs before
+   marking a backend as down.
+ * `:logger` &ndash; middleware will log progress to this object if supplied.

data/lib/rack-nackmode.rb

@@ -0,0 +1 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'rack', 'nack_mode'))

data/lib/rack/nack_mode.rb

@@ -0,0 +1,129 @@
+require 'active_support/core_ext/hash/keys'
+
+module Rack
+  # Middleware that communicates impending shutdown to a load balancer via
+  # NACKing (negative acking) health checks.  Your app needs to inform the
+  # middleware when it wants to shut down, and the middleware will call back
+  # when it's safe to do so.
+  #
+  # Responds to health checks on /admin (configurable via :path option).
+  #
+  # Basic usage:
+  #     class MyApp < Sinatra::Base
+  #       use Rack::NackMode do |health_check|
+  #         # store the middleware instance for calling #shutdown below
+  #         @health_check = health_check
+  #       end
+  #
+  #       class << self
+  #         def shutdown
+  #           if @health_check
+  #             @health_check.shutdown { exit 0 }
+  #           else
+  #             exit 0
+  #           end
+  #         end
+  #       end
+  #     end
+  #
+  # N.B. because Rack waits to initialise middleware until it receives an HTTP
+  # request, it's possible to shut down before the middleware is initialised.
+  # That's unlikely to be a problem, because having not received any HTTP
+  # requests, we've obviously not received any *health check* requests either,
+  # meaning the load balancer should already believe we're down: so it should
+  # be safe to shutdown immediately, as in the above example.
+  class NackMode
+    # Default number of health checks we NACK before shutting down.  This
+    # matches e.g. haproxy's default for how many failed checks it needs before
+    # marking a backend as down.
+    DEFAULT_NACKS_BEFORE_SHUTDOWN = 3
+
+    def initialize(app, options = {})
+      @app = app
+
+      options.assert_valid_keys :path,
+                                :healthy_if,
+                                :sick_if,
+                                :nacks_before_shutdown,
+                                :logger
+      @path = options[:path] || '/admin'
+      @health_callback = if options[:healthy_if] && options[:sick_if]
+        raise ArgumentError, 'Please specify either :healthy_if or :sick_if, not both'
+      elsif healthy_if = options[:healthy_if]
+        healthy_if
+      elsif sick_if = options[:sick_if]
+        lambda { !sick_if.call }
+      else
+        lambda { true }
+      end
+      @nacks_before_shutdown = options[:nacks_before_shutdown] || DEFAULT_NACKS_BEFORE_SHUTDOWN
+      raise ArgumentError, ":nacks_before_shutdown must be at least 1" unless @nacks_before_shutdown >= 1
+      @logger = options[:logger]
+
+      yield self if block_given?
+    end
+
+    def call(env)
+      if health_check?(env)
+        health_check_response(env)
+      else
+        @app.call(env)
+      end
+    end
+
+    def shutdown(&block)
+      info "Shutting down after NACKing #@nacks_before_shutdown health checks"
+      @shutdown_callback = block
+    end
+
+    private
+    def health_check?(env)
+      env['PATH_INFO'] == @path && env['REQUEST_METHOD'] == 'GET'
+    end
+
+    def health_check_response(env)
+      if shutting_down?
+        @nacks_before_shutdown -= 1
+        if @nacks_before_shutdown <= 0
+          if defined?(EM)
+            EM.next_tick do
+              info 'Shutting down'
+              @shutdown_callback.call
+            end
+          else
+            info 'Shutting down'
+            @shutdown_callback.call
+          end
+        else
+          info "Waiting for #@nacks_before_shutdown more health checks"
+        end
+        respond_sick
+      elsif healthy?
+        respond_healthy
+      else
+        respond_sick
+      end
+    end
+
+    def shutting_down?
+      @shutdown_callback
+    end
+
+    def healthy?
+      @health_callback.call
+    end
+
+    def respond_healthy
+      [200, {}, ['GOOD']]
+    end
+
+    def respond_sick
+      info 'Telling load balancer we are sick'
+      [503, {}, ['BAD']]
+    end
+
+    def info(*args)
+      @logger.info(*args) if @logger
+    end
+  end
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: rack-nackmode
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Sam Stokes
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: em-spec-helpers
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ! 'Middleware that communicates impending shutdown to a load balancer
+  via NACKing
+
+  (negative acking) health checks.  Provided you have at least two load-balanced
+
+  instances, this allows you to shut down or restart an instance without dropping
+
+  any requests.
+
+
+  Your app needs to inform the middleware when it wants to shut down, and the
+
+  middleware will call back when it''s safe to do so.
+
+'
+email:
+- sam@rapportive.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/rack/nack_mode.rb
+- lib/rack-nackmode.rb
+- README.markdown
+homepage: http://github.com/rapportive-oss/rack-nackmode
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.19
+signing_key: 
+specification_version: 3
+summary: Middleware for zero-downtime maintenance behind a load balancer
+test_files: []
+has_rdoc: