haveapi 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3eed7a7a97050e343134cb1d9cfd614099a613c6
+  data.tar.gz: 09d4bc3e055b2d385b8e6bdf49140425852b4a6f
+SHA512:
+  metadata.gz: ed8241e6a1e8d65b41fb56671fe421730eaab16a748d8373d4331c06a5b14990e2e4a7b535919524bf655ab8a0ca0f6fccdb4c83932d9ec78ece6caffb7e9397
+  data.tar.gz: 992ef4d404cdd0b07564b6bd9310c59280544a026382ec1a84b753586a8cab2482a293f72b3ea15b55f4dcd487181747b7abf14f2f04b880b057ea7b8bef7272

data/lib/haveapi/action.rb

@@ -0,0 +1,521 @@
+module HaveAPI
+  class Action < Common
+    obj_type :action
+    has_attr :version
+    has_attr :desc
+    has_attr :route
+    has_attr :resolve, ->(klass){ klass.respond_to?(:id) ? klass.id : nil }
+    has_attr :http_method, :get
+    has_attr :auth, true
+    has_attr :aliases, []
+
+    include Hookable
+
+    has_hook :exec_exception
+
+    attr_reader :message, :errors, :version
+    attr_accessor :flags
+
+    class << self
+      attr_reader :resource, :authorization, :examples
+
+      def inherited(subclass)
+        # puts "Action.inherited called #{subclass} from #{to_s}"
+
+        subclass.instance_variable_set(:@obj_type, obj_type)
+
+        if subclass.name
+          # not an anonymouse class
+          delayed_inherited(subclass)
+        end
+      end
+
+      def delayed_inherited(subclass)
+        resource = Kernel.const_get(subclass.to_s.deconstantize)
+
+        inherit_attrs(subclass)
+        inherit_attrs_from_resource(subclass, resource, [:auth])
+
+        i = @input.clone
+        i.action = subclass
+
+        o = @output.clone
+        o.action = subclass
+
+        m = {}
+
+        @meta.each do |k,v|
+          m[k] = v && v.clone
+          next unless v
+          m[k].action = subclass
+        end
+
+        subclass.instance_variable_set(:@input, i)
+        subclass.instance_variable_set(:@output, o)
+        subclass.instance_variable_set(:@meta, m)
+
+        begin
+          subclass.instance_variable_set(:@resource, resource)
+          subclass.instance_variable_set(:@model, resource.model)
+        rescue NoMethodError
+          return
+        end
+      end
+
+      def initialize
+        return if @initialized
+
+        input.exec
+        model_adapter(input.layout).load_validators(model, input) if model
+
+        output.exec
+
+        model_adapter(input.layout).used_by(:input, self)
+        model_adapter(output.layout).used_by(:output, self)
+
+        if @meta
+          @meta.each_value do |m|
+            next unless m
+            m.input && m.input.exec
+            m.output && m.output.exec
+          end
+        end
+
+        @initialized = true
+      end
+
+      def model_adapter(layout)
+        ModelAdapter.for(layout, resource.model)
+      end
+
+      def input(layout = nil, namespace: nil, &block)
+        if block
+          @input ||= Params.new(:input, self)
+          @input.layout = layout
+          @input.namespace = namespace
+          @input.add_block(block)
+        else
+          @input
+        end
+      end
+
+      def output(layout = nil, namespace: nil, &block)
+        if block
+          @output ||= Params.new(:output, self)
+          @output.layout = layout
+          @output.namespace = namespace
+          @output.add_block(block)
+        else
+          @output
+        end
+      end
+
+      def meta(type = :object, &block)
+        if block
+          @meta ||= {object: nil, global: nil}
+          @meta[type] ||= Metadata::ActionMetadata.new
+          @meta[type].action = self
+          @meta[type].instance_exec(&block)
+        else
+          @meta[type]
+        end
+      end
+
+      def authorize(&block)
+        @authorization = Authorization.new(&block)
+      end
+
+      def example(title = '', &block)
+        @examples ||= []
+        e = Example.new(title)
+        e.instance_eval(&block)
+        @examples << e
+      end
+
+      def build_route(prefix)
+        route = @route || to_s.demodulize.underscore
+
+        if !route.is_a?(String) && route.respond_to?(:call)
+          route = route.call(self.resource)
+        end
+
+        prefix + route % {resource: self.resource.to_s.demodulize.underscore}
+      end
+
+      def describe(context)
+        authorization = (@authorization && @authorization.clone) || Authorization.new
+
+        return false if (context.endpoint || context.current_user) && !authorization.authorized?(context.current_user)
+
+        route_method = context.action.http_method.to_s.upcase
+        context.authorization = authorization
+
+        if context.endpoint
+          context.action_instance = context.action.from_context(context)
+
+          ret = catch(:return) do
+            context.action_prepare = context.action_instance.prepare
+          end
+
+          return false if ret == false
+        end
+
+        {
+            auth: @auth,
+            description: @desc,
+            aliases: @aliases,
+            input: @input ? @input.describe(context) : {parameters: {}},
+            output: @output ? @output.describe(context) : {parameters: {}},
+            meta: @meta ? @meta.merge(@meta) { |_, v| v && v.describe(context) } : nil,
+            examples: @examples ? @examples.map { |e| e.describe } : [],
+            url: context.resolved_url,
+            method: route_method,
+            help: "#{context.url}?method=#{route_method}"
+        }
+      end
+
+      # Inherit attributes from resource action is defined in.
+      def inherit_attrs_from_resource(action, r, attrs)
+        begin
+          return unless r.obj_type == :resource
+
+        rescue NoMethodError
+          return
+        end
+
+        attrs.each do |attr|
+          action.method(attr).call(r.method(attr).call)
+        end
+      end
+
+      def from_context(c)
+        ret = new(nil, c.version, c.params, nil, c)
+        ret.instance_exec do
+          @safe_params = @params.dup
+          @authorization = c.authorization
+          @current_user = c.current_user
+        end
+
+        ret
+      end
+    end
+
+    def initialize(request, version, params, body, context)
+      @request = request
+      @version = version
+      @params = params
+      @params.update(body) if body
+      @context = context
+      @context.action = self.class
+      @context.action_instance = self
+      @metadata = {}
+      @reply_meta = {object: {}, global: {}}
+      @flags = {}
+
+      class_auth = self.class.authorization
+
+      if class_auth
+        @authorization = class_auth.clone
+      else
+        @authorization = Authorization.new {}
+      end
+    end
+
+    def validate!
+      begin
+        @params = validate
+      rescue ValidationError => e
+        error(e.message, e.to_hash)
+      end
+    end
+
+    def authorized?(user)
+      @current_user = user
+      @authorization.authorized?(user)
+    end
+
+    def current_user
+      @current_user
+    end
+
+    def params
+      @safe_params
+    end
+
+    def input
+      @safe_params[ self.class.input.namespace ] if self.class.input
+    end
+
+    def request
+      @request
+    end
+
+    def meta
+      @metadata
+    end
+
+    def set_meta(hash)
+      @reply_meta[:global].update(hash)
+    end
+
+    # Prepare object, set instance variables from URL parameters.
+    # This method should return queried object. If the method is
+    # not implemented or returns nil, action description will not
+    # contain link to an associated resource.
+    # --
+    # FIXME: is this correct behaviour?
+    # ++
+    def prepare
+
+    end
+
+    def pre_exec
+
+    end
+
+    # This method must be reimplemented in every action.
+    # It must not be invoked directly, only via safe_exec, which restricts output.
+    def exec
+      ['not implemented']
+    end
+
+    # Calls exec while catching all exceptions and restricting output only
+    # to what user can see.
+    # Return array +[status, data|error, errors]+
+    def safe_exec
+      ret = catch(:return) do
+        begin
+          validate!
+          prepare
+          pre_exec
+          exec
+        rescue Exception => e
+          tmp = call_class_hooks_as_for(Action, :exec_exception, args: [self, e])
+
+          if tmp.empty?
+            p e.message
+            puts e.backtrace
+            error('Server error occurred')
+          end
+
+          error(tmp[:message]) unless tmp[:status]
+        end
+      end
+
+      safe_output(ret)
+    end
+
+    def v?(v)
+      @version == v
+    end
+
+    def safe_output(ret)
+      if ret
+        output = self.class.output
+
+        if output
+          safe_ret = nil
+          adapter = self.class.model_adapter(output.layout)
+          out_params = self.class.output.params
+
+          case output.layout
+            when :object
+              out = adapter.output(@context, ret)
+              safe_ret = @authorization.filter_output(
+                  out_params,
+                  out,
+                  true
+              )
+              @reply_meta[:global].update(out.meta)
+
+            when :object_list
+              safe_ret = []
+
+              ret.each do |obj|
+                out = adapter.output(@context, obj)
+
+                safe_ret << @authorization.filter_output(
+                    out_params,
+                    out,
+                    true
+                )
+                safe_ret.last.update({Metadata.namespace => out.meta}) unless meta[:no]
+              end
+
+            when :hash
+              safe_ret = @authorization.filter_output(
+                  out_params,
+                  adapter.output(@context, ret),
+                  true
+              )
+
+            when :hash_list
+              safe_ret = ret
+              safe_ret.map! do |hash|
+                @authorization.filter_output(
+                    out_params,
+                    adapter.output(@context, hash),
+                    true
+                )
+              end
+
+            else
+              safe_ret = ret
+          end
+
+          ns = {output.namespace => safe_ret}
+          ns[Metadata.namespace] = @reply_meta[:global] unless meta[:no]
+
+          [true, ns]
+
+        else
+          [true, {}]
+        end
+
+      else
+        [false, @message, @errors]
+      end
+    end
+
+    input {}
+    output {}
+    meta(:global) do
+      input do
+        bool :no, label: 'Disable metadata'
+      end
+    end
+
+    protected
+    def with_restricted(*args)
+      if args.empty?
+        @authorization.restrictions
+      else
+        args.first.update(@authorization.restrictions)
+      end
+    end
+
+    # Convert parameter names to corresponding DB names.
+    # By default, input parameters are used for the translation.
+    def to_db_names(hash, src=:input)
+      return {} unless hash
+
+      params = self.class.method(src).call.params
+      ret = {}
+
+      hash.each do |k, v|
+        k = k.to_sym
+        hit = false
+
+        params.each do |p|
+          if k == p.name
+            ret[p.db_name] = v
+            hit = true
+            break
+          end
+        end
+
+        ret[k] = v unless hit
+      end
+
+      ret
+    end
+
+    # Convert DB names to corresponding parameter names.
+    # By default, output parameters are used for the translation.
+    def to_param_names(hash, src=:output)
+      return {} unless hash
+
+      params = self.class.method(src).call.params
+      ret = {}
+
+      hash.each do |k, v|
+        k = k.to_sym
+        hit = false
+
+        params.each do |p|
+          if k == p.db_name
+            ret[p.name] = v
+            hit = true
+            break
+          end
+        end
+
+        ret[k] = v unless hit
+      end
+
+      ret
+    end
+
+    def ok(ret={})
+      throw(:return, ret)
+    end
+
+    def error(msg, errs={})
+      @message = msg
+      @errors = errs
+      throw(:return, false)
+    end
+
+    private
+    def validate
+      # Validate standard input
+      @safe_params = @params.dup
+      input = self.class.input
+
+      if input
+        # First check layout
+        input.check_layout(@safe_params)
+
+        # Then filter allowed params
+        case input.layout
+          when :object_list, :hash_list
+            @safe_params[input.namespace].map! do |obj|
+              @authorization.filter_input(
+                  self.class.input.params,
+                  self.class.model_adapter(self.class.input.layout).input(obj))
+            end
+
+          else
+            @safe_params[input.namespace] = @authorization.filter_input(
+                self.class.input.params,
+                self.class.model_adapter(self.class.input.layout).input(@safe_params[input.namespace]))
+        end
+
+        # Remove duplicit key
+        @safe_params.delete(input.namespace.to_s)
+
+        # Now check required params, convert types and set defaults
+        input.validate(@safe_params)
+      end
+
+      # Validate metadata input
+      auth = Authorization.new { allow }
+      @metadata = {}
+
+      return if input && %i(object_list hash_list).include?(input.layout)
+
+      [:object, :global].each do |v|
+        meta = self.class.meta(v)
+        next unless meta
+
+        raw_meta = nil
+
+        [Metadata.namespace, Metadata.namespace.to_s].each do |ns|
+          params = v == :object ? (@params[input.namespace] && @params[input.namespace][ns]) : @params[ns]
+          next unless params
+
+          raw_meta = auth.filter_input(
+              meta.input.params,
+              self.class.model_adapter(meta.input.layout).input(params)
+          )
+
+          break if raw_meta
+        end
+
+        next unless raw_meta
+
+        @metadata.update(meta.input.validate(raw_meta))
+      end
+    end
+  end
+end

