attribute_guard 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a485b9e0bc322539e0ac6b7014eb40824c4d94227fc216fab8add8a4f7a201fe
+  data.tar.gz: 792be937f2a9c6a611773d99c7e9f42c84546e3d1693046a4b7d3ab7b06d7097
+SHA512:
+  metadata.gz: 36e1b736350dba0238b811205629d6dd4e3b15ef12a60084cb56f78104d90e0cf1b2df797ef555e352e023678d7f838302a583769e876f967a4e9fa5d5306452
+  data.tar.gz: d961953fc003bfcbada924c84a07b24aaacbca72d1d14c06d1d148ef76d5fb0926a4ecac6999758a63761c85873bdabcf5d76c1eebfda1285cd299ef3ecf6a69

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 1.0.0 (unreleased)
+
+### Added
+- Initial release.

data/MIT-LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright 2023 Brian Durand
+
+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,164 @@
+# Active Record Attribute Guard
+
+[![Continuous Integration](https://github.com/bdurand/attribute_guard/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/attribute_guard/actions/workflows/continuous_integration.yml)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+
+This Ruby gem provides an extension for ActiveRecord allowing you to declare certain attributes in a model to be locked. Locked attributes cannot be changed once a record is created unless you explicitly allow changes.
+
+This feature can be used for a couple of different purposes.
+
+1. Preventing changes to data that should be immutable.
+2. Prevent direct data updates that bypass required business logic.
+
+## Usage
+
+### Declaring Locked Attributes
+
+To declare locked attributes you simply need to include the `AttributeGuard` module into your model and then list the attributes with the `lock_attributes` method.
+
+```ruby
+class MyModel < ApplicationRecord
+  include AttributeGuard
+
+  lock_attributes :created_by, :created_at
+end
+```
+
+Once that is done, if you try to change a locked value on an existing record, you will get a validation error.
+
+```ruby
+record = MyModel.last
+record.created_at = Time.now
+record.save! # => raises ActiveRecord::RecordInvalid
+```
+
+You can customize the validation error message by setting the value of the `errors.messages.locked` value in your i18n localization files. You can also specify an error message with the optional `error` keyword argument.
+
+```ruby
+class MyModel < ApplicationRecord
+  include AttributeGuard
+
+  lock_attributes :created_by, error: "cannot be changed except by an admin"
+end
+```
+
+### Unlocking Attributes
+
+You can allow changes to locked attributes with the `unlock_attributes` method.
+
+```ruby
+record = MyModel.last
+record.unlock_attributes(:created_at, :created_by)
+record.update!(created_at: Time.now, created_by: nil) # Changes are persisted
+```
+
+You can also supply a block to `unlock_attributes` which will clear any unlocked attributes when the block exits.
+
+```ruby
+record = MyModel.last
+record.unlock_attributes(:created_at) do
+  record.update!(created_at: Time.now) # Changes are persisted
+end
+
+record.update!(created_at: Time.now) # => raises ActiveRecord::RecordInvalid
+```
+
+The `unlock_attributes` method will return the record itself, so you can chain other instance methods off of it.
+
+```ruby
+record.unlock_attributes(:created_at).update!(created_at: Time.now)
+```
+
+### Using As A Guard
+
+You can use locked attributes as a guard to prevent direct updates to certain attributes and force changes to go through specific methods instead.
+
+For example, suppose we have some business logic that needs to execute whenever the `status` field is changed. You might wrap that logic up into a method or service object. For this example, suppose that we want to send some kind of alert any time the status is changed.
+
+```ruby
+class MyModel
+  def update_status(new_status)
+    update!(status: new_status)
+    StatusAlert.new(self).send_status_changed_alert
+  end
+end
+
+record = MyModel.last
+record.update_status("completed")
+```
+
+This has the risk, though, that you can still make direct updates to the `status` which would bypass the additional business logic.
+
+```ruby
+record = MyModel.last
+record.update!(status: "canceled") # StatusAlert method is not called.
+```
+
+You can prevent this by locking the `status` attribute and then unlocking it within the method that includes the required business logic.
+
+```ruby
+class MyModel
+  include AttributeGuard
+
+  lock_attributes :status
+
+  def update_status(new_status)
+    unlock_attributes(:status) do
+      update!(status: new_status)
+    end
+    StatusAlert.new(self).send_status_changed_alert
+  end
+end
+
+record = MyModel.last
+record.update_status("completed") # Status gets updated
+record.update!(status: "canceled") # raises ActiveRecord::RecordInvalid error
+```
+
+### Modes
+
+The default behavior when a locked attribute is changed is to add a validation error to the record. You can change this behavior with the `mode` option when locking attributes.
+
+```ruby
+class MyModel
+  include AttributeGuard
+
+  lock_attributes :email, mode: :error
+  lock_attributes :name: mode: :warn
+  lock_attributes :created_at, mode: ->(record, attribute) { raise "Created timestamp cannot be changed" }
+end
+```
+
+* `:error` - Add a validation error to the record. This is the default.
+
+* `:warn` - Log a warning that the record was changed. This mode is useful to allow you soft deploy locked attributes to production on a mature project and give you information about where you may need to update code to unlock attributes.
+
+* `Proc` - If you provide a `Proc` object, it will be called with the record and the attribute name when a locked attribute is changed.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "attribute_guard"
+```
+
+Then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install attribute_guard
+```
+
+## Contributing
+
+Open a pull request on [GitHub](https://github.com/bdurand/attribute_guard).
+
+Please use the [standardrb](https://github.com/testdouble/standard) syntax and lint your code with `standardrb --fix` before submitting.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/attribute_guard.gemspec

@@ -0,0 +1,37 @@
+Gem::Specification.new do |spec|
+  spec.name = "attribute_guard"
+  spec.version = File.read(File.expand_path("../VERSION", __FILE__)).strip
+  spec.authors = ["Brian Durand"]
+  spec.email = ["bbdurand@gmail.com"]
+
+  spec.summary = "ActiveRecord extension that allows locking attributes to prevent unintended updates."
+
+  spec.homepage = "https://github.com/bdurand/attribute_guard"
+  spec.license = "MIT"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  ignore_files = %w[
+    .
+    Appraisals
+    Gemfile
+    Gemfile.lock
+    Rakefile
+    config.ru
+    assets/
+    bin/
+    gemfiles/
+    spec/
+  ]
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| ignore_files.any? { |path| f.start_with?(path) } }
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.5"
+
+  spec.add_dependency "activerecord", ">= 5.0"
+
+  spec.add_development_dependency "bundler"
+end

data/lib/attribute_guard.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/lazy_load_hooks"
+require "active_model/validator"
+
+ActiveSupport.on_load(:i18n) do
+  I18n.load_path << File.expand_path("locale/en.yml", __dir__)
+end
+
+# Extension for ActiveRecord models that adds the capability to lock attributes to prevent direct
+# changes to them. This is useful for attributes that should only be changed through specific methods.
+#
+# @example
+#   class User < ActiveRecord::Base
+#     include AttributeGuard
+#
+#     lock_attributes :name, :email
+#   end
+#
+#   user = User.create!(name: "Test", email: "test@example")
+#   user.name = "Test 2"
+#   user.save! # => raises ActiveRecord::RecordInvalid
+#
+#   user.unlock_attributes(:name)
+#   user.name = "Test 2"
+#   user.save! # => saves successfully
+#
+#   user.unlock_attributes(:name) do
+#     user.name = "Test 3"
+#     user.save! # => saves successfully
+#   end
+#
+#   user.name = "Test 4"
+#   user.save! # => raises ActiveRecord::RecordInvalid
+module AttributeGuard
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :locked_attributes, default: {}, instance_accessor: false
+    private_class_method :locked_attributes=
+    private_class_method :locked_attributes
+
+    validates_with LockedAttributesValidator
+  end
+
+  # Validator that checks for changes to locked attributes.
+  class LockedAttributesValidator < ActiveModel::Validator
+    def validate(record)
+      return if record.new_record?
+
+      record.class.send(:locked_attributes).each do |attribute, params|
+        if record.changes.include?(attribute) && record.attribute_locked?(attribute)
+          message, mode = params
+          if mode == :warn
+            record&.logger&.warn("Changed locked attribute #{attribute} on #{record.class.name} with id #{record.id}")
+          elsif mode.is_a?(Proc)
+            mode.call(record, attribute)
+          else
+            record.errors.add(attribute, message)
+          end
+        end
+      end
+    end
+  end
+
+  module ClassMethods
+    # Locks the given attributes so that they cannot be changed directly. Subclasses inherit
+    # the locked attributes from their parent classes.
+    #
+    # You can optionally specify a mode of what to do when a locked attribute is changed. The
+    # default is to add an error to the model, but you can also specify :warn to log a warning
+    # or a Proc to call with the record and attribute name.
+    #
+    # @param attributes [Array<Symbol, String>] the attributes to lock
+    # @param error [String, Symbol, Boolean] the error message to use in validate errors
+    # @param mode [Symbol, Proc] mode to use when a locked attribute is changed
+    # @return [void]
+    def lock_attributes(*attributes, error: :locked, mode: :error)
+      locked = locked_attributes.dup
+      error = error.dup.freeze if error.is_a?(String)
+
+      attributes.flatten.each do |attribute|
+        locked[attribute.to_s] = [error, mode]
+      end
+
+      self.locked_attributes = locked
+    end
+
+    # Returns the names of the locked attributes.
+    #
+    # @return [Array<String>] the names of the locked attributes.
+    def locked_attribute_names
+      locked_attributes.keys
+    end
+  end
+
+  # Unlocks the given attributes so that they can be changed. If a block is given, the attributes
+  # are unlocked only for the duration of the block.
+  #
+  # This method returns the object itself so that it can be chained.
+  #
+  # @example
+  #   user.unlock_attributes(:email).update!(email: "user@example.com")
+  #
+  # @param attributes [Array<Symbol, String>] the attributes to unlock
+  # @return [ActiveRecord::Base] the object itself
+  def unlock_attributes(*attributes)
+    attributes = attributes.flatten.map(&:to_s)
+    return if attributes.empty?
+
+    @unlocked_attributes ||= Set.new
+    if block_given?
+      save_val = @unlocked_attributes
+      begin
+        @unlocked_attributes = @unlocked_attributes.dup.merge(attributes)
+        yield
+      ensure
+        @unlocked_attributes = save_val
+        clear_unlocked_attributes if @unlocked_attributes.empty?
+      end
+    else
+      @unlocked_attributes.merge(attributes)
+    end
+
+    self
+  end
+
+  # Returns true if the given attribute is currently locked.
+  #
+  # @param attribute [Symbol, String] the attribute to check
+  # @return [Boolean] whether the attribute is locked
+  def attribute_locked?(attribute)
+    return false if new_record?
+
+    attribute = attribute.to_s
+    return false unless self.class.send(:locked_attributes).include?(attribute)
+
+    if defined?(@unlocked_attributes)
+      !@unlocked_attributes.include?(attribute.to_s)
+    else
+      true
+    end
+  end
+
+  # Clears any unlocked attributes.
+  #
+  # @return [void]
+  def clear_unlocked_attributes
+    if defined?(@unlocked_attributes)
+      remove_instance_variable(:@unlocked_attributes)
+    end
+  end
+end

data/lib/locale/en.yml

@@ -0,0 +1,4 @@
+en:
+  errors:
+    messages:
+      locked: "is locked and cannot be changed"

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: attribute_guard
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Brian Durand
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-07-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  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:
+- bbdurand@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE.txt
+- README.md
+- VERSION
+- attribute_guard.gemspec
+- lib/attribute_guard.rb
+- lib/locale/en.yml
+homepage: https://github.com/bdurand/attribute_guard
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.12
+signing_key:
+specification_version: 4
+summary: ActiveRecord extension that allows locking attributes to prevent unintended
+  updates.
+test_files: []