moonrope 1.3.3 → 2.0.2

data/example/authentication.rb

@@ -0,0 +1,50 @@
+authenticator :default do
+
+  description <<-DESCRIPTION
+    To authenticate to the API, you need to pass an appropriate API token with your
+    request. To find out how to obtain an API token, please refer to the Authentication
+    API documentaton which outlines the available methods available for this.
+  DESCRIPTION
+
+  header "X-Auth-Application", "The API application which is generated by us and provided to you.", :example => "abc123abc123abc123"
+  header "X-Auth-Token", "The API token for the user you wish to authenticate as.", :example => "abc123abc123abc123"
+
+  error "InvalidApplicationToken", "The application token provided in X-Auth-Application is not valid.", :attributes => {:token => "The token used to find the application"}
+  error "InvalidAuthToken", "The auth token provided in X-Auth-Token is not valid.", :attributes => {:token => "The token that was used"}
+  error "ExpiredAuthToken", "The auth token provided in X-Auth-Token has expired.", :attributes => {:expired_at => "The time the token expired"}
+
+  lookup do
+    if app_token = header['X-Auth-Application']
+      api_application = APIApplication.find_by_token(app_token)
+      if api_application.nil?
+        error "InvalidApplicationToken", :token => app_token
+      end
+
+      if auth_token = header['X-Auth-Token']
+        api_token = api_application.api_tokens.find_by_token(auth_token)
+        if api_token.nil? || api_token.inactive?
+          error "InvalidAuthToken", :token => auth_token
+        end
+
+        if api_token.expired?
+          error "ExpiredAuthToken", :expired_at => api_token.expired_at
+        end
+
+        api_token
+      end
+    end
+  end
+
+  rule :default, "NotAuthenticated", "Must be authenticated with a valid user API token." do
+    identity.is_a?(APIToken) && identity.user
+  end
+
+  rule :must_be_admin, "MustBeAdmin", "Must be authenticated as a valid admin user." do
+    identity.is_a?(APIToken) && identity.user && identity.user.admin?
+  end
+
+  rule :anonymous, "MustBeAnonymous", "Must not be authenticated (no auth headers provided)." do
+    identity == :anonymous
+  end
+
+end

data/example/controllers/meta_controller.rb

@@ -0,0 +1,14 @@
+controller :meta do
+
+  friendly_name "Meta API"
+  description <<-DESC
+    The meta API provides you with access to information about the API itself.
+  DESC
+
+  action :version do
+    description "Return the current software version"
+    returns :string, :eg => "v1.2.3"
+    action { LlamaCom::VERSION }
+  end
+
+end

data/example/controllers/users_controller.rb

@@ -0,0 +1,92 @@
+controller :users do
+
+  friendly_name "Users API"
+  description <<-DESC
+    The Users API provides full access to manage the users
+    which exist on your account.
+  DESC
+
+  action :list do
+    title "List all users"
+    description "This action will return a list of all users which the authenticated user has access to."
+    param :page, "The page number", :default => 1, :type => Integer
+    param :per_page, "The number of items to return per page", :default => 30, :type => Integer
+    sortable :username, :id, :created_at, :updated_at
+    paginated
+    filterable do
+      attribute :username, :type => String
+      attribute :age, :type => Integer
+      attribute :admin, :type => :boolean
+    end
+    returns :array, :structure => :user
+    action do
+      paginate(User.all) do |user|
+        structure user, :return => true
+      end
+    end
+  end
+
+  action :show do
+    title "Get unit information"
+    param :username, "The user's username", :type => String, :required => true
+    returns :hash, :structure => :user, :structure_opts => {:paramable => true}
+    error "UserNotFound", "No user was found matching the given username", :attributes => {:username => "The username which was looked up"}
+    action do
+      if user = User.find_by_username(params.username)
+        structure user, :return => true
+      else
+        error 'UserNotFound', :username => params.username
+      end
+    end
+  end
+
+  shared_action :properties do
+    param :username, "The user's username", :type => String
+    param :first_name, "The user's first name", :type => String
+    param :last_name, "The user's last name", :type => String
+    param :email_address, "The user's e-mail address", :type => String
+    param :password, "The user's password", :type => String
+    param :admin, "Should this user be an admin?", :type => :boolean do |object, value|
+      if identity.admin?
+        object.admin = value
+      end
+    end
+  end
+
+  action :create do
+    title "Create a new user"
+    description <<-DESCRIPTION
+      This action will create a new user with the properties which have been provided.
+    DESCRIPTION
+    use :properties
+    returns :hash, :structure => :user, :structure_opts => {:full => true}
+    error "ValidationError", "The details provided were not sufficient to save the user", :attributes => {:errors => "An array of errors for each field"}
+    action do
+      user = User.new
+      if user.save
+        structure user, :return => true
+      else
+        error 'ValidationError', :errors => user.errors
+      end
+    end
+  end
+
+  action :update do
+    title "Update an existing user"
+    description "This action will update an existing user with the properties provided."
+    param :id, "The ID of the user to update", :type => Integer, :required => true
+    use :properties
+    returns :hash, :structure => :user, :structure_opts => {:full => true}
+    error 'UserNotFound', "The user specified could not be found", :attributes => {:id => "The ID that was looked up"}
+    error "ValidationError", "The details provided were not sufficient to save the user", :attributes => {:errors => "An array of errors for each field"}
+    action do
+      user = User.find_by_id(params.id) || error('UserNotFound', :id => params.id)
+      if user.save
+        structure user, :return => true
+      else
+        error 'ValidationError', :errors => user.errors
+      end
+    end
+  end
+
+end

