globalid 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52c4368f15fc8952c9d79189ed9a78e649e0142421721aef338625c19b24c3b9
-  data.tar.gz: 4d6d1c379d45ccaf5761488c540d19cac9d0488b578564964edd88c52073c511
+  metadata.gz: 15140d3d09fd236ea096c178a473440eb3d2fab55503978d646f3f13a863589c
+  data.tar.gz: 65351562c30c6c4e68d5b21ac8a502a7f7f5c8995cf538844395d123c685afba
 SHA512:
-  metadata.gz: 49ff5a4b4d4f68afdffa67a85b5aebfb3b2f518257ffec22be8a60a29ac5596a67552aae46bebab28a4fe6b37a5802ac520b0f567098617110b2f54c4a74cfcb
-  data.tar.gz: f6ba35dc2c080b0c996bd4529cec1438a35545c693cc0271e25c6b7bdaa8f759de61f26ae6ecf16487d89c7e6e5afc41caab7114541cd8a54ebdf9e2a3ce1f60
+  metadata.gz: b2a642776d9233ad70854e49b1dde8287397b94321a158747abc6738c4a976a4bb93a5de9fa72d8e3f7792a5667cc01eb938200b0fb8da675bce28af8488c93d
+  data.tar.gz: c390cbaf842ce68dfd97e4a6d94ae40f9b83fa694ee5931975d96d1b8bd4c8795fbb308a12d3e0ba54f5e8b87d16229a665abe86aa9d00ec0e5e98bb5777ad23

data/README.md

@@ -161,6 +161,25 @@ GlobalID::Locator.locate_many gids
 
 Note the order is maintained in the returned results.
 
+### Options
+
+Either `GlobalID::Locator.locate` or `GlobalID::Locator.locate_many` supports a hash of options as second parameter. The supported options are:
+
+* :includes - A Symbol, Array, Hash or combination of them
+  The same structure you would pass into a `includes` method of Active Record.
+  See [Active Record eager loading associations](https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations)
+  If present, `locate` or `locate_many` will eager load all the relationships specified here.
+  Note: It only works if all the gids models have that relationships.
+* :only - A class, module or Array of classes and/or modules that are
+  allowed to be located.  Passing one or more classes limits instances of returned
+  classes to those classes or their subclasses.  Passing one or more modules in limits
+  instances of returned classes to those including that module.  If no classes or
+  modules match, +nil+ is returned.
+* :ignore_missing (Only for `locate_many`) - By default, `locate_many` will call `#find` on the model to locate the
+  ids extracted from the GIDs. In Active Record (and other data stores following the same pattern),
+  `#find` will raise an exception if a named ID can't be found. When you set this option to true,
+  we will use `#where(id: ids)` instead, which does not raise on missing records.
+
 ### Custom App Locator
 
 A custom locator can be set for an app by calling `GlobalID::Locator.use` and providing an app locator to use for that app.
@@ -172,7 +191,7 @@ A custom locator can either be a block or a class.
 Using a block:
 
 ```ruby
-GlobalID::Locator.use :foo do |gid|
+GlobalID::Locator.use :foo do |gid, options|
   FooRemote.const_get(gid.model_name).find(gid.model_id)
 end
 ```
@@ -182,7 +201,7 @@ Using a class:
 ```ruby
 GlobalID::Locator.use :bar, BarLocator.new
 class BarLocator
-  def locate(gid)
+  def locate(gid, options = {})
     @search_client.search name: gid.model_name, id: gid.model_id
   end
 end

data/lib/global_id/global_id.rb

@@ -50,12 +50,13 @@ class GlobalID
   end
 
   def model_class
-    model = model_name.constantize
+    @model_class ||= begin
+      model = model_name.constantize
 
-    unless model <= GlobalID
+      if model <= GlobalID
+        raise ArgumentError, "GlobalID and SignedGlobalID cannot be used as model_class."
+      end
       model
-    else
-      raise ArgumentError, "GlobalID and SignedGlobalID cannot be used as model_class."
     end
   end
 

data/lib/global_id/identification.rb

@@ -1,19 +1,118 @@
 class GlobalID
+  # Mix `GlobalID::Identification` into any model with a `#find(id)` class
+  # method. Support is automatically included in Active Record.
+  #
+  #   class Person
+  #     include ActiveModel::Model
+  #     include GlobalID::Identification
+  #
+  #     attr_accessor :id
+  #
+  #     def self.find(id)
+  #       new id: id
+  #     end
+  #
+  #     def ==(other)
+  #       id == other.try(:id)
+  #     end
+  #   end
+  #
+  #   person_gid = Person.find(1).to_global_id
+  #   # => #<GlobalID ...
+  #   person_gid.uri
+  #   # => #<URI ...
+  #   person_gid.to_s
+  #   # => "gid://app/Person/1"
+  #   GlobalID::Locator.locate person_gid
+  #   # => #<Person:0x007fae94bf6298 @id="1">
   module Identification
