eluvia-base 3.37.1

data/lib/eluvia/active_record/filters_model.rb

@@ -0,0 +1,58 @@
+module Eluvia
+  module ActiveRecord
+    module FiltersModel
+      extend ::ActiveSupport::Concern
+      include Eluvia::ActiveModel::Attributes # to support xxx_attr methods
+      include Eluvia::ActiveModel::RangeAttribute # to support range_attr methods
+      include Eluvia::ActiveModel::EnumAttribute # to support enum_attr methods
+
+      included do
+        extend ::ActiveModel::Translation # to support human_attribute_name method
+      end
+
+      class_methods do
+
+        def search_fields(*fields)
+          if fields.empty?
+            @_search_fields ||= []
+          else
+            @_search_fields = fields
+          end
+        end
+
+        def _filter_attrs
+          @filter_attrs ||= {}
+        end
+
+        def filter_attrs
+          _filter_attrs.values
+        end
+
+        def filter_attr_names
+          filter_attrs.map { |fa| fa[:attr_name] }
+        end
+
+        def has_filter_attr?(attr_name)
+          _filter_attrs.key?(attr_name.to_sym)
+        end
+
+        def find_filter_attr(attr_name)
+          _filter_attrs.fetch(attr_name.to_sym, nil)
+        end
+
+        def filter_attr(attr_name, type, options = {}, &proc)
+          attr_name = attr_name.to_sym
+
+          simple_attr attr_name, type
+
+          _filter_attrs[attr_name] = {
+            attr_name: attr_name,
+            type: type,
+            options: options,
+            proc: proc
+          }
+        end
+      end
+    end
+  end
+end

data/lib/eluvia/active_record/ordering.rb

@@ -0,0 +1,110 @@
+module Eluvia
+  module ActiveRecord
+    module Ordering
+      extend ::ActiveSupport::Concern
+
+      class_methods do
+
+        def _order_attrs
+          @order_attrs ||= {}
+        end
+
+        def order_attrs
+          _order_attrs.values
+        end
+
+        def has_order_attr?(attr_name)
+          _order_attrs.key?(attr_name.to_sym)
+        end
+
+        def find_order_attr(attr_name)
+          _order_attrs.fetch(attr_name.to_sym, nil)
+        end
+
+        # Registers a virtual sortable column backed by a custom Arel/SQL expression (e.g. a
+        # correlated subquery), for values that don't map to a real column or association. Escape
+        # hatch analogous to `filter_attr` in the Filtering concern.
+        #
+        # @param attr_name [Symbol] name usable as a key in the `order_by` hash passed to `order_2`
+        # @yield returns the SQL expression (String or Arel node) to order by
+        def order_attr(attr_name, &expr_proc)
+          unless expr_proc
+            raise Eluvia::Errors::StandardError.new('order_attr requires a block returning the order expression.')
+          end
+          _order_attrs[attr_name.to_sym] = { attr_name: attr_name.to_sym, expr_proc: expr_proc }
+        end
+
+        # Adds support for ordering over related models
+        #
+        # @param order_by [Hash] Hash of column names and order directions (e.g., { 'name' => :asc, 'related_model__column' => :desc })
+        def order_2(order_by)
+          scope = all
+
+          # Collect order clauses as an array so we can mix simple hash entries with
+          # Arel.sql fragments (needed for `NULLS LAST` on LEFT-joined association columns).
+          order_clauses = []
+          order_by.each do |order_column, order_direction|
+            order_direction = order_direction.to_sym
+            msg = I18n.t('eluvia.errors.ordering.invalid_direction',
+              default: 'Invalid order direction. Allowed values are `asc` and `desc`.')
+            raise Eluvia::Errors::UnprocessableEntity.new({ "order_by__#{order_column}" => msg }) \
+              unless %i[asc desc].include?(order_direction)
+
+            if has_order_attr?(order_column)
+
+              # Custom order attr, handled with the highest priority (same as `filter_attr`)
+              expr = find_order_attr(order_column)[:expr_proc].call
+              expr_sql = expr.respond_to?(:to_sql) ? expr.to_sql : expr.to_s
+              order_clauses << Arel.sql("(#{expr_sql}) #{order_direction.to_s.upcase} NULLS LAST")
+            elsif order_column.to_s.include?('__')
+
+              # Split the column name into association and actual column name
+              split_column = order_column.to_s.split('__')
+              msg = I18n.t('eluvia.errors.ordering.invalid_definition',
+                default: 'Invalid definition for an `order by` attribute. Expecting only one `__` delimiter.')
+              raise Eluvia::Errors::UnprocessableEntity.new({ "order_by__#{order_column}" => msg }) \
+                unless split_column.length == 2
+
+              # Check if the association exists on the model
+              association_name = split_column[0].to_sym
+              reflection = self.reflect_on_association(association_name)
+              msg = I18n.t('eluvia.errors.ordering.association_not_found', default: 'Association not found.')
+              raise Eluvia::Errors::UnprocessableEntity.new({ "order_by__#{order_column}" => msg }) unless reflection
+
+              # Retrieve the table name of the associated model
+              associated_table_name = reflection.klass.table_name
+
+              # Check that the column exists on the associated model
+              column_name = split_column[1]
+              msg = I18n.t('eluvia.errors.ordering.not_found_on_association', default: 'Does not exist on association.')
+              raise Eluvia::Errors::UnprocessableEntity.new({ "order_by__#{order_column}" => msg }) \
+                unless column_name.present? && reflection.klass.column_names.include?(column_name)
+
+              # LEFT JOIN so records with a NULL FK (or no matching associated row) are kept;
+              # NULLS LAST so those rows sort to the end regardless of asc/desc direction.
+              scope = scope.left_joins(association_name)
+              order_clauses << Arel.sql(
+                "#{associated_table_name}.#{column_name} #{order_direction.to_s.upcase} NULLS LAST"
+              )
+            else
+
+              # Check that the column exists on this model
+              msg = I18n.t('eluvia.errors.ordering.not_found', default: 'Does not exist.')
+              raise Eluvia::Errors::UnprocessableEntity.new({ "order_by__#{order_column}" => msg }) \
+                unless self.column_names.include?(order_column.to_s)
+
+              # Standard column, just add it to the order clauses
+              order_clauses << { order_column => order_direction }
+            end
+          end
+
+          # Apply ordering to the collection (each clause appends to the ORDER BY chain)
+          order_clauses.each { |clause| scope = scope.order(clause) }
+
+          scope
+        end
+
+      end
+    end
+  end
+end

