globalid 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: d325de1fd4887ed3e91ebb2ec6d58d4ed0d552d0
-  data.tar.gz: e7d0091c1cc92b20c682093faa424b528c32940f
+SHA1:
+  metadata.gz: db37405060de11d6af715c038fa47349a94f23d6
+  data.tar.gz: a2fc2891e16182cf893b690731c193659e03b349
 SHA512:
-  metadata.gz: 98f92c4c3fa1e9a127abcc44f1eb51ca529f5388dec8529aacce43c18a9fc9cc9aa947854620abe0bd609ebb46dfcee22a1d81089bffb83d106d29967c457147
-  data.tar.gz: 989269225c2d49d7a25cb6bb5e7f9bca1087268d5688d27558bb8d2fa1d1062360bbf72f2d8004cb764c886217f4d6a7eed73da1e0a1fe190b1ba250f1026bcb
+  metadata.gz: 5be8760a5728d9ff3b3c3cd6d8cae89d009fd9f9152449211fe0107fc92d56ef34c8357b9e7d565aed5f1dd0c7e5d3981ed56c056d403076b682ddc7891dbaba
+  data.tar.gz: f6a1fec5024a193076ebe07076163685abccc6e4348b2afa67f90bbd1dfc080fe6858de3391b7693956f29b196cb735d0012168e6722be9c7de2ab176556cddc

data/lib/global_id.rb

@@ -1,4 +1,5 @@
 require 'global_id/global_id'
+
 autoload :SignedGlobalID, 'global_id/signed_global_id'
 
 class GlobalID

data/lib/global_id/global_id.rb

@@ -2,16 +2,20 @@ require 'active_support'
 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
-require 'uri'
+require 'active_support/core_ext/module/delegation'
+require 'global_id/uri/gid'
 
 class GlobalID
   class << self
     attr_reader :app
 
     def create(model, options = {})
-      app = options.fetch :app, GlobalID.app
-      raise ArgumentError, "An app is required to create a GlobalID. Pass the :app option or set the default GlobalID.app." unless app
-      new URI("gid://#{app}/#{model.class.name}/#{model.id}"), options
+      if app = options.fetch(:app) { GlobalID.app }
+        new URI::GID.create(app, model), options
+      else
+        raise ArgumentError, 'An app is required to create a GlobalID. ' \
+          'Pass the :app option or set the default GlobalID.app.'
+      end
     end
 
     def find(gid, options = {})
@@ -25,14 +29,7 @@ class GlobalID
     end
 
     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.'
+      @app = URI::GID.validate_app(app)
     end
 
     private
@@ -47,10 +44,11 @@ class GlobalID
       end
   end
 
-  attr_reader :uri, :app, :model_name, :model_id
+  attr_reader :uri
+  delegate :app, :model_name, :model_id, :params, :to_s, to: :uri
 
   def initialize(gid, options = {})
-    extract_uri_components gid
+    @uri = gid.is_a?(URI::GID) ? gid : URI::GID.parse(gid)
   end
 
   def find(options = {})
@@ -65,29 +63,8 @@ class GlobalID
     other.is_a?(GlobalID) && @uri == other.uri
   end
 
-  def to_s
-    @uri.to_s
-  end
-
   def to_param
     # remove the = padding character for a prettier param -- it'll be added back in parse_encoded_gid
     Base64.urlsafe_encode64(to_s).sub(/=+$/, '')
   end
-
-  private
-    PATH_REGEXP = %r(\A/([^/]+)/([^/]+)\z)
-
-    # Pending a URI::GID to handle validation
-    def extract_uri_components(gid)
-      @uri = gid.is_a?(URI) ? gid : URI.parse(gid)
-      raise URI::BadURIError, "Not a gid:// URI scheme: #{@uri.inspect}" unless @uri.scheme == 'gid'
-
-      if @uri.path =~ PATH_REGEXP
-        @app = @uri.host
-        @model_name = $1
-        @model_id = $2
-      else
-        raise URI::InvalidURIError, "Expected a URI like gid://app/Person/1234: #{@uri.inspect}"
-      end
-    end
 end

data/lib/global_id/identification.rb

@@ -10,7 +10,7 @@ class GlobalID
     alias to_gid to_global_id
 
     def to_signed_global_id(options = {})
-      @signed_global_id ||= SignedGlobalID.create(self, options)
+      SignedGlobalID.create(self, options)
     end
     alias to_sgid to_signed_global_id
   end

data/lib/global_id/locator.rb

@@ -1,3 +1,6 @@
+require 'active_support'
+require 'active_support/core_ext/enumerable' # For Enumerable#index_by
+
 class GlobalID
   module Locator
     class << self
@@ -15,6 +18,31 @@ class GlobalID
         end
       end
 
+      # Takes an array of GlobalIDs or strings that can be turned into a GlobalIDs.
+      # The GlobalIDs are located using Model.find(array_of_ids), so the models must respond to
+      # that finder signature.
+      #
+      # This approach will efficiently call only one #find per model class, but still interpolate
+      # the results to match the order in which the gids were passed.
+      #
+      # Options:
+      # * <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_many(gids, options = {})
+        if (allowed_gids = parse_allowed(gids, options[:only])).any?
+          models_and_ids  = allowed_gids.collect { |gid| [ gid.model_name.constantize, gid.model_id ] }
+          ids_by_model    = models_and_ids.group_by(&:first)
+          loaded_by_model = Hash[ids_by_model.map { |model, ids| [ model, model.find(ids.map(&:last)).index_by { |record| record.id.to_s } ] }]
+
+          models_and_ids.collect { |(model, id)| loaded_by_model[model][id] }.compact
+        else
+          []
+        end
+      end
+
       # Takes either a SignedGlobalID or a string that can be turned into a SignedGlobalID
       #
       # Options:
@@ -27,6 +55,23 @@ class GlobalID
         SignedGlobalID.find sgid, options
       end
 
+      # Takes an array of SignedGlobalIDs or strings that can be turned into a SignedGlobalIDs.
+      # The SignedGlobalIDs are located using Model.find(array_of_ids), so the models must respond to
+      # that finder signature.
+      #
+      # This approach will efficiently call only one #find per model class, but still interpolate
+      # the results to match the order in which the gids were passed.
+      #
+      # Options:
+      # * <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_many_signed(sgids, options = {})
+        locate_many sgids.collect { |sgid| SignedGlobalID.parse(sgid) }, options
+      end
+
       # Tie a locator to an app.
       # Useful when different apps collaborate and reference each others' Global IDs.
       #
@@ -50,7 +95,7 @@ class GlobalID
       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)
+        URI::GID.validate_app(app)
 
         @locators[normalize_app(app)] = locator || BlockLocator.new(locator_block)
       end
@@ -64,6 +109,10 @@ class GlobalID
           only ? Array(only).any? { |c| model_class <= c } : true
         end
 
+        def parse_allowed(gids, only = nil)
+          gids.collect { |gid| GlobalID.parse(gid) }.compact.select { |gid| find_allowed?(gid.model_class, only) }
+        end
+
         def normalize_app(app)
           app.to_s.downcase
         end

data/lib/global_id/uri/gid.rb

@@ -0,0 +1,163 @@
+require 'uri/generic'
+require 'active_support/core_ext/module/aliasing'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/hash/indifferent_access'
+
+module URI
+  class GID < Generic
+    # URI::GID encodes an app unique reference to a specific model as an URI.
+    # It has the components: app name, model class name, model id and params.
+    # All components except params are required.
+    #
+    # The URI format looks like "gid://app/model_name/model_id".
+    #
+    # Simple metadata can be stored in params. Useful if your app has multiple databases,
+    # for instance, and you need to find out which one to look up the model in.
+    #
+    # Params will be encoded as query parameters like so
+    # "gid://app/model_name/model_id?key=value&another_key=another_value".
+    #
+    # Params won't be typecast, they're always strings.
+    # For convenience params can be accessed using both strings and symbol keys.
+    #
+    # Multi value params aren't supported. Any params encoding multiple values under
+    # the same key will return only the last value. For example, when decoding
+    # params like "key=first_value&key=last_value" key will only be last_value.
+    #
+    # Read the documentation for +parse+, +create+ and +build+ for more.
+    alias :app :host
+    attr_reader :model_name, :model_id, :params
+
+    class << self
+      # Validates +app+'s as URI hostnames containing only alphanumeric characters
+      # and hyphens. 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(nil)       # => ArgumentError
+      #   URI::GID.validate_app('foo/bar') # => ArgumentError
+      def validate_app(app)
+        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.'
+      end
+
+      # Create a new URI::GID by parsing a gid string with argument check.
+      #
+      #   URI::GID.parse 'gid://bcx/Person/1?key=value'
+      #
+      # This differs from URI() and URI.parse which do not check arguments.
+      #
+      #   URI('gid://bcx')             # => URI::GID instance
+      #   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
+        new(*generic_components)
+      end
+
+      # Shorthand to build a URI::GID from an app, a model and optional params.
+      #
+      #   URI::GID.create('bcx', Person.find(5), database: 'superhumans')
+      def create(app, model, params = nil)
+        build app: app, model_name: model.class.name, model_id: model.id, params: params
+      end
+
+      # Create a new URI::GID from components with argument check.
+      #
+      # The allowed components are app, model_name, model_id and params, which can be
+      # either a hash or an array.
+      #
+      # Using a hash:
+      #
+      #   URI::GID.build(app: 'bcx', model_name: 'Person', model_id: '1', params: { key: 'value' })
+      #
+      # Using an array, the arguments must be in order [app, model_name, model_id, params]:
+      #
+      #   URI::GID.build(['bcx', 'Person', '1', key: 'value'])
+      def build(args)
+        parts = Util.make_components_hash(self, args)
+        parts[:host] = parts[:app]
+        parts[:path] = "/#{parts[:model_name]}/#{parts[:model_id]}"
+        parts[:query] = URI.encode_www_form(parts[:params]) if parts[:params]
+
+        super parts
+      end
+    end
+
+    def to_s
+      # Implement #to_s to avoid no implicit conversion of nil into string when path is nil
+      "gid://#{app}#{path}#{'?' + query if query}"
+    end
+
+    protected
+      def set_path(path)
+        set_model_components(path) unless defined?(@model_name) && @model_id
+        super
+      end
+
+      # Ruby 2.2 uses #query= instead of #set_query
+      def query=(query)
+        set_params parse_query_params(query)
+        super
+      end
+
+      # Ruby 2.1 or less uses #set_query to assign the query
+      def set_query(query)
+        set_params parse_query_params(query)
+        super
+      end
+
+      def set_params(params)
+        @params = params
+      end
+
+    private
+      COMPONENT = [ :scheme, :app, :model_name, :model_id, :params ].freeze
+
+      # Extracts model_name and model_id from the URI path.
+      PATH_REGEXP = %r(\A/([^/]+)/?([^/]+)?\z)
+
+      def check_host(host)
+        validate_component(host)
+        super
+      end
+
+      def check_path(path)
+        validate_component(path)
+        set_model_components(path, true)
+      end
+
+      def check_scheme(scheme)
+        if scheme == 'gid'
+          super
+        else
+          raise URI::BadURIError, "Not a gid:// URI scheme: #{inspect}"
+        end
+      end
+
+      def set_model_components(path, validate = false)
+        _, model_name, model_id = path.match(PATH_REGEXP).to_a
+
+        validate_component(model_name) && validate_component(model_id) if validate
+
+        @model_name = model_name
+        @model_id = model_id
+      end
+
+      def validate_component(component)
+        return component unless component.blank?
+
+        raise URI::InvalidComponentError,
+          "Expected a URI like gid://app/Person/1234: #{inspect}"
+      end
+
+      def parse_query_params(query)
+        Hash[URI.decode_www_form(query)].with_indifferent_access if query
+      end
+  end
+
+  @@schemes['GID'] = GID
+end

metadata

@@ -1,41 +1,41 @@
 --- !ruby/object:Gem::Specification
 name: globalid
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - David Heinemeier Hansson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-12 00:00:00.000000000 Z
+date: 2015-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 4.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 4.1.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: URIs for your models makes it easy to pass references around.
@@ -51,6 +51,7 @@ files:
 - lib/global_id/locator.rb
 - lib/global_id/railtie.rb
 - lib/global_id/signed_global_id.rb
+- lib/global_id/uri/gid.rb
 - lib/globalid.rb
 homepage: http://www.rubyonrails.org
 licenses:
@@ -62,12 +63,12 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
@@ -75,5 +76,5 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: ! 'Refer to any model with a URI: gid://app/class/id'
+summary: 'Refer to any model with a URI: gid://app/class/id'
 test_files: []