concerns_on_rails 1.12.1 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56664d3e955f53dbeec1d586c31b57c860a208cedff76990236a728de1c6f9ec
-  data.tar.gz: 6a427597a32d8a2d848d2f51ed9cf45d6a3ea41dd9ea77c2b215b4a66846170e
+  metadata.gz: b5c234af5baa9aa52269898bb63da24e4cc373bc5e2b3d7db7467ef89a86141b
+  data.tar.gz: 20cd7d9bb802447d7fd38be485e623216774ffa3dba9d5aae9f225ad48fb0b8a
 SHA512:
-  metadata.gz: b34bc02259d6a33a0d1fa1dac2f2e71473cc543515df2088766b736eed4cdc8e9925616cca6397a5318d22bdcafbf910e8bea6ea9f93e1de4746613f3aa747b2
-  data.tar.gz: 52e3f5a2dda49da303b118a4962ca479bb43b628d363ff133c23939fc523235a01065441cea4002dccd33130ace25149da275ddb9839dc864b2e442377f88a28
+  metadata.gz: ebef3ed5411bf6fa388b9a1d47ab92eb9a871eeda6e478aee4dc0dfd586a10bcbf05497dba93325b896a897a0a0cc3a296ce833aaef72343decacce42c0087aa
+  data.tar.gz: efc7d26aca5aeff71308135c2617374d98ee8c0e955038a783e2b3c8c2b14a1827ae27fd2a7c64d6637e6c2fe61b2711da796f388e172bdc9dac827dc56e6743

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 <!-- CHANGELOG.md -->
 
