habarico 7.2.0.pre.beta.5

data/lib/habarico/contrib/preferences/errors.rb

@@ -0,0 +1,79 @@
+module Habarico
+  module Contrib
+    module Preferences
+      # Base class for all preference errors.
+      class PreferenceError < StandardError; end
+
+      # Raised when a key is neither registered exactly nor matched by a pattern.
+      class PreferenceNotRegistered < PreferenceError
+        attr_reader :key
+
+        def initialize(key)
+          @key = key
+          super(%(Preference key "#{key}" is not registered.))
+        end
+      end
+
+      # Raised when the same exact key is registered twice.
+      class PreferenceAlreadyRegistered < PreferenceError
+        attr_reader :key
+
+        def initialize(key)
+          @key = key
+          super(%(Preference key "#{key}" is already registered.))
+        end
+      end
+
+      # Raised when a key does not match the allowed key format.
+      class InvalidPreferenceKey < PreferenceError
+        attr_reader :key
+
+        def initialize(key)
+          @key = key
+          super(
+            %(Preference key "#{key}" is invalid. Keys must match ) +
+              %("^[a-zA-Z][a-zA-Z0-9_./-]*$" (ASCII letters, digits, underscore, dot, ) +
+              %(slash, hyphen; must start with a letter).)
+          )
+        end
+      end
+
+      # Base for the size and count guards. Both surface as 422, like a schema mismatch.
+      class PreferenceLimitExceeded < PreferenceError; end
+
+      # Raised when a value serializes to more bytes than the key's limit allows.
+      class PreferenceValueTooLarge < PreferenceLimitExceeded
+        attr_reader :key, :limit, :actual
+
+        def initialize(key, limit, actual)
+          @key = key
+          @limit = limit
+          @actual = actual
+          super(%(Value for preference "#{key}" is #{actual} bytes, over the #{limit} byte limit.))
+        end
+      end
+
+      # Raised when storing a new key would take a user past `max_keys_per_user`.
+      class TooManyPreferences < PreferenceLimitExceeded
+        attr_reader :key, :limit
+
+        def initialize(key, limit)
+          @key = key
+          @limit = limit
+          super(%(Cannot store preference "#{key}": the limit of #{limit} preferences per user is already reached.))
+        end
+      end
+
+      # Raised when a value fails JSON Schema validation for its key.
+      class PreferenceValidationError < PreferenceError
+        attr_reader :key, :validation_message
+
+        def initialize(key, message)
+          @key = key
+          @validation_message = message
+          super(%(Value for preference "#{key}" failed validation: #{message}))
+        end
+      end
+    end
+  end
+end

data/lib/habarico/contrib/preferences/locales/cs.yml

@@ -0,0 +1,8 @@
+cs:
+  habarico:
+    contrib:
+      preferences:
+        not_found: "Předvolba nenalezena."
+        invalid_value: "Neplatná hodnota předvolby."
+        value_too_large: "Hodnota předvolby je příliš velká."
+        too_many_preferences: "Pro tohoto uživatele je uloženo příliš mnoho předvoleb."

data/lib/habarico/contrib/preferences/locales/de.yml

@@ -0,0 +1,8 @@
+de:
+  habarico:
+    contrib:
+      preferences:
+        not_found: "Einstellung nicht gefunden."
+        invalid_value: "Ungültiger Wert für die Einstellung."
+        value_too_large: "Der Wert der Einstellung ist zu groß."
+        too_many_preferences: "Für diesen Benutzer sind zu viele Einstellungen gespeichert."

data/lib/habarico/contrib/preferences/locales/en.yml

@@ -0,0 +1,8 @@
+en:
+  habarico:
+    contrib:
+      preferences:
+        not_found: "Preference not found."
+        invalid_value: "Invalid value for preference."
+        value_too_large: "Preference value is too large."
+        too_many_preferences: "Too many preferences are stored for this user."

data/lib/habarico/contrib/preferences/locales/es.yml

@@ -0,0 +1,8 @@
+es:
+  habarico:
+    contrib:
+      preferences:
+        not_found: "Preferencia no encontrada."
+        invalid_value: "Valor no válido para la preferencia."
+        value_too_large: "El valor de la preferencia es demasiado grande."
+        too_many_preferences: "Hay demasiadas preferencias almacenadas para este usuario."

data/lib/habarico/contrib/preferences/locales/fr.yml

@@ -0,0 +1,8 @@
+fr:
+  habarico:
+    contrib:
+      preferences:
+        not_found: "Préférence introuvable."
+        invalid_value: "Valeur non valide pour la préférence."
+        value_too_large: "La valeur de la préférence est trop volumineuse."
+        too_many_preferences: "Trop de préférences sont enregistrées pour cet utilisateur."

data/lib/habarico/contrib/preferences/locales/it.yml

@@ -0,0 +1,8 @@
+it:
+  habarico:
+    contrib:
+      preferences:
+        not_found: "Preferenza non trovata."
+        invalid_value: "Valore non valido per la preferenza."
+        value_too_large: "Il valore della preferenza è troppo grande."
+        too_many_preferences: "Sono memorizzate troppe preferenze per questo utente."

data/lib/habarico/contrib/preferences/locales/ja.yml

@@ -0,0 +1,8 @@
+ja:
+  habarico:
+    contrib:
+      preferences:
+        not_found: "設定が見つかりません。"
+        invalid_value: "設定の値が無効です。"
+        value_too_large: "設定の値が大きすぎます。"
+        too_many_preferences: "このユーザーに保存されている設定が多すぎます。"

data/lib/habarico/contrib/preferences/locales/nl.yml

@@ -0,0 +1,8 @@
+nl:
+  habarico:
+    contrib:
+      preferences:
+        not_found: "Voorkeur niet gevonden."
+        invalid_value: "Ongeldige waarde voor voorkeur."
+        value_too_large: "De waarde van de voorkeur is te groot."
+        too_many_preferences: "Er zijn te veel voorkeuren opgeslagen voor deze gebruiker."

data/lib/habarico/contrib/preferences/locales/pl.yml

@@ -0,0 +1,8 @@
+pl:
+  habarico:
+    contrib:
+      preferences:
+        not_found: "Nie znaleziono preferencji."
+        invalid_value: "Nieprawidłowa wartość preferencji."
+        value_too_large: "Wartość preferencji jest zbyt duża."
+        too_many_preferences: "Dla tego użytkownika zapisano zbyt wiele preferencji."

data/lib/habarico/contrib/preferences/locales/pt.yml

@@ -0,0 +1,8 @@
+pt:
+  habarico:
+    contrib:
+      preferences:
+        not_found: "Preferência não encontrada."
+        invalid_value: "Valor inválido para a preferência."
+        value_too_large: "O valor da preferência é demasiado grande."
+        too_many_preferences: "Estão armazenadas demasiadas preferências para este utilizador."

data/lib/habarico/contrib/preferences/locales/ro.yml

@@ -0,0 +1,8 @@
+ro:
+  habarico:
+    contrib:
+      preferences:
+        not_found: "Preferința nu a fost găsită."
+        invalid_value: "Valoare invalidă pentru preferință."
+        value_too_large: "Valoarea preferinței este prea mare."
+        too_many_preferences: "Sunt stocate prea multe preferințe pentru acest utilizator."

data/lib/habarico/contrib/preferences/locales/sk.yml

@@ -0,0 +1,8 @@
+sk:
+  habarico:
+    contrib:
+      preferences:
+        not_found: "Predvoľba sa nenašla."
+        invalid_value: "Neplatná hodnota predvoľby."
+        value_too_large: "Hodnota predvoľby je príliš veľká."
+        too_many_preferences: "Pre tohto používateľa je uložených príliš veľa predvolieb."

data/lib/habarico/contrib/preferences/locales/uk.yml

@@ -0,0 +1,8 @@
+uk:
+  habarico:
+    contrib:
+      preferences:
+        not_found: "Налаштування не знайдено."
+        invalid_value: "Недійсне значення налаштування."
+        value_too_large: "Значення налаштування завелике."
+        too_many_preferences: "Для цього користувача збережено забагато налаштувань."

data/lib/habarico/contrib/preferences/registry.rb

@@ -0,0 +1,293 @@
+require "json"
+require "json_schemer"
+require "securerandom"
+require "habarico/contrib/preferences/errors"
+
+module Habarico
+  module Contrib
+    module Preferences
+      # Regex a preference key must match. Mirrors the Python KEY_PATTERN.
+      KEY_PATTERN = %r{\A[a-zA-Z][a-zA-Z0-9_./-]*\z}
+
+      # Sentinel meaning "no default registered". Distinct from nil, which is a valid
+      # stored/default value.
+      EMPTY = Object.new
+      def EMPTY.inspect = "EMPTY"
+
+      # Value object returned by get_value/get_values/set_value.
+      ResolvedPreference = Struct.new(:key, :value, :updated_at, keyword_init: true)
+
+      # One registered entry: its JSON Schema, its (possibly EMPTY/callable) default, a compiled
+      # json_schemer validator and its already-resolved size limit (nil meaning unlimited).
+      #
+      # `max_bytes` needs no sentinel, unlike `default`: nil is not a usable size, so it simply
+      # means "not given at registration" and defers to `max_value_bytes`. It is resolved once, at
+      # registration, exactly like `defaults` - nothing reads the configuration per write.
+      Entry = Struct.new(:schema, :default, :validator, :max_bytes, keyword_init: true)
+
+      class PreferenceRegistry
+        def initialize
+          @entries = {}          # key (String) => Entry
+          @pattern_entries = []  # [[Regexp, Entry], ...]
+        end
+
+        # Test/reload hook.
+        def _clear
+          @entries.clear
+          @pattern_entries.clear
+        end
+
+        def register(key, schema:, default: EMPTY, max_bytes: nil)
+          raise InvalidPreferenceKey, key unless key.is_a?(String) && key.match?(KEY_PATTERN)
+          raise PreferenceAlreadyRegistered, key if @entries.key?(key)
+
+          @entries[key] = build_entry(key, schema, default, max_bytes)
+          nil
+        end
+
+        def register_pattern(pattern, schema:, max_bytes: nil)
+          # A pattern entry never carries a default - there is no single key to attach one to - so
+          # `build_entry` returns on its EMPTY branch without validating anything. Same entry, one
+          # place: the two registration paths cannot drift when a field is added to `Entry`.
+          compiled = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern)
+          @pattern_entries << [compiled, build_entry(compiled.source, schema, EMPTY, max_bytes)]
+          nil
+        end
+
+        def registered?(key)
+          return true if @entries.key?(key)
+
+          @pattern_entries.any? { |pattern, _| full_match?(pattern, key) }
+        end
+
+        def get_schema(key)
+          entry_for(key).schema
+        end
+
+        def get_default(key)
+          default = resolve_default(entry_for(key))
+          default.equal?(EMPTY) ? nil : default
+        end
+
+        # Size limit in bytes for a key, or nil when it is unlimited.
+        def max_bytes_for(key)
+          entry_for(key).max_bytes
+        end
+
+        def validate(key, value)
+          entry = entry_for(key)
+          ensure_size_allowed!(key, entry, value)
+          errors = entry.validator.validate(value).to_a
+          raise PreferenceValidationError.new(key, errors.first&.dig("error").to_s) unless errors.empty?
+
+          value
+        end
+
+        def get_value(user_id, key)
+          entry = entry_for(key)
+          record = UserPreference.find_by(user_id: user_id, key: key)
+          resolve(key, entry, record)
+        end
+
+        def get_values(user_id)
+          resolved = {}
+
+          UserPreference.where(user_id: user_id).find_each do |record|
+            entry = begin
+              entry_for(record.key)
+            rescue PreferenceNotRegistered
+              record.destroy
+              next
+            end
+            item = resolve(record.key, entry, record)
+            resolved[record.key] = item if item
+          end
+
+          @entries.each do |key, entry|
+            next if resolved.key?(key)
+
+            item = resolve(key, entry, nil)
+            resolved[key] = item if item
+          end
+
+          resolved.keys.sort.map { |key| resolved[key] }
+        end
+
+        def set_value(user_id, key, value)
+          validate(key, value)
+          ensure_key_budget!(user_id, key)
+          record = UserPreference.find_or_initialize_by(user_id: user_id, key: key)
+          record.id ||= SecureRandom.uuid
+          record.value = value
+          record.updated_at = Time.current
+          record.save!
+          ResolvedPreference.new(key: key, value: record.value, updated_at: record.updated_at)
+        end
+
+        def delete_value(user_id, key)
+          entry_for(key) # raises PreferenceNotRegistered for unknown keys
+          UserPreference.where(user_id: user_id, key: key).delete_all
+          nil
+        end
+
+        def delete_values(user_id)
+          UserPreference.where(user_id: user_id).delete_all
+          nil
+        end
+
+        private
+
+        # Ahead of the schema: the size guard is the cheap check and the one that has to hold for
+        # free-form branches (a saved query's `filter`) the schema does not bound at all.
+        def ensure_size_allowed!(key, entry, value)
+          limit = entry.max_bytes
+          return if limit.nil?
+
+          size = JSON.generate(value).bytesize
+          raise PreferenceValueTooLarge.new(key, limit, size) if size > limit
+        end
+
+        # Configured limit for the key - or pattern - a preference is being registered under. An
+        # explicit `max_bytes:` wins; otherwise `max_value_bytes` decides, by the very string the
+        # preference is registered under, falling back to its "default" entry; a nil there means
+        # unlimited. A pattern may be configured as a Regexp or as its source string. Read once, at
+        # registration, exactly like `defaults`: changing the config afterwards does not move an
+        # already-registered limit.
+        def resolve_max_bytes(registered_as, max_bytes)
+          return max_bytes unless max_bytes.nil?
+
+          limits = Preferences.max_value_bytes || {}
+          limits.each do |configured, bytes|
+            name = configured.is_a?(Regexp) ? configured.source : configured.to_s
+            return bytes if name == registered_as
+          end
+          limits["default"]
+        end
+
+        # Refuses a NEW key once the user holds the maximum number of preferences. Overwriting a
+        # key they already have is always allowed, so nobody already past the limit is locked out
+        # of shrinking or fixing what they stored.
+        def ensure_key_budget!(user_id, key)
+          limit = Preferences.max_keys_per_user
+          return if limit.nil?
+
+          every_key_of_user = UserPreference.where(user_id: user_id)
+          # Overwriting a key the user already has adds no row, so it never spends budget - and
+          # without this guard a user sitting exactly at the limit could not rewrite anything.
+          return if every_key_of_user.where(key: key).exists?
+          raise TooManyPreferences.new(key, limit) if every_key_of_user.count >= limit
+        end
+
+        # json_schemer patterns must match the WHOLE key, like Python's fullmatch.
+        def full_match?(pattern, key)
+          match = pattern.match(key)
+          !match.nil? && match[0] == key
+        end
+
+        def entry_for(key)
+          return @entries[key] if @entries.key?(key)
+
+          @pattern_entries.each { |pattern, entry| return entry if full_match?(pattern, key) }
+          raise PreferenceNotRegistered, key
+        end
+
+        def build_entry(key, schema, default, max_bytes = nil)
+          validator = JSONSchemer.schema(schema)
+          entry = Entry.new(schema: schema, default: default, validator: validator,
+                            max_bytes: resolve_max_bytes(key, max_bytes))
+          return entry if default.equal?(EMPTY) || default.respond_to?(:call)
+
+          errors = validator.validate(default).to_a
+          raise PreferenceValidationError.new(key, errors.first&.dig("error").to_s) unless errors.empty?
+
+          entry
+        end
+
+        # Resolves a (possibly callable) default. A callable that returns EMPTY or an
+        # invalid value degrades to EMPTY, mirroring Python `_resolve_default`.
+        def resolve_default(entry)
+          default = entry.default
+          return default unless default.respond_to?(:call)
+
+          resolved = default.call
+          return EMPTY if resolved.equal?(EMPTY)
+          return EMPTY unless entry.validator.valid?(resolved)
+
+          resolved
+        end
+
+        # Mirrors Python `_resolve`: a stored value that fails validation is deleted and the
+        # default is returned instead; when there is neither a valid stored value nor a default,
+        # returns nil (single-GET => 404, list => omit).
+        def resolve(key, entry, record)
+          if record
+            if entry.validator.valid?(record.value)
+              return ResolvedPreference.new(key: key, value: record.value, updated_at: record.updated_at)
+            end
+
+            record.destroy
+          end
+
+          default = resolve_default(entry)
+          return nil if default.equal?(EMPTY)
+
+          ResolvedPreference.new(key: key, value: default, updated_at: nil)
+        end
+      end
+
+      # ---- module-level singleton API (mirrors Python module functions) ----
+
+      def self.registry
+        @registry ||= PreferenceRegistry.new
+      end
+
+      def self.register_preference(key, schema:, default: EMPTY, max_bytes: nil)
+        registry.register(key, schema: schema, default: default, max_bytes: max_bytes)
+      end
+
+      def self.register_preference_pattern(pattern, schema:, max_bytes: nil)
+        registry.register_pattern(pattern, schema: schema, max_bytes: max_bytes)
+      end
+
+      def self.max_bytes_for(key)
+        registry.max_bytes_for(key)
+      end
+
+      def self.registered?(key)
+        registry.registered?(key)
+      end
+
+      def self.get_schema(key)
+        registry.get_schema(key)
+      end
+
+      def self.get_default(key)
+        registry.get_default(key)
+      end
+
+      def self.validate(key, value)
+        registry.validate(key, value)
+      end
+
+      def self.get_value(user_id, key)
+        registry.get_value(user_id, key)
+      end
+
+      def self.get_values(user_id)
+        registry.get_values(user_id)
+      end
+
+      def self.set_value(user_id, key, value)
+        registry.set_value(user_id, key, value)
+      end
+
+      def self.delete_value(user_id, key)
+        registry.delete_value(user_id, key)
+      end
+
+      def self.delete_values(user_id)
+        registry.delete_values(user_id)
+      end
+    end
+  end
+end

data/lib/habarico/contrib/preferences/routes.rb

@@ -0,0 +1,17 @@
+# Registers the user-preferences routes through the RoutingService extension hook, so the
+# host's config/routes.rb (a single `RoutingService.instance.draw_routes`) needs no change.
+# The blocks are drawn at the admin-site root (beside schema/search) - matching the Python
+# AdminSite, where user-preferences lives next to schema/search. RoutingService draws them
+# inside a path-only `scope` (never a `namespace`/`scope module:`), so the controller path
+# must NOT start with a slash: Rails only strips a leading slash when a module scope is
+# active, and raises "is not a supported controller name" otherwise.
+# Keys may contain dots and slashes, so the `:key` segment is a glob with format off.
+Habarico::RoutingService.register_route_block do
+  controller_path = "habarico/contrib/preferences/user_preferences"
+
+  get    "user-preferences",       to: "#{controller_path}#index"
+  delete "user-preferences",       to: "#{controller_path}#destroy_all"
+  get    "user-preferences/*key",  to: "#{controller_path}#show",    format: false
+  put    "user-preferences/*key",  to: "#{controller_path}#update",  format: false
+  delete "user-preferences/*key",  to: "#{controller_path}#destroy", format: false
+end

data/lib/habarico/contrib/preferences/schemas.rb

@@ -0,0 +1,129 @@
+module Habarico
+  module Contrib
+    module Preferences
+      # Built-in preference value schemas, mirroring the pydantic models in the Python
+      # habarico/contrib/preferences/schemas.py. Plain JSON Schema (Draft 2020-12) hashes.
+      module Schemas
+        THEME = { "enum" => %w[light dark] }.freeze
+        LOCALE = { "type" => "string" }.freeze
+        APP_PAGE_WIDTH = { "enum" => %w[full centered] }.freeze
+        CONTRAST_MODE = { "type" => "boolean" }.freeze
+        STRIPED_ROWS = { "type" => "boolean" }.freeze
+        APP_DENSITY = { "enum" => %w[compact standard comfortable] }.freeze
+
+        COLUMNS = { "type" => "array", "items" => { "type" => "string" } }.freeze
+
+        COLUMN_WIDTHS = {
+          "type" => "object",
+          "additionalProperties" => { "type" => "number", "minimum" => 0 },
+        }.freeze
+
+        SORT = {
+          "type" => "object",
+          "required" => %w[field order],
+          "properties" => {
+            "field" => { "type" => "string" },
+            "order" => { "enum" => %w[ASC DESC] },
+          },
+        }.freeze
+
+        SAVED_QUERIES = {
+          "type" => "array",
+          "items" => {
+            "type" => "object",
+            "required" => %w[label],
+            "properties" => {
+              "label" => { "type" => "string" },
+              "value" => {
+                "type" => "object",
+                "properties" => {
+                  "filter" => { "type" => "object" },
+                  "displayedFilters" => { "type" => "object", "additionalProperties" => { "type" => "boolean" } },
+                  "sort" => { "anyOf" => [SORT, { "type" => "null" }] },
+                  "perPage" => { "type" => %w[integer null], "minimum" => 1 },
+                },
+              },
+            },
+          },
+        }.freeze
+
+        WIDGET_LAYOUT = {
+          "type" => "object",
+          "required" => %w[x y w h],
+          "properties" => {
+            "x" => { "type" => "integer", "minimum" => 0 },
+            "y" => { "type" => "integer", "minimum" => 0 },
+            "w" => { "type" => "integer", "minimum" => 1 },
+            "h" => { "type" => "integer", "minimum" => 1 },
+          },
+        }.freeze
+
+        GROUP_BY_BUCKET = {
+          "oneOf" => [
+            {
+              "type" => "object",
+              "required" => %w[type granularity],
+              "properties" => {
+                "type" => { "const" => "trunc" },
+                "granularity" => { "enum" => %w[second minute hour day week month quarter year] },
+              },
+            },
+            {
+              "type" => "object",
+              "required" => %w[type size],
+              "properties" => {
+                "type" => { "const" => "width" },
+                "size" => { "type" => "number" },
+              },
+            },
+          ],
+        }.freeze
+
+        GROUP_BY_ITEM = {
+          "type" => "object",
+          "required" => %w[field],
+          "properties" => {
+            "field" => { "type" => "string" },
+            "bucket" => { "anyOf" => [GROUP_BY_BUCKET, { "type" => "null" }] },
+          },
+        }.freeze
+
+        CHART_OPTIONS = {
+          "type" => "object",
+          "properties" => {
+            "orientation" => { "enum" => %w[vertical horizontal] },
+            "variant" => { "enum" => %w[pie doughnut] },
+          },
+        }.freeze
+
+        WIDGET_CONFIG = {
+          "type" => "object",
+          "required" => %w[id type layout],
+          "properties" => {
+            "id" => { "type" => "string" },
+            "type" => { "type" => "string" },
+            "resource" => { "type" => %w[string null] },
+            "label" => { "type" => %w[string null] },
+            "layout" => WIDGET_LAYOUT,
+            "filters" => { "type" => %w[object null], "additionalProperties" => { "type" => "string" } },
+            "sort" => { "anyOf" => [SORT, { "type" => "null" }] },
+            "perPage" => { "type" => %w[integer null], "minimum" => 1 },
+            "columns" => { "type" => %w[array null], "items" => { "type" => "string" } },
+            "field" => { "type" => %w[string null] },
+            "aggregateFunction" => { "type" => %w[string null], "enum" => [nil, "count", "sum", "avg", "min", "max"] },
+            "color" => { "type" => %w[string null], "enum" => [nil, "primary", "secondary", "success", "error", "warning", "info", "inherit"] },
+            "groupBy" => { "type" => %w[array null], "items" => GROUP_BY_ITEM },
+            "chartOptions" => { "anyOf" => [CHART_OPTIONS, { "type" => "null" }] },
+          },
+        }.freeze
+
+        DASHBOARD = {
+          "type" => "object",
+          "properties" => {
+            "widgets" => { "type" => "array", "items" => WIDGET_CONFIG },
+          },
+        }.freeze
+      end
+    end
+  end
+end

data/lib/habarico/contrib/preferences/serializer.rb

@@ -0,0 +1,19 @@
+module Habarico
+  module Contrib
+    module Preferences
+      # Serializes a ResolvedPreference into the API item shape { key, value, updated_at }.
+      # Mirrors the Python UserPreferenceItemSerializer.
+      module Serializer
+        module_function
+
+        def item(resolved)
+          {
+            "key" => resolved.key,
+            "value" => resolved.value,
+            "updated_at" => resolved.updated_at&.iso8601,
+          }
+        end
+      end
+    end
+  end
+end