lutaml-hal 0.1.6 → 0.1.8

data/lib/lutaml/hal/model_register.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
+require 'cgi'
 require_relative 'errors'
+require_relative 'endpoint_configuration'
 
 module Lutaml
   module Hal
-    # Register to map URL patterns to model classes
+    # Register to map URL patterns to model classes with EndpointParameter support
     class ModelRegister
       attr_accessor :models, :client, :register_name
 
@@ -15,12 +17,22 @@ module Lutaml
         @models = {}
       end
 
-      # Register a model with its base URL pattern
-      def add_endpoint(id:, type:, url:, model:, query_params: nil)
+      # Register a model with its URL pattern and parameters
+      def add_endpoint(id:, type:, url:, model:, parameters: [])
         @models ||= {}
 
         raise "Model with ID #{id} already registered" if @models[id]
-        if @models.values.any? { |m| m[:url] == url && m[:type] == type && m[:query_params] == query_params }
+
+        # Validate all parameters
+        parameters.each(&:validate!)
+
+        # Ensure path parameters in URL have corresponding parameter definitions
+        validate_path_parameters(url, parameters)
+
+        # Check for duplicate endpoints
+        if @models.values.any? do |m|
+          m[:url] == url && m[:type] == type && parameters_match?(m[:parameters], parameters)
+        end
           raise "Duplicate URL pattern #{url} for type #{type}"
         end
 
@@ -29,20 +41,52 @@ module Lutaml
           type: type,
           url: url,
           model: model,
-          query_params: query_params
+          parameters: parameters
         }
       end
 
+      # Register an endpoint using block configuration syntax
+      def register_endpoint(id, model, type: :index)
+        config = EndpointConfiguration.new
+        yield(config) if block_given?
+
+        raise ArgumentError, 'Endpoint path must be configured' unless config.endpoint_path
+
+        add_endpoint(
+          id: id,
+          type: type,
+          url: config.endpoint_path,
+          model: model,
+          parameters: config.parameters || []
+        )
+      end
+
       # Resolve and cast data to the appropriate model based on URL
       def fetch(endpoint_id, **params)
         endpoint = @models[endpoint_id] || raise("Unknown endpoint: #{endpoint_id}")
         raise 'Client not configured' unless client
 
-        url = interpolate_url(endpoint[:url], params)
-        response = client.get(build_url_with_query_params(url, endpoint[:query_params], params))
+        # Process parameters through EndpointParameter objects
+        processed_params = process_parameters(endpoint[:parameters], params)
+
+        # Build URL with path parameters
+        url = build_url_with_path_params(endpoint[:url], processed_params[:path])
+
+        # Add query parameters
+        final_url = build_url_with_query_params(url, processed_params[:query])
+
+        # Make request with headers
+        response = if processed_params[:headers].any?
+                     client.get_with_headers(final_url, processed_params[:headers])
+                   else
+                     client.get(final_url)
+                   end
 
         realized_model = endpoint[:model].from_json(response.to_json)
 
+        # Store embedded data for later resolution
+        realized_model.instance_variable_set(:@_embedded, response['_embedded']) if response['_embedded']
+
         mark_model_links_with_register(realized_model)
         realized_model
       end
@@ -98,46 +142,144 @@ module Lutaml
 
       private
 
-      def interpolate_url(url_template, params)
-        params.reduce(url_template) do |url, (key, value)|
-          url.gsub("{#{key}}", value.to_s)
+      def process_parameters(parameter_definitions, provided_params)
+        result = { path: {}, query: {}, headers: {}, cookies: {} }
+
+        parameter_definitions.each do |param_def|
+          param_name = param_def.name.to_sym
+          provided_value = provided_params[param_name]
+
+          # Check required parameters
+          if param_def.required && provided_value.nil?
+            raise ArgumentError, "Required parameter '#{param_def.name}' is missing"
+          end
+
+          # Use default value if not provided
+          value = provided_value || param_def.default_value
+
+          # Skip if still nil and not required
+          next if value.nil?
+
+          # Validate parameter value
+          unless param_def.validate_value(value)
+            raise ArgumentError, "Invalid value for parameter '#{param_def.name}': #{value}"
+          end
+
+          # Store in appropriate category
+          case param_def.location
+          when :path
+            result[:path][param_def.name] = value
+          when :query
+            result[:query][param_def.name] = value
+          when :header
+            result[:headers][param_def.name] = value
+          when :cookie
+            result[:cookies][param_def.name] = value
+          end
         end
