sinatra_resource 0.1.0

data/lib/builder/mongo_helpers.rb

@@ -0,0 +1,70 @@
+module SinatraResource
+  
+  class Builder
+
+    module MongoHelpers
+      
+      # Create a document from params. If not valid, returns 400.
+      #
+      # @return [MongoMapper::Document]
+      def create_document!
+        document = config[:model].new(params)
+        unless document.valid?
+          error 400, convert(body_for(:invalid_document, document))
+        end
+        unless document.save
+          error 400, convert(body_for(:internal_server_error))
+        end
+        document
+      end
+      
+      # Delete a document with +id+.
+      #
+      # @param [String] id
+      #
+      # @return [MongoMapper::Document]
+      def delete_document!(id)
+        document = find_document!(id)
+        document.destroy
+        document
+      end
+
+      # Find a document with +id+. If not found, returns 404.
+      #
+      # @param [String] id
+      #
+      # @return [MongoMapper::Document]
+      def find_document!(id)
+        document = config[:model].find_by_id(id)
+        unless document
+          error 404, convert(body_for(:not_found))
+        end
+        document
+      end
+
+      # Find all +model+ documents.
+      #
+      # @param [Class] model
+      #   a class that includes MongoMapper::Document
+      #
+      # @return [Array<MongoMapper::Document>]
+      def find_documents!
+        config[:model].find(:all)
+      end
+
+      # Update a document with +id+ from params. If not valid, returns 400.
+      #
+      # @return [MongoMapper::Document]
+      def update_document!(id)
+        document = config[:model].update(id, params)
+        unless document.valid?
+          error 400, convert(body_for(:invalid_document, document))
+        end
+        document
+      end
+
+    end
+
+  end
+
+end

data/lib/builder.rb

@@ -0,0 +1,84 @@
+module SinatraResource
+
+  class Builder
+    
+    def initialize(klass)
+      @klass = klass
+    end
+    
+    def build
+      build_get_one
+      build_get_many
+      build_post
+      build_put
+      build_delete
+      build_helpers
+    end
+    
+    def build_get_one
+      @klass.get '/:id/?' do
+        id = params.delete("id")
+        role = get_role(id)
+        check_permission(:read, role)
+        check_params(:read, role)
+        document = find_document!(id)
+        resource = build_resource(role, document)
+        display(:read, resource)
+      end
+    end
+
+    def build_get_many
+      @klass.get '/?' do
+        role = get_role
+        check_permission(:read, role)
+        check_params(:read, role)
+        documents = find_documents!
+        resources = build_resources(documents)
+        display(:read, resources)
+      end
+    end
+    
+    def build_post
+      @klass.post '/?' do
+        role = get_role
+        check_permission(:create, role)
+        check_params(:create, role)
+        document = create_document!
+        resource = build_resource(role, document)
+        display(:create, resource)
+      end
+    end
+    
+    def build_put
+      @klass.put '/:id/?' do
+        id = params.delete("id")
+        role = get_role(id)
+        check_permission(:update, role)
+        check_params(:update, role)
+        document = update_document!(id)
+        resource = build_resource(role, document)
+        display(:update, resource)
+      end
+    end
+    
+    def build_delete
+      @klass.delete '/:id/?' do
+        id = params.delete("id")
+        role = get_role(id)
+        check_permission(:delete, role)
+        check_params(:delete, role)
+        delete_document!(id)
+        display(:delete, "")
+      end
+    end
+    
+    def build_helpers
+      @klass.helpers do
+        include Helpers
+        include MongoHelpers
+      end
+    end
+    
+  end
+  
+end

data/lib/exceptions.rb

@@ -0,0 +1,10 @@
+module SinatraResource
+
+  class Error < RuntimeError; end
+    
+  class DefinitionError < Error; end
+  class NotImplemented  < Error; end
+  class UndefinedRole   < Error; end
+  class ValidationError < Error; end
+
+end

data/lib/resource.rb

@@ -0,0 +1,171 @@
+module SinatraResource
+  
+  module Resource
+    def self.included(includee)
+      includee.extend ClassMethods
+      includee.setup
+    end
+    
+    def config
+      self.class.instance_variable_get("@resource_config")
+    end
+    
+    module ClassMethods
+      
+      # Build the Sinatra actions based on the DSL statements in this class.
+      # You will want to do this last.
+      #
+      # If for some reason you reopen the class, you will need to call this
+      # method again. However, this usage has not been tested.
+      #
+      # @return [undefined]
+      def build
+        validate
+        Builder.new(self).build
+      end
+
+      # Specify the underlying +model+
+      #
+      # @example
+      #   model User
+      #
+      #   # which refers to, for example ...
+      #   # class User
+      #   #   include MongoMapper::Document
+      #   #   ...
+      #   # end
+      #
+      # @param [MongoMapper::Document] model
+      #
+      # @return [undefined]
+      def model(model)
+        if @resource_config[:model]
+          raise DefinitionError, "model already declared in #{self}"
+        end
+        @resource_config[:model] = model
+        default_properties
+      end
+      
+      # Specify the minimal role needed to access this resource for reading
+      # or writing.
+      #
+      # @example
+      #   permission :read   => :basic
+      #   permission :modify => :owner
+      #
+      # @param [Hash<Symbol => Symbol>] access_rules
+      #   valid keys are :read or :modify
+      #   values should be a role (such as :admin)
+      #
+      # @return [undefined]
+      def permission(access_rules)
+        access_rules.each_pair do |verb, role|
+          @resource_config[:permission][verb] = role
+        end
+      end
+      
+      # Declare a property and its access rules.
+      #
+      # @example
+      #   property :name,  :r => :basic
+      #   property :email, :r => :owner
+      #   property :role,  :r => :owner, :w => :admin
+      #
+      # @param [Symbol] name
+      #
+      # @param [Hash] access_rules
+      #
+      # @return [undefined]
+      def property(name, access_rules={}, &block)
+        if @resource_config[:properties][name]
+          raise DefinitionError, "property #{name} already declared in #{self}"
+        end
+        @resource_config[:properties][name] = {}
+        if block
+          @resource_config[:properties][name][:w] = :nobody
+          @resource_config[:properties][name][:read_proc] = block
+        else
+          access_rules.each_pair do |kind, role|
+            @resource_config[:properties][name][kind] = role
+          end
+        end
+      end
+      
+      # Specify the role definitions for this resource.
+      #
+      # @example
+      #   roles Roles
+      #   
+      #   # which refers to, for example ...
+      #   # module Roles
+      #   #   include SinatraResource::Roles
+      #   # 
+      #   #   role :anonymous
+      #   #   role :basic => :anonymous
+      #   #   role :admin => :basic
+      #   # end
+      #
+      # @param [Class] klass
+      #
+      # @return [undefined]
+      def roles(klass)
+        if @resource_config[:roles]
+          raise DefinitionError, "roles already declared in #{self}"
+        end
+        @resource_config[:roles] = klass
+      end
+
+      # For internal use. Initializes internal data structure.
+      def setup
+        @resource_config = {
+          :model      => nil,
+          :permission => {},
+          :properties => {},
+          :roles      => nil,
+          :path       => default_path,
+        }
+      end
+      
+      protected
+      
+      # Return the default relative path for a resource.
+      #
+      # @return [String]
+      def default_path
+        self.to_s.split('::').last.downcase
+      end
+
+      # Define some default properties to mirror common keys in the
+      # model
+      #
+      # @return [undefined]
+      def default_properties
+        keys = @resource_config[:model].keys
+        if keys.include?("_id")
+          property :id, :w => :nobody
+        end
+        
+        if keys.include?("created_at")
+          property :created_at, :w => :nobody
+        end
+
+        if keys.include?("updated_at")
+          property :updated_at, :w => :nobody
+        end
+      end
+      
+      # Verifies correctness of resource.
+      #
+      # @raise [ValidationError] if invalid
+      #
+      # @return [undefined]
+      def validate
+        unless @resource_config[:model]
+          raise ValidationError, "model required"
+        end
+      end
+      
+    end
+  end
+  
+end

data/lib/roles.rb

@@ -0,0 +1,163 @@
+module SinatraResource
+
+  module Roles
+    def self.included(includee)
+      includee.extend ClassMethods
+      includee.setup
+    end
+    
+    module ClassMethods
+
+      # High-level way to define a role. You can also specify what role it
+      # builds upon (its parent).
+      #
+      # For example:
+      #   role :anonymous
+      #   role :basic => :anonymous
+      #   role :admin => :basic
+      #
+      # This means: admin > basic > anonymous
+      #
+      # The order of the role statements does not matter. Only the
+      # dependencies between a role and its parent are significant.
+      #
+      # Roles do not have to be a single linear ordering. You can have any
+      # number of roles, connected in a DAG (directed acyclic graph). For
+      # example:
+      #
+      #   role :anonymous
+      #   role :basic   => :anonymous
+      #   role :editor  => :basic
+      #   role :manager => :basic
+      #   role :admin   => [:editor, :manager]
+      #
+      #   # which means:
+      #   # * admin > manager > basic > anonymous
+      #   # * admin > editor  > basic > anonymous
+      #   # * manager and editor cannot be compared
+      #
+      # @param [Symbol, Hash<Symbol => [Symbol, Array<Symbol>]>] arg
+      def role(arg)
+        if arg.is_a?(Symbol)
+          create_role(arg)
+        elsif arg.is_a?(Hash)
+          arg.each_pair do |name, parent_name|
+            create_role(name, parent_name)
+          end
+        else
+          raise ArgumentError
+        end
+      end
+
+      # Is +role+ at least as privileged as +minimum+?
+      #
+      # @example
+      #   satisfies?(:anonymous, :basic) # => false
+      #   satisfies?(:admin,     :basic) # => true
+      #   satisfies?(:basic,     :basic) # => true
+      #
+      # @param [Symbol] role
+      #   a role (such as :anonymous, :basic, or :admin)
+      #
+      # @param [Symbol] minimum
+      #
+      # @return [Boolean]
+      def satisfies?(role, minimum)
+        @satisfies_cache[[role, minimum]] ||= (
+          role == minimum || ancestors(role).include?(minimum)
+        )
+      end
+
+      def setup
+        @role_config = {}
+        @satisfies_cache = {}
+      end
+
+      # Halt if +role+ is undefined.
+      #
+      # @raise [UndefinedRole] if role undefined
+      def validate_role(role)
+        unless @role_config.include?(role)
+          raise UndefinedRole, "#{role.inspect} not defined"
+        end
+      end
+
+      protected
+
+      # Find the ancestors of +role+.
+      #
+      # @param [Symbol] role
+      #
+      # @return [Array<Symbol>]
+      def ancestors(role)
+        _ancestors([role])
+      end
+
+      # Find the ancestors of +roles+.
+      #
+      # Implementation details
+      #
+      # This is a recursive function. For each recursion, all of the parents
+      # of the list are found. A new list is created by merging the original
+      # list and the parents. The recursion stops when the new list is the
+      # same as the original list.
+      #
+      # If you have these roles ...
+      #   role :anonymous
+      #   role :basic   => :anonymous
+      #   role :owner   => :basic
+      #   role :curator => :basic
+      #   role :admin   => [:owner, :curator]
+      #
+      # ... and you do ...
+      #   _ancestors([:owner, :curator])
+      #
+      # ... then the recursion unfolds like this:
+      #   _ancestors([:owner, :curator, :basic])
+      #   _ancestors([:owner, :curator, :basic, :anonymous])
+      #
+      # @param [Array<Symbol>] roles
+      #
+      # @return [Array<Symbol>]
+      def _ancestors(roles)
+        parents = roles.map { |role| parents(role) }.flatten
+        list = parents.concat(roles).uniq
+        return roles if list == roles
+        _ancestors(list)
+      end
+
+      # Low-level way to define a role. You can also specify what role it
+      # builds upon (+parent_name+).
+      #
+      # @param [Symbol] name
+      #   The name of the role being defined
+      #
+      # @param [Symbol, nil] parent_name
+      #   The name of the parent role
+      #
+      # @api private
+      def create_role(name, parent_name=nil)
+        @role_config[name] = parent_name
+      end
+
+      # Find the parents of +role+.
+      #
+      # @param [Symbol] role
+      #   a role (such as :anonymous, :basic, or :admin)
+      #
+      # @return [Array<Symbol>]
+      def parents(role)
+        x = @role_config[role]
+        if x.is_a?(Enumerable)
+          x
+        elsif x
+          [x]
+        else
+          []
+        end
+      end
+
+    end
+  end
+  
+end

data/lib/sinatra_resource.rb

@@ -0,0 +1,6 @@
+require File.dirname(__FILE__) + '/exceptions'
+require File.dirname(__FILE__) + '/builder/helpers'
+require File.dirname(__FILE__) + '/builder/mongo_helpers'
+require File.dirname(__FILE__) + '/builder'
+require File.dirname(__FILE__) + '/resource'
+require File.dirname(__FILE__) + '/roles'

data/notes/keywords.mdown

@@ -0,0 +1 @@
+* role-based permissions

data/notes/permissions.mdown

@@ -0,0 +1,181 @@
+# Preface
+
+Please consider this document in the context of building APIs in the Resource
+Oriented Architecture style.
+
+# Introduction
+
+Permission systems may be relatively simple or relatively complex.
+
+Simple permission systems are more rigid, less expressive, and hopefully
+simpler to develop. Complex permission systems are more flexible, more
+expressive, simpler (in theory) for an end-user to update, but harder to
+develop.
+
+It is not hard to envision reasonable permission systems that get moderately
+complicated fairly quickly. Why?
+
+* It may be easier to state permissions in terms of general rules and
+  exceptions to the general rule instead of spelling out every single
+  situation explicitly.
+* Permissions are often multi-leveled.
+* Permissions are rules, so sometimes the precedence is not obvious.
+* Permissions are sometimes most conveniently stated in terms of
+  'positive' and 'negative' rules. This create possibilities for
+  logical contradictions.
+
+A relatively simple example of a permission system would:
+
+* have single level
+* would require every situation to be spelled out explicitly
+
+A more complex, but still achievable permission system would:
+
+* have a couple of levels
+* would allow general rules to be stated
+* would allow specific situations to be spelled out
+* would allow more specific rules to override more general ones
+* would detect conflicts
+
+# Permissions can be stated at many levels:
+
+* action level
+* document level
+* property level
+
+# What are some example use cases?
+
+## Resource-level permission stories:
+
+This stories illustrate when a user type either can or cannot access
+a resource based just upon the action type.
+
+    :admin_user can   :read   any Source
+    :admin_user can   :create a   Source
+    :admin_user can   :update any Source
+    :admin_user can   :delete any Source
+
+    :basic_user can   :read   any Source
+    :basic_user can't :create any Source
+    :basic_user can't :update any Source
+    :basic_user can't :delete any Source
+
+To extract the pattern:
+
+    UserType {can | can't} Action Resource
+
+In other words, if you know the user type, action, and resource, you
+know whether to allow or disallow.
+
+    def allow?(user_type, action, resource)
+      # logic depends solely on parameters
+    end
+    
+    def disallow?(user_type, action, resource)
+      # logic depends solely on parameters
+    end
+
+## Document-level use cases:
+
+In some cases, knowing the user type, action, and resource is not enough --
+the relationship between the 'document at hand' and the 'user at hand' is also
+needed. Note that the 'document at hand' is different from the 'resource' and
+the 'user at hand' is different from the 'user type'.
+
+    :basic_user can't :read   any          Note  # less useful
+    :basic_user can   :read   some         Notes # less useful
+    :basic_user can   :read   an   owned   Note
+    :basic_user can't :read   an   unowned Note
+    
+    :basic_user can   :create a            Note
+    
+    :basic_user can't :update any          Note  # less useful
+    :basic_user can   :update some         Notes # less useful
+    :basic_user can   :update an   owned   Note
+    :basic_user can't :update an   unowned Note
+    
+    :basic_user can't :delete any          Note  # less useful
+    :basic_user can   :delete some         Notes # less useful
+    :basic_user can   :delete an   owned   Note
+    :basic_user can't :delete an   unowned Note
+
+These stories can be rewritten to make the pattern clearer:
+
+    :basic_user user can   :read   the Note n if n.owner == user
+    :basic_user user can't :read   the Note n if n.owner != user
+    :basic_user user can   :create a   Note
+    :basic_user user can   :update the Note n if n.owner == user
+    :basic_user user can't :update the Note n if n.owner != user
+    :basic_user user can   :delete the Note n if n.owner == user
+    :basic_user user can't :delete the Note n if n.owner != user
+
+To extract the pattern:
+
+    UserType {can | can't} Action
+
+There is another way to see it, that uses "iff" ("if and only if"):
+
+    :basic_user user can   :read   the Note n iff n.owner == user
+    :basic_user user can   :create a   Note
+    :basic_user user can   :update the Note n iff n.owner == user
+    :basic_user user can   :delete the Note n iff n.owner == user
+
+I'm not sure I prefer the "iff" form. It is more compact, but I get the
+feeling that it makes it harder to have multilevel (cascading) permissions.
+
+To extract the pattern:
+
+    UserType User Action Resource Instance Relation
+
+    UserType : :basic_user
+    User     : 'user'
+    Action   : [:read, :create, :update, :delete]
+    Resource : Note
+    Instance : 'n'
+    Relation : :owner
+
+To back up (skipping a few steps, but I hope this is still clear) and remove
+the "iff" we would give us this pattern:
+
+    UserType User {can | can't} Action Resource Instance Relation
+
+The nice thing about the {can | can't} style is that it allows for one or both
+'sides' to be specified.
+
+Which brings us back to the 'allow?' and 'disallow?' methods:
+
+    def allow?(user_type, user, action, resource, instance, relation)
+      # logic depends solely on parameters
+    end
+    
+    def disallow?(user_type, user, action, resource, instance, relation)
+      # logic depends solely on parameters
+    end
+
+I would expect that user_type can be derived from user, so we can simplify:
+
+    def allow?(user, action, resource, instance, relation)
+      # logic depends solely on parameters
+    end
+    
+    def disallow?(user, action, resource, instance, relation)
+      # logic depends solely on parameters
+    end
+
+It is tempting to try to simplify further. For example, why not assume that resource can be inferred from instance? That may be so, but I'm not so convinced that there is only one resource for each instance. For example,
+what if we are talking about a "note" which can be exposed in two places:
+
+* /sources/40/note/231
+* /note/231
+
+I skipped a key question: is this two resources or two representations?
+(Sorry, I'm not going to answer this one right now.)
+
+Depending on your answer, another question arises: is there a need to specify different permissions for each of these (resources | representations)?
+
+## Property-level use cases:
+
+* read/write (a good default)
+* writable only by a certain user type / permission (e.g. admin)
+* writable only users that satisfy a relation (e.g. ownership)
+* writable only on creation

data/notes/questions.mdown

@@ -0,0 +1,18 @@
+# Questions:
+
+* How to use MongoMapper?
+
+* How to use ActiveRecord?
+
+* How to use DataMapper?
+
+* How to handle permissions?
+
+* How to handle action-level permissions?
+
+* How to handle document-level permissions?
+
+* How to do complete overrides?
+
+* How to have a resource define a "ratings" property if the underlying model
+  already has a :ratings association?