eluvia-base 3.39.0 → 3.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 691157713c8474d969d76eaee1106d331696a45b9458ee64a563762391e43ed3
-  data.tar.gz: 280074f623f0c865a349edaf49c277875c6eeb28374ab8062b0f2aff5f061d67
+  metadata.gz: 8d7c48fd8f44bcda78e3e702b68e2d1fc1da1f16c5c5231f9243c1a82c3132ca
+  data.tar.gz: 9eba98e2363832aea7e3015cfdc9312b7fb88fccae0d45def95cb34b8606a0ef
 SHA512:
-  metadata.gz: 1e202828e32b3c665d109ec6584c68fe4ff047b46a9af05b3119c68118d692e306ab3deac2534bc46779dcfc3e5a51b5af057e21940f0aea56ee076f6df9c8c9
-  data.tar.gz: 6eff59b834d789c738f7499d14770bc89cd2793d38ac337c2c7baf158b166170c94a38f55e7d4a6cad31cee49ba1937f81c1f9e15a9acd6748d711b8eb02356b
+  metadata.gz: eb92181c8003d8da9d2647734357877fc8e75aed3ae362ccd8fe91dad0da757f28648fbe1fffd9fcadb367ae97b5884670ae202847a5bf8842730b45b5355438
+  data.tar.gz: c6aa908b43d905ba1080d12b5c6c2cbeda73917c00a58ae45fbd3ef3c9ddf293ab87726036945ff27fce510dbac61d4ced691a1341d2997babeaa4c0c2e6b0d6

data/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.41.0] — 2026-10-27
+
+### Added
+- `Eluvia::ActiveRecord::FileArrayAttribute` registers each `file_array_attr` like `file_attr`
+  does: `file_array_attrs`, `file_array_attr_names`, `has_file_array_attr?` and
+  `find_file_array_attr` return its `underlying_attachments`, `underlying_filter`, `nature` and
+  `append_only` (HAB-991).
+- `append_only:` option on `file_array_attr`: the setter takes a list of flat
+  `{filename, content}` files, attaches each one with content, never removes an existing
+  attachment, and ignores `nil`. Requires `underlying_attachments` (HAB-991).
+
+## [3.40.0] — 2026-09-23
+
+### Added
+- `Eluvia::ActiveRecord::EnvFilterable` — a generic, model-agnostic filter driven by deploy-time
+  config (typically a base64-encoded JSON ENV var). `env_filter_fields` declares the column
+  whitelist (the only part ever interpolated into SQL; all values stay bound parameters),
+  `parse_env_filter_config` decodes the base64 JSON, and `apply_env_filter(scope, config)` applies
+  the AND-combined `field`/`operator`/`value` conditions to a scope. Operators: `eq`, `not_eq`,
+  `in`, `not_in`, `like`, `not_like` (case-insensitive substring; negative operators are
+  NULL-safe). Extracted from the payments service so services need only declare their whitelist
+  (VD-2811).
+
 ## [3.39.0] — 2026-09-18
 
 ### Added

data/README.md

@@ -276,7 +276,53 @@ end
 If `upload_key` is present on the assigned `Eluvia::File` but no finalizer is registered, a
 `Eluvia::Errors::StandardError` is raised.
 
