concerns_on_rails 1.18.0 → 1.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30c62bfbc26afd05fe7ed2e991add6fa180f3e71316ec638a045932e89bf2ce1
-  data.tar.gz: af936258d441cf0206e120853f0a227967f663e577983628087defe2d60d7202
+  metadata.gz: 191acd17664d56588e54832b2377ede09cf836fe481a0e4c27246adae9f2eb76
+  data.tar.gz: 95dc3faff52552da6688961fd51e926d4eb2a041f9974f05ea77a491b698d434
 SHA512:
-  metadata.gz: 359c8240a7d15da31c2a3236a69cb75b1cce57dc5fb80869214c64c05b3b7051d2a17ee17e73d5e9aec3321a53ca8a5de7ada2e73fa80f1f4da50e41fbfc6398
-  data.tar.gz: 6b7388a71ceed19ee2517786f5bffdde6acb2e13506ce4ee00b983ff46293a9479aa91d01e2f6912e50a7eb1944f644534369215274fa2234fd889315e32e6f1
+  metadata.gz: f472e83548c6ccd7850c3d3c9994cbb1efac4637210f07f35f69e16ca700aa7f131bed7d24737e825896aa8301cd2786dfe70aa0f563002f1bc8d199056fae28
+  data.tar.gz: 6c231481577b2db38df1730cb16ad72c2f06ea7bba9d9dc0730e0c8068dce94597b26b514241e1ebd6be51b91caf4ae75dbb8ea32aa11f1aef9109cd45f3d38b

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 <!-- CHANGELOG.md -->
 
