jsi 0.7.0 → 0.8.0

data/lib/jsi/schema_classes.rb

@@ -1,13 +1,24 @@
 # frozen_string_literal: true
 
 module JSI
-  # JSI Schema Modules are extended with JSI::SchemaModule
-  module SchemaModule
-    # @!method schema
-    #   the schema of which this is the JSI Schema Module
-    #   @return [Schema]
-    # note: defined on JSI Schema Module by JSI::SchemaClasses.module_for_schema
+  # A Module associated with a JSI Schema. See {Schema#jsi_schema_module}.
+  class SchemaModule < Module
+    # @private
+    def initialize(schema, &block)
+      super(&block)
 
+      @jsi_node = schema
+
+      schema.jsi_schemas.each do |schema_schema|
+        extend SchemaClasses.schema_property_reader_module(schema_schema, conflicting_modules: Set[SchemaModule])
+      end
+    end
+
+    # The schema for which this is the JSI Schema Module
+    # @return [Base + Schema]
+    def schema
+      @jsi_node
+    end
 
     # a URI which refers to the schema. see {Schema#schema_uri}.
     # @return (see Schema#schema_uri)
@@ -18,61 +29,81 @@ module JSI
     # @return [String]
     def inspect
       if name_from_ancestor
-        "#{name_from_ancestor} (JSI Schema Module)"
+        if schema.schema_absolute_uri
+          -"#{name_from_ancestor} <#{schema.schema_absolute_uri}> (JSI Schema Module)"
+        else
+          -"#{name_from_ancestor} (JSI Schema Module)"
+        end
       else
-        "(JSI Schema Module: #{schema.schema_uri || schema.jsi_ptr.uri})"
+        -"(JSI Schema Module: #{schema.schema_uri || schema.jsi_ptr.uri})"
       end
     end
 
-    alias_method :to_s, :inspect
+    def to_s
+      inspect
+    end
 
-    # invokes {JSI::Schema#new_jsi} on this module's schema, passing the given instance.
+    # invokes {JSI::Schema#new_jsi} on this module's schema, passing the given parameters.
     #
     # @param (see JSI::Schema#new_jsi)
-    # @return [JSI::Base] a JSI whose instance is the given instance
+    # @return [JSI::Base subclass] a JSI whose content comes from the given instance and whose schemas are
+    #   inplace applicators of this module's schema.
     def new_jsi(instance, **kw)
       schema.new_jsi(instance, **kw)
     end
+
+    # See {Schema#schema_content}
+    def schema_content
+      schema.jsi_node_content
+    end
+
+    # See {Schema#instance_validate}
+    def instance_validate(instance)
+      schema.instance_validate(instance)
+    end
+
+    # See {Schema#instance_valid?}
+    def instance_valid?(instance)
+      schema.instance_valid?(instance)
+    end
   end
 
-  # a module to extend the JSI Schema Module of a schema which describes other schemas
-  module DescribesSchemaModule
-    # instantiates the given schema content as a JSI Schema.
+  # A module to extend the {SchemaModule} of a schema which describes other schemas (a {Schema::MetaSchema})
+  module SchemaModule::MetaSchemaModule
+    # Instantiates the given schema content as a JSI Schema.
     #
-    # see {JSI::Schema::DescribesSchema#new_schema}
+    # see {JSI::Schema::MetaSchema#new_schema}
     #
-    # @param (see JSI::Schema::DescribesSchema#new_schema)
-    # @return [JSI::Base, JSI::Schema] a JSI whose instance is the given schema_content and whose schemas
-    #   consist of this module's schema.
-    def new_schema(schema_content, **kw)
-      schema.new_schema(schema_content, **kw)
+    # @param (see Schema::MetaSchema#new_schema)
+    # @yield (see Schema::MetaSchema#new_schema)
+    # @return [JSI::Base subclass + JSI::Schema] a JSI which is a {JSI::Schema} whose content comes from
+    #   the given `schema_content` and whose schemas are inplace applicators of this module's schema
+    def new_schema(schema_content, **kw, &block)
+      schema.new_schema(schema_content, **kw, &block)
     end
 
