sinatra_resource 0.1.0

data/examples/datacatalog/test/resources/users/users_get_one_test.rb

@@ -0,0 +1,75 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../helpers/resource_test_helper')
+
+class UsersGetOneResourceTest < ResourceTestCase
+
+  def app; DataCatalog::Users end
+  
+  before do
+    @user = create_user
+  end
+
+  after do
+    @user.destroy
+  end
+
+  context "get /:id" do
+    context "anonymous" do
+      before do
+        get "/#{@user.id}"
+      end
+    
+      use "return 401 because the API key is missing"
+    end
+
+    context "incorrect API key" do
+      before do
+        get "/#{@user.id}", :api_key => BAD_API_KEY
+      end
+  
+      use "return 401 because the API key is invalid"
+    end
+  end
+
+  %w(basic curator admin).each do |role|
+    context "#{role} : get /:fake_id" do
+      before do
+        get "/#{FAKE_ID}", :api_key => api_key_for(role)
+      end
+    
+      use "return 404 Not Found"
+      use "return an empty response body"
+    end
+  end
+
+  %w(basic curator).each do |role|
+    context "#{role} : get /:id" do
+      before do
+        get "/#{@user.id}", :api_key => api_key_for(role)
+      end
+
+      use "return 200 Ok"
+      doc_properties %w(name id created_at updated_at)
+    end
+  end
+  
+  context "owner : get /:id" do
+    before do
+      get "/#{@user.id}", :api_key => @user._api_key
+    end
+
+    use "return 200 Ok"
+    doc_properties %w(name email role _api_key id created_at updated_at)
+  end
+
+  %w(admin).each do |role|
+    context "#{role} : get /:id" do
+      before do
+        get "/#{@user.id}", :api_key => api_key_for(role)
+      end
+
+      use "return 200 Ok"
+      doc_properties %w(name email role _api_key id created_at updated_at)
+    end
+  end
+
+end

data/examples/datacatalog/test/resources/users/users_post_test.rb

