the_garage 2.0.0

data/lib/garage/nested_field_query.rb

@@ -0,0 +1,183 @@
+module Garage
+  module NestedFieldQuery
+    class InvalidQuery < StandardError; end
+    class InvalidData < StandardError; end
+
+    class Parser
+      def self.parse(*args)
+        new.parse(*args)
+      end
+
+      def parse(given_query, indent = nil)
+        parse_recurse(given_query.to_s.dup, indent)
+      end
+
+    private
+
+      def parse_recurse(query, indent)
+        result = []
+        current = nil
+        while query.sub!(/^(?:\s*([\w\.\*]+)|(,)|(\[)|(\]))/, '')
+          if $1
+            current = $1.to_s
+          elsif $2
+            if current
+              result << current
+              current = nil
+            else
+              raise InvalidQuery, "Expected field name: #{query}"
+            end
+          elsif $3
+            if current
+              current = { current => parse_recurse(query, 1) }
+            else
+              raise InvalidQuery, "'[' should come after field: #{query}"
+            end
+          elsif $4
+            if indent
+              if current
+                result << current
+                return merge(result)
+              else
+                raise InvalidQuery, "']' should be after '[field': #{query}"
+              end
+            else
+              raise InvalidQuery, "']' should be after '[field': #{query}"
+            end
+          end
+        end
+
+        if current
+          result << current
+        else
+          raise InvalidQuery, "premature end of query"
+        end
+
+        merge(result)
+      end
+
+      def merge(result)
+        hash = Hash.new
+        result.each do |res|
+          if res.is_a?(Hash)
+            hash.merge!(res)
+          else
+            hash[res] = nil
+          end
+        end
+        hash
+      end
+    end
+
+    class Builder
+      def self.build(*args)
+        new.build(*args)
+      end
+
+      def build(arg)
+        val = ''
+
+        case arg
+        when Hash
+          val << arg.map { |key, value|
+            if value.nil?
+              key
+            else
+              "#{key}[#{build(value)}]"
+            end
+          }.join(',')
+        when Symbol, String
+          val << arg.to_s
+        else
+          raise InvalidData, "Can't encode data type: #{arg.class}"
+        end
+
+        val
+      end
+    end
+
+    class DefaultSelector
+      # kinda NullObject pattern
+
+      # Doesn't specify anything - includes/excludes returns both false :)
+
+      def includes?(field)
+        false
+      end
+
+      def excludes?(field)
+        false
+      end
+
+      def [](name)
+        DefaultSelector.new
+      end
+
+      def canonical
+        ''
+      end
+    end
+
+    class FullSelector < DefaultSelector
+      def includes?(field)
+        true
+      end
+
+      def excludes?(field)
+        false
+      end
+
+      def [](name)
+        FullSelector.new
+      end
+
+      def canonical
+        '*'
+      end
+    end
+
+    class Selector
+      # includes eager loading
+
+      def self.build(fields)
+        if fields.present?
+          build_parsed(Parser.parse(fields))
+        else
+          NestedFieldQuery::DefaultSelector.new
+        end
+      end
+
+      def self.build_parsed(fields)
+        if fields.key? '*'
+          FullSelector.new
+        else
+          self.new(fields)
+        end
+      end
+
+      def initialize(fields = {})
+        @fields = fields
+      end
+
+      def [](name)
+        if @fields[name].nil?
+          DefaultSelector.new
+        else
+          Selector.build_parsed(@fields[name])
+        end
+      end
+
+      def canonical
+        Builder.build(@fields)
+      end
+
+      def includes?(field)
+        @fields.has_key?(field)
+      end
+
+      def excludes?(field)
+        !@fields.has_key?('__default__') && !@fields.has_key?(field)
+      end
+    end
+  end
+end

data/lib/garage/optional_response_body_responder.rb

@@ -0,0 +1,16 @@
+module Garage::OptionalResponseBodyResponder
+  protected
+
+  def api_behavior(*)
+    case
+    when put? && options[:put] && options[:put][:body]
+      display resource, status: options[:put][:status] || :ok
+    when patch? && options[:patch] && options[:patch][:body]
+      display resource, status: options[:patch][:status] || :ok
+    when delete? && options[:delete] && options[:delete][:body]
+      display resource, status: options[:delete][:status] || :ok
+    else
+      super
+    end
+  end
+end

data/lib/garage/paginating_responder.rb