-    # instantiates a given schema object as a JSI Schema and returns its JSI Schema Module.
-    #
-    # shortcut to chain {JSI::Schema::DescribesSchema#new_schema} + {Schema#jsi_schema_module}.
-    #
-    # @param (see JSI::Schema::DescribesSchema#new_schema)
-    # @return [Module, JSI::SchemaModule] the JSI Schema Module of the schema
-    def new_schema_module(schema_content, **kw)
-      schema.new_schema(schema_content, **kw).jsi_schema_module
+    # (see Schema::MetaSchema#new_schema_module)
+    def new_schema_module(schema_content, **kw, &block)
+      schema.new_schema(schema_content, **kw, &block).jsi_schema_module
     end
 
     # @return [Set<Module>]
-    attr_reader :schema_implementation_modules
+    def schema_implementation_modules
+      schema.schema_implementation_modules
+    end
   end
 
   # this module is a namespace for building schema classes and schema modules.
+  # @api private
   module SchemaClasses
-    extend Util::Memoize
-
     class << self
-      # @api private
+      # @private
       # @return [Set<Module>]
       def includes_for(instance)
         includes = Set[]
         includes << Base::ArrayNode if instance.respond_to?(:to_ary)
         includes << Base::HashNode if instance.respond_to?(:to_hash)
+        includes << Base::StringNode if instance.respond_to?(:to_str)
         includes.freeze
       end
 
@@ -82,14 +113,41 @@ module JSI
       # @param schemas [Enumerable<JSI::Schema>] schemas which the class will represent
       # @param includes [Enumerable<Module>] modules which will be included on the class
       # @return [Class subclassing JSI::Base]
-      def class_for_schemas(schemas, includes: )
-        schemas = SchemaSet.ensure_schema_set(schemas)
-        includes = Util.ensure_module_set(includes)
+      def class_for_schemas(schemas, includes: , mutable: )
+        @class_for_schemas_map[
+          schemas: SchemaSet.ensure_schema_set(schemas),
+          includes: Util.ensure_module_set(includes),
+          mutable: mutable,
+        ]
+      end
 
-        jsi_memoize(:class_for_schemas, schemas: schemas, includes: includes) do |schemas: , includes: |
-          Class.new(Base).instance_exec(schemas: schemas, includes: includes) do |schemas: , includes: |
+      private def class_for_schemas_compute(schemas: , includes: , mutable: )
+          Class.new(Base) do
             define_singleton_method(:jsi_class_schemas) { schemas }
             define_method(:jsi_schemas) { schemas }
+
+            define_singleton_method(:jsi_class_includes) { includes }
+
+            mutability_module = mutable ? Base::Mutable : Base::Immutable
+            conflicting_modules = Set[JSI::Base, mutability_module] + includes + schemas.map(&:jsi_schema_module)
+
+            include(mutability_module)
+
+            reader_modules = schemas.map do |schema|
+              JSI::SchemaClasses.schema_property_reader_module(schema, conflicting_modules: conflicting_modules)
+            end
+            reader_modules.each { |m| include m }
+            readers = reader_modules.map(&:jsi_property_readers).inject(Set[], &:merge).freeze
+            define_method(:jsi_property_readers) { readers }
+            define_singleton_method(:jsi_property_readers) { readers }
+
+            if mutable
+              writer_modules = schemas.map do |schema|
+                JSI::SchemaClasses.schema_property_writer_module(schema, conflicting_modules: conflicting_modules)
+              end
+              writer_modules.each { |m| include(m) }
+            end
+
             includes.each { |m| include(m) }
             schemas.each { |schema| include(schema.jsi_schema_module) }
             jsi_class = self
@@ -97,115 +155,119 @@ module JSI
 
             self
           end
-        end
       end
 
-      # a subclass of MetaschemaNode::BootstrapSchema with the given modules included
+      # a subclass of MetaSchemaNode::BootstrapSchema with the given modules included
       # @api private
       # @param modules [Set<Module>] schema implementation modules
       # @return [Class]
       def bootstrap_schema_class(modules)
-        modules = Util.ensure_module_set(modules)
-        jsi_memoize(__method__, modules: modules) do |modules: |
-          Class.new(MetaschemaNode::BootstrapSchema) do
+        @bootstrap_schema_class_map[
+          modules: Util.ensure_module_set(modules),
+        ]
+      end
+
+      private def bootstrap_schema_class_compute(modules: )
+          Class.new(MetaSchemaNode::BootstrapSchema) do
             define_singleton_method(:schema_implementation_modules) { modules }
             define_method(:schema_implementation_modules) { modules }
             modules.each { |mod| include(mod) }
 
             self
           end
-        end
       end
 
       # see {Schema#jsi_schema_module}
       # @api private