+## 1.14.0 (2026-06-06)
+
+### Added
+- **Controllers::Authorizable**: declarative, block-only per-action authorization gate. `authorize_by { current_user.admin? }` (arity-safe — also `|action|` / `|action, user|`) halts the first failing rule with 403; `require_role :admin, :editor, only: :publish` is sugar over the common role check. `only:` / `except:` scope a rule to a subset of actions. When `Respondable` is included the denial delegates to `render_error` (`code: "forbidden"`), otherwise the same envelope is rendered inline. Deliberately not a policy/ability framework (no policy objects, no ability DSL, no resource inference). Zero new runtime dependencies.
+- **Controllers::Throttleable**: per-request rate limiting with a store-agnostic, injectable backend. `throttle_by limit: 100, period: 1.minute` (bucketed per-IP by default, or by any `by:` lambda) halts an over-limit request with 429 plus `Retry-After` and `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. Fixed-window counter keyed by a floored time bucket; requires an explicit atomic store (`self.throttleable_store = Rails.cache`) — there is no silent in-process default, so the first throttled request raises until one is configured. Backports the essentials of Rails 7.2's `rate_limit` (with standardized headers) to Rails 5.0+. Zero new runtime dependencies.
+- **Controllers::Timezoneable**: per-request `Time.zone` selection via an `around_action` (`Time.use_zone`) — the time analogue of `Controllers::Localizable`. `timezoneable available: [...], default: "UTC"` resolves from `params` → `Time-Zone` header → cookie → default, every candidate validated through `ActiveSupport::TimeZone[...]` so it can never raise at request time; an unknown configured zone fails fast at declaration. Options `param:` / `header:` / `cookie:`. Zero new runtime dependencies.
+
+### Notes
+- All changes are additive and backward-compatible, with zero new runtime dependencies. The three new controller concerns stay namespace-only (`ConcernsOnRails::Controllers::*`), matching the existing controller concerns.
+
+## 1.13.0 (2026-06-06)
+
+### Added
+- **Models::Maskable**: non-destructive display masking for sensitive attributes. `maskable :email, with: :email` adds a `masked_<field>` reader and never writes the column (the raw value stays in the DB). Presets `:email` / `:phone` / `:credit_card` / `:last4` / `:all`, a configurable `mask:` character, and a `Proc` escape hatch. Backed by `Support::Masker`; complements `Sanitizable`.
+- **Models::Monetizable**: exact, float-free money handling over an integer subunit column. `monetizable :price_cents` derives `price` / `price=` / `formatted_price` (the `_cents` suffix is stripped, or name them with `as:`). Options `unit:` / `precision:` / `delimiter:` / `separator:` / `subunit_to_unit:`. Uses `BigDecimal` throughout; backed by `Support::Money`.
+- **Controllers::Localizable**: per-request locale selection from `params` and/or the `Accept-Language` header via an `around_action` (`I18n.with_locale`). `localizable available: %i[en fr], default: :en`; options `param:` / `header:`. The resolved locale is always validated against `I18n.available_locales`, so it can never raise `I18n::InvalidLocale`.
+
+### Notes
+- All changes are additive and backward-compatible, with zero new runtime dependencies (BigDecimal and I18n already ship with the existing stack). `ConcernsOnRails::Maskable` / `ConcernsOnRails::Monetizable` are aliased to their `Models::*` modules; the controller concern stays namespace-only (`ConcernsOnRails::Controllers::Localizable`).
+
 ## 1.12.1 (2026-06-06)
 
 ### Added

data/README.md

@@ -41,6 +41,8 @@ Article.published.without_deleted.find("hello-world")
   - [Addressable](#-addressable) — postal address normalization + format validation
   - [Taggable](#-taggable) — lightweight tagging over a single column
   - [Sanitizable](#-sanitizable) — opt-in HTML sanitization (XSS defense-in-depth)
+  - [Maskable](#-maskable) — non-destructive display masking of sensitive fields
+  - [Monetizable](#-monetizable) — integer-cents money columns (BigDecimal)
 - **Controller concerns**
   - [Paginatable](#-paginatable) — offset pagination with headers
   - [Filterable](#-filterable) — declarative URL-param filters
@@ -49,6 +51,10 @@ Article.published.without_deleted.find("hello-world")
   - [ErrorHandleable](#-errorhandleable) — JSON `rescue_from` handlers for common controller errors
   - [Includable](#-includable) — whitelisted association sideloading + sparse fieldsets
   - [SecureHeadable](#-secureheadable) — security response headers + native CSP DSL
+  - [Localizable](#-localizable) — per-request locale from params / Accept-Language
+  - [Authorizable](#-authorizable) — per-action 403 authorization gate (block-based)
+  - [Throttleable](#-throttleable) — rate limiting with 429 + `X-RateLimit-*` headers
+  - [Timezoneable](#-timezoneable) — per-request `Time.zone` from params / header / cookie
 - [Module paths & namespacing](#-module-paths--namespacing)
 - [Development](#-development)
 - [Contributing](#-contributing)
@@ -58,7 +64,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Sixteen model concerns + seven controller concerns**, all production-ready
+- **Eighteen model concerns + eight controller concerns**, all production-ready
 - **One include, one macro** — no boilerplate, no glue code
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable); controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early
@@ -871,6 +877,64 @@ article.sanitized_body  # => "<b>Hi</b>alert(1)"                    (script tag
 
 ---
 
+## 🙈 Maskable
+
+Non-destructive display masking for sensitive attributes. Each declaration adds a `masked_<field>` reader and **never writes the column** — the raw value stays in the database (masking is a presentation concern). Dependency-free.
+
+```ruby
+class User < ApplicationRecord
+  include ConcernsOnRails::Maskable
+
+  maskable :email, with: :email          # => user.masked_email  "j****@example.com"
+  maskable :card,  with: :credit_card    # => user.masked_card   "**** **** **** 4242"
+  maskable :ssn,   with: :last4, mask: "•"
+  maskable :token, with: ->(v) { "#{v.to_s[0, 3]}…" }
+end
+```
+
+**Presets** (`with:`)
+
+| Preset         | Result                                      |
+|----------------|---------------------------------------------|
+| `:email`       | `j****@example.com` (first char + domain)   |
+| `:phone`       | `***-2671` (last 4 digits)                  |
+| `:credit_card` | `**** **** **** 4242` (last 4 digits)       |
+| `:last4`       | keep the last 4 characters                  |
+| `:all`         | mask every character (the default)          |
+| `Proc`         | used as-is (you own the non-String guard)   |
+
+`mask:` sets the mask character (default `*`). Nil and non-string values pass through untouched. To strip dangerous HTML instead, see [Sanitizable](#-sanitizable).
+
+---
+
+## 💰 Monetizable
+
+Money handling for an integer "subunit" column (e.g. cents) — exact and float-free via `BigDecimal`. `monetizable :price_cents` derives three methods (the `_cents` suffix is stripped):
+
+```ruby
+class Product < ApplicationRecord
+  include ConcernsOnRails::Monetizable
+
+  monetizable :price_cents                          # => price / price= / formatted_price
+  monetizable :shipping_cents, as: :shipping
+  monetizable :total_cents, unit: "€", delimiter: ".", separator: ","
+end
+
+product.price = 19.99   # stores price_cents = 1999 (rounded to whole cents)
+product.price           # => BigDecimal 19.99
+product.formatted_price # => "$19.99"
+```
+
+| Method            | Returns                                       |
+|-------------------|-----------------------------------------------|
+| `price`           | the amount as a `BigDecimal` (cents ÷ 100)    |
+| `price=`          | assign in major units; rounded to whole cents |
+| `formatted_price` | a display string (`"$1,234.56"`)              |
+
+**Options**: `as:` (explicit method name — required when the column does not end in `_cents`), `unit:` (`"$"`), `precision:` (`2`), `delimiter:` (`","`), `separator:` (`"."`), `subunit_to_unit:` (`100`). `nil` stays `nil` across all three methods.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -1134,6 +1198,107 @@ end
 
 ---
 
+## 🌐 Localizable
+
+Per-request locale selection from the request params and/or the `Accept-Language` header, wrapped in an `around_action` so `I18n.locale` is set for the action and restored afterwards. Dependency-free.
+
+```ruby
+class ApplicationController < ActionController::Base
+  include ConcernsOnRails::Controllers::Localizable
+
+  localizable available: %i[en fr de], default: :en
+  # localizable param: :lang, header: false   # params[:lang] only
+end
+```
+
+Resolution order: `params[param]` → first match in `Accept-Language` → `default` → `I18n.default_locale`. The chosen locale is always validated against `I18n.available_locales`, so a stray param or a mismatched `available:` list can never raise `I18n::InvalidLocale`.
+
+**Options**: `available:` (allow-list for matching; defaults to `I18n.available_locales`), `default:`, `param:` (default `:locale`), `header:` (default `true`).
+
+---
+
+## 🔒 Authorizable
+
+A declarative, **block-only** per-action authorization gate. Each rule is a predicate; the first one that applies to the current action and returns falsey halts the request with **403**. Deliberately small — not a Pundit/CanCan replacement.
+
+```ruby
+class Api::BaseController < ApplicationController
+  include ConcernsOnRails::Controllers::Authorizable
+
+  authorize_by { current_user.present? }                          # every action
+  authorize_by(only: %i[update destroy]) { |_action, user| user.admin? }
+  require_role :admin, :editor, only: :publish                    # role sugar
+end
+```
+
+The predicate runs via `instance_exec`, so `current_user` (and any helper) resolves on the controller. It is **arity-safe** — write it with zero, one (`|action|`), or two (`|action, user|`) parameters.
+
+**API**
+
+| Method         | Signature                                                                                  |
+|----------------|--------------------------------------------------------------------------------------------|
+| `authorize_by` | `authorize_by(only: nil, except: nil, status: :forbidden, message: "Forbidden", &block)`   |
+| `require_role` | `require_role(*roles, via: :current_user, role_method: :role, only:, except:, status:, message:)` |
+
+**Notes**
+- Rules run in declaration order; the first failing rule renders and halts.
+- When `Respondable` is also included, denials delegate to `render_error` (envelope `{ success: false, error: { message:, code: "forbidden" } }`); otherwise the same envelope is rendered inline.
+- `only:` / `except:` are mutually exclusive (passing both raises `ArgumentError`); `authorize_by` requires a block and `require_role` requires at least one role.
+- **Non-goals**: no policy objects, no ability DSL, no resource inference — reach for [`pundit`](https://github.com/varvet/pundit) / [`cancancan`](https://github.com/CanCanCommunity/cancancan) when you outgrow a predicate per action.
+
+---
+
+## 🚦 Throttleable
+
+Per-request rate limiting with a **store-agnostic, injectable** backend — no `rack-attack` needed. When a rule's limit is exceeded the request is halted with **429** plus `Retry-After` and `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`.
+
+```ruby
+class Api::BaseController < ApplicationController
+  include ConcernsOnRails::Controllers::Throttleable
+
+  self.throttleable_store = Rails.cache               # must support atomic #increment
+
+  throttle_by limit: 100, period: 1.minute                          # by IP (default)
+  throttle_by limit: 5,   period: 1.minute, only: :create,
+              by: -> { current_user&.id || request.remote_ip }
+end
+```
+
+Fixed-window counter: the key embeds a floored time bucket (`epoch / period`) so each window starts clean and `X-RateLimit-Reset` is exact.
+
+**Options**: `limit:` (positive integer), `period:` (a `Duration` or seconds), `by:` (discriminator lambda, default per-IP), `only:` / `except:` (mutually exclusive action scoping), `name:` (disambiguates the counter key).
+
+**Notes**
+- The store MUST support **atomic increment-with-expiry** (`Rails.cache` with `#increment`, or Redis) — a non-atomic store under-counts under concurrency.
+- There is **no in-process default store** on purpose: the first throttled request raises `ArgumentError` until you set `throttleable_store`, so you never silently rate-limit per-process.
+- When `Respondable` is included, the 429 body delegates to `render_error` (`code: "rate_limited"`).
+- Backports the essentials of Rails 7.2's `rate_limit` (with standardized headers) to Rails 5.0+. For richer rules (fail2ban, allow/deny lists, exponential backoff) reach for [`rack-attack`](https://github.com/rack/rack-attack).
+
+---
+
+## 🕒 Timezoneable
+
+Per-request `Time.zone` selection wrapped in an `around_action` (`Time.use_zone`) — the time analogue of [Localizable](#-localizable). Dependency-free.
+
+```ruby
+class ApplicationController < ActionController::Base
+  include ConcernsOnRails::Controllers::Timezoneable
+
+  timezoneable available: ["UTC", "Eastern Time (US & Canada)"], default: "UTC"
+  # timezoneable param: :tz, header: false, cookie: :time_zone
+end
+```
+
+Resolution order: `params[param]` → `Time-Zone` header → cookie (if enabled) → `default` → the current `Time.zone`. Every value — the configured `available:` / `default:` **and** each request candidate — is resolved through `ActiveSupport::TimeZone[...]`, so a zone accepted at boot can never be rejected at request time.
+
+**Options**: `available:` (allow-list applied to param/header/cookie matching; `default:` bypasses it, mirroring Localizable), `default:`, `param:` (default `:time_zone`), `header:` (default `true`, reads the `Time-Zone` header), `cookie:` (default `false`; `true` reads the `:time_zone` cookie, or pass a cookie name).
+
+**Notes**
+- An unknown `available:` / `default:` zone raises `ArgumentError` at declaration time (fail-fast on misconfiguration).
+- Pairs naturally with the model concerns that read the clock (`Schedulable`, `Publishable`, `Expirable`, `SoftDeletable`).
+
+---
+
 ## 🗂️ Module paths & namespacing
 
 Every concern is available under two paths:

data/lib/concerns_on_rails/controllers/authorizable.rb

@@ -0,0 +1,124 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Controllers
+    # Declarative, block-only per-action authorization gate. Each rule is a
+    # predicate; the first rule that applies to the current action and returns a
+    # falsey value halts the request with 403 (rendered via Respondable's
+    # `render_error` when available, otherwise an inline envelope).
+    #
+    #   class Api::BaseController < ApplicationController
+    #     include ConcernsOnRails::Controllers::Authorizable
+    #
+    #     authorize_by { current_user.present? }                       # every action
+    #     authorize_by(only: %i[update destroy]) { |_action, user| user.admin? }
+    #     require_role :admin, :editor, only: :publish                 # role sugar
+    #   end
+    #
+    # The block is invoked with `instance_exec` so `current_user` (and any other
+    # helper) resolves on the controller. It is arity-safe: write it with zero,
+    # one (`|action|`), or two (`|action, user|`) parameters.
+    #
+    # Non-goals (kept deliberately small): this is NOT a policy/ability framework.
+    # No policy objects, no ability DSL, no resource inference — reach for Pundit
+    # or CanCanCan when you outgrow a predicate per action.
+    module Authorizable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :authorizable_rules, instance_accessor: false, default: []
+        before_action :enforce_authorization
+      end
+
+      module ClassMethods
+        # Register an authorization predicate. `only:`/`except:` scope it to a
+        # subset of actions (mutually exclusive). `status:` (default :forbidden)
+        # and `message:` control the denial response.
+        def authorize_by(only: nil, except: nil, status: :forbidden, message: "Forbidden", &block)
+          raise ArgumentError, "ConcernsOnRails::Controllers::Authorizable: a block is required" unless block
+
+          add_authorization_rule(check: block, only: only, except: except, status: status, message: message)
+        end
+
+        # Sugar for the common "actor must have one of these roles" rule. The
+        # actor is read via `via:` (default `:current_user`) and its role via
+        # `role_method:` (default `:role`). Implemented as a proc, never a lambda,
+        # so arity slicing can't raise.
+        def require_role(*roles, via: :current_user, role_method: :role, only: nil, except: nil,
+                         status: :forbidden, message: "Forbidden")
+          raise ArgumentError, "ConcernsOnRails::Controllers::Authorizable: at least one role is required" if roles.empty?
+
+          wanted = roles.map(&:to_s)
+          check = proc do
+            actor = respond_to?(via) ? send(via) : nil
+            actor.respond_to?(role_method) && wanted.include?(actor.public_send(role_method).to_s)
+          end
+          add_authorization_rule(check: check, only: only, except: except, status: status, message: message)
+        end
+
+        private
+
+        def add_authorization_rule(check:, only:, except:, status:, message:)
+          raise ArgumentError, "ConcernsOnRails::Controllers::Authorizable: pass either :only or :except, not both" if only && except
+
+          rule = {
+            check: check,
+            only: only && Array(only).map(&:to_s),
+            except: except && Array(except).map(&:to_s),
+            status: status,
+            message: message
+          }
+          self.authorizable_rules = authorizable_rules + [rule]
+        end
+      end
+
+      # Public so subclasses can override. Iterates the declared rules in order
+      # and denies on the first failing rule that applies to the current action.
+      def enforce_authorization
+        self.class.authorizable_rules.each do |rule|
+          next unless authorization_rule_applies?(rule)
+          next if invoke_authorization_check(rule[:check])
+
+          return authorization_denied(status: rule[:status], message: rule[:message])
+        end
+        nil
+      end
+
+      # Public override point for how a denial is rendered.
+      def authorization_denied(status:, message:)
+        return unless respond_to?(:response) && response
+
+        return render_error(message: message, status: status, code: "forbidden") if respond_to?(:render_error)
+
+        render json: { success: false, error: { message: message, code: "forbidden" } }, status: status
+      end
+
+      private
+
+      def authorization_rule_applies?(rule)
+        action = authorization_action_name
+        return rule[:only].include?(action) if rule[:only]
+        return !rule[:except].include?(action) if rule[:except]
+
+        true
+      end
+
+      # Arity-safe: slice the args to the predicate's arity before instance_exec
+      # so a zero/one/two-arg block all work. A negative arity (splat/optional)
+      # receives every arg.
+      def invoke_authorization_check(check)
+        args = [authorization_action_name, authorization_actor]
+        sliced = check.arity.negative? ? args : args.first(check.arity)
+        instance_exec(*sliced, &check)
+      end
+
+      def authorization_actor
+        respond_to?(:current_user) ? current_user : nil
+      end
+
+      def authorization_action_name
+        respond_to?(:action_name) ? action_name.to_s : nil
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/controllers/localizable.rb

@@ -0,0 +1,96 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Controllers
+    # Per-request locale selection from the request params and/or the
+    # `Accept-Language` header, wrapped in an `around_action` so `I18n.locale`
+    # is set for the action and restored afterwards.
+    #
+    #   class ApplicationController < ActionController::Base
+    #     include ConcernsOnRails::Controllers::Localizable
+    #
+    #     localizable available: %i[en fr de], default: :en
+    #     # localizable param: :lang, header: false   # params[:lang] only
+    #   end
+    #
+    # Resolution order: `params[param]` → first match in `Accept-Language` →
+    # `default` → `I18n.default_locale`. The chosen locale is always validated
+    # against `I18n.available_locales` before use, so a stray param or a
+    # mismatched `available:` list can never raise `I18n::InvalidLocale`.
+    #
+    # Options: `available:` (allow-list for param/header matching; defaults to
+    # `I18n.available_locales`), `default:`, `param:` (default `:locale`),
+    # `header:` (default `true`).
+    module Localizable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :localizable_options, instance_accessor: false, default: {}
+        around_action :switch_locale
+      end
+
+      class_methods do
+        def localizable(available: nil, default: nil, param: :locale, header: true)
+          self.localizable_options = {
+            available: available&.map(&:to_sym),
+            default: default&.to_sym,
+            param: param&.to_sym,
+            header: header
+          }
+        end
+      end
+
+      # Public so subclasses can override; runs the action under the resolved locale.
+      def switch_locale(&)
+        I18n.with_locale(resolved_locale, &)
+      end
+
+      # The locale chosen for this request — always one I18n can switch to.
+      def resolved_locale
+        opts = self.class.localizable_options
+        allowed = opts[:available].presence || I18n.available_locales
+        candidate = locale_from_param(opts, allowed) || locale_from_header(opts, allowed) || opts[:default]
+
+        candidate && I18n.available_locales.include?(candidate.to_sym) ? candidate.to_sym : I18n.default_locale
+      end
+
+      private
+
+      def locale_from_param(opts, allowed)
+        return nil unless opts[:param] && respond_to?(:params) && params
+
+        match_locale(params[opts[:param]], allowed)
+      end
+
+      def locale_from_header(opts, allowed)
+        return nil unless opts[:header]
+
+        header = accept_language_header
+        header.blank? ? nil : parse_accept_language(header, allowed)
+      end
+
+      def accept_language_header
+        return nil unless respond_to?(:request)
+
+        req = request
+        req.respond_to?(:headers) ? req.headers["Accept-Language"] : nil
+      end
+
+      def parse_accept_language(header, allowed)
+        header.split(",").each do |part|
+          lang = part.split(";").first.to_s.strip.split("-").first
+          match = match_locale(lang, allowed)
+          return match if match
+        end
+        nil
+      end
+
+      def match_locale(candidate, allowed)
+        return nil if candidate.blank?
+
+        wanted = candidate.to_s.downcase
+        allowed.find { |loc| loc.to_s.downcase == wanted }
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/controllers/throttleable.rb

@@ -0,0 +1,159 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Controllers
+    # Per-request rate limiting with a store-agnostic, injectable backend. When a
+    # rule's limit is exceeded the request is halted with 429 plus
+    # `Retry-After` and `X-RateLimit-Limit` / `X-RateLimit-Remaining` /
+    # `X-RateLimit-Reset` headers.
+    #
+    #   class Api::BaseController < ApplicationController
+    #     include ConcernsOnRails::Controllers::Throttleable
+    #
+    #     self.throttleable_store = Rails.cache               # must support atomic #increment
+    #
+    #     throttle_by limit: 100, period: 1.minute                          # by IP (default)
+    #     throttle_by limit: 5,   period: 1.minute, only: :create,
+    #                 by: -> { current_user&.id || request.remote_ip }
+    #   end
+    #
+    # Fixed-window counter: the key embeds a floored time bucket
+    # (`epoch / period`) so each window starts clean and `X-RateLimit-Reset` is
+    # exact. The store MUST support atomic increment-with-expiry (`Rails.cache`
+    # with `#increment`, or Redis); a non-atomic store under-counts under
+    # concurrency. There is no in-process default store on purpose — configure
+    # one explicitly or the first throttled request raises ArgumentError.
+    module Throttleable
+      extend ActiveSupport::Concern
+
+      # Default discriminator — one counter per client IP. Evaluated with
+      # instance_exec on the controller, so `request` resolves normally.
+      DEFAULT_DISCRIMINATOR = -> { request.remote_ip }
+
+      included do
+        class_attribute :throttleable_rules, instance_accessor: false, default: []
+        class_attribute :throttleable_store, instance_accessor: false, default: nil
+        before_action :enforce_throttles
+      end
+
+      module ClassMethods
+        # Declare a rate-limit rule. `limit` requests per `period` (a Duration or
+        # seconds), bucketed by `by:` (a callable, default per-IP). `only:`/
+        # `except:` scope it to a subset of actions (mutually exclusive). `name:`
+        # disambiguates the counter key when several rules share a discriminator.
+        def throttle_by(limit:, period:, by: nil, only: nil, except: nil, name: nil)
+          validate_throttle!(limit: limit, period: period, by: by, only: only, except: except)
+
+          rule = {
+            limit: limit,
+            period: period.to_i,
+            by: by || DEFAULT_DISCRIMINATOR,
+            only: only && Array(only).map(&:to_s),
+            except: except && Array(except).map(&:to_s),
+            name: (name || "rule#{throttleable_rules.size}").to_s
+          }
+          self.throttleable_rules = throttleable_rules + [rule]
+        end
+
+        private
+
+        def validate_throttle!(limit:, period:, by:, only:, except:)
+          prefix = "ConcernsOnRails::Controllers::Throttleable"
+          raise ArgumentError, "#{prefix}: :limit must be a positive integer" unless positive_integer?(limit)
+          raise ArgumentError, "#{prefix}: :period must be a positive duration" unless period.to_i.positive?
+          raise ArgumentError, "#{prefix}: :by must be callable" unless callable_or_nil?(by)
+          raise ArgumentError, "#{prefix}: pass either :only or :except, not both" if only && except
+        end
+
+        def positive_integer?(value)
+          value.is_a?(Integer) && value.positive?
+        end
+
+        def callable_or_nil?(value)
+          value.nil? || value.respond_to?(:call)
+        end
+      end
+
+      # Public so subclasses can override. Applies each in-scope rule; the first
+      # rule that exceeds its limit halts the request with a 429.
+      def enforce_throttles
+        self.class.throttleable_rules.each do |rule|
+          next unless throttle_rule_applies?(rule)
+
+          result = register_throttle_hit(rule)
+          emit_throttle_headers(rule, result)
+
+          return throttled_response(rule, result) if result[:count] > rule[:limit]
+        end
+        nil
+      end
+
+      # Public override point for the 429 body.
+      def throttled_response(_rule, result)
+        return unless respond_to?(:response) && response
+
+        message = "Rate limit exceeded. Retry in #{result[:retry_after]}s."
+        return render_error(message: message, status: :too_many_requests, code: "rate_limited") if respond_to?(:render_error)
+
+        render json: { success: false, error: { message: message, code: "rate_limited" } }, status: :too_many_requests
+      end
+
+      private
+
+      def throttle_rule_applies?(rule)
+        action = throttle_action_name
+        return rule[:only].include?(action) if rule[:only]
+        return !rule[:except].include?(action) if rule[:except]
+
+        true
+      end
+
+      def register_throttle_hit(rule)
+        store = throttle_store!
+        now = Time.now.to_i
+        window = now / rule[:period]
+        reset_at = (window + 1) * rule[:period]
+        key = "throttleable:#{rule[:name]}:#{throttle_discriminator(rule)}:#{window}"
+
+        # Atomic increment-with-expiry. Some stores return nil on the first
+        # increment of a missing key — seed it to 1 in that case.
+        count = store.increment(key, 1, expires_in: rule[:period])
+        count ||= seed_throttle_key(store, key, rule[:period])
+
+        { count: count.to_i, reset_at: reset_at, retry_after: [reset_at - now, 0].max }
+      end
+
+      def seed_throttle_key(store, key, period)
+        store.write(key, 1, expires_in: period) if store.respond_to?(:write)
+        1
+      end
+
+      def throttle_discriminator(rule)
+        instance_exec(&rule[:by])
+      end
+
+      def emit_throttle_headers(rule, result)
+        return unless respond_to?(:response) && response
+
+        remaining = [rule[:limit] - result[:count], 0].max
+        response.set_header("X-RateLimit-Limit", rule[:limit].to_s)
+        response.set_header("X-RateLimit-Remaining", remaining.to_s)
+        response.set_header("X-RateLimit-Reset", result[:reset_at].to_s)
+        response.set_header("Retry-After", result[:retry_after].to_s) if result[:count] > rule[:limit]
+      end
+
+      def throttle_store!
+        store = self.class.throttleable_store
+        return store if store
+
+        raise ArgumentError,
+              "ConcernsOnRails::Controllers::Throttleable: no store configured. " \
+              "Set `self.throttleable_store = Rails.cache` (must support atomic #increment)."
+      end
+
+      def throttle_action_name
+        respond_to?(:action_name) ? action_name.to_s : nil
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/controllers/timezoneable.rb

@@ -0,0 +1,129 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Controllers
+    # Per-request `Time.zone` selection from the request params, the `Time-Zone`
+    # header, and/or a cookie, wrapped in an `around_action` so `Time.zone` is set
+    # for the action and restored afterwards. The time analogue of Localizable
+    # (which does the same for `I18n.locale`). Dependency-free.
+    #
+    #   class ApplicationController < ActionController::Base
+    #     include ConcernsOnRails::Controllers::Timezoneable
+    #
+    #     timezoneable available: ["UTC", "Eastern Time (US & Canada)"], default: "UTC"
+    #     # timezoneable param: :tz, header: false, cookie: :time_zone
+    #   end
+    #
+    # Resolution order: `params[param]` → `Time-Zone` header → cookie (if enabled)
+    # → `default` → the current `Time.zone`. Every value — the configured
+    # `available:`/`default:` AND each request candidate — is resolved through
+    # `ActiveSupport::TimeZone[...]`, so a zone accepted at boot can never be
+    # rejected at request time.
+    #
+    # Options: `available:` (allow-list applied to param/header/cookie matching;
+    # `default:` bypasses it, mirroring Localizable), `default:`, `param:`
+    # (default `:time_zone`), `header:` (default `true`), `cookie:` (default
+    # `false`; `true` reads the `:time_zone` cookie, or pass a cookie name).
+    module Timezoneable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :timezoneable_options, instance_accessor: false, default: {}
+        around_action :switch_time_zone
+      end
+
+      module ClassMethods
+        def timezoneable(available: nil, default: nil, param: :time_zone, header: true, cookie: false)
+          self.timezoneable_options = {
+            available: validate_time_zones(available),
+            default: validate_time_zone(default),
+            param: param&.to_sym,
+            header: header,
+            cookie: cookie == true ? :time_zone : cookie.presence
+          }
+        end
+
+        private
+
+        def validate_time_zones(zones)
+          return nil if zones.nil?
+
+          Array(zones).map { |zone| validate_time_zone(zone) }
+        end
+
+        # Resolve a single configured zone to an ActiveSupport::TimeZone at boot,
+        # raising on an unknown name so misconfiguration fails fast.
+        def validate_time_zone(zone)
+          return nil if zone.nil?
+
+          ActiveSupport::TimeZone[zone] ||
+            raise(ArgumentError, "ConcernsOnRails::Controllers::Timezoneable: unknown time zone '#{zone}'")
+        end
+      end
+
+      # Public so subclasses can override; runs the action under the resolved
+      # zone. UNGUARDED on purpose — it touches `Time` globally, not the response
+      # (mirrors Localizable#switch_locale).
+      def switch_time_zone(&)
+        Time.use_zone(resolved_time_zone, &)
+      end
+
+      # The ActiveSupport::TimeZone chosen for this request — always one `Time`
+      # can switch to (falls back to the current `Time.zone`).
+      def resolved_time_zone
+        opts = self.class.timezoneable_options
+        allowed = opts[:available]
+        candidate = zone_from_param(opts, allowed) ||
+                    zone_from_header(opts, allowed) ||
+                    zone_from_cookie(opts, allowed) ||
+                    opts[:default]
+
+        resolve_zone(candidate) || Time.zone
+      end
+
+      private
+
+      # Match a raw source value against the allow-list (when present), returning
+      # the resolved TimeZone or nil so the resolution chain falls through.
+      def match_zone(raw, allowed)
+        return nil if raw.blank?
+
+        zone = ActiveSupport::TimeZone[raw.to_s]
+        return nil unless zone
+        return nil if allowed&.none? { |z| z.name == zone.name }
+
+        zone
+      end
+
+      # Final coercion: `default` is already a TimeZone; the Time.zone fallback is
+      # handled by the caller.
+      def resolve_zone(candidate)
+        return nil if candidate.blank?
+        return candidate if candidate.is_a?(ActiveSupport::TimeZone)
+
+        ActiveSupport::TimeZone[candidate.to_s]
+      end
+
+      def zone_from_param(opts, allowed)
+        return nil unless opts[:param] && respond_to?(:params) && params
+
+        match_zone(params[opts[:param]], allowed)
+      end
+
+      def zone_from_header(opts, allowed)
+        return nil unless opts[:header] && respond_to?(:request)
+
+        req = request
+        header = req.respond_to?(:headers) ? req.headers["Time-Zone"] : nil
+        match_zone(header, allowed)
+      end
+
+      def zone_from_cookie(opts, allowed)
+        key = opts[:cookie]
+        return nil unless key && respond_to?(:cookies) && cookies
+
+        match_zone(cookies[key], allowed)
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -18,4 +18,6 @@ module ConcernsOnRails
   Sequenceable  = Models::Sequenceable
   Taggable      = Models::Taggable
   Sanitizable   = Models::Sanitizable
+  Maskable      = Models::Maskable
+  Monetizable   = Models::Monetizable
 end

data/lib/concerns_on_rails/models/maskable.rb

@@ -0,0 +1,79 @@
+require "active_support/concern"
+require "concerns_on_rails/support/masker"
+
+module ConcernsOnRails
+  module Models
+    # Non-destructive display masking for sensitive string attributes.
+    #
+    # Masking is ALWAYS read-only: each declaration adds a `masked_<field>`
+    # reader and never writes the stored column (the raw value stays in the DB,
+    # because masking is a presentation concern). For stripping dangerous HTML
+    # see Models::Sanitizable.
+    #
+    #   class User < ApplicationRecord
+    #     include ConcernsOnRails::Models::Maskable
+    #
+    #     maskable :email, with: :email          # => user.masked_email  "j****@example.com"
+    #     maskable :card,  with: :credit_card    # => user.masked_card   "**** **** **** 4242"
+    #     maskable :ssn,   with: :last4, mask: "•"
+    #     maskable :token, with: ->(v) { "#{v.to_s[0, 3]}…" }
+    #   end
+    #
+    # Presets (the `with:` argument):
+    #   :email       — mask the local part, keep first char + domain
+    #   :phone       — keep the last 4 digits ("***-2671")
+    #   :credit_card — keep the last 4 digits ("**** **** **** 4242")
+    #   :last4       — keep the last 4 characters
+    #   :all         — mask every character (the default)
+    #   Proc         — used as-is (the caller owns the non-String guard)
+    #
+    # `mask:` sets the mask character (default "*") for the preset forms.
+    module Maskable
+      extend ActiveSupport::Concern
+
+      PRESETS = %i[email phone credit_card last4 all].freeze
+
+      included do
+        class_attribute :maskable_rules, instance_accessor: false, default: {}
+      end
+
+      class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+
+        def maskable(*fields, with: :all, mask: "*")
+          raise ArgumentError, "ConcernsOnRails::Models::Maskable: at least one field is required" if fields.empty?
+
+          masker = resolve_masker(with, mask)
+          ensure_columns!("ConcernsOnRails::Models::Maskable", fields)
+
+          fields.each do |field|
+            key = field.to_sym
+            self.maskable_rules = maskable_rules.merge(key => masker)
+            define_method("masked_#{field}") { masker.call(self[key]) }
+          end
+        end
+      end
+
+      class_methods do
+        private
+
+        def resolve_masker(with, mask)
+          case with
+          when Symbol
+            unless PRESETS.include?(with)
+              raise ArgumentError,
+                    "ConcernsOnRails::Models::Maskable: unknown preset '#{with}'. " \
+                    "Valid presets: #{PRESETS.join(', ')}"
+            end
+
+            ->(v) { ConcernsOnRails::Support::Masker.public_send(with, v, mask: mask) }
+          when Proc then with
+          else
+            raise ArgumentError,
+                  "ConcernsOnRails::Models::Maskable: :with must be a preset symbol or a Proc/lambda, got #{with.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/models/monetizable.rb

@@ -0,0 +1,89 @@
+require "active_support/concern"
+require "concerns_on_rails/support/money"
+
+module ConcernsOnRails
+  module Models
+    # Money handling for an integer "subunit" column (e.g. cents) — exact,
+    # float-free, via BigDecimal.
+    #
+    # Declaring `monetizable :price_cents` adds three methods derived from the
+    # column name (the `_cents` suffix is stripped):
+    #   * `price`            — the amount as a BigDecimal (cents / 100)
+    #   * `price=`           — assign in major units; rounded to whole cents
+    #   * `formatted_price`  — a display string ("$1,234.56")
+    #
+    #   class Product < ApplicationRecord
+    #     include ConcernsOnRails::Models::Monetizable
+    #
+    #     monetizable :price_cents                       # => price / price= / formatted_price
+    #     monetizable :shipping_cents, as: :shipping
+    #     monetizable :total_cents, unit: "€", separator: ",", delimiter: "."
+    #   end
+    #
+    #   product.price = 19.99   # stores price_cents = 1999
+    #   product.price           # => 0.1999e2  (BigDecimal 19.99)
+    #   product.formatted_price # => "$19.99"
+    #
+    # Options: `as:` (explicit method name — required when the column does not
+    # end in `_cents`), `unit:` ("$"), `precision:` (2), `delimiter:` (","),
+    # `separator:` ("."), `subunit_to_unit:` (100).
+    module Monetizable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :monetizable_rules, instance_accessor: false, default: {}
+      end
+
+      class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+
+        def monetizable(*fields, as: nil, unit: "$", precision: 2, delimiter: ",", separator: ".", subunit_to_unit: 100)
+          raise ArgumentError, "ConcernsOnRails::Models::Monetizable: at least one field is required" if fields.empty?
+
+          raise ArgumentError, "ConcernsOnRails::Models::Monetizable: :as cannot be combined with multiple fields" if as && fields.size > 1
+
+          ensure_columns!("ConcernsOnRails::Models::Monetizable", fields)
+          config = { unit: unit, precision: precision, delimiter: delimiter, separator: separator, subunit_to_unit: subunit_to_unit }
+          fields.each { |cents_field| define_money_accessors(cents_field.to_sym, as, config) }
+        end
+      end
+
+      class_methods do # rubocop:disable Metrics/BlockLength
+        private
+
+        def define_money_accessors(cents_field, as, config)
+          name = money_name(cents_field, as)
+          subunit = config[:subunit_to_unit]
+          self.monetizable_rules = monetizable_rules.merge(cents_field => name)
+
+          define_method(name) do
+            cents = self[cents_field]
+            cents.nil? ? nil : BigDecimal(cents.to_s) / subunit
+          end
+
+          define_method("#{name}=") do |amount|
+            self[cents_field] = amount.nil? ? nil : (BigDecimal(amount.to_s) * subunit).round
+          end
+
+          define_method("formatted_#{name}") do
+            cents = self[cents_field]
+            cents.nil? ? nil : ConcernsOnRails::Support::Money.format(cents, config)
+          end
+        end
+
+        def money_name(cents_field, as)
+          return as.to_sym if as
+
+          str = cents_field.to_s
+          unless str.end_with?("_cents")
+            raise ArgumentError,
+                  "ConcernsOnRails::Models::Monetizable: cannot derive a money method name from '#{cents_field}' " \
+                  "(it does not end in '_cents'); pass `as:` to name it explicitly"
+          end
+
+          str.delete_suffix("_cents").to_sym
+        end
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/support/masker.rb

@@ -0,0 +1,60 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Support
+    # Display-only value-masking helpers shared by Models::Maskable.
+    #
+    # Every method is string-safe: a non-String argument is returned untouched,
+    # exactly like the Normalizable / Sanitizable preset lambdas. Masking is for
+    # presentation only — callers keep the original value in the database.
+    module Masker
+      module_function
+
+      DEFAULT_MASK = "*".freeze
+
+      # Replace every character with the mask character.
+      def all(value, mask: DEFAULT_MASK)
+        value.is_a?(String) ? mask * value.length : value
+      end
+
+      # Keep only the last four characters visible.
+      def last4(value, mask: DEFAULT_MASK)
+        return value unless value.is_a?(String)
+
+        value.length <= 4 ? mask * value.length : (mask * (value.length - 4)) + value[-4..]
+      end
+
+      # Mask the local part of an email, keeping the first character + domain:
+      #   "john.doe@example.com" => "j*******@example.com"
+      def email(value, mask: DEFAULT_MASK)
+        return value unless value.is_a?(String)
+
+        local, at, domain = value.partition("@")
+        return value if at.empty? # not an email-shaped string; leave it alone
+
+        masked_local = local.length <= 1 ? mask : local[0] + (mask * (local.length - 1))
+        "#{masked_local}@#{domain}"
+      end
+
+      # Keep the last four digits of a phone number visible: "***-2671".
+      def phone(value, mask: DEFAULT_MASK)
+        return value unless value.is_a?(String)
+
+        digits = value.gsub(/\D/, "")
+        return value if digits.empty?
+
+        "#{mask * 3}-#{digits.length <= 4 ? digits : digits[-4..]}"
+      end
+
+      # Keep the last four digits of a card number: "**** **** **** 4242".
+      def credit_card(value, mask: DEFAULT_MASK)
+        return value unless value.is_a?(String)
+
+        digits = value.gsub(/\D/, "")
+        return all(value, mask: mask) if digits.length <= 4
+
+        "#{mask * 4} #{mask * 4} #{mask * 4} #{digits[-4..]}"
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/support/money.rb

@@ -0,0 +1,38 @@
+require "bigdecimal"
+
+module ConcernsOnRails
+  module Support
+    # Formats an integer subunit amount (e.g. cents) as a human-readable money
+    # string. Pure and stateless; used by Models::Monetizable. Uses BigDecimal
+    # throughout so there is no binary-float rounding drift.
+    module Money
+      module_function
+
+      # format(199999) => "$1,999.99"
+      # format(-500, unit: "£") => "-£5.00"
+      # format(1234, unit: "¥", precision: 0, subunit_to_unit: 1) => "¥1,234"
+      def format(cents, options = {})
+        unit      = options.fetch(:unit, "$")
+        precision = options.fetch(:precision, 2)
+        delimiter = options.fetch(:delimiter, ",")
+        separator = options.fetch(:separator, ".")
+        subunit   = options.fetch(:subunit_to_unit, 100)
+
+        decimal = BigDecimal(cents.to_s) / subunit
+        # BigDecimal#round returns an Integer for precision <= 0, so re-wrap it
+        # in a BigDecimal before #to_s("F") (Integer#to_s would read "F" as a radix).
+        rounded = BigDecimal(decimal.abs.round(precision).to_s)
+        whole, _, frac = rounded.to_s("F").partition(".")
+        whole = delimit(whole, delimiter)
+        number = precision.positive? ? "#{whole}#{separator}#{frac.ljust(precision, '0')[0, precision]}" : whole
+
+        "#{'-' if decimal.negative?}#{unit}#{number}"
+      end
+
+      # Insert the thousands delimiter into a non-negative integer string.
+      def delimit(integer_string, delimiter)
+        integer_string.reverse.gsub(/(\d{3})(?=\d)/, "\\1#{delimiter}").reverse
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.12.1".freeze
+  VERSION = "1.14.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -13,6 +13,8 @@ require "concerns_on_rails/support/random_value"
 require "concerns_on_rails/support/address_data"
 require "concerns_on_rails/support/sequence_calculator"
 require "concerns_on_rails/support/html_sanitizers"
+require "concerns_on_rails/support/masker"
+require "concerns_on_rails/support/money"
 
 # Model concerns
 require "concerns_on_rails/models/sluggable"
@@ -31,6 +33,8 @@ require "concerns_on_rails/models/addressable"
 require "concerns_on_rails/models/sequenceable"
 require "concerns_on_rails/models/taggable"
 require "concerns_on_rails/models/sanitizable"
+require "concerns_on_rails/models/maskable"
+require "concerns_on_rails/models/monetizable"
 
 # Controller concerns
 require "concerns_on_rails/controllers/paginatable"
@@ -40,6 +44,10 @@ require "concerns_on_rails/controllers/respondable"
 require "concerns_on_rails/controllers/error_handleable"
 require "concerns_on_rails/controllers/includable"
 require "concerns_on_rails/controllers/secure_headable"
+require "concerns_on_rails/controllers/localizable"
+require "concerns_on_rails/controllers/authorizable"
+require "concerns_on_rails/controllers/throttleable"
+require "concerns_on_rails/controllers/timezoneable"
 
 # Backwards compatibility (top-level aliases for pre-1.6 module paths)
 require "concerns_on_rails/legacy_aliases"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.12.1
+  version: 1.14.0
 platform: ruby
 authors:
 - Ethan Nguyen
@@ -70,18 +70,24 @@ files:
 - CODE_OF_CONDUCT.md
 - README.md
 - lib/concerns_on_rails.rb
+- lib/concerns_on_rails/controllers/authorizable.rb
 - lib/concerns_on_rails/controllers/error_handleable.rb
 - lib/concerns_on_rails/controllers/filterable.rb
 - lib/concerns_on_rails/controllers/includable.rb
+- lib/concerns_on_rails/controllers/localizable.rb
 - lib/concerns_on_rails/controllers/paginatable.rb
 - lib/concerns_on_rails/controllers/respondable.rb
 - lib/concerns_on_rails/controllers/secure_headable.rb
 - lib/concerns_on_rails/controllers/sortable.rb
+- lib/concerns_on_rails/controllers/throttleable.rb
+- lib/concerns_on_rails/controllers/timezoneable.rb
 - lib/concerns_on_rails/legacy_aliases.rb
 - lib/concerns_on_rails/models/activatable.rb
 - lib/concerns_on_rails/models/addressable.rb
 - lib/concerns_on_rails/models/expirable.rb
 - lib/concerns_on_rails/models/hashable.rb
+- lib/concerns_on_rails/models/maskable.rb
+- lib/concerns_on_rails/models/monetizable.rb
 - lib/concerns_on_rails/models/normalizable.rb
 - lib/concerns_on_rails/models/publishable.rb
 - lib/concerns_on_rails/models/sanitizable.rb
@@ -97,6 +103,8 @@ files:
 - lib/concerns_on_rails/support/address_data.rb
 - lib/concerns_on_rails/support/column_guard.rb
 - lib/concerns_on_rails/support/html_sanitizers.rb
+- lib/concerns_on_rails/support/masker.rb
+- lib/concerns_on_rails/support/money.rb
 - lib/concerns_on_rails/support/random_value.rb
 - lib/concerns_on_rails/support/sequence_calculator.rb
 - lib/concerns_on_rails/version.rb