recorder 1.2.3 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 807b7bea0674cab9a3a39b1fa03f78a62f0313650bb7adf51860a98257273186
-  data.tar.gz: 175315c3c23acef56bd6f9545681b7525eb41a11cadacf5e671dd197352f31d2
+  metadata.gz: 064c2afab28615f3f268bfacee354fdf6fceff7063190e084783dfe1640fe054
+  data.tar.gz: 6062f268b4a47ea089cf90fac14ac124fc2c5e07f65be6d37228a663ec4cfc5e
 SHA512:
-  metadata.gz: 8eb1a672f08d66c265f6d1b1dffd8d65703b4359f789febb42846f4bb0d89d860c49ffb383b78bd57f3bfefeb349fac6abd7ed8ecc890a22ffc45886087c91b7
-  data.tar.gz: b65ed4fc4d7fea8a5d442f301789e497d538fa57447a320328f89650e9c65f8773d7247c68e303d49cdbda5977786fb64a8841c1cb5ba65a1aaa638ce9f63a3c
+  metadata.gz: ed30006c3d6f960d017a8b97853d5737624c9690f31ffc60ee3d0dc2dbbb21507f3e52e8203dd103192ba8648ca6dc643e969a232fd40a7ee65d0dcc7f11a87b
+  data.tar.gz: 689acc4c8867035e627413e5586280e2b05327efa7a002713903300016f19a99caa1194e172de45633f6b4fb8771cdf3a380905784f327b3df01bca39ed93129

data/CHANGELOG.md

