rsb-settings 0.9.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 76cbb39669f95cda57ffe84f51976a7b1abad0490f0eb10817e1477501883bcf
+  data.tar.gz: ef58b6e75169cd038540c1ac6d5ade7b083c65bc7def22f4969027d579e93df3
+SHA512:
+  metadata.gz: 5aa780a9fb91f29fc9c64ee2c872283e7dd8c3b5c5e1d8ba37a4ba4c063e85bc627374cb2157ace53254927785687f60cdae31dad9a3404e0017a316b9cd6298
+  data.tar.gz: 37ac5f82736660dc1bf7e03111c75e7019dc73e3dbfc8cdf2bb7b0b15abebc1cc78261093e6d0aeba5915e2de785b060276aa22e43baff5ea934af30cce106cd

data/LICENSE

@@ -0,0 +1,15 @@
+Rails SaaS Builder (RSB)
+Copyright (C) 2026 Aleksandr Marchenko
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.

data/README.md

@@ -0,0 +1,71 @@
+# rsb-settings
+
+Foundation gem for Rails SaaS Builder. Provides a dynamic settings system with a schema registry that other gems register with. Settings resolve through a priority chain: database overrides → initializer configuration → environment variables → schema defaults. Includes locale management middleware and SEO helper utilities.
+
+## Installation
+
+### As part of Rails SaaS Builder
+
+```ruby
+gem "rails-saas-builder"
+```
+
+### Standalone
+
+```ruby
+gem "rsb-settings"
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate rsb_settings:install
+rails db:migrate
+```
+
+## Key Features
+
+- Schema-based setting definitions with type validation (string, integer, boolean, float, array, duration)
+- Priority resolution chain: DB → initializer → ENV (`RSB_CATEGORY_KEY`) → default
+- ActiveRecord encryption for sensitive settings
+- Initializer-level locks to prevent runtime changes
+- Change callbacks for reactive updates
+- Grouped settings display for admin UI
+- Locale middleware with cookie/Accept-Language negotiation
+
+## Basic Usage
+
+```ruby
+# Define a settings schema
+RSB::Settings.registry.define("billing") do
+  setting :currency, type: :string, default: "usd"
+  setting :trial_days, type: :integer, default: 14
+end
+
+# Read settings
+RSB::Settings.get("billing.currency")     #=> "usd"
+RSB::Settings.for("billing")              #=> { currency: "usd", trial_days: 14 }
+
+# Write settings (persists to database)
+RSB::Settings.set("billing.currency", "eur")
+```
+
+## Configuration
+
+```ruby
+RSB::Settings.configure do |config|
+  config.set("billing.currency", "eur")    # initializer override
+  config.lock("billing.currency")           # prevent runtime changes
+  config.available_locales = %w[en de fr]
+  config.default_locale = "en"
+end
+```
+
+## Documentation
+
+Part of [Rails SaaS Builder](../README.md). See the main README for the full picture.
+
+## License
+
+[LGPL-3.0](../LICENSE)

data/Rakefile

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'fileutils'
+require 'rake/testtask'
+
+task :prepare_test_db do
+  ENV['RAILS_ENV'] = 'test'
+  db = File.expand_path('test/dummy/db/test.sqlite3', __dir__)
+  FileUtils.rm_f(db)
+  require_relative 'test/dummy/config/environment'
+  ActiveRecord::Migration.verbose = false
+  ActiveRecord::MigrationContext.new(Rails.application.paths['db/migrate'].to_a).migrate
+  schema = File.expand_path('test/dummy/db/schema.rb', __dir__)
+  File.open(schema, 'w') { |f| ActiveRecord::SchemaDumper.dump(ActiveRecord::Base.connection_pool, f) }
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task test: :prepare_test_db
+task default: :test

data/app/models/rsb/settings/setting.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RSB
+  module Settings
+    class Setting < ActiveRecord::Base
+      self.table_name = 'rsb_settings_settings'
+
+      encrypts :value
+
+      validates :category, presence: true
+      validates :key, presence: true, uniqueness: { scope: :category }
+
+      scope :for_category, ->(cat) { where(category: cat.to_s) }
+
+      def self.get(category, key)
+        find_by(category: category.to_s, key: key.to_s)&.value
+      end
+
+      def self.set(category, key, value)
+        record = find_or_initialize_by(category: category.to_s, key: key.to_s)
+        record.update!(value: value.to_s)
+        record
+      end
+    end
+  end
+end