-      # @return [Module]
+      # @return [SchemaModule]
       def module_for_schema(schema)
         Schema.ensure_schema(schema)
-        jsi_memoize(:module_for_schema, schema: schema) do |schema: |
-          Module.new do
-            begin
-              define_singleton_method(:schema) { schema }
-
-              extend SchemaModule
-
-              schema.jsi_schema_instance_modules.each do |mod|
-                include(mod)
-              end
+        raise(Bug, "non-Base schema cannot have schema module: #{schema}") unless schema.is_a?(Base)
+        @schema_module_map[schema]
+      end
 
-              accessor_module = JSI::SchemaClasses.accessor_module_for_schema(schema,
-                conflicting_modules: Set[JSI::Base, JSI::Base::ArrayNode, JSI::Base::HashNode] +
-                  schema.jsi_schema_instance_modules,
-              )
-              include accessor_module
-
-              define_singleton_method(:jsi_property_accessors) { accessor_module.jsi_property_accessors }
-
-              @possibly_schema_node = schema
-              extend(SchemaModulePossibly)
-              schema.jsi_schemas.each do |schema_schema|
-                extend JSI::SchemaClasses.accessor_module_for_schema(schema_schema,
-                  conflicting_modules: Set[Module, SchemaModule, SchemaModulePossibly],
-                  setters: false,
-                )
-              end
-            end
-          end
+      # @private
+      # @deprecated after v0.7
+      def accessor_module_for_schema(schema, conflicting_modules: , setters: true)
+        Module.new do
+          include SchemaClasses.schema_property_reader_module(schema, conflicting_modules: conflicting_modules)
+          include SchemaClasses.schema_property_writer_module(schema, conflicting_modules: conflicting_modules) if setters
         end
       end
 
-      # a module of accessors for described property names of the given schema.
-      # getters are always defined. setters are defined by default.
+      # a module of readers for described property names of the given schema.
       #
-      # @api private
-      # @param schema [JSI::Schema] a schema for which to define accessors for any described property names
+      # @private
+      # @param schema [JSI::Schema] a schema for which to define readers for any described property names
       # @param conflicting_modules [Enumerable<Module>] an array of modules (or classes) which
       #   may be used alongside the accessor module. methods defined by any conflicting_module
       #   will not be defined as accessors.
-      # @param setters [Boolean] whether to define setter methods
       # @return [Module]
-      def accessor_module_for_schema(schema, conflicting_modules: , setters: true)
+      def schema_property_reader_module(schema, conflicting_modules: )
         Schema.ensure_schema(schema)
-        jsi_memoize(:accessor_module_for_schema, schema: schema, conflicting_modules: conflicting_modules, setters: setters) do |schema: , conflicting_modules: , setters: |
+        @schema_property_reader_module_map[schema: schema, conflicting_modules: conflicting_modules]
+      end
+
+      private def schema_property_reader_module_compute(schema: , conflicting_modules: )
           Module.new do
-            begin
-              define_singleton_method(:inspect) { '(JSI Schema Accessor Module)' }
+            readers = schema.described_object_property_names.select do |name|
+              Util.ok_ruby_method_name?(name) &&
+                !conflicting_modules.any? { |m| m.method_defined?(name) || m.private_method_defined?(name) }
+            end.to_set.freeze
 
-              conflicting_instance_methods = conflicting_modules.map do |mod|
-                mod.instance_methods + mod.private_instance_methods
-              end.inject(Set.new, &:|)
+            define_singleton_method(:inspect) { "(JSI Schema Property Reader Module: #{readers.join(', ')})" }
 
-              accessors_to_define = schema.described_object_property_names.select do |name|
-                # must not conflict with any method on a conflicting module
-                Util.ok_ruby_method_name?(name) && !conflicting_instance_methods.any? { |mn| mn.to_s == name }
-              end.to_set.freeze
+            define_singleton_method(:jsi_property_readers) { readers }
 
-              define_singleton_method(:jsi_property_accessors) { accessors_to_define }
+            readers.each do |property_name|
+              define_method(property_name) do |**kw, &block|
+                self[property_name, **kw, &block]
+              end
+            end
+          end
+      end
 
