activerecord 6.0.0 → 7.2.3

data/lib/active_record/delegated_type.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inquiry"
+
+module ActiveRecord
+  # = Delegated types
+  #
+  # Class hierarchies can map to relational database tables in many ways. Active Record, for example, offers
+  # purely abstract classes, where the superclass doesn't persist any attributes, and single-table inheritance,
+  # where all attributes from all levels of the hierarchy are represented in a single table. Both have their
+  # places, but neither are without their drawbacks.
+  #
+  # The problem with purely abstract classes is that all concrete subclasses must persist all the shared
+  # attributes themselves in their own tables (also known as class-table inheritance). This makes it hard to
+  # do queries across the hierarchy. For example, imagine you have the following hierarchy:
+  #
+  #   Entry < ApplicationRecord
+  #   Message < Entry
+  #   Comment < Entry
+  #
+  # How do you show a feed that has both +Message+ and +Comment+ records, which can be easily paginated?
+  # Well, you can't! Messages are backed by a messages table and comments by a comments table. You can't
+  # pull from both tables at once and use a consistent OFFSET/LIMIT scheme.
+  #
+  # You can get around the pagination problem by using single-table inheritance, but now you're forced into
+  # a single mega table with all the attributes from all subclasses. No matter how divergent. If a Message
+  # has a subject, but the comment does not, well, now the comment does anyway! So STI works best when there's
+  # little divergence between the subclasses and their attributes.
+  #
+  # But there's a third way: Delegated types. With this approach, the "superclass" is a concrete class
+  # that is represented by its own table, where all the superclass attributes that are shared amongst all the
+  # "subclasses" are stored. And then each of the subclasses have their own individual tables for additional
+  # attributes that are particular to their implementation. This is similar to what's called multi-table
+  # inheritance in Django, but instead of actual inheritance, this approach uses delegation to form the
+  # hierarchy and share responsibilities.
+  #
+  # Let's look at that entry/message/comment example using delegated types:
+  #
+  #   # Schema: entries[ id, account_id, creator_id, entryable_type, entryable_id, created_at, updated_at ]
+  #   class Entry < ApplicationRecord
+  #     belongs_to :account
+  #     belongs_to :creator
+  #     delegated_type :entryable, types: %w[ Message Comment ]
+  #   end
+  #
+  #   module Entryable
+  #     extend ActiveSupport::Concern
+  #
+  #     included do
+  #       has_one :entry, as: :entryable, touch: true
+  #     end
+  #   end
+  #
+  #   # Schema: messages[ id, subject, body, created_at, updated_at ]
+  #   class Message < ApplicationRecord
+  #     include Entryable
+  #   end
+  #
+  #   # Schema: comments[ id, content, created_at, updated_at ]
+  #   class Comment < ApplicationRecord
+  #     include Entryable
+  #   end
+  #
+  # As you can see, neither +Message+ nor +Comment+ are meant to stand alone. Crucial metadata for both classes
+  # resides in the +Entry+ "superclass". But the +Entry+ absolutely can stand alone in terms of querying capacity
+  # in particular. You can now easily do things like:
+  #
+  #   Account.find(1).entries.order(created_at: :desc).limit(50)
+  #
+  # Which is exactly what you want when displaying both comments and messages together. The entry itself can
+  # be rendered as its delegated type easily, like so:
+  #
+  #   # entries/_entry.html.erb
+  #   <%= render "entries/entryables/#{entry.entryable_name}", entry: entry %>
+  #
+  #   # entries/entryables/_message.html.erb
+  #   <div class="message">
+  #     <div class="subject"><%= entry.message.subject %></div>
+  #     <p><%= entry.message.body %></p>
+  #     <i>Posted on <%= entry.created_at %> by <%= entry.creator.name %></i>
+  #   </div>
+  #
+  #   # entries/entryables/_comment.html.erb
+  #   <div class="comment">
+  #     <%= entry.creator.name %> said: <%= entry.comment.content %>
+  #   </div>
+  #
+  # == Sharing behavior with concerns and controllers
+  #
+  # The entry "superclass" also serves as a perfect place to put all that shared logic that applies to both
+  # messages and comments, and which acts primarily on the shared attributes. Imagine:
+  #
+  #   class Entry < ApplicationRecord
+  #     include Eventable, Forwardable, Redeliverable
+  #   end
+  #
+  # Which allows you to have controllers for things like +ForwardsController+ and +RedeliverableController+
+  # that both act on entries, and thus provide the shared functionality to both messages and comments.
+  #
+  # == Creating new records
+  #
+  # You create a new record that uses delegated typing by creating the delegator and delegatee at the same time,
+  # like so:
+  #
+  #   Entry.create! entryable: Comment.new(content: "Hello!"), creator: Current.user, account: Current.account
+  #
+  # If you need more complicated composition, or you need to perform dependent validation, you should build a factory
+  # method or class to take care of the complicated needs. This could be as simple as:
+  #
+  #   class Entry < ApplicationRecord
+  #     def self.create_with_comment(content, creator: Current.user, account: Current.account)
+  #       create! entryable: Comment.new(content: content), creator: creator, account: account
+  #     end
+  #   end
+  #
+  # == Querying across records
+  #
+  # A consequence of delegated types is that querying attributes spread across multiple classes becomes slightly more
+  # tricky, but not impossible.
+  #
+  # The simplest method is to join the "superclass" to the "subclass" and apply the query parameters (i.e. <tt>#where</tt>)
+  # in appropriate places:
+  #
+  #   Comment.joins(:entry).where(comments: { content: 'Hello!' }, entry: { creator: Current.user } )
+  #
+  # For convenience, add a scope on the concern. Now all classes that implement the concern will automatically include
+  # the method:
+  #
+  #   # app/models/concerns/entryable.rb
+  #   scope :with_entry, ->(attrs) { joins(:entry).where(entry: attrs) }
+  #
+  # Now the query can be shortened significantly:
+  #
+  #   Comment.where(content: 'Hello!').with_entry(creator: Current.user)
+  #
+  # == Adding further delegation
+  #
+  # The delegated type shouldn't just answer the question of what the underlying class is called. In fact, that's
+  # an anti-pattern most of the time. The reason you're building this hierarchy is to take advantage of polymorphism.
+  # So here's a simple example of that:
+  #
+  #   class Entry < ApplicationRecord
+  #     delegated_type :entryable, types: %w[ Message Comment ]
+  #     delegate :title, to: :entryable
+  #   end
+  #
+  #   class Message < ApplicationRecord
+  #     def title
+  #       subject
+  #     end
+  #   end
+  #
+  #   class Comment < ApplicationRecord
+  #     def title
+  #       content.truncate(20)
+  #     end
+  #   end
+  #
+  # Now you can list a bunch of entries, call <tt>Entry#title</tt>, and polymorphism will provide you with the answer.
+  #
+  # == Nested \Attributes
+  #
+  # Enabling nested attributes on a delegated_type association allows you to
+  # create the entry and message in one go:
+  #
+  #   class Entry < ApplicationRecord
+  #     delegated_type :entryable, types: %w[ Message Comment ]
+  #     accepts_nested_attributes_for :entryable
+  #   end
+  #
+  #   params = { entry: { entryable_type: 'Message', entryable_attributes: { subject: 'Smiling' } } }
+  #   entry = Entry.create(params[:entry])
+  #   entry.entryable.id # => 2
+  #   entry.entryable.subject # => 'Smiling'
+  module DelegatedType
+    # Defines this as a class that'll delegate its type for the passed +role+ to the class references in +types+.
+    # That'll create a polymorphic +belongs_to+ relationship to that +role+, and it'll add all the delegated
+    # type convenience methods:
+    #
+    #   class Entry < ApplicationRecord
+    #     delegated_type :entryable, types: %w[ Message Comment ], dependent: :destroy
+    #   end
+    #
+    #   @entry.entryable_class # => Message or Comment
+    #   @entry.entryable_name  # => "message" or "comment"
+    #   Entry.messages         # => Entry.where(entryable_type: "Message")
+    #   @entry.message?        # => true when entryable_type == "Message"
+    #   @entry.message         # => returns the message record, when entryable_type == "Message", otherwise nil
+    #   @entry.message_id      # => returns entryable_id, when entryable_type == "Message", otherwise nil
+    #   Entry.comments         # => Entry.where(entryable_type: "Comment")
+    #   @entry.comment?        # => true when entryable_type == "Comment"
+    #   @entry.comment         # => returns the comment record, when entryable_type == "Comment", otherwise nil
+    #   @entry.comment_id      # => returns entryable_id, when entryable_type == "Comment", otherwise nil
+    #
+    # You can also declare namespaced types:
+    #
+    #   class Entry < ApplicationRecord
+    #     delegated_type :entryable, types: %w[ Message Comment Access::NoticeMessage ], dependent: :destroy
+    #   end
+    #
+    #   Entry.access_notice_messages
+    #   @entry.access_notice_message
+    #   @entry.access_notice_message?
+    #
+    # ==== Options
+    #
+    # The +options+ are passed directly to the +belongs_to+ call, so this is where you declare +dependent+ etc.
+    # The following options can be included to specialize the behavior of the delegated type convenience methods.
+    #
+    # [+:foreign_key+]
+    #   Specify the foreign key used for the convenience methods. By default this is guessed to be the passed
+    #   +role+ with an "_id" suffix. So a class that defines a
+    #   <tt>delegated_type :entryable, types: %w[ Message Comment ]</tt> association will use "entryable_id" as
+    #   the default <tt>:foreign_key</tt>.
+    # [+:foreign_type+]
+    #   Specify the column used to store the associated object's type. By default this is inferred to be the passed
+    #   +role+ with a "_type" suffix. A class that defines a
+    #   <tt>delegated_type :entryable, types: %w[ Message Comment ]</tt> association will use "entryable_type" as
+    #   the default <tt>:foreign_type</tt>.
+    # [+:primary_key+]
+    #   Specify the method that returns the primary key of associated object used for the convenience methods.
+    #   By default this is +id+.
+    #
+    # Option examples:
+    #   class Entry < ApplicationRecord
+    #     delegated_type :entryable, types: %w[ Message Comment ], primary_key: :uuid, foreign_key: :entryable_uuid
+    #   end
+    #
+    #   @entry.message_uuid # => returns entryable_uuid, when entryable_type == "Message", otherwise nil
+    #   @entry.comment_uuid # => returns entryable_uuid, when entryable_type == "Comment", otherwise nil
+    def delegated_type(role, types:, **options)
+      belongs_to role, options.delete(:scope), **options.merge(polymorphic: true)
+      define_delegated_type_methods role, types: types, options: options
+    end
+
+    private
+      def define_delegated_type_methods(role, types:, options:)
+        primary_key = options[:primary_key] || "id"
+        role_type = options[:foreign_type] || "#{role}_type"
+        role_id   = options[:foreign_key] || "#{role}_id"
+
+        define_singleton_method "#{role}_types" do
+          types.map(&:to_s)
+        end
+
+        define_method "#{role}_class" do
+          public_send(role_type).constantize
+        end
+
+        define_method "#{role}_name" do
+          public_send("#{role}_class").model_name.singular.inquiry
+        end
+
+        define_method "build_#{role}" do |*params|
+          public_send("#{role}=", public_send("#{role}_class").new(*params))
+        end
+
+        types.each do |type|
+          scope_name = type.tableize.tr("/", "_")
+          singular   = scope_name.singularize
+          query      = "#{singular}?"
+
+          scope scope_name, -> { where(role_type => type) }
+
+          define_method query do
+            public_send(role_type) == type
+          end
+
+          define_method singular do
+            public_send(role) if public_send(query)
+          end
+
+          define_method "#{singular}_#{primary_key}" do
+            public_send(role_id) if public_send(query)
+          end
+        end
+      end
+  end
+end