data/example/structures/pet_structure.rb

@@ -0,0 +1,12 @@
+structure :pet do
+
+  # Uncomment the below line to stop this structure being documented.
+  # no_doc!
+
+  basic :id, "The ID of the pet", :type => Integer, :eg => 148
+  basic :name, "The name of the pet", :type => String, :eg => "Fido"
+  basic :color, "What color is the pet?", :type => String, :eg => "Green"
+
+  expansion :user, "The user who owns this pet", :type => Hash, :structure => :user
+
+end

data/example/structures/user_structure.rb

@@ -0,0 +1,35 @@
+structure :user do
+
+  basic :id, "The user's internal system ID", :type => Integer, :eg => 123
+  basic :username, "The user's unique username", :type => String, :eg => "adamcooke"
+  group :name do
+    basic :first, "The user's first name", :type => String, :eg => "Adam", :source_attribute => :first_name
+    basic :last, "The user's last name", :type => String, :eg => "Cooke", :source_attribute => :last_name
+  end
+
+  full :admin, "Is this user an administrator?", :type => :boolean
+  full :age, "The user's age", :type => Integer, :doc => false
+  full :created_at, "The timestamp the user was created", :type => :timestamp
+  full :updated_at, "The timestamp the user was updated", :type => :timestamp
+
+  expansion :pets, "All pets that belong to this user", :structure => :pet, :type => Array
+
+  expansion :balance, "The user's balance", :type => Float, :eg => 12.50 do
+    o.user.balance
+  end
+
+  expansion :hidden, "This is a hidden expansion", :doc => false do
+    o.user.hidden
+  end
+
+  condition Proc.new { identity.admin? }, "Can only be accessed by API users with admin access" do
+    # This value will only be provided to users who are accesing the API with
+    # the permission to view
+    full :support_pin, "The PIN this user needs to use to access support", :type => String, :eg => "4953"
+  end
+
+  condition :default => :anonymous do
+    full :mask, "The unique mask that represents this user", :type => String, :eg => 'abc123abc123'
+  end
+
+end

data/lib/moonrope.rb

@@ -11,7 +11,8 @@ require 'moonrope/dsl/base_dsl'
 require 'moonrope/dsl/action_dsl'
 require 'moonrope/dsl/controller_dsl'
 require 'moonrope/dsl/structure_dsl'
-
+require 'moonrope/dsl/authenticator_dsl'
+require 'moonrope/authenticator'
 require 'moonrope/errors'
 require 'moonrope/eval_helpers'
 require 'moonrope/eval_environment'
@@ -26,13 +27,13 @@ require 'moonrope/version'
 require 'moonrope/railtie' if defined?(Rails)
 
 module Moonrope
-  
+
   class << self
     attr_accessor :logger
-    
+
     def logger
       @logger ||= Logger.new(STDOUT)
     end
   end
-    
+
 end

data/lib/moonrope/action.rb

@@ -1,3 +1,6 @@
+require 'moonrope/dsl/action_dsl'
+require 'moonrope/action_result'
+
 module Moonrope
   class Action
 
@@ -13,14 +16,35 @@ module Moonrope
     # @return [Hash] the params available for the action
     attr_reader :params
 
+    # @return [String] the title of the action
+    attr_accessor :title
+
     # @return [String] the description of the action
     attr_accessor :description
 
-    # @return [Proc] the access check condition for the action
-    attr_accessor :access
+    # @return [Array] the actual action blocks for the action
+    attr_accessor :actions
+
+    # @return [Symbol] the name of the authenticator for this action
+    attr_accessor :authenticator
+
+    # @return [Symbol] the name of the access rule for this action
+    attr_accessor :access_rule
+
+    # @return [Hash] the errors which can be retuend by this action
+    attr_accessor :errors
+
+    # @return [Hash] details of what will be returned on success
+    attr_accessor :returns
+
+    # @return [Bool] whether or not the action should be documented
+    attr_accessor :doc
+
+    # @return [Array] additional traits that have been applied to this action
+    attr_reader :traits
 
