globalid 1.2.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18495b4f7910329fd0a65dcfa294742d0cdbb129a4c7f6971c4f9c62e9ea890d
-  data.tar.gz: 5b6a25aabd0d04d9a4a2d4bb4d5152d68a67758fad96deabc011a4a169f2a055
+  metadata.gz: d57eeec2571a0ec07f96c46e09a1f2513958e798069847b6001c08088ebcb69c
+  data.tar.gz: d6585f62af8ae463201fdc6994d9f816c71e793dffb00803561e53bde284711e
 SHA512:
-  metadata.gz: fb525d60050154b885197a89aaf2b1f2f577d0574b83160a3c0cbc2899d67e8995cf23c2de852c30baaa1ef8cc594cad39187e3808b350195c95ead32359957c
-  data.tar.gz: 5dda5c09cffcc6e60da06931f3be5ba144db99f6ed0b9d7dc085633e0bac642f1c9d9ac7ba686dd59a6b9be64bb275ee8e78b39fae6e372b69c8131709db6f0f
+  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
 
@@ -165,19 +182,19 @@ Note the order is maintained in the returned results.
 
 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)
+* `: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 that relationships.
-* :only - A class, module or Array of classes and/or modules that are
+  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
+  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,
+  `#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
@@ -199,17 +216,85 @@ end
 Using a class:
 
 ```ruby
-GlobalID::Locator.use :bar, BarLocator.new
 class BarLocator
   def locate(gid, options = {})
     @search_client.search name: gid.model_name, id: gid.model_id
   end
 end
+
+GlobalID::Locator.use :bar, BarLocator.new
+```
+
+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.
+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
@@ -51,8 +56,21 @@ class GlobalID
 
   def model_class
     @model_class ||= begin
-      model = model_name.constantize
-
+      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

data/lib/global_id/identification.rb

@@ -1,3 +1,4 @@
+# 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.
@@ -31,8 +32,8 @@ class GlobalID
     #
     #   model = Person.new id: 1
     #   global_id = model.to_global_id
-    #   global_id.modal_class # => Person
-    #   global_id.modal_id # => "1"
+    #   global_id.model_class # => Person
+    #   global_id.model_id # => "1"
     #   global_id.to_param # => "Z2lkOi8vYm9yZGZvbGlvL1BlcnNvbi8x"
     def to_global_id(options = {})
       GlobalID.create(self, options)
@@ -52,8 +53,8 @@ class GlobalID
     #
     #   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.model_class # => Person
+    #   signed_global_id.model_id # => "1"
     #   signed_global_id.to_param # => "BAh7CEkiCGdpZAY6BkVUSSIiZ2..."
     #
     # ==== Expiration

data/lib/global_id/locator.rb

@@ -1,10 +1,25 @@
+# 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:
@@ -20,7 +35,7 @@ class GlobalID
       def locate(gid, options = {})
         gid = GlobalID.parse(gid)
 
-        return unless gid && find_allowed?(gid.model_class, options[:only])
+        return unless gid && find_allowed?(gid, options[:only])
 
         locator = locator_for(gid)
 
@@ -32,6 +47,35 @@ class GlobalID
         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.
@@ -132,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)
@@ -154,6 +204,10 @@ class GlobalID
       @locators = {}
 
       class BaseLocator
+        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
@@ -223,13 +277,18 @@ class GlobalID
             end
           end
       end
-      DEFAULT_LOCATOR = UnscopedLocator.new
+
+      self.default_locator = UnscopedLocator.new
 
       class BlockLocator
         def initialize(block)
           @locator = block
         end
 
+        def model_class(gid)
+          gid.model_name.constantize
+        end
+
         def locate(gid, options = {})
           @locator.call(gid, options)
         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'
@@ -48,5 +46,3 @@ class GlobalID
     end
   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'
 

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'
@@ -36,12 +37,15 @@ module URI
     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
@@ -49,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.
@@ -62,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
 

data/lib/global_id/verifier.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'active_support/message_verifier'
 
 class GlobalID

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'

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.2.1
+  version: 1.4.0
 platform: ruby
 authors:
 - David Heinemeier Hansson
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-09-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -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: []