-              accessors_to_define.each do |property_name|
-                define_method(property_name) do |**kw|
-                  self[property_name, **kw]
-                end
-                if setters
+      # a module of writers for described property names of the given schema.
+      # @private
+      def schema_property_writer_module(schema, conflicting_modules: )
+        Schema.ensure_schema(schema)
+        @schema_property_writer_module_map[schema: schema, conflicting_modules: conflicting_modules]
+      end
+
+      private def schema_property_writer_module_compute(schema: , conflicting_modules: )
+          Module.new do
+            define_singleton_method(:inspect) { '(JSI Schema Property Writer Module)' }
+
+            writers = schema.described_object_property_names.select do |name|
+              writer = "#{name}="
+              Util.ok_ruby_method_name?(name) &&
+                !conflicting_modules.any? { |m| m.method_defined?(writer) || m.private_method_defined?(writer) }
+            end.to_set.freeze
+
+            define_singleton_method(:jsi_property_writers) { writers }
+
+            writers.each do |property_name|
                   define_method("#{property_name}=") do |value|
                     self[property_name] = value
                   end
-                end
-              end
             end
           end
-        end
       end
     end
+
+    @class_for_schemas_map          = Hash.new { |h, k| h[k] = class_for_schemas_compute(**k) }
+    @bootstrap_schema_class_map      = Hash.new { |h, k| h[k] = bootstrap_schema_class_compute(**k) }
+    @schema_module_map                = Hash.new { |h, schema| h[schema] = SchemaModule.new(schema) }
+    @schema_property_reader_module_map = Hash.new { |h, k| h[k] = schema_property_reader_module_compute(**k) }
+    @schema_property_writer_module_map = Hash.new { |h, k| h[k] = schema_property_writer_module_compute(**k) }
   end
 
-  # a JSI Schema module and a JSI::NotASchemaModule are both a SchemaModulePossibly.
-  # this module provides a #[] method.
-  module SchemaModulePossibly
-    attr_reader :possibly_schema_node
+  # connecting {SchemaModule}s via {SchemaModule::Connection}s
+  module SchemaModule::Connects
+    attr_reader :jsi_node
 
     # a name relative to a named schema module of an ancestor schema.
-    # for example, if `Foos = JSI::JSONSchemaOrgDraft07.new_schema_module({'items' => {}})`
+    # for example, if `Foos = JSI::JSONSchemaDraft07.new_schema_module({'items' => {}})`
     # then the module `Foos.items` will have a name_from_ancestor of `"Foos.items"`
     # @api private
     # @return [String, nil]
@@ -216,7 +278,7 @@ module JSI
       name = named_ancestor_schema.jsi_schema_module.name
       ancestor = named_ancestor_schema
       tokens.each do |token|
-        if ancestor.jsi_schemas.any? { |s| s.jsi_schema_module.jsi_property_accessors.include?(token) }
+        if ancestor.jsi_property_readers.include?(token)
           name += ".#{token}"
         elsif [String, Numeric, TrueClass, FalseClass, NilClass].any? { |m| token.is_a?(m) }
           name += "[#{token.inspect}]"
@@ -225,22 +287,28 @@ module JSI
         end
         ancestor = ancestor[token]
       end
-      name
+      name.freeze
     end
 
-    # subscripting a JSI schema module or a NotASchemaModule will subscript the node, and
+    # Subscripting a JSI schema module or a {SchemaModule::Connection} will subscript its node, and
     # if the result is a JSI::Schema, return the JSI Schema module of that schema; if it is a JSI::Base,
-    # return a NotASchemaModule; or if it is another value (a basic type), return that value.
+    # return a SchemaModule::Connection; or if it is another value (a basic type), return that value.
     #
     # @param token [Object]
-    # @return [Module, NotASchemaModule, Object]
-    def [](token, **kw)
+    # @yield If the token identifies a schema and a block is given,
+    #   it is evaluated in the context of the schema's JSI schema module
+    #   using [Module#module_exec](https://ruby-doc.org/core/Module.html#method-i-module_exec).
+    # @return [SchemaModule, SchemaModule::Connection, Object]
+    def [](token, **kw, &block)
       raise(ArgumentError) unless kw.empty? # TODO remove eventually (keyword argument compatibility)
-      sub = @possibly_schema_node[token]
+      sub = @jsi_node[token]
       if sub.is_a?(JSI::Schema)
+        sub.jsi_schema_module_exec(&block) if block
         sub.jsi_schema_module
+      elsif block
+        raise(ArgumentError, "block given but token #{token.inspect} does not identify a schema")
       elsif sub.is_a?(JSI::Base)
-        NotASchemaModule.new(sub)
+        SchemaModule::Connection.new(sub)
       else
         sub
       end
