refraction 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Pivotal Labs
+
+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.md

@@ -0,0 +1,117 @@
+Refraction
+==========
+
+Refraction is a Rack middleware replacement for `mod_rewrite`. It can rewrite URLs before they are
+processed by your web application, and can redirect using 301 and 302 status codes. Refraction is
+thread-safe, so it doesn't need to be guarded by Rack::Lock.
+
+The best thing about Refraction is that rewrite rules are written in plain old Ruby code, not some
+funky web server config syntax. That means you can use Ruby regular expressions, case statements,
+conditionals, and whatever else you feel like.
+
+For example:
+
+    Refraction.configure do |req|
+      feedburner  = "http://feeds.pivotallabs.com/pivotallabs"
+
+      if req.env['HTTP_USER_AGENT'] !~ /FeedBurner|FeedValidator/ && req.host =~ /pivotallabs\.com/
+        case req.path
+        when %r{^/(talks|blabs|blog)\.(atom|rss)$}        ; req.found! "#{feedburner}/#{$1}.#{$2}"
+        when %r{^/users/(chris|edward)/blog\.(atom|rss)$} ; req.found! "#{feedburner}/#{$1}.#{$2}"
+        end
+      else
+        case req.host
+        when 'tweed.pivotallabs.com'
+          req.rewrite! "http://pivotallabs.com/tweed#{req.path}"
+        when /([-\w]+\.)?pivotallabs\.com/
+          # passthrough with no change
+        else  # wildcard domains (e.g. pivotalabs.com)
+          req.permanent! :host => "pivotallabs.com"
+        end
+      end
+    end
+
+Notice the use of regular expressions, the $1, $2, etc pseudo-variables, and string interpolation.
+This is an easy way to match URL patterns and assemble the new URL based on what was matched.
+
+## Installation (Rails)
+
+Refraction can be installed in a Rails application as a plugin.
+
+    $ script/plugin install git://github.com/pivotal/refraction.git
+
+In `environments/production.rb`, add Refraction at or near the top of your middleware stack.
+
+    config.middleware.insert_before(::Rack::Lock, ::Refraction, {})
+
+You may want to occasionally turn on Refraction in the development environment for testing
+purposes, but if your rules redirect to other servers that can be a problem.
+
+Put your rules in `config/initializers/refraction_rules.rb` (see example above). The file name
+doesn't actually matter, but convention is useful.
+
+## Server Configuration
+
+If your application is serving multiple virtual hosts, it's probably easiest to configure your web
+server to handle a wildcard server name and let Refraction handle managing the virtual hosts. For
+example, in nginx, that is done with a `server_name _;` directive.
+
+## Writing Rules
+
+Set up your rewrite/redirection rules during your app initialization using `Refraction.configure`.
+The `configure` method takes a block which is run for every request to process the rules. The block
+is passed a RequestContext object that contains information about the request URL and environment.
+The request object also has a small API for effecting rewrites and redirects.
+
+> Important note: don't do a `return` from within the configuration
+> block.  That would be bad (meaning your entire application would
+> break).  That's just how blocks work in Ruby.
+
+### `RequestContext#set(options)`
+
+The `set` method takes an options hash that sets pieces of the rewritten URL or redirect location
+header.
+
+  * :scheme - Usually `http` or `https`.
+  * :host - The server name.
+  * :port - The server port.  Usually not needed, as the scheme implies a default value.
+  * :path - The path of the URL.
+  * :query - Added at the end of the URL after a question mark (?)
+
+Any URL components not explicitly set remain unchanged from the original request URL. You can use
+`set` before calls to `rewrite!`, `permanent!`, or `found!` to set common values. Subsequent
+methods will merge their component values into values from `set`.
+
+### `RequestContext#rewrite!(options)`
+
+The `rewrite!` method modifies the request URL and relevant pieces of the environment. When
+Refraction rule processing results in a `rewrite!`, the request is passed on down the Rack stack
+to the app or the next middleware component. `rewrite!` can take a single argument, either an
+options hash that uses the same options as the `set` method, or a string that sets all components
+of the URL.
+
+### `RequestContext#permanent!(options)`
+
+The `permanent!` method tells Refraction to return a response with a `301 Moved Permanently`
+status, and sets the URL for the Location header. Like `rewrite!` it can take either a string or
+hash argument to set the URL or some of its components.
+
+### `RequestContext#found!(options)`
+
+The `found!` method tells Refraction to return a response with a `302 Found` status, and sets the
+URL for the Location header. Like `#rewrite!` it can take either a string or hash argument to set
+the URL or some of its components.
+
+### URL components
+
+The request object provides the following components of the URL for matching requests: `scheme`,
+`host`, `port`, `path`, and `query`. It also provides a full environment hash as the `env`
+attribute. For example, `req.env['HTTP_USER_AGENT']` can be used to access the request's user
+agent property.
+
+## Contributors
+
+  * Josh Susser (maintainer)
+  * Sam Pierson
+  * Wai Lun Mang
+

data/Rakefile

@@ -0,0 +1,28 @@
+require 'rake'
+require 'spec'
+require 'spec/rake/spectask'
+
+desc 'Default: run unit tests.'
+task :default => :spec
+ 
+desc 'Test the refraction plugin.'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.libs << 'lib'
+  t.verbose = true
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "refraction"
+    gem.summary = %Q{Rack middleware replacement for mod_rewrite}
+    gem.description = %Q{Reflection is a Rails plugin and standalone Rack middleware library. Give up quirky config syntax and use plain old Ruby for your rewrite and redirection rules.}
+    gem.email = "gems@pivotallabs.com"
+    gem.homepage = "http://github.com/pivotal/refraction"
+    gem.authors = ["Pivotal Labs", "Josh Susser", "Sam Pierson", "Wai Lun Mang"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/geminstaller.yml

@@ -0,0 +1,12 @@
+--- 
+gems: 
+- name: rack
+  version: ~> 1.0.0
+- name: rack-test
+  version: ~> 0.5.0
+- name: rake
+  version: > 0.8.7
+- name: rspec
+  version: ~> 1.1.3
+- name: rspec
+  version: 1.1.12

data/install.rb

@@ -0,0 +1,21 @@
+# generate refraction_rules.rb
+
+  init_dir = File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "..", "config", "initializers"))
+  if test(?d, init_dir)
+    rules_file = File.join(init_dir, "refraction_rules.rb")
+    unless File.exists?(rules_file)
+      File.open(rules_file, "w") do |f|
+      f.puts(<<'EOF')
+Refraction.configure do |req|
+  # req.permanent! "http://example.com/"
+end
+EOF
+puts "Generated starter rules file in #{rules_file}"
+      end
+    end
+  end
+
+puts ""
+puts "Make sure to add Refraction to your middleware stack in your production environment:"
+puts '  config.middleware.insert_before(::Rack::Lock, ::Refraction, {})'
+puts ""

data/lib/refraction.rb

@@ -0,0 +1,141 @@
+require 'rack'
+
+class Refraction
+  class RequestContext
+    attr_reader :env
+    attr_reader :status, :message, :action
+
+    def initialize(env)
+      @action = nil
+      @env = env
+
+      hostname = env['SERVER_NAME']   # because the rack mock doesn't set the HTTP_HOST
+      hostname = env['HTTP_HOST'].split(':').first if env['HTTP_HOST']
+      env_path = env['PATH_INFO'] || env['REQUEST_PATH']
+
+      @uri = URI::Generic.build(
+        :scheme => env['rack.url_scheme'],
+        :host   => hostname,
+        :path   => env_path.empty? ? '/' : env_path
+      )
+      unless [URI::HTTP::DEFAULT_PORT, URI::HTTPS::DEFAULT_PORT].include?(env['SERVER_PORT'].to_i)
+        @uri.port = env['SERVER_PORT']
+      end
+      @uri.query = env['QUERY_STRING'] if env['QUERY_STRING'] && !env['QUERY_STRING'].empty?
+    end
+
+    def response
+      headers = {
+        'Location' => location,
+        'Content-Type' => 'text/plain',
+        'Content-Length' => message.length.to_s
+      }
+      [status, headers, message]
+    end
+
+    # URI part accessors
+
+    def scheme
+      @uri.scheme
+    end
+
+    def host
+      @uri.host
+    end
+
+    def port
+      @uri.port
+    end
+
+    def path
+      @uri.path
+    end
+
+    def query
+      @uri.query
+    end
+
+    def method
+      @env['REQUEST_METHOD']
+    end
+
+    # actions
+
+    def set(options)
+      if options.is_a?(String)
+        @uri = URI.parse(options)
+      else
+        @uri.port = nil
+        options.each do |k,v|
+          k = 'scheme' if k == :protocol
+          @uri.send("#{k}=", v)
+        end
+      end
+    end
+
+    def rewrite!(options)
+      @action = :rewrite
+      set(options)
+    end
+
+    def permanent!(options)
+      @action = :permanent
+      @status = 301
+      set(options)
+      @message = "moved to #{@uri}"
+    end
+
+    def found!(options)
+      @action = :found
+      @status = 302
+      set(options)
+      @message = "moved to #{@uri}"
+    end
+
+    def location
+      @uri.to_s
+    end
+
+  end   # RequestContext
+
+  def self.configure(&block)
+    @rules = block
+  end
+
+  def self.rules
+    @rules
+  end
+
+  def initialize(app)
+    @app = app
+  end
+
+  def rules
+    self.class.rules
+  end
+
+  def call(env)
+    if self.rules
+      context = RequestContext.new(env)
+
+      self.rules.call(context)
+
+      case context.action
+      when :permanent, :found
+        context.response
+      when :rewrite
+        env["rack.url_scheme"]                 = context.scheme
+        env["HTTP_HOST"] = env["SERVER_NAME"]  = context.host
+        env["HTTP_PORT"]                       = context.port if context.port
+        env["PATH_INFO"] = env["REQUEST_PATH"] = context.path
+        env["QUERY_STRING"]                    = context.query
+        env["REQUEST_URI"] = context.query ? "#{context.path}?#{context.query}" : context.path
+        @app.call(env)
+      else
+        @app.call(env)
+      end
+    else
+      @app.call(env)
+    end
+  end
+end

data/spec/refraction_spec.rb

@@ -0,0 +1,180 @@
+require File.join(File.dirname(__FILE__), "spec_helper")
+require File.join(File.dirname(__FILE__), "..", "lib", "refraction")
+
+describe Refraction do
+
+  describe "if no rules have been configured" do
+    before do
+      Refraction.configure
+    end
+
+    it "does nothing" do
+      env = Rack::MockRequest.env_for('http://bar.com/about', :method => 'get')
+      app = mock('app')
+      app.should_receive(:call) { |resp|
+        resp['rack.url_scheme'].should == 'http'
+        resp['SERVER_NAME'].should == 'bar.com'
+        resp['PATH_INFO'].should == '/about'
+        [200, {}, ["body"]]
+      }
+      response = Refraction.new(app).call(env)
+    end
+  end
+
+  describe "path" do
+    before do
+      Refraction.configure do |req|
+        if req.path == '/'
+          req.permanent! 'http://yes.com/'
+        elsif req.path == ''
+          req.permanent! 'http://no.com/'
+        end
+      end
+    end
+
+    it "should be set to / if empty" do
+      env = Rack::MockRequest.env_for('http://bar.com', :method => 'get')
+      env['PATH_INFO'] = '/'
+      app = mock('app')
+      response = Refraction.new(app).call(env)
+      response[0].should == 301
+      response[1]['Location'].should == "http://yes.com/"
+    end
+  end
+
+  describe "permanent redirection" do
+
+    describe "using string arguments" do
+      before do
+        Refraction.configure do |req|
+          req.permanent! "http://foo.com/bar?baz"
+        end
+      end
+
+      it "should redirect everything to foo.com" do
+        env = Rack::MockRequest.env_for('http://bar.com', :method => 'get')
+        app = mock('app')
+        response = Refraction.new(app).call(env)
+        response[0].should == 301
+        response[1]['Location'].should == "http://foo.com/bar?baz"
+      end
+    end
+
+    describe "using hash arguments" do
+      before do
+        Refraction.configure do |req|
+          req.permanent! :host => "foo.com", :path => "/bar", :query => "baz"
+        end
+      end
+
+      it "should redirect http://bar.com to http://foo.com" do
+        env = Rack::MockRequest.env_for('http://bar.com', :method => 'get')
+        app = mock('app')
+        response = Refraction.new(app).call(env)
+        response[0].should == 301
+        response[1]['Location'].should == "http://foo.com/bar?baz"
+      end
+
+      it "should redirect https://bar.com to https://foo.com" do
+        env = Rack::MockRequest.env_for('https://bar.com', :method => 'get')
+        app = mock('app')
+        response = Refraction.new(app).call(env)
+        response[0].should == 301
+        response[1]['Location'].should == "https://foo.com/bar?baz"
+      end
+
+      it "should clear the port unless set explicitly" do
+        env = Rack::MockRequest.env_for('http://bar.com:3000/', :method => 'get')
+        app = mock('app')
+        response = Refraction.new(app).call(env)
+        response[0].should == 301
+        response[1]['Location'].should == "http://foo.com/bar?baz"
+      end
+    end
+  end
+
+  describe "temporary redirect for found" do
+    before(:each) do
+      Refraction.configure do |req|
+        if req.path =~ %r{^/users/(josh|edward)/blog\.(atom|rss)$}
+          req.found! "http://feeds.pivotallabs.com/pivotallabs/#{$1}.#{$2}"
+        end
+      end
+    end
+
+    it "should temporarily redirect to feedburner.com" do
+      env = Rack::MockRequest.env_for('http://bar.com/users/josh/blog.atom', :method => 'get')
+      app = mock('app')
+      response = Refraction.new(app).call(env)
+      response[0].should == 302
+      response[1]['Location'].should == "http://feeds.pivotallabs.com/pivotallabs/josh.atom"
+    end
+
+    it "should not redirect when no match" do
+      env = Rack::MockRequest.env_for('http://bar.com/users/sam/blog.rss', :method => 'get')
+      app = mock('app')
+      app.should_receive(:call) { |resp|
+        resp['rack.url_scheme'].should == 'http'
+        resp['SERVER_NAME'].should == 'bar.com'
+        resp['PATH_INFO'].should == '/users/sam/blog.rss'
+        [200, {}, ["body"]]
+      }
+      response = Refraction.new(app).call(env)
+    end
+  end
+
+  describe "rewrite url" do
+    before(:each) do
+      Refraction.configure do |req|
+        if req.host =~ /(tweed|pockets)\.example\.com/
+          req.rewrite! :host => 'example.com', :path => "/#{$1}#{req.path == '/' ? '' : req.path}"
+        end
+      end
+    end
+
+    it "should rewrite subdomain to scope the path for matching subdomains" do
+      env = Rack::MockRequest.env_for('http://tweed.example.com', :method => 'get')
+      app = mock('app')
+      app.should_receive(:call) { |resp|
+        resp['rack.url_scheme'].should == 'http'
+        resp['SERVER_NAME'].should == 'example.com'
+        resp['PATH_INFO'].should == '/tweed'
+        [200, {}, ["body"]]
+      }
+      Refraction.new(app).call(env)
+    end
+
+    it "should not rewrite if the subdomain does not match" do
+      env = Rack::MockRequest.env_for('http://foo.example.com', :method => 'get')
+      app = mock('app')
+      app.should_receive(:call) { |resp|
+        resp['rack.url_scheme'].should == 'http'
+        resp['SERVER_NAME'].should == 'foo.example.com'
+        resp['PATH_INFO'].should == '/'
+        [200, {}, ["body"]]
+      }
+      Refraction.new(app).call(env)
+    end
+  end
+
+  describe "environment" do
+    before(:each) do
+      Refraction.configure do |req|
+        if req.env['HTTP_USER_AGENT'] =~ /FeedBurner/
+          req.permanent! "http://yes.com/"
+        else
+          req.permanent! "http://no.com/"
+        end
+      end
+    end
+
+    it "should expose environment settings" do
+      env = Rack::MockRequest.env_for('http://foo.com/', :method => 'get')
+      env['HTTP_USER_AGENT'] = 'FeedBurner'
+      app = mock('app')
+      response = Refraction.new(app).call(env)
+      response[0].should == 301
+      response[1]['Location'].should == "http://yes.com/"
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require "rubygems"
+require "spec"
+require "rack/test"

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: refraction
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Pivotal Labs
+- Josh Susser
+- Sam Pierson
+- Wai Lun Mang
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-29 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.9
+    version: 
+description: Reflection is a Rails plugin and standalone Rack middleware library. Give up quirky config syntax and use plain old Ruby for your rewrite and redirection rules.
+email: gems@pivotallabs.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- MIT-LICENSE
+- README.md
+- Rakefile
+- VERSION
+- geminstaller.yml
+- install.rb
+- lib/refraction.rb
+- spec/refraction_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/pivotal/refraction
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Rack middleware replacement for mod_rewrite
+test_files: 
+- spec/refraction_spec.rb
+- spec/spec_helper.rb