restfulness 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7c75c4e41bde16b35b2e5ea93df0958073b8d114
-  data.tar.gz: 4d72d5c989d8d4cc1fdabdeb92475a07ee0e354a
+  metadata.gz: ed8387e688a8bb336c27f341003bdf225fb439c0
+  data.tar.gz: 02cef9941b4153e68215fb1497885a4472d28071
 SHA512:
-  metadata.gz: f78f392d57d5d9c64fc446def406f99fe12fdad295ad415bf15a9f3d7c789def2b304face6fc1e1a60f7db8dc256002aa6bce2a936e46f69b07abdfef1046183
-  data.tar.gz: 198200ae4575a6f756a75b142c4d07683cd1f4105cf8cd317603c018491c3d5644c5add334fbdcbeb4251b529bf6b4d648c1eb44e4256a04e1904b05c9365516
+  metadata.gz: 51d5acf131c42af07a033ef3e579bb2246fcbd4461b3b5accb9a98de7359d9267dbf0ae0e41db7aea0769520b8d7cd510f9f11e053902fe66fbf41f98b8c7411
+  data.tar.gz: 7c9890e63ccc7a98fb40e9f98ce42fe69168e94d7099a3e892df0e5a7862553ed6763ae3eff012ddd89fd64025fc2dacc05ae5c8f537e016e11a184ae52d617b

data/.travis.yml

@@ -3,4 +3,7 @@ rvm:
   - 2.0.0
   - 1.9.3
   - jruby-19mode # JRuby in 1.9 mode
-  - rbx
+  - rbx # Probably a bit optimistic
+matrix:
+  allow_failures:
+    - rvm: rbx

data/README.md

@@ -309,6 +309,37 @@ The `Resource#set_locale` method is called before any of the other callbacks are
 Most users will probably just want to override the `Resource#locale` method and provide the appropriate locale for the request. If you are using a User object or similar, double check your authentication process as the default `authorized?` method will be called *after* the locale is prepared.
 
 