data/db/migrate/20260208000001_create_rsb_settings_settings.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class CreateRSBSettingsSettings < ActiveRecord::Migration[8.0]
+  def change
+    create_table :rsb_settings_settings do |t|
+      t.string :category, null: false
+      t.string :key, null: false
+      t.string :value
+      t.timestamps
+    end
+
+    add_index :rsb_settings_settings, %i[category key], unique: true
+    add_index :rsb_settings_settings, :category
+  end
+end

data/lib/generators/rsb/settings/install/install_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RSB
+  module Settings
+    class InstallGenerator < Rails::Generators::Base
+      namespace 'rsb:settings:install'
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Install rsb-settings: copy migrations, create initializer.'
+
+      def copy_migrations
+        rake 'rsb_settings:install:migrations'
+      end
+
+      def create_initializer
+        template 'initializer.rb', 'config/initializers/rsb_settings.rb'
+      end
+
+      def print_post_install
+        say ''
+        say 'rsb-settings installed successfully!', :green
+        say ''
+        say 'Next steps:'
+        say '  1. rails db:migrate'
+        say '  2. Settings are ready — other RSB gems will register their schemas automatically.'
+        say ''
+      end
+    end
+  end
+end

data/lib/generators/rsb/settings/install/templates/initializer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# RSB Settings configuration
+# See: https://github.com/Rails-SaaS-Builder/rails-saas-builder
+
+RSB::Settings.configure do |config|
+  # Lock settings so they're visible in admin but not editable:
+  # config.lock "auth.registration_mode"
+  # config.lock "entitlements.default_currency"
+
+  # Set initializer-level overrides (takes priority over ENV and defaults):
+  # config.set "auth.registration_mode", "open"
+  # config.set "auth.password_min_length", 10
+end

data/lib/rsb/settings/configuration.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RSB
+  module Settings
+    class Configuration
+      BUILT_IN_LOCALE_NAMES = {
+        'en' => 'English',
+        'de' => 'Deutsch',
+        'fr' => 'Français',
+        'es' => 'Español',
+        'pt' => 'Português',
+        'it' => 'Italiano',
+        'nl' => 'Nederlands',
+        'ja' => '日本語',
+        'zh' => '中文',
+        'ko' => '한국어',
+        'ru' => 'Русский',
+        'ar' => 'العربية',
+        'pl' => 'Polski',
+        'sv' => 'Svenska',
+        'da' => 'Dansk',
+        'nb' => 'Norsk',
+        'fi' => 'Suomi',
+        'cs' => 'Čeština',
+        'tr' => 'Türkçe',
+        'uk' => 'Українська'
+      }.freeze
+
+      attr_accessor :available_locales, :default_locale
+
+      def initialize
+        @overrides = {}  # { "auth.registration_mode" => "open" }
+        @locks = Set.new # { "auth.registration_mode" }
+        @available_locales = ['en']
+        @default_locale = 'en'
+        @custom_locale_display_names = {}
+      end
+
+      def locale_display_names=(names)
+        @custom_locale_display_names = names || {}
+      end
+
+      def locale_display_names
+        BUILT_IN_LOCALE_NAMES.merge(@custom_locale_display_names)
+      end
+
+      # Set an initializer-level override
+      def set(key, value)
+        @overrides[key.to_s] = value
+      end
+
+      # Lock a setting (visible in admin but not editable)
+      def lock(key)
+        @locks << key.to_s
+      end
+
+      def locked?(key)
+        @locks.include?(key.to_s)
+      end
+
+      def locked_keys
+        @locks.to_a
+      end
+
+      # Read initializer override for resolver
+      def initializer_value(category, key)
+        @overrides["#{category}.#{key}"]
+      end
+    end
+  end
+end

