globalid 1.1.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52c4368f15fc8952c9d79189ed9a78e649e0142421721aef338625c19b24c3b9
-  data.tar.gz: 4d6d1c379d45ccaf5761488c540d19cac9d0488b578564964edd88c52073c511
+  metadata.gz: d57eeec2571a0ec07f96c46e09a1f2513958e798069847b6001c08088ebcb69c
+  data.tar.gz: d6585f62af8ae463201fdc6994d9f816c71e793dffb00803561e53bde284711e
 SHA512:
-  metadata.gz: 49ff5a4b4d4f68afdffa67a85b5aebfb3b2f518257ffec22be8a60a29ac5596a67552aae46bebab28a4fe6b37a5802ac520b0f567098617110b2f54c4a74cfcb
-  data.tar.gz: f6ba35dc2c080b0c996bd4529cec1438a35545c693cc0271e25c6b7bdaa8f759de61f26ae6ecf16487d89c7e6e5afc41caab7114541cd8a54ebdf9e2a3ce1f60
+  metadata.gz: 3fdc67028c552eb91fed9fc35031c5dec4215090260c21ce3d4d10b2db511be531162f3f93f7710ad15534e747a5610e0f9ecab5bed5c9fc5a45f30ee9936dd8
+  data.tar.gz: 2d07eeee13b8337cea053b4c67ba52dd5a9f05ff80e53b123d97364cf3dc0bf32654ff64c4a3f882fa69a44c960d2e11a2f7bb6a4edaf717331ebaf8ebe65528

data/README.md

@@ -37,6 +37,23 @@ GlobalID::Locator.locate person_gid
 # => #<Person:0x007fae94bf6298 @id="1">
 ```
 
+`locate` returns `nil` for a blank or unparseable Global ID, and lets the
+backend's own exceptions bubble up when a record can't be found. Use `fetch`
+when you want to tell apart a record that's gone for good from a transient
+backend failure:
+
+```ruby
+GlobalID::Locator.fetch person_gid
+# => #<Person:0x007fae94bf6298 @id="1">           # found
+# => raises GlobalID::Locator::RecordNotFound     # the record no longer exists
+# => raises GlobalID::Locator::RecordUnavailable  # the backend failed; retry may succeed
+```
+
+Both errors extend `GlobalID::Locator::Error`, so you can rescue either at
+once. This is useful, for example, to discard a background job whose argument
+points at a deleted record, without also discarding jobs that hit a temporary
+database error.
+
 ### Signed Global IDs
 
 For added security GlobalIDs can also be signed to ensure that the data hasn't been tampered with.
@@ -57,7 +74,7 @@ GlobalID::Locator.locate_signed person_sgid
 
 **Expiration**
 
-Signed Global IDs can expire some time in the future. This is useful if there's a resource
+Signed Global IDs can expire sometime in the future. This is useful if there's a resource
 people shouldn't have indefinite access to, like a share link.
 
 ```ruby
@@ -73,8 +90,8 @@ GlobalID::Locator.locate_signed(expiring_sgid.to_s, for: 'sharing')
 # => nil
 ```
 
-**In Rails, an auto-expiry of 1 month is set by default.** You can alter that deal
-in an initializer with:
+**In Rails, an auto-expiry of 1 month is set by default.** You can alter that
+default in an initializer with:
 
 ```ruby
 # config/initializers/global_id.rb
@@ -87,7 +104,7 @@ You can assign a default SGID lifetime like so:
 SignedGlobalID.expires_in = 1.month
 ```
 
-This way any generated SGID will use that relative expiry.
+This way, any generated SGID will use that relative expiry.
 
 It's worth noting that _expiring SGIDs are not idempotent_ because they encode the current timestamp; repeated calls to `to_sgid` will produce different results. For example, in Rails
 
@@ -161,6 +178,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 an `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 those 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 +208,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
 ```
@@ -180,17 +216,85 @@ end
 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
+
+GlobalID::Locator.use :bar, BarLocator.new
 ```
 
-After defining locators as above, URIs like "gid://foo/Person/1" and "gid://bar/Person/1" will now use the foo block locator and `BarLocator` respectively.
+It's recommended to inherit from `GlobalID::Locator::BaseLocator` (or `GlobalID::Locator::UnscopedLocator` for Active Record models) to get default implementations of `model_class` and `locate_many`:
+
+```ruby
+class BarLocator < GlobalID::Locator::BaseLocator
+  def locate(gid, options = {})
+    @search_client.search name: gid.model_name, id: gid.model_id
+  end
+end
+
+GlobalID::Locator.use :bar, BarLocator.new
+```
+
+After defining locators as above, URIs like `gid://foo/Person/1` and `gid://bar/Person/1` will now use the foo block locator and `BarLocator` respectively.
 Other apps will still keep using the default locator.
 
