Apps can hook in their own locator.

lib/global_id/global_id.rb

@@ -24,9 +24,15 @@ def parse(gid, options = {})
       parse_encoded_gid(gid, options)
     end
 
-    def app=(value)
-      validate_hostname(value)
-      @app = value
+    def app=(app)
+      @app = validate_app(app)
+    end
+
+    def validate_app(app)
+      URI.parse('gid:///').hostname = app
+    rescue URI::InvalidComponentError
+      raise ArgumentError, 'Invalid app name. ' \
+        'App names must be valid URI hostnames: alphanumeric and hyphen characters only.'
     end
 
     private
@@ -39,17 +45,6 @@ def repad_gid(gid)
         padding_chars = gid.length.modulo(4).zero? ? 0 : (4 - gid.length.modulo(4))
         gid + ('=' * padding_chars)
       end
-
-      def validate_hostname(hostname)
-        begin
-          URI.parse('gid:///').hostname = hostname
-        rescue URI::InvalidComponentError
-          raise ArgumentError,
-                'Invalid app name. App names must be valid URI hostnames: ' \
-                'alphanumeric and hyphen characters only.'
-        end
-      end
-
   end
 
   attr_reader :uri, :app, :model_name, :model_id
@@ -59,7 +54,7 @@ def initialize(gid, options = {})
   end
 
   def find(options = {})
-    model_class.find model_id if find_allowed?(options[:only])
+    Locator.locate self, options
   end
 
   def model_class
@@ -95,8 +90,4 @@ def extract_uri_components(gid)
         raise URI::InvalidURIError, "Expected a URI like gid://app/Person/1234: #{@uri.inspect}"
       end
     end
-
-    def find_allowed?(only = nil)
-      only ? Array(only).any? { |c| model_class <= c } : true
-    end
 end

lib/global_id/locator.rb

@@ -10,7 +10,9 @@ class << self
       #   instances of returned classes to those including that module.  If no classes or
       #   modules match, +nil+ is returned.
       def locate(gid, options = {})
-        GlobalID.find gid, options
+        if gid = GlobalID.parse(gid)
+          locator_for(gid).locate gid if find_allowed?(gid.model_class, options[:only])
+        end
       end
 
       # Takes either a SignedGlobalID or a string that can be turned into a SignedGlobalID
@@ -24,6 +26,68 @@ def locate(gid, options = {})
       def locate_signed(sgid, options = {})
         SignedGlobalID.find sgid, options
       end
+
+      # Tie a locator to an app.
+      # Useful when different apps collaborate and reference each others' Global IDs.
+      #
+      # The locator can be either a block or a class.
+      #
+      # Using a block:
+      #
+      #   GlobalID::Locator.use :foo do |gid|
+      #     FooRemote.const_get(gid.model_name).find(gid.model_id)
+      #   end
+      #
+      # Using a class:
+      #
+      #   GlobalID::Locator.use :bar, BarLocator.new
+      #
+      #   class BarLocator
+      #     def locate(gid)
+      #       @search_client.search name: gid.model_name, id: gid.model_id
+      #     end
+      #   end
+      def use(app, locator = nil, &locator_block)
+        raise ArgumentError, 'No locator provided. Pass a block or an object that responds to #locate.' unless locator || block_given?
+
+        GlobalID.validate_app(app)
+
+        @locators[normalize_app(app)] = locator || BlockLocator.new(locator_block)
+      end
+
+      private
+        def locator_for(gid)
+          @locators.fetch(normalize_app(gid.app)) { default_locator }
+        end
+
+        def find_allowed?(model_class, only = nil)
+          only ? Array(only).any? { |c| model_class <= c } : true
+        end
+
+        def normalize_app(app)
+          app.to_s.downcase
+        end
     end
+
+    private
+      @locators = {}
+
+      class ActiveRecordFinder
+        def locate(gid)
+          gid.model_class.find gid.model_id
+        end
+      end
+
+      mattr_reader(:default_locator) { ActiveRecordFinder.new }
+
+      class BlockLocator
+        def initialize(block)
+          @locator = block
+        end
+
+        def locate(gid)
+          @locator.call(gid)
+        end
+      end
   end
 end

test/cases/global_locator_test.rb

@@ -135,4 +135,50 @@ class GlobalLocatorTest < ActiveSupport::TestCase
     assert_nil GlobalID::Locator.locate 'gid://app/Person'
     assert_nil GlobalID::Locator.locate 'gid://app/Person/1/2'
   end
+
+  test 'use locator with block' do
+    GlobalID::Locator.use :foo do |gid|
+      :foo
+    end
+
+    with_app 'foo' do
+      assert_equal :foo, GlobalID::Locator.locate('gid://foo/Person/1')
+    end
+  end
+
+  test 'use locator with class' do
+    class BarLocator
+      def locate(gid); :bar; end
+    end
+
+    GlobalID::Locator.use :bar, BarLocator.new
+
+    with_app 'bar' do
+      assert_equal :bar, GlobalID::Locator.locate('gid://bar/Person/1')
+    end
+  end
+
+  test 'app locator is case insensitive' do
+    GlobalID::Locator.use :insensitive do |gid|
+      :insensitive
+    end
+
+    with_app 'insensitive' do
+      assert_equal :insensitive, GlobalID::Locator.locate('gid://InSeNsItIvE/Person/1')
+    end
+  end
+
+  test 'locator name cannot have underscore' do
+    assert_raises ArgumentError do
+      GlobalID::Locator.use('under_score') { |gid| 'will never be found' }
+    end
+  end
+
+  private
+    def with_app(app)
+      old_app, GlobalID.app = GlobalID.app, app
+      yield
+    ensure
+      GlobalID.app = old_app
+    end
 end