+
+    # Returns the Global ID of the model.
+    #
+    #   model = Person.new id: 1
+    #   global_id = model.to_global_id
+    #   global_id.modal_class # => Person
+    #   global_id.modal_id # => "1"
+    #   global_id.to_param # => "Z2lkOi8vYm9yZGZvbGlvL1BlcnNvbi8x"
     def to_global_id(options = {})
       GlobalID.create(self, options)
     end
     alias to_gid to_global_id
 
+    # Returns the Global ID parameter of the model.
+    #
+    #   model = Person.new id: 1
+    #   model.to_gid_param # => ""Z2lkOi8vYm9yZGZvbGlvL1BlcnNvbi8x"
     def to_gid_param(options = {})
       to_global_id(options).to_param
     end
 
+    # Returns the Signed Global ID of the model.
+    # Signed Global IDs ensure that the data hasn't been tampered with.
+    #
+    #   model = Person.new id: 1
+    #   signed_global_id = model.to_signed_global_id
+    #   signed_global_id.modal_class # => Person
+    #   signed_global_id.modal_id # => "1"
+    #   signed_global_id.to_param # => "BAh7CEkiCGdpZAY6BkVUSSIiZ2..."
+    #
+    # ==== Expiration
+    #
+    # Signed Global IDs can expire some time in the future. This is useful if
+    # there's a resource people shouldn't have indefinite access to, like a
+    # share link.
+    #
+    #   expiring_sgid = Document.find(5).to_sgid(expires_in: 2.hours, for: 'sharing')
+    #   # => #<SignedGlobalID:0x008fde45df8937 ...>
+    #   # Within 2 hours...
+    #   GlobalID::Locator.locate_signed(expiring_sgid.to_s, for: 'sharing')
+    #   # => #<Document:0x007fae94bf6298 @id="5">
+    #   # More than 2 hours later...
+    #   GlobalID::Locator.locate_signed(expiring_sgid.to_s, for: 'sharing')
+    #   # => nil
+    #
+    # In Rails, an auto-expiry of 1 month is set by default.
+    #
+    # You need to explicitly pass `expires_in: nil` to generate a permanent
+    # SGID that will not expire,
+    #
+    #   never_expiring_sgid = Document.find(5).to_sgid(expires_in: nil)
+    #   # => #<SignedGlobalID:0x008fde45df8937 ...>
+    #
+    #   # Any time later...
+    #   GlobalID::Locator.locate_signed never_expiring_sgid
+    #   # => #<Document:0x007fae94bf6298 @id="5">
+    #
+    # It's also possible to pass a specific expiry time
+    #
+    #   explicit_expiring_sgid = SecretAgentMessage.find(5).to_sgid(expires_at: Time.now.advance(hours: 1))
+    #   # => #<SignedGlobalID:0x008fde45df8937 ...>
+    #
+    #   # 1 hour later...
+    #   GlobalID::Locator.locate_signed explicit_expiring_sgid.to_s
+    #   # => nil
+    #
+    # Note that an explicit `:expires_at` takes precedence over a relative `:expires_in`.
+    #
+    # ==== Purpose
+    #
+    # You can even bump the security up some more by explaining what purpose a
+    # Signed Global ID is for. In this way evildoers can't reuse a sign-up
+    # form's SGID on the login page. For example.
+    #
+    #   signup_person_sgid = Person.find(1).to_sgid(for: 'signup_form')
+    #   # => #<SignedGlobalID:0x007fea1984b520
+    #   GlobalID::Locator.locate_signed(signup_person_sgid.to_s, for: 'signup_form')
+    #   => #<Person:0x007fae94bf6298 @id="1">
     def to_signed_global_id(options = {})
       SignedGlobalID.create(self, options)
     end
     alias to_sgid to_signed_global_id
 
+    # Returns the Signed Global ID parameter.
+    #
+    #   model = Person.new id: 1
+    #   model.to_sgid_param # => "BAh7CEkiCGdpZAY6BkVUSSIiZ2..."
     def to_sgid_param(options = {})
       to_signed_global_id(options).to_param
     end

