lutaml-hal 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da904351e361ae9657c850d5faf981c6b698583970ead3320f125fdf6078fcbb
-  data.tar.gz: 677a8d713e5c2499cd9250497ca2b6f2d9474e545a2d2b2989dbcd33802b5588
+  metadata.gz: b1006ba9c57ff945fa51c368b1ca12971d83fc47f668513a962da76811b6cc91
+  data.tar.gz: 4bc4bc6697181d9512604736ba42a6d4ce16d67d235ffd5ef79b481e09ca8243
 SHA512:
-  metadata.gz: d1d55faaa7c1f7d45b07a3d475b6908de807f7bed3bfebdfa32ce0ada2b91a1794f948046e0e0c554216f5e18219c07ee81dfb03a2ee0f5fb19e3367821e40fb
-  data.tar.gz: '07085ed8d705dfe5ff1893e1c9d2ab7bc87fe3b22e483dc14edfb1b89b2e54942e21fa38f6c1ff7910030fb57c6ecf198110fa70ef8447a49c377de2935873d8'
+  metadata.gz: befafec41b21cd9244ae937bdb5ce5e975a99bd708cd960e68b4db122554b73d73ef506bc82bda0961d196f10785957c10246d14607345d2e8239420571b1a58
+  data.tar.gz: e719a907ff8e198f797691829b4fab1280e866f8a403ca80945a55f0178d48a0737c274dc12f3052c635d96f53d7ca3663081f12359293638aa7d6b2d45f9845

data/README.adoc

@@ -71,6 +71,10 @@ A registry for managing HAL resource models and their endpoints. It allows you
 to register models, define their relationships, and fetch resources from the
 API.
 
+`Lutaml::Hal::GlobalRegister`::
+A global registry (Singleton) for managing ModelRegisters and facilitating model
+resolution across different resources. Its usage is optional.
+
 `Lutaml::Hal::Resource`::
 A base class for defining HAL resource models. It includes methods for
 defining attributes, links, and key-value mappings for resources.
@@ -96,6 +100,8 @@ At the data definition phase:
 . Define the API endpoint using the `Client` class.
 . Create a `ModelRegister` to manage the resource models and their
 respective endpoints.
+. (optional) Create a `GlobalRegister` to manage one or more `ModelRegister`
+  instances. It is necessary for automatic Link resolution.
 . Define the resource models using the `Resource` class.
 . Register the models with the `ModelRegister` and define their
 relationships using the `add_endpoint` method.
@@ -145,10 +151,38 @@ require 'lutaml-hal'
 
 # Create a new client with API endpoint
 client = Lutaml::Hal::Client.new(api_url: 'https://api.example.com')
-register = Lutaml::Hal::ModelRegister.new(client: client)
+register = Lutaml::Hal::ModelRegister.new(name: :my_model_register, client: client)
 # Or set client later, `register.client = client`
 ----
 
+The `name:` parameter is used to identify the `ModelRegister` instance.
+
+=== Creating a HAL global register
+
+The `GlobalRegister` class is a singleton that manages one or more
+`ModelRegister` instances.
+
+It is optional, but is required for automatic realization of models from Link
+objects. See <<fetching_resource_via_link_realization>> for more details.
+
+[source,ruby]
+----
+require 'lutaml-hal'
+
+# Create a new client with API endpoint
+client = Lutaml::Hal::Client.new(api_url: 'https://api.example.com')
+register = Lutaml::Hal::ModelRegister.new(name: :my_model_register, client: client)
+
+# Register the ModelRegister with the global register
+global_register = Lutaml::Hal::GlobalRegister.instance.register(:my_model_register, register)
+
+# Obtain the global register
+global_register.get(:my_model_register)
+
+# Delete a register mapping
+global_register.delete(:my_model_register)
+----
+
 
 === Defining HAL resource models
 