data/lib/haveapi/actions/default.rb

@@ -0,0 +1,55 @@
+module HaveAPI
+  module Actions
+    module Default
+      class Index < Action
+        route ''
+        http_method :get
+        aliases %i(list)
+
+        meta(:global) do
+          input do
+            bool :count, label: 'Return the count of all items', default: false
+          end
+
+          output do
+            integer :total_count, label: 'Total count of all items'
+          end
+        end
+
+        include HaveAPI::Actions::Paginable
+
+        def pre_exec
+          set_meta(total_count: count) if meta[:count]
+        end
+
+        # Return the total count of items.
+        def count
+
+        end
+      end
+
+      class Create < Action
+        route ''
+        http_method :post
+        aliases %i(new)
+      end
+
+      class Show < Action
+        route ->(r){ r.singular ? '' : ':%{resource}_id' }
+        http_method :get
+        aliases %i(find)
+      end
+
+      class Update < Action
+        route ->(r){ r.singular ? '' : ':%{resource}_id' }
+        http_method :put
+      end
+
+      class Delete < Action
+        route ->(r){ r.singular ? '' : ':%{resource}_id' }
+        http_method :delete
+        aliases %i(destroy)
+      end
+    end
+  end
+end

data/lib/haveapi/actions/paginable.rb

