v5.3.2

What's Changed

• Add Rails 7.1 testing by @argvniyx-enroute in #35

New Contributors

• @argvniyx-enroute made their first contribution in #35

Full Changelog: v5.3.1...v5.3.2

v5.3.1

What's Changed

• [Fix] Ensure that classes automatically excluded from audit logging stay excluded after reloads by @smudge in #32

Full Changelog: v5.3.0...v5.3.1

New threadsafe "with_transactional_batching" block method

This adds a Journaled.with_transactional_batching { } feature that can be used to conditionally enable batching within the current thread, even if the feature is disabled globally.

New `snapshot_on_deletion` feature!

This adds a new config that will enable snapshots by default for all delete actions.

Journaled::AuditLog.snapshot_on_deletion = true

Since changes will be empty on deletion, you should consider using this if you care about the contents of any records being deleted (and/or don't have a full audit trail from their time of creation).

Introducing: `Journaled::AuditLog`

This release introduces Betterment's Journaled::AuditLog mixin for ActiveRecord modules. It's similar to audit logging / papertrail-like gems, in that it will record changes to models (insert/update/delete). But instead of storing these changes in a local versions table (etc), it will emit them in the form of journaled events.

To get started, add has_audit_log to a model:

class MyModel < ApplicationRecord
  has_audit_log
  
  # ...
end

This pairs with the 5.0 release that introduced transactionally-batched journaling. (So, if you're changing several records at once within the scope of a single transaction, you'll only end up enqueuing 1 journaled event job).

Introducing: Batched Journaling!

This adds transactional batching to journaled. What does that mean? Well, now, by default, when multiple events are emitted inside of a transaction:

ActiveRecord::Base.transaction do
  event_1.journal!
  event_2.journal!
end

A single job will be enqueued directly before the SQL COMMIT statement, batching up the two events. (And if the transaction rolls back, the job will never be enqueued.)

This behavior can be disabled with a global config, but may become permanent in future versions:

Journaled.transactional_batching_enabled = !Rails.env.production?

What happens if we aren't in a transaction? Well, the same thing that happened before! (A job will be enqueued right away.) In future, we may introduce safety checks to warn you if you are attempting to journal events outside of a transactional context.

Because this bumps the version to 5.0, it also removes compatibility for Journaled::DeliveryJob jobs enqueued with legacy (3.1.0-era) arguments. This job now accepts a list of events to emit, rather than a single event-kwarg-blog, so a new legacy input pattern is accepted for compatibility with jobs enqueued by v4.x.x of the gem.

Introducing: Tagged Events!

• This adds a new tagged: true option to journal_attributes, and Journaled.tagged/Journaled.tag! helpers that allow events to be tagged with contextual metadata (useful for audit logs and tracing):

  class MyEvent
    include Journaled::Event
    
    journal_attributes :attr_1, :attr_2, tagged: true
  end
  
  Journaled.tagged(foo: 'bar') do
    # events emitted in this scope will have a `tags` attribute with contents `{ "foo": "bar" }`
  end
  
  # events emitted in this scope will have a `tags` attribute with contents `{}`

  All "tagged" events will be given a tags attribute, but it can be empty. Consuming apps with strict schema enforcement ("additionalProperties": false) will need to include the "tags" field in any relevant event schemas. While this feature is not a breaking change for existing events, we have incremented the gem by a full minor version (to 4.1.0).

• Under the hood, this removes RequestStore in favor of ActiveSupport::CurrentAttributes. This is the new convention for Rails apps (available in 5.2+), so in theory consuming apps shouldn't be impacted by this, but it is another reason to increment a full minor version at the least.

• The README now includes two standard usage examples:

class ApplicationController < ActionController::Base
  before_action do
    Journaled.tag!(request_id: request.request_id, current_user_id: current_user&.id)
  end
end

class ApplicationJob < ActiveJob::Base
  around_perform do |job, perform|
    Journaled.tagged(job_id: job.job_id, &perform)
  end
end

Direct `stream_name` configurability! (Removing `app_name` configs)

This release replaces default_app_name, journaled_app_name, and other app_name usage with default_stream_name, journaled_stream_name, and stream_name (respectively). It also moves off of an ENV-vars-by-default approach for stream configuration, to more of a BYO-ENV-vars strategy (where you can still reference the old ENV vars if you want).

Naturally, this prompts a major version bump to 4.0, and upgrade instructions have been added the README.

Other Information

• Worth noting, stream_name is now baked-into the Journaled::DeliveryJob handlers. This means that jobs will use the stream names that the events were configured to use at the time they were enqueued.

• The Journaled::Delivery "performable" class has been removed. (It was succeeded by the Journaled::DeliveryJob ActiveJob in version 3.0.) This means that anyone upgrading directly from 2.5.0 or below to 4.0 (this new version) will see errors if they have any jobs actively queued. A recommendation has been added to the README to upgrade one major version at a time, so 2.x -> 3.x -> 4.x would be the safest path.

v3.1.0 - detect_queue_adapter fixes

• This release fixes detect_queue_adapter! for aliased adapter constants. Not all adapter constants were compatible with the split('::').last function used to find the human-readable adapter name. Thankfully, in Rails 5.2+, there is a queue_adapter_name method that can be used to find precisely what we need.
• As such, this removes Rails 5.1 support, and adds 6.1 to the CI test matrix.

Full Changelog: v3.0.0...v3.1.0

Introducing: ActiveJob, and support for other queue adapters

• This removes the gem's direct dependency on delayed_job, in favor of an indirect dependency via activejob. As such, other DB-backed queue adapters can theoretically be supported!
• As a safety measure, the gem will now check in production that the queue adapter is :delayed_job, :que, :good_job, or :delayed. If it isn't in that list, the application will fail to boot. (Other adapters are allowed in non-production environments, and this gem now uses the :test adapter for its own tests.)
• The new job class is called Journaled::DeliveryJob. The DelayedJob-friendly equivalent (Journaled::Delivery) is still around for backwards-compatibility with any in-flight jobs. This will be removed in 4.0.
• This also trims down this gem's overall dependencies. Rather than depending on rails, it depends on railties, activejob, and activerecord. (And in its tests, it no longer depends on pg but instead uses an in-memory sqlite database.)