data/lib/eluvia/base/config.rb

@@ -0,0 +1,38 @@
+module Eluvia
+  module Base
+    module Config
+
+      # Which case paradigm the API should follow.
+      #
+      # Available values:
+      # - snake_case Uses snake case for all JSON keys in API (default).
+      # - camel_case Uses camel case for all JSON keys in API.
+      mattr_accessor :api_case
+      @@api_case = 'snake_case'
+
+      # API key recognized in x-private-api-key header. Used for server-to-server authorization in case of session_id authorization method. Also acts as secret key for JWT encoding/decoding.
+      mattr_accessor :private_api_key
+
+      # API key recognized in x-public-api-key header. Used for server-to-server authorization in case of session_id authorization method.
+      mattr_accessor :public_api_key
+
+      # Authorization method.
+      #
+      # Available values:
+      # - jwt        Uses JSON Web Tokens (JWT) in the 'authorization' or 'x-authorization' header (default).
+      # - session_id Uses session IDs in the 'session-id' header in combination with 'x-private-api-key' and 'x-public-api-key' headers.
+      mattr_accessor :authorization_method
+      @@authorization_method = 'jwt'
+
+      # Whether to use secure JWT tokens with issue time and unique identifiers. If false, JWT tokens will not have
+      # issue time and will not have unique identifiers, which can be useful for testing purposes. (default: true)
+      mattr_accessor :secure_jwt
+      @@secure_jwt = true
+
+      # UUID seed used for generating UUIDs.
+      mattr_accessor :uuid_seed
+      @@uuid_seed = '12345678-1234-1234-1234-1234567890ab'
+
+    end
+  end
+end

data/lib/eluvia/base/version.rb

@@ -0,0 +1,12 @@
+require 'json'
+
+module Eluvia
+  module Base
+    def self.version
+      path = File.expand_path('../../../version.json', __dir__)
+      file = File.read(path)
+      data = JSON.parse(file)
+      data['version']
+    end
+  end
+end

