feat: add global register

Author: ronaldtse

.rubocop_todo.yml

@@ -1,11 +1,17 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-03-12 04:30:42 UTC using RuboCop version 1.73.2.
+# on 2025-03-12 09:47:59 UTC using RuboCop version 1.73.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/EmptyLineAfterMagicComment:
+  Exclude:
+    - 'lib/lutaml/hal/global_register.rb'
+
 # Offense count: 3
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
@@ -15,9 +21,14 @@ Metrics/AbcSize:
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 177
+  Max: 188
 
-# Offense count: 8
+# Offense count: 1
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/CyclomaticComplexity:
+  Max: 9
+
+# Offense count: 9
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 21
@@ -27,6 +38,11 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Max: 7
 
+# Offense count: 1
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/PerceivedComplexity:
+  Max: 9
+
 # Offense count: 1
 Naming/AccessorMethodName:
   Exclude:
@@ -55,3 +71,19 @@ Naming/HeredocDelimiterNaming:
 Naming/VariableNumber:
   Exclude:
     - 'spec/lutaml/hal/page_spec.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: always, always_true, never
+Style/FrozenStringLiteralComment:
+  Exclude:
+    - '**/*.arb'
+    - 'lib/lutaml/hal/global_register.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: Mode.
+Style/StringConcatenation:
+  Exclude:
+    - 'lib/lutaml/hal/model_register.rb'

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

lib/lutaml/hal.rb

@@ -5,13 +5,20 @@
 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'

lib/lutaml/hal/client.rb

@@ -19,12 +19,19 @@ def initialize(options = {})
         @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 @@ def create_connection
       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 @@ def handle_response(response, url)
         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}"

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

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 @@ class Link < Lutaml::Model::Serializable
       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