lutaml-hal 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5860a26a1d8b235f8138e37fe835c3f0de0d4cc065f99b33da9ed17c0cb0a8cf
-  data.tar.gz: e558941f569c2d8d55ac62c66924a06a7445438281c261e060471bdf2d8c9f5f
+  metadata.gz: 443ab6a0ccf5927a142a841eb7e7178bb21aaaea9d64e67d84e325250cf23093
+  data.tar.gz: 9190a8b564e5e375d6605bea71e0ba9d9489536b862aca74272d28d49961c606
 SHA512:
-  metadata.gz: a3cda001e3ebb066cf62e8aa54fbec2a41ae93a173a056919da2151cf8f28fcba143352ad2dc287d478c7365fa3e087abc1757770264acc05a4be925378072d7
-  data.tar.gz: d34fd6af3af5e78d1b223f04fa9f1e9e71ff524b2ac9425935d6bd5e07e4d8fa10a2c255c063c70026388d5f2406a05a41cde1492482cd66a911fb1fe80fb623
+  metadata.gz: e0baa1f526af80dd8fdb4366f637ad059d0e7f58f4836b6a1377adca4834f846c29889c3bd6782109dc3da65f93e4387d675477794fbc0b08573b8a03684eeae
+  data.tar.gz: aabbfd4f298149c3f71b8145e79d17bbff4293eaf9b8db99fbcf1aadb114efeb82b9d2db7ec571ce2e4651aeac0863be424a3a0335595096e104728ffcd65127

data/lib/lutaml/hal/model_register.rb

@@ -4,6 +4,7 @@ require 'cgi'
 require_relative 'errors'
 require_relative 'endpoint_configuration'
 require_relative 'cache/cache_manager'
+require_relative 'single_flight'
 
 module Lutaml
   module Hal
@@ -17,6 +18,7 @@ module Lutaml
         @client = client
         @models = {}
         @cache_manager = Cache::CacheManager.new(cache, client: @client) if cache
+        @single_flight = SingleFlight.new
       end
 
       # Register a model with its URL pattern and parameters
@@ -71,115 +73,32 @@ module Lutaml
         # Process parameters through EndpointParameter objects
         processed_params = process_parameters(endpoint[:parameters], params)
 
-        # Build URL with path parameters
+        # Build URL with path and query 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])
 
-        realized_model = nil
+        cached = cached_endpoint_model(final_url)
+        return cached if cached
 
-        # Check cache first
-        if @cache_manager&.available?
-          cached_entry = @cache_manager.get(final_url)
-          if cached_entry
-            debug_log("Cache hit for fetch: #{final_url}")
-            realized_model = cached_entry.hal_resource
-            # Return cached model directly if valid
-            mark_model_links_with_register(realized_model)
-            return realized_model
-          end
-        end
-
-        # Make request if not cached
-        # Add conditional headers if we have cached metadata
-        request_headers = processed_params[:headers].dup
-        if @cache_manager&.available?
-          conditional_headers = @cache_manager.conditional_request_headers(final_url)
-          request_headers.merge!(conditional_headers) if conditional_headers
+        # Coalesce concurrent fetches of the same URL into a single request.
+        coalesce(final_url) do
+          cached_endpoint_model(final_url) ||
+            fetch_uncached(endpoint, final_url, processed_params[:headers])
         end
-
-        # Make request with headers
-        response = if request_headers.any?
-                     client.get_with_headers(final_url, request_headers)
-                   else
-                     client.get(final_url)
-                   end
-
-        # Handle 304 Not Modified
-        if response.respond_to?(:status) && response.status == 304
-          @cache_manager&.refresh_entry(final_url, response)
-          cached_entry = @cache_manager.get(final_url)
-          realized_model = cached_entry.hal_resource if cached_entry
-        else
-          # Create model from response
-          realized_model = endpoint[:model].from_json(response.to_json)
-
-          # Cache the realized model with metadata
-          @cache_manager&.set(final_url, response, realized_model)
-        end
-
-        # Store embedded data for later resolution
-        realized_model.embedded_data = response['_embedded'] if realized_model && response && response['_embedded']
-
-        mark_model_links_with_register(realized_model)
-
-        realized_model
       end
 
       def resolve_and_cast(link, href)
         raise 'Client not configured' unless client
 
