lutaml-hal 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3193d7b68f48f5930b5247d0b962ed31fc39f5280b171084bd1ef36ffd2ff6b5
-  data.tar.gz: 8cc11026dfbe93ab84546cf2e358d8a14fd9e71acef677675201bf1e288bdcb2
+  metadata.gz: a0879e2f05a3b6cfe0046dc4924ae0ba2bf5ef1925445e4469585c8ed77dd691
+  data.tar.gz: bc6e2d28adb425d5a29eab74c655bf4d721e81693a2109d4f5a61bb942d9cea4
 SHA512:
-  metadata.gz: 87f583829974459e7edbeadfa3a4bca22b616a7e2b02afba0171159728c612265a1147dc7a32ac4677e798eec1129377b3bcba74ce8f24262590c5ac060453e7
-  data.tar.gz: 46e96d2f8d1ca38a7c71d48280046d2765749acc19877b2628305d7de4c6949dbcb0512933343ea68453d44e052ac6553d18e051839d23cb50d17fbb6075ece3
+  metadata.gz: 9498991d51a700e261ccf411121797d88a5e205a1f2210ba8558615e69aacb89c61280fbf5454f579b18207de3ebfe5aedc3f99950f7e5bcd1ba6169770a3d31
+  data.tar.gz: 336e55e9740cef31a1e30f1208c212e41e9c643f8756394844bd14da89b221d34aabc62a4830e0b850d540c30feb31b765a02543a200086f39e417d36efce7ee

data/README.adoc

@@ -31,6 +31,7 @@ APIs.
 * Integration with the `lutaml-model` serialization framework
 * Error handling and response validation for API interactions
 * Comprehensive embed support for reducing HTTP requests and improving performance
+* Built-in rate limiting with exponential backoff and retry logic
 
 == Installation
 
@@ -103,30 +104,36 @@ puts category.name
 
 == Documentation
 
-=== Comprehensive guides
+=== Detailed topics
 
-For detailed documentation, see these comprehensive guides:
+For detailed documentation, see these topics:
 
-* **link:docs/getting-started-guide.adoc[Getting started guide]** - Step-by-step
-  tutorial for your first HAL API client (15 minutes)
+link:docs/getting-started.adoc[Getting started]::
+Get started with your HAL API client (15 minutes)
 
-* **link:docs/data-definition-guide.adoc[Data definition guide]** - Complete
-  reference for defining HAL resources, model registers, and API endpoints
+link:docs/data-definition.adoc[Data definition]::
+Full reference to define HAL resources, model registers, and API endpoints
 
-* **link:docs/runtime-usage-guide.adoc[Runtime usage guide]** - Patterns for
-  fetching resources, navigating links, and handling pagination
+link:docs/runtime-usage.adoc[Runtime usage]::
+Patterns to fetch resources, navigate links, and handle pagination
 
-* **link:docs/hal-links-reference.adoc[HAL links reference]** - Advanced
-  configuration and customization of HAL links
+link:docs/hal-links-reference.adoc[HAL links reference]::
+Advanced configuration of HAL links
 
-* **link:docs/pagination-guide.adoc[Pagination guide]** - Working with
-  paginated APIs and large datasets
+link:docs/pagination.adoc[Pagination]::
+Working with paginated APIs and large datasets
 
-* **link:docs/complex-path-patterns.adoc[Complex path patterns]** - Advanced
-  URL patterns and path matching examples
+link:docs/complex-path-patterns.adoc[Complex path patterns]::
+Advanced URL patterns and path matching examples
 
-* **link:docs/embedded-resources.adoc[Embedded resources]** - Implementing and
-using embedded resources in HAL APIs with automatic link realization
+link:docs/embedded-resources.adoc[Embedded resources]::
+Implementing and using embedded resources in HAL APIs with automatic link realization
+
+link:docs/rate-limiting.adoc[Rate limiting]::
+Configuring and using built-in rate limiting functionality
+
+link:docs/error-handling.adoc[Error handling]::
+Understanding and handling different types of errors when working with HAL APIs
 
 
 === Architecture overview
