rack-maintenance_mode 0.0.2 → 0.0.3

data/Gemfile

@@ -1,4 +1,2 @@
 source "http://rubygems.org"
-
-# Specify your gem's dependencies in maintenance_mode.gemspec
 gemspec

data/README.md

@@ -0,0 +1,160 @@
+# Rack::MaintenanceMode
+
+Rack::MaintenanceMode is a Rack middleware which manages sending clients
+maintenance (HTTP 503) responses, when appropriate.  It is intended to be robust
+and extensible, allowing you to meet your particular business needs.
+
+## Maintenance mode is easy. What's the deal?
+
+Glad you asked.  So, yes, in a lot of applications, maintenance mode is simple:
+all requests result in a 503 response.  But, as applications grow and business
+rules change, and … life happens … well, that's not always sufficient.
+
+Maybe you'd like to 503 on all public requests, but still allow requests from
+your IP to pass through it.  Maybe you want to 503 only requests to a particular
+subset of your URLs ("/api", for instance).  Maybe you want to be in maintenance
+mode based on some complex set of business rules (a particular column in the
+database has a set value, and it's a full moon tonight, and Kim Kardashian is
+married).  Whatever.
+
+## Installation
+
+If you're using Bundler, then add the gem to your Gemfile:
+
+```ruby
+gem 'rack-maintenance_mode'
+```
+
+Otherwise:
+
+```bash
+$ gem install rack-maintenance_mode
+```
+
+## How does it work?
+
+So, it's a Rack middleware.  That's pretty simple.  And, by default, it'll
+"just work," by watching for a `ENV["MAINTENANCE"]` variable to be set.  If
+it's set, it'll automatically respond with a default 503 response, containing
+a simple HTML page and message:
+
+> We are undergoing maintenance right now, please try again soon.
+
+## Customization
+
+The default, while useful, probably isn't exactly what you're looking for, is
+it?  So, how do we customize it?
+
+Well, if you're using Rails, then it will integrate with your application
+automatically using a Railtie.  This gives us a few things: first, the
+middleware will be automatically loaded for you.  And second, this gives you a
+simple way to override the default behaviour.
+
+### Customized maintenance mode logic
+
+You can create your own, custom, maintenance mode determination logic in a few
+ways.  Well, really… a ton of ways, but at the end of the day, you just need
+to encapsulate it in something that responds to `call`.  So, that could be a
+simple Proc, a module, a class, and instance, a mock, a stub, … I don't really
+care.  That's up to you.
+
+Here's a very simple example of a customization using the Railtie integration
+when using this gem with Rails (in `config/application.rb`):
+
+```ruby
+require File.expand_path('../boot', __FILE__)
+require 'rails/all'
+Bundler.require(:default, Rails.env) if defined?(Bundler)
+
+module MySuperApp
+  class Application < Rails::Application
+    …
+    config.maintenance_mode.if = Proc.new { |env| true }
+  end
+end
+```
+
+Hey look!  Every request is now in maintenance mode!  Ok, probably not so
+useful.  So, then:
+
+```ruby
+  config.maintenance_mode.if = Proc.new { |env|
+    ENV["MAINTENANCE"] == 'enabled' && !(env['PATH_INFO'] =~ /safe/)
+  }
+```
+
+Now, it'll only 503 if the ENV's maintenance flag is set and the request is to
+something other than a "safe" URL (i.e. "http://awesome.com/safe/foo").
+
+Maybe we don't like Procs all over the place.  Can't we make a class?
+
+```ruby
+# lib/maintenance.rb
+class Maintenance
+  def call(env)
+    ENV["MAINTENANCE"] == 'enabled' && !(env['PATH_INFO'] =~ /safe/)
+  end
+end
+
+# config/application.rb
+module MySuperApp
+  class Application < Rails::Application
+    …
+    config.maintenance_mode.if = Maintenance.new
+  end
+end
+```
+
+Sure can.
+
+"But wait," I hear you saying.  I still get the crappy default maintenance mode
+response.  I'd like to have super-pretty, customized page with CSS-based,
+shifting perspectives and whatnot.  Yes, we can.
+
+### Customized responses
+
+Customizing the response is pretty straightforward, as well.  Just as with
+customizing the maintenance logic, you can also customize the response.  The
+only real requirement, again, is that you use something that responds to `call`,
+which can accept a environment hash, and you return a Rack-compatible array.
+
+```ruby
+config.maintenance_mode.response = Proc.new { |env| [503, {'Content-Type' => 'text/plain'}, ['Go away']] }
+```
+
+This allows you to do some super-useful stuff.  Like, maybe by inspecting the
+`env`, you realize that it's an XML request, not HTML.  Well, you could send
+and XML response.  Or, maybe you'd like to load that pretty HTML page you've
+spent days crafting:
+
+```ruby
+config.maintenance_mode.response = Proc.new { |env| [503, {'Content-Type' => 'text/html'}, [Rails.root.join("public/503.html").read]] }
+```
+
+Or, maybe you like classes:
+
+```ruby
+# lib/maintenance_response.rb
+class MaintenanceResponse
+  def call(env)
+    content_type, body = case Pathname.new(env['PATH_INFO'])
+    when '.xml'
+      ['application/xml', '<error>Maintenance</error>']
+    when '.json'
+      ['application/json', 'Maintenance']
+    else
+      ['text/html', '<html><body>Maintenance</body></html>']
+    end
+
+    [503, {'Content-Type' => content_type}, [body]]
+  end
+end
+
+# config/application.rb
+module MySuperApp
+  class Application < Rails::Application
+    …
+    config.maintenance_mode.response = MaintenanceResponse.new
+  end
+end
+```