+#### Custom Model Class Derivation
+
+By default, GlobalID derives the model class by calling `constantize` on the model name from the GID. Custom locators can override this behavior by implementing a `model_class` method. This is useful when the model name in the GID doesn't match the actual class name, or when you want to redirect to a different model.
+
+Inherit from `BaseLocator` and override `model_class`:
+
+```ruby
+class RemoteLocator < GlobalID::Locator::BaseLocator
+  def model_class(gid)
+    # Map remote model names to local models
+    case gid.model_name
+    when 'User'
+      RemoteUser
+    when 'Profile'
+      RemoteProfile
+    else
+      super # Fall back to default constantize behavior
+    end
+  end
+
+  def locate(gid, options = {})
+    # Use the mapped model class to find the record
+    model_class(gid).find_by(remote_id: gid.model_id)
+  end
+end
+
+GlobalID::Locator.use :remote, RemoteLocator.new
+```
+
+This allows you to work with Global IDs that reference models that don't exist in your application, redirecting them to the appropriate local models.
+
+**Note**: For backward compatibility, if a custom locator doesn't implement `model_class`, GlobalID will fall back to the default behavior (`constantize`) but will emit a deprecation warning. To avoid this, inherit from `GlobalID::Locator::BaseLocator` or `GlobalID::Locator::UnscopedLocator`.
+
+### Custom Default Locator
+
+A custom default locator can be set for an app by calling `GlobalID::Locator.default_locator=` and providing a default locator to use for that app.
+
+```ruby
+class MyCustomLocator < UnscopedLocator
+  def locate(gid, options = {})
+    ActiveRecord::Base.connected_to(role: :reading) do
+      super(gid, options)
+    end
+  end
+
+  def locate_many(gids, options = {})
+    ActiveRecord::Base.connected_to(role: :reading) do
+      super(gids, options)
+    end
+  end
+end
+
+GlobalID::Locator.default_locator = MyCustomLocator.new
+```
+
 ## Contributing to GlobalID
 
 GlobalID is work of many contributors. You're encouraged to submit pull requests, propose

data/lib/global_id/global_id.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'active_support/core_ext/string/inflections'  # For #model_class constantize
 require 'active_support/core_ext/array/access'
 require 'active_support/core_ext/object/try'          # For #find
@@ -32,6 +33,10 @@ class GlobalID
       @app = URI::GID.validate_app(app)
     end
 
+    def default_locator(default_locator)
+      Locator.default_locator = default_locator
+    end
+
     private
       def parse_encoded_gid(gid, options)
         new(Base64.urlsafe_decode64(gid), options) rescue nil
@@ -50,12 +55,26 @@ class GlobalID
   end
 
   def model_class
-    model = model_name.constantize
-
-    unless model <= GlobalID
+    @model_class ||= begin
+      locator = Locator.locator_for(self)
+      model = begin
+        locator.model_class(self)
+      rescue NoMethodError
+        if locator.respond_to?(:model_class)
+          raise
+        else
+          GlobalID.deprecator.warn <<~MSG.squish
+            Your locator #{locator.class.name} does not implement the
+            `model_class` method. Please add a `model_class(gid)` method
+            to your locator or inherit from `GlobalID::Locator::BaseLocator`.
+          MSG
+          model_name.constantize
+        end
+      end
+      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,119 @@
+# frozen_string_literal: true
 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.model_class # => Person
+    #   global_id.model_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.model_class # => Person
+    #   signed_global_id.model_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

@@ -1,22 +1,81 @@
+# frozen_string_literal: true
 require 'active_support/core_ext/enumerable' # For Enumerable#index_by
 
 class GlobalID
   module Locator
+    class InvalidModelIdError < StandardError; end
+    class Error < StandardError; end
+
+    # Raised by GlobalID::Locator.fetch when the GlobalID is valid but the
+    # record it references no longer exists. The record is gone for good, so
+    # retrying won't help.
+    class RecordNotFound < Error; end
+
+    # Raised by GlobalID::Locator.fetch when the record couldn't be located
+    # due to any other error in the backend, such as a database connection
+    # error. The record may still exist, so retrying may succeed.
+    class RecordUnavailable < Error; end
+
     class << self
