eluvia-base 3.39.0 → 3.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 691157713c8474d969d76eaee1106d331696a45b9458ee64a563762391e43ed3
-  data.tar.gz: 280074f623f0c865a349edaf49c277875c6eeb28374ab8062b0f2aff5f061d67
+  metadata.gz: dcf7c769d60f4347beee0d63aff1e1e8944e5fb2412985f531465dd833cfe58e
+  data.tar.gz: dc7491fcac983ef84e9f33396139370ce94fb65ce8718742acc4806d4e35e0b6
 SHA512:
-  metadata.gz: 1e202828e32b3c665d109ec6584c68fe4ff047b46a9af05b3119c68118d692e306ab3deac2534bc46779dcfc3e5a51b5af057e21940f0aea56ee076f6df9c8c9
-  data.tar.gz: 6eff59b834d789c738f7499d14770bc89cd2793d38ac337c2c7baf158b166170c94a38f55e7d4a6cad31cee49ba1937f81c1f9e15a9acd6748d711b8eb02356b
+  metadata.gz: 1a8eff124c578195160772b542e7ece4419b76ada79214f3b7d7ba3cb5c24768249b8d8c24ea207e37a33e6dc5d4d3b7196f83d369df428ae9724b36702af1e4
+  data.tar.gz: 2df71bbb4195fde554b62bc8052d02894be13b14c652325f08af43b94d4b23385499bf0dbe5847ae16786519e59de04be8b6d8a65f4e734f8202bc99f793a55a

data/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.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-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.40.0
 platform: ruby
 authors:
 - Matěj Outlý
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-09-23 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