+
+        result
       end
 
-      def build_url_with_query_params(base_url, query_params_template, params)
-        return base_url unless query_params_template
+      def validate_path_parameters(url, parameters)
+        # Extract path parameter names from URL template
+        url_params = url.scan(/\{([^}]+)\}/).flatten
+
+        # Find path parameters in parameter definitions
+        path_params = parameters.select(&:path_parameter?).map(&:name)
+
+        # Check that all URL parameters have definitions
+        missing_params = url_params - path_params
+        unless missing_params.empty?
+          raise ArgumentError, "URL contains undefined path parameters: #{missing_params.join(', ')}"
+        end
+
+        # Check that all path parameter definitions are used in URL
+        unused_params = path_params - url_params
+        return if unused_params.empty?
 
-        query_params = []
-        query_params_template.each do |param_name, param_template|
-          # If the template is like {page}, look for the param in the passed params
-          if param_template.is_a?(String) && param_template.match?(/\{(.+)\}/)
-            param_key = param_template.match(/\{(.+)\}/)[1]
-            query_params << "#{param_name}=#{params[param_key.to_sym]}" if params[param_key.to_sym]
+        raise ArgumentError, "Path parameters defined but not used in URL: #{unused_params.join(', ')}"
+      end
+
+      def parameters_match?(params1, params2)
+        return true if params1.nil? && params2.nil?
+        return false if params1.nil? || params2.nil?
+        return false if params1.length != params2.length
+
+        params1.zip(params2).all? do |p1, p2|
+          p1.name == p2.name && p1.location == p2.location
+        end
+      end
+
+      def build_url_with_path_params(url_template, path_params)
+        path_params.reduce(url_template) do |url, (key, value)|
+          url.gsub("{#{key}}", value.to_s)
+        end
+      end
+
+      def build_url_with_query_params(base_url, query_params, params = nil)
+        # Handle both 2-argument and 3-argument calls for backward compatibility
+        if params.nil?
+          # 2-argument call: query_params is the final query parameters
+          final_query_params = query_params
+        else
+          # 3-argument call: query_params is template, params contains values
+          final_query_params = {}
+          query_params.each do |key, template_value|
+            if template_value.is_a?(String) && template_value.match?(/\{(\w+)\}/)
+              param_name = template_value.match(/\{(\w+)\}/)[1].to_sym
+              final_query_params[key] = params[param_name] if params[param_name]
+            else
+              final_query_params[key] = template_value
+            end
           end
         end
 
-        query_params.any? ? "#{base_url}?#{query_params.join('&')}" : base_url
+        return base_url if final_query_params.empty?
+
+        query_string = final_query_params.map { |key, value| "#{key}=#{CGI.escape(value.to_s)}" }.join('&')
+        "#{base_url}?#{query_string}"
+      end
+
+      # Interpolate path parameters in a URL template
+      def interpolate_url(url_template, params)
+        params.reduce(url_template) do |url, (key, value)|
+          url.gsub("{#{key}}", value.to_s)
+        end
       end
 
       def find_matching_model_class(href)
-        @models.values.find do |model_data|
+        # Find all matching patterns and select the most specific one (longest pattern)
+        matching_models = @models.values.select do |model_data|
           matches_url_with_params?(model_data, href)
-        end&.[](:model)
+        end
+
+        return nil if matching_models.empty?
+
+        # Sort by pattern length (descending) to get the most specific match first
+        result = matching_models.max_by { |model_data| model_data[:url].length }
+
+        result[:model]
       end
 
       def matches_url_with_params?(model_data, href)
         pattern = model_data[:url]
-        query_params = model_data[:query_params]
+        parameters = model_data[:parameters]
 
         return false unless pattern && href
 
         uri = parse_href_uri(href)
         pattern_path = extract_pattern_path(pattern)
 
-        return false unless path_matches?(pattern_path, uri.path)
-        return true unless query_params
+        path_match_result = path_matches?(pattern_path, uri.path)
+        return false unless path_match_result
 