@@ -0,0 +1,113 @@
+module Garage
+  module PaginatingResponder
+    def display(resource, *args)
+      if @options[:paginate]
+        resource = paginate resource
+      end
+      super(resource, *args)
+    end
+
+    def max_per_page=(count)
+      @max_per_page = count
+    end
+
+    def reveal_total!
+      @options.delete(:hard_limit)
+    end
+
+    private
+
+    def distinct?
+      !!@options[:distinct_by]
+    end
+
+    def hide_total?
+      !!@options[:hard_limit]
+    end
+
+    def hard_limit
+      @options[:hard_limit]
+    end
+
+    def max_per_page
+      @options[:max_per_page] || @max_per_page || 100
+    end
+
+    def set_total_count(rs, per_page)
+      if hard_limit
+        limit = hard_limit
+        rs.instance_variable_set(:@total_count, limit)
+      end
+    end
+
+    def total_count(rs)
+      if distinct?
+        rs.total_count(@options[:distinct_by], distinct: true)
+      else
+        rs.total_count
+      end
+    end
+
+    def paginate(rs)
+      @options[:hard_limit] ||= 1000 if @options[:hide_total] # backward compat for hide_total
+
+      per_page = [ max_per_page, (controller.params[:per_page] || @options[:per_page] || 20).to_i ].min
+
+      rs = rs.page(controller.params[:page] || 1).per(per_page)
+
+      set_total_count(rs, per_page)
+
+      unless hide_total?
+        controller.response.headers['X-List-TotalCount'] = total_count(rs).to_s
+      end
+
+      # FIXME construct_links must be called after calling rs.total_count to avoid invalid count cache
+      construct_links(rs, per_page)
+
+      if hide_total?
+        if rs.offset_value > hard_limit
+          rs = []
+        elsif rs.offset_value + per_page > hard_limit
+          rs = rs.slice 0, (hard_limit - rs.offset_value) # becomes Array here, and hope it's ok
+        end
+      end
+
+      rs
+    end
+
+    def construct_links(rs, per_page)
+      build_link_hash(rs, links={})
+      add_link_header(links, per_page) unless links.empty?
+    end
+
+    def build_link_hash(rs, links)
+      unless rs.first_page?
+        links[:first] = 1
+        links[:prev]  = rs.current_page - 1
+      end
+
+      if rs.current_page < rs.total_pages
+        links[:next] = rs.current_page + 1
+      end
+
+      unless rs.last_page? || hide_total?
+        links[:last] = rs.total_pages
+      end
+    end
+
+    def build_path_for(params)
+      parameters = controller.request.query_parameters.merge(params).tap {|p| p.delete(:access_token) }
+      "#{controller.request.path}?#{parameters.to_query}"
+    end
+
+    def add_link_header(links, per_page)
+      headers = []
+      links.each do |rel, page|
+        url = build_path_for(:page => page, :per_page => per_page)
+        headers << "<#{url}>; rel=\"#{rel}\"; page=\"#{page}\""
+      end
+      controller.response.headers['Link'] = headers.join ', '
+    end
+  end
+end
+

data/lib/garage/permission.rb

@@ -0,0 +1,13 @@
+module Garage
+  class Permission
+    attr_accessor :user, :action
+
+    def initialize(*args)
+      @user, @action, @perm = *args
+    end
+
+    def allowed?
+      @perm == :ok
+    end
+  end
+end

data/lib/garage/permissions.rb

@@ -0,0 +1,75 @@
+# Public: represents permissions of the current request user against
+# the resource and resource class.
+#
+# Examples
+#
+#   class Post
+#     include Garage::Authorizable
+#
+#     def build_permissions(perms, other)
+#       perms.permits! :read
+#       perms.permits! :write if owner == other
+#     end
+#
+#     def self.build_permissions(perms, other, target)
+#       if target[:user]
+#         perms.permits! :read, :write if target[:user] == other
+#       else
+#         perms.permits! :read, :write
+#       end
+#     end
+#   end
+require "garage/permission"
+
+module Garage
+  class Permissions
+    attr_accessor :user, :resource_class
+
+    def initialize(user, resource_class, permissions = { read: :forbidden, write: :forbidden })
+      @user = user
+      @resource_class = resource_class
+      @perms = permissions
+    end
+
+    def authorize!(action)
+      exists?          or raise PermissionError.new(user, action, resource_class, :not_found)
+      permits?(action) or raise PermissionError.new(user, action, resource_class, :forbidden)
+    end
+
+    def for(action)
+      Permission.new(@user, action, @perms[action])
+    end
+
+    def deleted!
+      @perms[:deleted] = true
+    end
+
+    def exists?
+      !@perms[:deleted]
+    end
+
+    def permits!(*actions)
+      actions.each do |action|
+        @perms[action] = :ok
+      end
+    end
+
+    def forbids!(*actions)
+      actions.each do |action|
+        @perms[action] = :forbidden
+      end
+    end
+
+    def permits?(action)
+      self.for(action).allowed?
+    end
+
+    def readable?
+      permits? :read
+    end
+
+    def writable?
+      permits? :write
+    end
+  end
+end

data/lib/garage/representer.rb