+#### Authentication in Resources
+
+Restfulness now provides very basic support for the [HTTP Basic Authentication](http://en.wikipedia.org/wiki/Basic_access_authentication). To use it, simply call the `authenticate_with_http_basic` method in your resource definition.
+
+Here's an example with the authentication details in the code, you'd obviously want to use something a bit more advanced than this in production:
+
+```ruby
+def authorized?
+  authenticate_with_http_basic do |username, password|
+    return (username == 'user' && password == 'pass')
+  end
+  false
+end
+```
+
+The `request` object provided in the resource, described below, provides access to the HTTP `Authorization` header via the `Reqest#authorization` method. If you want to use an alternative authentication method you can use this to extract the details you might need. For example:
+
+```ruby
+def authorized?
+  auth = request.authorization
+  if auth && auth.schema == 'Token'
+    if our_secret_token == auth.params
+      return true
+    end
+  end
+  false
+end
+```
+
+We don't yet provide support for Digest authentication, but your contributions would be more than welcome. Checkout the [HttpAuthentication/basic.rb](https://github.com/samlown/restfulness/blob/master/lib/restfulness/http_authentication/basic.rb) source for an example.
+
 ### Requests
 
 All resource instances have access to a `Request` object via the `#request` method, much like you'd find in a Rails project. It provides access to the details including in the HTTP request: headers, the request URL, path entries, the query, body and/or parameters.
@@ -618,6 +649,10 @@ Restfulness is still a work in progress but at Cabify we are using it in product
 
 ## History
 
+### 0.3.1 - September 19, 2014
+
+ * Added support for HTTP Basic Authentication, no breaking changes. (@samlown)
+
 ### 0.3.0 - May 13, 2014
 
  * Possible breaking change: `put` requests no longer check for existing resource via `exists?` callback. (@samlown)

data/lib/restfulness.rb

@@ -1,6 +1,7 @@
 
 require 'uri'
 require 'multi_json'
+require 'active_support'
 require 'active_support/core_ext'
 require 'active_support/dependencies'
 require 'active_support/logger'
@@ -11,7 +12,13 @@ require 'rack/builder'
 
 require 'http_accept_language/parser'
 
+require "restfulness/http_authentication/basic"
+
 require "restfulness/resources/events"
+require "restfulness/resources/authentication"
+
+require "restfulness/requests/authorization"
+require "restfulness/requests/authorization_header"
 
 require "restfulness/application"
 require "restfulness/dispatcher"

data/lib/restfulness/http_authentication/basic.rb

@@ -0,0 +1,37 @@
+module Restfulness
+  module HttpAuthentication
+
+    class Basic
+
+      # The Requests::AuthorizationHeader object generated in the request
+      attr_accessor :header
+
+      def initialize(header)
+        self.header = header
+      end
+
+      # Determine if the header we were provided is valid.
+      def valid?
+        header.schema == 'Basic' && credentials.length == 2
+      end
+
+      # Attempt to decode the credentials provided in the header.
+      def credentials
+        @credentials ||= begin
+          txt = ::Base64.decode64(header.params || '')
+          txt.split(/:/, 2)
+        end
+      end
+
+      def username
+        credentials[0]
+      end
+
+      def password
+        credentials[1]
+      end
+
+    end
+
+  end
+end

data/lib/restfulness/request.rb

@@ -5,6 +5,7 @@ module Restfulness
   #
   # Currently wraps around the information provided in a Rack Request object.
   class Request
+    include Requests::Authorization
 
     # Who does this request belong to?
     attr_reader :app

data/lib/restfulness/requests/authorization.rb

@@ -0,0 +1,22 @@
+module Restfulness
+  module Requests
+
+    module Authorization
+
+      def authorization
+        @authorization ||= begin
+          payload = authorization_header_payload
+          AuthorizationHeader.new(payload) unless payload.nil?
+        end
+      end
+
+      private
+
+      def authorization_header_payload
+        headers[:authorization]
+      end
+
+    end
+
+  end
+end

data/lib/restfulness/requests/authorization_header.rb

@@ -0,0 +1,22 @@
+module Restfulness
+  module Requests
+
+    # Handle the HTTP Authorization header payload to automatically extract the scheme
+    # and parameters.
+    class AuthorizationHeader
+
+      attr_accessor :schema, :params
+
+      def initialize(payload)
+        (self.schema, self.params) = payload.strip.split(' ', 2)
+      end
+
+      def schema=(txt)
+        # Make sure we're in Titlecase
+        @schema = txt.slice(0,1).capitalize + txt.slice(1..-1).downcase
+      end
+
+    end
+
+  end
+end

data/lib/restfulness/resource.rb

@@ -2,6 +2,7 @@ module Restfulness
 
   class Resource
     include Resources::Events
+    include Resources::Authentication
 
     attr_reader :request, :response
 

data/lib/restfulness/resources/authentication.rb

@@ -0,0 +1,21 @@
+module Restfulness
+  module Resources
+
+    # Module to support authentication in Restfulness resources.
+    module Authentication
+
+      # Parse the request headers for HTTP Basic Authentication details and
+      # run the provided block.
+      # If the request does not include and basic headers or the details are invalid,
+      # the block will not be called.
+      def authenticate_with_http_basic
+        header = request.authorization
+        auth = HttpAuthentication::Basic.new(header) if header
+        if auth && auth.valid?
+          yield auth.username, auth.password
+        end
+      end
+
+    end
+  end
+end

data/lib/restfulness/version.rb

@@ -1,3 +1,3 @@
 module Restfulness
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/restfulness.gemspec

@@ -25,5 +25,5 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rspec", "~> 2.14.1"
 end

data/spec/unit/http_authentication/basic_spec.rb

@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+describe Restfulness::HttpAuthentication::Basic do
+
+  let :klass do
+    Restfulness::HttpAuthentication::Basic
+  end
+  let :header_klass do
+    Restfulness::Requests::AuthorizationHeader
+  end
+  let :header do
+    Restfulness::Requests::AuthorizationHeader.new("Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
+  end
+
+  describe "#initialize" do
+    it "should set the header" do
+      obj = klass.new(header)
+      obj.header.should eql(header)
+    end
+  end
+
+  describe "#valid?" do
+    it "should detect valid schema and credentials" do
+      obj = klass.new(header)
+      obj.valid?.should be_true
+    end
+
+    it "should reject different schema" do
+      obj = klass.new(header_klass.new("Fooo Bar"))
+      obj.valid?.should be_false
+    end
+
+    it "should reject if the basic request credentials are of invalid length" do
+      creds = ::Base64.strict_encode64("username")
+      obj = klass.new(header_klass.new("Fooo #{creds}"))
+      obj.valid?.should be_false
+    end
+  end
+
+  describe "#credentials #username and #password" do
+
+    it "should decode and prepare the params" do
+      obj = klass.new(header)
+      obj.credentials.length.should eql(2)
+      obj.username.should eql('Aladdin')
+      obj.password.should eql('open sesame')
+    end
+
+  end
+
+end

data/spec/unit/requests/authorization_header_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+
+describe Restfulness::Requests::AuthorizationHeader do
+
+  describe "#initialize" do
+
+    let :klass do
+      Restfulness::Requests::AuthorizationHeader
+    end
+
+    it "should accept standard header" do
+      obj = klass.new("Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
+      obj.schema.should eql("Basic")
+      obj.params.should eql("QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
+    end
+
+    it "should accept non-standard schema" do
+      obj = klass.new("bAsic QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
+      obj.schema.should eql("Basic")
+      obj.params.should eql("QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
+    end
+
+    it "should ignore any whitespace" do
+      obj = klass.new(" Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== ")
+      obj.schema.should eql("Basic")
+      obj.params.should eql("QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
+    end
+
+    it "should append additional stuff" do
+      obj = klass.new("Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== foooo")
+      obj.schema.should eql("Basic")
+      obj.params.should eql("QWxhZGRpbjpvcGVuIHNlc2FtZQ== foooo")
+    end
+
+  end
+
+end

data/spec/unit/requests/authorization_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+describe Restfulness::Requests::Authorization do
+
+  let :app do
+    Class.new(Restfulness::Application) do
+      routes do
+        # empty
+      end
+    end
+  end
+  let :request do
+    Restfulness::Request.new(app)
+  end
+
+  describe "#authorization" do
+
+    it "should be nil if no authorization header resent" do
+      auth = request.authorization
+      auth.should be_nil
+    end
+ 
+    it "should build new authorization header when present" do
+      request.headers[:authorization] = "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
+      auth = request.authorization
+      auth.should be_a(Restfulness::Requests::AuthorizationHeader)
+      auth.schema.should eql("Basic")
+    end
+
+ end
+
+end

data/spec/unit/resources/authentication_spec.rb

@@ -0,0 +1,50 @@
+
+require 'spec_helper'
+
+describe Restfulness::Resources::Authentication do
+
+  let :app do
+    Class.new(Restfulness::Application) do
+      routes do
+        # empty
+      end
+    end
+  end
+  let :request do
+    Restfulness::Request.new(app).tap do |req|
+      req.headers[:authorization] = "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
+    end
+  end
+  let :response do
+    Restfulness::Response.new(request)
+  end
+
+  describe "#authenticate_with_http_basic" do
+
+    class AuthResource < Restfulness::Resource
+    end
+
+    it "should run block and provide user and password" do
+      obj = AuthResource.new(request, response)
+      expect { |b| obj.authenticate_with_http_basic(&b) }.to yield_control
+      obj.authenticate_with_http_basic do |username, password|
+        username.should eql('Aladdin')
+        password.should eql('open sesame')
+      end
+    end
+
+    it "should not run block if no authorization header" do
+      request.headers[:authorization] = nil
+      obj = AuthResource.new(request, response)
+      expect { |b| obj.authenticate_with_http_basic(&b) }.not_to yield_control
+    end
+
+    it "should not run block if non-basic authorization header" do
+      request.headers[:authorization] = "Digest QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
+      obj = AuthResource.new(request, response)
+      expect { |b| obj.authenticate_with_http_basic(&b) }.not_to yield_control
+    end
+
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: restfulness
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Sam Lown
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-13 00:00:00.000000000 Z
+date: 2014-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -98,16 +98,16 @@ dependencies:
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.14.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.14.1
 description: Simple REST server that focuses on resources instead of routes.
 email:
 - me@samlown.com
@@ -130,9 +130,13 @@ files:
 - lib/restfulness/dispatcher.rb
 - lib/restfulness/dispatchers/rack.rb
 - lib/restfulness/exceptions.rb
+- lib/restfulness/http_authentication/basic.rb
 - lib/restfulness/path.rb
 - lib/restfulness/request.rb
+- lib/restfulness/requests/authorization.rb
+- lib/restfulness/requests/authorization_header.rb
 - lib/restfulness/resource.rb
+- lib/restfulness/resources/authentication.rb
 - lib/restfulness/resources/events.rb
 - lib/restfulness/response.rb
 - lib/restfulness/route.rb
@@ -146,9 +150,13 @@ files:
 - spec/unit/dispatcher_spec.rb
 - spec/unit/dispatchers/rack_spec.rb
 - spec/unit/exceptions_spec.rb
+- spec/unit/http_authentication/basic_spec.rb
 - spec/unit/path_spec.rb
 - spec/unit/request_spec.rb
+- spec/unit/requests/authorization_header_spec.rb
+- spec/unit/requests/authorization_spec.rb
 - spec/unit/resource_spec.rb
+- spec/unit/resources/authentication_spec.rb
 - spec/unit/resources/events_spec.rb
 - spec/unit/response_spec.rb
 - spec/unit/route_spec.rb
@@ -184,9 +192,13 @@ test_files:
 - spec/unit/dispatcher_spec.rb
 - spec/unit/dispatchers/rack_spec.rb
 - spec/unit/exceptions_spec.rb
+- spec/unit/http_authentication/basic_spec.rb
 - spec/unit/path_spec.rb
 - spec/unit/request_spec.rb
+- spec/unit/requests/authorization_header_spec.rb
+- spec/unit/requests/authorization_spec.rb
 - spec/unit/resource_spec.rb
+- spec/unit/resources/authentication_spec.rb
 - spec/unit/resources/events_spec.rb
 - spec/unit/response_spec.rb
 - spec/unit/route_spec.rb