@@ -0,0 +1,12 @@
+module HaveAPI::Actions
+  module Paginable
+    def self.included(action)
+      action.input do
+        integer :offset, label: 'Offset', desc: 'The offset of the first object',
+                default: 0
+        integer :limit, label: 'Limit', desc: 'The number of objects to retrieve',
+                default: 25
+      end
+    end
+  end
+end

data/lib/haveapi/api.rb

@@ -0,0 +1,66 @@
+module HaveAPI
+  # Return a list of all resources or yield them if block is given.
+  def self.resources(module_name) # yields: resource
+    ret = []
+
+    module_name.constants.select do |c|
+      obj = module_name.const_get(c)
+
+      if obj.obj_type == :resource
+        if block_given?
+          yield obj
+        else
+          ret << obj
+        end
+      end
+    end
+
+    ret
+  end
+
+  # Iterate through all resources and return those for which yielded block
+  # returned true.
+  def self.filter_resources(module_name)
+    ret = []
+
+    resources(module_name) do |r|
+      ret << r if yield(r)
+    end
+
+    ret
+  end
+
+  # Return list of resources for version +v+.
+  def self.get_version_resources(module_name, v)
+    filter_resources(module_name) do |r|
+      r.version.is_a?(Array) ? r.version.include?(v) : (r.version == v || r.version == :all)
+    end
+  end
+
+  # Return a list of all API versions.
+  def self.get_versions(module_name)
+    ret = []
+
+    resources(module_name) do |r|
+      ret << r.version unless ret.include?(r.version)
+    end
+
+    ret
+  end
+
+  def self.set_module_name(name)
+    @module_name = name
+  end
+
+  def self.module_name
+    @module_name
+  end
+
+  def self.set_default_authenticate(chain)
+    @default_auth = chain
+  end
+
+  def self.default_authenticate
+    @default_auth
+  end
+end

data/lib/haveapi/authentication/base.rb

@@ -0,0 +1,37 @@
+module HaveAPI
+  module Authentication
+    # Base class for authentication providers.
+    class Base
+      attr_accessor :name, :resources
+
+      def initialize(server, v)
+        @server = server
+        @version = v
+        setup
+      end
+
+      # Reimplement this method in your authentication provider.
+      # +request+ is passed directly from Sinatra.
+      def authenticate(request)
+
+      end
+
+      # Reimplement to describe provider.
+      def describe
+        {}
+      end
+
+      protected
+      # Called during API mount.
+      def setup
+
+      end
+
+      # Immediately return from authentication chain.
+      # User is not allowed to authenticate.
+      def deny
+        throw(:return)
+      end
+    end
+  end
+end