data/lib/eluvia/errors/bad_request.rb

@@ -0,0 +1,17 @@
+module Eluvia
+  module Errors
+    class BadRequest < Eluvia::Errors::StandardError
+
+      def initialize(message = nil)
+        super(
+          message || "The server cannot or will not process the request due to an apparent client error.",
+          "Bad Request",
+          400,
+          nil,
+          false
+        )
+      end
+
+    end
+  end
+end

data/lib/eluvia/errors/forbidden.rb

@@ -0,0 +1,17 @@
+module Eluvia
+  module Errors
+    class Forbidden < Eluvia::Errors::StandardError
+
+      def initialize(message = nil)
+        super(
+          message || "The request contained valid data and was understood by the server, but the server is refusing action.",
+          "Forbidden",
+          403,
+          nil,
+          false
+        )
+      end
+
+    end
+  end
+end

data/lib/eluvia/errors/not_found.rb

@@ -0,0 +1,17 @@
+module Eluvia
+  module Errors
+    class NotFound < Eluvia::Errors::StandardError
+
+      def initialize(message = nil)
+        super(
+          message || "The requested resource could not be found but may be available in the future.",
+          "Not Found",
+          404,
+          nil,
+          false
+        )
+      end
+
+    end
+  end
+end

data/lib/eluvia/errors/service_unavailable.rb

@@ -0,0 +1,17 @@
+module Eluvia
+  module Errors
+    class ServiceUnavailable < Eluvia::Errors::StandardError
+
+      def initialize(message = nil)
+        super(
+          message || "The server cannot handle the request (because it is overloaded or down for maintenance).",
+          "Service Unavailable",
+          503,
+          nil,
+          false
+        )
+      end
+
+    end
+  end
+end

data/lib/eluvia/errors/standard_error.rb

@@ -0,0 +1,33 @@
+module Eluvia
+  module Errors
+    class StandardError < ::StandardError
+
+      attr_reader :message, :error, :status, :source, :timestamp, :no_sentry
+
+      def initialize(message = nil, error = nil, status = nil, source = nil, no_sentry = false)
+        super(message)
+        @message = message || "We encountered unexpected error, but our developers had been already notified about it"
+        @error = error || "Internal Server Error"
+        @status = status || 500
+        @source = source
+        @timestamp = Time.current
+        @no_sentry = no_sentry
+      end
+
+      def to_h
+        {
+          message: message,
+          error: error,
+          status: status,
+          source: source,
+          timestamp: timestamp
+        }
+      end
+
+      def to_s
+        to_h.to_s
+      end
+
+    end
+  end
+end

data/lib/eluvia/errors/unauthorized.rb

@@ -0,0 +1,17 @@
+module Eluvia
+  module Errors
+    class Unauthorized < Eluvia::Errors::StandardError
+
+      def initialize(message = nil, no_sentry = false)
+        super(
+          message || "Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided.",
+          "Unauthorized",
+          401,
+          nil,
+          no_sentry
+        )
+      end
+
+    end
+  end
+end

data/lib/eluvia/errors/unprocessable_entity.rb

@@ -0,0 +1,26 @@
+module Eluvia
+  module Errors
+    class UnprocessableEntity < Eluvia::Errors::StandardError
+
+      attr_reader :messages
+
+      def initialize(messages = {})
+        super(nil, "Unprocessable Entity", 422, nil, false)
+        @messages = messages
+      end
+
+      def to_h
+        messages.reduce([]) do |r, (attribute, message)|
+          r << {
+            message: (message.is_a?(Array) ? message.join(', ') : message).humanize,
+            error: error,
+            status: status,
+            source: attribute,
+            timestamp: timestamp
+          }
+        end
+      end
+
+    end
+  end
+end

data/lib/eluvia/fieldset/rest_field.rb