-        query_params_match?(query_params, parse_query_params(uri.query))
+        # Check query parameters if any are defined
+        query_params = parameters.select(&:query_parameter?)
+        return true if query_params.empty?
+
+        parsed_query = parse_query_params(uri.query)
+        query_params_match?(query_params, parsed_query)
       end
 
       def parse_href_uri(href)
@@ -150,25 +292,27 @@ module Lutaml
       end
 
       def path_matches?(pattern_path, href_path)
-        if href_path.start_with?('/') && client&.api_url
-          path_pattern = extract_path(pattern_path)
-          pattern_match?(path_pattern, href_path) || pattern_match?(pattern_path, href_path)
-        else
-          pattern_match?(pattern_path, href_path)
-        end
+        pattern_match?(pattern_path, href_path)
       end
 
       def query_params_match?(expected_params, actual_params)
-        expected_params.all? do |param_name, param_pattern|
-          actual_value = actual_params[param_name]
-          next false unless actual_value
+        # Query parameters should be optional unless marked as required
+        expected_params.all? do |param_def|
+          actual_value = actual_params[param_def.name]
 
-          template_param?(param_pattern) || actual_value == param_pattern.to_s
-        end
-      end
+          # Required parameters must be present
+          if param_def.required
+            return false if actual_value.nil?
 
-      def template_param?(param_pattern)
-        param_pattern.is_a?(String) && param_pattern.match?(/\{.+\}/)
+            return param_def.validate_value(actual_value)
+          end
+
+          # Optional parameters are always considered matching if not present
+          return true if actual_value.nil?
+
+          # If present, they must be valid
+          param_def.validate_value(actual_value)
+        end
       end
 
       def parse_query_params(query_string)
@@ -176,37 +320,19 @@ module Lutaml
 
         query_string.split('&').each_with_object({}) do |param, hash|
           key, value = param.split('=', 2)
-          hash[key] = value if key
+          hash[key] = CGI.unescape(value) if key && value
         end
       end
 
-      def matches_url?(pattern, href)
-        return false unless pattern && href
-
-        if href.start_with?('/') && client&.api_url
-          # Try both with and without the API endpoint prefix
-          path_pattern = extract_path(pattern)
-          return pattern_match?(path_pattern, href) ||
-                 pattern_match?(pattern, "#{client.api_url}#{href}")
-        end
-
-        pattern_match?(pattern, href)
-      end
-
-      def extract_path(pattern)
-        return pattern unless client&.api_url && pattern.start_with?(client.api_url)
-
-        pattern.sub(client.api_url, '')
-      end
-
-      # Match URL pattern (supports * wildcards and {param} templates)
+      # Match URL pattern (supports {param} templates)
       def pattern_match?(pattern, url)
         return false unless pattern && url
 
         # Convert {param} to wildcards for matching
         pattern_with_wildcards = pattern.gsub(/\{[^}]+\}/, '*')
-        # Convert * wildcards to regex pattern - use .+ instead of [^/]+ to match query parameters
-        regex = Regexp.new("^#{pattern_with_wildcards.gsub('*', '.+')}$")
+        # Convert * wildcards to regex pattern - use [^/]+ to match path segments, not across slashes
+        # This ensures that {param} only matches a single path segment
+        regex = Regexp.new("^#{pattern_with_wildcards.gsub('*', '[^/]+')}$")
 
         Hal.debug_log("pattern_match?: regex: #{regex.inspect}")
         Hal.debug_log("pattern_match?: href to match #{url}")

data/lib/lutaml/hal/page.rb

@@ -23,6 +23,9 @@ module Lutaml
       def self.inherited(subclass)
         super
 
+        # Skip automatic link creation for anonymous classes (used in tests)
+        return unless subclass.name
+
         page_links_symbols = %i[self next prev first last up]
         subclass_name = subclass.name
         subclass.class_eval do

data/lib/lutaml/hal/resource.rb

@@ -2,6 +2,8 @@
 
 require 'lutaml/model'
 require_relative 'link'
+require_relative 'link_class_factory'
+require_relative 'link_set_class_factory'
 
 module Lutaml
   module Hal
@@ -11,6 +13,28 @@ module Lutaml
       # will be used to resolve links unless overriden in resource#realize()
       attr_accessor Hal::REGISTER_ID_ATTR_NAME.to_sym
 