@@ -213,20 +220,6 @@ register.add_endpoint(
 For complex path pattern examples, see
 link:docs/complex-path-patterns.adoc[Complex Path Patterns].
 
-== Error handling
-
-The library provides structured error handling:
-
-[source,ruby]
-----
-begin
-  product = register.fetch(:product_resource, id: '123')
-rescue Lutaml::Hal::Errors::NotFoundError => e
-  puts "Product not found: #{e.message}"
-rescue Lutaml::Hal::Errors::ApiError => e
-  puts "API Error: #{e.message}"
-end
-----
 
 == Contributing
 

data/lib/lutaml/hal/cache/cache_configuration.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Lutaml
+  module Hal
+    module Cache
+      # Represents cache configuration with validation and defaults
+      class CacheConfiguration < Lutaml::Model::Serializable
+        attribute :adapter_type, :string
+        attribute :adapter_config, :hash
+        attribute :ttl, :integer
+        attribute :max_size, :integer
+        attribute :http_aware, :boolean
+        attribute :respect_http_headers, :boolean
+        attribute :enable_conditional_requests, :boolean
+        attribute :ignore_query_params, :string
+
+        # Default configuration values
+        DEFAULT_TTL = 3600
+        DEFAULT_MAX_SIZE = 1000
+        DEFAULT_ADAPTER_TYPE = 'memory'
+
+        # Create configuration from hash or symbol
+        def self.from_config(config)
+          return new if config.nil?
+
+          case config
+          when Hash
+            from_hash(config)
+          when Symbol, String
+            from_simple_config(config)
+          else
+            raise ArgumentError, "Invalid cache configuration: #{config.inspect}"
+          end
+        end
+
+        # Validate the configuration
+        def validate!
+          validate_adapter_type!
+          validate_ttl!
+          validate_max_size!
+          validate_adapter_config!
+        end
+
+        # Check if HTTP-aware caching should be used
+        #
+        # HTTP-aware caching (conditional requests backed by a response cache)
+        # is opt-in: it only applies when explicitly enabled and the
+        # lutaml-store HTTP cache backend is available. By default the register
+        # uses the basic object cache, which stores realized models directly.
+        def http_aware?
+          http_aware == true && http_cache_available?
+        end
+
+        # Check if basic caching should be used
+        def basic_cache?
+          !http_aware?
+        end
+
+        # Get the effective TTL (with fallback to default)
+        def effective_ttl
+          ttl || DEFAULT_TTL
+        end
+
+        # Get the effective max size (with fallback to default)
+        def effective_max_size
+          max_size || DEFAULT_MAX_SIZE
+        end
+
+        # Get the effective adapter type (with fallback to default)
+        def effective_adapter_type
+          adapter_type || DEFAULT_ADAPTER_TYPE
+        end
+
+        # Get HTTP cache configuration hash
+        def http_cache_config
+          {
+            adapter_type: effective_adapter_type.to_sym,
+            default_ttl: effective_ttl,
+            max_entries: effective_max_size,
+            respect_http_headers: respect_http_headers != false,
+            enable_conditional_requests: enable_conditional_requests != false,
+            ignore_query_params: parse_ignore_query_params
+          }.merge(adapter_config || {})
+        end
+
+        # Get basic cache configuration hash
+        def basic_cache_config
+          {
+            adapter: adapter_config || { type: effective_adapter_type.to_sym },
+            default_ttl: effective_ttl,
+            max_size: effective_max_size
+          }
+        end
+
+        private
+
+        def self.from_hash(config)
+          adapter_info = config[:adapter] || config['adapter'] || {}
+
+          # Handle direct adapter_type specification
+          adapter_type = config[:adapter_type] || config['adapter_type'] || extract_adapter_type(adapter_info)
+
+          new(
+            adapter_type: adapter_type,
+            adapter_config: adapter_info.is_a?(Hash) ? adapter_info : nil,
+            ttl: config[:ttl] || config['ttl'],
+            max_size: config[:max_size] || config['max_size'],
+            http_aware: config.key?(:http_aware) ? config[:http_aware] : config['http_aware'],
+            respect_http_headers: config.key?(:respect_http_headers) ? config[:respect_http_headers] : config['respect_http_headers'],
+            enable_conditional_requests: config.key?(:enable_conditional_requests) ? config[:enable_conditional_requests] : config['enable_conditional_requests'],
+            ignore_query_params: config[:ignore_query_params] || config['ignore_query_params']
+          )
+        end
+
+        def self.from_simple_config(config)
+          new(adapter_type: config.to_s)
+        end
+
+        def self.extract_adapter_type(adapter_info)
+          case adapter_info
+          when Hash
+            type = adapter_info[:type] || adapter_info['type']
+            type&.to_s
+          when Symbol, String
+            adapter_info.to_s
+          end
+        end
+
+        def validate_adapter_type!
+          valid_types = %w[memory filesystem sqlite]
+          return if valid_types.include?(effective_adapter_type)
+
+          raise ArgumentError, "Invalid adapter type: #{effective_adapter_type}. Valid types: #{valid_types.join(', ')}"
+        end
+
+        def validate_ttl!
+          return unless ttl
+          return if ttl.is_a?(Integer) && ttl > 0
+
+          raise ArgumentError, "TTL must be a positive integer, got: #{ttl.inspect}"
+        end
+
+        def validate_max_size!
+          return unless max_size
+          return if max_size.is_a?(Integer) && max_size > 0
+
+          raise ArgumentError, "Max size must be a positive integer, got: #{max_size.inspect}"
+        end
+
+        def validate_adapter_config!
+          return unless adapter_config
+          return if adapter_config.is_a?(Hash)
+
+          raise ArgumentError, "Adapter config must be a hash, got: #{adapter_config.class}"
+        end
+
+        # Override the setter to validate before assignment
+        def adapter_config=(value)
+          raise ArgumentError, "Adapter config must be a hash, got: #{value.class}" if value && !value.is_a?(Hash)
+
+          super(value)
+        end
+
+        def http_cache_available?
+          defined?(::Lutaml::Store::HttpCache)
+        end
+
+        def parse_ignore_query_params
+          return [] unless ignore_query_params
+
+          case ignore_query_params
+          when String
+            ignore_query_params.split(',').map(&:strip)
+          when Array
+            ignore_query_params
+          else
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/hal/cache/cache_entry.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'cache_metadata'
+
+module Lutaml
+  module Hal
+    module Cache
+      # Represents a complete cached entry with metadata and HAL resource
+      class CacheEntry
+        attr_accessor :url, :cached_at, :metadata, :hal_resource
+
+        def initialize(url: nil, cached_at: nil, metadata: nil, hal_resource: nil)
+          @url = url
+          @cached_at = cached_at
+          @metadata = metadata
+          @hal_resource = hal_resource
+        end
+
+        # Plain-hash representation suitable for JSON persistence. The HAL
+        # resource and its class are recorded so the model can be rebuilt; the
+        # metadata is kept as its own JSON document.
+        def to_storage_h
+          {
+            'url' => url,
+            'cached_at' => cached_at,
+            'metadata' => metadata&.to_json,
+            'model_class' => hal_resource&.class&.name,
+            'model' => hal_resource&.to_json
+          }
+        end
+
+        # Called by lutaml-store's CacheStore when serializing a persisted entry.
+        def to_json(*_args)
+          JSON.generate(to_storage_h)
+        end
+
+        # True if the given hash looks like a to_storage_h document (as opposed
+        # to a legacy in-memory cache hash holding a live :realized_model).
+        def self.storage_format?(hash)
+          hash.key?('model') || hash.key?(:model) ||
+            hash.key?('model_class') || hash.key?(:model_class)
+        end
+
+        # Rebuild a CacheEntry from a to_storage_h document. Tolerates string or
+        # symbol keys, since lutaml-store parses persisted JSON with
+        # symbolize_names.
+        def self.from_storage_h(hash)
+          h = hash.transform_keys(&:to_s)
+          new(
+            url: h['url'],
+            cached_at: h['cached_at'],
+            metadata: h['metadata'] ? CacheMetadata.from_json(h['metadata']) : nil,
+            hal_resource: rebuild_model(h['model_class'], h['model'])
+          )
+        end
+
+        def self.rebuild_model(class_name, model_json)
+          return nil unless class_name && model_json
+
+          Object.const_get(class_name).from_json(model_json)
+        rescue NameError
+          nil
+        end
+
+        # Create a cache entry from a URL, response, and realized HAL resource
+        def self.create(url, response, hal_resource)
+          new(
+            url: url,
+            cached_at: Time.now.to_s,
+            metadata: CacheMetadata.from_response(response),
+            hal_resource: hal_resource
+          )
+        end
+
+        # Check if the cache entry is still valid based on TTL
+        def valid?(default_ttl)
+          return false unless cached_at
+
+          cached_time = cached_at.is_a?(String) ? Time.parse(cached_at) : cached_at
+          age = Time.now - cached_time
+          ttl = metadata&.max_age || default_ttl
+
+          age < ttl
+        end
+
+        # Check if the entry is expired and needs revalidation
+        def expired?(default_ttl)
+          !valid?(default_ttl)
+        end
+
+        # Check if the entry can be revalidated with conditional requests
+        def revalidatable?
+          return false unless metadata
+
+          !!(metadata.etag || metadata.last_modified)
+        end
+
+        # Get conditional headers for revalidation
+        def conditional_headers
+          metadata&.conditional_headers || {}
+        end
+
+        # Check if the response is cacheable based on metadata
+        def cacheable?
+          metadata&.cacheable? != false
+        end
+
+        # Update the cache entry with fresh metadata (for 304 responses)
+        def refresh_metadata(response)
+          self.cached_at = Time.now.to_s
+          self.metadata = CacheMetadata.from_response(response)
+        end
+
+        # Get cache age in seconds
+        def age
+          return 0 unless cached_at
+
+          cached_time = cached_at.is_a?(String) ? Time.parse(cached_at) : cached_at
+          Time.now - cached_time
+        end
+
+        # Check if entry should be served stale (useful for error scenarios)
+        def serve_stale?(max_stale = nil)
+          return false unless max_stale
+          return false if valid?(Float::INFINITY) # Still fresh
+
+          cached_time = cached_at.is_a?(String) ? Time.parse(cached_at) : cached_at
+          current_age = Time.now - cached_time
+          ttl = metadata&.max_age || 0
+
+          # Entry is stale if current_age > ttl
+          # But we can serve it if the staleness is within the max_stale window
+          staleness = current_age - ttl
+          current_age > ttl && staleness < max_stale
+        end
+      end
+    end
+  end
+end