@@ -0,0 +1,83 @@
+module Eluvia
+  module Fieldset
+    class RestField
+
+      FIELDSET_PATTERN = /\A[^()]+\(.+\)\z/
+      private_constant :FIELDSET_PATTERN
+
+      attr_reader :name
+      attr_accessor :fieldset
+
+      def initialize(name, fieldset = nil)
+        @name = name
+        @fieldset = fieldset
+      end
+
+      def self.create_from_string(field_string, default_fieldset_string: nil)
+        if FIELDSET_PATTERN.match?(field_string)
+          name, subfields_string = field_string[0..-2].split('(', 2)
+          fieldset = RestFieldset.create_from_string(subfields_string, default_field_fieldset_string: default_fieldset_string)
+        else
+          name = field_string
+          fieldset = default_fieldset_string.present? ? RestFieldset.create_from_string(default_fieldset_string) : nil
+        end
+        new(name, fieldset)
+      end
+
+      def deep_dup
+        self.class.new(name, fieldset&.deep_dup)
+      end
+
+      def join(rest_field)
+        raise ArgumentError, "name mismatch ('#{name}' != '#{rest_field.name}')" unless name == rest_field.name
+
+        field = deep_dup
+        if field.fieldset.present? && rest_field.fieldset.present?
+          field.fieldset = field.fieldset.join(rest_field.fieldset)
+        elsif rest_field.fieldset.present?
+          field.fieldset = field.fieldset&.deep_dup
+        end
+        field
+      end
+
+      def intersection(rest_field)
+        raise ArgumentError, "name mismatch ('#{name}' != '#{rest_field.name}')" unless name == rest_field.name
+
+        field = deep_dup
+        if field.fieldset.present? && rest_field.fieldset.present?
+          field.fieldset = field.fieldset.intersection(rest_field.fieldset)
+        elsif rest_field.fieldset.present?
+          field.fieldset = rest_field.fieldset.deep_dup
+        end
+        field
+      end
+
+      def left_intersection(rest_field)
+        raise ArgumentError, "name mismatch ('#{name}' != '#{rest_field.name}')" unless name == rest_field.name
+
+        field = deep_dup
+        if field.fieldset.present? && rest_field.fieldset.present?
+          field.fieldset = field.fieldset.left_intersection(rest_field.fieldset)
+        end
+        field
+      end
+
+      def |(other)
+        join(other)
+      end
+
+      def &(other)
+        intersection(other)
+      end
+
+      def to_s
+        fieldset.present? ? "#{name}(#{fieldset})" : name
+      end
+
+      def ==(other)
+        other.is_a?(RestField) && name == other.name && fieldset == other.fieldset
+      end
+
+    end
+  end
+end

data/lib/eluvia/fieldset/rest_fieldset.rb