data/lib/rsb/settings/engine.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RSB
+  module Settings
+    class Engine < ::Rails::Engine
+      isolate_namespace RSB::Settings
+
+      # Insert locale middleware into the Rails middleware stack.
+      # Applies to all requests (host app + all engines).
+      # Host app can remove: config.middleware.delete RSB::Settings::LocaleMiddleware
+      initializer 'rsb_settings.locale_middleware' do |app|
+        app.middleware.use RSB::Settings::LocaleMiddleware
+      end
+
+      # Signal readiness — downstream gems hook in after this
+      initializer 'rsb_settings.ready' do
+        # Registry is available. Other gems can now register schemas.
+      end
+
+      initializer 'rsb_settings.register_seo_settings', after: 'rsb_settings.ready' do
+        RSB::Settings.registry.register(RSB::Settings::SeoSettingsSchema.build)
+      end
+
+      config.generators do |g|
+        g.test_framework :minitest, fixture: false
+        g.assets false
+        g.helper false
+      end
+    end
+  end
+end

data/lib/rsb/settings/locale_helper.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RSB
+  module Settings
+    module LocaleHelper
+      def rsb_available_locales
+        RSB::Settings.available_locales
+      end
+
+      def rsb_current_locale
+        I18n.locale.to_s
+      end
+
+      def rsb_locale_display_name(code)
+        RSB::Settings.locale_display_name(code)
+      end
+
+      def rsb_locale_switcher(current_path: nil)
+        locales = RSB::Settings.available_locales
+        return ''.html_safe if locales.size <= 1
+
+        path = current_path || (respond_to?(:request) ? request.fullpath : '/')
+        current = rsb_current_locale
+
+        parts = locales.map do |loc|
+          if loc == current
+            %(<span class="rsb-locale-current">#{ERB::Util.html_escape(RSB::Settings.locale_display_name(loc))}</span>)
+          else
+            <<~HTML.strip
+              <form action="/rsb/locale" method="post" style="display:inline">
+                <input type="hidden" name="locale" value="#{ERB::Util.html_escape(loc)}">
+                <input type="hidden" name="redirect_to" value="#{ERB::Util.html_escape(path)}">
+                <button type="submit" class="rsb-locale-link">#{ERB::Util.html_escape(RSB::Settings.locale_display_name(loc))}</button>
+              </form>
+            HTML
+          end
+        end
+
+        %(<nav class="rsb-locale-switcher">#{parts.join(' ')}</nav>).html_safe
+      end
+    end
+  end
+end

data/lib/rsb/settings/locale_middleware.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'rack/request'
+require 'rack/response'
+
+module RSB
+  module Settings
+    # Rack middleware that resolves locale from cookie, Accept-Language header,
+    # or configured default. Also handles POST /rsb/locale to set the locale cookie.
+    #
+    # Resolution chain (highest priority first):
+    #   1. Cookie (rsb_locale)
+    #   2. Accept-Language header (best match from available_locales)
+    #   3. Configured default_locale
+    #
+    # The middleware auto-inserts into the Rails middleware stack via the
+    # rsb_settings engine initializer. Applies to all requests (host app + engines).
+    #
+    # @example Remove from host app if not wanted
+    #   config.middleware.delete RSB::Settings::LocaleMiddleware
+    #
+    class LocaleMiddleware
+      COOKIE_NAME = 'rsb_locale'
+      COOKIE_MAX_AGE = 31_536_000 # 1 year in seconds
+      LOCALE_PATH = '/rsb/locale'
+
+      def initialize(app)
+        @app = app
+      end
+
+      # @param env [Hash] Rack environment
+      # @return [Array] Rack response tuple [status, headers, body]
+      def call(env)
+        request = Rack::Request.new(env)
+
+        # Handle locale switching endpoint
+        return handle_locale_change(request) if request.post? && request.path_info == LOCALE_PATH
+
+        # Resolve and set locale for this request
+        locale = resolve_locale(request)
+        I18n.locale = locale
+        env['rsb.locale'] = locale.to_s
+
+        @app.call(env)
+      ensure
+        I18n.locale = I18n.default_locale
+      end
+
+      private
+
+      # Handles POST /rsb/locale: validates locale, sets cookie, redirects back.
+      #
+      # @param request [Rack::Request]
+      # @return [Array] Rack response tuple
+      def handle_locale_change(request)
+        locale = request.params['locale'].to_s.strip
+        available = RSB::Settings.available_locales
+
+        # Empty locale = redirect without setting cookie
+        return redirect_response(redirect_path(request)) if locale.empty?
+
+        # Invalid locale falls back to default
+        locale = RSB::Settings.default_locale unless available.include?(locale)
+
+        response = Rack::Response.new
+        response.set_cookie(COOKIE_NAME, {
+                              value: locale,
+                              path: '/',
+                              max_age: COOKIE_MAX_AGE,
+                              same_site: :lax,
+                              httponly: false
+                            })
+        response.redirect(redirect_path(request))
+        response.finish
+      end
+
+      # Resolves locale from cookie, Accept-Language, or default.
+      #
+      # @param request [Rack::Request]
+      # @return [String] resolved locale code
+      def resolve_locale(request)
+        available = RSB::Settings.available_locales
+        default = RSB::Settings.default_locale
+
+        # 1. Cookie
+        cookie_locale = request.cookies[COOKIE_NAME].to_s.strip
+        return cookie_locale if cookie_locale.present? && available.include?(cookie_locale)
+
+        # 2. Accept-Language header
+        accept_locale = parse_accept_language(
+          request.env['HTTP_ACCEPT_LANGUAGE'],
+          available
+        )
+        return accept_locale if accept_locale
+
+        # 3. Default
+        default
+      end
+
+      # Parses the Accept-Language header and returns the best match.
+      #
+      # @param header [String, nil] Accept-Language header value
+      # @param available [Array<String>] available locale codes
+      # @return [String, nil] best matching locale or nil
+      def parse_accept_language(header, available)
+        return nil if header.nil? || header.empty?
+
+        locales = header.split(',').filter_map do |part|
+          part = part.strip
+          next if part.empty?
+
+          lang, quality_str = part.split(';', 2)
+          lang = lang.to_s.split('-').first.to_s.downcase.strip
+          next if lang.empty?
+
+          quality = if quality_str
+                      q_match = quality_str.match(/q\s*=\s*([\d.]+)/)
+                      q_match ? q_match[1].to_f : 1.0
+                    else
+                      1.0
+                    end
+
+          [lang, quality]
+        end
+
+        locales
+          .sort_by { |_, q| -q }
+          .each { |lang, _| return lang if available.include?(lang) }
+
+        nil
+      end
+
+      # Determines a safe redirect path from request params or Referer.
+      #
+      # @param request [Rack::Request]
+      # @return [String] safe redirect path (always starts with "/")
+      def redirect_path(request)
+        # 1. redirect_to param
+        redirect_to = request.params['redirect_to'].to_s
+        return redirect_to if redirect_to.start_with?('/') && !redirect_to.start_with?('//')
+
+        # 2. Referer header (extract path only)
+        if request.referrer.present?
+          begin
+            uri = URI.parse(request.referrer)
+            path = uri.path.to_s
+            return path if path.start_with?('/')
+          rescue URI::InvalidURIError
+            # fall through
+          end
+        end
+
+        # 3. Fallback
+        '/'
+      end
+
+      # Creates a simple redirect response without setting a cookie.
+      #
+      # @param path [String] redirect target
+      # @return [Array] Rack response tuple
+      def redirect_response(path)
+        response = Rack::Response.new
+        response.redirect(path)
+        response.finish
+      end
+    end
+  end
+end

data/lib/rsb/settings/registry.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module RSB
+  module Settings
+    class Registry
+      attr_reader :schemas, :change_callbacks
+
+      def initialize
+        @schemas = {}
+        @change_callbacks = {}
+      end
+
+      # Register a schema (from a gem's pure-data definition)
+      def register(schema)
+        raise ArgumentError, "Expected RSB::Settings::Schema, got #{schema.class}" unless schema.is_a?(Schema)
+
+        @schemas[schema.category] = if @schemas[schema.category]
+                                      @schemas[schema.category].merge(schema)
+                                    else
+                                      schema
+                                    end
+      end
+
+      # Convenience: define and register in one step
+      def define(category, &block)
+        schema = Schema.new(category, &block)
+        register(schema)
+        schema
+      end
+
+      # Query
+      def for(category)
+        @schemas[category.to_s]
+      end
+
+      def all
+        @schemas.values
+      end
+
+      def categories
+        @schemas.keys
+      end
+
+      def find_definition(key)
+        category, setting_key = key.to_s.split('.', 2)
+        @schemas[category]&.find(setting_key)
+      end
+
+      # Returns definitions for a category grouped by the `group` field.
+      # Settings with a nil group are placed under "General".
+      # "General" always appears first if present, followed by other groups
+      # in the order their first setting was registered.
+      #
+      # @param category [String] the settings category name
+      # @return [Hash<String, Array<SettingDefinition>>] ordered hash of group name to definitions
+      # @example
+      #   registry.grouped_definitions("auth")
+      #   # => { "General" => [defn1], "Session & Security" => [defn2, defn3], "Registration" => [defn4] }
+      def grouped_definitions(category)
+        schema = @schemas[category.to_s]
+        return {} unless schema
+
+        groups = {}
+        schema.definitions.each do |defn|
+          group_name = defn.group || 'General'
+          groups[group_name] ||= []
+          groups[group_name] << defn
+        end
+
+        # Ensure "General" is first if present
+        return groups unless groups.key?('General') && groups.keys.first != 'General'
+
+        general = groups.delete('General')
+        { 'General' => general }.merge(groups)
+      end
+
+      # Change callbacks
+      def on_change(key, &block)
+        @change_callbacks[key.to_s] ||= []
+        @change_callbacks[key.to_s] << block
+      end
+
+      def fire_change(key, old_value, new_value)
+        callbacks = @change_callbacks[key.to_s] || []
+        callbacks.each { |cb| cb.call(old_value, new_value) }
+      end
+    end
+  end
+end

data/lib/rsb/settings/resolver.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module RSB
+  module Settings
+    class Resolver
+      def initialize(registry:, configuration:)
+        @registry = registry
+        @configuration = configuration
+        @cache = {}
+      end
+
+      def get(category, key)
+        cache_key = "#{category}.#{key}"
+        return @cache[cache_key] if @cache.key?(cache_key)
+
+        value = resolve(category, key)
+        @cache[cache_key] = value
+        value
+      end
+
+      def set(category, key, value)
+        full_key = "#{category}.#{key}"
+        old_value = get(category, key)
+        new_value = value
+
+        Setting.transaction do
+          Setting.set(category, key, value)
+          invalidate(category, key)
+          @registry.fire_change(full_key, old_value, new_value)
+        end
+
+        new_value
+      end
+
+      def for(category)
+        schema = @registry.for(category)
+        return {} unless schema
+
+        schema.definitions.each_with_object({}) do |defn, hash|
+          hash[defn.key] = get(category, defn.key.to_s)
+        end
+      end
+
+      def invalidate(category = nil, key = nil)
+        if category && key
+          @cache.delete("#{category}.#{key}")
+        else
+          @cache.clear
+        end
+      end
+
+      private
+
+      def resolve(category, key)
+        definition = @registry.find_definition("#{category}.#{key}")
+
+        # 1. Database (admin panel / runtime override)
+        db_value = Setting.get(category, key)
+        return cast(db_value, definition) if db_value.present?
+
+        # 2. Initializer (code-level config overrides)
+        init_value = @configuration.initializer_value(category, key)
+        return init_value unless init_value.nil?
+
+        # 3. Environment variable (RSB_AUTH_REGISTRATION_MODE)
+        env_key = "RSB_#{category.to_s.upcase}_#{key.to_s.upcase}"
+        env_value = ENV[env_key]
+        return cast(env_value, definition) if env_value.present?
+
+        # 4. Default (from schema definition)
+        definition&.default
+      end
+
+      def cast(value, definition)
+        return value unless definition
+        return value unless value.is_a?(String)
+
+        case definition.type
+        when :integer then value.to_i
+        when :float then value.to_f
+        when :boolean then ActiveModel::Type::Boolean.new.cast(value)
+        when :symbol then value.to_sym
+        when :string then value.to_s
+        when :array then value.is_a?(Array) ? value : value.split(',').map(&:strip)
+        when :duration then value.to_i.seconds
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/rsb/settings/schema.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RSB
+  module Settings
+    class Schema
+      SettingDefinition = Data.define(
+        :key, :type, :default, :description,
+        :enum, :validates, :encrypted, :locked,
+        :group, :depends_on, :label
+      ) do
+        def initialize(key:, type:, default:, description:, enum:, validates:, encrypted:, locked:, group: nil,
+                       depends_on: nil, label: nil)
+          super
+        end
+      end
+
+      attr_reader :category, :definitions
+
+      def initialize(category, &block)
+        @category = category.to_s
+        @definitions = []
+        instance_eval(&block) if block_given?
+      end
+
+      # Define a setting within this schema.
+      #
+      # @param key [Symbol] setting key within the category
+      # @param type [Symbol] value type (:string, :integer, :boolean, :float, :symbol, :array, :duration)
+      # @param default [Object] default value (nil if not specified)
+      # @param description [String] human-readable description shown in admin UI
+      # @param enum [Array, Proc, nil] allowed values (static array or dynamic proc)
+      # @param validates [Hash, nil] custom validation rules
+      # @param encrypted [Boolean] encrypt value in schema (default: false)
+      # @param locked [Boolean] lock by default, preventing runtime changes (default: false)
+      # @param group [String, nil] subgroup name for admin UI grouping. nil = "General" group
+      # @param depends_on [String, nil] full setting key (e.g., "auth.account_enabled") this setting depends on.
+      #   When the referenced setting resolves to a falsy value, this setting is rendered disabled in the admin UI.
+      # @return [void]
+      def setting(key, type:, default: nil, description: '', enum: nil, validates: nil, encrypted: false,
+                  locked: false, group: nil, depends_on: nil, label: nil)
+        @definitions << SettingDefinition.new(
+          key: key.to_sym,
+          type: type.to_sym,
+          default: default,
+          description: description,
+          enum: enum,
+          validates: validates,
+          encrypted: encrypted,
+          locked: locked,
+          group: group,
+          depends_on: depends_on,
+          label: label
+        )
+      end
+
+      def keys
+        @definitions.map(&:key)
+      end
+
+      def defaults
+        @definitions.each_with_object({}) { |d, h| h[d.key] = d.default }
+      end
+
+      def find(key)
+        @definitions.find { |d| d.key == key.to_sym }
+      end
+
+      def valid?
+        !@category.nil? && !@category.empty? && @definitions.all? { |d| !d.key.nil? && !d.type.nil? }
+      end
+
+      def merge(other_schema)
+        raise ArgumentError, 'Cannot merge schemas from different categories' unless other_schema.category == @category
+
+        merged = Schema.new(@category)
+        merged.instance_variable_set(:@definitions, @definitions + other_schema.definitions)
+        merged
+      end
+    end
+  end
+end

data/lib/rsb/settings/seo_helper.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RSB
+  module Settings
+    module SeoHelper
+      def rsb_seo_title
+        page_title = @rsb_page_title.to_s
+        app_name = RSB::Settings.get('seo.app_name').to_s
+
+        title = if app_name.present? && page_title.present?
+                  format_str = RSB::Settings.get('seo.title_format').to_s
+                  format_str.gsub('%<page_title>s', page_title).gsub('%<app_name>s', app_name)
+                elsif app_name.present?
+                  app_name
+                else
+                  page_title
+                end
+
+        "<title>#{ERB::Util.html_escape(title)}</title>".html_safe
+      end
+
+      def rsb_seo_meta_tags
+        tags = []
+        tags << rsb_seo_title
+
+        is_admin = (@rsb_seo_context == :admin)
+
+        # Meta description (auth only)
+        unless is_admin
+          description = @rsb_meta_description.to_s
+          tags << %(<meta name="description" content="#{ERB::Util.html_escape(description)}" />) if description.present?
+        end
+
+        # Robots
+        if is_admin
+          tags << '<meta name="robots" content="noindex, nofollow" />'
+        elsif RSB::Settings.get('seo.auth_indexable') == false
+          tags << '<meta name="robots" content="noindex, nofollow" />'
+        end
+
+        # Open Graph (auth only)
+        unless is_admin
+          page_title = @rsb_page_title.to_s
+          tags << %(<meta property="og:title" content="#{ERB::Util.html_escape(page_title)}" />) if page_title.present?
+
+          description = @rsb_meta_description.to_s
+          if description.present?
+            tags << %(<meta property="og:description" content="#{ERB::Util.html_escape(description)}" />)
+          end
+
+          tags << '<meta property="og:type" content="website" />'
+
+          if respond_to?(:request) && request.present?
+            canonical = canonical_url
+            tags << %(<meta property="og:url" content="#{ERB::Util.html_escape(canonical)}" />)
+            tags << %(<link rel="canonical" href="#{ERB::Util.html_escape(canonical)}" />)
+          end
+
+          og_image = RSB::Settings.get('seo.og_image_url').to_s
+          tags << %(<meta property="og:image" content="#{ERB::Util.html_escape(og_image)}" />) if og_image.present?
+        end
+
+        tags.join("\n").html_safe
+      end
+
+      def rsb_seo_head_tags
+        value = RSB::Settings.get('seo.head_tags').to_s
+        value.present? ? value.html_safe : ''
+      end
+
+      def rsb_seo_body_tags
+        value = RSB::Settings.get('seo.body_tags').to_s
+        value.present? ? value.html_safe : ''
+      end
+
+      private
+
+      def canonical_url
+        uri = URI.parse(request.original_url)
+        "#{uri.scheme}://#{uri.host}#{":#{uri.port}" unless [80, 443].include?(uri.port)}#{uri.path}"
+      end
+    end
+  end
+end

data/lib/rsb/settings/seo_settings_schema.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RSB
+  module Settings
+    class SeoSettingsSchema
+      # Build the SEO settings schema for the "seo" category.
+      #
+      # @return [RSB::Settings::Schema]
+      def self.build
+        RSB::Settings::Schema.new('seo') do
+          setting :app_name,
+                  type: :string,
+                  default: '',
+                  group: 'General',
+                  description: 'App name used in page title suffix (empty = no suffix)'
+
+          setting :title_format,
+                  type: :string,
+                  default: '%<page_title>s | %<app_name>s',
+                  group: 'General',
+                  description: 'Format pattern for <title> tag (use %<page_title>s and %<app_name>s placeholders)'
+
+          setting :og_image_url,
+                  type: :string,
+                  default: '',
+                  group: 'Open Graph',
+                  description: 'Default Open Graph image URL for social sharing'
+
+          setting :auth_indexable,
+                  type: :boolean,
+                  default: true,
+                  group: 'Robots',
+                  description: 'Allow search engines to index auth pages (login, register, etc.)'
+
+          setting :head_tags,
+                  type: :string,
+                  default: '',
+                  group: 'Script Injection',
+                  description: 'HTML to inject in <head> on all RSB pages (analytics, fonts, etc.)'
+
+          setting :body_tags,
+                  type: :string,
+                  default: '',
+                  group: 'Script Injection',
+                  description: 'HTML to inject before </body> on all RSB pages'
+        end
+      end
+    end
+  end
+end

data/lib/rsb/settings/test_helper.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RSB
+  module Settings
+    module TestHelper
+      extend ActiveSupport::Concern
+
+      included do
+        teardown do
+          RSB::Settings.reset!
+          RSB::Settings::Setting.delete_all if RSB::Settings::Setting.table_exists?
+        end
+      end
+
+      # Temporarily override settings within a block
+      def with_settings(overrides = {})
+        originals = {}
+        overrides.each do |key, value|
+          originals[key] = begin
+            RSB::Settings.get(key)
+          rescue StandardError
+            nil
+          end
+          RSB::Settings.set(key, value)
+        end
+        yield
+      ensure
+        originals.each do |key, value|
+          category, setting_key = key.to_s.split('.', 2)
+          if value.nil?
+            RSB::Settings::Setting.find_by(category: category, key: setting_key)&.destroy
+            # Invalidate cache so the resolver picks up the deletion
+            RSB::Settings.send(:resolver).invalidate(category, setting_key)
+          else
+            RSB::Settings.set(key, value)
+          end
+        end
+      end
+
+      # Register a test schema quickly
+      def register_test_schema(category, **settings)
+        RSB::Settings.registry.define(category) do
+          settings.each do |key, default|
+            type = case default
+                   when Integer then :integer
+                   when true, false then :boolean
+                   when Float then :float
+                   when Symbol then :symbol
+                   when Array then :array
+                   else :string
+                   end
+            setting key, type: type, default: default
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rsb/settings/validation_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RSB
+  module Settings
+    class ValidationError < StandardError; end
+  end
+end

data/lib/rsb/settings/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative '../../../../lib/rsb/version' unless defined?(RSB::VERSION)
+
+module RSB
+  module Settings
+    VERSION = RSB::VERSION
+  end
+end

data/lib/rsb/settings.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'active_support/inflector'
+ActiveSupport::Inflector.inflections(:en) { |inflect| inflect.acronym 'RSB' }
+
+require 'rsb/settings/version'
+require 'rsb/settings/engine'
+require 'rsb/settings/schema'
+require 'rsb/settings/registry'
+require 'rsb/settings/resolver'
+require 'rsb/settings/configuration'
+require 'rsb/settings/validation_error'
+require 'rsb/settings/locale_helper'
+require 'rsb/settings/locale_middleware'
+require 'rsb/settings/seo_settings_schema'
+require 'rsb/settings/seo_helper'
+
+module RSB
+  module Settings
+    class << self
+      # --- Instance-based registry (resettable for tests) ---
+
+      def registry
+        @registry ||= Registry.new
+      end
+
+      # --- Public API ---
+
+      def get(key)
+        category, setting_key = parse_key(key)
+        resolver.get(category, setting_key)
+      end
+
+      def set(key, value)
+        category, setting_key = parse_key(key)
+        resolver.set(category, setting_key, value)
+      end
+
+      def for(category)
+        resolver.for(category)
+      end
+
+      # --- Configuration (locks, initializer overrides) ---
+
+      def configure
+        yield(configuration)
+      end
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Clear the resolver cache. Use after a transaction rollback
+      # to prevent stale cached values from being returned.
+      #
+      # @return [void]
+      def invalidate_cache!
+        resolver.invalidate
+      end
+
+      # --- Locale configuration ---
+
+      def available_locales
+        configuration.available_locales
+      end
+
+      def default_locale
+        configuration.default_locale
+      end
+
+      def locale_display_name(code)
+        configuration.locale_display_names[code.to_s] || code.to_s
+      end
+
+      def locale_display_names
+        configuration.locale_display_names
+      end
+
+      # --- Test support ---
+
+      def reset!
+        @registry = Registry.new
+        @resolver = nil
+        @configuration = Configuration.new
+      end
+
+      private
+
+      def resolver
+        @resolver ||= Resolver.new(registry: registry, configuration: configuration)
+      end
+
+      def parse_key(key)
+        parts = key.to_s.split('.', 2)
+        raise ArgumentError, "Key must be in 'category.key' format, got: #{key}" if parts.size != 2
+
+        parts
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: rsb-settings
+version: !ruby/object:Gem::Version
+  version: 0.9.1
+platform: ruby
+authors:
+- Aleksandr Marchenko
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: Foundation gem for RSB. Provides a dynamic settings system with a schema
+  registry that other gems register with. Settings resolve via DB → initializer →
+  ENV → default.
+email:
+- alex@marchenko.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- app/models/rsb/settings/setting.rb
+- db/migrate/20260208000001_create_rsb_settings_settings.rb
+- lib/generators/rsb/settings/install/install_generator.rb
+- lib/generators/rsb/settings/install/templates/initializer.rb
+- lib/rsb/settings.rb
+- lib/rsb/settings/configuration.rb
+- lib/rsb/settings/engine.rb
+- lib/rsb/settings/locale_helper.rb
+- lib/rsb/settings/locale_middleware.rb
+- lib/rsb/settings/registry.rb
+- lib/rsb/settings/resolver.rb
+- lib/rsb/settings/schema.rb
+- lib/rsb/settings/seo_helper.rb
+- lib/rsb/settings/seo_settings_schema.rb
+- lib/rsb/settings/test_helper.rb
+- lib/rsb/settings/validation_error.rb
+- lib/rsb/settings/version.rb
+homepage: https://github.com/Rails-SaaS-Builder/rails-saas-builder
+licenses:
+- LGPL-3.0
+metadata:
+  source_code_uri: https://github.com/Rails-SaaS-Builder/rails-saas-builder
+  bug_tracker_uri: https://github.com/Rails-SaaS-Builder/rails-saas-builder/issues
+  changelog_uri: https://github.com/Rails-SaaS-Builder/rails-saas-builder/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: Dynamic runtime settings with schema registry for Rails SaaS Builder
+test_files: []