lutaml-hal 0.1.7 → 0.1.8

data/lib/lutaml/hal/client.rb

@@ -57,6 +57,30 @@ module Lutaml
         raise LinkResolutionError, "Resource not found: #{e.message}"
       end
 
+      # Make a GET request with custom headers
+      def get_with_headers(url, headers = {})
+        cache_key = "#{url}:#{headers.to_json}"
+
+        return @cache[cache_key] if @cache_enabled && @cache.key?(cache_key)
+
+        @last_response = @connection.get(url) do |req|
+          headers.each { |key, value| req.headers[key] = value }
+        end
+
+        response = handle_response(@last_response, url)
+
+        @cache[cache_key] = response if @cache_enabled
+        response
+      rescue Faraday::ConnectionFailed => e
+        raise ConnectionError, "Connection failed: #{e.message}"
+      rescue Faraday::TimeoutError => e
+        raise TimeoutError, "Request timed out: #{e.message}"
+      rescue Faraday::ParsingError => e
+        raise ParsingError, "Response parsing error: #{e.message}"
+      rescue Faraday::Adapter::Test::Stubs::NotFound => e
+        raise LinkResolutionError, "Resource not found: #{e.message}"
+      end
+
       private
 
       def create_connection

data/lib/lutaml/hal/endpoint_configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Hal
+    # Configuration object for endpoint registration with EndpointParameter support
+    class EndpointConfiguration
+      attr_reader :endpoint_path, :parameters
+
+      def initialize
+        @endpoint_path = nil
+        @parameters = []
+      end
+
+      # Set the endpoint path
+      def path(path_string)
+        @endpoint_path = path_string
+      end
+
+      # Add a parameter to this endpoint
+      def add_parameter(parameter)
+        @parameters << parameter
+      end
+
+      # Add multiple parameters
+      def parameters=(param_list)
+        @parameters = param_list || []
+      end
+
+      # DSL method to add path parameter
+      def path_parameter(name, **options)
+        add_parameter(EndpointParameter.path(name, **options))
+      end
+
+      # DSL method to add query parameter
+      def query_parameter(name, **options)
+        add_parameter(EndpointParameter.query(name, **options))
+      end
+
+      # DSL method to add header parameter
+      def header_parameter(name, **options)
+        add_parameter(EndpointParameter.header(name, **options))
+      end
+
+      # DSL method to add cookie parameter
+      def cookie_parameter(name, **options)
+        add_parameter(EndpointParameter.cookie(name, **options))
+      end
+    end
+  end
+end