@@ -0,0 +1,158 @@
+module Eluvia
+  module Fieldset
+    class RestFieldset
+      include Enumerable
+
+      def initialize(*fields)
+        @fields_map = {}
+        fields.each { |field| append(field) }
+      end
+
+      class << self
+
+        def create_from_list(fields, default_field_fieldset_string: nil)
+          new(*fields.map { |field_string| RestField.create_from_string(field_string, default_fieldset_string: default_field_fieldset_string) })
+        end
+
+        def create_from_string(fields_string, default_field_fieldset_string: nil)
+          new(*split_fields(fields_string).map { |field_string| RestField.create_from_string(field_string, default_fieldset_string: default_field_fieldset_string) })
+        end
+
+        private
+
+        def split_fields(fields_string)
+          fields = []
+          brackets = 0
+          field = +''
+
+          fields_string.each_char do |char|
+            if char == ',' && brackets.zero?
+              field = field.strip
+              fields << field unless field.empty?
+              field = +''
+              next
+            end
+
+            brackets += 1 if char == '('
+            brackets -= 1 if char == ')'
+            field << char
+          end
+
+          field = field.strip
+          fields << field unless field.empty?
+          fields
+        end
+
+      end
+
+      def fields
+        @fields_map.values
+      end
+
+      def join(rest_fieldset)
+        fieldset = deep_dup
+        rest_fieldset.fields.each do |rf|
+          fieldset.fields_map[rf.name] = if fieldset.fields_map.key?(rf.name)
+                                           fieldset.fields_map[rf.name].join(rf)
+                                         else
+                                           rf.deep_dup
+                                         end
+        end
+        fieldset
+      end
+
+      def intersection(rest_fieldset)
+        fieldset = deep_dup
+        fields_map = fieldset.fields_map
+        fieldset.fields_map = {}
+
+        fields_map.each do |name, rf|
+          fieldset.append(rf.intersection(rest_fieldset.fields_map[name])) if rest_fieldset.fields_map.key?(name)
+        end
+        fieldset
+      end
+
+      def left_intersection(rest_fieldset)
+        fieldset = deep_dup
+        fields_map = fieldset.fields_map
+        fieldset.fields_map = {}
+
+        fields_map.each do |name, rf|
+          fieldset.append(rf.left_intersection(rest_fieldset.fields_map[name])) if rest_fieldset.fields_map.key?(name)
+        end
+        fieldset
+      end
+
+      def delete(key)
+        @fields_map.delete(key.to_s)
+      end
+
+      def |(other)
+        join(other)
+      end
+
+      def &(other)
+        intersection(other)
+      end
+
+      def deep_dup
+        self.class.new(*fields.map(&:deep_dup))
+      end
+
+      def to_s
+        fields.join(',')
+      end
+
+      def empty?
+        @fields_map.empty?
+      end
+
+      def get(key)
+        @fields_map[key.to_s]
+      end
+      alias [] get
+
+      def append(field)
+        rest_field =
+          case field
+          when RestField
+            field
+          when String
+            RestField.create_from_string(field)
+          else
+            raise ArgumentError, "field can be only RestField or string ('#{field}' [#{field.class}])"
+          end
+
+        rest_field = @fields_map[rest_field.name].join(rest_field) if @fields_map.key?(rest_field.name)
+
+        @fields_map[rest_field.name] = rest_field
+        self
+      end
+
+      def flat
+        @fields_map.keys.to_set
+      end
+
+      def each(&block)
+        fields.each(&block)
+      end
+
+      def include?(key)
+        @fields_map.key?(key.to_s)
+      end
+
+      def has_any_key(*keys)
+        keys.any? { |key| include?(key) }
+      end
+
+      def ==(other)
+        other.is_a?(RestFieldset) && fields_map == other.fields_map
+      end
+
+      protected
+
+      attr_accessor :fields_map
+
+    end
+  end
+end

data/lib/eluvia/fieldset.rb

@@ -0,0 +1,12 @@
+require 'eluvia/fieldset/rest_field'
+require 'eluvia/fieldset/rest_fieldset'
+
+module Eluvia
+  module Fieldset
+    ALL_FIELDS = '__all__'.freeze
+    DEFAULT_FIELDS = '__default__'.freeze
+
+    RF = RestField
+    RFS = RestFieldset
+  end
+end

data/lib/eluvia/handlers/error_handler.rb

@@ -0,0 +1,60 @@
+module Eluvia
+  module ErrorHandler
+    extend ::ActiveSupport::Concern
+
+    ERRORS = {
+      'ActiveRecord::RecordNotFound' => 'Eluvia::Errors::NotFound',
+      'JSON::ParserError' => 'Eluvia::Errors::BadRequest',
+    }.freeze
+
+    included do
+      rescue_from(::StandardError, with: ->(e) { handle_error(e) })
+    end
+
+    private
+
+    def handle_error(error)
+      if defined?(Sentry)
+        no_sentry = defined?(error.no_sentry) ? !!error.no_sentry : false
+        unless no_sentry
+          Sentry.capture_exception(error)
+        end
+      end
+      log_error(error)
+      render_error(map_error(error))
+    end
+
+    def map_error(error)
+      return error if error.class <= Errors::StandardError
+      if ERRORS.key?(error.class.name)
+        ERRORS[error.class.name].constantize.new(error.to_s)
+      else
+        Eluvia::Errors::StandardError.new(error.to_s)
+      end
+    end
+
+    def render_error(error)
+      render json: Eluvia::ErrorSerializer.new(error), status: error.status
+    end
+
+    def log_error(error)
+      if error.respond_to?(:messages)
+        message = error.messages.values.join(', ')
+      elsif error.respond_to?(:message)
+        message = error.message
+      else
+        message = 'Unknown error occurred.'
+      end
+      message = "#{error.class.name}: #{message}"
+      if error.respond_to?(:status)
+        if error.status.to_i >= 500
+          Rails.logger.error(message)
+        else
+          Rails.logger.info(message)
+        end
+      else
+        Rails.logger.error(message)
+      end
+    end
+  end
+end