data/lib/global_id/locator.rb

@@ -2,18 +2,33 @@ require 'active_support/core_ext/enumerable' # For Enumerable#index_by
 
 class GlobalID
   module Locator
+    class InvalidModelIdError < StandardError; end
+
     class << self
       # Takes either a GlobalID or a string that can be turned into a GlobalID
       #
       # Options:
+      # * <tt>:includes</tt> - A Symbol, Array, Hash or combination of them.
+      #   The same structure you would pass into a +includes+ method of Active Record.
+      #   If present, locate will load all the relationships specified here.
+      #   See https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations.
       # * <tt>:only</tt> - A class, module or Array of classes and/or modules that are
       #   allowed to be located.  Passing one or more classes limits instances of returned
       #   classes to those classes or their subclasses.  Passing one or more modules in limits
       #   instances of returned classes to those including that module.  If no classes or
       #   modules match, +nil+ is returned.
       def locate(gid, options = {})
-        if gid = GlobalID.parse(gid)
-          locator_for(gid).locate gid if find_allowed?(gid.model_class, options[:only])
+        gid = GlobalID.parse(gid)
+
+        return unless gid && find_allowed?(gid.model_class, options[:only])
+
+        locator = locator_for(gid)
+
+        if locator.method(:locate).arity == 1
+          GlobalID.deprecator.warn "It seems your locator is defining the `locate` method only with one argument. Please make sure your locator is receiving the options argument as well, like `locate(gid, options = {})`."
+          locator.locate(gid)
+        else
+          locator.locate(gid, options.except(:only))
         end
       end
 
@@ -28,6 +43,11 @@ class GlobalID
       # per model class, but still interpolate the results to match the order in which the gids were passed.
       #
       # Options:
+      # * <tt>:includes</tt> - A Symbol, Array, Hash or combination of them
+      #   The same structure you would pass into a includes method of Active Record.
+      #   @see https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations
+      #   If present, locate_many will load all the relationships specified here.
+      #   Note: It only works if all the gids models have that relationships.
       # * <tt>:only</tt> - A class, module or Array of classes and/or modules that are
       #   allowed to be located.  Passing one or more classes limits instances of returned
       #   classes to those classes or their subclasses.  Passing one or more modules in limits
@@ -49,6 +69,10 @@ class GlobalID
       # Takes either a SignedGlobalID or a string that can be turned into a SignedGlobalID
       #
       # Options:
+      # * <tt>:includes</tt> - A Symbol, Array, Hash or combination of them
+      #   The same structure you would pass into a includes method of Active Record.
+      #   @see https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations
+      #   If present, locate_signed will load all the relationships specified here.
       # * <tt>:only</tt> - A class, module or Array of classes and/or modules that are
       #   allowed to be located.  Passing one or more classes limits instances of returned
       #   classes to those classes or their subclasses.  Passing one or more modules in limits
@@ -66,6 +90,11 @@ class GlobalID
       # the results to match the order in which the gids were passed.
       #
       # Options:
+      # * <tt>:includes</tt> - A Symbol, Array, Hash or combination of them
+      #   The same structure you would pass into a includes method of Active Record.
+      #   @see https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations
+      #   If present, locate_many_signed will load all the relationships specified here.
+      #   Note: It only works if all the gids models have that relationships.
       # * <tt>:only</tt> - A class, module or Array of classes and/or modules that are
       #   allowed to be located.  Passing one or more classes limits instances of returned
       #   classes to those classes or their subclasses.  Passing one or more modules in limits
@@ -82,7 +111,7 @@ class GlobalID
       #
       # Using a block:
       #
-      #   GlobalID::Locator.use :foo do |gid|
+      #   GlobalID::Locator.use :foo do |gid, options|
       #     FooRemote.const_get(gid.model_name).find(gid.model_id)
       #   end
       #
@@ -91,7 +120,7 @@ class GlobalID
       #   GlobalID::Locator.use :bar, BarLocator.new
       #
       #   class BarLocator
-      #     def locate(gid)
+      #     def locate(gid, options = {})
       #       @search_client.search name: gid.model_name, id: gid.model_id
       #     end
       #   end
@@ -125,32 +154,55 @@ class GlobalID
       @locators = {}
 
       class BaseLocator
-        def locate(gid)
-          gid.model_class.find gid.model_id
+        def locate(gid, options = {})
+          return unless model_id_is_valid?(gid)
+          model_class = gid.model_class
+          model_class = model_class.includes(options[:includes]) if options[:includes]
+
+          model_class.find gid.model_id
         end
 
         def locate_many(gids, options = {})