-        # Check cache first
-        if @cache_manager&.available?
-          cached_entry = @cache_manager.get(href)
-          if cached_entry
-            debug_log("Cache hit for: #{href}")
-            cached_model = cached_entry.hal_resource
-            # A model rebuilt from a persistent cache needs to be (re)marked so
-            # its links can be realized against this register.
-            mark_model_links_with_register(cached_model)
-            return cached_model
-          end
-        end
+        cached = cached_resolved_model(href)
+        return cached if cached
 
         debug_log("resolve_and_cast: link #{link}, href #{href}")
 
-        # Add conditional headers if we have cached metadata
-        conditional_headers = @cache_manager&.conditional_request_headers(href) || {}
-
-        response = if conditional_headers.any?
-                     client.get_by_url_with_headers(href, conditional_headers)
-                   else
-                     client.get_by_url(href)
-                   end
-
-        # Handle 304 Not Modified
-        if response.respond_to?(:status) && response.status == 304
-          @cache_manager&.refresh_entry(href, response)
-          cached_entry = @cache_manager.get(href)
-          return cached_entry.hal_resource if cached_entry
+        # Coalesce concurrent resolutions of the same href into one request.
+        coalesce(href) do
+          cached_resolved_model(href) || resolve_and_cast_uncached(href)
         end
-
-        # 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("resolve_and_cast: resolved to model_class #{model_class}")
-        debug_log("resolve_and_cast: response: #{response.inspect}")
-        debug_log("resolve_and_cast: amended: #{response_with_link_details}")
-
-        model = model_class.from_json(response_with_link_details.to_json)
-        mark_model_links_with_register(model)
-
-        # Cache the realized model with metadata
-        @cache_manager&.set(href, response, model)
-
-        model
       end
 
       # Recursively mark all models in the link with the register name
@@ -248,6 +167,104 @@ module Lutaml
         puts "[Lutaml::Hal] DEBUG: #{message}" if ENV['DEBUG_API']
       end
 