@@ -250,49 +318,50 @@ module JSI
 
     # @return [Array<JSI::Schema, Array>, nil]
     def named_ancestor_schema_tokens
-      schema_ancestors = possibly_schema_node.jsi_ancestor_nodes
+      schema_ancestors = @jsi_node.jsi_ancestor_nodes
       named_ancestor_schema = schema_ancestors.detect { |jsi| jsi.is_a?(JSI::Schema) && jsi.jsi_schema_module.name }
       return nil unless named_ancestor_schema
-      tokens = possibly_schema_node.jsi_ptr.relative_to(named_ancestor_schema.jsi_ptr).tokens
+      tokens = @jsi_node.jsi_ptr.relative_to(named_ancestor_schema.jsi_ptr).tokens
       [named_ancestor_schema, tokens]
     end
   end
 
-  # a JSI Schema Module is a module which represents a schema. a NotASchemaModule represents
+  class SchemaModule
+    include Connects
+  end
+
+  # A JSI Schema Module is a module which represents a schema. A SchemaModule::Connection represents
   # a node in a schema's document which is not a schema, such as the 'properties'
   # object (which contains schemas but is not a schema).
   #
   # instances of this class act as a stand-in to allow users to subscript or call property accessors on
   # schema modules to refer to their subschemas' schema modules.
   #
-  # a NotASchemaModule is extended with the module_for_schema of the node's schema.
-  #
-  # NotASchemaModule holds a node which is not a schema. when subscripted, it subscripts
-  # its node. if the value is a JSI::Schema, its schema module is returned. if the value
-  # is another node, a NotASchemaModule for that node is returned. otherwise - when the
-  # value is a basic type - that value itself is returned.
-  class NotASchemaModule
+  # A SchemaModule::Connection has readers for property names described by the node's schemas.
+  class SchemaModule::Connection
+    include SchemaModule::Connects
+
     # @param node [JSI::Base]
     def initialize(node)
       raise(Bug, "node must be JSI::Base: #{node.pretty_inspect.chomp}") unless node.is_a?(JSI::Base)
       raise(Bug, "node must not be JSI::Schema: #{node.pretty_inspect.chomp}") if node.is_a?(JSI::Schema)
-      @possibly_schema_node = node
+      @jsi_node = node
       node.jsi_schemas.each do |schema|
-        extend(JSI::SchemaClasses.accessor_module_for_schema(schema, conflicting_modules: [NotASchemaModule, SchemaModulePossibly], setters: false))
+        extend(JSI::SchemaClasses.schema_property_reader_module(schema, conflicting_modules: [SchemaModule::Connection]))
       end
     end
 
-    include SchemaModulePossibly
-
     # @return [String]
     def inspect
       if name_from_ancestor
-        "#{name_from_ancestor} (JSI wrapper for Schema Module)"
+        -"#{name_from_ancestor} (#{self.class})"
       else
-        "(JSI wrapper for Schema Module: #{@possibly_schema_node.jsi_ptr.uri})"
+        -"(#{self.class}: #{@jsi_node.jsi_ptr.uri})"
       end
     end
 
-    alias_method :to_s, :inspect
+    def to_s
+      inspect
+    end
   end
 end

data/lib/jsi/schema_registry.rb

@@ -14,6 +14,7 @@ module JSI
 
     # an exception raised when a URI we are looking for has not been registered
     class ResourceNotFound < StandardError
+      attr_accessor :uri
     end
 
     def initialize
@@ -45,12 +46,12 @@ module JSI
       # allow for registration of resources at the root of a document whether or not they are schemas.
       # jsi_schema_base_uri at the root comes from the `uri` parameter to new_jsi / new_schema.
       if resource.jsi_schema_base_uri && resource.jsi_ptr.root?
-        register_single(resource.jsi_schema_base_uri, resource)
+        internal_store(resource.jsi_schema_base_uri, resource)
       end
 
       resource.jsi_each_descendent_node do |node|
         if node.is_a?(JSI::Schema) && node.schema_absolute_uri
-          register_single(node.schema_absolute_uri, node)
+          internal_store(node.schema_absolute_uri, node)
         end
       end
 
@@ -72,12 +73,18 @@ module JSI
     #
     # the block would normally load JSON from the filesystem or similar.
     #
-    # @param uri [Addressable::URI]
+    # @param uri [#to_str]
     # @yieldreturn [JSI::Base] a JSI instance containing the resource identified by the given uri
     # @return [void]
     def autoload_uri(uri, &block)
