json_api_server 0.0.1

data/lib/json_api_server/filter_builders.rb

@@ -0,0 +1,135 @@
+module JsonApiServer # :nodoc:
+  # Base filter/query builder class. All should inherit from this class.
+  class FilterBuilder
+    # The filter attribute, i.e., filter[foo]
+    attr_reader :attr
+    # Casted value(s). If value included a common, an array of casted values.
+    attr_reader :value
+    # Instance of FilterConfig for the specific attribute/column.
+    attr_reader :config
+    # Column name in the database. Specified when the filter name in the query doesn't
+    # match the column name in the database.
+    attr_reader :column_name
+    # Can be IN, <, >, <=, etc.
+    attr_reader :operator
+
+    def initialize(attr, value, operator, config)
+      @attr = attr
+      @value = value
+      @config = config
+      @column_name = @config.column_name
+      @operator = operator
+    end
+
+    # Subclasses must implement. Can return an ActiveRecord::Relation or
+    # nil.
+    def to_query(_model)
+      raise 'subclasses should implement this method.'
+    end
+
+    protected
+
+    def full_column_name(model)
+      "\"#{model.table_name}\".\"#{column_name}\""
+    end
+
+    # Delegate to protected method ActiveRecord::Base.sanitize_sql.
+    # def sanitize_sql(condition)
+    #   ActiveRecord::Base.send(:sanitize_sql, condition)
+    # end
+
+    # For queries where wildcards are appropriate. Adds wildcards
+    # based on filter's configs.
+    def add_wildcards(value)
+      return value unless value.present?
+
+      case config.wildcard
+      when :left
+        return "%#{value}"
+      when :right
+        return "#{value}%"
+      when :both
+        return "%#{value}%"
+      else # none by default
+        return value
+      end
+    end
+  end
+
+  # Query equality builder. i.e.. where(foo: 'bar').
+  class SqlEql < FilterBuilder
+    def to_query(model)
+      model.where("#{full_column_name(model)} = ?", value)
+    end
+  end
+
+  # Query comparison builder, .i.e., where('id > ?', '22').
+  class SqlComp < FilterBuilder
+    def self.allowed_operators
+      ['=', '<', '>', '>=', '<=', '!=']
+    end
+
+    def to_query(model)
+      if self.class.allowed_operators.include?(operator)
+        model.where("#{full_column_name(model)} #{operator} ?", value)
+      end
+    end
+  end
+
+  # Query IN builder, .i.e., where('id IN (?)', [1,2,3]).
+  class SqlIn < FilterBuilder
+    def to_query(model)
+      model.where("#{full_column_name(model)} IN (?)", value)
+    end
+  end
+
+  # Query LIKE builder, .i.e., where('title LIKE ?', '%foo%').
+  # Wildcards are added based on configs. Defaults to '%<value>%'
+  class SqlLike < FilterBuilder
+    def to_query(model)
+      val = add_wildcards(value)
+      model.where("#{full_column_name(model)} LIKE ?", val)
+    end
+  end
+
+  # Query ILIKE builder, .i.e., where('title ILIKE ?', '%foo%').
+  # Wildcards are added based on configs. Defaults to '%<value>%'
+  # Postgres only. Case insensitive search.
+  class PgIlike < FilterBuilder
+    def to_query(model)
+      val = add_wildcards(value)
+      model.where("#{full_column_name(model)} ILIKE :val", val: val)
+    end
+  end
+
+  # Searches a jsonb array ['foo', 'bar'].  If multiple values passed, it performs
+  # an OR search ?|. Case sensitive search.
+  # Postgres only.
+  class PgJsonbArray < FilterBuilder
+    #--
+    # http://stackoverflow.com/questions/30629076/how-to-escape-the-question-mark-operator-to-query-postgresql-jsonb-type-in-r
+    # https://www.postgresql.org/docs/9.4/static/functions-json.html
+    #++
+    def to_query(model)
+      model.where("#{full_column_name(model)} ?| array[:name]", name: value)
+    end
+  end
+
+  # Searches a jsonb array ['foo', 'bar']. The array is returned as text. It performs an
+  # ILIKE %value%. Does not work with multiple values.
+  # Postgres only.
+  class PgJsonbIlikeArray < FilterBuilder
+    def to_query(model)
+      val = add_wildcards(value)
+      model.where("#{full_column_name(model)}::text ILIKE :name", name: val)
+    end
+  end
+
+  # Call a model singleton method to perform the query.
+  class ModelQuery < FilterBuilder
+    def to_query(model)
+      method = config.method
+      model.send(method, value) if method.present?
+    end
+  end
+end

