journaled 2.0.0.alpha1 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4ee54a77497db5d43b3932d6015b18b6b2c4ae45
-  data.tar.gz: 6fc6bed161faf09676c7578531eb563a47ee9e6b
+  metadata.gz: 205035e968787393ef42062f36bdb6068e48a962
+  data.tar.gz: bd6db1eec4f70ed2311e099d942014f9dd10c073
 SHA512:
-  metadata.gz: 030301523134d5a36c15de4e7096917c9d948c00c1514c41c9e82ff0184f358f9c346786e9f1757d229c0050073f996b03ff2bac038a7a773a9f9c02bd56bd5a
-  data.tar.gz: a6d3c21d82902e96f3486b3637365b20d0803a11ece98260121bc80b73555bf823b3eaf6731ba82daa8c83e6044f815793e4c5d73c996d8606eed7f0dec85f5a
+  metadata.gz: 4f482a501e506d57a38345a985485846f842a714c16a0e4af90b1a130751af5ec482759ed1a72aada99db5435adf5fbea3f137caa3e7e341f245ebbd4a5bb0d3
+  data.tar.gz: 46644b2d30fc64f0c52a810203940a8bffc6b8cd854635199582e356bbeb61c2749f87aa7046f8fa44d33011e384ec31983bd0be6537735d69d118777b84ec5f

data/README.md

@@ -26,37 +26,44 @@ if you haven't already.
 
 2. To integrate Journaled into your application, simply include the gem in your 
 app's Gemfile.
+
+    ```ruby
+    gem 'journaled'
     ```
-    gem 'journaled', https_github: 'Betterment/journaled'
+
+    If you use rspec, add the following to your rails helper:
+
+    ```ruby
+    # spec/rails_helper.rb
+
+    # ... your other requires
+    require 'journaled/rspec'
     ```
-3. You will also need to define the following environment variables to allow Journaled to publish events to your AWS Kinesis event stream:
 
-  * `JOURNALED_STREAM_NAME`
+3. You will also need to define the following environment variables to allow Journaled to publish events to your AWS Kinesis event stream:
 
-Special case: if your `Journaled::Event` objects override the
-`#journaled_app_name` method to a non-nil value e.g. `my_app`, you will
-instead need to provide a corresponding
-`[upcased_app_name]_JOURNALED_STREAM_NAME` variable for each distinct
-value, e.g. `MY_APP_JOURNALED_STREAM_NAME`. You can provide a default value
-for all `Journaled::Event`s in an initializer like this:
+    * `JOURNALED_STREAM_NAME`
 
-```ruby
-Journaled.default_app_name = 'my_app'
-```
+    Special case: if your `Journaled::Event` objects override the
+    `#journaled_app_name` method to a non-nil value e.g. `my_app`, you will
+    instead need to provide a corresponding
+    `[upcased_app_name]_JOURNALED_STREAM_NAME` variable for each distinct
+    value, e.g. `MY_APP_JOURNALED_STREAM_NAME`. You can provide a default value
+    for all `Journaled::Event`s in an initializer like this:
 
-You may optionally define the following ENV vars to specify AWS
-credentials outside of the locations that the AWS SDK normally looks:
+    ```ruby
+    Journaled.default_app_name = 'my_app'
+    ```
 
-  * `RUBY_AWS_ACCESS_KEY_ID`
-  * `RUBY_AWS_SECRET_ACCESS_KEY`
+    You may optionally define the following ENV vars to specify AWS
+    credentials outside of the locations that the AWS SDK normally looks:
 
-You may also specify the region to target your AWS stream by setting
-`AWS_DEFAULT_REGION`. If you don't specify, Journaled will default to
-`us-east-1`.
+      * `RUBY_AWS_ACCESS_KEY_ID`
+      * `RUBY_AWS_SECRET_ACCESS_KEY`
 
-Journaled::Event provides a `commit_hash` method which you may journal
-if you like. If you choose to use it, you must provide a `GIT_COMMIT`
-environment variable.
+    You may also specify the region to target your AWS stream by setting
+    `AWS_DEFAULT_REGION`. If you don't specify, Journaled will default to
+    `us-east-1`.
 
 ## Usage
 
@@ -66,7 +73,7 @@ Out of the box, `Journaled` provides an event type and ActiveRecord
 mix-in for durably journaling changes to your model, implemented via
 ActiveRecord hooks. Use it like so:
 
-```
+```ruby
 class User < ApplicationRecord
   include Journaled::Changes
 
@@ -76,7 +83,7 @@ end
 
 Add the following to your controller base class for attribution:
 
-```
+```ruby
 class ApplicationController < ActionController::Base
   include Journaled::Actor
 
@@ -101,10 +108,30 @@ record is created or destroyed, an event will be sent to Kinesis with the follow
     your `journal_changes_to` declaration (e.g. `identity_change`)
   * `changes` - a serialized JSON object representing the latest values
     of any new or changed attributes from the specified set (e.g.
-    `{"email":"mynewemail@example.com"}`)
+    `{"email":"mynewemail@example.com"}`). Upon destroy, all
+    specified attributes will be serialized as they were last stored.
   * `actor` - a string (usually a rails global_id) representing who
     performed the action.
 
+Callback-bypassing database methods like `update_all`, `delete_all`,
+`update_columns` and `delete` are intercepted and will require an
+additional `force: true` argument if they would interfere with change
+journaling. Note that the less-frequently-used methods `toggle`,
+`increment*`, `decrement*`, and `update_counters` are not intercepted at
+this time.
+ 
+#### 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. 
@@ -189,6 +216,49 @@ An event like the following will be journaled to kinesis:
 }
 ```
 
+### Helper methods for custom events
+
+Journaled provides a couple helper methods that may be useful in your
+custom events. You can add whichever you need your event types like
+this:
+
+```ruby
+# my_event.rb
+class MyEvent
+  include Journaled::Event
+
+  journal_attributes :commit_hash, :actor_uri # ... etc, etc
+
+  def commit_hash
+    Journaled.commit_hash
+  end
+
+  def actor_uri
+    Journaled.actor_uri
+  end
+
+  # ... etc, etc
+end
+```
+
+#### `Journaled.commit_hash`
+
+If you choose to use it, you must provide a `GIT_COMMIT` environment
+variable. `Journaled.commit_hash` will fail if it is undefined.
+
+#### `Journaled.actor_uri`
+
+Returns one of the following in order of preference:
+
+* The current controller-defined `journaled_actor`'s GlobalID, if
+  set
+* A string of the form `gid://[app_name]/[os_username]` if performed on
+  the command line
+* a string of the form `gid://[app_name]` as a fallback
+
+In order for this to be most useful, you must configure your controller
+as described in [Change Journaling](#change-journaling) above.
+
 ## Future improvements & issue tracking
 Suggestions for enhancements to this engine are currently being tracked via Github Issues. Please feel free to open an
 issue for a desired feature, as well as for any observed bugs.

data/app/models/concerns/journaled/changes.rb

@@ -3,7 +3,9 @@ module Journaled::Changes
 
   included do
     cattr_accessor :_journaled_change_definitions
+    cattr_accessor :journaled_attribute_names
     self._journaled_change_definitions = []
+    self.journaled_attribute_names = []
 
     after_create do
       self.class._journaled_change_definitions.each do |definition|
@@ -24,6 +26,32 @@ module Journaled::Changes
     end
   end
 
+  def delete(force: false)
+    if force || self.class.journaled_attribute_names.empty?
+      super()
+    else
+      raise(<<~ERROR)
+        #delete aborted by Journaled::Changes.
+
+        Invoke #delete(force: true) to override and skip journaling.
+      ERROR
+    end
+  end
+
+  def update_columns(attributes, force: false)
+    unless force || self.class.journaled_attribute_names.empty?
+      conflicting_journaled_attribute_names = self.class.journaled_attribute_names & attributes.keys.map(&:to_sym)
+      raise(<<~ERROR) if conflicting_journaled_attribute_names.present?
+        #update_columns aborted by Journaled::Changes due to journaled attributes:
+
+          #{conflicting_journaled_attribute_names.join(', ')}
+
+        Invoke #update_columns with additional arg `{ force: true }` to override and skip journaling.
+      ERROR
+    end
+    super(attributes)
+  end
+
   class_methods do
     def journal_changes_to(*attribute_names, as:) # rubocop:disable Naming/UncommunicativeMethodParamName
       if attribute_names.empty? || attribute_names.any? { |n| !n.is_a?(Symbol) }
@@ -33,6 +61,19 @@ module Journaled::Changes
       raise "as: must be a symbol" unless as.is_a?(Symbol)
 
       _journaled_change_definitions << Journaled::ChangeDefinition.new(attribute_names: attribute_names, logical_operation: as)
+      journaled_attribute_names.concat(attribute_names)
+    end
+
+    def delete(id_or_array, force: false)
+      if force || journaled_attribute_names.empty?
+        where(primary_key => id_or_array).delete_all(force: true)
+      else
+        raise(<<~ERROR)
+          #delete aborted by Journaled::Changes.
+
+          Invoke #delete(id_or_array, force: true) to override and skip journaling.
+        ERROR
+      end
     end
   end
 end

data/app/models/journaled/actor_uri_provider.rb

@@ -0,0 +1,22 @@
+class Journaled::ActorUriProvider
+  include Singleton
+
+  def actor_uri
+    actor_global_id_uri || fallback_global_id_uri
+  end
+
+  private
+
+  def actor_global_id_uri
+    actor = RequestStore.store[:journaled_actor_proc]&.call
+    actor.to_global_id.to_s if actor
+  end
+
+  def fallback_global_id_uri
+    if defined?(::Rails::Console) || File.basename($PROGRAM_NAME) == "rake"
+      "gid://local/#{Etc.getlogin}"
+    else
+      "gid://#{Rails.application.config.global_id.app}"
+    end
+  end
+end

data/app/models/journaled/change_definition.rb

@@ -2,7 +2,23 @@ class Journaled::ChangeDefinition
   attr_reader :attribute_names, :logical_operation
 
   def initialize(attribute_names:, logical_operation:)
-    @attribute_names = attribute_names
+    @attribute_names = attribute_names.map(&:to_s)
     @logical_operation = logical_operation
+    @validated = false
+  end
+
+  def validated?
+    @validated
+  end
+
+  def validate!(model)
+    nonexistent_attribute_names = attribute_names - model.class.attribute_names
+    raise <<~ERROR if nonexistent_attribute_names.present?
+      Unable to persist #{model} because `journal_changes_to, as: #{logical_operation.inspect}`
+      includes nonexistant attributes:
+
+        #{nonexistent_attribute_names.join(', ')}
+    ERROR
+    @validated = true
   end
 end

data/app/models/journaled/change_writer.rb

@@ -1,14 +1,11 @@
 class Journaled::ChangeWriter
   attr_reader :model, :change_definition
-  delegate :logical_operation, to: :change_definition
+  delegate :attribute_names, :logical_operation, to: :change_definition
 
   def initialize(model:, change_definition:)
     @model = model
     @change_definition = change_definition
-  end
-
-  def attribute_names
-    @attribute_names ||= change_definition.attribute_names.map(&:to_s)
+    change_definition.validate!(model) unless change_definition.validated?
   end
 
   def create
@@ -48,27 +45,11 @@ class Journaled::ChangeWriter
   end
 
   def actor_uri
-    actor_global_id_uri || fallback_global_id_uri
+    @actor_uri ||= Journaled.actor_uri
   end
 
   private
 
-  def actor_global_id_uri
-    actor.to_global_id.to_s if actor
-  end
-
-  def actor
-    @actor ||= RequestStore.store[:journaled_actor_proc]&.call
-  end
-
-  def fallback_global_id_uri
-    if defined?(::Rails::Console) || File.basename($PROGRAM_NAME) == "rake"
-      "gid://local/#{Etc.getlogin}"
-    else
-      "gid://#{Rails.application.config.global_id.app}"
-    end
-  end
-
   def pluck_changed_values(change_hash, index:)
     change_hash.each_with_object({}) do |(k, v), result|
       result[k] = v[index]

data/app/models/journaled/event.rb

@@ -19,10 +19,6 @@ module Journaled::Event
     @created_at ||= Time.zone.now
   end
 
-  def commit_hash
-    @commit_hash ||= ENV.fetch('GIT_COMMIT')
-  end
-
   # Event metadata and configuration (not serialized)
 
   def journaled_schema_name

data/config/initializers/change_protection.rb

@@ -0,0 +1,3 @@
+require 'journaled/relation_change_protection'
+
+ActiveRecord::Relation.class_eval { prepend Journaled::RelationChangeProtection }

data/lib/journaled.rb

@@ -20,5 +20,13 @@ module Journaled
     @schema_providers ||= [Journaled::Engine, Rails]
   end
 
-  module_function :development_or_test?, :enabled?, :schema_providers
+  def commit_hash
+    ENV.fetch('GIT_COMMIT')
+  end
+
+  def actor_uri
+    Journaled::ActorUriProvider.instance.actor_uri
+  end
+
+  module_function :development_or_test?, :enabled?, :schema_providers, :commit_hash, :actor_uri
 end

data/lib/journaled/relation_change_protection.rb

@@ -0,0 +1,27 @@
+module Journaled::RelationChangeProtection
+  def update_all(updates, force: false)
+    unless force || !@klass.respond_to?(:journaled_attribute_names) || @klass.journaled_attribute_names.empty?
+      conflicting_journaled_attribute_names = @klass.journaled_attribute_names & updates.keys.map(&:to_sym)
+      raise(<<~ERROR) if conflicting_journaled_attribute_names.present?
+        #update_all aborted by Journaled::Changes due to journaled attributes:
+
+          #{conflicting_journaled_attribute_names.join(', ')}
+
+        Invoke #update_all with additional arg `{ force: true }` to override and skip journaling.
+      ERROR
+    end
+    super(updates)
+  end
+
+  def delete_all(force: false)
+    if force || !@klass.respond_to?(:journaled_attribute_names) || @klass.journaled_attribute_names.empty?
+      super()
+    else
+      raise(<<~ERROR)
+        #delete_all aborted by Journaled::Changes.
+
+        Invoke #delete_all(force: true) to override and skip journaling.
+      ERROR
+    end
+  end
+end

data/lib/journaled/rspec.rb

@@ -0,0 +1,18 @@
+require 'rspec/expectations'
+
+RSpec::Matchers.define :journal_changes_to do |*attribute_names, as:|
+  match do |model_class|
+    model_class._journaled_change_definitions.any? do |change_definition|
+      change_definition.logical_operation == as &&
+        attribute_names.map(&:to_s).sort == change_definition.attribute_names.sort
+    end
+  end
+
+  failure_message do |model_class|
+    "expected #{model_class} to journal changes to #{attribute_names.map(&:inspect).join(', ')} as #{as.inspect}"
+  end
+
+  failure_message_when_negated do |model_class|
+    "expected #{model_class} not to journal changes to #{attribute_names.map(&:inspect).join(', ')} as #{as.inspect}"
+  end
+end

data/lib/journaled/version.rb

@@ -1,3 +1,3 @@
 module Journaled
-  VERSION = "2.0.0.alpha1".freeze
+  VERSION = "2.0.0.rc1".freeze
 end

data/spec/dummy/README.rdoc

@@ -0,0 +1,28 @@
+== README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...
+
+
+Please feel free to use a different markup language if you do not plan to run
+<tt>rake doc:app</tt>.