+      # Access embedded data if available
+      def embedded_data
+        @_embedded
+      end
+
+      # Check if embedded data exists for a given key
+      def has_embedded?(key)
+        embedded_data&.key?(key.to_s)
+      end
+
+      # Get embedded content for a specific key
+      def get_embedded(key)
+        embedded_data&.[](key.to_s)
+      end
+
+      # Create a resource instance from embedded JSON data
+      def self.from_embedded(json_data, register_name = nil)
+        instance = from_json(json_data.to_json)
+        instance.instance_variable_set("@#{Hal::REGISTER_ID_ATTR_NAME}", register_name) if register_name
+        instance
+      end
+
       class << self
         attr_accessor :link_definitions
 
@@ -18,7 +42,6 @@ module Lutaml
         def inherited(subclass)
           super
           subclass.class_eval do
-            create_link_set_class
             init_links_definition
           end
         end
@@ -36,21 +59,47 @@ module Lutaml
                      link_set_class: nil,
                      collection: false,
                      type: :link)
+          # Validate required parameters
+          raise ArgumentError, 'realize_class parameter is required' if realize_class.nil?
+
           # Use the provided "key" as the attribute name
           attribute_name = attr_key.to_sym
 
           Hal.debug_log "Defining HAL link for `#{attr_key}` with realize class `#{realize_class}`"
 
+          # Normalize realize_class to a string for consistent handling
+          # Support both Class objects (when autoload is available) and strings (for delayed interpretation)
+          realize_class_name = case realize_class
+                               when Class
+                                 realize_class.name.split('::').last # Use simple name from actual class
+                               when String
+                                 realize_class # Use string as-is for lazy resolution
+                               else
+                                 raise ArgumentError,
+                                       "realize_class must be a Class or String, got #{realize_class.class}"
+                               end
+
+          # Create a dynamic LinkSet class if `link_set_class:` is not provided.
+          # This must happen BEFORE creating the Link class to ensure proper order
+          link_set_klass = link_set_class || create_link_set_class
+
+          # Ensure it was actually created
+          raise 'Failed to create LinkSet class' if link_set_klass.nil?
+
           # Create a dynamic Link subclass name based on "realize_class", the
           # class to realize for a Link object, if `link_class:` is not provided.
-          link_klass = link_class || create_link_class(realize_class)
+          link_klass = link_class || create_link_class(realize_class_name)
 
-          # Create a dynamic LinkSet class if `link_set_class:` is not provided.
+          # Now add the link to the LinkSet class
           unless link_set_class
-            link_set_klass = link_set_class || get_link_set_class
             link_set_klass.class_eval do
               # Declare the corresponding lutaml-model attribute
-              attribute attribute_name, link_klass, collection: collection
+              # Pass collection parameter correctly to the attribute definition
+              if collection
+                attribute attribute_name, link_klass, collection: true
+              else
+                attribute attribute_name, link_klass
+              end
 
               # Define the mapping for the attribute
               key_value do
@@ -73,69 +122,26 @@ module Lutaml
         end
 
         # This method obtains the Links class that holds the Link classes
+        # Delegates to LinkSetClassFactory for simplified implementation
         def get_link_set_class
-          parent_klass_name = name.split('::')[0..-2].join('::')
-          child_klass_name = "#{name.split('::').last}LinkSet"
-          klass_name = [parent_klass_name, child_klass_name].join('::')
-
-          raise unless Object.const_defined?(klass_name)
-
-          Object.const_get(klass_name)
+          create_link_set_class
         end
 
-        private
-
         # The "links" class holds the `_links` object which contains
         # the resource-linked Link classes
+        # Delegates to LinkSetClassFactory for simplified implementation
         def create_link_set_class
-          parent_klass_name = name.split('::')[0..-2].join('::')
-          child_klass_name = "#{name.split('::').last}LinkSet"
-          klass_name = [parent_klass_name, child_klass_name].join('::')
-
-          Hal.debug_log "Creating link set class #{klass_name}"
-
-          # Check if the LinkSet class is already defined, return if so
-          return Object.const_get(klass_name) if Object.const_defined?(klass_name)
-
-          # Define the LinkSet class dynamically as a normal Lutaml::Model class
-          # since it is not a Resource.
-          klass = Class.new(Lutaml::Hal::LinkSet)
-          parent_klass = !parent_klass_name.empty? ? Object.const_get(parent_klass_name) : Object
-          parent_klass.const_set(child_klass_name, klass)
-
-          # Define the LinkSet class with mapping inside the current class
-          class_eval do
-            attribute :links, klass
-            key_value do
-              map '_links', to: :links
-            end
-          end
+          LinkSetClassFactory.create_for(self)
         end
 
         def init_links_definition
           @link_definitions = {}
         end
 