data/lib/lutaml/hal/endpoint_parameter.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Hal
+    # OpenAPI-inspired parameter definition for HAL endpoints
+    class EndpointParameter
+      attr_reader :name, :location, :required, :schema, :description, :example
+
+      def initialize(name:, in:, required: nil, schema: {}, description: nil, example: nil)
+        @name = name.to_s
+        @location = validate_location(binding.local_variable_get(:in))
+        @required = determine_required(required, @location)
+        @schema = Schema.new(schema)
+        @description = description
+        @example = example
+
+        validate!
+      end
+
+      # Convenience constructors for different parameter types
+      def self.path(name, **options)
+        new(name: name, in: :path, **options)
+      end
+
+      def self.query(name, **options)
+        new(name: name, in: :query, **options)
+      end
+
+      def self.header(name, **options)
+        new(name: name, in: :header, **options)
+      end
+
+      def self.cookie(name, **options)
+        new(name: name, in: :cookie, **options)
+      end
+
+      # Parameter type checks
+      def path_parameter?
+        @location == :path
+      end
+
+      def query_parameter?
+        @location == :query
+      end
+
+      def header_parameter?
+        @location == :header
+      end
+
+      def cookie_parameter?
+        @location == :cookie
+      end
+
+      # Validate a parameter value against this parameter's schema
+      def validate_value(value)
+        @schema.validate(value)
+      end
+
+      # Get the default value for this parameter
+      def default_value
+        @schema.default
+      end
+
+      def validate!
+        # Path parameters must be required
+        raise ArgumentError, 'Path parameters must be required' if path_parameter? && !@required
+
+        @schema.validate_definition!
+      end
+
+      private
+
+      def validate_location(location)
+        valid_locations = %i[path query header cookie]
+        unless valid_locations.include?(location)
+          raise ArgumentError, "Invalid parameter location: #{location}. Must be one of: #{valid_locations.join(', ')}"
+        end
+
+        location
+      end
+
+      def determine_required(required, location)
+        return true if location == :path # Path parameters are always required
+
+        required.nil? ? false : required
+      end
+
+      # Schema validation and type checking
+      class Schema
+        attr_reader :type, :format, :enum, :minimum, :maximum, :min_length, :max_length,
+                    :pattern, :items, :default, :nullable
+
+        def initialize(definition = {})
+          @type = definition[:type] || :string
+          @format = definition[:format]
+          @enum = definition[:enum]
+          @minimum = definition[:minimum]
+          @maximum = definition[:maximum]
+          @min_length = definition[:min_length]
+          @max_length = definition[:max_length]
+          @pattern = definition[:pattern]
+          @items = definition[:items]
+          @default = definition[:default]
+          @nullable = definition[:nullable] || false
+        end
+
+        def validate(value)
+          return true if value.nil? && @nullable
+          return false if value.nil? && !@nullable
+
+          case @type
+          when :string
+            validate_string(value)
+          when :integer
+            validate_integer(value)
+          when :number
+            validate_number(value)
+          when :boolean
+            validate_boolean(value)
+          when :array
+            validate_array(value)
+          else
+            true
+          end
+        end
+
+        def validate_definition!
+          valid_types = %i[string integer number boolean array object]
+          raise ArgumentError, "Invalid schema type: #{@type}" unless valid_types.include?(@type)
+
+          return unless @type == :array && @items.nil?
+
+          raise ArgumentError, "Array type requires 'items' definition"
+        end
+
+        private
+
+        def validate_string(value)
+          return false unless value.is_a?(String)
+          return false if @min_length && value.length < @min_length
+          return false if @max_length && value.length > @max_length
+          return false if @pattern && !value.match?(@pattern)
+          return false if @enum && !@enum.include?(value)
+
+          true
+        end
+
+        def validate_integer(value)
+          int_value = value.is_a?(String) ? value.to_i : value
+          return false unless int_value.is_a?(Integer)
+          return false if @minimum && int_value < @minimum
+          return false if @maximum && int_value > @maximum
+          return false if @enum && !@enum.include?(int_value)
+
+          true
+        end
+
+        def validate_number(value)
+          num_value = value.is_a?(String) ? value.to_f : value
+          return false unless num_value.is_a?(Numeric)
+          return false if @minimum && num_value < @minimum
+          return false if @maximum && num_value > @maximum
+          return false if @enum && !@enum.include?(num_value)
+
+          true
+        end
+
+        def validate_boolean(value)
+          [true, false, 'true', 'false', '1', '0'].include?(value)
+        end
+
+        def validate_array(value)
+          return false unless value.is_a?(Array)
+          return false if @min_items && value.length < @min_items
+          return false if @max_items && value.length > @max_items
+
+          # Validate each item if items schema is provided
+          if @items
+            item_schema = Schema.new(@items)
+            return false unless value.all? { |item| item_schema.validate(item) }
+          end
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/hal/global_register.rb

@@ -39,6 +39,10 @@ module Lutaml
 
         @model_registers.delete(name)
       end
+
+      def unregister(name)
+        delete(name)
+      end
     end
   end
 end

data/lib/lutaml/hal/link.rb

@@ -24,7 +24,12 @@ module Lutaml
       # This method will use the global register according to the source of the Link object.
       # If the Link does not have a register, a register needs to be provided explicitly
       # via the `register:` parameter.
-      def realize(register: nil)
+      def realize(register: nil, parent_resource: nil)
+        # First check if embedded content is available
+        if parent_resource && (embedded_content = check_embedded_content(parent_resource, register))
+          return embedded_content
+        end
+
         register = find_register(register)
         raise "No register provided for link resolution (class: #{self.class}, href: #{href})" if register.nil?
 
@@ -34,6 +39,56 @@ module Lutaml
 
       private
 
+      def check_embedded_content(parent_resource, register = nil)
+        return nil unless parent_resource.respond_to?(:embedded_data)
+
+        # Try to find embedded content that matches this link
+        # Look for embedded content by matching the link's key or href pattern
+        embedded_data = parent_resource.embedded_data
+        return nil unless embedded_data
+
+        # Try to find matching embedded content
+        # This is a simplified approach - in practice, you might need more sophisticated matching
+        embedded_data.each_value do |content|
+          # If content is an array, check if any item matches this link
+          if content.is_a?(Array)
+            matching_item = content.find { |item| matches_embedded_item?(item) }
+            return create_embedded_resource(matching_item, parent_resource, register) if matching_item
+          elsif content.is_a?(Hash) && matches_embedded_item?(content)
+            return create_embedded_resource(content, parent_resource, register)
+          end
+        end
+
+        nil
+      end
+
+      def matches_embedded_item?(item)
+        return false unless item.is_a?(Hash)
+
+        # Check if the embedded item's self link matches this link's href
+        item_self_link = item.dig('_links', 'self', 'href')
+        return true if item_self_link == href
+
+        # Additional matching logic could be added here
+        false
+      end
+
+      def create_embedded_resource(embedded_item, _parent_resource, register = nil)
+        # Get the register to determine the appropriate model class
+        register = find_register(register)
+        return nil unless register
+
+        # Try to find the model class for this href
+        href_path = href.sub(register.client.api_url, '') if register.client
+        model_class = register.send(:find_matching_model_class, href_path)
+        return nil unless model_class
+
+        # Create the resource from embedded data
+        resource = model_class.from_embedded(embedded_item, instance_variable_get("@#{Hal::REGISTER_ID_ATTR_NAME}"))
+        register.send(:mark_model_links_with_register, resource)
+        resource
+      end
+
       def find_register(explicit_register)
         return explicit_register if explicit_register
 

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,35 +142,116 @@ 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]
-          else
-            # Fixed parameter - always include it
-            query_params << "#{param_name}=#{param_template}"
+        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)
         # Find all matching patterns and select the most specific one (longest pattern)
         matching_models = @models.values.select do |model_data|
-          matches = matches_url_with_params?(model_data, href)
-          matches
+          matches_url_with_params?(model_data, href)
         end
 
         return nil if matching_models.empty?
@@ -139,7 +264,7 @@ module Lutaml
 
       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
 
@@ -149,7 +274,9 @@ module Lutaml
         path_match_result = path_matches?(pattern_path, uri.path)
         return false unless path_match_result
 
-        return true unless query_params
+        # 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)
@@ -169,24 +296,23 @@ module Lutaml
       end
 
       def query_params_match?(expected_params, actual_params)
-        # Query parameters should be optional - if they're template parameters (like {page}),
-        # they don't need to be present in the actual URL
-        expected_params.all? do |param_name, param_pattern|
-          actual_value = actual_params[param_name]
-
-          # If it's a template parameter (like {page}), it's optional
-          if template_param?(param_pattern)
-            # Template parameters are always considered matching (they're optional)
-            true
-          else
-            # Non-template parameters must match exactly if present
-            actual_value == param_pattern.to_s
+        # Query parameters should be optional unless marked as required
+        expected_params.all? do |param_def|
+          actual_value = actual_params[param_def.name]
+
+          # Required parameters must be present
+          if param_def.required
+            return false if actual_value.nil?
+
+            return param_def.validate_value(actual_value)
           end
-        end
-      end
 
-      def template_param?(param_pattern)
-        param_pattern.is_a?(String) && param_pattern.match?(/\{.+\}/)
+          # 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)
@@ -194,30 +320,11 @@ module Lutaml
 
         query_string.split('&').each_with_object({}) do |param, hash|
           key, value = param.split('=', 2)
-          hash[key] = value if key
-        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}")
+          hash[key] = CGI.unescape(value) if key && value
         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