rhales 0.3.0 → 0.4.0

data/lib/rhales/hydration_data_aggregator.rb

@@ -37,7 +37,7 @@ module Rhales
 
     private
 
-    def process_template(template_name, parser)
+    def process_template(_template_name, parser)
       data_content = parser.section('data')
       return unless data_content
 
@@ -62,22 +62,22 @@ module Rhales
       end
 
       # Merge or set the data
-      if @merged_data.key?(window_attr)
-        @merged_data[window_attr] = merge_data(
+      @merged_data[window_attr] = if @merged_data.key?(window_attr)
+        merge_data(
           @merged_data[window_attr],
           processed_data,
           merge_strategy || 'deep',
           window_attr,
-          template_path
+          template_path,
         )
       else
-        @merged_data[window_attr] = processed_data
-      end
+        processed_data
+                                  end
 
       # Track the window attribute
       @window_attributes[window_attr] = {
         path: template_path,
-        merge_strategy: merge_strategy
+        merge_strategy: merge_strategy,
       }
     end
 
@@ -116,11 +116,11 @@ module Rhales
       result = target.dup
 
       source.each do |key, value|
-        if result.key?(key) && result[key].is_a?(Hash) && value.is_a?(Hash)
-          result[key] = deep_merge(result[key], value)
+        result[key] = if result.key?(key) && result[key].is_a?(Hash) && value.is_a?(Hash)
+          deep_merge(result[key], value)
         else
-          result[key] = value
-        end
+          value
+                      end
       end
 
       result
@@ -134,7 +134,7 @@ module Rhales
           raise ::Rhales::HydrationCollisionError.new(
             "#{window_attr}.#{key}",
             @window_attributes[window_attr][:path],
-            template_path
+            template_path,
           )
         end
         result[key] = value
@@ -146,13 +146,13 @@ module Rhales
     def strict_merge(target, source, window_attr, template_path)
       # In strict mode, any collision is an error
       target.each_key do |key|
-        if source.key?(key)
-          raise ::Rhales::HydrationCollisionError.new(
-            "#{window_attr}.#{key}",
-            @window_attributes[window_attr][:path],
-            template_path
-          )
-        end
+        next unless source.key?(key)
+
+        raise ::Rhales::HydrationCollisionError.new(
+          "#{window_attr}.#{key}",
+          @window_attributes[window_attr][:path],
+          template_path,
+        )
       end
 
       target.merge(source)
@@ -175,6 +175,7 @@ module Rhales
       return true if data == {}
       return true if data == []
       return true if data.respond_to?(:empty?) && data.empty?
+
       false
     end
   end
@@ -186,8 +187,8 @@ module Rhales
     end
 
     # Delegate all methods to the wrapped context
-    def method_missing(method, *args, &block)
-      @context.send(method, *args, &block)
+    def method_missing(method, *, &)
+      @context.send(method, *, &)
     end
 
     def respond_to_missing?(method, include_private = false)
@@ -215,6 +216,6 @@ module Rhales
     end
 
     # Alias for compatibility with template engine
-    alias_method :resolve_variable, :get
+    alias resolve_variable get
   end
 end

data/lib/rhales/hydration_endpoint.rb

@@ -0,0 +1,211 @@
+require 'json'
+require 'digest'
+
+module Rhales
+  # Handles API endpoint responses for link-based hydration strategies
+  #
+  # Provides JSON and ES module endpoints that serve hydration data
+  # separately from HTML templates, enabling better caching, parallel
+  # loading, and reduced HTML payload sizes.
+  #
+  # ## Supported Response Formats
+  #
+  # ### JSON Response (application/json)
+  # ```json
+  # {
+  #   "myData": { "user": "john", "theme": "dark" },
+  #   "config": { "apiUrl": "https://api.example.com" }
+  # }
+  # ```
+  #
+  # ### ES Module Response (text/javascript)
+  # ```javascript
+  # export default {
+  #   "myData": { "user": "john", "theme": "dark" },
+  #   "config": { "apiUrl": "https://api.example.com" }
+  # };
+  # ```
+  #
+  # ## Usage
+  #
+  # ```ruby
+  # endpoint = HydrationEndpoint.new(config, context)
+  #
+  # # JSON response
+  # json_response = endpoint.render_json('template_name')
+  #
+  # # ES Module response
+  # module_response = endpoint.render_module('template_name')
+  # ```
+  class HydrationEndpoint
+    def initialize(config, context = nil)
+      @config = config
+      @context = context
+    end
+
+    # Render JSON response for API endpoints
+    def render_json(template_name, additional_context = {})
+      merged_data = process_template_data(template_name, additional_context)
+
+      {
+        content: JSON.generate(merged_data),
+        content_type: 'application/json',
+        headers: json_headers(merged_data)
+      }
+    rescue JSON::NestingError, JSON::GeneratorError, ArgumentError, Encoding::UndefinedConversionError => e
+      # Handle JSON serialization errors and encoding issues
+      error_data = {
+        error: {
+          message: "Failed to serialize data to JSON: #{e.message}",
+          template: template_name,
+          timestamp: Time.now.iso8601
+        }
+      }
+
+      {
+        content: JSON.generate(error_data),
+        content_type: 'application/json',
+        headers: json_headers(error_data)
+      }
+    rescue StandardError => e
+      # Handle any other unexpected errors during JSON generation
+      error_data = {
+        error: {
+          message: "Unexpected error during JSON generation: #{e.message}",
+          template: template_name,
+          timestamp: Time.now.iso8601
+        }
+      }
+
+      {
+        content: JSON.generate(error_data),
+        content_type: 'application/json',
+        headers: json_headers(error_data)
+      }
+    end
+
+    # Render ES module response for modulepreload strategy
+    def render_module(template_name, additional_context = {})
+      merged_data = process_template_data(template_name, additional_context)
+
+      {
+        content: "export default #{JSON.generate(merged_data)};",
+        content_type: 'text/javascript',
+        headers: module_headers(merged_data)
+      }
+    end
+
+    # Render JSONP response with callback
+    def render_jsonp(template_name, callback_name, additional_context = {})
+      merged_data = process_template_data(template_name, additional_context)
+
+      {
+        content: "#{callback_name}(#{JSON.generate(merged_data)});",
+        content_type: 'application/javascript',
+        headers: jsonp_headers(merged_data),
+      }
+    end
+
+    # Check if template data has changed (for ETags)
+    def data_changed?(template_name, etag, additional_context = {})
+      current_etag = calculate_etag(template_name, additional_context)
+      current_etag != etag
+    end
+
+    # Get ETag for current template data
+    def calculate_etag(template_name, additional_context = {})
+      merged_data = process_template_data(template_name, additional_context)
+      # Simple ETag based on data hash
+      Digest::MD5.hexdigest(JSON.generate(merged_data))
+    end
+
+    private
+
+    def process_template_data(template_name, additional_context)
+      # Create a minimal context for data processing
+      template_context = create_template_context(additional_context)
+
+      # Process template to extract hydration data
+      view = View.new(@context.req, @context.sess, @context.cust, @context.locale, props: {})
+      aggregator = HydrationDataAggregator.new(template_context)
+
+      # Build composition to get template dependencies
+      composition = view.send(:build_view_composition, template_name)
+      composition.resolve!
+
+      # Aggregate data from all templates in the composition
+      aggregator.aggregate(composition)
+    rescue StandardError => ex
+      # Return error structure that can be serialized
+      {
+        error: {
+          message: "Failed to process template data: #{ex.message}",
+          template: template_name,
+          timestamp: Time.now.iso8601,
+        }
+      }
+    end
+
+    def create_template_context(additional_context)
+      if @context
+        # Merge additional context into existing context by reconstructing with merged props
+        merged_props = @context.props.merge(additional_context)
+        @context.class.for_view(@context.req, @context.sess, @context.cust, @context.locale, **merged_props)
+      else
+        # Create minimal context with just the additional data
+        Context.minimal(props: additional_context)
+      end
+    end
+
+    def json_headers(data)
+      headers = {
+        'Content-Type' => 'application/json',
+        'Cache-Control' => cache_control_header,
+        'Vary' => 'Accept, Accept-Encoding'
+      }
+
+      # Add CORS headers if enabled
+      if cors_enabled?
+        headers.merge!(cors_headers)
+      end
+
+      # Add ETag for caching
+      headers['ETag'] = %("#{Digest::MD5.hexdigest(JSON.generate(data))}")
+
+      headers
+    end
+
+    def module_headers(data)
+      headers = json_headers(data)
+      headers['Content-Type'] = 'text/javascript'
+      headers
+    end
+
+    def jsonp_headers(data)
+      headers = json_headers(data)
+      headers['Content-Type'] = 'application/javascript'
+      headers
+    end
+
+    def cache_control_header
+      if @config.hydration.api_cache_enabled
+        "public, max-age=#{@config.hydration.api_cache_ttl || 300}"
+      else
+        "no-cache, no-store, must-revalidate"
+      end
+    end
+
+    def cors_enabled?
+      @config.hydration.cors_enabled || false
+    end
+
+    def cors_headers
+      {
+        'Access-Control-Allow-Origin' => @config.hydration.cors_origin || '*',
+        'Access-Control-Allow-Methods' => 'GET, HEAD, OPTIONS',
+        'Access-Control-Allow-Headers' => 'Accept, Accept-Encoding, Authorization',
+        'Access-Control-Max-Age' => '86400'
+      }
+    end
+  end
+end

data/lib/rhales/hydration_injector.rb

@@ -0,0 +1,171 @@
+require_relative 'earliest_injection_detector'
+require_relative 'link_based_injection_detector'
+
+module Rhales
+  # Handles intelligent hydration script injection with multiple strategies
+  # for optimal performance and resource loading.
+  #
+  # ## Supported Injection Strategies
+  #
+  # ### Traditional Strategies
+  # - **`:late`** (default) - Inject before </body> tag (safest, backwards compatible)
+  # - **`:early`** - Inject before detected mount points (#app, #root, etc.)
+  # - **`:earliest`** - Inject in HTML head section for maximum performance
+  #
+  # ### Link-Based Strategies (API endpoints)
+  # - **`:link`** - Basic link reference to API endpoint
+  # - **`:prefetch`** - Browser prefetch for future page loads
+  # - **`:preload`** - High priority preload for current page
+  # - **`:modulepreload`** - ES module preloading
+  # - **`:lazy`** - Intersection observer-based lazy loading
+  #
+  # ## Strategy Selection Logic
+  #
+  # 1. **Template Disable Check**: Respect `disable_early_for_templates` configuration
+  # 2. **Strategy Routing**: Execute strategy-specific injection logic
+  # 3. **Fallback Chain**: :earliest → :early → :late (when enabled)
+  # 4. **Safety Validation**: All injection points validated for HTML safety
+  #
+  # Link-based strategies generate API calls instead of inline data,
+  # enabling better caching, parallel loading, and reduced HTML payload.
+  #
+  class HydrationInjector
+    LINK_BASED_STRATEGIES = [:link, :prefetch, :preload, :modulepreload, :lazy].freeze
+
+    def initialize(hydration_config, template_name = nil)
+      @hydration_config = hydration_config
+      @template_name = template_name
+      @strategy = hydration_config.injection_strategy
+      @fallback_to_late = hydration_config.fallback_to_late
+      @fallback_when_unsafe = hydration_config.fallback_when_unsafe
+      @disabled_templates = hydration_config.disable_early_for_templates
+      @earliest_detector = EarliestInjectionDetector.new
+      @link_detector = LinkBasedInjectionDetector.new(hydration_config)
+    end
+
+    def inject(template_html, hydration_html, mount_point_data = nil)
+      return template_html if hydration_html.nil? || hydration_html.strip.empty?
+
+      # Check if early/earliest injection is disabled for this template
+      if [:early, :earliest].include?(@strategy) && template_disabled_for_early?
+        return inject_late(template_html, hydration_html)
+      end
+
+      case @strategy
+      when :early
+        inject_early(template_html, hydration_html, mount_point_data)
+      when :earliest
+        inject_earliest(template_html, hydration_html)
+      when :late
+        inject_late(template_html, hydration_html)
+      when *LINK_BASED_STRATEGIES
+        inject_link_based(template_html, hydration_html)
+      else
+        inject_late(template_html, hydration_html)
+      end
+    end
+
+    # Special method for link-based strategies that need merged data context
+    def inject_link_based_strategy(template_html, merged_data, nonce = nil)
+      return template_html if merged_data.nil? || merged_data.empty?
+
+      # Check if early injection is disabled for this template
+      if template_disabled_for_early?
+        # For link strategies, we still generate the links but fall back to late positioning
+        link_html = generate_all_link_strategies(merged_data, nonce)
+        return inject_late(template_html, link_html)
+      end
+
+      link_html = generate_all_link_strategies(merged_data, nonce)
+
+      case @strategy
+      when :earliest
+        inject_earliest(template_html, link_html)
+      when *LINK_BASED_STRATEGIES
+        inject_link_based(template_html, link_html)
+      else
+        inject_late(template_html, link_html)
+      end
+    end
+
+    private
+
+    def inject_early(template_html, hydration_html, mount_point_data)
+      # Fallback to late injection if no mount point found
+      if mount_point_data.nil?
+        return @fallback_to_late ? inject_late(template_html, hydration_html) : template_html
+      end
+
+      # Check if the mount point data indicates an unsafe injection
+      # (This would be nil if SafeInjectionValidator found no safe position)
+      if mount_point_data[:position].nil?
+        return @fallback_when_unsafe ? inject_late(template_html, hydration_html) : template_html
+      end
+
+      # Insert hydration script before the mount element
+      position = mount_point_data[:position]
+
+      before = template_html[0...position]
+      after = template_html[position..]
+
+      "#{before}#{hydration_html}\n#{after}"
+    end
+
+    def template_disabled_for_early?
+      @template_name && @disabled_templates.include?(@template_name)
+    end
+
+    def inject_earliest(template_html, hydration_html)
+      begin
+        injection_position = @earliest_detector.detect(template_html)
+      rescue => e
+        # Fall back to late injection on detector error
+        return @fallback_to_late ? inject_late(template_html, hydration_html) : template_html
+      end
+
+      if injection_position
+        before = template_html[0...injection_position]
+        after = template_html[injection_position..]
+        "#{before}#{hydration_html}\n#{after}"
+      else
+        # Fallback to late injection if earliest fails
+        @fallback_to_late ? inject_late(template_html, hydration_html) : template_html
+      end
+    end
+
+    def inject_link_based(template_html, hydration_html)
+      # For link-based strategies, try earliest injection first, then fallback
+      injection_position = @earliest_detector.detect(template_html)
+
+      if injection_position
+        before = template_html[0...injection_position]
+        after = template_html[injection_position..]
+        "#{before}#{hydration_html}\n#{after}"
+      else
+        # Fallback to late injection
+        @fallback_to_late ? inject_late(template_html, hydration_html) : template_html
+      end
+    end
+
+    def generate_all_link_strategies(merged_data, nonce)
+      link_parts = []
+
+      merged_data.each do |window_attr, _data|
+        link_html = @link_detector.generate_for_strategy(@strategy, @template_name, window_attr, nonce)
+        link_parts << link_html
+      end
+
+      link_parts.join("\n")
+    end
+
+    def inject_late(template_html, hydration_html)
+      # Try to inject before closing </body> tag
+      if template_html.include?('</body>')
+        template_html.sub('</body>', "#{hydration_html}\n</body>")
+      else
+        # If no </body> tag, append to end
+        "#{template_html}\n#{hydration_html}"
+      end
+    end
+  end
+end

data/lib/rhales/hydrator.rb

@@ -63,8 +63,8 @@ module Rhales
       # This method is now deprecated in favor of the two-pass architecture
       # It's kept for backward compatibility but will be removed in future versions
       def generate_hydration_html
-        warn "[DEPRECATION] Hydrator#generate_hydration_html is deprecated. Use the two-pass rendering architecture instead."
-        ""
+        warn '[DEPRECATION] Hydrator#generate_hydration_html is deprecated. Use the two-pass rendering architecture instead.'
+        ''
       end
 
       # Process <data> section and return JSON string
@@ -123,7 +123,7 @@ module Rhales
         # Convenience method to generate hydration HTML
         # DEPRECATED: Use the two-pass rendering architecture instead
         def generate(parser, context)
-          warn "[DEPRECATION] Hydrator.generate is deprecated. Use the two-pass rendering architecture instead."
+          warn '[DEPRECATION] Hydrator.generate is deprecated. Use the two-pass rendering architecture instead.'
           new(parser, context).generate_hydration_html
         end