apes 1.0.0

data/lib/apes/concerns/response.rb

@@ -0,0 +1,74 @@
+#
+# This file is part of the apes gem. Copyright (C) 2016 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Apes
+  module Concerns
+    # JSON API response handling module.
+    module Response
+      attr_accessor :included
+
+      # Returns the template to use to render a object.
+      #
+      # @param object [Object] The object to render.
+      # @return [String] The template to use.
+      def response_template_for(object)
+        return @object_template if @object_template
+        object = object.first if object.respond_to?(:first)
+        object.class.name.underscore.gsub("/", "_")
+      end
+
+      # Returns the metadata for the current response.
+      #
+      # @param default [Object] Fallback data if nothing is found.
+      # @return [HashWithIndifferentAccess|Object|Nil] The metadata for the current response.
+      def response_meta(default = nil)
+        @meta || default || HashWithIndifferentAccess.new
+      end
+
+      # Returns the data for the current response.
+      #
+      # @param default [Object] Fallback data if nothing is found.
+      # @return [HashWithIndifferentAccess|Object|Nil] The data for the current response.
+      def response_data(default = nil)
+        @data || default || HashWithIndifferentAccess.new
+      end
+
+      # Returns the linked objects for the current response.
+      #
+      # @param default [Object] Fallback data if nothing is found.
+      # @return [HashWithIndifferentAccess|Object|Nil] The linked objects for the current response.
+      def response_links(default = nil)
+        @links || default || HashWithIndifferentAccess.new
+      end
+
+      # Returns the included (side-loaded) objects for the current response.
+      #
+      # @param default [Object] Fallback data if nothing is found.
+      # @return [HashWithIndifferentAccess|Object|Nil] The included objects for the current response.
+      def response_included(default = nil)
+        controller.included || default || HashWithIndifferentAccess.new
+      end
+
+      # Adds an object to the included (side-load) set.
+      #
+      # @param object [Object] The object to include.
+      # @param template [String] The template to use for rendering.
+      # @return [HashWithIndifferentAccess] A hash of objects to include. Keys are a template:id formatted strings, values are `[object, template]` pairs.
+      def response_include(object, template = nil)
+        controller.included ||= HashWithIndifferentAccess.new
+        controller.included[sprintf("%s:%s", response_template_for(object), object.to_param)] = [object, template]
+        controller.included
+      end
+
+      # Serializes a timestamp.
+      #
+      # @param timestamp [DateTime] The timestamp to serialize.
+      # @return [String] The serialized timestamp.
+      def response_timestamp(timestamp)
+        timestamp.safe_send(:strftime, "%FT%T.%L%z")
+      end
+    end
+  end
+end

data/lib/apes/controller.rb

@@ -0,0 +1,77 @@
+#
+# This file is part of the apes gem. Copyright (C) 2016 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Apes
+  # A ready to use controller for JSON API applications.
+  #
+  # @attribute [r] current_account
+  #   @return [Object] The current account making the request
+  # @attribute [r] cursor
+  #   @return [Apes::PaginationCursor] The pagination cursor for this request.
+  # @attribute [r] request_cursor
+  #   @return [Apes::PaginationCursor] The original pagination cursor sent from the client.
+  class Controller < ActionController::API
+    include ActionController::ImplicitRender
+    include ActionView::Layouts
+    include Apes::Concerns::Request
+    include Apes::Concerns::Response
+    include Apes::Concerns::Pagination
+    include Apes::Concerns::Errors
+
+    layout "general"
+    before_filter :request_handle_cors
+    before_filter :request_validate
+
+    attr_reader :current_account, :cursor, :request_cursor
+
+    # Exception handling
+    rescue_from Exception, with: :error_handle_exception
+    # This allows to avoid to declare all the views
+    rescue_from ActionView::MissingTemplate, with: :render_default_views
+
+    # Returns the default URL options for this request.
+    # It ensures that the host is always included and that is set properly in development mode.
+    #
+    # @return [Hash] Default URL options for the request.
+    def default_url_options
+      rv = {only_path: false}
+      rv = {host: request_source_host} if Apes::RuntimeConfiguration.development?
+      rv
+    end
+
+    # Tiny handle to handle CORS OPTIONS requests. It just renders nothing as headers are handle in Apes::Concerns::Response module.
+    #
+    # To enable this route, add the following to the routes.rb:
+    #
+    #     # This is to enable AJAX cross domain
+    #     match '*path', to: 'application#handle_cors', via: :options
+    def handle_cors
+      render(nothing: true, status: :no_content)
+    end
+
+    # Default handler to render errors.
+    #
+    # @param status [Symbol|Fixnum] The HTTP error code to return.
+    # @param errors [Array] The list of occurred errors.
+    def render_error(status, errors)
+      @errors = errors
+      status_code = status.is_a?(Fixnum) ? status : Rack::Utils::SYMBOL_TO_STATUS_CODE.fetch(status.to_sym, 500)
+      render("errors/#{status_code}", status: status)
+    end
+
+    private
+
+    # :nodoc:
+    def render_default_views(exception)
+      if defined?(@objects)
+        render "/collection"
+      elsif defined?(@object)
+        render "/object"
+      else
+        error_handle_exception(exception)
+      end
+    end
+  end
+end