+      # Run the block, coalescing concurrent calls that share `key` into one
+      # execution (single-flight) so duplicate in-flight requests for the same
+      # URL collapse into a single fetch. Only active when caching is enabled —
+      # the cache is what lets the shared result be reused. Different keys run
+      # in parallel.
+      def coalesce(key, &block)
+        return block.call unless @cache_manager&.available?
+
+        @single_flight.run(key, &block)
+      end
+
+      # Cached, register-marked model for a fully-built endpoint URL, or nil.
+      def cached_endpoint_model(url)
+        return nil unless @cache_manager&.available?
+
+        entry = @cache_manager.get(url)
+        return nil unless entry
+
+        debug_log("Cache hit for fetch: #{url}")
+        model = entry.hal_resource
+        mark_model_links_with_register(model)
+        model
+      end
+
+      # The fetch miss path: HTTP request, 304 handling, model build and cache.
+      def fetch_uncached(endpoint, final_url, headers)
+        request_headers = headers.dup
+        if @cache_manager&.available?
+          conditional_headers = @cache_manager.conditional_request_headers(final_url)
+          request_headers.merge!(conditional_headers) if conditional_headers
+        end
+
+        response = if request_headers.any?
+                     client.get_with_headers(final_url, request_headers)
+                   else
+                     client.get(final_url)
+                   end
+
+        if response.respond_to?(:status) && response.status == 304
+          @cache_manager&.refresh_entry(final_url, response)
+          cached_entry = @cache_manager.get(final_url)
+          realized_model = cached_entry.hal_resource if cached_entry
+        else
+          realized_model = endpoint[:model].from_json(response.to_json)
+          @cache_manager&.set(final_url, response, realized_model)
+        end
+
+        realized_model.embedded_data = response['_embedded'] if realized_model && response && response['_embedded']
+        mark_model_links_with_register(realized_model)
+        realized_model
+      end
+
+      # Cached, register-marked model for a link href, or nil.
+      def cached_resolved_model(href)
+        return nil unless @cache_manager&.available?
+
+        entry = @cache_manager.get(href)
+        return nil unless entry
+
+        debug_log("Cache hit for: #{href}")
+        model = entry.hal_resource
+        # A model rebuilt from a persistent cache needs to be (re)marked so its
+        # links can be realized against this register.
+        mark_model_links_with_register(model)
+        model
+      end
+
+      # The resolve_and_cast miss path: HTTP request, 304 handling, model build
+      # and cache.
+      def resolve_and_cast_uncached(href)
+        conditional_headers = @cache_manager&.conditional_request_headers(href) || {}
+
+        response = if conditional_headers.any?
+                     client.get_by_url_with_headers(href, conditional_headers)
+                   else
+                     client.get_by_url(href)
+                   end
+
+        if response.respond_to?(:status) && response.status == 304
+          @cache_manager&.refresh_entry(href, response)
+          cached_entry = @cache_manager.get(href)
+          return cached_entry.hal_resource if cached_entry
+        end
+
+        # 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("resolve_and_cast: resolved to model_class #{model_class}")
+        model = model_class.from_json(response_with_link_details.to_json)
+        mark_model_links_with_register(model)
+        @cache_manager&.set(href, response, model)
+        model
+      end
+
       def process_parameters(parameter_definitions, provided_params)
         result = { path: {}, query: {}, headers: {}, cookies: {} }
 

data/lib/lutaml/hal/single_flight.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Hal
+    # Coalesces concurrent calls that share a key so the work runs once and the
+    # result (or error) is shared by all callers. Calls for *different* keys run
+    # in parallel — only same-key callers wait on the in-flight leader.
+    #
+    # Pure stdlib (Mutex + ConditionVariable); no external dependency. In-flight
+    # entries are removed once resolved, so memory is bounded by concurrency,
+    # not by the number of distinct keys ever seen.
+    class SingleFlight
+      Call = Struct.new(:mutex, :cond, :done, :value, :error)
+
+      def initialize
+        @registry_mutex = Mutex.new
+        @calls = {}
+      end
+
+      # Run the block at most once per key under concurrency, returning its
+      # result. The first caller for a key (the leader) runs the block; others
+      # wait and receive the same value (or re-raise the same error).
+      def run(key)
+        leader = false
+        call = @registry_mutex.synchronize do
+          @calls[key] ||= begin
+            leader = true
+            Call.new(Mutex.new, ConditionVariable.new, false)
+          end
+        end
+
+        return await(call) unless leader
+
+        begin
+          call.value = yield
+        rescue StandardError => e
+          call.error = e
+        ensure
+          @registry_mutex.synchronize { @calls.delete(key) }
+          call.mutex.synchronize do
+            call.done = true
+            call.cond.broadcast
+          end
+        end
+
+        raise call.error if call.error
+
+        call.value
+      end
+
+      private
+
+      def await(call)
+        call.mutex.synchronize do
+          call.cond.wait(call.mutex) until call.done
+        end
+        raise call.error if call.error
+
+        call.value
+      end
+    end
+  end
+end

data/lib/lutaml/hal/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Hal
-    VERSION = '0.2.1'
+    VERSION = '0.2.2'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-hal
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Ribose Inc.
@@ -110,6 +110,7 @@ files:
 - lib/lutaml/hal/page.rb
 - lib/lutaml/hal/rate_limiter.rb
 - lib/lutaml/hal/resource.rb
+- lib/lutaml/hal/single_flight.rb
 - lib/lutaml/hal/type_resolver.rb
 - lib/lutaml/hal/version.rb
 homepage: https://github.com/lutaml/lutaml-hal