@@ -0,0 +1,214 @@
+module Garage::Representer
+  attr_accessor :params, :representer_attrs, :partial, :selector
+
+  def partial?
+    @partial
+  end
+
+  def render_hash(options={})
+    obj = {}
+    representer_attrs.each do |definition|
+      if definition.options[:if]
+        next unless definition.options[:if].call(self, options[:responder])
+      end
+
+      if definition.respond_to?(:encode)
+        next unless handle_definition?(selector, definition, options)
+        obj[definition.name] = definition.encode(self, options[:responder], selector[definition.name])
+      else
+        next if selector.excludes?('_links')
+        obj['_links'] ||= {}
+        obj['_links'][definition.rel.to_s] = { 'href' => definition.pathify(self) }
+      end
+    end
+    obj
+  end
+
+  def handle_definition?(selector, definition, options)
+    if definition.requires_select?
+      # definition is not selected by default - it's opt-in
+      selector.includes?(definition.name) && definition.selectable?(self, options[:responder])
+    else
+      # definition is selected by default - it's opt-out
+      !selector.excludes?(definition.name)
+    end
+  end
+
+  def default_url_options
+    @default_url_options ||= {}
+  end
+
+  def represent!
+    self.representer_attrs ||= []
+    self.representer_attrs += self.class.representer_attrs
+  end
+
+  def self.representers
+    @representers ||= []
+  end
+
+  def resource_class
+    self.class
+  end
+
+  def to_resource
+    self
+  end
+
+  def link_path_for(rel)
+    represent! unless representer_attrs
+    representer_attrs.grep(Link).find { |link| link.rel === rel }.try(:pathify, self)
+  end
+
+  def self.included(base)
+    self.representers << base
+
+    base.class_eval do
+      if Rails.application
+        include Rails.application.routes.url_helpers
+      end
+      extend ClassMethods
+    end
+  end
+
+  module ClassMethods
+    attr_writer :representer_attrs
+
+    def inherited(child)
+      super
+      child.representer_attrs = self.representer_attrs.clone
+    end
+
+    def representer_attrs
+      @representer_attrs ||= []
+    end
+
+    def property(name, options={})
+      representer_attrs << Definition.new(name, options)
+    end
+
+    def link(rel, options={}, &block)
+      representer_attrs << Link.new(rel, options, block)
+    end
+
+    def collection(name, options={})
+      representer_attrs << Collection.new(name, options)
+    end
+
+    def oauth_scope(scope)
+      ->(resource, responder){
+        # FIXME: this only works with User resource for now
+        # partial representation will not render request scope-specific fields for better caching
+        !resource.partial? && responder.controller.requested_by?(resource) && responder.controller.has_scope?(scope)
+      }
+    end
+
+    def accessible(*args)
+      ->(resource, responder){
+        responder.controller.allow_access?(*args)
+      }
+    end
+
+    # represents the representer's schema in JSON format
+    def metadata
+      {:definitions => representer_attrs.grep(Definition).map {|definition| definition.name},
+       :links => representer_attrs.grep(Link).map {|link| link.options[:as] ? {link.rel => {'as' => link.options[:as]}} : link.rel}
+      }
+    end
+
+    def param(*keys)
+      keys.each {|key| params << key }
+    end
+
+    def params
+      @params ||= []
+    end
+  end
+
+  class NonEncodableValue < StandardError;  end
+
+  class Definition
+    attr_reader :options
+
+    def initialize(name, options={})
+      @name = name
+      @options = options
+    end
+
+    def requires_select?
+      @options[:selectable]
+    end
+
+    def selectable?(*args)
+      if boolean?(@options[:selectable])
+        @options[:selectable]
+      else
+        @options[:selectable].call(*args)
+      end
+    end
+
+    def name
+      (@options[:as] || @name).to_s
+    end
+
+    def encode(object, responder, selector = nil)
+      value = object.send(@name)
+      encode_value(value, responder, selector)
+    end
+
+    def encode_value(value, responder, selector)
+      if !value.nil? && value.respond_to?(:represent!)
+        responder.encode_to_hash(value, partial: true, selector: selector)
+      elsif primitive?(value)
+        value
+      else
+        raise NonEncodableValue, "#{value.class} can not be encoded directly. Forgot to include Garage::Representer?"
+      end
+    end
+
+    def primitive?(value)
+      [
+        ActiveSupport::TimeWithZone,
+        Date,
+        Time,
+        Bignum,
+        Fixnum,
+        Float,
+        Hash,
+        Array,
+        String,
+        NilClass,
+        TrueClass,
+        FalseClass,
+        Symbol,
+      ].any? {|k| value.is_a?(k) }
+    end
+
+    private
+
+    def boolean?(value)
+      value.is_a?(TrueClass) || value.is_a?(FalseClass)
+    end
+  end
+
+  class Collection < Definition
+    def encode(object, responder, selector = nil)
+      value = object.send(@name)
+      value.map do |item|
+        encode_value(item, responder, selector)
+      end
+    end
+  end
+
+  class Link
+    attr_reader :rel, :options, :block
+
+    def initialize(rel, options, block)
+      @rel, @options, @block = rel, options, block
+    end
+
+    def pathify(representer)
+      representer.instance_exec(&@block)
+    end
+  end
+end