concerns_on_rails 1.15.0 → 1.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d0ca1b10759cf285948bef864e3cba343b3d1caa5e461b000af0486b4d51781
-  data.tar.gz: 1006768d58216c32a190c551ede050eb2e12ac24d13daf847600e83d1f219f52
+  metadata.gz: dbe5bebe66a84e336f6dbffff99b12d12ed65f6238ea000b9a149908b1a78e0c
+  data.tar.gz: 8478287a2750b501288e02e30394cfb79a45e2208190c14e8fce945457229e2b
 SHA512:
-  metadata.gz: 7b8c99595c6fbdd34ba4eb2ed011dee168c6178cffbee5bd1803195e83d5e2301bb87db99bc2dbf1143ba6d5e584f708d44aefbbea13248af2bc0d6eba0772d2
-  data.tar.gz: b43057a24fd64599ee62ef31dcbddd0daf3b985193a36dd02811c17721ebebf0e73f5793c73ffb41c98524ca9b5bec1a100c9c3619ccf8ceb896ce5ce11051cc
+  metadata.gz: 06bd9e4b6a3493047ea48b60f2ff75517bb3d117c8cbe4712071f7464db173c8cb73f7a3763d22a4376f458ba1d85deffca47648544ec4879642d14dc40e6a78
+  data.tar.gz: 042252611fb6ef6a41c671d3cf2a17e29ee7dcf82349f8f84b22d04274ebbcd2c48c23a2b6a03291325e0d072daedf29981b84bc2fb0a11a6cf832d5f79a572e

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 <!-- CHANGELOG.md -->
 
+## 1.16.0 (2026-06-10)
+
+Two new concerns, hardened by an adversarial edge-case review. 574 examples, 0 failures.
+
+### Added
+- **Models::Auditable**: lightweight single-column change history ("paper_trail-lite"). `auditable_by :price, :status, into: :audit_log, actor: -> { Current.user&.email }, max_entries: 100` appends one JSON entry per changed field per save (creates record `from: nil`) into one text column — no extra tables, written in the same INSERT/UPDATE via `before_save`. Readers: `audit_trail`, `last_change_for(:field)`, `audited_changes_since(time)`, `clear_audit_trail!`. Tolerant JSON decode (corrupt column → `[]`), newest-N trimming (default 200), opt-in value truncation (`max_value_length:` stores the first N characters of long String values + `…`), values JSON-coerced (times → ISO8601 UTC, BigDecimal → precision-safe string, non-finite floats → `"NaN"`/`"Infinity"` strings), `"by"` omitted when no actor. Entries build on the persisted trail, so a save aborted by a later callback cannot duplicate entries on retry. Zero new runtime dependencies.
+- **Controllers::Idempotentable**: Stripe-style `Idempotency-Key` support with an injectable store (`self.idempotency_store = Rails.cache`; contract: `#read`, `#write(expires_in:, unless_exist:)`, `#delete` — no in-process default on purpose). `idempotent_actions :create, ttl: 24.hours, lock_ttl: 1.minute, header: "Idempotency-Key", required: false` claims each key atomically, caches 2xx–4xx responses and replays them with `X-Idempotency-Replayed: true`; concurrent duplicates get 409 + `Retry-After`, payload mismatches get 422 (`idempotency_key_reuse`, fingerprint overridable), 5xx/exceptions release the claim so retries re-execute. Keys are validated (≤255 chars, control characters rejected to prevent response-header injection via the echoed `X-Idempotency-Key`), SHA256-hashed, and scoped per `controller#action`. Error bodies delegate to `render_error` when Respondable is present. Zero new runtime dependencies.
+
 ## 1.15.0 (2026-06-10)
 
 A review-driven release: 23 correctness/safety fixes (each with a regression spec) and 7 backward-compatible enhancements. 510 examples, 0 failures.

data/README.md

@@ -43,6 +43,7 @@ Article.published.without_deleted.find("hello-world")
   - [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)
+  - [Auditable](#-auditable) — single-column change history ("paper_trail-lite")
 - **Controller concerns**
   - [Paginatable](#-paginatable) — offset pagination with headers
   - [Filterable](#-filterable) — declarative URL-param filters
@@ -55,6 +56,7 @@ Article.published.without_deleted.find("hello-world")
   - [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
+  - [Idempotentable](#-idempotentable) — `Idempotency-Key` request replay (409 on concurrent duplicates)
 - [Module paths & namespacing](#-module-paths--namespacing)
 - [Development](#-development)
 - [Contributing](#-contributing)
@@ -64,7 +66,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Eighteen model concerns + eight controller concerns**, all production-ready
+- **Nineteen model concerns + twelve 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
@@ -935,6 +937,39 @@ product.formatted_price # => "$19.99"
 
 ---
 
+## 📜 Auditable
+
+Lightweight change history ("paper_trail-lite") stored as JSON entries in **one text column** on the same table — no extra tables, no versioning engine.
+
+```ruby
+class Product < ApplicationRecord
+  include ConcernsOnRails::Auditable
+
+  auditable_by :price, :status                       # default column :audit_log
+  # auditable_by :price, into: :history,
+  #              actor: -> { Current.user&.email },  # stamps "by" on each entry
+  #              max_entries: 50                     # keep the newest 50
+end
+
+product.update!(price: 200)
+product.audit_trail
+# => [{"field"=>"price", "from"=>100, "to"=>200, "at"=>"2026-06-10T12:34:56Z", "by"=>"admin@shop.com"}]
+product.last_change_for(:price)            # newest entry for one field
+product.audited_changes_since(1.day.ago)   # recent entries, oldest first
+product.clear_audit_trail!                 # wipe the column (skips callbacks)
+```
+
+One entry is recorded **per changed field per save** (creates record `"from" => nil`), appended in the same `INSERT`/`UPDATE` via `before_save` — zero extra queries.
+
+**Options**: `into:` (`:audit_log`), `actor:` (callable, `instance_exec`'d on the record; `"by"` omitted when absent), `max_entries:` (`200`; keeps the newest N, `nil` = unlimited), `max_value_length:` (`nil`; truncates long String `from`/`to` values to the first N characters + `…`).
+
+**Notes**
+- Writes that skip callbacks (`update_column(s)`, `touch`, `increment!`) are **not** audited; `save(validate: false)` is.
+- Values are JSON-coerced (times → ISO8601 UTC strings, `BigDecimal` → precision-safe numeric string); a corrupt column decodes as `[]` and is replaced on the next tracked save.
+- Per-record and bounded by design — reach for [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) / [`audited`](https://github.com/collectiveidea/audited) when you need reify/undo or audit queries across models.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -1299,6 +1334,33 @@ Resolution order: `params[param]` → `Time-Zone` header → cookie (if enabled)
 
 ---
 
+## 🔁 Idempotentable
+
+Stripe-style **`Idempotency-Key`** support for mutating endpoints, with a **store-agnostic, injectable** backend. The first request with a key runs the action and caches the response; a retry **replays** the cached response; a concurrent duplicate gets **409**.
+
+```ruby
+class PaymentsController < ApplicationController
+  include ConcernsOnRails::Controllers::Idempotentable
+
+  self.idempotency_store = Rails.cache    # must support #read / #write(expires_in:, unless_exist:) / #delete
+
+  idempotent_actions :create, ttl: 24.hours, required: true
+end
+```
+
+Per-key lifecycle: claim atomically (`write unless_exist`, TTL `lock_ttl:`) → run action → cache 2xx–4xx responses for `ttl:`; 5xx and raised exceptions release the claim so the client can retry. Replays carry `X-Idempotency-Replayed: true`; duplicates in flight get 409 + `Retry-After`; reusing a key with a **different payload** gets 422 (`idempotency_key_reuse`, fingerprint overridable via `idempotency_fingerprint`).
+
+**Options**: `*actions` (allow-list, required), `ttl:` (`24.hours`), `lock_ttl:` (`1.minute`), `header:` (`"Idempotency-Key"`), `required:` (`false`).
+
+**Notes**
+- Cache keys are scoped per `controller#action` and the client key is SHA256-hashed, so the same key on different endpoints never collides.
+- There is **no in-process default store** on purpose: the first keyed request raises `ArgumentError` until you set `idempotency_store`.
+- When `Respondable` is included, the 400/409/422 bodies delegate to `render_error`.
+- Declare halting filters (authentication, `Throttleable`) **before** including this concern — a 401/403 rendered by an inner filter would be cached and replayed for the full TTL. Responses rendered by `rescue_from` handlers are never cached.
+- Keys must be ≤255 chars with no control characters (the raw key is echoed in `X-Idempotency-Key`); set `lock_ttl:` above the slowest declared action's worst case.
+
+---
+
 ## 🗂️ Module paths & namespacing
 
 Every concern is available under two paths:
@@ -1334,7 +1396,7 @@ Both forms reference the same module, so you can freely mix them.
 | Association-cascade soft delete / sentinel-aware unique indexes | [`paranoia`](https://github.com/rubysherpas/paranoia) or [`discard`](https://github.com/jhawthorn/discard) |
 | Tagging with contexts, ownership, or tag clouds | [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on) |
 | Full-text search with ranking / stemming | [`pg_search`](https://github.com/Casecommons/pg_search) / Elasticsearch |
-| Audit trails / version history | [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) / [`audited`](https://github.com/collectiveidea/audited) |
+| Versioned audit trails with undo/reify, who-dunnit queries, or association tracking | [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) / [`audited`](https://github.com/collectiveidea/audited) |
 
 `Sluggable` wraps [`friendly_id`](https://github.com/norman/friendly_id) and `Sortable` wraps [`acts_as_list`](https://github.com/brendon/acts_as_list), so you get those leaders' engines behind the declarative macro.
 

data/lib/concerns_on_rails/controllers/idempotentable.rb

@@ -0,0 +1,300 @@
+require "active_support/concern"
+require "digest"
+require "json"
+
+module ConcernsOnRails
+  module Controllers
+    # Stripe-style `Idempotency-Key` support for mutating endpoints, with a
+    # store-agnostic, injectable backend. The first request with a key executes
+    # the action and caches the rendered response; a retry with the same key
+    # replays the cached response instead of re-running the action; a concurrent
+    # duplicate while the first is still in flight is halted with 409.
+    #
+    #   class PaymentsController < ApplicationController
+    #     include ConcernsOnRails::Controllers::Idempotentable
+    #
+    #     self.idempotency_store = Rails.cache    # must support #read / #write(expires_in:, unless_exist:) / #delete
+    #
+    #     idempotent_actions :create, ttl: 24.hours, required: true
+    #   end
+    #
+    # Lifecycle per key (scoped to controller#action, so the same client key on
+    # different endpoints never collides):
+    #   * claim won  -> action runs; 2xx-4xx responses are cached for `ttl:`;
+    #                   5xx responses and raised exceptions release the claim so
+    #                   the client can retry.
+    #   * done       -> the cached status/body/content type is replayed with
+    #                   `X-Idempotency-Replayed: true`.
+    #   * in flight  -> 409 with code "idempotency_conflict" and `Retry-After`.
+    #   * same key, different request payload -> 422 "idempotency_key_reuse"
+    #     (override `idempotency_fingerprint` to customize payload matching).
+    #
+    # The claim is taken atomically via `write(..., unless_exist: true)`
+    # (memcached `add` / Redis `SET NX` through Rails.cache); a store without
+    # that atomicity is best-effort under concurrency. There is no in-process
+    # default store on purpose — configure one explicitly or the first keyed
+    # request raises ArgumentError. Note that responses rendered by
+    # `rescue_from` handlers bypass the around filter's success path and are
+    # never cached.
+    #
+    # IMPORTANT — callback ordering: declare halting filters (authentication,
+    # authorization, rate limiting) BEFORE including this module. A
+    # before_action that runs *inside* the around filter and halts (401/403)
+    # has its response cached and replayed for the full `ttl:` — the client
+    # cannot fix credentials and retry until it expires. Rails offers no
+    # reliable way for the around filter to detect a halted inner chain.
+    # Likewise set `lock_ttl:` above the worst-case duration of the slowest
+    # declared action — if the action outlasts the claim, a concurrent retry
+    # can win the expired key and execute the action a second time.
+    module Idempotentable
+      extend ActiveSupport::Concern
+
+      DEFAULT_HEADER = "Idempotency-Key".freeze
+      MAX_KEY_LENGTH = 255
+      IGNORED_FINGERPRINT_KEYS = %w[controller action format].freeze
+
+      included do
+        class_attribute :idempotency_rules, instance_accessor: false, default: []
+        class_attribute :idempotency_store, instance_accessor: false, default: nil
+        around_action :enforce_idempotency
+      end
+
+      module ClassMethods
+        # Declare idempotent actions. `ttl:` is the cached-response lifetime,
+        # `lock_ttl:` the in-flight claim lifetime (kept short so a crashed
+        # worker cannot wedge a key), `header:` the request header to read, and
+        # `required:` whether a missing key is a 400. Each call appends a rule;
+        # the first rule listing the current action wins.
+        def idempotent_actions(*actions, ttl: 86_400, lock_ttl: 60, header: DEFAULT_HEADER, required: false)
+          actions = actions.flatten.map(&:to_s)
+          validate_idempotent!(actions, ttl: ttl, lock_ttl: lock_ttl, header: header, required: required)
+
+          rule = { actions: actions, ttl: ttl.to_i, lock_ttl: lock_ttl.to_i, header: header.to_s, required: required }
+          self.idempotency_rules = idempotency_rules + [rule]
+        end
+
+        private
+
+        def validate_idempotent!(actions, ttl:, lock_ttl:, header:, required:)
+          prefix = "ConcernsOnRails::Controllers::Idempotentable"
+          raise ArgumentError, "#{prefix}: pass at least one action" if actions.empty?
+          raise ArgumentError, "#{prefix}: :ttl must be a positive duration" unless ttl.to_i.positive?
+          raise ArgumentError, "#{prefix}: :lock_ttl must be a positive duration" unless lock_ttl.to_i.positive?
+          raise ArgumentError, "#{prefix}: :header must be a non-blank String" if header.to_s.strip.empty?
+          raise ArgumentError, "#{prefix}: :required must be true or false" unless [true, false].include?(required)
+        end
+      end
+
+      # around_action entry point. Public so subclasses can override and specs
+      # can drive it directly with a block standing in for the action.
+      def enforce_idempotency(&)
+        rule = idempotency_rule_for_action
+        return yield unless rule
+
+        raw = read_idempotency_header(rule)
+        return idempotency_handle_missing_key(rule, &) if raw.nil?
+
+        key = raw.to_s.strip
+        unless valid_idempotency_key?(key)
+          return idempotency_error_response(message: "#{rule[:header]} is invalid (expected 1-#{MAX_KEY_LENGTH} characters).",
+                                            status: :bad_request, code: "idempotency_key_invalid")
+        end
+
+        @idempotency_key = key
+        run_with_idempotency(rule, key, &)
+      end
+
+      # The raw key sent for the matched rule (nil when absent). Handy for logging.
+      def idempotency_key
+        @idempotency_key
+      end
+
+      # Digest of the request payload, used to reject reusing one key for a
+      # different request. Public override point — e.g. for raw-body APIs:
+      #   def idempotency_fingerprint = Digest::SHA256.hexdigest(request.raw_post)
+      # Override it for multipart endpoints too: an uploaded file stringifies
+      # with its object id, so retried uploads never match and 422 — digest
+      # stable parts instead (e.g. params[:file]&.original_filename).
+      def idempotency_fingerprint
+        raw = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h
+        filtered = raw.reject { |k, _| IGNORED_FINGERPRINT_KEYS.include?(k.to_s) }
+        Digest::SHA256.hexdigest(JSON.generate(idempotency_deep_sort(filtered)))
+      end
+
+      # Public override point for how a cached response is replayed.
+      def replay_idempotent_response(record)
+        return unless respond_to?(:response) && response
+
+        emit_idempotency_replayed_header(true)
+        options = { body: record["body"], status: record["status"] }
+        options[:content_type] = record["content_type"] if record["content_type"]
+        render(options)
+      end
+
+      # Single funnel for all error outcomes. Uses Respondable's render_error
+      # when available, otherwise the same inline envelope as Throttleable.
+      def idempotency_error_response(message:, status:, code:)
+        return unless respond_to?(:response) && response
+
+        return render_error(message: message, status: status, code: code) if respond_to?(:render_error)
+
+        render json: { success: false, error: { message: message, code: code } }, status: status
+      end
+
+      private
+
+      def idempotency_rule_for_action
+        action = respond_to?(:action_name) ? action_name.to_s : nil
+        return nil unless action
+
+        self.class.idempotency_rules.find { |rule| rule[:actions].include?(action) }
+      end
+
+      def idempotency_handle_missing_key(rule, &)
+        return yield unless rule[:required]
+
+        idempotency_error_response(message: "#{rule[:header]} header is required for this action.",
+                                   status: :bad_request, code: "idempotency_key_missing")
+      end
+
+      def valid_idempotency_key?(key)
+        # Control characters are rejected because the raw key is echoed in the
+        # X-Idempotency-Key response header — CR/LF would enable header
+        # injection on servers that don't validate header values (Rack 2).
+        !key.empty? && key.length <= MAX_KEY_LENGTH && !key.match?(/[[:cntrl:]]/)
+      end
+
+      def run_with_idempotency(rule, key, &)
+        store = idempotency_store!
+        cache_key = idempotency_cache_key(key)
+        fingerprint = idempotency_fingerprint
+        emit_idempotency_key_header(key)
+
+        claim = { "state" => "in_flight", "fingerprint" => fingerprint, "claimed_at" => Time.now.to_i }
+        if store.write(cache_key, claim, expires_in: rule[:lock_ttl], unless_exist: true)
+          idempotency_execute_and_store(store, cache_key, rule, fingerprint, &)
+        else
+          idempotency_resolve_existing(store, cache_key, rule, fingerprint)
+        end
+      end
+
+      def idempotency_execute_and_store(store, cache_key, rule, fingerprint)
+        emit_idempotency_replayed_header(false)
+        completed = false
+        begin
+          yield
+          completed = true
+        ensure
+          # Covers raise and throw alike, so a retry can re-execute.
+          store.delete(cache_key) unless completed
+        end
+
+        status = idempotency_response_status
+        return store.delete(cache_key) if status >= 500
+
+        record = { "state" => "done", "status" => status, "body" => idempotency_response_body,
+                   "content_type" => idempotency_response_content_type, "fingerprint" => fingerprint }
+        store.write(cache_key, record, expires_in: rule[:ttl])
+      end
+
+      def idempotency_resolve_existing(store, cache_key, rule, fingerprint)
+        record = store.read(cache_key)
+
+        if record && record["fingerprint"] != fingerprint
+          return idempotency_error_response(message: "#{rule[:header]} was already used with a different request payload.",
+                                            status: :unprocessable_entity, code: "idempotency_key_reuse")
+        end
+
+        return replay_idempotent_response(record) if record && record["state"] == "done"
+
+        # In flight — or the claim expired between our failed write and this
+        # read (rare); answering 409 is the conservative, retry-safe choice.
+        idempotency_conflict_response(rule)
+      end
+
+      def idempotency_conflict_response(rule)
+        response.set_header("Retry-After", rule[:lock_ttl].to_s) if respond_to?(:response) && response
+        idempotency_error_response(message: "A request with this #{rule[:header]} is already in progress.",
+                                   status: :conflict, code: "idempotency_conflict")
+      end
+
+      def read_idempotency_header(rule)
+        return nil unless respond_to?(:request) && request.respond_to?(:headers) && request.headers
+
+        request.headers[rule[:header]]
+      end
+
+      def idempotency_cache_key(key)
+        # The user key is hashed so any validated key is safe in any backend
+        # (memcached limits key length and bans whitespace/control characters).
+        "idempotentable:#{idempotency_scope}:#{Digest::SHA256.hexdigest(key)}"
+      end
+
+      def idempotency_scope
+        controller = respond_to?(:controller_path) ? controller_path : self.class.name || "anonymous"
+        action = respond_to?(:action_name) ? action_name.to_s : ""
+        "#{controller}##{action}"
+      end
+
+      def idempotency_store!
+        store = self.class.idempotency_store
+        return store if store
+
+        raise ArgumentError,
+              "ConcernsOnRails::Controllers::Idempotentable: no store configured. " \
+              "Set `self.idempotency_store = Rails.cache` " \
+              "(must support #read, #write(expires_in:, unless_exist:) and #delete)."
+      end
+
+      def idempotency_response_status
+        return 200 unless respond_to?(:response) && response.respond_to?(:status)
+
+        response.status.to_i
+      end
+
+      def idempotency_response_body
+        return nil unless respond_to?(:response) && response.respond_to?(:body)
+
+        response.body
+      end
+
+      def idempotency_response_content_type
+        return nil unless respond_to?(:response) && response
+
+        # media_type (real Rails) excludes the charset; the harness only has content_type.
+        if response.respond_to?(:media_type) && response.media_type
+          response.media_type
+        elsif response.respond_to?(:content_type)
+          response.content_type
+        end
+      end
+
+      def emit_idempotency_key_header(key)
+        response.set_header("X-Idempotency-Key", key) if respond_to?(:response) && response
+      end
+
+      def emit_idempotency_replayed_header(replayed)
+        response.set_header("X-Idempotency-Replayed", replayed.to_s) if respond_to?(:response) && response
+      end
+
+      # Deterministic JSON regardless of param insertion order: hashes become
+      # sorted [key, value] pairs, arrays keep their (significant) order, and
+      # non-JSON-primitive leaves are stringified so nothing can raise.
+      def idempotency_deep_sort(value)
+        case value
+        when Hash then value.map { |k, v| [k.to_s, idempotency_deep_sort(v)] }.sort_by(&:first)
+        when Array then value.map { |v| idempotency_deep_sort(v) }
+        else idempotency_scalar(value)
+        end
+      end
+
+      def idempotency_scalar(value)
+        case value
+        when Float then value.finite? ? value : value.to_s # JSON.generate raises on NaN/Infinity
+        when nil, true, false, Integer, String then value
+        else value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -20,4 +20,5 @@ module ConcernsOnRails
   Sanitizable   = Models::Sanitizable
   Maskable      = Models::Maskable
   Monetizable   = Models::Monetizable
+  Auditable     = Models::Auditable
 end

data/lib/concerns_on_rails/models/auditable.rb

@@ -0,0 +1,224 @@
+require "active_support/concern"
+require "bigdecimal"
+require "json"
+
+module ConcernsOnRails
+  module Models
+    # Lightweight change history ("paper_trail-lite") stored as JSON entries in
+    # a single text column on the same table — no extra tables, no versioning
+    # engine — so it works on any database, including SQLite.
+    #
+    #   class Product < ApplicationRecord
+    #     include ConcernsOnRails::Auditable
+    #
+    #     auditable_by :price, :status                       # default column :audit_log
+    #     # auditable_by :price, into: :history,
+    #     #              actor: -> { Current.user&.email },  # stamps "by"
+    #     #              max_entries: 50,                    # keep the newest 50
+    #     #              max_value_length: 120               # truncate long from/to strings
+    #   end
+    #
+    #   product.update!(price: 200)
+    #   product.audit_trail
+    #   # => [{"field"=>"price", "from"=>100, "to"=>200,
+    #   #      "at"=>"2026-06-10T12:34:56Z", "by"=>"admin@shop.com"}]
+    #   product.last_change_for(:price)            # newest entry for one field
+    #   product.audited_changes_since(1.day.ago)
+    #   product.clear_audit_trail!                 # wipe the column (skips callbacks)
+    #
+    # Notes:
+    #   * One entry per changed field per save; creates record `"from" => nil`.
+    #     "by" is omitted entirely when no actor is configured (or it returns nil).
+    #   * Entries are appended in the same INSERT/UPDATE via before_save — no
+    #     extra queries. Writes that skip callbacks (update_column(s), touch,
+    #     increment!) are NOT audited.
+    #   * Values are JSON-coerced: times → ISO8601 UTC strings, BigDecimal →
+    #     plain numeric string, symbols → strings. With `max_value_length:`,
+    #     String values longer than the limit are stored as the first N
+    #     characters plus a trailing "…" (non-strings are never truncated).
+    #   * A corrupt or non-array column decodes as [] and is overwritten on the
+    #     next tracked save. Concurrent saves of one row are last-writer-wins.
+    #   * New entries are built on the PERSISTED trail (so an aborted save
+    #     can't duplicate entries on retry). Assigning the audit column by
+    #     hand in the same save as a tracked change is therefore ignored —
+    #     use clear_audit_trail! to reset it.
+    #   * Reach for paper_trail/audited when you need reify/undo, who-dunnit
+    #     queries across models, or association tracking.
+    module Auditable
+      extend ActiveSupport::Concern
+
+      LABEL = "ConcernsOnRails::Models::Auditable".freeze
+      DEFAULT_INTO = :audit_log
+      DEFAULT_MAX_ENTRIES = 200
+
+      included do
+        class_attribute :auditable_fields, instance_accessor: false, default: []
+        class_attribute :auditable_into, instance_accessor: false, default: DEFAULT_INTO
+        class_attribute :auditable_actor, instance_accessor: false, default: nil
+        class_attribute :auditable_max_entries, instance_accessor: false, default: DEFAULT_MAX_ENTRIES
+        class_attribute :auditable_max_value_length, instance_accessor: false, default: nil
+      end
+
+      module ClassMethods
+        include ConcernsOnRails::Support::ColumnGuard
+
+        # Configure the tracked fields and the audit column. See the module docs.
+        def auditable_by(*fields, into: DEFAULT_INTO, actor: nil, max_entries: DEFAULT_MAX_ENTRIES, max_value_length: nil)
+          fields = fields.flatten.map(&:to_sym).uniq
+          into = into.to_sym
+          validate_auditable!(fields, into: into, actor: actor, max_entries: max_entries, max_value_length: max_value_length)
+
+          self.auditable_fields = fields
+          self.auditable_into = into
+          self.auditable_actor = actor
+          self.auditable_max_entries = max_entries
+          self.auditable_max_value_length = max_value_length
+          ensure_columns!(LABEL, into, *fields)
+
+          before_save :auditable_capture_changes
+        end
+
+        private
+
+        def validate_auditable!(fields, into:, actor:, max_entries:, max_value_length:)
+          raise ArgumentError, "#{LABEL}: auditable_by requires at least one field" if fields.empty?
+          raise ArgumentError, "#{LABEL}: cannot track the audit column ':#{into}' itself" if fields.include?(into)
+          raise ArgumentError, "#{LABEL}: max_entries must be a positive Integer or nil" unless positive_integer_or_nil?(max_entries)
+          unless positive_integer_or_nil?(max_value_length)
+            raise ArgumentError, "#{LABEL}: max_value_length must be a positive Integer or nil"
+          end
+          raise ArgumentError, "#{LABEL}: actor must be callable (respond to #call)" unless actor.nil? || actor.respond_to?(:call)
+        end
+
+        def positive_integer_or_nil?(value)
+          value.nil? || (value.is_a?(Integer) && value.positive?)
+        end
+      end
+
+      # ---- instance methods ----
+
+      # Decoded audit entries, oldest first. [] for blank/corrupt columns.
+      def audit_trail
+        auditable_decode(self[self.class.auditable_into])
+      end
+
+      # The most recent entry recorded for `field`, or nil.
+      def last_change_for(field)
+        name = field.to_s
+        audit_trail.reverse_each.find { |entry| entry["field"] == name }
+      end
+
+      # Entries recorded at or after `time`, oldest first. Entries whose "at"
+      # is missing or unparseable are excluded.
+      def audited_changes_since(time)
+        audit_trail.select do |entry|
+          at = auditable_parse_time(entry["at"])
+          at && at >= time
+        end
+      end
+
+      # Wipe the trail with a single UPDATE. Deliberately uses update_column so
+      # clearing can never itself be captured or run other callbacks/validations.
+      def clear_audit_trail!
+        raise ArgumentError, "#{LABEL}: clear_audit_trail! cannot be called on a new record" if new_record?
+
+        update_column(self.class.auditable_into, nil)
+      end
+
+      private
+
+      # before_save hook — appends one entry per changed tracked field so the
+      # audit column rides the same INSERT/UPDATE statement.
+      def auditable_capture_changes
+        fields = self.class.auditable_fields
+        return if fields.blank?
+
+        pending = respond_to?(:changes_to_save) ? changes_to_save : changes
+        tracked = pending.slice(*fields.map(&:to_s))
+        return if tracked.empty?
+
+        entries = auditable_persisted_trail + auditable_build_entries(tracked)
+        max = self.class.auditable_max_entries
+        entries = entries.last(max) if max
+        self[self.class.auditable_into] = JSON.generate(entries)
+      end
+
+      # Base the new trail on the PERSISTED column value, not the in-memory
+      # attribute: an aborted save leaves the in-memory column holding the
+      # entry it appended, and reading it back on retry would duplicate the
+      # change. (attribute_in_database is Rails 5.1+; fall back for 5.0.)
+      def auditable_persisted_trail
+        into = self.class.auditable_into
+        raw = respond_to?(:attribute_in_database) ? attribute_in_database(into.to_s) : self[into]
+        auditable_decode(raw)
+      end
+
+      def auditable_build_entries(tracked)
+        at = Time.now.utc.iso8601
+        by = auditable_resolve_actor
+        tracked.map do |field, (from, to)|
+          entry = { "field" => field, "from" => auditable_entry_value(from), "to" => auditable_entry_value(to), "at" => at }
+          entry["by"] = by unless by.nil?
+          entry
+        end
+      end
+
+      def auditable_resolve_actor
+        actor = self.class.auditable_actor
+        return nil unless actor
+
+        auditable_json_value(instance_exec(&actor))
+      end
+
+      # from/to pipeline: JSON coercion, then opt-in truncation.
+      def auditable_entry_value(value)
+        auditable_truncate(auditable_json_value(value))
+      end
+
+      # Keep the first max_value_length characters and mark the cut with "…".
+      # Only String values are truncated — numbers, booleans, arrays pass through.
+      def auditable_truncate(value)
+        limit = self.class.auditable_max_value_length
+        return value unless limit && value.is_a?(String) && value.length > limit
+
+        "#{value[0, limit]}…"
+      end
+
+      # Coerce a Ruby value to a JSON-safe primitive. Times → ISO8601 UTC,
+      # BigDecimal → plain numeric string (precision-safe), Symbol → String.
+      # TimeWithZone is caught by `when Time` (it masquerades via #is_a?).
+      def auditable_json_value(value)
+        case value
+        when nil, true, false, Integer, String then value
+        when Float then auditable_float_value(value)
+        when BigDecimal then value.to_s("F")
+        when Time, DateTime then value.to_time.utc.iso8601
+        when Date then value.iso8601
+        when Symbol then value.to_s
+        else value.as_json
+        end
+      end
+
+      # JSON.generate raises on non-finite floats — store NaN/Infinity as strings.
+      def auditable_float_value(value)
+        value.finite? ? value : value.to_s
+      end
+
+      def auditable_parse_time(raw)
+        Time.iso8601(raw.to_s)
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # Tolerant decode: blank, invalid JSON or non-array payloads become [].
+      def auditable_decode(raw)
+        return [] if raw.nil? || raw.to_s.strip.empty?
+
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Array) ? parsed.grep(Hash) : []
+      rescue JSON::ParserError
+        []
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.15.0".freeze
+  VERSION = "1.16.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -35,6 +35,7 @@ require "concerns_on_rails/models/taggable"
 require "concerns_on_rails/models/sanitizable"
 require "concerns_on_rails/models/maskable"
 require "concerns_on_rails/models/monetizable"
+require "concerns_on_rails/models/auditable"
 
 # Controller concerns
 require "concerns_on_rails/controllers/paginatable"
@@ -48,6 +49,7 @@ require "concerns_on_rails/controllers/localizable"
 require "concerns_on_rails/controllers/authorizable"
 require "concerns_on_rails/controllers/throttleable"
 require "concerns_on_rails/controllers/timezoneable"
+require "concerns_on_rails/controllers/idempotentable"
 
 # 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.15.0
+  version: 1.16.0
 platform: ruby
 authors:
 - Ethan Nguyen
@@ -73,6 +73,7 @@ files:
 - 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/idempotentable.rb
 - lib/concerns_on_rails/controllers/includable.rb
 - lib/concerns_on_rails/controllers/localizable.rb
 - lib/concerns_on_rails/controllers/paginatable.rb
@@ -84,6 +85,7 @@ files:
 - 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/auditable.rb
 - lib/concerns_on_rails/models/expirable.rb
 - lib/concerns_on_rails/models/hashable.rb
 - lib/concerns_on_rails/models/maskable.rb