@@ -0,0 +1,146 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.4.0]
+
+### Added
+
+- README coverage of what a revision's `data` holds: the complete attribute
+  snapshot on every event, when `changes` and `associations` are present, and
+  which events record a revision at all. No behaviour changes — the snapshot is
+  what the gem has always written, and it is now written down.
+- A known issue for the `changes` key on `destroy` revisions, which describes
+  the record's last update rather than the deletion.
+- A `changes:` option on `recorder` that merges extra entries into a revision's
+  `changes`. It takes a Proc evaluated on the record or the name of a method on it;
+  both receive the event.
+
+### Changed
+
+- `Recorder::Revision` declares both `belongs_to :user` and `belongs_to :item`
+  with `optional: true`. The associations have always been optional in practice,
+  but only because the gem is required before the Active Record railtie applies
+  `belongs_to_required_by_default`, so the reflections are built while the
+  default is still off. Had that ordering ever shifted, every revision without a
+  user would have failed validation, and so would every `destroy` revision,
+  which is written after its item's row is deleted. `Tape::Record#record` calls
+  `create`, not `create!`, so those revisions would have been dropped with
+  nothing raised anywhere. Recorded revisions are unchanged.
+
+### Fixed
+
+- `Recorder::Changeset#previous` and `#next` no longer raise `NoMethodError` when
+  the changes carry a key that is not an attribute of the model, and skip values
+  that are not a two-element `[old, new]` pair rather than indexing into them.
+
+## [1.3.0] - 2026-09-16
+
+### Added
+
+- Support for Rails 7.0, 7.1, 7.2, 8.0, and 8.1. Rails 6.1 remains supported.
+- Support for Ruby 3.3 and 3.4. Ruby 3.0 remains the minimum.
+- Declared and tested the supported Ruby versions (#10).
+- The specs and RuboCop now run in GitHub Actions (#9).
+- Releases are published to RubyGems.org from GitHub Actions when a version tag
+  is pushed (#22).
+- Gem metadata: `source_code_uri`, `changelog_uri`, `bug_tracker_uri`, and
+  `rubygems_mfa_required`.
+- README coverage of the public API: configuration, `Recorder.meta=`,
+  `recorder_disabled!`, and the association tracking options (#20).
+
+### Changed
+
+- `activerecord` and `activesupport` requirements widen from `~> 6.1` to
+  `>= 6.1, < 9`, and the `< 3.4` Ruby ceiling is removed. Rails 6.1 and 7.0
+  cannot run on Ruby 3.4; every other combination is exercised in CI.
+- The released gem now ships only `lib/`, the README, the LICENSE, and this
+  changelog. Previous releases also carried repository scaffolding — CI
+  configuration, `Rakefile`, `bin/`, and dotfiles — that a host app never loads.
+- `recorder_revisions.item_id` and `recorder_revisions.user_id` are now
+  `bigint`. Rails has defaulted primary keys to `bigint` since 5.1, so the
+  `integer` columns could not hold a key from any table this gem audits once it
+  passed 2,147,483,647. No release since Rails 5.0 shipped a migration that could
+  run; installs from the 0.1.x line on Rails 4 have the narrow columns and are
+  unaffected, because the gem ships no migration that alters an existing table
+  (#18).
+
+### Removed
+
+- `pg` is no longer a runtime dependency. Revisions still require PostgreSQL
+  column types, but the adapter is the host application's to declare, so the
+  gem no longer forces `pg` into its bundle.
+- The `--with_partitions` generator option. It dispatched to a template that was
+  never added to the gem, so the run wrote the first migration and then aborted,
+  leaving a partial install. It never completed once (#18).
+- The `--with_number_column` generator option. The `number` column it added was
+  never read by the gem, and the migration it generated could not run on any
+  Rails this gem supports, so there is no working installed base. Anyone who has
+  the column keeps it — the counter lives in a trigger in their own schema,
+  which this does not touch, and the gem never writes the column. Optional
+  cleanup, including a working `DROP TRIGGER`, is in #14 — the `down` the gem
+  originally shipped is a syntax error and cannot roll it back (#14).
+
+### Fixed
+
+- Asynchronous recording no longer enqueues job arguments Sidekiq rejects. The
+  `meta` hash supplied through `Recorder.meta=` reached the worker with its
+  original keys and values, and Sidekiq raises on arguments that are not JSON
+  native from 7.0 onwards. Because the raise happened inside an `after_create`,
+  it rolled back the host application's own write. The enqueued payload is now
+  normalised to JSON natives in full (#19).
+- `rails generate recorder:install` now produces migrations that run. The
+  templates subclassed a bare `ActiveRecord::Migration`, which Rails has
+  rejected since 5.0, so `rails db:migrate` raised on the only documented way to
+  install the gem. The version is templated from the host app's Rails (#18).
+- `Recorder.version` returns the version instead of raising `TypeError`. It
+  scoped into `VERSION::STRING`, but `VERSION` is a `String` (#17).
+- `recorder_disabled!` re-enables recording when the block raises. The re-enable
+  was skipped on the exception path, so recording stayed off for the rest of the
+  request or job and every later save went silently unaudited (#17).
+- Made the spec suite runnable and trustworthy again (#8).
+
+## [1.2.3] - 2023-04-25
+
+### Fixed
+
+- A revision is created when an item's associations change.
+- No revision is created for an `:update` event when nothing changed.
+
+## [1.2.2] - 2022-11-17
+
+### Fixed
+
+- Refactoring for full Rails 6 compatibility.
+
+## [1.2.1] - 2022-11-16
+
+### Fixed
+
+- Fixed parsing of empty associations.
+
+## [1.2.0] - 2022-11-15
+
+### Added
+
+- Rails 6 support.
+
+## [1.1.1] - 2021-09-13
+
+Releases at and before 1.1.1 predate this changelog. See the
+[commit history](https://github.com/jetrockets/recorder/commits/master) for
+details.
+
+[Unreleased]: https://github.com/jetrockets/recorder/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/jetrockets/recorder/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/jetrockets/recorder/compare/v1.2.3...v1.3.0
+[1.2.3]: https://github.com/jetrockets/recorder/compare/v1.2.2...v1.2.3
+[1.2.2]: https://github.com/jetrockets/recorder/compare/v1.2.1...v1.2.2
+[1.2.1]: https://github.com/jetrockets/recorder/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/jetrockets/recorder/compare/v1.1.1...v1.2.0
+[1.1.1]: https://github.com/jetrockets/recorder/releases/tag/v1.1.1

data/README.md

@@ -1,6 +1,29 @@
 # Recorder
 
-Recorder tracks changes of your Rails models
+[![CI](https://github.com/jetrockets/recorder/actions/workflows/ci.yml/badge.svg)](https://github.com/jetrockets/recorder/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/recorder)](https://rubygems.org/gems/recorder)
+
+Recorder tracks changes of your Rails models. Each create, update, and destroy on
+an observed model writes a `recorder_revisions` row holding an attribute snapshot,
+the changes, and — when the controller concern is included — the user and IP
+behind the request.
+
+## Requirements
+
+- PostgreSQL — revisions are stored in `jsonb` and `inet` columns
+- Ruby and Rails per the table below
+
+| Rails | Supported Ruby |
+|-------|----------------|
+| 6.1   | 3.0 – 3.3      |
+| 7.0   | 3.0 – 3.3      |
+| 7.1   | 3.0 – 3.4      |
+| 7.2   | 3.1 – 3.4      |
+| 8.0   | 3.2 – 3.4      |
+| 8.1   | 3.2 – 3.4      |
+
+Rails 6.1 and 7.0 cannot run on Ruby 3.4 — they require `mutex_m`, which left the
+default gems in that release. Every combination in the table is exercised in CI.
 
 ## Installation
 
@@ -14,15 +37,25 @@ And then execute:
 
     $ bundle
 
-Or install it yourself as:
+Generate the migration for the `recorder_revisions` table:
+
+    $ rails generate recorder:install
+
+The generator writes the migration but does not run it. Run it yourself:
+
+    $ rails db:migrate
+
+The generator accepts one option:
 
-    $ gem install recorder
+- `--with_index_by_user_id` — adds an index on `user_id`.
 
 ## Usage
 
-To enable logging on a model you just need to include `Recorder::Observer` into the model and configure logging options for it:
+### Observing a model
 
-``` ruby
+Include `Recorder::Observer` into the model and configure logging options for it:
+
+```ruby
 class Post < ActiveRecord::Base
   include ::Recorder::Observer
 
@@ -40,8 +73,55 @@ Recorder supports the following options:
  * `only: [array]` - only these attributes are logged, other attributes are ingored;
  * `associations: {hash} (hash)` - allows to set what associations will be logged alongside with the model. For each association you can also set ignore and only options;
  * `async: bool` - a logging strategy (true - asynchronous, false - synchronous).
+ * `changes: Proc | Symbol` - extra entries to merge into a revision's `changes`. A Proc
+   is evaluated on the record, a Symbol names a method on it; both receive the event
+   (`:create`, `:update` or `:destroy`) and return a hash of `name => [old, new]`, or
+   `nil` for nothing. Anything else raises `ArgumentError` where `recorder` is called.
+
+The entries are merged after `only:` and `ignore:` have been applied, so those
+filters never drop them, and a key that matches an attribute replaces that
+attribute's entry. An update that reports only custom entries still records a
+revision.
+
+Inside the callback, read `saved_changes` and `saved_change_to_<attribute>?`, not
+`<attribute>_changed?`: the callback runs from `after_create`/`after_update`, where
+the dirty state has already been reset.
 
-There are two strategies for logging: synchronous and asynchronous. When the synchronous strategy is used, a revision record is saved immediately after a model is saved, and the async strategy moves creating of revision records to [Sidekiq](https://github.com/mperham/sidekiq).
+`Recorder::Changeset` rebuilds the previous and next versions by assigning each
+change onto a copy of the record, and skips what it cannot assign: a key that is
+not an attribute, and any value that is not a two-element `[old, new]` pair. To display such
+a key, define `previous_<key>`/`next_<key>` on the model's changeset class, and
+pick a name that `Recorder::Changeset` does not already answer to.
+
+These per-model options, `changes:` included, do not reach the recorder yet — see [Known issues](#known-issues).
+Until they do, every observed model records a full attribute snapshot, filtered
+only by the global `Recorder.config.ignore`. Options declared as an instance
+method are read, so that is the way to opt into any of them today:
+
+```ruby
+def recorder_options
+  {ignore: %i[identifier], changes: :extra_changes}
+end
+```
+
+### Global configuration
+
+```ruby
+Recorder.config do |config|
+  config.ignore = %i[created_at updated_at]
+  config.async = false
+  config.sidekiq_options = {queue: 'recorder', retry: 10, backtrace: true}
+end
+```
+
+`ignore` defaults to `[]`, `async` to `false`, and `sidekiq_options` to the hash
+shown above.
+
+There are two strategies for logging: synchronous and asynchronous. When the synchronous strategy is used, a revision record is saved immediately after a model is saved, and the async strategy moves creating of revision records to [Sidekiq](https://github.com/sidekiq/sidekiq). Under the async
+strategy the revision is enqueued to `Recorder::Sidekiq::RevisionsWorker` two
+seconds out; the worker is loaded by the railtie when `Sidekiq` is defined.
+
+### Recording the current user
 
 To enable storing of such data as user_id and ip, you need to include `Recorder::Rails::ControllerConcern` to `ApplicationController`. Recorder uses [request_store](https://github.com/steveklabnik/request_store) to safely store these data on a thread level.
 
@@ -52,11 +132,142 @@ To enable storing of such data as user_id and ip, you need to include `Recorder:
   end
 ```
 
+The concern reads `current_user`; override `recorder_user_id` to name a different
+method. Override `recorder_meta` to store a hash alongside every revision. A
+revision without a user is valid — `user_id` stays `nil`.
+
+### Turning recording off
+
+`Recorder::Manager` suspends recording for the current request or thread:
+
+```ruby
+class Importer
+  include Recorder::Manager
+
+  def call
+    recorder_disabled! do
+      # nothing recorded in here
+    end
+  end
+end
+```
+
+The block form re-enables recording on the way out, including when the block
+raises. Called without a block, `recorder_disabled!` stays in effect until
+`recorder_enabled!`.
+
+### Reading revisions
+
+Observed models get a `revisions` association:
+
+```ruby
+revision = post.revisions.ordered_by_created_at.first
+
+revision.event        # "update"
+revision.data         # {"attributes" => {...}, "changes" => {...}, "associations" => {...}}
+revision.user_id
+revision.action_date
+```
+
+`data` carries a complete attribute snapshot on every event, not only what
+changed:
+
+- `attributes` — every attribute of the record as it stood when the callback
+  ran, filtered by the model's `only:` or `ignore:` and, failing those, by
+  `Recorder.config.ignore`. Always present.
+- `changes` — the same filter applied to `saved_changes`, as
+  `name => [old, new]`, plus any entries from `changes:`. Omitted when that
+  leaves nothing.
+- `associations` — those two keys again, one entry per association named in
+  `associations:`. Omitted when no association reports anything.
+
+The snapshot is the contract, not an accident of the implementation: a revision
+is self-contained, so reconstructing a record at a point in time does not mean
+replaying every prior diff. It is also what keeps a `destroy` revision useful,
+since the row it describes is gone.
+
+An `update` records a revision only when the record or one of its recorded
+associations reports a change; `create` and `destroy` always record one.
+
+`#item_changeset` wraps `data['changes']` in a `Recorder::Changeset`, which reads
+the values back as the model's own types:
+
+```ruby
+changeset = revision.item_changeset
+
+changeset.keys                        # attributes that changed
+changeset.previous(:title)            # value before the change
+changeset.next(:title)                # value after it
+changeset.human_attribute_name(:title)
+changeset.previous_version            # a copy of the record with the old values
+```
+
+Changed associations are reachable the same way:
+
+```ruby
+revision.changed_associations         # ["author"]
+revision.association_changeset('author')
+```
+
+To render a changeset yourself, define `PostChangeset` — the class is looked up
+as `"#{model}Changeset"` — or point at another one with a
+`recorder_changeset_class` class method on the model. Otherwise
+`Recorder::Changeset` is used.
+
+## Known issues
+
+The gem is under active maintenance and these defects are known as of 1.3.0:
+
+- The per-model options above (`ignore:`, `only:`, `associations:`, `async:`)
+  are not applied. `Recorder::Tape` asks the record instance for
+  `recorder_options`, but `Recorder::Observer` defines that method on the class,
+  so the lookup always falls back to `{}` — every observed model records a full
+  attribute snapshot, synchronously. Global configuration is unaffected.
+- `Recorder.enabled=` does not switch recording off. It writes to
+  `Recorder.config`, which nothing on the recording path reads — the gates are in
+  `Recorder.store`, which `Recorder::Manager` drives.
+- Collection associations are never recorded. `associations:` handles only
+  singular associations; a `has_many` reflection is skipped without a warning.
+- A `destroy` revision carries a `changes` key describing the record's last
+  *update*. `destroy` does not clear `saved_changes`, and `data` is built the
+  same way for every event. The `attributes` snapshot is the accurate record of
+  what was deleted.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+The specs need a PostgreSQL server. Connection settings are read from the
+environment — `RECORDER_DB_HOST`, `RECORDER_DB_PORT`, `RECORDER_DB_USERNAME`,
+`RECORDER_DB_PASSWORD`, `RECORDER_DB_NAME` — and default to `postgres:postgres`
+on `localhost:5432` against a `recorder_test` database, which must already exist.
+
+`rake spec` runs against whichever Rails version the root `Gemfile` resolves to.
+To run against a specific one, use the appraisal gemfiles:
+
+```bash
+bundle exec appraisal install            # once, to generate gemfiles/
+bundle exec appraisal rails-7.2 rake spec
+```
+
+CI runs the suite across the whole Ruby × Rails matrix above, plus `bundle exec
+rubocop`. Both must pass before a pull request merges.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version, bump `Recorder::VERSION` and move the `[Unreleased]`
+changelog entries under it in a pull request. Once that merges, tag the merge
+commit and push the tag:
+
+```bash
+git fetch origin
+git tag vX.Y.Z origin/master
+git push origin vX.Y.Z
+```
+
+The Release workflow then runs CI against the tagged commit, checks the tag
+matches `Recorder::VERSION`, publishes the gem to [rubygems.org](https://rubygems.org)
+through trusted publishing, and creates the GitHub release from the changelog.
 
 ## Contributing
 
@@ -64,11 +275,10 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/jetroc
 
 ## Credits
 
-![JetRockets](https://media.jetrockets.pro/jetrockets-white.png)
+![JetRockets](https://media.jetrockets.com/jetrockets-white.png)
 
-Recorder is maintained by [JetRockets](https://www.jetrockets.pro]).
+Recorder is maintained by [JetRockets](https://www.jetrockets.com).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/lib/generators/recorder/install_generator.rb

@@ -10,20 +10,6 @@ module Recorder
 
     source_root File.expand_path('templates', __dir__)
 
-    class_option(
-      :with_partitions,
-      type: :boolean,
-      default: false,
-      desc: 'Create partitions to `recorder_revisions` table'
-    )
-
-    class_option(
-      :with_number_column,
-      type: :boolean,
-      default: false,
-      desc: 'Add `number` column to `recorder_revisions` table'
-    )
-
     class_option(
       :with_index_by_user_id,
       type: :boolean,
@@ -35,9 +21,7 @@ module Recorder
 
     def create_migration_file
       add_or_skip_recorder_migration('create_recorder_revisions')
-      add_or_skip_recorder_migration('add_number_column_to_recorder_revisions') if options.with_number_column?
       add_or_skip_recorder_migration('add_index_by_user_id_to_recorder_revisions') if options.with_index_by_user_id?
-      add_or_skip_recorder_migration('add_partitions_to_recorder_revisions') if options.with_partitions?
     end
 
     def self.next_migration_number(dirname)
@@ -47,11 +31,11 @@ module Recorder
     protected
 
     def add_or_skip_recorder_migration(template)
-      migration_dir = File.expand_path('db/migrate')
+      migration_dir = File.expand_path('db/migrate', destination_root)
       if self.class.migration_exists?(migration_dir, template)
         ::Kernel.warn "Migration already exists: #{template}"
       else
-        migration_template "#{template}.rb", "db/migrate/#{template}.rb"
+        migration_template "#{template}.rb.tt", "db/migrate/#{template}.rb"
       end
     end
   end

data/lib/generators/recorder/templates/{add_index_by_user_id_to_recorder_revisions.rb → add_index_by_user_id_to_recorder_revisions.rb.tt}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# This migration adds number column to the `revisions` table.
-class AddIndexByUserIdToRecorderRevisions < ActiveRecord::Migration
+# This migration adds an index by `user_id` to the `recorder_revisions` table.
+class AddIndexByUserIdToRecorderRevisions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     add_index :recorder_revisions, :user_id
   end

data/lib/generators/recorder/templates/{create_recorder_revisions.rb → create_recorder_revisions.rb.tt}

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
 # This migration creates the `recorder_revisions` table.
-class CreateRecorderRevisions < ActiveRecord::Migration
+class CreateRecorderRevisions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     create_table :recorder_revisions do |t|
       t.string :item_type, null: false
-      t.integer :item_id
+      t.bigint :item_id
       t.string :event, null: false
       t.jsonb :data, null: false
       t.inet :ip
       t.date :action_date, null: false
-      t.integer :user_id
+      t.bigint :user_id
       t.jsonb :meta
       t.datetime :created_at, null: false
     end

data/lib/recorder/changeset.rb

@@ -33,7 +33,7 @@ module Recorder
       @previous_version = item.dup
 
       changes.each do |key, change|
-        @previous_version.send("#{key}=", change[0])
+        @previous_version.try("#{key}=", change[0]) if pair?(change)
       end
 
       @previous_version
@@ -49,10 +49,16 @@ module Recorder
       @next_version = item.dup
 
       changes.each do |key, change|
-        @next_version.send("#{key}=", change[1])
+        @next_version.try("#{key}=", change[1]) if pair?(change)
       end
 
       @next_version
     end
+
+    private
+
+    def pair?(change)
+      change.is_a?(Array) && change.size == 2
+    end
   end
 end

data/lib/recorder/manager.rb

@@ -4,9 +4,11 @@ module Recorder
   module Manager
     def recorder_disabled!
       Recorder.store.recorder_disabled!
+      return unless block_given?
 
-      if block_given?
+      begin
         yield
+      ensure
         Recorder.store.recorder_enabled!
       end
     end

data/lib/recorder/observer.rb

@@ -27,6 +27,8 @@ module Recorder
       end
 
       def recorder(options = {})
+        Recorder::Tape::Data.validate_changes_option!(options[:changes])
+
         @recorder_options = options
 
         after_create do

data/lib/recorder/revision.rb

@@ -18,8 +18,8 @@ module Recorder
       )
     end
 
-    belongs_to :item, polymorphic: true, inverse_of: :revisions
-    belongs_to :user
+    belongs_to :item, polymorphic: true, inverse_of: :revisions, optional: true
+    belongs_to :user, optional: true
 
     validates :item_type, presence: true
     validates :event, presence: true

data/lib/recorder/tape/data.rb

@@ -23,8 +23,14 @@ module Recorder
         {attributes: sanitize_attributes(item.attributes, options)}
       end
 
+      def self.validate_changes_option!(callback)
+        return if callback.nil? || callback.is_a?(Proc) || callback.is_a?(Symbol) || callback.is_a?(String)
+
+        raise ArgumentError, "`changes:` expects a Proc or a method name, got #{callback.inspect}"
+      end
+
       def changes_for(event, options)
-        changes = sanitize_attributes(item.saved_changes, options)
+        changes = sanitize_attributes(item.saved_changes, options).merge(custom_changes_for(event, options))
 
         changes.present? ? {changes: changes} : {}
       end
@@ -37,6 +43,17 @@ module Recorder
 
       private
 
+      def custom_changes_for(event, options)
+        callback = options[:changes]
+        return {} unless callback
+
+        self.class.validate_changes_option!(callback)
+
+        changes = callback.is_a?(Proc) ? item.instance_exec(event, &callback) : item.send(callback, event)
+
+        changes ? Hash(changes).symbolize_keys : {}
+      end
+
       def sanitize_attributes(attributes, options)
         if options[:only].present?
           only = wrap_options(options[:only])

data/lib/recorder/tape/record.rb

@@ -28,13 +28,15 @@ module Recorder
         options[:async].nil? ? Recorder.config.async : options[:async]
       end
 
+      # Sidekiq accepts only JSON-native job arguments. `data` is serialised
+      # ahead of the round trip so it survives as a string for the worker to
+      # parse back; everything else is normalised by the round trip itself.
       def record_async(params, options)
         params[:data] = params[:data].to_json
-        params[:action_date] = params[:action_date].to_s
 
         Recorder::Sidekiq::RevisionsWorker.perform_in(
           options[:delay] || 2.seconds,
-          params.stringify_keys
+          JSON.parse(params.to_json)
         )
       end
     end

data/lib/recorder/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Recorder
-  VERSION = '1.2.3'
+  VERSION = '1.4.0'
 end

data/lib/recorder.rb

@@ -60,7 +60,7 @@ module Recorder
 
     # Returns version of Recorder as +String+
     def version
-      VERSION::STRING
+      VERSION
     end
   end
 end

metadata

@@ -1,71 +1,83 @@
 --- !ruby/object:Gem::Specification
 name: recorder
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.4.0
 platform: ruby
 authors:
 - Igor Alexandrov
 autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2023-04-25 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 - !ruby/object:Gem::Dependency
-  name: pg
+  name: request_store
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: request_store
+  name: appraisal
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
+        version: '2.5'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.5'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -84,16 +96,16 @@ dependencies:
   name: generator_spec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: jetrockets-standard
   requirement: !ruby/object:Gem::Requirement
@@ -109,47 +121,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: rspec-rails
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
-  name: rails-dummy
+  name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '5.0'
 description: Recorder tracks changes of your Rails models
 email:
 - igor.alexandrov@jetrockets.com
@@ -157,21 +169,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".rspec"
-- ".rubocop.yml"
-- ".travis.yml"
-- Gemfile
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
-- bin/console
-- bin/setup
 - lib/generators/recorder/USAGE
 - lib/generators/recorder/install_generator.rb
-- lib/generators/recorder/templates/add_index_by_user_id_to_recorder_revisions.rb
-- lib/generators/recorder/templates/add_number_column_to_recorder_revisions.rb
-- lib/generators/recorder/templates/create_recorder_revisions.rb
+- lib/generators/recorder/templates/add_index_by_user_id_to_recorder_revisions.rb.tt
+- lib/generators/recorder/templates/create_recorder_revisions.rb.tt
 - lib/recorder.rb
 - lib/recorder/changeset.rb
 - lib/recorder/config.rb
@@ -186,11 +190,14 @@ files:
 - lib/recorder/tape/data.rb
 - lib/recorder/tape/record.rb
 - lib/recorder/version.rb
-- recorder.gemspec
 homepage: https://github.com/jetrockets/recorder
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/jetrockets/recorder
+  changelog_uri: https://github.com/jetrockets/recorder/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/jetrockets/recorder/issues
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -199,14 +206,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Rails model auditor

data/.gitignore

@@ -1,16 +0,0 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-
-/spec/dummy/config/database.yml
-/spec/dummy/log/*
-
-# Ignore vim swap files
-*.swp
-*.swo

data/.rspec

@@ -1,2 +0,0 @@
---format documentation
---color

data/.rubocop.yml

@@ -1,27 +0,0 @@
-inherit_gem:
-  jetrockets-standard: config/gems.yml
-
-AllCops:
-  Exclude:
-    - 'bin/*'
-    - 'tmp/**/*'
-    - 'docs/**/*'
-    - 'Gemfile'
-    - 'vendor/**/*'
-    - 'gemfiles/**/*'
-  DisplayCopNames: true
-  TargetRubyVersion: 2.5
-
-Style/TrailingCommaInArrayLiteral:
-  EnforcedStyleForMultiline: no_comma
-
-Style/TrailingCommaInHashLiteral:
-  EnforcedStyleForMultiline: no_comma
-
-Layout/ParameterAlignment:
-  EnforcedStyle: with_first_parameter
-
-# See https://github.com/rubocop-hq/rubocop/issues/4222
-Lint/AmbiguousBlockAssociation:
-  Exclude:
-    - 'spec/**/*'

data/.travis.yml

@@ -1,4 +0,0 @@
-language: ruby
-rvm:
-  - 2.2.4
-before_install: gem install bundler -v 1.11.2

data/Gemfile

@@ -1,6 +0,0 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-
-# Specify your gem's dependencies in recorder.gemspec
-gemspec

data/Rakefile

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'rails/dummy/tasks'
-
-RSpec::Core::RakeTask.new(:spec)
-
-task default: :spec

data/bin/console

@@ -1,15 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require 'bundler/setup'
-require 'recorder'
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require 'irb'
-IRB.start

data/bin/setup

@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here

data/lib/generators/recorder/templates/add_number_column_to_recorder_revisions.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-# This migration adds number column to the `revisions` table.
-class AddNumberColumnToRecorderRevisions < ActiveRecord::Migration
-  def up
-    add_column :recorder_revisions, :number, :integer, null: false, default: 0
-
-    execute <<~SQL
-            CREATE OR REPLACE FUNCTION get_recorder_revisions_number()
-              RETURNS trigger AS
-            $BODY$
-            BEGIN
-                SELECT COALESCE(MAX(recorder_revisions.number), 0) + 1
-                INTO NEW.number
-                FROM
-                  recorder_revisions
-                WHERE
-                  recorder_revisions.item_type = NEW.item_type
-                  AND recorder_revisions.item_id = NEW.item_id;
-      #{"      "}
-                RETURN NEW;
-            END;
-            $BODY$ LANGUAGE plpgsql;
-    SQL
-
-    execute <<~SQL
-      CREATE TRIGGER update_recorder_revisions_number
-        BEFORE INSERT ON recorder_revisions FOR EACH ROW
-        EXECUTE PROCEDURE get_recorder_revisions_number();
-    SQL
-  end
-
-  def down
-    execute <<-SQL
-      DROP TRIGGER update_recorder_revisions_number;
-    SQL
-
-    execute <<-SQL
-      DROP FUNCTION IF EXISTS get_recorder_revisions_number;
-    SQL
-
-    remove_column :recorder_revisions, :number
-  end
-end

data/recorder.gemspec

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-lib = File.expand_path('lib', __dir__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'recorder/version'
-
-Gem::Specification.new do |spec|
-  spec.name = 'recorder'
-  spec.version = Recorder::VERSION
-  spec.authors = ['Igor Alexandrov']
-  spec.email = ['igor.alexandrov@jetrockets.com']
-
-  spec.summary = 'Rails model auditor'
-  spec.description = 'Recorder tracks changes of your Rails models'
-  spec.homepage = 'https://github.com/jetrockets/recorder'
-  spec.license = 'MIT'
-
-  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir = 'exe'
-  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ['lib']
-
-  spec.add_dependency 'activerecord', '~> 6.1'
-  spec.add_dependency 'activesupport', '~> 6.1'
-  spec.add_dependency 'pg'
-  spec.add_dependency 'request_store'
-
-  spec.add_development_dependency 'bundler', '>= 2.0'
-  # spec.add_development_dependency 'database_cleaner'
-  spec.add_development_dependency 'generator_spec'
-  spec.add_development_dependency 'jetrockets-standard'
-  spec.add_development_dependency 'rake', '~> 13.0'
-  spec.add_development_dependency 'rspec-rails'
-  # spec.add_development_dependency 'timecop', '~> 0.8.1'
-  # spec.add_development_dependency 'yard'
-  spec.add_development_dependency 'rails-dummy'
-end