-    # @return [Proc] the action for the action
-    attr_accessor :action
+    # @return [Hash] a hash of filters that are applied
+    attr_reader :filters
 
     #
     # Initialize a new action
@@ -33,6 +57,10 @@ module Moonrope
       @controller = controller
       @name = name
       @params = {}
+      @errors = {}
+      @traits = []
+      @actions = []
+      @filters = {}
       @dsl = Moonrope::DSL::ActionDSL.new(self)
       @dsl.instance_eval(&block) if block_given?
     end
@@ -49,23 +77,51 @@ module Moonrope
       end
     end
 
+    #
+    # Return the authenticator that should be used when executing this action
+    #
+    # @return [Moonrope::Authenticator]
+    #
+    def authenticator_to_use
+      @authenticator_to_use ||= begin
+        if @authenticator
+          @controller.base.authenticators[@authenticator] || :not_found
+        elsif @controller.authenticator
+          @controller.base.authenticators[@controller.authenticator] || :not_found
+        else
+          @controller.base.authenticators[:default] || :none
+        end
+      end
+    end
+
+    #
+    # Return the access rule to use for this action#
+    #
+    # @return [Symbol]
+    #
+    def access_rule_to_use
+      @access_rule_to_use ||= access_rule || @controller.access_rule || :default
+    end
+
     #
     # Execute a block of code and catch approprite Moonrope errors and return
     # a result.
     #
-    def convert_errors_to_action_result(&block)
+    def convert_errors_to_action_result(start_time = nil, &block)
       begin
         yield block
       rescue => exception
         case exception
         when Moonrope::Errors::RequestError
           result = ActionResult.new(self)
+          result.time = start_time ? (Time.now - start_time).round(2) : nil
           result.status = exception.status
           result.data = exception.data
           result
         else
           if error_block = @controller.base.external_errors[exception.class]
             result = ActionResult.new(self)
+            result.time = start_time ? (Time.now - start_time).round(2) : nil
             error_block.call(exception, result)
             result
           else
@@ -86,7 +142,7 @@ module Moonrope
       if request.is_a?(EvalEnvironment)
         eval_environment = request
       else
-        eval_environment = EvalEnvironment.new(@controller.base, request)
+        eval_environment = EvalEnvironment.new(@controller.base, request, self)
       end
 
       #
@@ -95,27 +151,24 @@ module Moonrope
       #
       eval_environment.default_params = self.default_params
 
-      #
-      # Set the current action to the eval environment so it knows what action
-      # invoked this.
-      #
-      eval_environment.action = self
+      start_time = Time.now
 
-      convert_errors_to_action_result do
+      convert_errors_to_action_result(start_time) do
         #
         # Validate the parameters
         #
         self.validate_parameters(eval_environment.params)
 
-        start_time = Time.now
-
         # Run before filters
         controller.before_actions_for(name).each do |action|
           eval_environment.instance_eval(&action.block)
         end
 
         # Run the actual action
-        response = eval_environment.instance_eval(&action)
+        response = nil
+        actions.each do |action|
+          response = eval_environment.instance_exec(response, &action)
+        end
 
         # Calculate the length of time this request takes
         time_to_run = Time.now - start_time
@@ -144,34 +197,25 @@ module Moonrope
       if request.is_a?(EvalEnvironment)
         eval_environment = request
       else
-        eval_environment = EvalEnvironment.new(@controller.base, request)
+        eval_environment = EvalEnvironment.new(@controller.base, request, self)
       end
 
-      access_condition = self.access || @controller.access || @controller.base.default_access
-
-      if eval_environment.auth
-        # If there's no authentication object, access is permitted otherwise
-        # we'll do the normal testing.
-        if access_condition.is_a?(Proc)
-          !!eval_environment.instance_exec(self, &access_condition)
-        elsif access_condition.is_a?(Symbol)
-          !!(eval_environment.auth.respond_to?(access_condition) && eval_environment.auth.send(access_condition))
-        elsif access_condition.is_a?(Hash) && access_condition[:must_be] && access_condition[:with]
-          !!(eval_environment.auth.is_a?(access_condition[:must_be]) &&
-              eval_environment.auth.respond_to?(access_condition[:with]) &&
-              eval_environment.auth.send(access_condition[:with])
-            )
-        elsif access_condition.is_a?(Hash) && access_condition[:must_be]
-          !!(eval_environment.auth.is_a?(access_condition[:must_be]))
-        elsif access_condition == true
-          true
+      if authenticator_to_use.is_a?(Moonrope::Authenticator)
+        if rule = authenticator_to_use.rules[access_rule_to_use]
+          eval_environment.instance_exec(self, &rule[:block]) == true
         else