@@ -0,0 +1,142 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../helpers/resource_test_helper')
+
+class UsersPostResourceTest < ResourceTestCase
+
+  include DataCatalog
+
+  def app; Users end
+  
+  before do
+    @user_count = User.all.length
+    @valid_params = {
+      :name => "New User",
+      :role => "basic"
+    }
+    @extra_admin_params = {
+      :role     => "basic",
+      :_api_key => "222200004444"
+    }
+  end
+
+  shared "no new users" do
+    test "should not change number of user documents in database" do
+      assert_equal @user_count, User.all.length
+    end
+  end
+
+  shared "one new user" do
+    test "should add one user document to database" do
+      assert_equal @user_count + 1, User.all.length
+    end
+  end
+
+  shared "correct Location header" do
+    test "should set Location header correctly" do
+      base_uri = Config.environment_config["base_uri"]
+      path = %(/users/#{parsed_response_body["id"]})
+      expected = URI.join(base_uri, path).to_s
+      assert_equal expected, last_response.headers['Location']
+    end
+  end
+  
+  context "post /" do
+    context "anonymous" do
+      before do
+        post "/", @valid_params
+      end
+    
+      use "return 401 because the API key is missing"
+      use "no new users"
+    end
+
+    context "incorrect API key" do
+      before do
+        post "/", @valid_params.merge(:api_key => BAD_API_KEY)
+      end
+  
+      use "return 401 because the API key is invalid"
+      use "no new users"
+    end
+  end
+
+  %w(basic curator).each do |role|
+    [:name, :role].each do |missing|
+      context "#{role} : post / but missing #{missing}" do
+        before do
+          post "/", valid_params_for(role).delete_if { |k, v| k == missing }
+        end
+  
+        use "return 401 Unauthorized"
+        use "no new users"
+      end
+    end
+  
+    [:role, :_api_key, :id, :created_at, :updated_at].each do |invalid|
+      context "#{role} : post / but with #{invalid}" do
+        before do
+          post "/", valid_params_for(role).merge(invalid => 9)
+        end
+  
+        use "return 401 Unauthorized"
+        use "no new users"
+      end
+    end
+  
+    context "#{role} : post / with valid params" do
+      before do
+        post "/", valid_params_for(role)
+      end
+      
+      use "return 401 Unauthorized"
+      use "no new users"
+    end
+  end
+
+  %w(admin).each do |role|
+    [:name, :role].each do |missing|
+      context "#{role} : post / but missing #{missing}" do
+        before do
+          post "/", valid_params_for(role).
+            merge(@extra_admin_params).delete_if { |k, v| k == missing }
+        end
+        
+        use "return 400 Bad Request"
+        use "no new users"
+        missing_param missing
+      end
+    end
+  
+    [:id, :created_at, :updated_at].each do |invalid|
+      context "#{role} : post / but with #{invalid}" do
+        before do
+          post "/", valid_params_for(role).
+            merge(@extra_admin_params).merge(invalid => 9)
+        end
+  
+        use "return 400 Bad Request"
+        use "no new users"
+        invalid_param invalid
+      end
+    end
+  
+    context "#{role} : post / with valid params" do
+      before do
+        post "/", valid_params_for(role).merge(@extra_admin_params)
+      end
+  
+      use "return 201 Created"
+      use "correct Location header"
+      use "one new user"
+      doc_properties %w(name email role _api_key id created_at updated_at)
+
+      test "should set all fields in database" do
+        user = User.find_by_id(parsed_response_body["id"])
+        raise "Cannot find user" unless user
+        @valid_params.merge(@extra_admin_params).each_pair do |key, value|
+          assert_equal value, user[key]
+        end
+      end
+    end
+  end
+
+end

data/examples/datacatalog/test/resources/users/users_put_test.rb

@@ -0,0 +1,171 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../helpers/resource_test_helper')
+
+class UsersPutResourceTest < ResourceTestCase
+
+  include DataCatalog
+
+  def app; Users end
+
+  before do
+    @user = create_user
+    @user_copy = @user.dup
+    @valid_params = {
+      :name   => "Changed User",
+      :role   => "curator"
+    }
+    @extra_admin_params = {
+      :_api_key => "222200004444"
+    }
+  end
+
+  after do
+    @user.destroy
+  end
+  
+  shared "user unchanged" do
+    test "should not change user in database" do
+      assert_equal @user_copy, User.find_by_id(@user.id)
+    end
+  end
+  
+  context "put /:id" do
+    context "anonymous" do
+      before do
+        put "/#{@user.id}", @valid_params
+      end
+    
+      use "return 401 because the API key is missing"
+      use "user unchanged"
+    end
+  
+    context "incorrect API key" do
+      before do
+        put "/#{@user.id}", @valid_params.merge(:api_key => BAD_API_KEY)
+      end
+  
+      use "return 401 because the API key is invalid"
+      use "user unchanged"
+    end
+  end
+  
+  %w(basic curator).each do |role|
+    [:created_at, :updated_at].each do |invalid|
+      context "#{role} : put / but with #{invalid}" do
+        before do
+          put "/#{@user.id}", valid_params_for(role).
+            merge(@extra_admin_params).merge(invalid => 9)
+        end
+  
+        use "return 401 Unauthorized"
+        use "user unchanged"
+      end
+    end
+
+    [:name, :role].each do |erase|
+      context "#{role} : put / but blanking out #{erase}" do
+        before do
+          put "/#{@user.id}", valid_params_for(role).
+            merge(@extra_admin_params).merge(erase => "")
+        end
+      
+        use "return 401 Unauthorized"
+        use "user unchanged"
+      end
+    end
+
+    [:name, :role].each do |missing|
+      context "#{role} : put /:id without #{missing}" do
+        before do
+          put "/#{@user.id}", valid_params_for(role).
+            merge(@extra_admin_params).delete_if { |k, v| k == missing }
+        end
+      
+        use "return 401 Unauthorized"
+        use "user unchanged"
+      end
+    end
+
+    context "#{role} : put /:id with valid params" do
+      before do
+        put "/#{@user.id}", valid_params_for(role).merge(@extra_admin_params)
+      end
+
+      use "return 401 Unauthorized"
+      use "user unchanged"
+    end
+  end
+
+  %w(admin).each do |role|
+    [:created_at, :updated_at].each do |invalid|
+      context "#{role} : put / but with #{invalid}" do
+        before do
+          put "/#{@user.id}", valid_params_for(role).
+            merge(@extra_admin_params).merge(invalid => 9)
+        end
+  
+        use "return 400 Bad Request"
+        use "user unchanged"
+        invalid_param invalid
+      end
+    end
+
+    [:name, :role].each do |erase|
+      context "#{role} : put / but blanking out #{erase}" do
+        before do
+          put "/#{@user.id}", valid_params_for(role).
+            merge(@extra_admin_params).merge(erase => "")
+        end
+      
+        use "return 400 Bad Request"
+        use "user unchanged"
+        missing_param erase
+      end
+    end
+
+    context "#{role} : put /:id with no parameters" do
+      before do
+        put "/#{@user.id}", :api_key => api_key_for(role)
+      end
+
+      use "return 400 because no parameters were given"
+      use "user unchanged"
+    end
+
+    [:name, :role].each do |missing|
+      context "#{role} : put /:id without #{missing}" do
+        before do
+          put "/#{@user.id}", valid_params_for(role).
+            merge(@extra_admin_params).delete_if { |k, v| k == missing }
+        end
+      
+        use "return 200 Ok"
+        doc_properties %w(name email role _api_key id created_at updated_at)
+  
+        test "should change correct fields in database" do
+          user = User.find_by_id(@user.id)
+          @valid_params.merge(@extra_admin_params).each_pair do |key, value|
+            assert_equal(value, user[key]) if key != missing
+          end
+          assert_equal @user_copy[missing], user[missing]
+        end
+      end
+    end
+
+    context "#{role} : put /:id with valid params" do
+      before do
+        put "/#{@user.id}", valid_params_for(role).merge(@extra_admin_params)
+      end
+      
+      use "return 200 Ok"
+      doc_properties %w(name email role _api_key id created_at updated_at)
+  
+      test "should change all fields in database" do
+        user = User.find_by_id(@user.id)
+        @valid_params.merge(@extra_admin_params).each_pair do |key, value|
+          assert_equal value, user[key]
+        end
+      end
+    end
+  end
+
+end

data/lib/builder/helpers.rb

@@ -0,0 +1,319 @@
+module SinatraResource
+  
+  class Builder
+
+    module Helpers
+      
+      # Build a resource, based on +document+, appropriate for +role+.
+      #
+      # @param [Symbol] role
+      #   a role (such as :anonymous, :basic, or :admin)
+      #
+      # @param [MongoMapper::Document] document
+      #
+      # @return [Hash<String => Object>]
+      def build_resource(role, document)
+        resource = {}
+        config[:properties].each_pair do |property, hash|
+          if authorized?(:read, role, property)
+            resource[property.to_s] = value(property, document, hash)
+          end
+        end
+        resource
+      end
+
+      # Builds a list of resources, based on +documents+, using the
+      # appropriate role for each document. (Delegates to +lookup_role+.)
+      #
+      # @param [Array<MongoMapper::Document>] documents
+      #
+      # @param [String] api_key
+      #
+      # @return [Array<Hash<String => Object>>]
+      def build_resources(documents)
+        documents.map do |document|
+          build_resource(lookup_role(document), document)
+        end
+      end
+
+      # Halt unless the current params are ok for +action+ and +role+.
+      #
+      # @param [Symbol] action
+      #   :read, :create, :update, or :delete
+      #
+      # @param [Symbol] role
+      #   a role (such as :anonymous, :basic, or :admin)
+      #
+      # @return [undefined]
+      def check_params(action, role)
+        params_check_action(action)
+        params_check_action_and_role(action, role)
+      end
+
+      # Halt unless the current role has permission to carry out +action+
+      #
+      # @param [Symbol] action
+      #   :read, :create, :update, or :delete
+      #
+      # @param [Symbol] role
+      #   a role (such as :anonymous, :basic, or :admin)
+      #
+      # @return [undefined]
+      def check_permission(action, role)
+        before_authorization(action, role)
+        unless authorized?(action, role)
+          error 401, convert(body_for(:unauthorized))
+        end
+      end
+      
+      # Convert +object+ to desired format.
+      #
+      # For example, an application might want to convert +object+ to JSON or
+      # XML.
+      #
+      # Applications must override this method.
+      # 
+      # @param [Object] object
+      #
+      # @return [String]
+      def convert
+        raise NotImplementedError
+      end
+
+      # Display +object+ as appropriate for +action+.
+      #
+      # @param [Object] object
+      #
+      # @return [String]
+      def display(action, object)
+        case action
+        when :read
+        when :create
+          response.status = 201
+          path = config[:path] + %(/#{object["id"]})
+          response.headers['Location'] = full_uri(path)
+        when :update
+        when :delete
+          response.status = 204
+        end
+        convert(object)
+      end
+
+      # Convert a path to a full URI.
+      #
+      # Applications must override this method.
+      # 
+      # @param [String] path
+      #
+      # @return [String]
+      def full_uri(path)
+        raise NotImplementedError
+      end
+
+      # Get role, using +id+ if specified. Delegates to +lookup_role+.
+      #
+      # When +id+ is present, it can help determine 'relative' roles such
+      # as 'ownership' of the current user of a particular document.
+      #
+      # @param [String, nil] id
+      #
+      # @return [Symbol]
+      def get_role(id=nil)
+        lookup_role(id ? config[:model].find_by_id(id) : nil)
+      end
+
+      # Return the minimum role required for +action+, and, if specified,
+      # +property+.
+      #
+      # @param [Symbol] action
+      #   :read, :create, :update, or :delete
+      #
+      # @return [Symbol]
+      #   a role (such as :anonymous, :basic, or :admin)
+      def minimum_role(action, property=nil)
+        if property.nil?
+          config[:permission][to_read_or_modify(action)]
+        else
+          config[:properties][property][to_r_or_w(action)]
+        end || :anonymous
+      end
+      
+      protected
+
+      # Is +role+ authorized for +action+, and, if specified, +property+?
+      #
+      # @param [Symbol] role
+      #   a role (such as :anonymous, :basic, or :admin)
+      #
+      # @param [Symbol] action
+      #   :read, :create, :update, or :delete
+      #
+      # @param [Symbol] property
+      #   a property of a resource
+      #
+      # @return [Boolean]
+      def authorized?(action, role, property=nil)
+        klass = config[:roles]
+        klass.validate_role(role)
+        klass.satisfies?(role, minimum_role(action, property))
+      end
+
+      # Application-level hook that runs as part of +check_permission+,
+      # before +authorized?(action, role)+ is called.
+      #
+      # For example, an application might want to throw custom errors
+      # in certain situations before +authorized?+ runs.
+      #
+      # Applications must override this method.
+      # 
+      # @param [Symbol] action
+      #   :read, :create, :update, or :delete
+      #
+      # @param [Symbol] role
+      #   a role (such as :anonymous, :basic, or :admin)
+      #
+      # @return [String]
+      def before_authorization(action, role)
+        raise NotImplementedError
+      end
+
+      # Default body message for a +situation+
+      #
+      # @param [Symbol] situation
+      #
+      # @param [Object] object
+      #
+      # @return [String]
+      def body_for(situation, object=nil)
+        case situation
+        when :errors
+          { "errors" => object }
+        when :internal_server_error
+          ""
+        when :invalid_document
+          { "errors" => object.errors.errors }
+        when :invalid_params
+          { "errors" => { "invalid_params" => object } }
+        when :no_params
+          { "errors" => "no_params" }
+        when :non_empty_params
+          { "errors" => "non_empty_params" }
+        when :not_found
+          ""
+        when :unauthorized
+          ""
+        end
+      end
+
+      # Lookup the rol, using +document+ if specified.
+      #
+      # Applications must override this method.
+      #
+      # @param [MongoMapper::Document, nil] document
+      #
+      # @return [Symbol]
+      def lookup_role(document=nil)
+        raise NotImplementedError
+      end
+
+      # Are the params suitable for +action+? Raise 400 Bad Request if not.
+      #
+      # @param [Symbol] action
+      #   :read, :create, :update, or :delete
+      #
+      # @return [undefined]
+      def params_check_action(action)
+        case action
+        when :read
+          unless params.empty?
+            error 400, convert(body_for(:non_empty_params))
+          end
+        when :create
+          # No need to complain. If there are problems,
+          # params_check_action_and_role will catch them.
+        when :update
+          if params.empty?
+            error 400, convert(body_for(:no_params))
+          end
+        when :delete
+          unless params.empty?
+            error 400, convert(body_for(:non_empty_params))
+          end
+        end
+      end
+
+      # Checks each parameter to make sure it is authorized for +action+ and
+      # +role+. Raises a 400 Bad Request if not authorized.
+      #
+      # @param [Symbol] action
+      #   :read, :create, :update, or :delete
+      #
+      # @param [Symbol] role
+      #   a role (such as :anonymous, :basic, or :admin)
+      #
+      # @return [undefined]
+      def params_check_action_and_role(action, role)
+        invalid = []
+        params.each_pair do |property, value|
+          invalid << property if !authorized?(action, role, property.intern)
+        end
+        unless invalid.empty?
+          error 400, convert(body_for(:invalid_params, invalid))
+        end
+      end
+
+      # Converts +action+ to :r or :w (i.e. read or write).
+      #
+      # @param [Symbol] action
+      #   :read, :create, or :update
+      #
+      # @return [Symbol]
+      #   :r or :w
+      def to_r_or_w(action)
+        case action
+        when :read   then :r
+        when :create then :w
+        when :update then :w
+        else raise "Unexpected action : #{action.inspect}"
+        end
+      end
+
+      # Converts +action+ to (:read or :modify).
+      #
+      # @param [Symbol] action
+      #   :read, :create, :update, or :delete
+      #
+      # @return [Symbol]
+      #   :read or :modify
+      def to_read_or_modify(action)
+        case action
+        when :read   then :read
+        when :create then :modify
+        when :update then :modify
+        when :delete then :modify
+        else raise "Unexpected action : #{action.inspect}"
+        end
+      end
+
+      # Lookup +attribute+ in +document+
+      #
+      # @param [Symbol] attribute
+      #   an attribute of +document+
+      #
+      # @param [MongoMapper::Document] document
+      #
+      # @return [undefined]
+      def value(attribute, document, property_hash)
+        proc = property_hash[:read_proc]
+        if proc
+          proc.call(document)
+        else
+          document[attribute == :id ? :_id : attribute]
+        end
+      end
+
+    end
+
+  end
+
+end