-          models_and_ids  = gids.collect { |gid| [ gid.model_class, gid.model_id ] }
-          ids_by_model    = models_and_ids.group_by(&:first)
-          loaded_by_model = Hash[ids_by_model.map { |model, ids|
-            [ model, find_records(model, ids.map(&:last), ignore_missing: options[:ignore_missing]).index_by { |record| record.id.to_s } ]
-          }]
+          ids_by_model = Hash.new { |hash, key| hash[key] = [] }
+
+          gids.each do |gid|
+            next unless model_id_is_valid?(gid)
+            ids_by_model[gid.model_class] << gid.model_id
+          end
+
+          records_by_model_name_and_id = {}
 
-          models_and_ids.collect { |(model, id)| loaded_by_model[model][id] }.compact
+          ids_by_model.each do |model, ids|
+            records = find_records(model, ids, ignore_missing: options[:ignore_missing], includes: options[:includes])
+
+            records_by_id = records.index_by do |record|
+              record.id.is_a?(Array) ? record.id.map(&:to_s) : record.id.to_s
+            end
+
+            records_by_model_name_and_id[model.name] = records_by_id
+          end
+
+          gids.filter_map { |gid| records_by_model_name_and_id[gid.model_name][gid.model_id] }
         end
 
         private
           def find_records(model_class, ids, options)
+            model_class = model_class.includes(options[:includes]) if options[:includes]
+
             if options[:ignore_missing]
-              model_class.where(id: ids)
+              model_class.where(model_class.primary_key => ids)
             else
               model_class.find(ids)
             end
           end
+
+          def model_id_is_valid?(gid)
+            Array(gid.model_id).size == Array(gid.model_class.primary_key).size
+          end
       end
 
       class UnscopedLocator < BaseLocator
-        def locate(gid)
+        def locate(gid, options = {})
           unscoped(gid.model_class) { super }
         end
 
@@ -174,12 +226,12 @@ class GlobalID
           @locator = block
         end
 
-        def locate(gid)
-          @locator.call(gid)
+        def locate(gid, options = {})
+          @locator.call(gid, options)
         end
 
         def locate_many(gids, options = {})
-          gids.map { |gid| locate(gid) }
+          gids.map { |gid| locate(gid, options) }
         end
       end
   end

data/lib/global_id/railtie.rb

@@ -42,6 +42,10 @@ class GlobalID
         send :extend, GlobalID::FixtureSet
       end
     end
+
+    initializer "web_console.deprecator" do |app|
+      app.deprecators[:global_id] = GlobalID.deprecator if app.respond_to?(:deprecators)
+    end
   end
 end
 

data/lib/global_id/signed_global_id.rb

@@ -5,7 +5,7 @@ class SignedGlobalID < GlobalID
   class ExpiredMessage < StandardError; end
 
   class << self
-    attr_accessor :verifier
+    attr_accessor :verifier, :expires_in
 
     def parse(sgid, options = {})
       super verify(sgid.to_s, options), options
@@ -19,8 +19,6 @@ class SignedGlobalID < GlobalID
       end
     end
 
-    attr_accessor :expires_in
-
     DEFAULT_PURPOSE = "default"
 
     def pick_purpose(options)
@@ -29,11 +27,22 @@ class SignedGlobalID < GlobalID
 
     private
       def verify(sgid, options)
+        verify_with_verifier_validated_metadata(sgid, options) ||
+          verify_with_legacy_self_validated_metadata(sgid, options)
+      end
+
+      def verify_with_verifier_validated_metadata(sgid, options)
+        pick_verifier(options).verify(sgid, purpose: pick_purpose(options))
+      rescue ActiveSupport::MessageVerifier::InvalidSignature
+        nil
+      end
+
+      def verify_with_legacy_self_validated_metadata(sgid, options)
         metadata = pick_verifier(options).verify(sgid)
 
         raise_if_expired(metadata['expires_at'])
 
-        metadata['gid'] if pick_purpose(options) == metadata['purpose']
+        metadata['gid'] if pick_purpose(options)&.to_s == metadata['purpose']&.to_s
       rescue ActiveSupport::MessageVerifier::InvalidSignature, ExpiredMessage
         nil
       end
@@ -55,25 +64,19 @@ class SignedGlobalID < GlobalID
   end
 
   def to_s
-    @sgid ||= @verifier.generate(to_h)
+    @sgid ||= @verifier.generate(@uri.to_s, purpose: purpose, expires_at: expires_at)
   end
   alias to_param to_s
 
