globalid 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7f6fd8b8b0b07aad73739e2004b5c4229e48dfa64960dcfa243f6c1b6276b44
-  data.tar.gz: a1cc24c9968a2236d2974f4ecac4d3fbb8513e4ac74d18685185afa684fad41d
+  metadata.gz: d57eeec2571a0ec07f96c46e09a1f2513958e798069847b6001c08088ebcb69c
+  data.tar.gz: d6585f62af8ae463201fdc6994d9f816c71e793dffb00803561e53bde284711e
 SHA512:
-  metadata.gz: 68bd4cc42217eb59cff8b1f73c989e9f17ddce332f7d65f533e5b2fa6e429a10328d9c5b02f165e778cd83c02afa095103984910c098e75c9dcab788a4c97024
-  data.tar.gz: 652bc775cb1da110f6eca011d5a6ef3d907f79ddbfda755206d84eddca06c2153b734befb5b5dc6ea09ed911b87c72fcae6f9bfb5554da1b4616d60d22a298fb
+  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.
@@ -199,17 +216,63 @@ 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.
 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.
@@ -221,7 +284,7 @@ class MyCustomLocator < UnscopedLocator
       super(gid, options)
     end
   end
-  
+
   def locate_many(gids, options = {})
     ActiveRecord::Base.connected_to(role: :reading) do
       super(gids, options)

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
@@ -55,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.

data/lib/global_id/locator.rb

@@ -1,8 +1,20 @@
+# 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.
@@ -23,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)
 
@@ -35,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.
@@ -135,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)
@@ -157,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
@@ -234,6 +285,10 @@ class GlobalID
           @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,14 +37,15 @@ module URI
     COMPOSITE_MODEL_ID_MAX_SIZE = 20
     COMPOSITE_MODEL_ID_DELIMITER = "/"
 
-    URI_PARSER = URI::RFC2396_Parser.new # :nodoc:
+    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
@@ -51,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.
@@ -64,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) << URI_PARSER << true # RFC2396 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: globalid
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - David Heinemeier Hansson
@@ -37,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: []
@@ -54,15 +68,16 @@ 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.3.0
+  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.3.0
+  source_code_uri: https://github.com/rails/globalid/tree/v1.4.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -78,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.12
 specification_version: 4
 summary: 'Refer to any model with a URI: gid://app/class/id'
 test_files: []