+      # The default locator used when no app-specific locator is found.
+      attr_accessor :default_locator
+
       # 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, 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
 
+      # Like .locate, but instead of returning +nil+ or leaking the backend's
+      # own exceptions when the record can't be returned, it raises one of two
+      # GlobalID-specific errors so callers can tell the cases apart:
+      #
+      # * GlobalID::Locator::RecordNotFound when the record no longer exists.
+      #   Retrying won't help.
+      # * GlobalID::Locator::RecordUnavailable when the record couldn't be
+      #   located due to any other failure in the backend, like a database
+      #   connection error. The record may still exist, so retrying may succeed.
+      #
+      # The distinction is drawn without knowing the backend's exception
+      # classes: the record is looked up through a query that doesn't raise on
+      # missing records (like .locate_many's +:ignore_missing+), so an empty
+      # result means the record is gone, while an error from the query itself
+      # means the backend is unavailable.
+      #
+      # Returns +nil+ for a blank or unparseable GlobalID, or one disallowed by
+      # the +:only+ option, just like .locate, and accepts the same options.
+      #
+      # Note: custom locators registered with .use need to implement locate_many
+      # with support for the +:ignore_missing+ option for this method to work.
+      def fetch(gid, options = {})
+        gid = GlobalID.parse(gid)
+
+        return unless gid && find_allowed?(gid, options[:only])
+
+        fetch_record(gid, options.except(:only)) or raise RecordNotFound, "Couldn't find record for #{gid}"
+      end
+
       # Takes an array of GlobalIDs or strings that can be turned into a GlobalIDs.
       # All GlobalIDs must belong to the same app, as they will be located using
       # the same locator using its locate_many method.
@@ -28,6 +87,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 +113,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 +134,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 +155,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 +164,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
@@ -103,17 +176,23 @@ class GlobalID
         @locators[normalize_app(app)] = locator || BlockLocator.new(locator_block)
       end
 
+      def locator_for(gid)
+        @locators.fetch(normalize_app(gid.app)) { default_locator }
+      end
+
       private
-        def locator_for(gid)
-          @locators.fetch(normalize_app(gid.app)) { DEFAULT_LOCATOR }
+        def find_allowed?(gid, only = nil)
+          only ? Array(only).any? { |c| gid.model_class <= c } : true
         end
 
-        def find_allowed?(model_class, only = nil)
-          only ? Array(only).any? { |c| model_class <= c } : true
+        def fetch_record(gid, options)
+          locator_for(gid).locate_many([gid], options.merge(ignore_missing: true)).first
+        rescue => error
+          raise RecordUnavailable, "Couldn't fetch record for #{gid}: #{error.message}"
         end
 
         def parse_allowed(gids, only = nil)
-          gids.collect { |gid| GlobalID.parse(gid) }.compact.select { |gid| find_allowed?(gid.model_class, only) }
+          gids.collect { |gid| GlobalID.parse(gid) }.compact.select { |gid| find_allowed?(gid, only) }
         end
 
         def normalize_app(app)
@@ -125,32 +204,63 @@ class GlobalID
       @locators = {}
 
       class BaseLocator
-        def locate(gid)
-          gid.model_class.find gid.model_id
+        def model_class(gid)
+          gid.model_name.constantize
+        end
+
+        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 = {}
+
+          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
 
-          models_and_ids.collect { |(model, id)| loaded_by_model[model][id] }.compact
+          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(primary_key(model_class) => ids)
             else
               model_class.find(ids)
             end
           end
+
+          def model_id_is_valid?(gid)
+            Array(gid.model_id).size == Array(primary_key(gid.model_class)).size
+          end
+
+          def primary_key(model_class)
+            model_class.respond_to?(:primary_key) ? model_class.primary_key : :id
+          end
       end
 
       class UnscopedLocator < BaseLocator
-        def locate(gid)
+        def locate(gid, options = {})
           unscoped(gid.model_class) { super }
         end
 
@@ -167,19 +277,24 @@ class GlobalID
             end
           end
       end
-      DEFAULT_LOCATOR = UnscopedLocator.new
+
+      self.default_locator = UnscopedLocator.new
 
       class BlockLocator
         def initialize(block)
           @locator = block
         end
 
-        def locate(gid)
-          @locator.call(gid)
+        def model_class(gid)
+          gid.model_name.constantize
+        end
+
+        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