data/lib/active_record/deprecator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  def self.deprecator # :nodoc:
+    @deprecator ||= ActiveSupport::Deprecation.new
+  end
+end

data/lib/active_record/destroy_association_async_job.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  class DestroyAssociationAsyncError < StandardError
+  end
+
+  # = Active Record Destroy Association Async Job
+  #
+  # Job to destroy the records associated with a destroyed record in background.
+  class DestroyAssociationAsyncJob < ActiveJob::Base
+    queue_as { ActiveRecord.queues[:destroy] }
+
+    discard_on ActiveJob::DeserializationError
+
+    def perform(
+      owner_model_name: nil, owner_id: nil,
+      association_class: nil, association_ids: nil, association_primary_key_column: nil,
+      ensuring_owner_was_method: nil
+    )
+      association_model = association_class.constantize
+      owner_class = owner_model_name.constantize
+      owner = owner_class.find_by(owner_class.primary_key => [owner_id])
+
+      if !owner_destroyed?(owner, ensuring_owner_was_method)
+        raise DestroyAssociationAsyncError, "owner record not destroyed"
+      end
+
+      association_model.where(association_primary_key_column => association_ids).find_each do |r|
+        r.destroy
+      end
+    end
+
+    private
+      def owner_destroyed?(owner, ensuring_owner_was_method)
+        !owner || (ensuring_owner_was_method && owner.public_send(ensuring_owner_was_method))
+      end
+  end
+end

