rack-api-key 0.0.1 → 0.0.2

data/README.md

@@ -1,12 +1,14 @@
 # RackApiKey
 
+[![Build Status](https://travis-ci.org/techwhizbang/rack-api-key.png)](https://travis-ci.org/techwhizbang/rack-api-key)
+
 RackApiKey is a middleware that relies on the client submitting requests
-with a header named "X-API-KEY" storing their private API key as the value. 
+with a header named "X-API-KEY" storing their private API key as the value.
 The middleware will then intercept the request, read the value from the named 
 header and call the given "proc" used for API key lookup. The API key lookup 
 should only return a value if there is an exact match for the value stored in 
 the named API key header. 
-If such a API key exists, the middleware will pass the request onward and also 
+If such an API key exists, the middleware will pass the request onward and also
 set a new value in the request representing the authenticated API key. Otherwise
 the middleware will return a HTTP status of 401, and a plain text message
 notifying the calling requestor that they are not authorized.
@@ -28,18 +30,97 @@ Or install it yourself as:
 ## Usage
 
 ```ruby
-		Rack::Builder.new do
-		  map '/' do 
-				use RackApiKey, :api_key_proc => Proc.new { |val| ApiKey.find(val) }
-		    run lambda { |env| [200, {"Content-Type" => "text/html"}, "Testing Middleware"] }
-		  end
-
-		  map "/all-options" do
-		  	use RackApiKey, 
-		  		:api_key_proc => Proc.new { |val| ApiKey.find(val) },
-		  		:rack_api_key => "account.api.key",
-		  		:header_key => "HTTP_X_CUSTOM_API_HEADER"
-		    run lambda { |env| [200, {"Content-Type" => "text/html"}, "Testing Middleware"] }
-		  end
-		end
+use RackApiKey, :api_key_proc => Proc.new { |val| ApiKey.find(val) },
+		  					:rack_api_key => "account.api.key",
+		  					:header_key => "HTTP_X_CUSTOM_API_HEADER"
+```
+
+### :header_key
+It's important to note that internally Rack actually mutates any given headers
+and prefixes them with HTTP and subsequently underscores them. For example if an
+API client passed "X-API-KEY" in the header, Rack would interpret that header
+as "HTTP_X_API_KEY". "HTTP_X_API_KEY" is the default header. If you want to use
+a different header you can specify it in the :header_key options Hash.
+
+### :api_key_proc
+This is required, there is no default behavior, and the middleware will not work
+properly unless you specify a Proc that takes one argument.
+The value the Proc receives will be the value set in the API header key.
+Use anything you like to determine if the header value
+is valid. If the value is invalid, the Proc should return nil, otherwise return
+a value that will ultimately be set in the Rack env.
+
+### :rack_api_key
+This is the key that will be set in the Rack env with the return value of the
+:api_key_proc.
+
+### :url_restriction
+This is an option that can restrict the rack-api-middleware to specific URLs.
+This works well when you have a mixture of API endpoints that require
+authentication and some that might not. Or a combination of API endpoints and
+publicly facing webpages. Perhaps you've scoped all of your API endpoints to
+"/api", and the rest of the URL mappings or routes are supposed to be wide open.
+
+
+### unauthorized_api_key method
+This is a method that can be overridden with however you'd like to respond
+when a request with an invalid or unauthorized API key is encountered. The default
+behavior responds with a 401 plain/text message. I find it especially useful to
+override this method and switch the response to JSON format.
+
+### valid_api_key? method
+This is another method that can be overridden if there are additional checks
+and validations beyond the ones already provided. For instance the API key
+may exist, but for some reason it was temporarily disabled. You could add a check
+for that here.
+
+### rack_api_key_request_setter method
+The default behavior of this method will take the return value of the API key
+proc and set it to the Rack env with the ke specified by :rack_api_key. You
+may override this method if you prefer setting something else in the Rack env 
+or perhaps nothing at all.
+
+## Examples
+
+```ruby
+# Overridden to use the default behavior plus check if the api key is enabled.
+def valid_api_key?(api_header_val, api_key_lookup_val)
+  super && api_key_lookup_val.enabled?
+end
+```
+
+```ruby
+# Overridden to respond in JSON format. 
+def unauthorized_api_key
+ 	body_text = {"error" => "blah blah blah"}.to_json
+  [401, {'Content-Type' => 'application/json; charset=utf-8',
+         'Content-Length' => body_text.size.to_s},
+  [body_text]]
+end
+```
+
+```ruby
+# Overridden to set the Account attached to the API key instead.
+def rack_api_key_request_setter(env, api_key_lookup_val)
+  env[@options[:rack_api_key]] = api_key_lookup_val.account
+end
+```
+
+```ruby
+Rack::Builder.new do
+  map '/' do 
+    use RackApiKey,
+      :api_key_proc => Proc.new { |val| ApiKey.find(val) },
+      :url_restriction => [/api/]
+    run lambda { |env| [200, {"Content-Type" => "text/html"}, "Testing Middleware"] }
+  end
+
+  map "/all-options" do
+  	use RackApiKey, 
+  		:api_key_proc => Proc.new { |val| ApiKey.find(val) },
+  		:rack_api_key => "account.api.key",
+  		:header_key => "HTTP_X_CUSTOM_API_HEADER"
+    run lambda { |env| [200, {"Content-Type" => "text/html"}, "Testing Middleware"] }
+  end
+end
 ```

data/lib/rack-api-key/version.rb

@@ -1,3 +1,3 @@
 class RackApiKey
-	VERSION = "0.0.1"
+	VERSION = "0.0.2"
 end

data/lib/rack-api-key.rb

@@ -23,7 +23,14 @@ class RackApiKey
 	#											on successful authentication. The default value is
 	# 										"rack_api_key".
 	# * +:header_key+ - A way to override the header's name used to store the API key.
-	# 									The default value is "HTTP_X_API_KEY".
+	# 									The value given here should reflect how Rack interprets the
+  #                   header. For example if the client passes "X-API-KEY" Rack
+  #                   transforms interprets it as "HTTP_X_API_KEY". The default
+  #                   value is "HTTP_X_API_KEY".
+  # * +:url_restriction+ - A way to restrict specific URLs that should pass through
+  #                        the rack-api-key middleware. In order to use pass an Array of Regex patterns.
+  #                        If left unspecified all requests will pass through the rack-api-key
+  #                        middleware.
 	#
 	# ==== Example
 	#		use RackApiKey, 
@@ -35,21 +42,26 @@ class RackApiKey
 		default_options = { 
 												:header_key => "HTTP_X_API_KEY", 
 											  :rack_api_key => "rack_api_key",
-											  :api_key_proc => Proc.new { raise NotImplementedError.new("Caller must implement a way to lookup an API key.") }
+											  :api_key_proc => Proc.new { raise NotImplementedError.new("Caller must implement a way to lookup an API key.") },
+                        :url_restriction => []
 											}
 		@options = default_options.merge(options)
 	end
 
 	def call(env)
-    api_header_val = env[@options[:header_key]]
-    api_key_lookup_val = @options[:api_key_proc].call(api_header_val)
-
-    if valid_api_key?(api_header_val, api_key_lookup_val)
-      rack_api_key_request_setter(env, api_key_lookup_val)
-      @app.call(env)
-    else
-      unauthorized_api_key
+    
+    if @options[:url_restriction].nil? || @options[:url_restriction].empty?      
+      process_request(env)
+    else 
+      request = Rack::Request.new(env)
+      url_matches = @options[:url_restriction].select { |url_regex| request.fullpath.match(url_regex) }
+      unless url_matches.empty?
+        process_request(env)
+      else
+        @app.call(env)
+      end
     end
+
   end
 
   ##
@@ -80,4 +92,18 @@ class RackApiKey
     !api_key_lookup_val.nil? && api_key_lookup_val != ""
   end
 
+  private
+
+  def process_request(env)
+    api_header_val = env[@options[:header_key]]
+    api_key_lookup_val = @options[:api_key_proc].call(api_header_val)
+
+    if valid_api_key?(api_header_val, api_key_lookup_val)
+      rack_api_key_request_setter(env, api_key_lookup_val)
+      @app.call(env)
+    else
+      unauthorized_api_key
+    end
+  end
+
 end

data/spec/rack_api_key_spec.rb

@@ -25,6 +25,7 @@ describe RackApiKey do
 
 	# simple test app for the middleware test
 	def app
+
 		Rack::Builder.new do
       map '/' do 
 				use RackApiKey, :api_key_proc => Proc.new { |val| ApiKey.find(val) }
@@ -43,6 +44,13 @@ describe RackApiKey do
 	    		:header_key => "HTTP_X_CUSTOM_API_HEADER"
 	      run lambda { |env| [200, {"Content-Type" => "text/html"}, "Testing Middleware"] }
 	    end
+
+	    map "/url-restricted" do
+	    	use RackApiKey,
+	    		:api_key_proc => Proc.new { |val| ApiKey.find(val) },
+					:url_restriction => [/url-restricted\/foo/]
+				run lambda { |env| [200, {"Content-Type" => "text/html"}, "Testing Middleware"] }
+	    end
 	    
     end  	
 	end
@@ -114,4 +122,43 @@ describe RackApiKey do
 	  end
 
 	end
+
+	context "when URL restriction is used" do
+
+		context "and the requesting URL matches the restricted list" do
+
+			it 'attempts to find the ApiKey with the header value' do
+				ApiKey.should_receive(:find).with("SECRET API KEY")
+				get "/url-restricted/foo", {}, "HTTP_X_API_KEY" => "SECRET API KEY"
+			end
+
+			it 'responds with a 200 upon successful authorization' do
+				ApiKey.stub(:find).and_return(ApiKey.new("SECRET API KEY"))
+				get "/url-restricted/foo", {}, "HTTP_X_API_KEY" => "SECRET API KEY"
+				last_response.ok?.should be_true
+			end
+
+			it 'responds with a 401 when the header is not set' do
+				header("HTTP_X_API_KEY", nil)
+				get "/url-restricted/foo"
+				last_response.status.should == 401
+			end
+
+		end
+
+		context "and the requesting URL is not in the restricted list" do
+
+			it 'does not attempt to find the ApiKey with the header value' do
+				ApiKey.should_not_receive(:find).with("SECRET API KEY")
+				get "/url-restricted/bar"
+			end
+
+			it 'responds with a 200 without the header set' do
+				get "/url-restricted/bar"
+				last_response.ok?.should be_true
+			end
+
+		end
+
+	end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rack-api-key
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-04 00:00:00.000000000 Z
+date: 2013-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -107,7 +107,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3957032321281409751
+      hash: 2860984967925191594
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -116,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3957032321281409751
+      hash: 2860984967925191594
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25