@@ -1,7 +1,5 @@
-begin
-require 'rails/railtie'
-rescue LoadError
-else
+# frozen_string_literal: true
+require 'rails'
 require 'global_id'
 require 'active_support/core_ext/string/inflections'
 require 'active_support/core_ext/integer/time'
@@ -42,7 +40,9 @@ class GlobalID
         send :extend, GlobalID::FixtureSet
       end
     end
-  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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'active_support/message_verifier'
 require 'time'
 
@@ -5,7 +6,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 +20,6 @@ class SignedGlobalID < GlobalID
       end
     end
 
-    attr_accessor :expires_in
-
     DEFAULT_PURPOSE = "default"
 
     def pick_purpose(options)
@@ -29,11 +28,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 +65,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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'uri/generic'
 require 'active_support/core_ext/module/aliasing'
 require 'active_support/core_ext/object/blank'
@@ -30,13 +31,21 @@ 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 = "/"
+
+    URI_PARSER = URI::RFC3986_Parser.new # :nodoc:
 
     class << self
-      # Validates +app+'s as URI hostnames containing only alphanumeric characters
-      # and hyphens. An ArgumentError is raised if +app+ is invalid.
+      # Validates +app+'s as URI hostnames containing only alphanumeric characters,
+      # hyphens and dashes. An ArgumentError is raised if +app+ is invalid.
       #
       #   URI::GID.validate_app('bcx')     # => 'bcx'
       #   URI::GID.validate_app('foo-bar') # => 'foo-bar'
+      #   URI::GID.validate_app('foo_bar') # => 'foo_bar'
       #
       #   URI::GID.validate_app(nil)       # => ArgumentError
       #   URI::GID.validate_app('foo/bar') # => ArgumentError
@@ -44,7 +53,7 @@ module URI
         parse("gid://#{app}/Model/1").app
       rescue URI::Error
         raise ArgumentError, 'Invalid app name. ' \
-          'App names must be valid URI hostnames: alphanumeric and hyphen characters only.'
+          'App names must be valid URI hostnames: alphanumeric, hyphen and underscore characters only.'
       end
 
       # Create a new URI::GID by parsing a gid string with argument check.
@@ -57,7 +66,7 @@ module URI
       #   URI.parse('gid://bcx')       # => URI::GID instance
       #   URI::GID.parse('gid://bcx/') # => raises URI::InvalidComponentError
       def parse(uri)
-        generic_components = URI.split(uri) << nil << true # nil parser, true arg_check
+        generic_components = URI.split(uri) << URI_PARSER << true # RFC3986 parser, true arg_check
         new(*generic_components)
       end
 
@@ -83,7 +92,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 +157,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 +182,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

@@ -1,13 +1,14 @@
+# frozen_string_literal: true
 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/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+class GlobalID
+  VERSION = "1.4.0"
+end

data/lib/global_id.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 require 'active_support'
+require 'global_id/version'
 require 'global_id/global_id'
 
 autoload :SignedGlobalID, 'global_id/signed_global_id'
@@ -16,4 +18,8 @@ class GlobalID
     super
     require 'global_id/signed_global_id'
   end
+
+  def self.deprecator # :nodoc:
+    @deprecator ||= ActiveSupport::Deprecation.new("2.1", "GlobalID")
+  end
 end

data/lib/globalid.rb

@@ -1,2 +1,3 @@
+# frozen_string_literal: true
 require 'global_id'
-require 'global_id/railtie'
+require 'global_id/railtie' if defined?(Rails::Railtie)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: globalid
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.4.0
 platform: ruby
 authors:
 - David Heinemeier Hansson
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-25 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -16,14 +15,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
@@ -38,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
 description: URIs for your models makes it easy to pass references around.
 email: david@loudthinking.com
 executables: []
@@ -55,13 +68,17 @@ files:
 - lib/global_id/signed_global_id.rb
 - lib/global_id/uri/gid.rb
 - lib/global_id/verifier.rb
+- lib/global_id/version.rb
 - lib/globalid.rb
 homepage: http://www.rubyonrails.org
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/rails/globalid/issues
+  changelog_uri: https://github.com/rails/globalid/releases/tag/v1.4.0
+  mailing_list_uri: https://discuss.rubyonrails.org/c/rubyonrails-talk
+  source_code_uri: https://github.com/rails/globalid/tree/v1.4.0
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -69,15 +86,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
-signing_key: 
+rubygems_version: 4.0.12
 specification_version: 4
 summary: 'Refer to any model with a URI: gid://app/class/id'
 test_files: []