data/lib/active_record/disable_joins_association_relation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  class DisableJoinsAssociationRelation < Relation # :nodoc:
+    attr_reader :ids, :key
+
+    def initialize(klass, key, ids)
+      @ids = ids.uniq
+      @key = key
+      super(klass)
+    end
+
+    def limit(value)
+      records.take(value)
+    end
+
+    def first(limit = nil)
+      if limit
+        records.limit(limit).first
+      else
+        records.first
+      end
+    end
+
+    def load
+      super
+      records = @records
+
+      records_by_id = records.group_by do |record|
+        record[key]
+      end
+
+      records = ids.flat_map { |id| records_by_id[id] }
+      records.compact!
+
+      @records = records
+    end
+  end
+end

data/lib/active_record/dynamic_matchers.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveRecord
-  module DynamicMatchers #:nodoc:
+  module DynamicMatchers # :nodoc:
     private
       def respond_to_missing?(name, _)
         if self == Base
@@ -12,12 +12,12 @@ module ActiveRecord
         end
       end
 
-      def method_missing(name, *arguments, &block)
+      def method_missing(name, ...)
         match = Method.match(self, name)
 
         if match && match.valid?
           match.define
-          send(name, *arguments, &block)
+          send(name, ...)
         else
           super
         end
@@ -49,9 +49,9 @@ module ActiveRecord
 
         attr_reader :model, :name, :attribute_names
 
-        def initialize(model, name)
+        def initialize(model, method_name)
           @model           = model
-          @name            = name.to_s
+          @name            = method_name.to_s
           @attribute_names = @name.match(self.class.pattern)[1].split("_and_")
           @attribute_names.map! { |name| @model.attribute_aliases[name] || name }
         end
@@ -69,7 +69,6 @@ module ActiveRecord
         end
 
         private
-
           def body
             "#{finder}(#{attributes_hash})"
           end

data/lib/active_record/encryption/auto_filtered_parameters.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    class AutoFilteredParameters
+      def initialize(app)
+        @app = app
+        @attributes_by_class = Concurrent::Map.new
+        @collecting = true
+
+        install_collecting_hook
+      end
+
+      def enable
+        apply_collected_attributes
+        @collecting = false
+      end
+
+      private
+        attr_reader :app
+
+        def install_collecting_hook
+          ActiveRecord::Encryption.on_encrypted_attribute_declared do |klass, attribute|
+            attribute_was_declared(klass, attribute)
+          end
+        end
+
+        def attribute_was_declared(klass, attribute)
+          if collecting?
+            collect_for_later(klass, attribute)
+          else
+            apply_filter(klass, attribute)
+          end
+        end
+
+        def apply_collected_attributes
+          @attributes_by_class.each do |klass, attributes|
+            attributes.each do |attribute|
+              apply_filter(klass, attribute)
+            end
+          end
+        end
+
+        def collecting?
+          @collecting
+        end
+
+        def collect_for_later(klass, attribute)
+          @attributes_by_class[klass] ||= Concurrent::Array.new
+          @attributes_by_class[klass] << attribute
+        end
+
+        def apply_filter(klass, attribute)
+          filter = [("#{klass.model_name.element}" if klass.name), attribute.to_s].compact.join(".")
+          unless excluded_from_filter_parameters?(filter)
+            app.config.filter_parameters << filter unless app.config.filter_parameters.include?(filter)
+            klass.filter_attributes += [ attribute ]
+          end
+        end
+
+        def excluded_from_filter_parameters?(filter_parameter)
+          ActiveRecord::Encryption.config.excluded_from_filter_parameters.find { |excluded_filter| excluded_filter.to_s == filter_parameter }
+        end
+    end
+  end
+end

data/lib/active_record/encryption/cipher/aes256_gcm.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module ActiveRecord
+  module Encryption
+    class Cipher
+      # A 256-GCM cipher.
+      #
+      # By default it will use random initialization vectors. For deterministic encryption, it will use a SHA-256 hash of
+      # the text to encrypt and the secret.
+      #
+      # See +Encryptor+
+      class Aes256Gcm
+        CIPHER_TYPE = "aes-256-gcm"
+
+        class << self
+          def key_length
+            OpenSSL::Cipher.new(CIPHER_TYPE).key_len
+          end
+
+          def iv_length
+            OpenSSL::Cipher.new(CIPHER_TYPE).iv_len
+          end
+        end
+
+        # When iv not provided, it will generate a random iv on each encryption operation (default and
+        # recommended operation)
+        def initialize(secret, deterministic: false)
+          @secret = secret
+          @deterministic = deterministic
+        end
+
+        def encrypt(clear_text)
+          # This code is extracted from +ActiveSupport::MessageEncryptor+. Not using it directly because we want to control
+          # the message format and only serialize things once at the +ActiveRecord::Encryption::Message+ level. Also, this
+          # cipher is prepared to deal with deterministic/non deterministic encryption modes.
+
+          cipher = OpenSSL::Cipher.new(CIPHER_TYPE)
+          cipher.encrypt
+          cipher.key = @secret
+
+          iv = generate_iv(cipher, clear_text)
+          cipher.iv = iv
+
+          encrypted_data = clear_text.empty? ? clear_text.dup : cipher.update(clear_text)
+          encrypted_data << cipher.final
+
+          ActiveRecord::Encryption::Message.new(payload: encrypted_data).tap do |message|
+            message.headers.iv = iv
+            message.headers.auth_tag = cipher.auth_tag
+          end
+        end
+
+        def decrypt(encrypted_message)
+          encrypted_data = encrypted_message.payload
+          iv = encrypted_message.headers.iv
+          auth_tag = encrypted_message.headers.auth_tag
+
+          # Currently the OpenSSL bindings do not raise an error if auth_tag is
+          # truncated, which would allow an attacker to easily forge it. See
+          # https://github.com/ruby/openssl/issues/63
+          raise ActiveRecord::Encryption::Errors::EncryptedContentIntegrity if auth_tag.nil? || auth_tag.bytes.length != 16
+
+          cipher = OpenSSL::Cipher.new(CIPHER_TYPE)
+
+          cipher.decrypt
+          cipher.key = @secret
+          cipher.iv = iv
+
+          cipher.auth_tag = auth_tag
+          cipher.auth_data = ""
+
+          decrypted_data = encrypted_data.empty? ? encrypted_data : cipher.update(encrypted_data)
+          decrypted_data << cipher.final
+
+          decrypted_data
+        rescue OpenSSL::Cipher::CipherError, TypeError, ArgumentError
+          raise ActiveRecord::Encryption::Errors::Decryption
+        end
+
+        def inspect # :nodoc:
+          "#<#{self.class.name}:#{'%#016x' % (object_id << 1)}>"
+        end
+
+        private
+          def generate_iv(cipher, clear_text)
+            if @deterministic
+              generate_deterministic_iv(clear_text)
+            else
+              cipher.random_iv
+            end
+          end
+
+          def generate_deterministic_iv(clear_text)
+            OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, @secret, clear_text)[0, ActiveRecord::Encryption.cipher.iv_length]
+          end
+      end
+    end
+  end
+end

data/lib/active_record/encryption/cipher.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    # The algorithm used for encrypting and decrypting +Message+ objects.
+    #
+    # It uses AES-256-GCM. It will generate a random IV for non deterministic encryption (default)
+    # or derive an initialization vector from the encrypted content for deterministic encryption.
+    #
+    # See +Cipher::Aes256Gcm+.
+    class Cipher
+      DEFAULT_ENCODING = Encoding::UTF_8
+
+      # Encrypts the provided text and return an encrypted +Message+.
+      def encrypt(clean_text, key:, deterministic: false)
+        cipher_for(key, deterministic: deterministic).encrypt(clean_text).tap do |message|
+          message.headers.encoding = clean_text.encoding.name unless clean_text.encoding == DEFAULT_ENCODING
+        end
+      end
+
+      # Decrypt the provided +Message+.
+      #
+      # When +key+ is an Array, it will try all the keys raising a
+      # +ActiveRecord::Encryption::Errors::Decryption+ if none works.
+      def decrypt(encrypted_message, key:)
+        try_to_decrypt_with_each(encrypted_message, keys: Array(key)).tap do |decrypted_text|
+          decrypted_text.force_encoding(encrypted_message.headers.encoding || DEFAULT_ENCODING)
+        end
+      end
+
+      def key_length
+        Aes256Gcm.key_length
+      end
+
+      def iv_length
+        Aes256Gcm.iv_length
+      end
+
+      private
+        def try_to_decrypt_with_each(encrypted_text, keys:)
+          keys.each.with_index do |key, index|
+            return cipher_for(key).decrypt(encrypted_text)
+          rescue ActiveRecord::Encryption::Errors::Decryption
+            raise if index == keys.length - 1
+          end
+        end
+
+        def cipher_for(secret, deterministic: false)
+          Aes256Gcm.new(secret, deterministic: deterministic)
+        end
+    end
+  end
+end