eluvia-base 3.38.0 → 3.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5504d4c333c7a6ec87a0752207016b6ba9e9b4b6627a1de04afde70b755a907e
-  data.tar.gz: 0d666609cd85101862b53301e4a31f08f99719b02164ddb2c43aff83edb4a698
+  metadata.gz: dcf7c769d60f4347beee0d63aff1e1e8944e5fb2412985f531465dd833cfe58e
+  data.tar.gz: dc7491fcac983ef84e9f33396139370ce94fb65ce8718742acc4806d4e35e0b6
 SHA512:
-  metadata.gz: 1da58aaaef1574dc606baa60d941ac243554808301a5a94d4ccea92b21c65375895a3e66c8b749dc181d22c8d5da50955e0c34840d1818a0001a5ba4821f3f74
-  data.tar.gz: 9ca68b4c7e319abbb95228e0639c1d13c0158571491fd3e355363e5cf1237abac9cf5e83513f5dc70da3a86ed9b4768bd83c47ccc6f23bbc4a6c42ac42b752fe
+  metadata.gz: 1a8eff124c578195160772b542e7ece4419b76ada79214f3b7d7ba3cb5c24768249b8d8c24ea207e37a33e6dc5d4d3b7196f83d369df428ae9724b36702af1e4
+  data.tar.gz: 2df71bbb4195fde554b62bc8052d02894be13b14c652325f08af43b94d4b23385499bf0dbe5847ae16786519e59de04be8b6d8a65f4e734f8202bc99f793a55a

data/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+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
+- This changelog, in the format the ci-toolbox release job expects: on release the unreleased
+  heading is rewritten to the released version and date, and the section becomes the description
+  of the GitLab release.
+- `Eluvia::Base::Config.max_page_limit` — upper bound for the `limit` pagination param on
+  `set_pagination` (default `1000`, `nil` disables the check), overridable per controller via
+  `pagination_max_limit` or per call via the `max_limit:` keyword.
+- `Eluvia::Base::Config.disable_pagination_errors` and the `disable_errors:` keyword on
+  `set_pagination`, to restore the previous silent-fallback behavior for an invalid `limit`
+  instead of raising.
+- `allow_meta_only_limit:` keyword on `set_pagination` to reject `limit=0` like any other invalid
+  value, for resources that don't support a meta-only request.
+- Translations (`lib/eluvia/locales/*.yml`) for all validation error messages raised by this gem
+  (ordering, filtering, fieldset, pagination), in the same languages supported by `habarico`
+  (`cs`, `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`, `ro`, `sk`, `uk`).
+- `Eluvia::PaginationHandler.order_by_param_name` — resolves the `order_by`/`orderBy` query
+  parameter name the same way `set_pagination` does, for callers outside this concern (e.g.
+  request-level validators run in a `before_action` ahead of it) that need to read the same
+  parameter without duplicating the `Config.api_case` check.
+
+### Security
+- **BREAKING:** `set_pagination`'s `limit` param is now capped and validated (HAB-946, from the
+  HAB-894 audit). A non-numeric, negative, or above-`max_page_limit` `limit` is rejected with a
+  `422 Unprocessable Entity` (error detail on the `limit` field) instead of being silently
+  truncated or defaulted. `limit=0` no longer raises `ZeroDivisionError` — it's now accepted as a
+  deliberate meta-only request (see `allow_meta_only_limit:`), mirroring `ListPagination` in
+  `eluvia-base-django`. Only a missing or blank `limit` still falls back to `default_limit`,
+  unchanged.
+- **BREAKING:** `set_pagination`'s `order_by` param is now strictly validated (HAB-915, from the
+  HAB-894 audit). Each `field:direction` entry must have exactly one `:` separator, a non-blank
+  field name, and a lower-case `asc`/`desc` direction; anything else is rejected with a
+  `422 Unprocessable Entity` (format errors on `order_by`, direction errors on
+  `order_by__<field>`) instead of being silently truncated to two segments or defaulted to `asc`.
+  A blank `order_by=` no longer raises `NoMethodError` — it's treated as "not supplied" and falls
+  back to `default_order_by`/`fallback_order_by`.

data/README.md

@@ -82,6 +82,58 @@ class TestRecordsController < ApplicationController
 end
 ```
 
+**BREAKING CHANGE:** the `limit` param is now capped. Requests with a `limit` above the configured ceiling are
+rejected with a `422 Unprocessable Entity` (error detail on the `limit` field) instead of being silently accepted.
+A negative or non-numeric `limit` no longer falls through to Kaminari — it now also raises the same `422`. Only a
+missing or blank `limit` param still falls back to `default_limit`, unchanged. `limit=0` is treated as a deliberate
+meta-only request (see below) rather than an error, mirroring `ListPagination` in eluvia-base-django.
+
+The ceiling defaults to `Eluvia::Base::Config.max_page_limit` (`1000` by default, `nil` disables the check):
+
+```ruby
+Eluvia::Base::Config.max_page_limit = 500
+```
+
+It can be overridden per controller by overriding `pagination_max_limit`, or per call via the `max_limit:` keyword
+(an explicit `max_limit: nil` removes the ceiling for that call only, regardless of `pagination_max_limit`):
+
+```ruby
+class TestRecordsController < ApplicationController
+  def pagination_max_limit
+    50
+  end
+end
+```
+
+```ruby
+before_action -> { set_pagination(default_limit: 20, default_offset: 0, max_limit: 50) }, only: [:index]
+```
+
+To restore the pre-validation behavior (invalid or above-ceiling `limit` silently falls back to `default_limit`
+instead of raising `422`), enable `disable_errors` — globally via `Eluvia::Base::Config.disable_pagination_errors =
+true` (default: `false`), or per call via the `disable_errors:` keyword, which takes precedence over the global
+setting:
+
+```ruby
+before_action -> { set_pagination(default_limit: 20, default_offset: 0, disable_errors: true) }, only: [:index]
+```
+
+`limit=0` is accepted by default as a way to request only pagination metadata without fetching any records — check
+`@limit.zero?` in the action and skip the query:
+
+```ruby
+def index
+  @test_records = @limit.zero? ? TestRecord.none : TestRecord.all.order(@order_by).page(@page).per(@limit).padding(@padding)
+end
+```
+
+Pass `allow_meta_only_limit: false` (e.g. for a search-backed resource, mirroring
+`AnySearchCursorBasedPagination` in eluvia-base-django) to reject `limit=0` like any other invalid value instead:
+
+```ruby
+before_action -> { set_pagination(default_limit: 20, default_offset: 0, allow_meta_only_limit: false) }, only: [:index]
+```
+
 ### 2.3. Params parser
 
 You can use `parse_json_param` helper to parse JSON without predefined structure. In case you know the input JSON
@@ -223,3 +275,76 @@ end
 
 If `upload_key` is present on the assigned `Eluvia::File` but no finalizer is registered, a
 `Eluvia::Errors::StandardError` is raised.
+
+### 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,
+`lib/eluvia/locales/*.yml` ships ready-made translations — under the `eluvia.errors.*` key namespace — for the
+same set of languages supported by `habarico`: `cs`, `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`, `ro`,
+`sk`, `uk`. These are appended to `I18n.load_path` automatically when the gem loads; a host application only
+needs to add the relevant locale to its own `I18n.available_locales` and set `I18n.locale` as usual. A host app's
+own `config/locales/*.yml` takes precedence over these if it defines the same key.
+
+## 3. Development
+
+### 3.1. Versioning and releases
+
+The gem version lives in `version.json` and is read at load time by `Eluvia::Base.version`. Releases are
+driven by the `ruby-library` component of the
+[ci-toolbox](https://gitlab.eluvia.dev/gitlab-ci/ci-toolbox) — the release job bumps the version, tags it,
+and the tag pipeline publishes the gem to [geminabox](https://geminabox.eluvia.dev) and to
+[rubygems.org](https://rubygems.org/gems/eluvia-base), and creates a GitLab release.
+
+### 3.2. Changelog
+
+Notable changes go to [CHANGELOG.md](CHANGELOG.md) under the `## [Unreleased]` heading, in the
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format. The release job rewrites that heading to
+the released version and the release date, and uses the section as the description of the GitLab release —
+so what you write there is what the Releases page shows.

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/config.rb

@@ -40,6 +40,19 @@ module Eluvia
       mattr_accessor :search_use_unaccent
       @@search_use_unaccent = true
 
+      # Upper bound for the `limit` pagination param on `set_pagination`. Requests with a
+      # higher `limit` are rejected with 422 instead of being silently truncated. `nil`
+      # disables the check. Mirrors `MAX_PAGE_LIMIT` in eluvia-base-django. (default: 1000)
+      mattr_accessor :max_page_limit
+      @@max_page_limit = 1000
+
+      # Whether an invalid `limit` param (non-numeric, negative, above `max_page_limit`, or zero
+      # without `allow_meta_only_limit:`) on `set_pagination` silently falls back to
+      # `default_limit` instead of being rejected with 422. Mirrors `disable_errors` on
+      # `LimitResolutionMixin` in eluvia-base-django. (default: false)
+      mattr_accessor :disable_pagination_errors
+      @@disable_pagination_errors = false
+
     end
   end
 end

data/lib/eluvia/handlers/pagination_handler.rb

@@ -2,23 +2,104 @@ module Eluvia
   module PaginationHandler
     extend ::ActiveSupport::Concern
 
-    def set_pagination(default_limit: 20, default_offset: 0, default_order_by: 'created_at:asc', fallback_order_by: 'created_at:asc', force_order_by: false)
+    # Resolves the query parameter name carrying the `order_by` input according to the configured
+    # API case. Exposed so callers outside this concern (e.g. request-level validators run in a
+    # `before_action` ahead of `set_pagination`) parse the exact same parameter, instead of
+    # duplicating this ternary and risking it drifting out of sync with `Config.api_case`.
+    def self.order_by_param_name
+      Eluvia::Base::Config.api_case == 'camel_case' ? :orderBy : :order_by
+    end
+
+    # Sentinel distinguishing an unset `max_limit:` kwarg (defer to `pagination_max_limit`) from
+    # an explicit `max_limit: nil` (no ceiling for this call only, regardless of the config/method).
+    NOT_SET = Object.new.freeze
+
+    # Ceiling applied to `limit` for this controller. Override to customize (e.g. a
+    # per-resource value pulled from a resource definition). Defaults to the library-wide config.
+    def pagination_max_limit
+      Eluvia::Base::Config.max_page_limit
+    end
+
+    def set_pagination(default_limit: 20, default_offset: 0, default_order_by: 'created_at:asc',
+                       fallback_order_by: 'created_at:asc', force_order_by: false, max_limit: NOT_SET,
+                       disable_errors: nil, allow_meta_only_limit: true)
 
       # Pagination
-      @limit = params[:limit] ? params[:limit].to_i : default_limit
+      @limit = resolve_pagination_limit(default_limit: default_limit, max_limit: max_limit,
+        disable_errors: disable_errors, allow_meta_only_limit: allow_meta_only_limit)
+
       @offset = params[:offset] ? params[:offset].to_i : default_offset
-      @page = (@offset / @limit) + 1
-      @padding = @offset % @limit
+      if @limit.zero?
+        # Meta-only request (see `allow_meta_only_limit:`) - no records to page through.
+        @page = 1
+        @padding = 0
+      else
+        @page = (@offset / @limit) + 1
+        @padding = @offset % @limit
+      end
 
       # Order by
+      order_by_param = Eluvia::PaginationHandler.order_by_param_name
+      user_order_by = params[order_by_param].to_s.strip
+      # A blank `order_by` is treated as "not supplied" (falls through to defaults/fallback)
+      # rather than as a literal empty ordering, since a Kaminari scope always needs some order.
+      order_by = !force_order_by && user_order_by.present? ? user_order_by : default_order_by
+      order_by = "#{order_by},#{fallback_order_by}"
+
       @order_by = {}
-      order_by_param = Eluvia::Base::Config.api_case == 'camel_case' ? :orderBy : :order_by
-      order_by = "#{!force_order_by && params.key?(order_by_param) ? params[order_by_param] : default_order_by},#{fallback_order_by}"
-      order_by.to_s.split(',').each do |o|
-        s = o.to_s.split(':')
-        @order_by[s.first] = s.length >= 2 && s[1].downcase == 'desc' ? :desc : :asc
+      order_by.split(',').each do |entry|
+        entry = entry.strip
+        # `-1` keeps a trailing empty segment (e.g. `name:`) instead of Ruby's default of
+        # dropping it, so it is caught below as an invalid direction rather than as a bare field.
+        parts = entry.split(':', -1)
+        field_name, direction = parts
+
+        if parts.length != 2 || field_name.blank?
+          raise Eluvia::Errors::UnprocessableEntity.new({
+            'order_by' => I18n.t('eluvia.errors.ordering.invalid_format',
+              default: 'Invalid format, expected "field_name:asc" or "field_name:desc".')
+          })
+        end
+
+        unless %w[asc desc].include?(direction)
+          raise Eluvia::Errors::UnprocessableEntity.new({
+            "order_by__#{field_name}" => I18n.t('eluvia.errors.ordering.invalid_direction',
+              default: 'Invalid order direction. Allowed values are `asc` and `desc`.')
+          })
+        end
+
+        @order_by[field_name] = direction.to_sym
+      end
+
+    end
+
+    private
+
+    def resolve_pagination_limit(default_limit:, max_limit:, disable_errors:, allow_meta_only_limit:)
+      return default_limit unless params[:limit].present?
+
+      raw_limit = params[:limit].to_s
+      parsed_limit = raw_limit.match?(/\A-?\d+\z/) ? raw_limit.to_i : nil
+      errors_disabled = disable_errors.nil? ? Eluvia::Base::Config.disable_pagination_errors : disable_errors
+
+      if parsed_limit.nil? || parsed_limit.negative? || (parsed_limit.zero? && !allow_meta_only_limit)
+        return default_limit if errors_disabled
+
+        msg = I18n.t('eluvia.errors.pagination.invalid_limit',
+          default: 'Limit must be a positive integer, got %<limit>s.', limit: params[:limit])
+        raise Eluvia::Errors::UnprocessableEntity.new('limit' => msg)
+      end
+
+      ceiling = max_limit == NOT_SET ? pagination_max_limit : max_limit
+      if ceiling && parsed_limit > ceiling
+        return default_limit if errors_disabled
+
+        msg = I18n.t('eluvia.errors.pagination.max_limit_exceeded',
+          default: 'Limit %<limit>s exceeds the maximum allowed limit of %<max>s.', limit: parsed_limit, max: ceiling)
+        raise Eluvia::Errors::UnprocessableEntity.new('limit' => msg)
       end
 
+      parsed_limit
     end
 
   end

data/lib/eluvia/locales/cs.yml

@@ -0,0 +1,22 @@
+cs:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Neplatný formát, očekává se "field_name:asc" nebo "field_name:desc".'
+        invalid_direction: "Neplatný směr řazení. Povolené hodnoty jsou `asc` a `desc`."
+        invalid_definition: "Neplatná definice atributu `order by`. Očekává se pouze jeden oddělovač `__`."
+        association_not_found: "Asociace nenalezena."
+        not_found_on_association: "Na asociaci neexistuje."
+        not_found: "Neexistuje."
+      filter:
+        unknown_param: "Neznámý parametr filtru."
+        invalid_term: "Neplatný filtrovací výraz."
+        invalid_value_format: "Neplatný formát hodnoty."
+        invalid_uuid_format: "Neplatný formát UUID."
+        invalid_integer_format: "Neplatný formát celého čísla."
+        invalid_date_format: "Neplatný formát data."
+      fieldset:
+        unknown_field: "Neznámé pole."
+      pagination:
+        invalid_limit: "Limit musí být kladné celé číslo, zadáno %<limit>s."
+        max_limit_exceeded: "Limit %<limit>s překračuje maximální povolený limit %<max>s."

data/lib/eluvia/locales/de.yml

@@ -0,0 +1,22 @@
+de:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Ungültiges Format, erwartet wird "field_name:asc" oder "field_name:desc".'
+        invalid_direction: "Ungültige Sortierrichtung. Erlaubte Werte sind `asc` und `desc`."
+        invalid_definition: "Ungültige Definition für ein `order by`-Attribut. Es wird genau ein `__`-Trennzeichen erwartet."
+        association_not_found: "Assoziation nicht gefunden."
+        not_found_on_association: "Existiert nicht in der Assoziation."
+        not_found: "Existiert nicht."
+      filter:
+        unknown_param: "Unbekannter Filterparameter."
+        invalid_term: "Ungültiger Filterbegriff."
+        invalid_value_format: "Ungültiges Wertformat."
+        invalid_uuid_format: "Ungültiges UUID-Format."
+        invalid_integer_format: "Ungültiges Ganzzahlformat."
+        invalid_date_format: "Ungültiges Datumsformat."
+      fieldset:
+        unknown_field: "Unbekanntes Feld."
+      pagination:
+        invalid_limit: "Limit muss eine positive Ganzzahl sein, erhalten: %<limit>s."
+        max_limit_exceeded: "Limit %<limit>s überschreitet das maximal zulässige Limit von %<max>s."

data/lib/eluvia/locales/en.yml

@@ -0,0 +1,25 @@
+# Translations for the validation error messages raised by eluvia-base (ordering.rb, filtering.rb,
+# fieldset_serializer.rb, pagination_handler.rb). Each key mirrors the `default:` string passed to
+# `I18n.t` at the call site, so a host app without these locale files still gets the same English text.
+en:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Invalid format, expected "field_name:asc" or "field_name:desc".'
+        invalid_direction: "Invalid order direction. Allowed values are `asc` and `desc`."
+        invalid_definition: "Invalid definition for an `order by` attribute. Expecting only one `__` delimiter."
+        association_not_found: "Association not found."
+        not_found_on_association: "Does not exist on association."
+        not_found: "Does not exist."
+      filter:
+        unknown_param: "Unknown filter param."
+        invalid_term: "Invalid filter term."
+        invalid_value_format: "Invalid value format."
+        invalid_uuid_format: "Invalid UUID format."
+        invalid_integer_format: "Invalid integer format."
+        invalid_date_format: "Invalid date format."
+      fieldset:
+        unknown_field: "Unknown field."
+      pagination:
+        invalid_limit: "Limit must be a positive integer, got %<limit>s."
+        max_limit_exceeded: "Limit %<limit>s exceeds the maximum allowed limit of %<max>s."

data/lib/eluvia/locales/es.yml

@@ -0,0 +1,22 @@
+es:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Formato no válido, se espera "field_name:asc" o "field_name:desc".'
+        invalid_direction: "Dirección de ordenación no válida. Los valores permitidos son `asc` y `desc`."
+        invalid_definition: "Definición no válida para un atributo `order by`. Se espera solo un delimitador `__`."
+        association_not_found: "Asociación no encontrada."
+        not_found_on_association: "No existe en la asociación."
+        not_found: "No existe."
+      filter:
+        unknown_param: "Parámetro de filtro desconocido."
+        invalid_term: "Término de filtro no válido."
+        invalid_value_format: "Formato de valor no válido."
+        invalid_uuid_format: "Formato de UUID no válido."
+        invalid_integer_format: "Formato de número entero no válido."
+        invalid_date_format: "Formato de fecha no válido."
+      fieldset:
+        unknown_field: "Campo desconocido."
+      pagination:
+        invalid_limit: "El límite debe ser un número entero positivo, recibido %<limit>s."
+        max_limit_exceeded: "El límite %<limit>s supera el límite máximo permitido de %<max>s."

data/lib/eluvia/locales/fr.yml

@@ -0,0 +1,22 @@
+fr:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Format invalide, attendu "field_name:asc" ou "field_name:desc".'
+        invalid_direction: "Direction de tri invalide. Les valeurs autorisées sont `asc` et `desc`."
+        invalid_definition: "Définition invalide pour un attribut `order by`. Un seul délimiteur `__` est attendu."
+        association_not_found: "Association introuvable."
+        not_found_on_association: "N'existe pas sur l'association."
+        not_found: "N'existe pas."
+      filter:
+        unknown_param: "Paramètre de filtre inconnu."
+        invalid_term: "Terme de filtre invalide."
+        invalid_value_format: "Format de valeur invalide."
+        invalid_uuid_format: "Format UUID invalide."
+        invalid_integer_format: "Format d'entier invalide."
+        invalid_date_format: "Format de date invalide."
+      fieldset:
+        unknown_field: "Champ inconnu."
+      pagination:
+        invalid_limit: "La limite doit être un entier positif, valeur reçue %<limit>s."
+        max_limit_exceeded: "La limite %<limit>s dépasse la limite maximale autorisée de %<max>s."

data/lib/eluvia/locales/it.yml

@@ -0,0 +1,22 @@
+it:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Formato non valido, previsto "field_name:asc" oppure "field_name:desc".'
+        invalid_direction: "Direzione di ordinamento non valida. I valori consentiti sono `asc` e `desc`."
+        invalid_definition: "Definizione non valida per un attributo `order by`. È previsto un solo delimitatore `__`."
+        association_not_found: "Associazione non trovata."
+        not_found_on_association: "Non esiste nell'associazione."
+        not_found: "Non esiste."
+      filter:
+        unknown_param: "Parametro di filtro sconosciuto."
+        invalid_term: "Termine di filtro non valido."
+        invalid_value_format: "Formato del valore non valido."
+        invalid_uuid_format: "Formato UUID non valido."
+        invalid_integer_format: "Formato numero intero non valido."
+        invalid_date_format: "Formato data non valido."
+      fieldset:
+        unknown_field: "Campo sconosciuto."
+      pagination:
+        invalid_limit: "Il limite deve essere un numero intero positivo, ricevuto %<limit>s."
+        max_limit_exceeded: "Il limite %<limit>s supera il limite massimo consentito di %<max>s."

data/lib/eluvia/locales/ja.yml

@@ -0,0 +1,22 @@
+ja:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: '形式が無効です。"field_name:asc" または "field_name:desc" を指定してください。'
+        invalid_direction: "並び順が無効です。使用できる値は `asc` と `desc` です。"
+        invalid_definition: "`order by` 属性の定義が無効です。`__` 区切り文字は1つだけ使用できます。"
+        association_not_found: "アソシエーションが見つかりません。"
+        not_found_on_association: "アソシエーション上に存在しません。"
+        not_found: "存在しません。"
+      filter:
+        unknown_param: "不明なフィルターパラメータです。"
+        invalid_term: "フィルター条件が無効です。"
+        invalid_value_format: "値の形式が無効です。"
+        invalid_uuid_format: "UUID の形式が無効です。"
+        invalid_integer_format: "整数の形式が無効です。"
+        invalid_date_format: "日付の形式が無効です。"
+      fieldset:
+        unknown_field: "不明なフィールドです。"
+      pagination:
+        invalid_limit: "limit は正の整数である必要があります（指定値: %<limit>s）。"
+        max_limit_exceeded: "limit %<limit>s は許可されている最大値 %<max>s を超えています。"

data/lib/eluvia/locales/nl.yml

@@ -0,0 +1,22 @@
+nl:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Ongeldig formaat, verwacht wordt "field_name:asc" of "field_name:desc".'
+        invalid_direction: "Ongeldige sorteerrichting. Toegestane waarden zijn `asc` en `desc`."
+        invalid_definition: "Ongeldige definitie voor een `order by`-attribuut. Er wordt precies één `__`-scheidingsteken verwacht."
+        association_not_found: "Associatie niet gevonden."
+        not_found_on_association: "Bestaat niet binnen de associatie."
+        not_found: "Bestaat niet."
+      filter:
+        unknown_param: "Onbekende filterparameter."
+        invalid_term: "Ongeldige filterterm."
+        invalid_value_format: "Ongeldig waardeformaat."
+        invalid_uuid_format: "Ongeldig UUID-formaat."
+        invalid_integer_format: "Ongeldig geheel-getalformaat."
+        invalid_date_format: "Ongeldig datumformaat."
+      fieldset:
+        unknown_field: "Onbekend veld."
+      pagination:
+        invalid_limit: "Limit moet een positief geheel getal zijn, ontvangen: %<limit>s."
+        max_limit_exceeded: "Limit %<limit>s overschrijdt de maximaal toegestane limiet van %<max>s."

data/lib/eluvia/locales/pl.yml

@@ -0,0 +1,22 @@
+pl:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Nieprawidłowy format, oczekiwano "field_name:asc" lub "field_name:desc".'
+        invalid_direction: "Nieprawidłowy kierunek sortowania. Dozwolone wartości to `asc` i `desc`."
+        invalid_definition: "Nieprawidłowa definicja atrybutu `order by`. Oczekiwany jest dokładnie jeden separator `__`."
+        association_not_found: "Nie znaleziono powiązania."
+        not_found_on_association: "Nie istnieje w powiązaniu."
+        not_found: "Nie istnieje."
+      filter:
+        unknown_param: "Nieznany parametr filtra."
+        invalid_term: "Nieprawidłowy termin filtra."
+        invalid_value_format: "Nieprawidłowy format wartości."
+        invalid_uuid_format: "Nieprawidłowy format UUID."
+        invalid_integer_format: "Nieprawidłowy format liczby całkowitej."
+        invalid_date_format: "Nieprawidłowy format daty."
+      fieldset:
+        unknown_field: "Nieznane pole."
+      pagination:
+        invalid_limit: "Limit musi być dodatnią liczbą całkowitą, otrzymano %<limit>s."
+        max_limit_exceeded: "Limit %<limit>s przekracza maksymalny dozwolony limit %<max>s."

data/lib/eluvia/locales/pt.yml

@@ -0,0 +1,22 @@
+pt:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Formato inválido, esperado "field_name:asc" ou "field_name:desc".'
+        invalid_direction: "Direção de ordenação inválida. Os valores permitidos são `asc` e `desc`."
+        invalid_definition: "Definição inválida para o atributo `order by`. É esperado apenas um delimitador `__`."
+        association_not_found: "Associação não encontrada."
+        not_found_on_association: "Não existe na associação."
+        not_found: "Não existe."
+      filter:
+        unknown_param: "Parâmetro de filtro desconhecido."
+        invalid_term: "Termo de filtro inválido."
+        invalid_value_format: "Formato de valor inválido."
+        invalid_uuid_format: "Formato de UUID inválido."
+        invalid_integer_format: "Formato de número inteiro inválido."
+        invalid_date_format: "Formato de data inválido."
+      fieldset:
+        unknown_field: "Campo desconhecido."
+      pagination:
+        invalid_limit: "O limite deve ser um número inteiro positivo, recebido %<limit>s."
+        max_limit_exceeded: "O limite %<limit>s excede o limite máximo permitido de %<max>s."

data/lib/eluvia/locales/ro.yml

@@ -0,0 +1,22 @@
+ro:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Format invalid, se așteaptă "field_name:asc" sau "field_name:desc".'
+        invalid_direction: "Direcție de sortare invalidă. Valorile permise sunt `asc` și `desc`."
+        invalid_definition: "Definiție invalidă pentru atributul `order by`. Este permis un singur delimitator `__`."
+        association_not_found: "Asocierea nu a fost găsită."
+        not_found_on_association: "Nu există în asociere."
+        not_found: "Nu există."
+      filter:
+        unknown_param: "Parametru de filtrare necunoscut."
+        invalid_term: "Termen de filtrare invalid."
+        invalid_value_format: "Format de valoare invalid."
+        invalid_uuid_format: "Format UUID invalid."
+        invalid_integer_format: "Format de număr întreg invalid."
+        invalid_date_format: "Format de dată invalid."
+      fieldset:
+        unknown_field: "Câmp necunoscut."
+      pagination:
+        invalid_limit: "Limita trebuie să fie un număr întreg pozitiv, valoare primită %<limit>s."
+        max_limit_exceeded: "Limita %<limit>s depășește limita maximă permisă de %<max>s."

data/lib/eluvia/locales/sk.yml

@@ -0,0 +1,22 @@
+sk:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Neplatný formát, očakáva sa "field_name:asc" alebo "field_name:desc".'
+        invalid_direction: "Neplatný smer radenia. Povolené hodnoty sú `asc` a `desc`."
+        invalid_definition: "Neplatná definícia atribútu `order by`. Očakáva sa iba jeden oddeľovač `__`."
+        association_not_found: "Asociácia nebola nájdená."
+        not_found_on_association: "Na asociácii neexistuje."
+        not_found: "Neexistuje."
+      filter:
+        unknown_param: "Neznámy parameter filtra."
+        invalid_term: "Neplatný filtrovací výraz."
+        invalid_value_format: "Neplatný formát hodnoty."
+        invalid_uuid_format: "Neplatný formát UUID."
+        invalid_integer_format: "Neplatný formát celého čísla."
+        invalid_date_format: "Neplatný formát dátumu."
+      fieldset:
+        unknown_field: "Neznáme pole."
+      pagination:
+        invalid_limit: "Limit musí byť kladné celé číslo, zadané %<limit>s."
+        max_limit_exceeded: "Limit %<limit>s prekračuje maximálny povolený limit %<max>s."

data/lib/eluvia/locales/uk.yml

@@ -0,0 +1,22 @@
+uk:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Недійсний формат, очікується "field_name:asc" або "field_name:desc".'
+        invalid_direction: "Недійсний напрямок сортування. Дозволені значення: `asc` і `desc`."
+        invalid_definition: "Недійсне визначення атрибута `order by`. Очікується рівно один роздільник `__`."
+        association_not_found: "Асоціацію не знайдено."
+        not_found_on_association: "Не існує в асоціації."
+        not_found: "Не існує."
+      filter:
+        unknown_param: "Невідомий параметр фільтра."
+        invalid_term: "Недійсний термін фільтра."
+        invalid_value_format: "Недійсний формат значення."
+        invalid_uuid_format: "Недійсний формат UUID."
+        invalid_integer_format: "Недійсний формат цілого числа."
+        invalid_date_format: "Недійсний формат дати."
+      fieldset:
+        unknown_field: "Невідоме поле."
+      pagination:
+        invalid_limit: "Ліміт має бути додатним цілим числом, отримано %<limit>s."
+        max_limit_exceeded: "Ліміт %<limit>s перевищує максимально допустимий ліміт %<max>s."

data/lib/eluvia-base.rb

@@ -4,6 +4,9 @@ require 'eluvia/base/config'
 # Version
 require 'eluvia/base/version'
 
+# Locales (translations for the validation error messages raised across this gem)
+I18n.load_path += Dir[File.expand_path('eluvia/locales/*.yml', __dir__)]
+
 # Uploads
 require 'eluvia/uploads'
 
@@ -17,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.38.0
+  version: 3.40.0
 platform: ruby
 authors:
 - Matěj Outlý
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-14 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
@@ -117,6 +131,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/eluvia-base.rb
@@ -127,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
@@ -149,6 +165,19 @@ files:
 - lib/eluvia/handlers/params_handler.rb
 - lib/eluvia/helpers/attachment_helper.rb
 - lib/eluvia/integrations/eluvia_integration.rb
+- lib/eluvia/locales/cs.yml
+- lib/eluvia/locales/de.yml
+- lib/eluvia/locales/en.yml
+- lib/eluvia/locales/es.yml
+- lib/eluvia/locales/fr.yml
+- lib/eluvia/locales/it.yml
+- lib/eluvia/locales/ja.yml
+- lib/eluvia/locales/nl.yml
+- lib/eluvia/locales/pl.yml
+- lib/eluvia/locales/pt.yml
+- lib/eluvia/locales/ro.yml
+- lib/eluvia/locales/sk.yml
+- lib/eluvia/locales/uk.yml
 - lib/eluvia/models/file.rb
 - lib/eluvia/models/file_wrapper.rb
 - lib/eluvia/models/image_wrapper.rb