data/lib/rack/maintenance_mode.rb

@@ -4,6 +4,11 @@ require 'rack/maintenance_mode/middleware'
 require 'rack/maintenance_mode/railtie' if defined?(Rails)
 
 module Rack
+  ##
+  # Rack::MaintenanceMode is a Rack middleware which manages sending clients
+  # maintenance (HTTP 503) responses, when appropriate.  It is intended to be
+  # robust and extensible, allowing you to meet your particular business needs.
+  #
   module MaintenanceMode
   end
 end

data/lib/rack/maintenance_mode/default_mode_check.rb

@@ -1,6 +1,20 @@
 module Rack
   module MaintenanceMode
+    ##
+    # This is the default behaviour for the gem, with respect to determining
+    # whether or not a particular request should be responded to with a
+    # maintenance response.
+    #
     module DefaultModeCheck
+      ##
+      # With this implementation, maintenance mode will be enabled if there is
+      # an `ENV["MAINTENANCE"]` variable set and it has an acceptable value.
+      #
+      # Acceptable values for MAINTENANCE: on, yes, y, true, t, enable, enabled
+      #
+      # If the MAINTENANCE variable is unset or does not match one of the above
+      # values, maintenance mode is disabled.
+      #
       def self.call(env)
         ENV["MAINTENANCE"].to_s =~ /^(?:on|yes|y|true|t|enabled?)$/i
       end

data/lib/rack/maintenance_mode/middleware.rb

@@ -3,11 +3,21 @@ require 'rack/maintenance_mode/default_mode_check'
 module Rack
   module MaintenanceMode
     ##
-    # A Rack middleware to automatically put the Rack application into maintenance
-    # mode (HTTP 503).
+    # A Rack middleware to automatically put the Rack application into
+    # maintenance mode (HTTP 503).
     #
-    # This middleware allows you to optionally allow users to pass through the 503
-    # wall and access the application by IP or by route requested.
+    # The default behaviour may be overridden by passing specific options at
+    # the time of initialization.
+    #
+    # Available options:
+    #
+    # `:if` - Any object which responds to `call(hash)` and returns a
+    # true/false-like result.  Used for determining whether or not we're in
+    # maintenance mode.
+    #
+    # `:response` - Any object which responds to `call(hash)` and returns a
+    # Rack-compatible response array.  Used for generating the client response
+    # when in maintenance mode.
     #
     class Middleware
       DEFAULT_RESPONSE = Proc.new { |env| [503, {"Content-Type" => "text/html"}, ["<html><body><h2>We are undergoing maintenance right now, please try again soon.</body></html>"]] }

data/lib/rack/maintenance_mode/railtie.rb

@@ -1,5 +1,16 @@
 module Rack
   module MaintenanceMode
+    ##
+    # This is the primary integration point when using this gem within a Rails
+    # application.  This railtie allows for the following customizations:
+    #
+    # `config.maintenance_mode.if` - used for overriding the logic to determine
+    # whether or not the application is in maintenance mode.
+    #
+    # `config.maintenance_mode.response` - used for generating the maintenance
+    # response for the client when in maintenance mode.
+    #
+    #
     class Railtie < Rails::Railtie
       config.maintenance_mode = ActiveSupport::OrderedOptions.new
 

data/lib/rack/maintenance_mode/version.rb

@@ -1,5 +1,5 @@
 module Rack
   module MaintenanceMode
-    VERSION = "0.0.2"
+    VERSION = "0.0.3"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rack-maintenance_mode
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-01-05 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2151949620 !ruby/object:Gem::Requirement
+  requirement: &2156868180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '2.0'
   type: :development
   prerelease: false
-  version_requirements: *2151949620
+  version_requirements: *2156868180
 - !ruby/object:Gem::Dependency
   name: rack
-  requirement: &2151949120 !ruby/object:Gem::Requirement
+  requirement: &2156867680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: 1.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *2151949120
+  version_requirements: *2156867680
 description: Allows you to create a customized maintenance mode for your application
   that is run early in the Rack stack.
 email:
@@ -45,6 +45,7 @@ files:
 - .rspec
 - .rvmrc
 - Gemfile
+- README.md
 - Rakefile
 - lib/rack-maintenance_mode.rb
 - lib/rack/maintenance_mode.rb