data/lib/apes/errors.rb

@@ -0,0 +1,38 @@
+#
+# This file is part of the apes gem. Copyright (C) 2016 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Apes
+  # Error used by the framework.
+  module Errors
+    # The base error.
+    class BaseError < RuntimeError
+      attr_reader :details
+
+      # Creates a new error.
+      #
+      # @param details [Object] The details of this error.
+      def initialize(details = nil)
+        super("")
+        @details = details
+      end
+    end
+
+    # Error raised when the request is not compliant with JSON API specification.
+    class BadRequestError < BaseError
+    end
+
+    # Error raised when the sent data is not valid.
+    class InvalidDataError < BaseError
+    end
+
+    # Error raised when the sent data is not missing.
+    class MissingDataError < BaseError
+    end
+
+    # Error raised when provided authentication is invalid.
+    class AuthenticationError < RuntimeError
+    end
+  end
+end

data/lib/apes/model.rb

@@ -0,0 +1,94 @@
+#
+# This file is part of the apes gem. Copyright (C) 2016 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Apes
+  # Some utility extensions to ActiveModel.
+  module Model
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Find a object by using the UUID, a handle or model specific definitions (defined using SECONDARY_KEY or SECONDARY_QUERY constants).
+      # Raise exception when nothing is found.
+      #
+      # @param id [Object] The value to find.
+      # @return [Object] The first found model.
+      def find_with_any!(id)
+        if id =~ Validators::UuidValidator::VALID_REGEX
+          find(id)
+        elsif defined?(self::SECONDARY_KEY)
+          find_by!(self::SECONDARY_KEY => id)
+        elsif defined?(self::SECONDARY_QUERY)
+          find_by!(self::SECONDARY_QUERY, {id: id})
+        else
+          find_by!(handle: id)
+        end
+      end
+
+      # Find a object by using the UUID, a handle or model specific definitions (defined using SECONDARY_KEY or SECONDARY_QUERY constants).
+      #
+      # @param id [Object] The value to find.
+      # @return [Object] The first found model.
+      def find_with_any(id)
+        find_with_any!(id)
+      rescue ActiveRecord::RecordNotFound
+        nil
+      end
+
+      # Performs a search on the model.
+      #
+      # @param params [Hash] The list of params for the query.
+      # @param query [ActiveRecord::Relation|NilClass] A model query to further scope, if any.
+      # @param fields [Array] The model fields where to perform search on.
+      # @param start_only [Boolean] Whether only match that starts with the searched value rather than just containing it.
+      # @param parameter [Symbol|NilClass] The field in `params` which contains the value to search. Will fallback to `params[:filter][:query]` (using `.dig`).
+      # @param placeholder [Symbol] The placeholder to use in prepared statement. Useful to avoid collisions. Default is `query`.
+      # @param method [Symbol] The operator to use for searching. Everything different from `or` will fallback to `and`.
+      # @param case_sensitive [Boolean] Whether to perform case sensitive search. Default is `false`.
+      # @return [ActiveRecord::Relation] A query relation object.
+      def search(params: {}, query: nil, fields: ["name"], start_only: false, parameter: nil, placeholder: :query, method: :or, case_sensitive: false)
+        query ||= where({})
+        value = parameter ? params[parameter] : params.dig(:filter, :query)
+        return query if value.blank?
+
+        value = "#{value}%"
+        value = "%#{value}" unless start_only
+
+        method = method.to_s == "or" ? " OR " : " AND "
+        operator = case_sensitive ? "LIKE" : "ILIKE"
+
+        sql = fields.map { |f| "#{f} #{operator} :#{placeholder}" }.join(method)
+        query.where(sql, {placeholder => value})
+      end
+    end
+
+    # A list of manually managed errors for the model.
+    #
+    # @return [ActiveModel::Errors] A list of manually managed errors for the model.
+    def additional_errors
+      @additional_errors ||= ActiveModel::Errors.new(self)
+    end
+
+    # Perform validations on the model and makes sure manually added errors are included.
+    def run_validations!
+      errors.messages.merge!(additional_errors.messages)
+      super
+    end
+
+    # A list of automatically and manually added errors for the model.
+    #
+    # @return [ActiveModel::Errors] A list of automatically and manually added errors for the model.
+    def all_validation_errors
+      additional_errors.each do |field, error|
+        errors.add(field, error)
+      end
+
+      errors.each do |field|
+        errors[field].uniq!
+      end
+
+      errors
+    end
+  end
+end