-        # This is a Link class that helps us realize the targeted class
+        # Creates a Link class that helps us realize the targeted class
+        # Delegates to LinkClassFactory for simplified implementation
         def create_link_class(realize_class_name)
-          parent_klass_name = name.split('::')[0..-2].join('::')
-          child_klass_name = "#{realize_class_name.split('::').last}Link"
-          klass_name = [parent_klass_name, child_klass_name].join('::')
-
-          Hal.debug_log "Creating link class #{klass_name} for #{realize_class_name}"
-
-          return Object.const_get(klass_name) if Object.const_defined?(klass_name)
-
-          # Define the link class dynamically
-          klass = Class.new(Link) do
-            # Define the link class with the specified key and class
-            attribute :type, :string, default: realize_class_name
-          end
-
-          parent_klass = !parent_klass_name.empty? ? Object.const_get(parent_klass_name) : Object
-          parent_klass.const_set(child_klass_name, klass)
-
-          klass
+          LinkClassFactory.create_for(self, realize_class_name)
         end
       end
     end

data/lib/lutaml/hal/type_resolver.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Hal
+    # Module that provides lazy type resolution functionality for dynamically created classes
+    # This solves the class loading order problem where HAL type names would be inconsistent
+    # depending on file loading order.
+    module TypeResolver
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        attr_reader :realize_class_name
+
+        def setup_type_resolution(realize_class_name)
+          @realize_class_name = realize_class_name
+          @resolved_type_name = nil
+        end
+
+        # Lazy resolution at class level - only happens once per class
+        def resolved_type_name
+          @resolved_type_name ||= resolve_type_name(@realize_class_name)
+        end
+
+        private
+
+        def resolve_type_name(class_name_string)
+          return class_name_string unless class_name_string.is_a?(String)
+
+          # Try simple name first (preferred for HAL output)
+          begin
+            Object.const_get(class_name_string)
+            class_name_string
+          rescue NameError
+            # Try within current module namespace
+            begin
+              current_module = name.split('::')[0..-2].join('::')
+              unless current_module.empty?
+                Object.const_get(current_module).const_get(class_name_string)
+                return class_name_string
+              end
+            rescue NameError
+              # Continue to fallback
+            end
+
+            # Fallback: return the original string (may be fully qualified)
+            class_name_string
+          end
+        end
+      end
+
+      # Override the type getter to use class-level lazy resolution
+      def type
+        @type || self.class.resolved_type_name
+      end
+    end
+  end
+end

data/lib/lutaml/hal/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Hal
-    VERSION = '0.1.6'
+    VERSION = '0.1.8'
   end
 end

data/lib/lutaml/hal.rb

@@ -15,6 +15,7 @@ end
 
 require_relative 'hal/version'
 require_relative 'hal/errors'
+require_relative 'hal/endpoint_parameter'
 require_relative 'hal/link'
 require_relative 'hal/link_set'
 require_relative 'hal/resource'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-hal
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-03 00:00:00.000000000 Z
+date: 2025-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -79,13 +79,18 @@ files:
 - lib/lutaml-hal.rb
 - lib/lutaml/hal.rb
 - lib/lutaml/hal/client.rb
+- lib/lutaml/hal/endpoint_configuration.rb
+- lib/lutaml/hal/endpoint_parameter.rb
 - lib/lutaml/hal/errors.rb
 - lib/lutaml/hal/global_register.rb
 - lib/lutaml/hal/link.rb
+- lib/lutaml/hal/link_class_factory.rb
 - lib/lutaml/hal/link_set.rb
+- lib/lutaml/hal/link_set_class_factory.rb
 - lib/lutaml/hal/model_register.rb
 - lib/lutaml/hal/page.rb
 - lib/lutaml/hal/resource.rb
+- lib/lutaml/hal/type_resolver.rb
 - lib/lutaml/hal/version.rb
 homepage: https://github.com/lutaml/lutaml-hal
 licenses: