rack-rewrite 0.1.0 → 0.1.1

data/README.rdoc

@@ -1,21 +1,89 @@
 = rack-rewrite
 
-A rack middleware for enforcing rewrite rules. In many cases you can get away with rack-rewrite
-instead of writing Apache mod_rewrite rules.
+A rack middleware for defining and applying rewrite rules. In many cases you 
+can get away with rack-rewrite instead of writing Apache mod_rewrite rules.
 
-== Usage in a rails app
+== Use Cases
+
+=== Rebuild of existing site in a new technology
+
+It's very common for sites built in older technologies to be rebuilt with the 
+latest and greatest.  Let's consider a site that has already established quite
+a bit of "google juice."  When we launch the new site, we don't want to lose
+that hard-earned reputation.  By writing rewrite rules that issue 301's for
+old URL's, we can "transfer" that google ranking to the new site.  An example
+rule might look like:
+
+  rewrite '/contact-us.php', '/contact-us'
+  rewrite '/wiki/John_Trupiano', '/john'
+
+=== Retiring old routes
+
+As a web application evolves you will undoubtedly reach a point where you need
+to change the name of something (a model, e.g.).  This name change will
+typically require a similar change to your routing.  The danger here is that
+any URL's previously generated (in a transactional email for instance) will
+have the URL hard-coded.  In order for your rails app to continue to serve
+this URL, you'll need to add an extra entry to your routes file.
+Alternatively, you could use rack-rewrite to redirect or pass through requests
+to these routes and keep your routes.rb clean.
+
+  rewrite %r{/features(.*)}, '/facial_features$1'
+
+== Sample rackup file
+  
+  use Rack::Rewrite do
+    rewrite '/wiki/John_Trupiano', '/john'
+    r301 '/wiki/Yair_Flicker', '/yair'
+    r302 '/wiki/Greg_Jastrab', '/greg'
+    r301 %r{/wiki/(\w+)_\w+}, '/$1'
+  end
+
+== Sample usage in a rails app
   config.gem 'rack-rewrite', '~> 0.1.0'
+  require 'rack-rewrite
   config.middleware.insert_before(Rack::Lock, Rack::Rewrite) do
     rewrite '/wiki/John_Trupiano', '/john'
     r301 '/wiki/Yair_Flicker', '/yair'
     r302 '/wiki/Greg_Jastrab', '/greg'
+    r301 %r{/wiki/(\w+)_\w+}, '/$1'
   end
+  
+== Rewrite Rules
+
+=== :rewrite
+
+Calls to #rewrite will simply update the PATH_INFO and REQUEST_URI HTTP header
+values and pass the request onto the next chain in the Rack stack.  The URL
+that a user's browser will show will not be changed.  See these examples:
+
+  rewrite '/wiki/John_Trupiano', '/john'   # [1]
+  rewrite %r{/wiki/(\w+)_\w+}, '/$1'       # [2]
+
+For [1], the user's browser will continue to display /wiki/John_Trupiano, but
+the actual HTTP header values for PATH_INFO and REQUEST_URI in the request 
+will be changed to /john for subsequent nodes in the Rack stack.  Rails
+reads these headers to determine which routes will match.
+
+Rule [2] showcases the use of regular expressions and substitutions.  [2] is a 
+generalized version of [1] that will match any /wiki/FirstName_LastName URL's
+and rewrite them as the first name only.  This is an actual catch-all rule we 
+applied when we rebuilt our website in September 2009 
+( http://www.smartlogicsolutions.com ).
 
-== Notes
+=== :r301, :302
 
-* Haven't tested full paths for :rewrite, :r301, :r302
-* No regular expression support yet
+Calls to #r301 and #r302 have the same signature as #rewrite.  The difference,
+however, is that these actually short-circuit the rack stack and send back
+301's and 302's, respectively.  See these examples:
 
+  r301 '/wiki/John_Trupiano', '/john'                # [1]
+  r301 '/wiki/(.*)', 'http://www.google.com/?q=$1'   # [2]
+  
+Recall that rules are interpreted from top to bottom.  So you can install 
+"default" rewrite rules if you like.  [2] is a sample default rule that
+will redirect all other requests to the wiki to a google search.
+  
 == Copyright
 
 Copyright (c) 2009 John Trupiano. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/lib/rack-rewrite.rb

@@ -1,4 +1,10 @@
+$: << File.expand_path(File.dirname(__FILE__))
+
+require 'rack-rewrite/rule'
+
 module Rack
+  # A rack middleware for defining and applying rewrite rules. In many cases you 
+  # can get away with rack-rewrite instead of writing Apache mod_rewrite rules.  
   class Rewrite
     def initialize(app, &rule_block)
       @app = app
@@ -7,49 +13,17 @@ module Rack
     end
     
     def call(env)
-      if matched_rule = find_rule(env)
-        apply(matched_rule, env)
-      else
-        @app.call(env)
+      if matched_rule = find_first_matching_rule(env)
+        rack_response = matched_rule.apply!(env)
+        # Don't invoke the app if applying the rule returns a rack response
+        return rack_response unless rack_response === true
       end
+      @app.call(env)
     end
-    
-    # This logic needs to be pushed into Rule subclasses
-    def apply(rule, env)
-      case rule[0]
-      when :r301
-        [301, {'Location' => rule[2]}, ['Redirecting...']]
-      when :r302
-        [302, {'Location' => rule[2]}, ['Redirecting...']]
-      when :rewrite
-        # return [200, {}, {:content => env.inspect}]
-        env['PATH_INFO'] = env['REQUEST_URI'] = rule[2]
-        @app.call(env)
-      else
-        raise Exception.new("Unsupported rule: #{rule[0]}")
-      end
-    end
-    
-    # This will probably have to change as rule matching gets more complicated
-    def find_rule(env)
-      @rule_set.rules.detect { |rule| rule[1] == env['PATH_INFO'] }
-    end
-    
-    class RuleSet
-      
-      attr_reader :rules
-      def initialize
-        @rules = []
-      end
-      
-      private
-        # We're explicitly defining the functions for our DSL rather than using
-        # method_missing
-        %w(rewrite r301 r302).each do |meth|
-          define_method(meth) do |from, to|
-            @rules << [meth.to_sym, from, to]
-          end
-        end
-    end
+        
+    private
+      def find_first_matching_rule(env) #:nodoc:
+        @rule_set.rules.detect { |rule| rule.matches?(env['PATH_INFO']) }
+      end    
   end
 end

data/lib/rack-rewrite/rule.rb

@@ -0,0 +1,92 @@
+module Rack
+  class Rewrite
+    class RuleSet
+      attr_reader :rules
+      def initialize #:nodoc:
+        @rules = []
+      end
+
+      protected
+        # We're explicitly defining private functions for our DSL rather than
+        # using method_missing
+        
+        # Creates a rewrite rule that will simply rewrite the REQUEST_URI and
+        # PATH_INFO headers of the Rack environment.  The user's browser
+        # will continue to show the initially requested URL.
+        # 
+        #  rewrite '/wiki/John_Trupiano', '/john'
+        #  rewrite %r{/wiki/(\w+)_\w+}, '/$1'        
+        def rewrite(from, to)
+          @rules << Rule.new(:rewrite, from, to)
+        end
+        
+        # Creates a redirect rule that will send a 301 when matching.
+        #
+        #  r301 '/wiki/John_Trupiano', '/john'
+        #  r301 '/contact-us.php', '/contact-us'
+        def r301(from, to)
+          @rules << Rule.new(:r301, from, to)
+        end
+        
+        # Creates a redirect rule that will send a 302 when matching.
+        #
+        #  r302 '/wiki/John_Trupiano', '/john'
+        #  r302 '/wiki/(.*)', 'http://www.google.com/?q=$1'
+        def r302(from, to)
+          @rules << Rule.new(:r302, from, to)
+        end
+    end
+
+    # TODO: Break rules into subclasses
+    class Rule #:nodoc:
+      attr_reader :rule_type, :from, :to
+      def initialize(rule_type, from, to) #:nodoc:
+        @rule_type, @from, @to = rule_type, from, to
+      end
+
+      def matches?(path) #:nodoc:
+        case self.from
+        when Regexp
+          path =~ self.from
+        when String
+          path == self.from
+        else
+          false
+        end
+      end
+
+      # Either (a) return a Rack response (short-circuting the Rack stack), or
+      # (b) alter env as necessary and return true
+      def apply!(env) #:nodoc:
+        interpreted_to = self.send(:interpret_to, env['PATH_INFO'])
+        case self.rule_type
+        when :r301
+          [301, {'Location' => interpreted_to}, ['Redirecting...']]
+        when :r302
+          [302, {'Location' => interpreted_to}, ['Redirecting...']]
+        when :rewrite
+          # return [200, {}, {:content => env.inspect}]
+          env['PATH_INFO'] = env['REQUEST_URI'] = interpreted_to
+          true
+        else
+          raise Exception.new("Unsupported rule: #{rule.rule_type}")
+        end
+      end
+      
+      private
+        # is there a better way to do this?
+        def interpret_to(path) #:nodoc:
+          if self.from.is_a?(Regexp)
+            if from_match_data = self.from.match(path)
+              computed_to = self.to.dup
+              (from_match_data.size - 1).downto(1) do |num|
+                computed_to.gsub!("$#{num}", from_match_data[num])
+              end
+              return computed_to
+            end
+          end
+          self.to
+        end
+    end 
+  end
+end

data/rack-rewrite.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{rack-rewrite}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["John Trupiano"]
-  s.date = %q{2009-10-10}
+  s.date = %q{2009-10-12}
   s.description = %q{A rack middleware for enforcing rewrite rules. In many cases you can get away with rack-rewrite instead of writing Apache mod_rewrite rules.}
   s.email = %q{jtrupiano@gmail.com}
   s.extra_rdoc_files = [
@@ -24,8 +24,10 @@ Gem::Specification.new do |s|
      "Rakefile",
      "VERSION",
      "lib/rack-rewrite.rb",
+     "lib/rack-rewrite/rule.rb",
      "rack-rewrite.gemspec",
      "test/rack-rewrite_test.rb",
+     "test/rule_test.rb",
      "test/test_helper.rb"
   ]
   s.homepage = %q{http://github.com/jtrupiano/rack-rewrite}
@@ -36,6 +38,7 @@ Gem::Specification.new do |s|
   s.summary = %q{A rack middleware for enforcing rewrite rules}
   s.test_files = [
     "test/rack-rewrite_test.rb",
+     "test/rule_test.rb",
      "test/test_helper.rb"
   ]
 

data/test/rule_test.rb

@@ -0,0 +1,84 @@
+require 'test_helper'
+
+class RuleTest < Test::Unit::TestCase
+
+  context '#Rule#apply' do
+    should 'set Location header to result of #interpret_to for a 301' do
+      rule = Rack::Rewrite::Rule.new(:r301, %r{/abc}, '/def')
+      env = {'PATH_INFO' => '/abc'}
+      assert_equal rule.send(:interpret_to, '/abc'), rule.apply!(env)[1]['Location']
+    end
+  end
+  
+  context 'Rule#matches' do
+    
+    context 'Given any rule with a "from" string of /features' do
+      setup do
+        @rule = Rack::Rewrite::Rule.new(:rewrite, '/features', '/facial_features')
+      end
+      
+      should 'match PATH_INFO of /features' do
+        assert @rule.matches?("/features")
+      end
+      
+      should 'not match PATH_INFO of /features.xml' do
+        assert !@rule.matches?("/features.xml")
+      end
+      
+      should 'not match PATH_INFO of /my_features' do
+        assert !@rule.matches?("/my_features")
+      end
+    end
+    
+    context 'Given any rule with a "from" regular expression of /features(.*)' do
+      setup do
+        @rule = Rack::Rewrite::Rule.new(:rewrite, %r{/features(.*)}, '/facial_features$1')
+      end
+    
+      should 'match PATH_INFO of /features' do
+        assert @rule.matches?("/features")
+      end
+    
+      should 'match PATH_INFO of /features.xml' do
+        assert @rule.matches?('/features.xml')
+      end
+    
+      should 'match PATH_INFO of /features/1' do
+        assert @rule.matches?('/features/1')
+      end
+    
+      should 'match PATH_INFO of /features?filter_by=name' do
+        assert @rule.matches?('/features?filter_by_name=name')
+      end
+    
+      should 'match PATH_INFO of /features/1?hide_bio=1' do
+        assert @rule.matches?('/features/1?hide_bio=1')
+      end
+    end
+  end
+  
+  context 'Rule#interpret_to' do
+    
+    should 'return #to when #from is a string' do
+      rule = Rack::Rewrite::Rule.new(:rewrite, '/abc', '/def')
+      assert_equal '/def', rule.send(:interpret_to, '/abc')
+    end
+    
+    should 'replace $1 on a match' do
+      rule = Rack::Rewrite::Rule.new(:rewrite, %r{/person_(\d+)}, '/people/$1')
+      assert_equal '/people/1', rule.send(:interpret_to, "/person_1")
+    end
+    
+    should 'be able to catch querystrings with a regexp match' do
+      rule = Rack::Rewrite::Rule.new(:rewrite, %r{/person_(\d+)(.*)}, '/people/$1$2')
+      assert_equal '/people/1?show_bio=1', rule.send(:interpret_to, '/person_1?show_bio=1')
+    end
+    
+    should 'be able to make 10 replacements' do
+      # regexp to reverse 10 characters
+      rule = Rack::Rewrite::Rule.new(:rewrite, %r{(\w)(\w)(\w)(\w)(\w)(\w)(\w)(\w)(\w)(\w)}, '$10$9$8$7$6$5$4$3$2$1')
+      assert_equal 'jihgfedcba', rule.send(:interpret_to, "abcdefghij")
+    end
+  end
+  
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rack-rewrite
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - John Trupiano
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-10 00:00:00 -04:00
+date: 2009-10-12 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -39,8 +39,10 @@ files:
 - Rakefile
 - VERSION
 - lib/rack-rewrite.rb
+- lib/rack-rewrite/rule.rb
 - rack-rewrite.gemspec
 - test/rack-rewrite_test.rb
+- test/rule_test.rb
 - test/test_helper.rb
 has_rdoc: true
 homepage: http://github.com/jtrupiano/rack-rewrite
@@ -72,4 +74,5 @@ specification_version: 3
 summary: A rack middleware for enforcing rewrite rules
 test_files: 
 - test/rack-rewrite_test.rb
+- test/rule_test.rb
 - test/test_helper.rb