data/lib/json_api_server/filter_config.rb

@@ -0,0 +1,71 @@
+module JsonApiServer # :nodoc:
+  # Configuration for a filter http://jsonapi.org/format/#fetching-filtering.
+  #
+  # Example filter configuration:
+  #
+  #  filter_options = [
+  #       { id: { type: 'Integer' } },
+  #       { tags: { builder: :pg_jsonb_ilike_array } },
+  #       :body,
+  #       { title: { wildcard: :right }},
+  #       { search: { builder: :model_query, method: :search } },
+  #       { created: { col_name: :created_at, type: 'DateTime' } }
+  #   ]
+  #
+  class FilterConfig
+    # Attribute used in queries. i.e., /path?filter[foo]=bar => foo
+    attr_reader :attr
+    # (optional) If the fitler name is not the same as the database column name,
+    # map it. i.e., map :created to :created_at.
+    # { created: { col_name: :created_at, type: 'DateTime' } }
+    attr_reader :column_name
+    # (optional) Data type. Specify data type class as string. i.e., 'String',
+    # 'DateTime', 'Time', 'BigDecimal', etc. Defaults to 'String'.
+    attr_reader :type
+    # (optional) Symbol - the builder class to use for LIKE queries. Defaults
+    # to :sql_like if not specified.
+    attr_reader :like
+    # (optional) Symbol - the builder class to use for IN queries. Defaults to
+    # :sql_in if not specified.
+    attr_reader :in
+    # (optional) Symbol - the builder class to use for '=', '<', '>', '>=', '<=', '=',
+    # '!<', '!>', '<>' queries. Defaults to :sql_comparison.
+    attr_reader :comparison
+    # (optional) Symbol - the builder class to use for all other queries. Defaults to
+    # :sql_eql.
+    attr_reader :default
+    # (optional) Symbol - the builder class to use for all queries for the attribute.
+    attr_reader :builder
+    # (optional) Use with ModelQuery builder which calls a class method on the model.
+    attr_reader :method
+    # (optional) Symbol - :left, :right or :none. Defaults to wildcarding beginning
+    # end of string, i.e., "%#{value}%",
+    attr_reader :wildcard
+
+    def initialize(config)
+      if config.respond_to?(:keys)
+        # i.e, c.filter_options = { permitted: [{created: {attr: :created_at, type: DateTime}}] }
+        key, value = config.first
+        @attr = key
+        @column_name = value[:col_name] || @attr
+        @type = value[:type] || self.class.default_type
+        @like = value[:like]
+        @in = value[:in]
+        @comparison = value[:comparison]
+        @default = value[:default]
+        @builder = value[:builder]
+        @wildcard = value[:wildcard]
+        @method = value[:method]
+      else
+        # i.e., c.filter_options = { permitted: [:body] }
+        @attr = @column_name = config
+        @type = self.class.default_type
+      end
+    end
+
+    # Default data type is String unless a filter config specifies.
+    def self.default_type
+      String
+    end
+  end
+end

data/lib/json_api_server/filter_parser.rb

@@ -0,0 +1,88 @@
+module JsonApiServer # :nodoc:
+  # Returns query_builder class for key specified.
+  def self.filter_builder(key)
+    JsonApiServer.configuration.filter_builders[key]
+  end
+  # Takes a filter param and associated config and creates an
+  # ActiveRecord::Relation query which can be merged into a
+  # master query. Part of http://jsonapi.org/recommendations/#filtering.
+  class FilterParser
+    # The filter name, i.e., :id, :title
+    attr_reader :attr
+    # The original filter value.
+    attr_reader :value
+    # Original value cast to the appropriate data type.
+    attr_reader :casted_value
+    # Model class or ActiveRecord_Relation. Queries are built using this model.
+    attr_reader :model
+    # Instance of FilterConfig for the filter.
+    attr_reader :config
+    # Query operator if one applies. i.e., IN, =, <, >, >=, <=, !=
+    attr_reader :operator
+
+    # parameters:
+    #   - attr (String) - filter name as it appears in the url.
+    #                    i.e., filter[tags]=art,theater => tags
+    #   - value (String) - value from query, i.e., 'art,theater'
+    #   - model (class or class name) - Model class or class name.
+    #                    i.e., User or 'User'.
+    #   - config (instance of FilterConfig) - filter config for the filter.
+    def initialize(attr, value, model, config)
+      @attr = attr
+      @value = value
+      @model = model.is_a?(Class) ? model : model.constantize
+      @config = config
+      parse
+    end
+
+    # Converts filter into an ActiveRecord::Relation where query which
+    # can be merged with other queries.
+    def to_query
+      return nil if config.nil? # not a whitelisted attr
+      klass = JsonApiServer.filter_builder(builder_key) || raise("Query builder '#{builder_key}' doesn't exist.")
+      builder = klass.new(attr, casted_value, operator, config)
+      builder.to_query(@model)
+    end
+
+    protected
+
+    def builder_key
+      return config.builder if config.builder.present?
+
+      case operator
+      when 'IN'
+        config.in || configuration.default_in_builder
+      when '*'
+        config.like || configuration.default_like_builder
+      when *SqlComp.allowed_operators
+        config.comparison || configuration.default_comparison_builder
+      else
+        config.default || configuration.default_builder
+      end
+    end
+
+    # Value, operator, or specified class.
+    def parse
+      if value.include?(',')
+        arr = value.split(',')
+        arr.map!(&:strip)
+        @casted_value = cast(arr, config.type)
+        @operator = 'IN'
+      else
+        value =~ /\A(!?[<|>]?=?\*?)(.+)/
+        # JsonApiServer.logger.debug("VALUE IS #{Regexp.last_match(2)}")
+        # JsonApiServer.logger.debug("CONFIG.TYPE IS #{config.type}")
+        @casted_value = cast(Regexp.last_match(2), config.type)
+        @operator = Regexp.last_match(1)
+      end
+    end
+
+    def cast(value, type)
+      JsonApiServer::Cast.to(value, type)
+    end
+
+    def configuration
+      JsonApiServer.configuration
+    end
+  end
+end

data/lib/json_api_server/include.rb

@@ -0,0 +1,158 @@
+# TODO: error message and internationalization.
+# TODO: cache permitted inclusions?
+module JsonApiServer # :nodoc:
+  # ==== Description:
+  #
+  # Handles include parameters per JSON API spec http://jsonapi.org/format/#fetching-includes.
+  #
+  # An endpoint may support an include request parameter to allow the client to
+  # customize which related resources should be returned.
+  #  ie., GET /articles/1?include=comments,comment.author,tags HTTP/1.1
+  #
+  # This class (1) whitelists include params, (2) maintains an array of
+  # permitted inclusions, and (3) generates a sub-query
+  # if eagerloading is configured for inclusions.
+  #
+  # === Usage:
+  #
+  # An inclusion request looks like:
+  #   /topics?include=author,comment.author,comments
+  #
+  # It is converted to an array of relationships:
+  #   ['author', 'comment.author', 'comments']
+  #
+  # Includes are whitelisted with a configuration that looks like:
+  #  {
+  #    {'author': -> { includes(:author) }},
+  #    {'comments': -> { includes(:comments) }},
+  #    'comment.author'
+  #  }
+  #
+  # In this example, author, comments, and comment.author are allowed includes. If
+  # an unsupported include is requested, a JsonApiServer::BadRequest exception is
+  # raised which renders a 400 error.
+  #
+  # A proc/lambda can be specified to eagerload relationships. Be careful,
+  # to date, there is no way to apply limits to :includes.
+  #
+  # ==== Example:
+  #  permitted = {
+  #    {'author': -> { includes(:author) }},
+  #    {'comments': -> { includes(:comments) }},
+  #    'comment.author'
+  #  }
+  #
+  #  # create instance
+  #  include = JsonApiServer::Include.new(request, Topic, permitted)
+  #
+  #  # merge into master query
+  #  recent_topics = Topic.recent.merge(include.query)
+  #
+  #  # use in serializers
+  #  class CommentSerializer < JsonApiServer::ResourceSerializer
+  #    def relationships
+  #      if relationship?('comment.author') # relationship? is a helper methods in serializers.
+  #        #...
+  #      end
+  #    end
+  #  end
+  #
+  # ==== Note:
+  # JsonApiServer::Builder class provides an easier way to use this class.
+  #
+  class Include
+    # ActionDispatch::Request passed in constructor.
+    attr_reader :request
+
+    # Query parameters from #request.
+    attr_reader :params
+
+    # ActiveRecord::Base model passed in constructor.
+    attr_reader :model
+
+    # Include configs passed in constructor.
+    attr_reader :permitted
+
+    # Arguments:
+    #
+    # - <tt>request</tt> - ActionDispatch::Request
+    # - <tt>model</tt> (ActiveRecord::Base) - Model to append queries to.
+    # - <tt>permitted</tt> (Array) - Permitted inclusions. To eagerload the relationship, pass a proc:
+    #
+    # ===== Example:
+    #
+    # Eagerloads author, comments, comments -> authors.
+    #
+    #  [
+    #    {'author': -> { includes(:author) }},
+    #    {'comments': -> { includes(:comments) }},
+    #    {'comments.author': -> {includes(comments: :author) }},
+    #    'publisher.addresses'
+    #  ]
+    def initialize(request, model, permitted = [])
+      @request = request
+      @model = model
+      @permitted = permitted.is_a?(Array) ? permitted : []
+      @params = request.query_parameters
+    end
+
+    # Array of whitelisted include params. Raises JsonApiServer::BadRequest if
+    # any #include_params is not whitelisted.
+    #
+    # ==== Examples
+    #
+    #   include=comments becomes ['comments']
+    #   include=comments.author,tags becomes ['comments.author', 'tags']
+    def includes
+      include_params.select { |i| config_for(i).present? }
+    end
+
+    # Array of include params from the request.
+    #
+    # ===== Examples
+    #
+    #  include=comments becomes ['comments']
+    #  include=comments.author,tags becomes ['comments.author', 'tags']
+    def include_params
+      @include_params ||= begin
+        params[:include].present? ? params[:include].split(',').map!(&:strip) : []
+      end
+    end
+
+    # Returns an ActiveRecord::Relation object (a query fragment). Returns nil
+    # if no eagerloading is configured.
+    def relation
+      @relation ||= begin
+        additions = false
+        # TODO: merge! has unexpected results.
+        frag = include_params.reduce(model.all) do |result, inclusion|
+          config = config_for(inclusion)
+          query = config.respond_to?(:keys) ? config.values.first : nil
+          unless query.nil?
+            additions = true
+            result = result.merge(query)
+          end
+          result
+        end
+        additions ? frag : nil
+      end
+    end
+
+    alias query relation
+
+    protected
+
+    # Returns config. Raises JsonApiServer::BadRequest if inclusion is not whitelisted.
+    def config_for(inclusion)
+      config = permitted.find do |v|
+        inc = inclusion.to_s
+        v.respond_to?(:keys) ? v.keys.first.to_s == inc : v.to_s == inc
+      end
+      if config.nil?
+        msg = I18n.t('json_api_server.render_400.inclusion', param: inclusion)
+        raise JsonApiServer::BadRequest, msg
+      end
+      config
+    end
+  end
+end