eluvia-base 3.37.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f3de7ff3e455a14c86e7c241ac9456ef39ca93ba40c32fd0a8dfb480986b644
+  data.tar.gz: 3ee766edbedf1243cf4036ef90b6e84da1b81585dd9115ed387c802280269850
+SHA512:
+  metadata.gz: 96a8f3748400de99c05d3bc237f5d598de09c07b7366a60336a38051af342bf61a14bd35a96572a704f36f8395213b1288ebd5dd5b78099979d082a0d8016b6d
+  data.tar.gz: 175ea58ec0bc03a3f7a3271ab5447a2676d892df10eee44825c0effe924fa2b3029ec7c8bfc3ef253247f984847485f42e9f4cf49ef8bee64fac2cb2683532aa

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Eluvia.land s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+# Eluvia Base
+
+This library provides a set of Ruby on Rails customizations and other helpers in order to meet common Eluvia standards 
+for API communication (https://sparktech.myjetbrains.com/youtrack/articles/BASE-A-4/Communication-interface-FE-BE) and 
+Eluvia requirements for backend application behavior. 
+
+It applies to both client and server sides:
+- Pagination and ordering is handled for the API requests (server side).
+- Extended params parsing is implemented for the API requests (server side).
+- Extended filtering is handled for the API requests (server side).
+- Errors are serialized in the API response in a standard way (server side).
+- Integration helpers are implemented to provide easy communication with other Eluvia components (client side).
+
+## 1. Installation
+
+### 1.1. Gem
+
+To install the library to your project, just add this to your `Gemfile`:
+
+```ruby
+gem 'eluvia-base'
+```
+
+New dependencies should be installed with:
+
+```bash
+bundle install
+```
+
+### 1.2. Initializer
+
+Next, create an initializer `config/initializers/eluvia_base.rb` with the configuration:
+
+```ruby
+Eluvia::Base.setup do |config|
+  config.api_case = ENV.fetch('API_CASE') { '' }
+  config.private_api_key = ENV.fetch('PRIVATE_API_KEY') { '' }
+  config.public_api_key = ENV.fetch('PUBLIC_API_KEY') { '' }
+end
+```
+
+For full list of configuration options, see `lib/eluvia/base/config.rb` file.
+
+## 2. Usage
+
+### 2.1. Application controller setup
+
+In order to use all the implemented functionality, you should integrate all defined handlers to your 
+main `ApplicationController`:
+
+```ruby
+
+class ApplicationController < ActionController::API
+  include Eluvia::ErrorHandler
+  include Eluvia::PaginationHandler
+  include Eluvia::ParamsHandler
+
+  # ...
+end
+```
+
+### 2.2. Pagination
+
+In order to interpret `limit`, `offset` and `order_by` parameters, you can user `set_pagination` decorator. It will
+transform the input parameters into the `@order_by`, `@page`, `@limit` and `@padding` instance variables which can be 
+easily used in Active Record and Kaminari interfaces. 
+
+```ruby
+
+class TestRecordsController < ApplicationController
+  # ...
+
+  before_action -> { set_pagination(20, 0, 'created_at:desc') }, only: [:index]
+
+  # ...
+
+  def index
+    @test_records = TestRecord.all.order(@order_by).page(@page).per(@limit).padding(@padding)
+  end
+
+  # ...
+end
+```
+
+### 2.3. Params parser
+
+You can use `parse_json_param` helper to parse JSON without predefined structure. In case you know the input JSON
+structure, you should use standard "strong params" mechanism.
+
+```ruby
+
+class TestRecordsController < ApplicationController
+  # ...
+
+  def create
+    @test_record = TestRecord.create(test_record_params)
+    # ...
+  end
+
+  # ...
+
+  def test_record_params
+    result = params.permit(
+      :param_1,
+      :param_2,
+    )
+    result[:additional_params] = parse_json_param(params[:additional_params])
+    result
+  end
+
+  # ...
+end
+```
+
+### 2.4. Eluvia integration
+
+Integration class can be implemented with the help of `Eluvia::EluviaIntegration` concern. This concern acts as 
+a wrapper over `RestClient` and brings some functionality for JSON parsing, pagination and Eluvia specific headers
+composition.
+
+```ruby
+
+class TestRecordsIntegration
+  include Singleton
+  include Eluvia::EluviaIntegration
+
+  def initialize
+    @service_url = '...'
+  end
+
+  def get_some_data(session_id)
+    parse_get_request(compose_url('some-data'), compose_headers_both(session_id))
+  end
+
+  def post_some_data(session_id, data)
+    parse_post_request(compose_url('some-data'), compose_headers_both(session_id), data)
+  end
+
+end
+```
+
+For the full list of features, see `Eluvia::EluviaIntegration` interface.
+
+### 2.5. Raising error
+
+You can raise en exception `Eluvia::Errors::XXX` anywhere in the code and this exception will be automatically 
+formatted as standardized error response.
+
+For example, this exception:
+
+```ruby
+
+raise Eluvia::Errors::NotFound.new('Test record was not found.')
+```
+
+will be formatted into this response:
+
+```json
+{
+  "errors": [
+    {
+      "message": "Test record was not found.",
+      "error": "Not Found",
+      "status": 404,
+      "source": null,
+      "timestamp": "2022-11-04T17:11:00.969Z"
+    }
+  ]
+}
+```
+
+For example, this exception:
+
+```ruby
+
+raise Eluvia::Errors::UnprocessableEntity.new('param_1' => 'Param 1 must not be blank.', 
+                                              'param_2' => 'Param 2 must not be blank.')
+```
+
+will be formatted into this response:
+
+```json
+{
+  "errors": [
+    {
+      "message": "Param 1 must not be blank.",
+      "error": "Unprocessable Entity",
+      "status": 422,
+      "source": "param_1",
+      "timestamp": "2022-11-04T17:11:00.969Z"
+    },
+    {
+      "message": "Param 2 must not be blank.",
+      "error": "Unprocessable Entity",
+      "status": 422,
+      "source": "param_2",
+      "timestamp": "2022-11-04T17:11:00.969Z"
+    }
+  ]
+}
+```
+
+For the full list of available exceptions, see content of `lib/eluvia/errors` folder.
+
+### 2.6. Chunked/direct upload finalization
+
+`Eluvia::File` carries an `upload_key` attribute, an alternative to `content` (base64 encoded file data)
+for `file_attr` fields backed by an underlying ActiveStorage attachment. When `upload_key` is present,
+the setter no longer base64-decodes `content` — instead it delegates to `Eluvia::Uploads.finalizer`, a
+registrable extension point that finalizes a previously uploaded (chunked/direct) temp object into the
+ActiveStorage attachment. This lets a separate library (e.g. a chunked upload provider) implement the
+actual storage logic (S3 `copy_object`, tus, ...) without eluvia-base depending on it.
+
+Register a finalizer, typically from an initializer:
+
+```ruby
+
+Eluvia::Uploads.finalizer = ->(attachment_record, upload_key, filename) do
+  # Resolve `upload_key` in your storage backend and attach the resulting blob to `attachment_record`,
+  # using `filename` as the final (sanitized) filename.
+end
+```
+
+If `upload_key` is present on the assigned `Eluvia::File` but no finalizer is registered, a
+`Eluvia::Errors::StandardError` is raised.

data/lib/eluvia/active_model/amount_attribute.rb

@@ -0,0 +1,108 @@
+module Eluvia
+  module ActiveModel
+    module AmountAttribute
+      extend ::ActiveSupport::Concern
+      include Eluvia::ActiveModel::Attributes
+
+      class_methods do
+
+        # *********************************************************************
+        # Attribute store methods
+        # *********************************************************************
+
+        def _amount_attrs
+          @amount_attrs ||= {}
+        end
+
+        def amount_attrs
+          _amount_attrs.values
+        end
+
+        def amount_attr_names
+          amount_attrs.map { |a| a[:attr_name] }
+        end
+
+        def has_amount_attr?(attr_name)
+          _amount_attrs.key?(attr_name.to_sym)
+        end
+
+        def find_amount_attr(attr_name)
+          _amount_attrs.fetch(attr_name.to_sym, nil)
+        end
+
+        # *********************************************************************
+        # Transform value methods
+        # *********************************************************************
+
+        def convert_value_from_major_to_minor(value_major, precision: 2)
+          if value_major.nil?
+            nil
+          else
+            (value_major.to_f * (10**precision)).round(0).to_i
+          end
+        end
+
+        def convert_value_from_minor_to_major(value_minor, precision: 2)
+          if value_minor.nil?
+            nil
+          else
+            (value_minor.to_f / (10**precision)).round(precision)
+          end
+        end
+
+        # *********************************************************************
+        # Attribute definition methods
+        # *********************************************************************
+
+        # Adds a new amount attribute to this model
+        #
+        # @param attr_name [Symbol] Attribute name
+        # @param precision [Integer] Number of decimal places
+        # @param declare [Boolean] Whether to declare the underlying attribute as integer
+        def amount_attr(attr_name, precision: 2, declare: false)
+          if declare
+            integer_attr attr_name
+          end
+
+          # Prepare internal structure
+          _amount_attrs[attr_name] = {
+            precision: precision,
+          }
+
+          # Define attribute for minor units
+          minor_attr_name = :"#{attr_name}_minor"
+          float_attr minor_attr_name
+
+          # Get a value in minor units
+          define_method(minor_attr_name) do
+            self.send(attr_name)
+          end
+
+          # Set a value in minor units
+          define_method(:"#{minor_attr_name}=") do |value_minor|
+            self.send(:"#{attr_name}=", value_minor)
+            value_minor
+          end
+
+          # Define attribute for major units
+          major_attr_name = :"#{attr_name}_major"
+          float_attr major_attr_name
+
+          # Get a value in major units
+          define_method(major_attr_name) do
+            self.class.convert_value_from_minor_to_major(self.send(attr_name), precision: precision)
+          end
+
+          # Set a value in major units
+          define_method(:"#{major_attr_name}=") do |value_major|
+            self.send(:"#{attr_name}=", self.class.convert_value_from_major_to_minor(value_major, precision: precision))
+            value_major
+          end
+
+        end
+
+      end
+
+    end
+  end
+end

data/lib/eluvia/active_model/array_attribute.rb

@@ -0,0 +1,134 @@
+module Eluvia
+  module ActiveModel
+    module ArrayAttribute
+      extend ::ActiveSupport::Concern
+      include Eluvia::ActiveModel::Attributes
+
+      class_methods do
+
+        # *********************************************************************
+        # Attribute store methods
+        # *********************************************************************
+
+        def _array_attrs
+          @array_attrs ||= {}
+        end
+
+        def array_attrs
+          _array_attrs.values
+        end
+
+        def array_attr_names
+          array_attrs.map { |a| a[:attr_name] }
+        end
+
+        def has_array_attr?(attr_name)
+          _array_attrs.key?(attr_name.to_sym)
+        end
+
+        def find_array_attr(attr_name)
+          _array_attrs.fetch(attr_name.to_sym, nil)
+        end
+
+        # *********************************************************************
+        # Attribute definition methods for array
+        # *********************************************************************
+
+        def array_column(attr_name, options = {})
+          array_attr(attr_name, **options)
+        end
+
+        # Add a new "array" attribute to this model
+        #
+        # @param attr_name [Symbol] Attribute name
+        # @param type [Symbol] Type of the array elements (:any, :string, :uuid, :date, :datetime, :integer, :float, :boolean)
+        # @param filter [Proc, nil] Optional filter proc to filter array elements
+        # @param transform [Proc, nil] Optional transform proc to transform array elements
+        # @param serialize [Boolean] Whether to serialize the array as JSON string in the underlying attribute
+        # @param declare [Boolean] Whether to declare the underlying attribute as any
+        def array_attr(attr_name, type: :string, filter: nil, transform: nil, serialize: false, declare: false)
+          attr_name = attr_name.to_sym
+          type = type.to_sym
+
+          # Declare underlying attribute
+          if declare
+            any_attr attr_name
+          end
+
+          # Type check
+          raise Eluvia::Errors::StandardError.new("Unknown type `#{type}`.") unless Eluvia::ActiveModel::Attributes::SIMPLE_TYPES.include?(type)
+
+          # Register metadata
+          self._array_attrs[attr_name] = {
+            attr_name: attr_name,
+            type: type,
+            filter: filter,
+            transform: transform,
+            serialize: serialize
+          }
+
+          # *******************************************************************
+          # Dynamically defined instance methods for array
+          # *******************************************************************
+
+          # Set method
+          define_method(:"#{attr_name}=") do |value|
+
+            # Convert string to array, we expect JSON string here
+            if value.is_a?(::String)
+              if !value.blank?
+                value = JSON.parse(value) rescue nil
+              else
+                value = nil
+              end
+            end
+
+            # Check input
+            raise Eluvia::Errors::BadRequest.new("Invalid value for array attribute `#{attr_name}`, expecting Array or nil.") unless value.nil? || value.is_a?(::Array)
+
+            # Handle blank value
+            if value.blank?
+              write_attribute(attr_name, nil)
+              return
+            end
+
+            # Clean values according to the specified type
+            value = value.map { |item| self.class.send(:"clean_#{type}_value", item) }
+
+            # Optional value filter
+            if filter && filter.respond_to?(:call)
+              value = value.select { |item| filter.call(item) }
+            end
+
+            # Optional value transform
+            if transform && transform.respond_to?(:call)
+              value = value.map { |item| transform.call(item) }.compact
+            end
+
+            # Store to the underlying attribute
+            write_attribute(attr_name, serialize ? value.to_json : value)
+          end
+
+          # Get method
+          define_method(attr_name) do
+            # Read value from the underlying attribute and parse it if needed
+            value = read_attribute(attr_name)
+            value = JSON.parse(value) rescue nil if serialize
+
+            # Handle blank value
+            return nil if value.blank?
+
+            # Check output
+            raise Eluvia::Errors::StandardError.new("Invalid value for array attribute `#{attr_name}`, expecting Array.") unless value.is_a?(::Array)
+
+            # Clean values according to the specified type
+            value = value.map { |item| self.class.send(:"clean_#{type}_value", item) }
+
+            value
+          end
+        end
+
+      end
+    end
+  end
+end