journaled 4.2.0 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfdabb8b24bdfdf23c4f77ec819f03e89a4a0239ed997368eb1f07ac0bc2cd5b
-  data.tar.gz: 97eeec1dfa22f7b683f23e322eb663e6fae4b47e0c2786690c4f44166b8cca51
+  metadata.gz: dc6d5adec8f9ee32ba34d1ba8dae8cb3da062e39dd1b67d5fc3e219be116d675
+  data.tar.gz: ae77057a26203e90fbb8770e1b41864edcff69058cd80b65011eb414ddf2365a
 SHA512:
-  metadata.gz: 78c8b888f9c00a084e8d60c2f271d56a9a188f60287cb30edfbadc7a4f9fc1c3fc3210c763e757658a0040fb57f6f94f1a713fc1f95942db801e2e114dd50ec3
-  data.tar.gz: f0e56609680ecfc3e1f3f3a9d2ba801515762311307f0a208757a70a82ff7c37ba6af040f8ee5a64ebbf7a08a910579c27d65e940680b2406383b8eca022f323
+  metadata.gz: 05a99d3d5d530bca784fb44fa290d0ff661430263fbde8fa882f8c98a9dda2eabe76c82df142b6477e68439066cba52d66d875c035a7af6e9d6a2938c8985b82
+  data.tar.gz: 7726aa5152e545cdba1a50ef475f8df0ce37fb97edc2d4fa146c74f73b41c7096434948afeecbe61bc042138cae9c3b94dda475adbf9c74d42892b1d6286e069

data/README.md

@@ -179,52 +179,6 @@ journaling. Note that the less-frequently-used methods `toggle`,
 `increment*`, `decrement*`, and `update_counters` are not intercepted at
 this time.
 
-### Tagged Events
-
-Events may be optionally marked as "tagged." This will add a `tags` field, intended for tracing and
-auditing purposes.
-
-```ruby
-class MyEvent
-  include Journaled::Event
-
-  journal_attributes :attr_1, :attr_2, tagged: true
-end
-```
-
-You may then use `Journaled.tag!` and `Journaled.tagged` inside of your
-`ApplicationController` and `ApplicationJob` classes (or anywhere else!) to tag
-all events with request and job metadata:
-
-```ruby
-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.id) { perform.call }
-  end
-end
-```
-
-This feature relies on `ActiveSupport::CurrentAttributes` under the hood, so these tags are local to
-the current thread, and will be cleared at the end of each request request/job.
-
-#### Testing
-
-If you use RSpec (and have required `journaled/rspec` in your
-`spec/rails_helper.rb`), you can regression-protect important journaling
-config with the `journal_changes_to` matcher:
-
-```ruby
-it "journals exactly these things or there will be heck to pay" do
-  expect(User).to journal_changes_to(:email, :first_name, :last_name, as: :identity_change)
-end
-```
-
 ### Custom Journaling
 
 For every custom implementation of journaling in your application, define the JSON schema for the attributes in your event.