-          false
+          if access_rule_to_use == :default
+            # The default rule on any authenticator will allow everything so we
+            # don't need to worry about this not being defined.
+            true
+          else
+            # If an access rule that doesn't exist has been requested, we will
+            # raise an internal error.
+            raise Moonrope::Errors::MissingAccessRule, "The rule '#{access_rule_to_use}' was not found on '#{authenticator_to_use.name}' authenticator"
+          end
         end
       else
-        # No authentication object is available to test with. The result here
-        # depends on whether or not an access condition has been defined or not.
-        !access_condition
+        true
       end
     end
 
@@ -191,12 +235,98 @@ module Moonrope
           raise Moonrope::Errors::ParameterError, "`#{name}` parameter is invalid"
         end
 
-        if value[:type] && param_set[name] && !param_set[name].is_a?(value[:type])
-          raise Moonrope::Errors::ParameterError, "`#{name}` should be a `#{value[:type]}` but is a `#{param_set[name].class}`"
+        if value[:options].is_a?(Array) && param_set[name] && !value[:options].include?(param_set[name])
+          raise Moonrope::Errors::ParameterError, "`#{name}` must be one of #{value[:options].join(', ')}"
+        end
+
+        if value[:type] && param_set[name]
+          if value[:type] == :boolean
+            if BOOLEAN_VALUES.include?(param_set[name])
+              param_set._set_value(name, TRUE_LIKE_VALUES.include?(param_set[name]))
+            else
+              raise Moonrope::Errors::ParameterError, "`#{name}` should be a boolean value"
+            end
+          elsif value[:type].is_a?(Symbol) || value[:type].is_a?(String)
+            # Value is a symbol, nothing to do.
+          elsif !param_set[name].is_a?(value[:type])
+            raise Moonrope::Errors::ParameterError, "`#{name}` should be a `#{value[:type]}` but is a `#{param_set[name].class}`"
+          end
         end
       end
       true
     end
 
+    TRUE_LIKE_VALUES = ['true', '1', 1, true]
+    FALSE_LIKE_VALUES = ['false', '0', 0, false]
+    BOOLEAN_VALUES = TRUE_LIKE_VALUES + FALSE_LIKE_VALUES
+
+    #
+    # Does this action allow the user to include/exclude full attributes when
+    # calling this action?
+    #
+    def can_change_full?
+      if returns && opts = returns[:structure_opts]
+        opts[:paramable] == true ||
+        (opts[:paramable].is_a?(Hash) && opts[:paramable].has_key?(:full))
+      else
+        false
+      end
+    end
+
+    #
+    # Does this action include full attributes by default?
+    #
+    def includes_full_attributes?
+      if returns && opts = returns[:structure_opts]
+        (opts[:paramable].is_a?(Hash) && opts[:paramable][:full] == true) ||
+        opts[:full] == true
+      else
+        false
+      end
+    end
+
+    #
+    # Does this action allow the user to include/exclude expansions when calling
+    # this action?
+    #
+    def can_change_expansions?
+      if returns && opts = returns[:structure_opts]
+        opts[:paramable] == true ||
+        (opts[:paramable].is_a?(Hash) && opts[:paramable].has_key?(:expansions))
+      else
+        false
+      end
+    end
+
+    #
+    # Does this action include full attributes by default?
+    #
+    def includes_expansion?(expansion)
+      if returns && opts = returns[:structure_opts]
+        (opts[:paramable].is_a?(Hash) && opts[:paramable][:expansions] == true) ||
+        opts[:expansions] == true ||
+        (opts[:paramable].is_a?(Hash) && opts[:paramable][:expansions].is_a?(Array) && opts[:paramable][:expansions].include?(expansion)) ||
+        (opts[:expansions].is_a?(Array) && opts[:expansions].include?(expansion))
+      else
+        false
+      end
+    end
+
+    #
+    # Which expansions is the user permitted to include/exclude when calling this
+    # action.
+    #
+    def available_expansions
+      if returns && (structure = returns[:structure]) && can_change_expansions?
+        if returns[:structure_opts][:paramable].is_a?(Hash) && returns[:structure_opts][:paramable][:expansions].is_a?(Array)
+          returns[:structure_opts][:paramable][:expansions]
+        else
+          @controller.base.structure(structure).all_expansions
+        end
+      else
+        []
+      end
+    end
+
   end
 end