turnout 0.1.0 → 0.2.0

data/MIT-LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2011 by Biola University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,82 @@
+Turnout
+=======
+Turnout is a [Ruby on Rails](http://rubyonrails.org) engine with a [Rack](http://rack.rubyforge.org/) component that allows you to put your Rails app in maintenance mode.
+
+Features
+========
+* Easy installation
+* Rake commands to turn maintenance mode on and off
+* Easily provide a reason for each downtime without editing the maintenance.html file
+* Allow certain IPs or IP ranges to bypass the maintenance page
+* Allow certain paths to be accessible during maintenance
+* Easily override the default maintenance.html file with your own
+* Simple [YAML](http://yaml.org) based config file for easy activation, deactivation and configuration without the rake commands
+
+Installation
+============
+In your Gemfile add:
+
+    gem 'turnout'
+
+then run
+
+    bundle install
+
+Activation
+==========
+
+    rake maintenance:start
+
+or
+
+    rake maintenance:start reason="Somebody googled Google!"
+    
+or
+
+    rake maintenance:start allowed_paths="/login,^/faqs/[0-9]*"
+
+or
+
+    rake maintenance:start allowed_ips="4.8.15.16"
+
+or
+
+    rake maintenance:start reason="Someone told me I should type <code>sudo rm -rf /</code>" allowed_paths="^/help,^/contact_us" allowed_ips="127.0.0.1,192.168.0.0/24"
+
+Notes
+-----
+* The `reason` parameter can contain HTML
+* Multiple `allowed_paths` and `allowed_ips` can be given. Just comma separate them.
+* All `allowed_paths` are treated as regular expressions.
+* If you need to use a comma in an `allowed_paths` regular expression just escape it with a backslash: `\,`.
+* IP ranges can be given to `allowed_ips` using [CIDR notation](http://en.wikipedia.org/wiki/CIDR_notation).
+
+Deactivation
+============
+
+    rake maintenance:end
+
+Customization
+=============
+
+A [default maintenance page](https://github.com/biola/turnout/blob/master/public/maintenance.html) is provided, but you can create your own `public/maintenance.html` instead. If you provide a `reason` to the rake task, Turnout will use [Nokogiri](http://nokogiri.org) to parse the `maintenance.html` file and attempt to find a tag with `id="reason"`. It will replace the `inner_html` of the tag with the reason you provided. So be sure your `maintenance.html` file can be parsed as HTML.
+
+Behind the Scenes
+=================
+On every request the Rack app will check to see if `tmp/maintenance.yml` exists. If the file exists the maintenance page will be shown (unless allowed IPs are given and the requester is in the allowed range).
+
+So if you want to get the maintenance page up or down in a hury `touch tmp/maintenance.yml` and `rm tmp/maintenance.yml` will work.
+
+Turnout will attempt to parse the `maintenance.yml` file looking for `reason` and `allowed_ip` settings. The file is not cached so you can change these values manually or just rerun the `rake maintenance:start` command.
+
+Example maintenance.yml File
+----------------------------
+
+    ---
+    reason: Someone told me I should type <code>sudo rm -rf /</code>
+    allowed_paths:
+    - ^/help
+    - ^/contact_us
+    allowed_ips:
+    - 127.0.0.1
+    - 192.168.0.0/24

data/lib/rack/turnout.rb

@@ -25,10 +25,18 @@ class Rack::Turnout
   def on?(env)
     request = Rack::Request.new(env)
     
+    return false if path_allowed?(request.path)
     return false if ip_allowed?(request.ip)
     File.exists? settings_file
   end
 
+  def path_allowed?(path)
+    (settings['allowed_paths'] || []).each do |allowed_path|
+      return true if path =~ Regexp.new(allowed_path)
+    end
+    false
+  end
+
   def ip_allowed?(ip)
     ip = IPAddr.new(ip) unless ip.is_a? IPAddr
     (settings['allowed_ips'] || []).each do |allowed_ip|

data/lib/tasks/maintenance.rake

@@ -2,20 +2,42 @@ namespace :maintenance do
 
   desc 'Enable the maintenance mode page ("reason" and/or "allowed_ips" can be passed as environment variables)'
   task :start do |t, args|
-    settings = { 'reason' => ENV['reason'], 'allowed_ips' => ENV['allowed_ips'].to_s.split(',') }
+    settings = {
+      'reason' => ENV['reason'],
+      'allowed_paths' => split_paths(ENV['allowed_paths']),
+      'allowed_ips' => split_ips(ENV['allowed_ips'])
+    }
      
     file = File.open settings_file, 'w'
     file.write settings.to_yaml
     file.close
+    
+    puts "Created #{settings_file}"
+    puts "Run `rake maintenance:end` to stop maintenance mode"
   end
 
   desc 'Disable the maintenance mode page'
   task :end do 
     File.delete settings_file
+    
+    puts "Deleted #{settings_file}"
   end
   
   def settings_file
     Rails.root.join('tmp', 'maintenance.yml')
   end
 
+  def split_paths(paths_string)
+    # used negative lookbehind to split on "," but not on "\,"
+    paths = paths_string.to_s.split(/(?<!\\),\ ?/)
+    paths.map! do |path|
+      path.gsub('\,', ',') # remove the escape characters
+    end
+    paths
+  end
+
+  def split_ips(ips_string)
+    ips_string.to_s.split(',')
+  end
+
 end

data/lib/turnout/version.rb

@@ -1,5 +1,5 @@
 module Turnout
 
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turnout
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,12 +9,12 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-07-15 00:00:00.000000000 -07:00
+date: 2011-07-28 00:00:00.000000000 -07:00
 default_executable: 
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &86563140 !ruby/object:Gem::Requirement
+  requirement: &71247680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -22,7 +22,7 @@ dependencies:
         version: '1.3'
   type: :runtime
   prerelease: false
-  version_requirements: *86563140
+  version_requirements: *71247680
 description: Turnout makes it easy to put your Rails application into maintenance
   mode
 email: adam.crownoble@biola.edu
@@ -30,6 +30,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.markdown
+- MIT-LICENSE
 - lib/turnout.rb
 - lib/rack/turnout.rb
 - lib/turnout/version.rb