@@ -158,7 +192,7 @@ A HAL resource is defined by creating a subclass of the `Resource` class and
 defining its attributes, links, and key-value mappings.
 
 The `Resource` class is the base class for defining HAL resource models.
-It inherits from `Lutaml::Model::Serialization`, which provides data
+It inherits from `Lutaml::Model::Serializable`, which provides data
 modelling and serialization capabilities.
 
 The declaration of attributes, links, and key-value mappings for a HAL resource
@@ -780,16 +814,34 @@ product_index
 ====
 
 
+[[fetching_resource_via_link_realization]]
 === Fetching a resource via link realization
 
 Given a resource index that contains links to resources, the individual resource
 links can be "realized" as actual model instances through the
-`Link#realize(register)` method which dynamically retrieves the resource.
+`Link#realize(register:)` method which dynamically retrieves the resource.
 
 Given a `Link` object, the `realize` method fetches the resource from the API
 using the provided `register`.
 
-Syntax:
+There are two ways a resource gets realized from a `Link` object:
+
+* If a `Lutaml::Hal::GlobalRegister` is used, and the `Link` object originated
+from a fetch using a `ModelRegister` then the `realize` method has sufficient
+information to automatically fetch the resource from the API using the same
+`register`.
++
+NOTE: This relies on the `Hal::REGISTER_ID_ATTR_NAME` attribute to be set
+in the `ModelRegister` class. This attribute is used to identify the
+resource endpoint ID in the URL.
+
+* If a `GlobalRegister` is not used, even if the Link object originated
+from a fetch using a `ModelRegister`, the `realize` method does not have sufficient
+information to fetch the resource from the API using the same
+`register`. In this case an explicit `register` must be provided to the
+`realize(register: ...)` method.
+
+Syntax for standalone usage:
 
 [source,ruby]
 ----
@@ -813,12 +865,26 @@ NOTE: It is possible to use the `realize` method on a link object using another
 `ModelRegister` instance. This is useful when you want to resolve a link
 using a different API endpoint or a different set of resource models.
 
+Syntax when using a `GlobalRegister`:
+
+[source,ruby]
+----
+resource_index = model_register.fetch(:resource_index)
+resource_index.links.products.first.realize
+# => client.get('/resources/1')
+----
+
 .Dynamically realizing a resource from the collection using links
 [example]
 ====
 [source,ruby]
 ----
+# Without a GlobalRegister
 product_2 = product_index.links.products.last.realize(register)
+
+# With a GlobalRegister
+product_2 = product_index.links.products.last.realize
+
 # => client.get('/products/2')
 # => {
 #   "id": 2,
@@ -842,9 +908,16 @@ product_2
 #                         <ProductLink href: "/products/4", title: "Product 4">,
 #                         <ProductLink href: "/products/6", title: "Product 6">
 #                     ]}>
+
+# Without a GlobalRegister
+product_2_related_1 = product_2.links.related.first.realize(register)
+
+# With a GlobalRegister
+product_2_related_1 = product_2.links.related.first.realize
 ----
 ====
 
+
 === Handling HAL pages / pagination
 
 The `Lutaml::Hal::Page` class is used to handle pagination in HAL APIs.
@@ -907,7 +980,12 @@ page_1
 #                next: #<ResourceIndexLink href: "/resources?page=2&items=10">,
 #                last: #<ResourceIndexLink href: "/resources?page=10&items=10">>>
 
+# Without a GlobalRegister
 page_2 = page.links.next.realize(register)
+
+# With a GlobalRegister
+page_2 = page.links.next.realize
+
 # => client.get('/resources?page=2&items=10')
 # => #<ResourceIndex page: 2, pages: 10, limit: 10, total: 100,
 #      links: #<ResourceIndexLinks

data/lib/lutaml/hal/client.rb

@@ -19,12 +19,19 @@ module Lutaml
         @debug = options[:debug] || !ENV['DEBUG_API'].nil?
         @cache = options[:cache] || {}
         @cache_enabled = options[:cache_enabled] || false