@@ -309,6 +263,40 @@ An event like the following will be journaled to kinesis:
 }
 ```
 
+### Tagged Events
+
+Events may be optionally marked as "tagged." This will add a `tags` field, intended for tracing and
+auditing purposes.
+
+```ruby
+class MyEvent
+  include Journaled::Event
+
+  journal_attributes :attr_1, :attr_2, tagged: true
+end
+```
+
+You may then use `Journaled.tag!` and `Journaled.tagged` inside of your
+`ApplicationController` and `ApplicationJob` classes (or anywhere else!) to tag
+all events with request and job metadata:
+
+```ruby
+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.id) { perform.call }
+  end
+end
+```
+
+This feature relies on `ActiveSupport::CurrentAttributes` under the hood, so these tags are local to
+the current thread, and will be cleared at the end of each request request/job.
+
 ### Helper methods for custom events
 
 Journaled provides a couple helper methods that may be useful in your
@@ -352,6 +340,102 @@ Returns one of the following in order of preference:
 In order for this to be most useful, you must configure your controller
 as described in [Change Journaling](#change-journaling) above.
 
+### Testing
+
+If you use RSpec, you can test for journaling behaviors with the
+`journal_event(s)_including` and `journal_changes_to` matchers. First, make
+sure to require `journaled/rspec` in your spec setup (e.g.
+`spec/rails_helper.rb`):
+
+```ruby
+require 'journaled/rspec'
+```
+
+#### Checking for specific events
+
+The `journal_event_including` and `journal_events_including` matchers allow you
+to check for one or more matching event being journaled:
+
+```ruby
+expect { my_code }
+  .to journal_event_including(name: 'foo')
+expect { my_code }
+  .to journal_events_including({ name: 'foo', value: 1 }, { name: 'foo', value: 2 })
+```
+
+This will only perform matches on the specified fields (and will not match one
+way or the other against unspecified fields). These matchers will also ignore
+any extraneous events that are not positively matched (as they may be unrelated
+to behavior under test).
+
+When writing tests, pairing every positive assertion with a negative assertion
+is a good practice, and so negative matching is also supported (via both
+`.not_to` and `.to not_`):
+
+```ruby
+expect { my_code }
+  .not_to journal_events_including({ name: 'foo' }, { name: 'bar' })
+expect { my_code }
+  .to raise_error(SomeError)
+  .and not_journal_event_including(name: 'foo') # the `not_` variant can chain off of `.and`
+```
+
+Several chainable modifiers are also available:
+
+```ruby
+expect { my_code }.to journal_event_including(name: 'foo')
+  .with_schema_name('my_event_schema')
+  .with_partition_key(user.id)
+  .with_stream_name('my_stream_name')
+  .with_enqueue_opts(run_at: future_time)
+  .with_priority(999)
+```
+
+All of this can be chained together to test for multiple sets of events with
+multiple sets of options:
+
+```ruby
+expect { subject.journal! }
+  .to journal_events_including({ name: 'event1', value: 300 }, { name: 'event2', value: 200 })
+    .with_priority(10)
+  .and journal_event_including(name: 'event3', value: 100)
+    .with_priority(20)
+  .and not_journal_event_including(name: 'other_event')
+```
+
+#### Checking for `Journaled::Changes` declarations
+
+The `journal_changes_to` matcher checks against the list of attributes specified
+on the model. It does not actually test that an event is emitted within a given
+codepath, and is instead intended to guard against accidental regressions that
+may impact external consumers of these events:
+
+```ruby
+it "journals exactly these things or there will be heck to pay" do
+  expect(User).to journal_changes_to(:email, :first_name, :last_name, as: :identity_change)
+end
+```
+
+### Instrumentation
+
+When an event is enqueued, an `ActiveSupport::Notification` titled
+`journaled.event.enqueue` is emitted. Its payload will include the `:event` and
+its background job `:priority`.
+
+This can be forwarded along to your preferred monitoring solution via a Rails
+initializer:
+
+```ruby
+ActiveSupport::Notifications.subscribe('journaled.event.enqueue') do |*args|
+  payload = ActiveSupport::Notifications::Event.new(*args).payload
+  journaled_event = payload[:event]
+
+  tags = { priority: payload[:priority], event_type: journaled_event.journaled_attributes[:event_type] }
+
+  Statsd.increment('journaled.event.enqueue', tags: tags.map { |k,v| "#{k.to_s[0..64]}:#{v.to_s[0..255]}" })
+end
+```
+
 ## Upgrades
 
 Since this gem relies on background jobs (which can remain in the queue across

data/app/models/journaled/event.rb

@@ -63,7 +63,7 @@ module Journaled::Event
   end
 
   included do
-    cattr_accessor(:journaled_enqueue_opts, instance_writer: false) { {} }
+    class_attribute :journaled_enqueue_opts, default: {}
 
     journal_attributes :id, :event_type, :created_at
   end

data/app/models/journaled/writer.rb

@@ -26,9 +26,9 @@ class Journaled::Writer
 
   def journal!
     validate!
-    Journaled::DeliveryJob
-      .set(journaled_enqueue_opts.reverse_merge(priority: Journaled.job_priority))
-      .perform_later(**delivery_perform_args)
+    ActiveSupport::Notifications.instrument('journaled.event.enqueue', event: journaled_event, priority: job_opts[:priority]) do
+      Journaled::DeliveryJob.set(job_opts).perform_later(**delivery_perform_args)
+    end
   end
 
   private
@@ -43,6 +43,10 @@ class Journaled::Writer
     schema_validator(journaled_schema_name).validate! serialized_event
   end
 
+  def job_opts
+    journaled_enqueue_opts.reverse_merge(priority: Journaled.job_priority)
+  end
+
   def delivery_perform_args
     {
       serialized_event: serialized_event,

data/lib/journaled/rspec.rb

@@ -16,3 +16,89 @@ RSpec::Matchers.define :journal_changes_to do |*attribute_names, as:|
     "expected #{model_class} not to journal changes to #{attribute_names.map(&:inspect).join(', ')} as #{as.inspect}"
   end
 end
+
+RSpec::Matchers.define_negated_matcher :not_journal_changes_to, :journal_changes_to
+
+RSpec::Matchers.define :journal_events_including do |*expected_events|
+  raise "Please specify at least one expected event. RSpec argument matchers are supported." if expected_events.empty?
+
+  attr_accessor :expected, :actual, :matches, :nonmatches
+
+  chain :with_schema_name, :expected_schema_name
+  chain :with_partition_key, :expected_partition_key
+  chain :with_stream_name, :expected_stream_name
+  chain :with_enqueue_opts, :expected_enqueue_opts
+  chain :with_priority, :expected_priority
+
+  def supports_block_expectations?
+    true
+  end
+
+  def hash_including_recursive(hash)
+    hash_including(
+      hash.transform_values { |v| v.is_a?(Hash) ? hash_including_recursive(v) : v },
+    )
+  end
+
+  match do |block|
+    expected_events = [expected_events.first].flatten(1) unless expected_events.length > 1
+
+    self.expected = expected_events.map { |e| { journaled_attributes: e } }
+    expected.each { |e| e.merge!(journaled_schema_name: expected_schema_name) } if expected_schema_name
+    expected.each { |e| e.merge!(journaled_partition_key: expected_partition_key) } if expected_partition_key
+    expected.each { |e| e.merge!(journaled_stream_name: expected_stream_name) } if expected_stream_name
+    expected.each { |e| e.merge!(journaled_enqueue_opts: expected_enqueue_opts) } if expected_enqueue_opts
+    expected.each { |e| e.merge!(priority: expected_priority) } if expected_priority
+    self.actual = []
+
+    callback = ->(_name, _started, _finished, _unique_id, payload) do
+      event = payload[:event]
+      a = { journaled_attributes: event.journaled_attributes }
+      a[:journaled_schema_name] = event.journaled_schema_name if expected_schema_name
+      a[:journaled_partition_key] = event.journaled_partition_key if expected_partition_key
+      a[:journaled_stream_name] = event.journaled_stream_name if expected_stream_name
+      a[:journaled_enqueue_opts] = event.journaled_enqueue_opts if expected_enqueue_opts
+      a[:priority] = payload[:priority] if expected_priority
+      actual << a
+    end
+
+    ActiveSupport::Notifications.subscribed(callback, 'journaled.event.enqueue', &block)
+
+    self.matches = actual.select do |a|
+      expected.any? { |e| values_match?(hash_including_recursive(e), a) }
+    end
+
+    self.nonmatches = actual - matches
+
+    exact_matches = matches.dup
+    matches.count == expected.count && expected.all? do |e|
+      match, index = exact_matches.each_with_index.find { |a, _| values_match?(hash_including_recursive(e), a) }
+      exact_matches.delete_at(index) if match
+    end && exact_matches.empty?
+  end
+
+  failure_message do
+    <<~MSG
+      Expected the code block to journal exactly one matching event per expected event.
+
+      Expected Events (#{expected.count}):
+      ===============================================================================
+        #{expected.map(&:to_json).join("\n ")}
+      ===============================================================================
+
+      Matching Events (#{matches.count}):
+      ===============================================================================
+        #{matches.map(&:to_json).join("\n ")}
+      ===============================================================================
+
+      Non-Matching Events (#{nonmatches.count}):
+      ===============================================================================
+        #{nonmatches.map(&:to_json).join("\n  ")}
+      ===============================================================================
+    MSG
+  end
+end
+
+RSpec::Matchers.alias_matcher :journal_event_including, :journal_events_including
+RSpec::Matchers.define_negated_matcher :not_journal_events_including, :journal_events_including
+RSpec::Matchers.define_negated_matcher :not_journal_event_including, :journal_event_including

data/lib/journaled/version.rb

@@ -1,3 +1,3 @@
 module Journaled
-  VERSION = "4.2.0".freeze
+  VERSION = "4.3.0".freeze
 end

data/spec/models/concerns/journaled/changes_spec.rb

@@ -44,7 +44,7 @@ RSpec.describe Journaled::Changes do
 
   subject { klass.new }
 
-  let(:change_writer) { double(Journaled::ChangeWriter, create: true, update: true, delete: true) }
+  let(:change_writer) { instance_double(Journaled::ChangeWriter, create: true, update: true, delete: true) }
 
   before do
     allow(Journaled::ChangeWriter).to receive(:new) do |opts|

data/spec/models/journaled/writer_spec.rb

@@ -1,11 +1,12 @@
 require 'rails_helper'
 
 RSpec.describe Journaled::Writer do
+  let(:event_class) { Class.new { include Journaled::Event } }
   subject { described_class.new journaled_event: journaled_event }
 
   describe '#initialize' do
     context 'when the Journaled Event does not implement all the necessary methods' do
-      let(:journaled_event) { double }
+      let(:journaled_event) { instance_double(event_class) }
 
       it 'raises on initialization' do
         expect { subject }.to raise_error RuntimeError, /An enqueued event must respond to/
@@ -14,7 +15,8 @@ RSpec.describe Journaled::Writer do
 
     context 'when the Journaled Event returns non-present values for some of the required methods' do
       let(:journaled_event) do
-        double(
+        instance_double(
+          event_class,
           journaled_schema_name: nil,
           journaled_attributes: {},
           journaled_partition_key: '',
@@ -30,7 +32,8 @@ RSpec.describe Journaled::Writer do
 
     context 'when the Journaled Event complies with the API' do
       let(:journaled_event) do
-        double(
+        instance_double(
+          event_class,
           journaled_schema_name: :fake_schema_name,
           journaled_attributes: { foo: :bar },
           journaled_partition_key: 'fake_partition_key',
@@ -71,8 +74,9 @@ RSpec.describe Journaled::Writer do
 
     let(:journaled_enqueue_opts) { {} }
     let(:journaled_event) do
-      double(
-        journaled_schema_name: :fake_schema_name,
+      instance_double(
+        event_class,
+        journaled_schema_name: 'fake_schema_name',
         journaled_attributes: journaled_event_attributes,
         journaled_partition_key: 'fake_partition_key',
         journaled_stream_name: 'my_app_events',
@@ -85,7 +89,9 @@ RSpec.describe Journaled::Writer do
       let(:journaled_event_attributes) { { foo: 1 } }
 
       it 'raises an error and does not enqueue anything' do
-        expect { subject.journal! }.to raise_error JSON::Schema::ValidationError
+        expect { subject.journal! }
+          .to raise_error(JSON::Schema::ValidationError)
+          .and not_journal_event_including(anything)
         expect(enqueued_jobs.count).to eq 0
       end
     end
@@ -95,7 +101,9 @@ RSpec.describe Journaled::Writer do
         let(:journaled_event_attributes) { { id: 'FAKE_UUID', event_type: 'fake_event', created_at: Time.zone.now, foo: 1 } }
 
         it 'raises an error and does not enqueue anything' do
-          expect { subject.journal! }.to raise_error JSON::Schema::ValidationError
+          expect { subject.journal! }
+            .to raise_error(JSON::Schema::ValidationError)
+            .and not_journal_event_including(anything)
           expect(enqueued_jobs.count).to eq 0
         end
       end
@@ -104,7 +112,13 @@ RSpec.describe Journaled::Writer do
         let(:journaled_event_attributes) { { id: 'FAKE_UUID', event_type: 'fake_event', created_at: Time.zone.now, foo: :bar } }
 
         it 'creates a delivery with the app name passed through' do
-          expect { subject.journal! }.to change { enqueued_jobs.count }.from(0).to(1)
+          expect { subject.journal! }
+            .to change { enqueued_jobs.count }.from(0).to(1)
+            .and journal_event_including(journaled_event_attributes)
+            .with_schema_name('fake_schema_name')
+            .with_partition_key('fake_partition_key')
+            .with_stream_name('my_app_events')
+            .with_enqueue_opts({})
           expect(enqueued_jobs.first[:args].first).to include('stream_name' => 'my_app_events')
         end
 
@@ -124,6 +138,13 @@ RSpec.describe Journaled::Writer do
                 enqueued_jobs.count { |j| j['job_class'] == 'Journaled::DeliveryJob' && j['priority'] == 999 }
               end
             }.from(0).to(1)
+              .and journal_event_including(journaled_event_attributes)
+              .with_schema_name('fake_schema_name')
+              .with_partition_key('fake_partition_key')
+              .with_stream_name('my_app_events')
+              .with_priority(999)
+              .and not_journal_event_including(anything)
+              .with_enqueue_opts(priority: 999) # with_enqueue_opts looks at event itself
           end
         end
 
@@ -138,6 +159,12 @@ RSpec.describe Journaled::Writer do
                 enqueued_jobs.count { |j| j['job_class'] == 'Journaled::DeliveryJob' && j['priority'] == 13 }
               end
             }.from(0).to(1)
+              .and journal_event_including(journaled_event_attributes)
+              .with_schema_name('fake_schema_name')
+              .with_partition_key('fake_partition_key')
+              .with_stream_name('my_app_events')
+              .with_priority(13)
+              .with_enqueue_opts(priority: 13)
           end
         end
       end
@@ -154,7 +181,9 @@ RSpec.describe Journaled::Writer do
         end
 
         it 'raises an error and does not enqueue anything' do
-          expect { subject.journal! }.to raise_error JSON::Schema::ValidationError
+          expect { subject.journal! }
+            .to not_journal_events_including(anything)
+            .and raise_error JSON::Schema::ValidationError
           expect(enqueued_jobs.count).to eq 0
         end
       end
@@ -165,7 +194,16 @@ RSpec.describe Journaled::Writer do
         end
 
         it 'creates a delivery with the app name passed through' do
-          expect { subject.journal! }.to change { enqueued_jobs.count }.from(0).to(1)
+          expect { subject.journal! }
+            .to change { enqueued_jobs.count }.from(0).to(1)
+            .and journal_event_including(journaled_event_attributes)
+            .with_schema_name('fake_schema_name')
+            .with_partition_key('fake_partition_key')
+            .with_stream_name('my_app_events')
+            .with_enqueue_opts({})
+            .with_priority(Journaled.job_priority)
+            .and not_journal_event_including(anything)
+            .with_enqueue_opts(priority: Journaled.job_priority)
           expect(enqueued_jobs.first[:args].first).to include('stream_name' => 'my_app_events')
         end
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: journaled
 version: !ruby/object:Gem::Version
-  version: 4.2.0
+  version: 4.3.0
 platform: ruby
 authors:
 - Jake Lipson
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-03-17 00:00:00.000000000 Z
+date: 2022-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob