refraction 0.1.4 → 0.2.0

data/README.md

@@ -64,12 +64,32 @@ example, in nginx, that is done with a `server_name _;` directive.
 
 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.
+is passed a request object that contains information about the request URL and environment.  The
+request is an instance of Refraction::Request, which is a subclass of Rack::Request.  That means it has
+all the standard Rack::Request methods for examining the request environment, headers, url components,
+and so on, plus a few more for convenience.
+
+### 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.  And other Rack::Request methods such as `ip` and `xhr?` are also available.
+
+## Taking Action
+
+The request object includes a small API for effecting rewrites and redirects.  You should only use
+one action method per request.  That isn't enforced, but the effects will be unpredictable.
 
 > 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.
+> break).  That's just how blocks work in Ruby - you can only return from
+> them once, not on every request.
+
+There are two ways to specify the new location or URL: as a string or as an options hash of components.
+If you use a string then that becomes the literal value for the redirect location or the rewritten
+URL.  If you use a hash, you can modify one or several of the URL components and leave the others
+unchanged.
 
 ### `RequestContext#set(options)`
 
@@ -84,7 +104,15 @@ header.
 
 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`.
+action methods will merge their component values into values from `set`.
+
+Note: If you change the URL scheme or host, any non-standard port will be reset to the default port
+for the scheme unless specified.  In the following example the first line will reset the port to the
+default (that is, 80), but the second line will retain any non-standard port.
+
+    if req.path =~ %r{^/images}  then  req.found! :host => "assets.#{req.host}"  end
+    if req.path =~ %r{^/images}  then  req.found! :host => "assets.#{req.host}", :port => req.port  end
+
 
 ### `RequestContext#rewrite!(options)`
 
@@ -117,17 +145,11 @@ The args are largely the same as the contents of a standard Rack response array
 that you don't need to wrap the content in an array, and the Content-Length header is generated so it
 should not be supplied.
 
-### 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
   * Brian Morearty
+  * Dennis Collinson
 

data/VERSION

@@ -1 +1 @@
-0.1.4
+0.2.0

data/lib/refraction.rb

@@ -5,6 +5,8 @@ class Refraction
 
   class Request < Rack::Request
     attr_reader :action, :status, :message
+
+    # backward compatibility: support URI::HTTP component names
     def method; request_method; end
     def query;  query_string;   end
 
@@ -61,11 +63,13 @@ class Refraction
       @re_location || url
     end
 
+    # use original request's values when not set explicitly
     def scheme;       @re_scheme || super; end
     def host;         @re_host   || super; end
     def path;         @re_path   || super; end
     def query_string; @re_query  || super; end
 
+    # changing the scheme or host means use default port instead of port in original request
     def port
       @re_port || ((@re_scheme || @re_host) && default_port) || super
     end

data/refraction.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{refraction}
-  s.version = "0.1.4"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Pivotal Labs", "Josh Susser", "Sam Pierson", "Wai Lun Mang"]
-  s.date = %q{2010-07-01}
+  s.date = %q{2010-02-01}
   s.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.}
   s.email = %q{gems@pivotallabs.com}
   s.extra_rdoc_files = [
@@ -21,7 +21,6 @@ Gem::Specification.new do |s|
      "Rakefile",
      "VERSION",
      "geminstaller.yml",
-     "init.rb",
      "install.rb",
      "lib/refraction.rb",
      "refraction.gemspec",
@@ -31,7 +30,7 @@ Gem::Specification.new do |s|
   s.homepage = %q{http://github.com/pivotal/refraction}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.6}
+  s.rubygems_version = %q{1.3.5}
   s.summary = %q{Rack middleware replacement for mod_rewrite}
   s.test_files = [
     "spec/refraction_spec.rb",

metadata

@@ -1,12 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: refraction
 version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 1
-  - 4
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors: 
 - Pivotal Labs
@@ -17,23 +12,19 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-01 00:00:00 -07:00
+date: 2010-02-01 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rspec
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        segments: 
-        - 1
-        - 2
-        - 9
         version: 1.2.9
-  type: :development
-  version_requirements: *id001
+    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: []
@@ -48,7 +39,6 @@ files:
 - Rakefile
 - VERSION
 - geminstaller.yml
-- init.rb
 - install.rb
 - lib/refraction.rb
 - refraction.gemspec
@@ -67,20 +57,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      segments: 
-      - 0
       version: "0"
+  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      segments: 
-      - 0
       version: "0"
+  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
 summary: Rack middleware replacement for mod_rewrite

data/init.rb

@@ -1 +0,0 @@
-require "refraction"