+
+        @api_url = strip_api_url(@api_url)
+      end
+
+      # Strip any trailing slash from the API URL
+      def strip_api_url(url)
+        url.sub(%r{/\Z}, '')
       end
 
       # Get a resource by its full URL
       def get_by_url(url, params = {})
         # Strip API endpoint if it's included
-        path = url.sub(%r{^#{@api_url}/}, '')
+        path = strip_api_url(url)
         get(path, params)
       end
 
@@ -62,7 +69,7 @@ module Lutaml
       end
 
       def handle_response(response, url)
-        debug_log(response, url) if @debug
+        debug_api_log(response, url) if @debug
 
         case response.status
         when 200..299
@@ -80,11 +87,11 @@ module Lutaml
         end
       end
 
-      def debug_log(response, url)
+      def debug_api_log(response, url)
         if defined?(Rainbow)
-          puts Rainbow("\n===== DEBUG: HAL API REQUEST =====").blue
+          puts Rainbow("\n===== Lutaml::Hal DEBUG: HAL API REQUEST =====").blue
         else
-          puts "\n===== DEBUG: HAL API REQUEST ====="
+          puts "\n===== Lutaml::Hal DEBUG: HAL API REQUEST ====="
         end
 
         puts "URL: #{url}"

data/lib/lutaml/hal/errors.rb

@@ -8,5 +8,6 @@ module Lutaml
     class BadRequestError < Error; end
     class ServerError < Error; end
     class LinkResolutionError < Error; end
+    class ParsingError < Error; end
   end
 end

data/lib/lutaml/hal/global_register.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module Lutaml
+  module Hal
+    # Global register for model registers
+    # This class is a singleton that manages the registration and retrieval of model registers.
+    # It ensures that each model register is unique and provides a way to access them globally.
+    #
+    # @example
+    #   global_register = GlobalRegister.instance
+    #   global_register.register(:example, ExampleModelRegister.new)
+    #   example_register = global_register.get(:example)
+    class GlobalRegister
+      include Singleton
+
+      def initialize
+        @model_registers = {}
+      end
+
+      def register(name, model_register)
+        if @model_registers[name] && @model_registers[name] != model_register
+          raise "Model register with name #{name} replacing another one" \
+                " (#{@model_registers[name].inspect} vs #{model_register.inspect})"
+        end
+
+        @model_registers[name] = model_register
+      end
+
+      def get(name)
+        raise "Model register with name #{name} not found" unless @model_registers[name]
+
+        @model_registers[name]
+      end
+
+      def delete(name)
+        return unless @model_registers[name]
+
+        @model_registers.delete(name)
+      end
+    end
+  end
+end

data/lib/lutaml/hal/link.rb

@@ -7,6 +7,10 @@ module Lutaml
   module Hal
     # HAL Link representation with realization capability
     class Link < Lutaml::Model::Serializable
+      # This is the model register that has fetched the origin of this link, and
+      # will be used to resolve unless overriden in resource#realize()
+      attr_accessor Hal::REGISTER_ID_ATTR_NAME.to_sym
+
       attribute :href, :string
       attribute :title, :string
       attribute :name, :string
@@ -16,9 +20,33 @@ module Lutaml
       attribute :profile, :string
       attribute :lang, :string
 
-      # Fetch the actual resource this link points to
-      def realize(register)
-        register.resolve_and_cast(href)
+      # Fetch the actual resource this link points to.
+      # 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)
+        register = find_register(register)
+        raise "No register provided for link resolution (class: #{self.class}, href: #{href})" if register.nil?
+
+        Hal.debug_log "Resolving link href: #{href} using register"
+        register.resolve_and_cast(self, href)
+      end
+
+      private
+
+      def find_register(explicit_register)
+        return explicit_register if explicit_register
+
+        register_id = instance_variable_get("@#{Hal::REGISTER_ID_ATTR_NAME}")
+        return nil if register_id.nil?
+
+        register = Lutaml::Hal::GlobalRegister.instance.get(register_id)
+        if register.nil?
+          raise 'GlobalRegister in use but unable to find the register. '\
+            'Please provide a register to the `#realize` method to resolve the link'
+        end
+
+        register
       end
     end
   end

data/lib/lutaml/hal/link_set.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require_relative 'model_register'
+
+module Lutaml
+  module Hal
+    # HAL Link representation with realization capability
+    class LinkSet < Lutaml::Model::Serializable
+      attr_accessor Hal::REGISTER_ID_ATTR_NAME.to_sym
+    end
+  end
+end

data/lib/lutaml/hal/model_register.rb

@@ -6,9 +6,10 @@ module Lutaml
   module Hal
     # Register to map URL patterns to model classes
     class ModelRegister
-      attr_accessor :models, :client
+      attr_accessor :models, :client, :register_name
 
-      def initialize(client: nil)
+      def initialize(name:, client: nil)
+        @register_name = name
         # If `client` is not set, it can be set later
         @client = client
         @models = {}
@@ -39,27 +40,59 @@ module Lutaml
         url = interpolate_url(endpoint[:url], params)
         response = client.get(url)
 
-        endpoint[:model].from_json(response.to_json)
+        realized_model = endpoint[:model].from_json(response.to_json)
+
+        mark_model_links_with_register(realized_model)
+        realized_model
       end
 
-      def resolve_and_cast(href)
+      def resolve_and_cast(link, href)
         raise 'Client not configured' unless client
 
-        debug_log("href #{href}")
+        Hal.debug_log("resolve_and_cast: link #{link}, href #{href}")
         response = client.get_by_url(href)
 
-        # TODO: Merge more content into the resource
+        # TODO: Merge full Link content into the resource?
         response_with_link_details = response.to_h.merge({ 'href' => href })
 
         href_path = href.sub(client.api_url, '')
+
         model_class = find_matching_model_class(href_path)
         raise LinkResolutionError, "Unregistered URL pattern: #{href}" unless model_class
 
-        debug_log("model_class #{model_class}")
-        debug_log("response: #{response.inspect}")
-        debug_log("amended: #{response_with_link_details}")
+        Hal.debug_log("resolve_and_cast: resolved to model_class #{model_class}")
+        Hal.debug_log("resolve_and_cast: response: #{response.inspect}")
+        Hal.debug_log("resolve_and_cast: amended: #{response_with_link_details}")
 
-        model_class.from_json(response_with_link_details.to_json)
+        model = model_class.from_json(response_with_link_details.to_json)
+        mark_model_links_with_register(model)
+        model
+      end
+
+      # Recursively mark all models in the link with the register name
+      # This is used to ensure that all links in the model are registered
+      # with the same register name for consistent resolution
+      def mark_model_links_with_register(inspecting_model)
+        return unless inspecting_model.is_a?(Lutaml::Model::Serializable)
+
+        inspecting_model.instance_variable_set("@#{Hal::REGISTER_ID_ATTR_NAME}", @register_name)
+
+        # Recursively process model attributes to mark links with this register
+        inspecting_model.class.attributes.each_pair do |key, config|
+          attr_type = config.type
+          next unless attr_type < Lutaml::Hal::Resource ||
+                      attr_type < Lutaml::Hal::Link ||
+                      attr_type < Lutaml::Hal::LinkSet
+
+          value = inspecting_model.send(key)
+          next if value.nil?
+
+          # Handle both array and single values with the same logic
+          values = value.is_a?(Array) ? value : [value]
+          values.each { |item| mark_model_links_with_register(item) }
+        end
+
+        inspecting_model
       end
 
       private
@@ -103,11 +136,15 @@ module Lutaml
         pattern_with_wildcards = pattern.gsub(/\{[^}]+\}/, '*')
         # Convert * wildcards to regex pattern
         regex = Regexp.new("^#{pattern_with_wildcards.gsub('*', '[^/]+')}$")
-        regex.match?(url)
-      end
 
-      def debug_log(message)
-        puts "DEBUG: #{message}" if ENV['DEBUG_API']
+        Hal.debug_log("pattern_match?: regex: #{regex.inspect}")
+        Hal.debug_log("pattern_match?: href to match #{url}")
+        Hal.debug_log("pattern_match?: pattern to match #{pattern_with_wildcards}")
+
+        matches = regex.match?(url)
+        Hal.debug_log("pattern_match?: matches = #{matches}")
+
+        matches
       end
     end
   end

data/lib/lutaml/hal/page.rb

@@ -23,7 +23,7 @@ module Lutaml
       def self.inherited(subclass)
         super
 
-        page_links_symbols = %i[self next prev first last]
+        page_links_symbols = %i[self next prev first last up]
         subclass_name = subclass.name
         subclass.class_eval do
           # Define common page links

data/lib/lutaml/hal/resource.rb

@@ -7,6 +7,10 @@ module Lutaml
   module Hal
     # Resource class for all HAL resources
     class Resource < Lutaml::Model::Serializable
+      # This is the model register that has fetched this resource, and
+      # will be used to resolve links unless overriden in resource#realize()
+      attr_accessor Hal::REGISTER_ID_ATTR_NAME.to_sym
+
       class << self
         attr_accessor :link_definitions
 
@@ -35,20 +39,22 @@ module Lutaml
           # 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}`"
+
           # 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)
 
           # Create a dynamic LinkSet class if `link_set_class:` is not provided.
           unless link_set_class
-            link_set_klass = link_set_class || get_links_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
 
               # Define the mapping for the attribute
               key_value do
-                map attr_key, to: attribute_name
+                map key, to: attribute_name
               end
             end
           end
@@ -67,7 +73,7 @@ module Lutaml
         end
 
         # This method obtains the Links class that holds the Link classes
-        def get_links_class
+        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('::')
@@ -86,12 +92,14 @@ module Lutaml
           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::Model::Serializable)
+          # 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)
 
@@ -111,9 +119,11 @@ module Lutaml
         # This is a Link class that helps us realize the targeted class
         def create_link_class(realize_class_name)
           parent_klass_name = name.split('::')[0..-2].join('::')
-          child_klass_name = "#{name.split('::').last}Link"
+          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

data/lib/lutaml/hal/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Hal
-    VERSION = '0.1.3'
+    VERSION = '0.1.4'
   end
 end

data/lib/lutaml/hal.rb

@@ -5,13 +5,20 @@ require 'lutaml/model'
 module Lutaml
   # HAL implementation for Lutaml
   module Hal
+    REGISTER_ID_ATTR_NAME = '_global_register_id'
+
+    def self.debug_log(message)
+      puts "[Lutaml::Hal] DEBUG: #{message}" if ENV['DEBUG_API']
+    end
   end
 end
 
 require_relative 'hal/version'
 require_relative 'hal/errors'
 require_relative 'hal/link'
+require_relative 'hal/link_set'
 require_relative 'hal/resource'
 require_relative 'hal/page'
+require_relative 'hal/global_register'
 require_relative 'hal/model_register'
 require_relative 'hal/client'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-hal
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Ribose Inc.
@@ -80,7 +80,9 @@ files:
 - lib/lutaml/hal.rb
 - lib/lutaml/hal/client.rb
 - lib/lutaml/hal/errors.rb
+- lib/lutaml/hal/global_register.rb
 - lib/lutaml/hal/link.rb
+- lib/lutaml/hal/link_set.rb
 - lib/lutaml/hal/model_register.rb
 - lib/lutaml/hal/page.rb
 - lib/lutaml/hal/resource.rb