-      uri = Addressable::URI.parse(uri)
-      ensure_uri_absolute(uri)
+      uri = registration_uri(uri)
+      mutating
+      unless block
+        raise(ArgumentError, ["#{SchemaRegistry}#autoload_uri must be invoked with a block", "URI: #{uri}"].join("\n"))
+      end
+      if @autoload_uris.key?(uri)
+        raise(Collision, ["already registered URI for autoload", "URI: #{uri}", "loader: #{@autoload_uris[uri]}"].join("\n"))
+      end
       @autoload_uris[uri] = block
       nil
     end
@@ -86,32 +93,50 @@ module JSI
     # @return [JSI::Base]
     # @raise [JSI::SchemaRegistry::ResourceNotFound]
     def find(uri)
-      uri = Addressable::URI.parse(uri)
-      ensure_uri_absolute(uri)
-      if @autoload_uris.key?(uri) && !@resources.key?(uri)
+      uri = registration_uri(uri)
+      if @autoload_uris.key?(uri)
         autoloaded = @autoload_uris[uri].call
         register(autoloaded)
+        @autoload_uris.delete(uri)
       end
-      registered_uris = @resources.keys
-      if !registered_uris.include?(uri)
-        if @autoload_uris.key?(uri)
+      if !@resources.key?(uri)
+        if autoloaded
           msg = [
             "URI #{uri} was registered with autoload_uri but the result did not contain a resource with that URI.",
             "the resource resulting from autoload_uri was:",
             autoloaded.pretty_inspect.chomp,
           ]
         else
-          msg = ["URI #{uri} is not registered. registered URIs:", *registered_uris]
+          msg = ["URI #{uri} is not registered. registered URIs:", *(@resources.keys | @autoload_uris.keys)]
         end
-        raise(ResourceNotFound, msg.join("\n"))
+        raise(ResourceNotFound.new(msg.join("\n")).tap { |e| e.uri = uri })
       end
       @resources[uri]
     end
 
+    def inspect
+      [
+        "#<#{self.class}",
+        *[['resources', @resources.keys], ['autoload', @autoload_uris.keys]].map do |label, uris|
+          [
+            "  #{label} (#{uris.size})#{uris.empty? ? "" : ":"}",
+            *uris.map do |uri|
+              "    #{uri}"
+            end,
+          ]
+        end.inject([], &:+),
+        '>',
+      ].join("\n").freeze
+    end
+
+    def to_s
+      inspect
+    end
+
     def dup
       self.class.new.tap do |reg|
         @resources.each do |uri, resource|
-          reg.register_single(uri, resource)
+          reg.internal_store(uri, resource)
         end
         @autoload_uris.each do |uri, autoload|
           reg.autoload_uri(uri, &autoload)
@@ -119,13 +144,21 @@ module JSI
       end
     end
 
+    def freeze
+      @resources.freeze
+      @autoload_uris.freeze
+      @resources_mutex = nil
+      super
+    end
+
     protected
     # @param uri [Addressable::URI]
     # @param resource [JSI::Base]
     # @return [void]
-    def register_single(uri, resource)
+    def internal_store(uri, resource)
+      mutating
       @resources_mutex.synchronize do
-        ensure_uri_absolute(uri)
+        uri = registration_uri(uri)
         if @resources.key?(uri)
           if @resources[uri] != resource
             raise(Collision, "URI collision on #{uri}.\nexisting:\n#{@resources[uri].pretty_inspect.chomp}\nnew:\n#{resource.pretty_inspect.chomp}")
@@ -139,13 +172,29 @@ module JSI
 
     private
 
-    def ensure_uri_absolute(uri)
+    # registration URIs are
+    # - absolute
+    #   - without fragment
+    #   - not relative
+    # - normalized
+    # - frozen
+    # @param uri [#to_str]
+    # @return [Addressable::URI]
+    def registration_uri(uri)
+      uri = Util.uri(uri)
       if uri.fragment
         raise(NonAbsoluteURI, "#{self.class} only registers absolute URIs. cannot access URI with fragment: #{uri}")
       end
       if uri.relative?
         raise(NonAbsoluteURI, "#{self.class} only registers absolute URIs. cannot access relative URI: #{uri}")
       end
+      uri.normalize.freeze
+    end
+
+    def mutating
+      if frozen?
+        raise(FrozenError, "cannot modify frozen #{self.class}")
+      end
     end
   end
 end