data/lib/apes/pagination_cursor.rb

@@ -0,0 +1,152 @@
+#
+# This file is part of the apes gem. Copyright (C) 2016 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Apes
+  # A cursor that can be sent to the client, received unmodified and retrieved later to paginate results.
+  #
+  # @attribute value
+  #   @return [String] The value obtain from previous pagination. It can either be the value of the first or last element in previous iteration.
+  # @attribute use_offset
+  #   @return [Boolean] Whether to use offset based pagination rather than collection fields values.
+  # @attribute direction
+  #   @return [IO|String] Which page to get in this iteration.
+  # @attribute size
+  #   @return [IO|String] The size of the pagination page.
+  class PaginationCursor
+    # The default size of a pagination page.
+    DEFAULT_SIZE = 25
+
+    # Format to serialize timestamp when using them for pagination.
+    TIMESTAMP_FORMAT = "%FT%T.%6N%z".freeze
+
+    attr_accessor :value, :use_offset, :direction, :size
+
+    # Creates a new cursor.
+    #
+    # @param params [Hash] The request parameters.
+    # @param field [Symbol] The parameters field where to lookup for the serialized cursor.
+    # @param count_field [Symbol] The parameters field where to lookup for the overriding cursor size.
+    # @return [Apes::PaginationCursor] A new cursor instance.
+    def initialize(params = {}, field = :page, count_field = :count)
+      begin
+        payload = JWT.decode(params[field], jwt_secret, true, {algorithm: "HS256", verify_aud: true, aud: "pagination"}).dig(0, "sub")
+
+        extract_payload(payload)
+      rescue
+        default_payload
+      end
+
+      # Sanitization
+      sanitize(count_field, params)
+    end
+
+    # Get the operator (`>` or `<`) for the query according to the direction and the provided ordering.
+    #
+    # @param order [Symbol] The order to use.
+    # @return [String] The operator to use for the query.
+    def operator(order)
+      if direction == "next"
+        order == :asc ? ">" : "<" # Descending order means newer results first
+      else
+        order == :asc ? "<" : ">" # Descending order means newer results first
+      end
+    end
+
+    # Verifies whether a specific page might exist for the given collection.
+    #
+    # @param page [String] The page to check. It can be `first`, `next`, `prev` or `previous`.
+    # @param collection [Enumerable] The collection to analyze.
+    # @return [Boolean] Returns `true` if the page might exist for the collection, `false` otherwise.
+    def might_exist?(page, collection)
+      case page.to_s
+      when "first" then true
+      when "next" then collection.present?
+      else value.present? && collection.present? # Previous
+      end
+    end
+
+    # Serializes the cursor to send it to the client.
+    #
+    # @param collection [Enumerable] The collection to analyze.
+    # @param page [String] The page to return. It can be `first`, `next`, `prev` or `previous`.
+    # @param field [Symbol] When not using offset based pagination, the field to consider for generation.
+    # @param size [Fixnum] The number of results to advance when using offset based pagination.
+    # @param use_offset [Boolean] Whether to use offset based pagination.
+    # @return [String] The serialized cursor.
+    def save(collection, page, field: :id, size: nil, use_offset: nil)
+      size ||= self.size
+      use_offset = self.use_offset if use_offset.nil?
+      direction, value = use_offset ? update_with_offset(page, size) : update_with_field(page, collection, field)
+
+      value = value.strftime(TIMESTAMP_FORMAT) if value.respond_to?(:strftime)
+
+      JWT.encode({aud: "pagination", sub: {value: value, use_offset: use_offset, direction: direction, size: size}}, jwt_secret, "HS256")
+    end
+    alias_method :serialize, :save
+
+    private
+
+    # :nodoc:
+    def default_payload
+      @value = nil
+      @direction = "next"
+      @size = 0
+      @use_offset = false
+    end
+
+    # :nodoc:
+    def extract_payload(payload)
+      @value = payload["value"]
+      @direction = payload["direction"]
+      @size = payload["size"]
+      @use_offset = payload["use_offset"]
+    end
+
+    # :nodoc:
+    def sanitize(count_field, params)
+      @direction = "next" unless ["prev", "previous"].include?(@direction)
+      @size = params[count_field].to_integer if params[count_field].present?
+      @size = DEFAULT_SIZE if @size < 1
+    end
+
+    # :nodoc:
+    def update_with_field(type, collection, field)
+      case type.ensure_string
+      when "next"
+        direction = "next"
+        value = collection.last&.send(field)
+      when "prev", "previous"
+        direction = "previous"
+        value = collection.first&.send(field)
+      else # first
+        direction = "next"
+        value = nil
+      end
+
+      [direction, value]
+    end
+
+    # :nodoc:
+    def update_with_offset(type, size)
+      case type.ensure_string
+      when "next"
+        direction = "next"
+        value = self.value + size
+      when "prev", "previous"
+        direction = "previous"
+        value = [0, self.value - size].max
+      else # first
+        direction = "next"
+        value = nil
+      end
+
+      [direction, value]
+    end
+
+    def jwt_secret
+      Apes::RuntimeConfiguration.jwt_token
+    end
+  end
+end

data/lib/apes/runtime_configuration.rb

@@ -0,0 +1,80 @@
+#
+# This file is part of the apes gem. Copyright (C) 2016 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Apes
+  # Internal class to handle runtime configuration.
+  class RuntimeConfiguration
+    class << self
+      # Returns the root directory of apes.
+      # @return [String]
+      def root
+        Pathname.new(Gem.loaded_specs["apes"].full_gem_path).to_s
+      end
+
+      # Returns the current Rails root directory.
+      #
+      # @param default [String] The fallback if Rails configuration is invalid.
+      # @return [String] The current Rails root directory.
+      def rails_root(default = nil)
+        fetch_with_fallback(default) { Rails.root.to_s }
+      end
+
+      # Returns the current RubyGems root directory.
+      #
+      # @param default [String] The fallback if RubyGems configuration is invalid.
+      # @return [String] The current RubyGems root directory.
+      def gems_root(default = nil)
+        fetch_with_fallback(default) { Pathname.new(Gem.loaded_specs["lazier"].full_gem_path).parent.to_s }
+      end
+
+      # Returns the current Rails environment.
+      #
+      # @param default [String] The fallback environment if Rails configuration is invalid.
+      # @return [String] The the current Rails environment.
+      def environment(default = "development")
+        fetch_with_fallback(default) { Rails.env }
+      end
+
+      # Check if Rails is in development environment.
+      #
+      # @return [Boolean] `true` if Rails is in `development` environment, `false` otherwise.
+      def development?
+        environment == "development"
+      end
+
+      # Returns the JWT token used by Apes. This should be defined in the Rails secrets.yml file.
+      #
+      # @param default [String] The fallback if no valid secret is found in Rails secrets file.
+      # @return [String] The JWT token used by Apes.
+      def jwt_token(default = "secret")
+        fetch_with_fallback(default) { Rails.application.secrets.jwt }
+      end
+
+      # Returns the CORS source used by Apes. This should be defined in the Rails secrets.yml file.
+      #
+      # @param default [String] The fallback if no valid CORS source is found in Rails secrets file.
+      # @return [String] The CORS source used by Apes.
+      def cors_source(default = "localhost")
+        fetch_with_fallback(default) { Rails.application.secrets.cors_source }
+      end
+
+      # Returns a map where keys are tags and values are strftime compliant formats.
+      #
+      # @param default [String] The fallback if no valid configuration is found in Rails.
+      # @return [Hash] A object describing valid timestamps formats.
+      def timestamp_formats(default = {})
+        fetch_with_fallback(default) { Rails.application.config.timestamp_formats }
+      end
+
+      private
+
+      def fetch_with_fallback(default)
+        yield
+      rescue
+        default
+      end
+    end
+  end
+end