+## 1.19.0 (2026-06-13)
+
+Two new concerns, selected by a unanimous three-judge design panel over six independently-proposed candidates (typed-JSON-settings and RFC-deprecation-headers each beat conditional counter caches, deep cloning, anonymization, params contracts, feature gates, and maintenance mode on value × shippability), then hardened in review (an `ActiveSupport::TimeWithZone` passed as `deprecated_at:`/`sunset_at:` — i.e. `Time.current` — was spuriously rejected as unparseable because `Module#===` ignores TimeWithZone's `is_a?(Time)` lie; a bare `Date` written to a `:datetime` key now anchors to midnight UTC instead of the host zone via `Date#to_time`; an unknown `header_format:` now raises at declaration time instead of silently emitting the RFC form). 894 examples, 0 failures.
+
+### Added
+- **Models::Storable**: typed, defaulted, optionally-validated accessors over a single JSON-or-text column ("store_attribute-lite") — native `store_accessor` is untyped on every supported Rails version (a form-submitted `"true"` stays a String), has no defaults and no per-key dirty methods. `storable_by :settings, theme: { type: :string, default: "light", in: %w[light dark] }, ...` (repeatable — same column merges keys, columns independent, subclasses add keys without mutating the parent; `prefix:`/`suffix:` affix the generated names) gives a casting reader/writer, a `?` predicate (boolean keys), `_changed?`/`_was` computed per key against the column's own previous value, and `reset_<key>` (key removal → default applies again, distinct from an explicitly-written nil, which reads back as nil). Casting via `ActiveModel::Type` with JSON-safe representations: `:decimal` as a precision-safe String, `:datetime` as UTC ISO8601 with microseconds, `:date` as ISO8601, `:json` passthrough (reader returns a dup — reassign, don't mutate). The codec never uses `serialize` (sidestepping the Rails 7.1 kwarg drift entirely): a plain text column is JSON-encoded/decoded manually and tolerantly (corrupt JSON → `{}`, garbage values cast to nil, readers never raise), while native `json`/`jsonb` columns and host-app-`serialize`d columns are detected lazily and handed the Hash. Undeclared keys are preserved; string keys throughout; `in:` adds an inclusion validation on the (affixed) accessor name, nil/absent passing. Every generated name is collision-checked against methods and columns at macro time; key specs are shape- and type-validated (`ArgumentError`, ColumnGuard for the column). Whole-column dirty / last-write-wins semantics documented. Zero new runtime dependencies.
+- **Controllers::Deprecatable**: standards-based API endpoint deprecation — RFC 9745 `Deprecation` (final structured-fields form `@<unix>`, or the widely-deployed pre-RFC draft literal `true` via `header_format: :legacy`), RFC 8594 `Sunset` (IMF-fixdate via `Time#httpdate`, not the classic hand-rolled ISO8601 bug), and RFC 8288 `Link` rels (`rel="deprecation"` migration docs + `rel="successor-version"`, appended to any existing Link header, never clobbered). `deprecate_actions :index, :show, deprecated_at:, sunset_at:, link:, successor:, after_sunset:, header_format:, notify:` — repeatable, inherited; no positional actions = whole-controller catch-all; the LAST matching rule wins (deliberately the reverse of Idempotentable's first-match: deprecation rules are configuration overrides, so a base-controller catch-all is naturally overridden by a later action-specific declaration) and exactly one Deprecation header is ever emitted. Times parse eagerly at declaration (`ArgumentError` on garbage; bare dates = 00:00 UTC — sunset is an instant; `sunset_at >= deprecated_at` enforced; TimeWithZone accepted). `after_sunset: :gone` (requires `sunset_at`) halts with 410 `endpoint_sunset` at/after the boundary instant — headers still ride the 410 so the cut-off self-documents — via Respondable's `render_error` when present, inline envelope otherwise; the default `:headers` never blocks. Every matching hit instruments `deprecated_endpoint.concerns_on_rails` (`ActiveSupport::Notifications`) and `instance_exec`s `notify:` (raising notify propagates — broken metrics should be loud) through the `on_deprecated_access(rule)` override point, so teams can measure stragglers before flipping enforcement. `deprecation_active?`/`sunset_passed?` predicates for serializers; one UTC clock seam (`deprecation_now`). Zero new runtime dependencies.
+
 ## 1.18.0 (2026-06-12)
 
 Two new concerns, designed and hardened through adversarial design- and code-review rounds (a shared-reflection registration strategy that produced invalid SQL was caught and replaced before implementation; a time-serialization path that silently lost sub-second precision likewise; a NULL page-boundary value that would have silently dropped rows now raises; a post-review pass fixed `has_many :through` aliasing, which crashed at macro time under lazy class loading and re-derived its `source:` from the alias name at query time). A follow-up enhancement round added bidirectional cursors, allow-listed order presets, and row-value predicates to CursorPaginatable, and `only:`/`except:`/`deprecated:`/`alias_foreign_key:` to Aliasable. 793 examples, 0 failures.

data/README.md

@@ -46,6 +46,7 @@ Article.published.without_deleted.find("hello-world")
   - [Auditable](#-auditable) — single-column change history ("paper_trail-lite")
   - [Lockable](#-lockable) — failed-attempt tracking + account lockout
   - [Aliasable](#-aliasable) — full read/write/query aliases for associations
+  - [Storable](#-storable) — typed accessors over one JSON settings column ("store_attribute-lite")
 - **Controller concerns**
   - [Paginatable](#-paginatable) — offset pagination with headers
   - [CursorPaginatable](#-cursorpaginatable) — cursor (keyset) pagination with headers
@@ -61,6 +62,7 @@ Article.published.without_deleted.find("hello-world")
   - [Timezoneable](#-timezoneable) — per-request `Time.zone` from params / header / cookie
   - [Idempotentable](#-idempotentable) — `Idempotency-Key` request replay (409 on concurrent duplicates)
   - [WebhookVerifiable](#-webhookverifiable) — HMAC verification for inbound webhooks (Stripe/GitHub/Shopify)
+  - [Deprecatable](#-deprecatable) — RFC `Deprecation`/`Sunset` headers + 410 sunset enforcement
 - [Module paths & namespacing](#-module-paths--namespacing)
 - [Development](#-development)
 - [Contributing](#-contributing)
@@ -1039,6 +1041,42 @@ Book.joins(:sections).where(sections: { title: "Intro" })
 
 ---
 
+## ⚙️ Storable
+
+Typed, defaulted, optionally-validated accessors over a **single JSON (or text) column** ("store_attribute-lite"). Rails' native `store_accessor` is untyped on every supported version — a form-submitted `"true"` stays the String `"true"` — with no defaults and no per-key dirty tracking; that gap is why the `store_attribute` / `jsonb_accessor` gems exist.
+
+```ruby
+class Account < ApplicationRecord
+  include ConcernsOnRails::Storable
+
+  storable_by :settings,
+    theme:          { type: :string,  default: "light", in: %w[light dark] },
+    notifications:  { type: :boolean, default: true },
+    items_per_page: { type: :integer, default: 25 },
+    trial_ends_at:  { type: :datetime }
+  storable_by :flags, { beta: { type: :boolean, default: false } }, prefix: :flag
+end
+
+account.theme                     # => "light"  (virtual default; nothing persisted)
+account.notifications = "0"       # params arrive as strings…
+account.notifications            # => false    (…and read back cast)
+account.notifications?           # boolean keys get a predicate
+account.items_per_page_changed?  # per-key dirty (and items_per_page_was)
+account.reset_theme              # drop the key → the default applies again
+account.flag_beta                # affixed accessor
+```
+
+**Options** (per key): `type:` (`:string` default, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`, `:json`), `default:` (a value, or a Proc `instance_exec`'d per read), `in:` (inclusion validation, errors on the accessor name). Macro options: `prefix:` / `suffix:` affix the generated method names (the collision escape hatch). The macro is repeatable — repeat calls for the same column merge keys, different columns are independent, and subclasses can add keys without affecting the parent.
+
+**Notes**
+- Works on a plain `text` column (JSON encoded/decoded internally), a native `json`/`jsonb` column, or a column the host app already `serialize`d — detected automatically. `serialize` itself is never used, so the Rails 7.1 API drift is irrelevant.
+- nil vs unset: a written `nil` (explicit JSON null) reads back as `nil` and does **not** fall back to the default; `reset_<key>` removes the key so the default applies again. `:decimal` is stored as a precision-safe string, `:date`/`:datetime` as ISO8601 (datetime in UTC at microsecond precision).
+- Writing one key dirties (and saves) the **whole column** — concurrent writers to different keys are last-write-wins on the hash. Undeclared keys are preserved. `:json` readers return a dup: reassign, don't mutate in place.
+- Generated names are collision-checked against existing methods and columns at macro time (`ArgumentError`; affix to escape). Read-side casting never raises — corrupt column JSON decodes as `{}`, garbage values cast to `nil`.
+- Reach for [`store_attribute`](https://github.com/palkan/store_attribute) / [`jsonb_accessor`](https://github.com/madeintandem/jsonb_accessor) when you need to **query** into the store (jsonb operators, store-backed scopes).
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -1504,6 +1542,39 @@ end
 
 ---
 
+## 🌅 Deprecatable
+
+Standards-based **API endpoint deprecation**: the RFC 9745 `Deprecation` and RFC 8594 `Sunset` headers, `Link` rels pointing at the migration docs and the successor endpoint, an instrumentation hook to measure who still calls the endpoint, and optional **410 Gone** enforcement once the sunset instant passes. This is how Stripe/GitHub/Zalando retire API versions — and nothing native exists on any Rails version.
+
+```ruby
+class Api::V1::OrdersController < ApplicationController
+  include ConcernsOnRails::Controllers::Deprecatable
+
+  deprecate_actions :index, :show,
+    deprecated_at: "2026-06-01",
+    sunset_at:     "2026-12-31T00:00:00Z",
+    link:          "https://docs.example.com/v1-migration",
+    successor:     "https://api.example.com/v2/orders",
+    after_sunset:  :gone,         # default :headers — announce, never block
+    notify:        -> { StatsD.increment("api.v1.orders.deprecated") }
+end
+
+# Every matching response then carries:
+#   Deprecation: @1780272000
+#   Sunset: Thu, 31 Dec 2026 00:00:00 GMT
+#   Link: <https://docs.example.com/v1-migration>; rel="deprecation", <https://api.example.com/v2/orders>; rel="successor-version"
+```
+
+**Options**: `deprecated_at:` (required; Time/Date/String — parsed eagerly, normalized to UTC), `sunset_at:` (optional, must be ≥ `deprecated_at`; a bare date means **00:00 UTC that day** — sunset is an instant, not end-of-day), `link:` / `successor:` (URLs), `after_sunset:` (`:headers` default | `:gone` → 410 with code `endpoint_sunset` at/after the sunset instant), `header_format:` (`:rfc9745` default, `@<unix>` | `:legacy`, the widely-deployed draft literal `true`), `notify:` (callable, `instance_exec`'d per matching request — a raising notify propagates on purpose). No positional actions = catch-all for the whole controller. **The last matching rule wins**, so an action-specific declaration naturally overrides a base controller's catch-all.
+
+**Notes**
+- Headers go out on every matching response — **including the 410 itself**, so the cut-off self-documents. `Link` values are appended to any existing `Link` header (pagination, CDN), never clobbered.
+- Each hit instruments `deprecated_endpoint.concerns_on_rails` (`ActiveSupport::Notifications`) with `{controller:, action:, deprecated_at:, sunset_at:}` — subscribe to count stragglers *before* flipping `after_sunset: :gone`. Override `on_deprecated_access(rule)` to replace the default instrumentation.
+- 410 bodies delegate to `Respondable`'s `render_error` when present (inline JSON envelope otherwise). `skip_before_action :apply_api_deprecations` opts an action out; `deprecation_active?` / `sunset_passed?` are available for serializers/response bodies.
+- Flipping `:gone` is a deliberate, customer-facing cut-off — coordinate it with `notify:`-driven outreach, and mind CDN-cached responses that may outlive the headers.
+
+---
+
 ## 🗂️ Module paths & namespacing
 
 Every concern is available under two paths:

data/lib/concerns_on_rails/controllers/deprecatable.rb

@@ -0,0 +1,268 @@
+require "active_support/concern"
+require "active_support/notifications"
+require "date"
+require "time"
+
+module ConcernsOnRails
+  module Controllers
+    # Standards-based API endpoint deprecation — the receiving end of an API
+    # retirement plan (how Stripe / GitHub / Zalando sunset versions). Declare
+    # which actions are deprecated and the standard signalling headers go out on
+    # every response so clients (and their SDKs) can discover the deprecation,
+    # the migration docs, the successor endpoint, and the hard cut-off — then
+    # optionally enforce a 410 Gone once that cut-off passes.
+    #
+    #   class Api::V1::OrdersController < ApplicationController
+    #     include ConcernsOnRails::Controllers::Deprecatable
+    #
+    #     deprecate_actions :index, :show,
+    #       deprecated_at: "2026-06-01",
+    #       sunset_at:     "2026-12-31T00:00:00Z",
+    #       link:          "https://docs.example.com/v1-migration",
+    #       successor:     "https://api.example.com/v2/orders",
+    #       after_sunset:  :gone,
+    #       notify:        -> { StatsD.increment("api.v1.orders.deprecated") }
+    #   end
+    #
+    # Headers emitted (always — including on the 410, so the failure is
+    # self-documenting):
+    #   * Deprecation — RFC 9745. The final form is a structured-fields Date
+    #     item: "@<unix-seconds>" of `deprecated_at`. `header_format: :legacy`
+    #     emits the still-widely-deployed pre-RFC draft form, the literal "true".
+    #   * Sunset      — RFC 8594. An IMF-fixdate (HTTP-date) via Time#httpdate,
+    #     NOT ISO 8601 — hand-rolling that is the classic bug.
+    #   * Link        — RFC 8288. rel="deprecation" (the migration doc) and/or
+    #     rel="successor-version" (the replacement endpoint), APPENDED to any
+    #     Link header already on the response (pagination / CDN), never clobbered.
+    #
+    # `sunset_at` is an INSTANT, not a calendar day: a bare date "2026-12-31" is
+    # normalised to 00:00 UTC, so the endpoint dies at the START of that day, not
+    # end-of-day. Times are parsed eagerly at declaration time and normalised to
+    # UTC.
+    #
+    # THE LAST MATCHING RULE WINS (deliberately the reverse of Idempotentable's
+    # first-match): deprecation rules are configuration overrides, not guards, so
+    # a V1 base controller's catch-all `deprecate_actions` is naturally
+    # overridden by a later, action-specific declaration in a subclass. Exactly
+    # one rule applies per request and exactly one Deprecation header is emitted.
+    # With no positional actions a rule is a catch-all for the whole controller
+    # (the WebhookVerifiable convention).
+    #
+    # `after_sunset: :gone` (requires `sunset_at`) halts with 410 once the sunset
+    # instant is reached (the boundary instant counts as sunset — inclusive). The
+    # default `:headers` NEVER blocks, however long past sunset — flip to `:gone`
+    # only once metrics show callers have migrated. `on_deprecated_access` is that
+    # metrics seam: it instruments "deprecated_endpoint.concerns_on_rails" and
+    # runs `notify:`. A raising `notify` propagates on purpose — a broken metrics
+    # hook should be loud, not silently swallowed (WebhookVerifiable's stance).
+    module Deprecatable
+      extend ActiveSupport::Concern
+
+      LABEL = "ConcernsOnRails::Controllers::Deprecatable".freeze
+      VALID_AFTER_SUNSET = %i[headers gone].freeze
+      VALID_HEADER_FORMATS = %i[rfc9745 legacy].freeze
+      UNPARSEABLE = "could not be parsed (pass a Time, Date, DateTime, or parseable String)".freeze
+
+      included do
+        class_attribute :deprecatable_rules, instance_accessor: false, default: []
+        before_action :apply_api_deprecations
+      end
+
+      module ClassMethods
+        # Declare a deprecation rule. No positional actions = catch-all for the
+        # whole controller. Repeatable; rules accumulate (reassigned, never
+        # mutated, so subclasses inherit) and the LAST one matching the current
+        # action wins.
+        def deprecate_actions(*actions, deprecated_at: nil, sunset_at: nil, link: nil, successor: nil,
+                              after_sunset: :headers, header_format: :rfc9745, notify: nil)
+          actions = actions.flatten.map(&:to_s)
+          after_sunset = after_sunset.to_sym
+          header_format = header_format.to_sym
+
+          deprecated_time = parse_deprecation_time(deprecated_at)
+          sunset_time = sunset_at.nil? ? nil : parse_deprecation_time(sunset_at)
+          validate_deprecate_actions!(deprecated_at: deprecated_at, deprecated_time: deprecated_time,
+                                      sunset_at: sunset_at, sunset_time: sunset_time, link: link,
+                                      successor: successor, after_sunset: after_sunset, notify: notify)
+          unless VALID_HEADER_FORMATS.include?(header_format)
+            raise ArgumentError, "#{LABEL}: :header_format must be one of #{VALID_HEADER_FORMATS.join(', ')}"
+          end
+
+          rule = { actions: actions, deprecated_at: deprecated_time, sunset_at: sunset_time,
+                   link: link, successor: successor, after_sunset: after_sunset,
+                   header_format: header_format, notify: notify }
+          self.deprecatable_rules = deprecatable_rules + [rule]
+        end
+
+        private
+
+        def validate_deprecate_actions!(deprecated_at:, deprecated_time:, sunset_at:, sunset_time:,
+                                        link:, successor:, after_sunset:, notify:)
+          raise ArgumentError, "#{LABEL}: :deprecated_at is required" if deprecated_at.nil?
+          raise ArgumentError, "#{LABEL}: :deprecated_at #{UNPARSEABLE}" if deprecated_time.nil?
+
+          validate_deprecation_sunset!(sunset_at, sunset_time, deprecated_time, after_sunset)
+          validate_deprecation_link!(:link, link)
+          validate_deprecation_link!(:successor, successor)
+          raise ArgumentError, "#{LABEL}: :notify must be callable" unless notify.nil? || notify.respond_to?(:call)
+        end
+
+        def validate_deprecation_sunset!(sunset_at, sunset_time, deprecated_time, after_sunset)
+          unless VALID_AFTER_SUNSET.include?(after_sunset)
+            raise ArgumentError, "#{LABEL}: :after_sunset must be one of #{VALID_AFTER_SUNSET.join(', ')}"
+          end
+
+          unless sunset_at.nil?
+            raise ArgumentError, "#{LABEL}: :sunset_at #{UNPARSEABLE}" if sunset_time.nil?
+            raise ArgumentError, "#{LABEL}: :sunset_at must be on or after :deprecated_at" if sunset_time < deprecated_time
+          end
+
+          raise ArgumentError, "#{LABEL}: after_sunset: :gone requires :sunset_at" if after_sunset == :gone && sunset_time.nil?
+        end
+
+        def validate_deprecation_link!(name, value)
+          return if value.nil?
+          return if value.is_a?(String) && !value.strip.empty?
+
+          raise ArgumentError, "#{LABEL}: :#{name} must be a non-blank String"
+        end
+
+        # Eager parse to a UTC Time. A bare Date (or date-only String) becomes
+        # midnight UTC — sunset is an instant at the START of the day.
+        def parse_deprecation_time(value)
+          case value
+          # TimeWithZone listed explicitly: it lies about is_a?(Time) but
+          # Module#=== checks the real ancestry, so `when Time` alone would
+          # miss it — and Time.current / 1.month.from_now are exactly the
+          # values Rails hosts pass.
+          when ActiveSupport::TimeWithZone, Time then value.utc
+          when DateTime then value.to_time.utc
+          when Date then Time.utc(value.year, value.month, value.day)
+          when String then parse_deprecation_string(value)
+          end
+        end
+
+        def parse_deprecation_string(value)
+          return nil if value.strip.empty?
+
+          # DateTime.parse reads a zoneless string as UTC (+00:00) regardless of
+          # the host's system timezone — deterministic — and honours an explicit
+          # offset when one is present.
+          DateTime.parse(value).to_time.utc
+        rescue ArgumentError, TypeError
+          nil
+        end
+      end
+
+      # before_action entry point. Public so host apps can
+      # `skip_before_action :apply_api_deprecations` or override it.
+      def apply_api_deprecations
+        rule = deprecation_rule_for_action
+        return nil unless rule
+
+        # Order matters: headers go out unconditionally (so even the 410 carries
+        # them), THEN we record the access, THEN enforce. Recording before
+        # enforcing means metrics still count callers who get the 410.
+        emit_deprecation_headers(rule)
+        on_deprecated_access(rule)
+        enforce_deprecation_sunset(rule)
+      end
+
+      # Public override point + instrumentation seam. Default: emit an
+      # ActiveSupport::Notifications event and run the rule's `notify:` callable
+      # (instance_exec'd, so it can read controller state). A raising `notify`
+      # propagates by design.
+      def on_deprecated_access(rule)
+        ActiveSupport::Notifications.instrument(
+          "deprecated_endpoint.concerns_on_rails",
+          controller: deprecation_controller_name, action: deprecation_action_name,
+          deprecated_at: rule[:deprecated_at], sunset_at: rule[:sunset_at]
+        )
+        instance_exec(&rule[:notify]) if rule[:notify]
+      end
+
+      # True when some rule covers the current action.
+      def deprecation_active?
+        !deprecation_rule_for_action.nil?
+      end
+
+      # True when the matching rule has a sunset_at that the clock has reached.
+      def sunset_passed?
+        deprecation_sunset_reached?(deprecation_rule_for_action)
+      end
+
+      private
+
+      def deprecation_rule_for_action
+        action = deprecation_action_name
+        return nil unless action
+
+        # Last match wins — see the module comment. reverse_each.find returns the
+        # most recently declared rule covering this action (catch-all or not).
+        self.class.deprecatable_rules.reverse_each.find do |rule|
+          rule[:actions].empty? || rule[:actions].include?(action)
+        end
+      end
+
+      def emit_deprecation_headers(rule)
+        return unless respond_to?(:response) && response
+
+        response.set_header("Deprecation", deprecation_header_value(rule))
+        response.set_header("Sunset", rule[:sunset_at].httpdate) if rule[:sunset_at]
+        emit_deprecation_link_header(rule)
+      end
+
+      def deprecation_header_value(rule)
+        # :legacy is the pre-RFC draft form everyone already ships; :rfc9745 is
+        # the structured-fields Date item finalised in RFC 9745.
+        return "true" if rule[:header_format] == :legacy
+
+        "@#{rule[:deprecated_at].to_i}"
+      end
+
+      def emit_deprecation_link_header(rule)
+        parts = []
+        parts << "<#{rule[:link]}>; rel=\"deprecation\"" if rule[:link]
+        parts << "<#{rule[:successor]}>; rel=\"successor-version\"" if rule[:successor]
+        return if parts.empty?
+
+        value = parts.join(", ")
+        # Append, never clobber: pagination / CDN may already have set Link.
+        existing = response.headers["Link"]
+        value = "#{existing}, #{value}" unless existing.to_s.empty?
+        response.set_header("Link", value)
+      end
+
+      def enforce_deprecation_sunset(rule)
+        return unless rule[:after_sunset] == :gone
+        return unless deprecation_sunset_reached?(rule)
+
+        message = "This endpoint was sunset on #{rule[:sunset_at].httpdate}."
+        return render_error(message: message, status: :gone, code: "endpoint_sunset") if respond_to?(:render_error)
+        return unless respond_to?(:response) && response
+
+        render json: { success: false, error: { message: message, code: "endpoint_sunset" } }, status: :gone
+      end
+
+      # Inclusive: the boundary instant itself counts as sunset.
+      def deprecation_sunset_reached?(rule)
+        !!(rule && rule[:sunset_at] && deprecation_now >= rule[:sunset_at])
+      end
+
+      def deprecation_action_name
+        respond_to?(:action_name) ? action_name.to_s : nil
+      end
+
+      def deprecation_controller_name
+        return controller_path if respond_to?(:controller_path)
+
+        self.class.name
+      end
+
+      # Single clock seam so travel_to drives everything in specs.
+      def deprecation_now
+        Time.now.utc
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -23,4 +23,5 @@ module ConcernsOnRails
   Auditable     = Models::Auditable
   Lockable      = Models::Lockable
   Aliasable     = Models::Aliasable
+  Storable      = Models::Storable
 end

data/lib/concerns_on_rails/models/storable.rb

@@ -0,0 +1,436 @@
+require "active_support/concern"
+require "active_support/core_ext/object/deep_dup"
+require "active_model/type"
+require "bigdecimal"
+require "json"
+require "time"
+
+module ConcernsOnRails
+  module Models
+    # Typed, defaulted, optionally-validated accessors over a single JSON (or
+    # serialized-text) column ("store_attribute-lite"). Rails' native
+    # `store_accessor` is untyped on every supported version (a form-submitted
+    # "true" stays the String "true"), ships no defaults, and exposes no
+    # per-key dirty methods — the gap that the store_attribute / jsonb_accessor
+    # gems exist to fill. This concern closes it with no extra dependency.
+    #
+    #   class Account < ApplicationRecord
+    #     include ConcernsOnRails::Storable
+    #
+    #     storable_by :settings,
+    #       theme:          { type: :string,  default: "light", in: %w[light dark] },
+    #       notifications:  { type: :boolean, default: true },
+    #       items_per_page: { type: :integer, default: 25 },
+    #       trial_ends_at:  { type: :datetime }
+    #     storable_by :flags, { beta: { type: :boolean, default: false } }, prefix: :flag
+    #   end
+    #
+    #   account.theme              # => "light" (virtual default; nothing stored yet)
+    #   account.notifications = "0"
+    #   account.notifications      # => false   (cast, not the String "0")
+    #   account.notifications?     # => false   (boolean keys get a predicate)
+    #   account.flag_beta          # => false   (prefixed accessor)
+    #   account.items_per_page_changed?  # per-key dirty, computed off the column's _was
+    #   account.reset_theme        # drop the key so the reader falls back to the default
+    #
+    # Per key: `type:` (:string default, :integer, :float, :decimal, :boolean,
+    # :date, :datetime, :json), `default:` (a value, or a Proc instance_exec'd
+    # per read), `in:` (an enumerable membership set). The macro is repeatable —
+    # repeat calls for the SAME column merge keys; different columns are
+    # independent. `prefix:`/`suffix:` rename the generated accessors as
+    # `<prefix>_<key>_<suffix>`.
+    #
+    # Notes:
+    #   * Whole-column dirty: writing one key reassigns (and so dirties) the
+    #     entire column. Two requests writing different keys of the same row are
+    #     last-write-wins on the whole hash — there is no per-key merge on save.
+    #   * nil vs unset: a writer-stored nil (explicit JSON null) reads back as
+    #     nil and does NOT fall back to the default; `reset_<key>` removes the
+    #     key entirely so the reader resolves the default again.
+    #   * :json values are passed through uncast and the reader returns a dup —
+    #     reassign (`record.config = record.config.merge("k" => 1)`), don't
+    #     mutate in place, or the write is silently lost.
+    #   * Read-side casting never raises: corrupt column JSON decodes to {} and
+    #     ungarbageable values cast to nil (ActiveModel semantics). :decimal is
+    #     stored precision-safe as a String (BigDecimal), :date/:datetime as
+    #     ISO8601 strings (datetime in UTC, microsecond precision).
+    #   * Reserved option names: passing key specs as keyword arguments means a
+    #     key literally named `prefix` or `suffix` would be swallowed by the
+    #     affix options — declare those via the positional Hash escape hatch
+    #     (`storable_by :col, { prefix: { type: :string } }`).
+    #   * Reach for the store_attribute or jsonb_accessor gems when you need
+    #     querying into the store, jsonb operators, or store-backed scopes.
+    module Storable
+      extend ActiveSupport::Concern
+
+      LABEL = "ConcernsOnRails::Models::Storable".freeze
+
+      VALID_TYPES = %i[string integer float decimal boolean date datetime json].freeze
+      ALLOWED_SPEC_KEYS = %i[type default in].freeze
+
+      # Reusable ActiveModel casters for the JSON-native types. :decimal,
+      # :date and :datetime round-trip through Strings and are handled
+      # explicitly; :json is passed through uncast.
+      CASTERS = {
+        string: ActiveModel::Type::String.new,
+        integer: ActiveModel::Type::Integer.new,
+        float: ActiveModel::Type::Float.new,
+        boolean: ActiveModel::Type::Boolean.new,
+        date: ActiveModel::Type::Date.new,
+        datetime: ActiveModel::Type::DateTime.new
+      }.freeze
+
+      included do
+        # { column => { key => normalized_spec } }. Subclasses inherit and may
+        # add keys; every write reassigns deep copies so a parent is never
+        # mutated by a child.
+        class_attribute :storable_keys, instance_accessor: false, default: {}
+        # { generated_method_name => [column, key] } — lets a re-declaration of
+        # the same key skip the collision guard while a different key claiming
+        # an already-taken accessor still raises.
+        class_attribute :storable_owned_methods, instance_accessor: false, default: {}
+
+        validate :storable_validate_inclusions
+      end
+
+      module ClassMethods
+        include ConcernsOnRails::Support::ColumnGuard
+
+        # Declare typed accessors over `column`. Key specs may arrive as the
+        # positional `keys` Hash or as trailing keyword arguments (they are
+        # merged); the positional form is the escape hatch for keys literally
+        # named `prefix`/`suffix`. See the module docs.
+        def storable_by(column, keys = {}, prefix: nil, suffix: nil, **kw_keys)
+          column = column.to_sym
+          ensure_columns!(LABEL, column)
+
+          prepared = storable_merge_key_specs(keys, kw_keys).map do |key, raw_spec|
+            key = key.to_sym
+            [key, storable_normalize_spec(key, raw_spec, prefix, suffix)]
+          end
+
+          storable_install_keys(column, prepared)
+        end
+
+        # Lazily decide — once per class/column, at first write when a DB
+        # connection exists — whether the column's attribute type stores a Hash
+        # natively (a :json column, or a host-app `serialize`d column) so we can
+        # hand it the Hash; everything else gets a generated JSON String.
+        def storable_native_hash_column?(column)
+          cache = (@storable_native_hash_cache ||= {})
+          name = column.to_sym
+          return cache[name] if cache.key?(name)
+
+          cache[name] = storable_detect_native_hash(column)
+        end
+
+        private
+
+        def storable_merge_key_specs(keys, kw_keys)
+          raise ArgumentError, "#{LABEL}: keys must be a Hash of name => spec (got #{keys.class})" unless keys.is_a?(Hash)
+
+          keys.merge(kw_keys)
+        end
+
+        def storable_assert_spec_shape!(key, raw_spec)
+          raise ArgumentError, "#{LABEL}: spec for ':#{key}' must be a Hash, got #{raw_spec.class}" unless raw_spec.is_a?(Hash)
+
+          unknown = raw_spec.keys.map(&:to_sym) - ALLOWED_SPEC_KEYS
+          return if unknown.empty?
+
+          raise ArgumentError,
+                "#{LABEL}: unknown option(s) #{unknown.join(', ')} in spec for ':#{key}' (allowed: #{ALLOWED_SPEC_KEYS.join(', ')})"
+        end
+
+        def storable_normalize_spec(key, raw_spec, prefix, suffix)
+          storable_assert_spec_shape!(key, raw_spec)
+
+          type = (raw_spec[:type] || :string).to_sym
+          unless VALID_TYPES.include?(type)
+            raise ArgumentError, "#{LABEL}: unknown type ':#{type}' for ':#{key}' (valid: #{VALID_TYPES.join(', ')})"
+          end
+
+          inclusion = raw_spec[:in]
+          if !inclusion.nil? && !inclusion.respond_to?(:include?)
+            raise ArgumentError, "#{LABEL}: in: for ':#{key}' must be enumerable (respond to #include?)"
+          end
+
+          { type: type, default: raw_spec[:default], in: inclusion,
+            accessor: [prefix, key, suffix].compact.join("_").to_sym }
+        end
+
+        # Guard collisions against a working copy of the owners map (so two keys
+        # in one call claiming the same accessor are caught too), then commit
+        # the merged config and define the accessors.
+        def storable_install_keys(column, prepared)
+          owners = storable_owned_methods.dup
+          prepared.each { |key, spec| storable_guard_collisions!(column, key, spec, owners) }
+
+          merged = storable_keys.dup
+          column_keys = (merged[column] || {}).dup
+          prepared.each { |key, spec| column_keys[key] = spec }
+          merged[column] = column_keys
+          self.storable_keys = merged
+          self.storable_owned_methods = owners
+
+          prepared.each { |key, spec| storable_define_key_methods(column, key, spec) }
+        end
+
+        def storable_guard_collisions!(column, key, spec, owners)
+          storable_method_names(spec[:accessor], spec[:type]).each do |method_name|
+            owner = owners[method_name]
+            if owner
+              next if owner == [column, key] # our own re-declaration — merge, don't collide
+
+              raise storable_collision_error(method_name)
+            end
+            raise storable_collision_error(method_name) if storable_method_taken?(method_name, spec[:accessor])
+
+            owners[method_name] = [column, key]
+          end
+        end
+
+        # The reader is intentionally listed first so a column-attribute clash
+        # reports the bare accessor name.
+        def storable_method_names(accessor, type)
+          base = accessor.to_s
+          names = [base, "#{base}=", "#{base}_changed?", "#{base}_was", "reset_#{base}"]
+          names << "#{base}?" if type == :boolean
+          names.map(&:to_sym)
+        end
+
+        # A name is taken when it shadows a column's (lazily defined) attribute
+        # accessors or any already-defined instance method.
+        def storable_method_taken?(method_name, accessor)
+          return true if column_names.include?(accessor.to_s)
+
+          method_defined?(method_name) || private_method_defined?(method_name)
+        end
+
+        def storable_collision_error(method_name)
+          ArgumentError.new(
+            "#{LABEL}: generated method '#{method_name}' collides with an existing method or column; " \
+            "pass prefix: or suffix: to rename the accessors"
+          )
+        end
+
+        # Methods look the spec up at call time (not via closure) so a later
+        # merge that changes a key's type/default takes effect without redefining.
+        def storable_define_key_methods(column, key, spec)
+          base = spec[:accessor].to_s
+
+          define_method(base) { storable_get(column, key) }
+          define_method("#{base}=") { |value| storable_set(column, key, value) }
+          define_method("#{base}_changed?") { storable_key_changed?(column, key) }
+          define_method("#{base}_was") { storable_key_was(column, key) }
+          define_method("reset_#{base}") { storable_reset(column, key) }
+          define_method("#{base}?") { storable_get(column, key) == true } if spec[:type] == :boolean
+        end
+
+        def storable_detect_native_hash(column)
+          name = column.to_s
+          type = type_for_attribute(name)
+          return true if defined?(ActiveRecord::Type::Serialized) && type.is_a?(ActiveRecord::Type::Serialized)
+
+          col = columns_hash[name]
+          !col.nil? && col.type == :json
+        rescue StandardError
+          false
+        end
+      end
+
+      # ---- readers / writers (the generated accessors delegate here) ----
+
+      private
+
+      def storable_get(column, key)
+        spec = storable_spec(column, key)
+        storable_resolve(spec, storable_decode(self[column]), key)
+      end
+
+      def storable_set(column, key, value)
+        spec = storable_spec(column, key)
+        hash = storable_decode(self[column]).dup
+        hash[key.to_s] = storable_cast_write(spec[:type], value)
+        storable_assign(column, hash)
+      end
+
+      # Per-key dirty: decode the column's own _was value and compare the cast
+      # per-key values. After a save (dirty reset) _was equals the current value,
+      # so the key reads as unchanged.
+      def storable_key_changed?(column, key)
+        storable_key_was(column, key) != storable_get(column, key)
+      end
+
+      def storable_key_was(column, key)
+        spec = storable_spec(column, key)
+        storable_resolve(spec, storable_decode(attribute_was(column.to_s)), key)
+      end
+
+      # In-memory only (no save) — hence no bang. Removing the key lets the
+      # reader fall back to the default again.
+      def storable_reset(column, key)
+        hash = storable_decode(self[column])
+        return unless hash.key?(key.to_s)
+
+        new_hash = hash.dup
+        new_hash.delete(key.to_s)
+        storable_assign(column, new_hash)
+      end
+
+      def storable_spec(column, key)
+        self.class.storable_keys.fetch(column).fetch(key)
+      end
+
+      # absent -> default; present-but-nil -> nil (never the default); present ->
+      # cast through the declared type.
+      def storable_resolve(spec, hash, key)
+        skey = key.to_s
+        return storable_default(spec) unless hash.key?(skey)
+
+        raw = hash[skey]
+        return nil if raw.nil?
+
+        storable_cast_read(spec[:type], raw)
+      end
+
+      # A Proc default is instance_exec'd per call; a mutable Hash/Array default
+      # is deep-duped per call so one instance's mutation never leaks into another.
+      def storable_default(spec)
+        default = spec[:default]
+        return instance_exec(&default) if default.is_a?(Proc)
+
+        case default
+        when Hash, Array then default.deep_dup
+        else default
+        end
+      end
+
+      # ---- storage codec ----
+
+      # A native-json Hash is used as-is; a String is parsed tolerantly; anything
+      # else (nil, an array, a stray scalar) decodes to {}.
+      def storable_decode(raw)
+        case raw
+        when Hash then raw
+        when String then storable_parse(raw)
+        else {}
+        end
+      end
+
+      def storable_parse(string)
+        return {} if string.strip.empty?
+
+        parsed = JSON.parse(string)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      # Reassigning the whole attribute is what marks the column dirty. Hand a
+      # Hash to native/serialized columns; otherwise generate the JSON String.
+      def storable_assign(column, hash)
+        self[column] = if self.class.storable_native_hash_column?(column)
+                         hash
+                       else
+                         JSON.generate(hash)
+                       end
+      end
+
+      # ---- casting ----
+
+      def storable_cast_read(type, raw)
+        case type
+        when :json     then raw.deep_dup
+        when :decimal  then storable_read_decimal(raw)
+        when :date     then CASTERS[:date].cast(raw)
+        when :datetime then storable_read_time(raw)
+        else CASTERS[type].cast(raw)
+        end
+      rescue StandardError
+        # ActiveModel casting tolerates garbage already; BigDecimal()/Time.iso8601
+        # do not, so swallow and follow the "cast to nil" convention.
+        nil
+      end
+
+      def storable_read_decimal(raw)
+        return raw if raw.is_a?(BigDecimal)
+
+        BigDecimal(raw.to_s)
+      end
+
+      def storable_read_time(raw)
+        return raw if raw.is_a?(Time)
+
+        Time.iso8601(raw.to_s)
+      end
+
+      def storable_cast_write(type, value)
+        case type
+        when :json     then value
+        when :decimal  then storable_write_decimal(value)
+        when :date     then storable_write_date(value)
+        when :datetime then storable_write_datetime(value)
+        else CASTERS[type].cast(value)
+        end
+      end
+
+      # Precision-safe String (the Auditable precedent): BigDecimal#to_s("F").
+      def storable_write_decimal(value)
+        return nil if value.nil?
+
+        big = value.is_a?(BigDecimal) ? value : BigDecimal(value.to_s)
+        big.to_s("F")
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def storable_write_date(value)
+        CASTERS[:date].cast(value)&.iso8601
+      end
+
+      # UTC iso8601(6): microsecond precision, the lesson CursorPaginatable learned.
+      def storable_write_datetime(value)
+        storable_coerce_time(value)&.utc&.iso8601(6)
+      end
+
+      # A bare Date becomes midnight UTC (deterministic — Date#to_time would
+      # anchor to the host's zone).
+      def storable_coerce_time(value)
+        case value
+        when nil then nil
+        when ActiveSupport::TimeWithZone, Time then value
+        when DateTime then value.to_time
+        when Date then Time.utc(value.year, value.month, value.day)
+        else CASTERS[:datetime].cast(value)
+        end
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # ---- validation ----
+
+      # One pass adds an inclusion error per `in:`-constrained key whose stored
+      # value is present and non-nil but casts outside the allowed set. Absent
+      # and nil values pass (compose with a presence validator if you need them).
+      def storable_validate_inclusions
+        self.class.storable_keys.each do |column, keys|
+          decoded = storable_decode(self[column])
+          keys.each do |key, spec|
+            allowed = spec[:in]
+            next unless allowed
+
+            skey = key.to_s
+            next unless decoded.key?(skey)
+
+            raw = decoded[skey]
+            next if raw.nil?
+
+            value = storable_cast_read(spec[:type], raw)
+            errors.add(spec[:accessor], "is not included in the list") unless allowed.include?(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.18.0".freeze
+  VERSION = "1.19.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -50,6 +50,7 @@ require "concerns_on_rails/models/monetizable"
 require "concerns_on_rails/models/auditable"
 require "concerns_on_rails/models/lockable"
 require "concerns_on_rails/models/aliasable"
+require "concerns_on_rails/models/storable"
 
 # Controller concerns
 require "concerns_on_rails/controllers/paginatable"
@@ -66,6 +67,7 @@ require "concerns_on_rails/controllers/timezoneable"
 require "concerns_on_rails/controllers/idempotentable"
 require "concerns_on_rails/controllers/webhook_verifiable"
 require "concerns_on_rails/controllers/cursor_paginatable"
+require "concerns_on_rails/controllers/deprecatable"
 
 # Backwards compatibility (top-level aliases for pre-1.6 module paths)
 require "concerns_on_rails/legacy_aliases"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.18.0
+  version: 1.19.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-12 00:00:00.000000000 Z
+date: 2026-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -72,6 +72,7 @@ files:
 - lib/concerns_on_rails.rb
 - lib/concerns_on_rails/controllers/authorizable.rb
 - lib/concerns_on_rails/controllers/cursor_paginatable.rb
+- lib/concerns_on_rails/controllers/deprecatable.rb
 - lib/concerns_on_rails/controllers/error_handleable.rb
 - lib/concerns_on_rails/controllers/filterable.rb
 - lib/concerns_on_rails/controllers/idempotentable.rb
@@ -104,6 +105,7 @@ files:
 - lib/concerns_on_rails/models/soft_deletable.rb
 - lib/concerns_on_rails/models/sortable.rb
 - lib/concerns_on_rails/models/stateable.rb
+- lib/concerns_on_rails/models/storable.rb
 - lib/concerns_on_rails/models/taggable.rb
 - lib/concerns_on_rails/models/tokenizable.rb
 - lib/concerns_on_rails/support/address_data.rb