-### 2.7. Translations
+### 2.7. ENV-driven scope restriction
+
+`Eluvia::ActiveRecord::EnvFilterable` applies a deploy-time restriction — typically a base64-encoded
+JSON blob in an ENV var — to any scope. It is generic and model-agnostic: a model only declares which
+columns the config may reference, and the config lists `field` / `operator` / `value` conditions that
+are AND-combined. Only declared fields are ever interpolated into SQL (as a column name); every value
+stays a bound parameter, so the config cannot inject SQL. Conditions with an unknown field or operator
+are silently ignored.
+
+```ruby
+
+class BankTransaction < ApplicationRecord
+  include Eluvia::ActiveRecord::EnvFilterable
+
+  # Only these columns may appear in a filter config.
+  env_filter_fields %i[id direction variable_symbol date amount is_hidden]
+end
+```
+
+Read and apply the config (e.g. from a Pundit `policy_scope`):
+
+```ruby
+
+config = BankTransaction.parse_env_filter_config(ENV['ADMIN_BANK_TRANSACTIONS_FILTER_B64'])
+scope  = BankTransaction.apply_env_filter(BankTransaction.all, config)
+```
+
+`parse_env_filter_config` returns `nil` for a blank/missing ENV var (which disables the filter) and
+raises `ArgumentError` on malformed input, so a broken deploy config fails loudly instead of silently
+letting everything through. The config shape is:
+
+```json
+{
+  "conditions": [
+    { "field": "direction", "operator": "eq",   "value": "in" },
+    { "field": "is_hidden", "operator": "eq",   "value": false },
+    { "field": "variable_symbol", "operator": "like", "value": ["12", "34"] }
+  ]
+}
+```
+
+Operators: `eq` / `not_eq` (equality), `in` / `not_in` (membership; value may be a scalar or array),
+`like` / `not_like` (case-insensitive `ILIKE '%…%'` substring match; value may be a scalar or array —
+`like` matches any, `not_like` excludes any). The negative operators (`not_eq`, `not_in`, `not_like`)
+are NULL-safe: a row whose value is `NULL` is kept.
+
+### 2.8. Translations
 
 All validation error messages raised by this gem (ordering, filtering, fieldset and pagination errors) go through
 `I18n.t` with an English `default:`, so the gem works out of the box without any locale setup. In addition,

data/lib/eluvia/active_record/env_filterable.rb

@@ -0,0 +1,110 @@
+require 'base64'
+
+module Eluvia
+  module ActiveRecord
+    # Generic, model-agnostic filter driven by deploy-time configuration (typically a base64-encoded
+    # JSON blob in an ENV var). The config is a list of `field` / `operator` / `value` conditions,
+    # AND-combined, that narrow a scope — e.g. to restrict what an admin interface may ever see.
+    #
+    # Only fields declared via `env_filter_fields` are ever interpolated into SQL (as a column name);
+    # every value is a bound parameter, so the config cannot be used to inject arbitrary SQL. Unknown
+    # fields and operators are silently ignored.
+    #
+    # @example Declaring the whitelist on a model
+    #   class BankTransaction < ApplicationRecord
+    #     include Eluvia::ActiveRecord::EnvFilterable
+    #     env_filter_fields %i[id direction variable_symbol date amount is_hidden]
+    #   end
+    #
+    # @example Applying it to a scope (e.g. from a Pundit `policy_scope`)
+    #   config = BankTransaction.parse_env_filter_config(ENV['ADMIN_BANK_TRANSACTIONS_FILTER_B64'])
+    #   BankTransaction.apply_env_filter(scope, config)
+    module EnvFilterable
+      extend ::ActiveSupport::Concern
+
+      class_methods do
+
+        # Declares (with arguments) or returns (without arguments) the fields that may appear in an
+        # env filter config. Only these column names are ever interpolated into SQL. Names are stored
+        # as strings so they compare directly against the config's `field` values.
+        #
+        # @param field_names [Array<String, Symbol>] whitelisted column names
+        # @return [Array<String>] the declared whitelist
+        def env_filter_fields(*field_names)
+          if field_names.empty?
+            @_env_filter_fields ||= []
+          else
+            @_env_filter_fields = field_names.flatten.map(&:to_s)
+          end
+        end
+
+        # Decodes a base64-encoded JSON filter config (typically read straight from an ENV var) into a
+        # Hash. Returns `nil` for blank input so a missing ENV var disables the filter. Raises
+        # `ArgumentError` on malformed input so a broken deploy-time config fails loudly rather than
+        # silently letting everything through.
+        #
+        # @param encoded [String, nil] base64-encoded JSON, or `nil`/blank
+        # @return [Hash, nil]
+        def parse_env_filter_config(encoded)
+          return nil if encoded.blank?
+
+          JSON.parse(Base64.strict_decode64(encoded.strip))
+        rescue ArgumentError, JSON::ParserError => e
+          raise ArgumentError, "invalid env filter config: #{e.message}"
+        end
+
+        # Applies an env filter config to +scope+. Config is a Hash with a `"conditions"` array; each
+        # condition has `"field"`, `"operator"` and `"value"`. All conditions are AND-combined. A blank
+        # config returns the scope unchanged; conditions with an unknown field or operator are ignored.
+        #
+        # Operators:
+        #   eq / not_eq        equality (not_eq keeps NULLs)
+        #   in / not_in        membership; value may be a scalar or array (not_in keeps NULLs)
+        #   like / not_like    case-insensitive substring match; value may be a scalar or an array
+        #                      (like → matches any; not_like → excludes any, keeps NULLs)
+        #
+        # @param scope [ActiveRecord::Relation]
+        # @param config [Hash, nil]
+        # @return [ActiveRecord::Relation]
+        def apply_env_filter(scope, config)
+          return scope if config.blank?
+
+          Array(config['conditions']).each do |cond|
+            field = cond['field'].to_s
+            op = cond['operator'].to_s
+            next unless env_filter_fields.include?(field)
+
+            col = "#{table_name}.#{field}" # field is whitelisted → safe to interpolate
+            val = cond['value']
+
+            scope =
+              case op
+              when 'eq'
+                scope.where(field => val)
+              when 'not_eq'
+                scope.where("#{col} IS NULL OR #{col} <> ?", val)
+              when 'in'
+                scope.where(field => Array(val))
+              when 'not_in'
+                scope.where("#{col} IS NULL OR #{col} NOT IN (?)", Array(val))
+              when 'like'
+                Array(val).each_with_index.reduce(scope) do |s, (v, i)|
+                  clause = scope.where("#{col} ILIKE ('%' || ? || '%')", v)
+                  i.zero? ? clause : s.or(clause)
+                end
+              when 'not_like'
+                Array(val).reduce(scope) do |s, v|
+                  s.where("#{col} IS NULL OR #{col} NOT ILIKE ('%' || ? || '%')", v)
+                end
+              else
+                scope
+              end
+          end
+
+          scope
+        end
+
+      end
+    end
+  end
+end