-  def to_h
-    # Some serializers decodes symbol keys to symbols, others to strings.
-    # Using string keys remedies that.
-    { 'gid' => @uri.to_s, 'purpose' => purpose, 'expires_at' => encoded_expiration }
-  end
-
   def ==(other)
     super && @purpose == other.purpose
   end
 
-  private
-    def encoded_expiration
-      expires_at.utc.iso8601(3) if expires_at
-    end
+  def inspect # :nodoc:
+    "#<#{self.class.name}:#{'%#016x' % (object_id << 1)}>"
+  end
 
+  private
     def pick_expiration(options)
       return options[:expires_at] if options.key?(:expires_at)
 

data/lib/global_id/uri/gid.rb

@@ -30,6 +30,11 @@ module URI
 
     # Raised when creating a Global ID for a model without an id
     class MissingModelIdError < URI::InvalidComponentError; end
+    class InvalidModelIdError < URI::InvalidComponentError; end
+
+    # Maximum size of a model id segment
+    COMPOSITE_MODEL_ID_MAX_SIZE = 20
+    COMPOSITE_MODEL_ID_DELIMITER = "/"
 
     class << self
       # Validates +app+'s as URI hostnames containing only alphanumeric characters
@@ -83,7 +88,8 @@ module URI
       def build(args)
         parts = Util.make_components_hash(self, args)
         parts[:host] = parts[:app]
-        parts[:path] = "/#{parts[:model_name]}/#{CGI.escape(parts[:model_id].to_s)}"
+        model_id_segment = Array(parts[:model_id]).map { |p| CGI.escape(p.to_s) }.join(COMPOSITE_MODEL_ID_DELIMITER)
+        parts[:path] = "/#{parts[:model_name]}/#{model_id_segment}"
 
         if parts[:params] && !parts[:params].empty?
           parts[:query] = URI.encode_www_form(parts[:params])
@@ -147,12 +153,22 @@ module URI
 
       def set_model_components(path, validate = false)
         _, model_name, model_id = path.split('/', 3)
-        validate_component(model_name) && validate_model_id(model_id, model_name) if validate
-
-        model_id = CGI.unescape(model_id) if model_id
 
+        validate_component(model_name) && validate_model_id_section(model_id, model_name) if validate
         @model_name = model_name
-        @model_id = model_id
+
+        if model_id
+          model_id_parts = model_id
+            .split(COMPOSITE_MODEL_ID_DELIMITER, COMPOSITE_MODEL_ID_MAX_SIZE)
+            .reject(&:blank?)
+
+          model_id_parts.map! do |id|
+            validate_model_id(id)
+            CGI.unescape(id)
+          end
+
+          @model_id = model_id_parts.length == 1 ? model_id_parts.first : model_id_parts
+        end
       end
 
       def validate_component(component)
@@ -162,13 +178,20 @@ module URI
           "Expected a URI like gid://app/Person/1234: #{inspect}"
       end
 
-      def validate_model_id(model_id, model_name)
-        return model_id unless model_id.blank? || model_id.include?('/')
+      def validate_model_id_section(model_id, model_name)
+        return model_id unless model_id.blank?
 
         raise MissingModelIdError, "Unable to create a Global ID for " \
           "#{model_name} without a model id."
       end
 
+      def validate_model_id(model_id_part)
+        return unless model_id_part.include?('/')
+
+        raise InvalidModelIdError, "Unable to create a Global ID for " \
+          "#{model_name} with a malformed model id."
+      end
+
       def parse_query_params(query)
         Hash[URI.decode_www_form(query)].with_indifferent_access if query
       end

data/lib/global_id/verifier.rb

@@ -3,11 +3,11 @@ require 'active_support/message_verifier'
 class GlobalID
   class Verifier < ActiveSupport::MessageVerifier
     private
-      def encode(data)
+      def encode(data, **)
         ::Base64.urlsafe_encode64(data)
       end
 
-      def decode(data)
+      def decode(data, **)
         ::Base64.urlsafe_decode64(data)
       end
   end

data/lib/global_id.rb

@@ -16,4 +16,8 @@ class GlobalID
     super
     require 'global_id/signed_global_id'
   end
+
+  def self.deprecator # :nodoc:
+    @deprecator ||= ActiveSupport::Deprecation.new("2.1", "GlobalID")
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: globalid
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - David Heinemeier Hansson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-25 00:00:00.000000000 Z
+date: 2023-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement