explicit_activerecord 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f9d1ed0101b826fc591cb78e46eef4f297754b42dba7fa3e2ee3c8342082ddd3
+  data.tar.gz: c52614803edb50bd57da611fe5e19507f68199de979c314ad34c32f6495bf1e2
+SHA512:
+  metadata.gz: 968de86a11cd97fcf632c2d9d4d043d44eda52bda87ccf1e55a944afdd1feeaa95e9caaca75027a8047c51be5c3bc01675502f128a29bdaf7fbdcc3fdeac56d5
+  data.tar.gz: d41aeb3ecd8d4b32492f2d71253ace7884883a436c23307cfe13040b4dd98fd59dee0595318cb7cb3c0a4c0fb7ffd1e5368d6dcd7ac214e8bd1e7e14dc79845d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Gusto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,168 @@
+# ExplicitActiveRecord
+
+[![Build status](https://badge.buildkite.com/3899d0bb95a2680f73cad1df4cedc875476548d85392d47740.svg?branch=main)](https://buildkite.com/gusto/explicitactiverecord)
+
+
+If you're like a lot of Rails projects, you use `ActiveRecord`. And like a lot of other Rails projects, you probably call `save!`, `update!`, and `destroy!` on instances of your model throughout your codebase, and probably couldn't easily locate all of the places.
+
+`ExplicitActiveRecord` exists for users of `ActiveRecord` who want to use `ActiveRecord` more explicitly.
+
+Today, there are lots of very implicit ways to use `ActiveRecord`.
+
+Examples:
+```ruby
+class MyModel < ActiveRecord::Base; end
+class MyOtherModel < ActiveRecord::Base
+  has_one :my_model, autosave: true
+end
+instance = MyModel.new
+
+# Lots of different instance methods
+instance.save!
+instance.update!
+
+# Dynamic creation methods off of associations
+MyOtherModel.new.create_my_model
+
+# Autosaves "MyModel" association
+MyOtherModel.new.save!
+
+# Can reference the class implicitly
+self.class.create!
+
+# ... and more!!!
+```
+
+This gem gives several APIs to allow you to use `ActiveRecord` more explicitly.
+
+Note that this gem primarily exists as a way to use `ActiveRecord` explicitly when your current usage is highly implicit. We recommend eventually migrating to Ruby and Rails features once your model is using ActiveRecord explicitly. See the last section for more information.
+
+## ExplicitActiveRecord::Persistence
+`ExplicitActiveRecord::Persistence` has a single public method to find all places where persistence events — `create`, `update`, or `destroy` — happen.
+
+Once your model is configured correctly to use `ExplicitActiveRecord::Persistence`, you will be required to wrap all code that persists your model with code that explicitly declares both the class and instance that is being persisted. See usage for more information.
+
+### Incremental
+`ExplicitActiveRecord::Persistence` is *incremental*. This means that you can include `ExplicitActiveRecord::Persistence`, and specify a *non-raising* behavior when the model is persisted implicitly, and use your logs or bug tracking system to find places where the model is implicitly raising, without breaking production. [See the `README` for `deprecation_helper` for more information on this](https://github.com/Gusto/deprecation_helper/blob/main/README.md).
+
+### Usage 
+The first step is to `include ExplicitActiveRecord::Persistence` in your models:
+
+Secondly, you'll need to configure `dangerous_update_behaviors` (see the `deprecation_helper` gem for more info).
+
+All together, this looks like this:
+```ruby
+# Example 1
+class MyModel < ActiveRecord::Base
+  include ExplicitActiveRecord::Persistence
+  self.dangerous_update_behaviors = [DeprecationHelper::Strategies::LogError.new]
+end
+
+# Example 2
+class MyOtherModel < ActiveRecord::Base
+  include ExplicitActiveRecord::Persistence
+  self.dangerous_update_behaviors = [DeprecationHelper::Strategies::RaiseError.new]
+  has_one :my_model, autosave: true
+end
+```
+
+Now you can use the `with_explicit_persistence` method to declare explicitly when the model is being persisted. Here are some examples of supported usages:
+
+```ruby
+# You can pass in a single instance of the `MyModel` class:
+MyModel.with_explicit_persistence_for(instance) do
+  instance.save!
+end
+
+# You can pass in multiple instances of the `MyModel` class:
+MyModel.with_explicit_persistence_for([instance1, instance2]) do
+  instance1.save!
+  instance2.save!
+end
+# or
+instances = [instance1, instance2]
+MyModel.with_explicit_persistence_for(instances) do
+  instances.destroy_all
+end
+```
+
+Note that you cannot pass in a relation to `with_explicit_persistence_for` — only an instance of or array of instances of the class.
+
+It is *not* recommended to use this dynamically, such as:
+```ruby
+# Don't do this!
+self.class.with_explicit_persistence_forinstance) do
+  instance.save!
+end
+```
+The reason we do not want to do this is because writing to the class is no longer explicit! Just looking at this code, you cannot tell what class `self.class` is. If `self.class` is `MyModel`, then searching your codebase for `MyModel.with_explicit_persistence_for` will no longer reveal all of the persistence locations.
+
+### Specifying different dangerous update behavior
+You can specify multiple behaviors to invoke when the model is updated implicitly/dangerously, as long as that strategy conforms to `DeprecationHelper::Strategies::StrategyInterface` (see `deprecation_helper` for more information).
+
+Note that by default, `ExplicitActiveRecord` uses the global configuration for `DeprecationHelper`. If your project has already configured `DeprecationHelper`, using:
+```ruby
+DeprecationHelper.configure { |config| config.deprecation_strategies = [...] })
+```
+then `ExplicitActiveRecord` will use the global configuration.
+
+### How it works
+When a client calls `my_model.save!` or `my_model.update!` without using the explicit persistence wrapper, `ExplicitActiveRecord::Persistence` will invoke `DeprecationHelper` with whatever deprecation strategies your model is configured with. 
+
+
+## ExplicitActiveRecord::NoDbAccess 
+`ExplicitActiveRecord::NoDbAccess` has a single public method to restrict the use of the database.
+
+Once your class or module is configured correctly to use `ExplicitActiveRecord::NoDbAccess`, you will not be able to use the database within the `no_db_access` block. 
+
+### Incremental
+Note that unlike `ExplicitActiveRecord::Persistence`, `ExplicitActiveRecord::NoDbAccess` is NOT *incremental*. This means that using the DB within one of these blocks *will raise*. If you're interested in allowing `no_db_access` to behave like `Persistence`, please file an issue. It is recommended to use `NoDbAccess` in new code where you are very confident your code should not be using the DB.
+
+### Usage 
+The first step is to `include ExplicitActiveRecord::NoDbAccess` in your module or class.
+
+Then, you can use the `no_db_access` block.
+
+All together, this looks like this:
+```ruby
+class MyClass # can also be a module
+  include ExplicitActiveRecord::NoDbAccess
+  
+  # Class method
+  def self.my_method
+    no_db_access do
+      # anything that does not use the DB
+    end
+  end
+
+  # Instance method
+  def my_method
+    self.class.no_db_access do
+      # anything that does not use the DB
+    end
+  end
+end
+```
+
+### How it works
+`NoDbAccess` uses `ActiveSupport::Notifications` to subscribe to the `sql.active_record` event. This ensures that any DB use via `ActiveRecord` is disallowed.
+
+# Why you want to use this gem, and why you don't
+
+There are several native Ruby and Rails features that can be used to match the intent of this gem. `ExplicitActiveRecord` is not a total substitute for these Ruby and Rails primitives, but rather they intend to create a safe way to migrate your codebase to use them.
+
+This gem adds some verbosity to the use of `ActiveRecord`. More importantly, Ruby offers native primitives for this sort of work. When creating a new rails project or rails engine, it is not recommended to use this gem. Instead, it is recommended to make use of `private_constant`, like this:
+```ruby
+module MyModule
+  class MyModel < ActiveRecord::Base
+  end
+
+  private_constant :MyModel
+end
+```
+
+Furthermore, I recommend not returning instances of `MyModel` when a call is made to the public API of `MyModule`. Instead, you can return a [value object](https://martinfowler.com/bliki/ValueObject.html). The important thing here is that by not returning instances of your model or letting unauthorized clients reference it, you can systematically and technically enforce the idea that your model is only persisted in one place.
+
+Another way to implement this idea using native Rails is by using [Multiple Databases with Active Record](https://guides.rubyonrails.org/active_record_multiple_databases.html). For example, for NoDbAccess, you can simply set up a null database in your application, and switch to it within your block.
+
+The reason this gem exists is because if your Rails project is like the ones I've seen, you are not doing this from the start. `ExplicitActiveRecord` is *not* a substitute for Ruby primitives like `private_constant` and conceptual primitives like value objects. Those primitives are the end goal, and this gem is just meant to provide a safe and incremental way to get you there.

data/lib/explicit_activerecord.rb

@@ -0,0 +1,8 @@
+require 'sorbet-runtime'
+require 'active_support/concern'
+require 'deprecation_helper'
+require 'explicit_activerecord/persistence'
+require 'explicit_activerecord/no_db_access'
+
+module ExplicitActiveRecord
+end

data/lib/explicit_activerecord/no_db_access.rb

@@ -0,0 +1,49 @@
+# typed: false
+
+# this is meant to allow callers to write code like this:
+#   model = MyModel.find
+#   no_db_access do
+#     (do things with model...)
+#   end
+#   model.save!
+# you are guaranteed that no database access will happen within the no_db_access block
+module ExplicitActiveRecord
+  module NoDBAccess
+    extend T::Sig
+
+    sig { returns(T::Boolean) }
+    def self.in_a_no_db_access_block?
+      (@pure_function_block_counter || 0) > 0
+    end
+
+    sig { void }
+    def self.no_db_access
+      unless @subscribed
+        ActiveSupport::Notifications.subscribe('sql.active_record') do |_name, _start, _finish, _id, _payload|
+          if NoDBAccess.in_a_no_db_access_block?
+            @should_raise = true
+          end
+        end
+        @subscribed = true
+      end
+
+      @pure_function_block_counter = (@pure_function_block_counter || 0) + 1
+      yield
+
+      if @should_raise
+        @should_raise = false
+        raise DbAccessError.new('Cannot execute sql within a no_db_access block.')
+      end
+    ensure
+      @should_raise = false
+      @pure_function_block_counter -= 1
+    end
+
+    sig { params(block: T.proc.void).void }
+    def no_db_access(&block)
+      NoDBAccess.no_db_access(&block)
+    end
+
+    class DbAccessError < StandardError; end
+  end
+end

data/lib/explicit_activerecord/persistence.rb

@@ -0,0 +1,133 @@
+# typed: false
+
+require 'sorbet-runtime'
+require 'active_support/concern'
+require 'deprecation_helper'
+
+module ExplicitActiveRecord
+  module Persistence
+    extend T::Sig
+
+    extend ActiveSupport::Concern
+
+    class UnrecognizedDangerousUpdateResponseBehaviorError < StandardError
+      extend T::Sig
+
+      sig { void }
+      def initialize
+        super 'Please provide a behavior that implements DeprecationHelper::Strategies::StrategyBase'
+      end
+    end
+
+    class InvalidInstanceOfClassError < ArgumentError
+      extend T::Sig
+
+      sig { params(klass: T.class_of(ActiveRecord::Base), instances: T::Array[ActiveRecord::Base]).void }
+      def initialize(klass, instances)
+        super "The provided instances of (#{instances.map(&:class).to_sentence}) are not an instance of the class (#{klass}) extending this concern."
+      end
+    end
+
+    included do |base|
+      extend T::Sig
+
+      before_save :ensure_explicitly_persisted!
+      before_destroy :ensure_explicitly_persisted!
+
+      base.class_eval do
+        sig { params(behaviors: T::Array[DeprecationHelper::Strategies::BaseStrategyInterface]).returns(T::Boolean) }
+        def self.dangerous_update_behaviors=(behaviors)
+          if behaviors.all? { |behavior| behavior.is_a?(DeprecationHelper::Strategies::BaseStrategyInterface) }
+            @dangerous_update_behaviors = behaviors
+            true
+          else
+            raise UnrecognizedDangerousUpdateResponseBehaviorError
+          end
+        end
+
+        sig { returns(T::Array[DeprecationHelper::Strategies::BaseStrategyInterface]) }
+        def self.dangerous_update_behaviors
+          # By default, `ExplicitActiveRecord` uses whatever the global configuration is for DeprecationHelper.
+          @dangerous_update_behaviors || DeprecationHelper.deprecation_strategies
+        end
+      end
+
+      sig { params(instance_or_instances: T.nilable(T.any(ActiveRecord::Base, T::Array[ActiveRecord::Base]))).returns(T.untyped) }
+      def self.with_explicit_persistence_for(instance_or_instances)
+        if instance_or_instances.present?
+          instances = Array.wrap(instance_or_instances)
+
+          invalid_instances = instances.select { |i| i.class != self }
+          if invalid_instances.any?
+            raise InvalidInstanceOfClassError.new(self, invalid_instances)
+          end
+
+          begin
+            instances.each { |model| PermissionStore.permit(model) }
+            ret = yield
+          ensure
+            instances.each { |model| PermissionStore.revoke(model) }
+          end
+
+          ret
+        else
+          yield
+        end
+      end
+
+      sig { returns(T.untyped) }
+      def can_be_dangerously_updated
+        @can_be_dangerously_updated
+      end
+
+      private
+
+      sig { returns(T.untyped) }
+      def ensure_explicitly_persisted!
+        return true if PermissionStore.permitted?(self)
+
+        DeprecationHelper.deprecate!(
+          "#{self.class.name} instances should only be persisted explicitly",
+          allow_list: ['bin/rails'],
+          deprecation_strategies: self.class.dangerous_update_behaviors,
+        )
+
+        true
+      end
+    end
+
+    # Note that this should probably be a `private_constant :PermissionStore`
+    # However, some clients are stubbing the methods here because the want to stub
+    # ExplicitActiveRecord in spec.
+    #
+    # TODO: Give a supported API for stubbing explicit persistence and then make this a private constant.
+    #
+    class PermissionStore
+      extend T::Sig
+
+      sig { params(model: ActiveRecord::Base).returns(Array) }
+      def self.permit(model)
+        self.storage.push(model)
+      end
+
+      sig { params(model: ActiveRecord::Base).returns(T.untyped) }
+      def self.revoke(model)
+        idx = self.storage.index(model)
+        self.storage.delete_at(idx) unless idx.nil?
+      end
+
+      sig { params(model: ActiveRecord::Base).returns(T::Boolean) }
+      def self.permitted?(model)
+        model.can_be_dangerously_updated || self.storage.include?(model)
+      end
+
+      sig { returns(Array) }
+      def self.storage
+        @storage ||= []
+      end
+
+      # don't need to construct this class, directly
+      private_class_method :new
+    end
+  end
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: explicit_activerecord
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alex Evanczuk
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-02-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.6293
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.6293
+- !ruby/object:Gem::Dependency
+  name: deprecation_helper
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.6293
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.6293
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- alex.evanczuk@gusto.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/explicit_activerecord.rb
+- lib/explicit_activerecord/no_db_access.rb
+- lib/explicit_activerecord/persistence.rb
+homepage: 
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: This is a gem for using ActiveRecord more explicitly.
+test_files: []