data/lib/eluvia/active_record/file_array_attribute.rb

@@ -6,6 +6,30 @@ module Eluvia
 
       class_methods do
 
+        # *********************************************************************
+        # Attribute store methods
+        # *********************************************************************
+
+        def _file_array_attrs
+          @file_array_attrs ||= {}
+        end
+
+        def file_array_attrs
+          _file_array_attrs.values
+        end
+
+        def file_array_attr_names
+          file_array_attrs.map { |a| a[:attr_name] }
+        end
+
+        def has_file_array_attr?(attr_name)
+          _file_array_attrs.key?(attr_name.to_sym)
+        end
+
+        def find_file_array_attr(attr_name)
+          _file_array_attrs.fetch(attr_name.to_sym, nil)
+        end
+
         # *********************************************************************
         # Attribute definition methods for file array
         # *********************************************************************
@@ -16,78 +40,101 @@ module Eluvia
         # @param underlying_attachments [Symbol, nil] Name of the attribute holding underlying Active Storage attachments
         # @param underlying_filter [Proc, nil] Optional filter to be applied to scope underlying attachments
         # @param nature [Symbol] Nature of file attribute (:file, :image, etc.)
+        # @param append_only [Boolean] Whether the setter only attaches new `{filename, content}` files and never removes existing ones
         # @param declare [Boolean] Whether to declare the underlying attribute
-        def file_array_attr(attr_name, underlying_attachments: nil, underlying_filter: nil, nature: :file, declare: false)
+        def file_array_attr(attr_name, underlying_attachments: nil, underlying_filter: nil, nature: :file, append_only: false, declare: false)
           attr_name = attr_name.to_sym
           nature = nature.to_sym
 
+          raise ArgumentError, "`append_only` file array attribute `#{attr_name}` requires `underlying_attachments`." if append_only && !underlying_attachments
+
           # Define it using "has many" attribute
           if declare
             has_many_attr(attr_name, nature == :image ? 'Eluvia::ImageWrapper' : 'Eluvia::FileWrapper')
           end
 
+          # Register metadata
+          self._file_array_attrs[attr_name] = {
+            attr_name: attr_name,
+            underlying_attachments: underlying_attachments,
+            underlying_filter: underlying_filter,
+            nature: nature,
+            append_only: append_only
+          }
+
           # *******************************************************************
           # Dynamically defined instance methods for file array
           # *******************************************************************
 
           if underlying_attachments
 
-            # Set method
-            define_method(:"#{attr_name}=") do |new_values|
-
-              # Check input
-              raise Eluvia::Errors::BadRequest.new("Invalid value for attribute `#{attr_name}`, expecting Array.") unless new_values.is_a?(::Array)
-
-              # Current values
-              current_values = self.send(attr_name)
-              current_ids = current_values.map(&:id)
-              new_ids = []
-
-              # Create missing attachments
-              new_values.each do |value|
-                # Normalize and check value
-                if value.is_a?(::Hash)
-                  if nature == :image
-                    value = Eluvia::ImageWrapper.map(value)
-                  else
-                    value = Eluvia::FileWrapper.map(value)
+            if append_only
+
+              # Set method - attaches each new file, leaves the existing attachments untouched
+              define_method(:"#{attr_name}=") do |new_values|
+                append_file_array_uploads(attr_name, underlying_attachments, new_values)
+              end
+
+            else
+
+              # Set method
+              define_method(:"#{attr_name}=") do |new_values|
+
+                # Check input
+                raise Eluvia::Errors::BadRequest.new("Invalid value for attribute `#{attr_name}`, expecting Array.") unless new_values.is_a?(::Array)
+
+                # Current values
+                current_values = self.send(attr_name)
+                current_ids = current_values.map(&:id)
+                new_ids = []
+
+                # Create missing attachments
+                new_values.each do |value|
+                  # Normalize and check value
+                  if value.is_a?(::Hash)
+                    if nature == :image
+                      value = Eluvia::ImageWrapper.map(value)
+                    else
+                      value = Eluvia::FileWrapper.map(value)
+                    end
                   end
-                end
-                raise Eluvia::Errors::BadRequest.new("Invalid value for attribute `#{attr_name}[]`, expecting Eluvia::FileWrapper or Eluvia::ImageWrapper.") unless value.is_a?(Eluvia::FileWrapper) || value.is_a?(Eluvia::ImageWrapper)
-                raise Eluvia::Errors::BadRequest.new("Invalid value for attribute `#{attr_name}[].file`, can't be blank.") if value.file.blank?
+                  raise Eluvia::Errors::BadRequest.new("Invalid value for attribute `#{attr_name}[]`, expecting Eluvia::FileWrapper or Eluvia::ImageWrapper.") unless value.is_a?(Eluvia::FileWrapper) || value.is_a?(Eluvia::ImageWrapper)
+                  raise Eluvia::Errors::BadRequest.new("Invalid value for attribute `#{attr_name}[].file`, can't be blank.") if value.file.blank?
 
-                # Keep track of new ids
-                new_ids << value.id if value.id
+                  # Keep track of new ids
+                  new_ids << value.id if value.id
 
-                # Retrieve filename and content
-                filename = value.file&.filename
-                content = value.file&.content
+                  # Retrieve filename and content
+                  filename = value.file&.filename
+                  content = value.file&.content
 
-                # Sanitize filename
-                filename = ActiveStorage::Filename.new(filename).sanitized
+                  # Sanitize filename
+                  filename = ActiveStorage::Filename.new(filename).sanitized
 
-                # Create or update attachment only if both filename and content are passed (this means that user uploaded a new file)
-                if !filename.blank? && !content.blank?
+                  # Create or update attachment only if both filename and content are passed (this means that user uploaded a new file)
+                  if !filename.blank? && !content.blank?
 
-                  # Delete the existing attachment
-                  if value.id && current_ids.include?(value.id)
-                    attachment_record = self.send("#{underlying_attachments}_attachments").find(value.id)
-                    attachment_record.purge_later
+                    # Delete the existing attachment
+                    if value.id && current_ids.include?(value.id)
+                      attachment_record = self.send("#{underlying_attachments}_attachments").find(value.id)
+                      attachment_record.purge_later
+                    end
+
+                    # Create a new attachment
+                    self.send(underlying_attachments).attach(io: StringIO.new(Base64.decode64(content)), filename: filename)
                   end
 
-                  # Create a new attachment
-                  self.send(underlying_attachments).attach(io: StringIO.new(Base64.decode64(content)), filename: filename)
                 end
 
-              end
-
-              # Delete no longer wanted attachments
-              current_values.each do |value|
-                unless new_ids.include?(value.id)
-                  attachment_record = self.send("#{underlying_attachments}_attachments").find(value.id)
-                  attachment_record.purge_later
+                # Delete no longer wanted attachments
+                current_values.each do |value|
+                  unless new_ids.include?(value.id)
+                    attachment_record = self.send("#{underlying_attachments}_attachments").find(value.id)
+                    attachment_record.purge_later
+                  end
                 end
               end
+
             end
 
             # Get method
@@ -111,6 +158,32 @@ module Eluvia
         end
 
       end
+
+      private
+
+      # Attaches each `{filename, content}` upload of an append-only file array attribute
+      def append_file_array_uploads(attr_name, underlying_attachments, new_values)
+        return if new_values.nil?
+
+        # Check input
+        raise Eluvia::Errors::BadRequest.new("Invalid value for attribute `#{attr_name}`, expecting Array.") unless new_values.is_a?(::Array)
+
+        new_values.each do |value|
+          # Normalize and check value
+          value = Eluvia::File.map(value) if value.is_a?(::Hash)
+          raise Eluvia::Errors::BadRequest.new("Invalid value for attribute `#{attr_name}[]`, expecting Eluvia::File.") unless value.is_a?(Eluvia::File)
+          raise Eluvia::Errors::BadRequest.new("Invalid value for attribute `#{attr_name}[]`, `upload_key` is not supported.") if value.upload_key.present?
+
+          # An item without content carries no new file
+          next if value.content.blank?
+
+          filename = ActiveStorage::Filename.new(value.filename.to_s).sanitized
+          raise Eluvia::Errors::BadRequest.new("Invalid value for attribute `#{attr_name}[].filename`, can't be blank.") if filename.blank?
+
+          self.send(underlying_attachments).attach(io: StringIO.new(Base64.decode64(value.content)), filename: filename)
+        end
+      end
+
     end
   end
 end

data/lib/eluvia-base.rb

@@ -20,6 +20,7 @@ require 'eluvia/active_model/object_attribute'
 require 'eluvia/active_model/range_attribute' # depends on object_attribute
 
 # Active record
+require 'eluvia/active_record/env_filterable'
 require 'eluvia/active_record/file_array_attribute'
 require 'eluvia/active_record/file_attribute'
 require 'eluvia/active_record/filtering'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: eluvia-base
 version: !ruby/object:Gem::Version
-  version: 3.39.0
+  version: 3.41.0
 platform: ruby
 authors:
 - Matěj Outlý
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.19'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: ostruct
   requirement: !ruby/object:Gem::Requirement
@@ -128,6 +142,7 @@ files:
 - lib/eluvia/active_model/enum_attribute.rb
 - lib/eluvia/active_model/object_attribute.rb
 - lib/eluvia/active_model/range_attribute.rb
+- lib/eluvia/active_record/env_filterable.rb
 - lib/eluvia/active_record/file_array_attribute.rb
 - lib/eluvia/active_record/file_attribute.rb
 - lib/eluvia/active_record/filtering.rb