rhales 0.3.0 → 0.5.3

data/lib/rhales/hydration/hydration_endpoint.rb

@@ -0,0 +1,215 @@
+# lib/rhales/hydration/hydration_endpoint.rb
+#
+# frozen_string_literal: true
+
+require 'digest'
+require_relative '../utils/json_serializer'
+
+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: JSONSerializer.dump(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: JSONSerializer.dump(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: JSONSerializer.dump(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 #{JSONSerializer.dump(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}(#{JSONSerializer.dump(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(JSONSerializer.dump(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, client: {})
+      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.client.merge(additional_context)
+        @context.class.for_view(@context.req, @context.locale, **merged_props)
+      else
+        # Create minimal context with just the additional data
+        Context.minimal(client: 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(JSONSerializer.dump(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/hydration_injector.rb

@@ -0,0 +1,175 @@
+# lib/rhales/hydration/hydration_injector.rb
+#
+# frozen_string_literal: true
+
+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/{hydration_registry.rb → hydration/hydration_registry.rb}

@@ -1,4 +1,6 @@
 # lib/rhales/hydration_registry.rb
+#
+# frozen_string_literal: true
 
 module Rhales
   # Registry to track window attributes used in hydration blocks

data/lib/rhales/hydration/hydrator.rb

@@ -0,0 +1,102 @@
+# lib/rhales/hydrator.rb
+#
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative '../utils/json_serializer'
+
+module Rhales
+    # Data Hydrator for RSFC client-side data injection
+    #
+    # ## RSFC Security Model: Server-to-Client Security Boundary
+    #
+    # The Hydrator enforces a critical security boundary between server and client:
+    #
+    # ### Server Side (Template Rendering)
+    # - Templates have FULL server context access (like ERB/HAML)
+    # - Can access user objects, database connections, internal APIs
+    # - Can access secrets, configuration, authentication state
+    # - Can process sensitive business logic
+    #
+    # ### Client Side (Data Hydration)
+    # - Only data declared in <schema> sections reaches the browser
+    # - Creates explicit allowlist like designing a REST API
+    # - For <schema>: Direct props serialization (no interpolation)
+    # - JSON serialization validates data structure
+    #
+    # ### Process Flow (Schema-based, preferred)
+    # 1. Backend provides fully-resolved props to render call
+    # 2. Props are directly serialized as JSON
+    # 3. Client receives only the declared props
+    #
+    # ### Example (Schema-based)
+    # ```rue
+    # <schema lang="js-zod" window="appData">
+    # const schema = z.object({
+    #   user_name: z.string(),
+    #   theme: z.string()
+    # });
+    # </schema>
+    # ```
+    # Backend: render('template', user_name: user.name, theme: user.theme_preference)
+    #
+    #
+    # Server template can access {{user.admin?}} and {{internal_config}},
+    # but client only gets the declared user_name and theme values.
+    #
+    # This creates an API-like boundary where data is serialized once and
+    # parsed once, enforcing the same security model as REST endpoints.
+    #
+    # Note: With the new two-pass architecture, the Hydrator's role is
+    # greatly simplified. All data merging happens server-side in the
+    # HydrationDataAggregator, so this class only handles JSON generation
+    # for individual templates (used during the aggregation phase).
+    class Hydrator
+      class HydrationError < StandardError; end
+      class JSONSerializationError < HydrationError; end
+
+      attr_reader :parser, :context, :window_attribute
+
+      def initialize(parser, context)
+        @parser           = parser
+        @context          = context
+        @window_attribute = parser.window_attribute || 'data'
+      end
+
+# Process <schema> section and return JSON string
+      def process_data_section
+        # Check for schema section
+        if @parser.schema_lang
+          # Schema section: Direct props serialization
+          JSONSerializer.dump(@context.client)
+        else
+          # No hydration section
+          '{}'
+        end
+      rescue JSON::ParserError => ex
+        raise JSONSerializationError, "Invalid JSON in schema section: #{ex.message}"
+      end
+
+      # Get processed data as Ruby hash (for internal use)
+      def processed_data_hash
+        json_string = process_data_section
+        JSONSerializer.parse(json_string)
+      rescue JSON::ParserError => ex
+        raise JSONSerializationError, "Cannot parse processed data as JSON: #{ex.message}"
+      end
+
+      private
+
+class << self
+# Generate only JSON data (for testing or API endpoints)
+        def generate_json(parser, context)
+          new(parser, context).process_data_section
+        end
+
+        # Generate data hash (for internal processing)
+        def generate_data_hash(parser, context)
+          new(parser, context).processed_data_hash
+        end
+      end
+    end
+end

data/lib/rhales/hydration/link_based_injection_detector.rb

@@ -0,0 +1,195 @@
+# lib/rhales/hydration/link_based_injection_detector.rb
+#
+# frozen_string_literal: true
+
+require 'strscan'
+require_relative 'safe_injection_validator'
+
+module Rhales
+  # Generates link-based hydration strategies that use browser resource hints
+  # and API endpoints instead of inline scripts
+  #
+  # ## Supported Strategies
+  #
+  # - **`:link`** - Basic link reference: `<link href="/api/hydration/template">`
+  # - **`:prefetch`** - Background prefetch: `<link rel="prefetch" href="..." as="fetch">`
+  # - **`:preload`** - High priority preload: `<link rel="preload" href="..." as="fetch">`
+  # - **`:modulepreload`** - ES module preload: `<link rel="modulepreload" href="..."`
+  # - **`:lazy`** - Lazy loading with intersection observer
+  #
+  # All strategies generate both link tags and accompanying JavaScript
+  # for data fetching and assignment to window objects.
+  class LinkBasedInjectionDetector
+    def initialize(hydration_config)
+      @hydration_config = hydration_config
+      @api_endpoint_path = hydration_config.api_endpoint_path || '/api/hydration'
+      @crossorigin_enabled = hydration_config.link_crossorigin.nil? ? true : hydration_config.link_crossorigin
+    end
+
+    def generate_for_strategy(strategy, template_name, window_attr, nonce = nil)
+      case strategy
+      when :link
+        generate_basic_link(template_name, window_attr, nonce)
+      when :prefetch
+        generate_prefetch_link(template_name, window_attr, nonce)
+      when :preload
+        generate_preload_link(template_name, window_attr, nonce)
+      when :modulepreload
+        generate_modulepreload_link(template_name, window_attr, nonce)
+      when :lazy
+        generate_lazy_loading(template_name, window_attr, nonce)
+      else
+        raise ArgumentError, "Unsupported link strategy: #{strategy}"
+      end
+    end
+
+    private
+
+    def generate_basic_link(template_name, window_attr, nonce)
+      endpoint_url = "#{@api_endpoint_path}/#{template_name}"
+
+      link_tag = %(<link href="#{endpoint_url}" type="application/json">)
+
+      script_tag = <<~HTML.strip
+        <script#{nonce_attribute(nonce)} data-hydration-target="#{window_attr}">
+        // Load hydration data for #{window_attr}
+        window.__rhales__ = window.__rhales__ || {};
+        if (!window.__rhales__.loadData) {
+          window.__rhales__.loadData = function(target, url) {
+            fetch(url)
+              .then(r => r.json())
+              .then(data => window[target] = data);
+          };
+        }
+        window.__rhales__.loadData('#{window_attr}', '#{endpoint_url}');
+        </script>
+      HTML
+
+      "#{link_tag}\n#{script_tag}"
+    end
+
+    def generate_prefetch_link(template_name, window_attr, nonce)
+      endpoint_url = "#{@api_endpoint_path}/#{template_name}"
+      crossorigin_attr = @crossorigin_enabled ? ' crossorigin' : ''
+
+      link_tag = %(<link rel="prefetch" href="#{endpoint_url}" as="fetch"#{crossorigin_attr}>)
+
+      script_tag = <<~HTML.strip
+        <script#{nonce_attribute(nonce)} data-hydration-target="#{window_attr}">
+        // Prefetch hydration data for #{window_attr}
+        window.__rhales__ = window.__rhales__ || {};
+        if (!window.__rhales__.loadPrefetched) {
+          window.__rhales__.loadPrefetched = function(target, url) {
+            fetch(url)
+              .then(r => r.json())
+              .then(data => window[target] = data);
+          };
+        }
+        window.__rhales__.loadPrefetched('#{window_attr}', '#{endpoint_url}');
+        </script>
+      HTML
+
+      "#{link_tag}\n#{script_tag}"
+    end
+
+    def generate_preload_link(template_name, window_attr, nonce)
+      endpoint_url = "#{@api_endpoint_path}/#{template_name}"
+      crossorigin_attr = @crossorigin_enabled ? ' crossorigin' : ''
+
+      link_tag = %(<link rel="preload" href="#{endpoint_url}" as="fetch"#{crossorigin_attr}>)
+
+      script_tag = <<~HTML.strip
+        <script#{nonce_attribute(nonce)} data-hydration-target="#{window_attr}">
+        // Preload strategy - high priority fetch
+        fetch('#{endpoint_url}')
+          .then(r => r.json())
+          .then(data => {
+            window['#{window_attr}'] = data;
+            // Dispatch ready event
+            window.dispatchEvent(new CustomEvent('rhales:hydrated', {
+              detail: { target: '#{window_attr}', data: data }
+            }));
+          })
+          .catch(err => console.error('Rhales hydration error:', err));
+        </script>
+      HTML
+
+      "#{link_tag}\n#{script_tag}"
+    end
+
+    def generate_modulepreload_link(template_name, window_attr, nonce)
+      endpoint_url = "#{@api_endpoint_path}/#{template_name}.js"
+
+      link_tag = %(<link rel="modulepreload" href="#{endpoint_url}">)
+
+      script_tag = <<~HTML.strip
+        <script type="module"#{nonce_attribute(nonce)} data-hydration-target="#{window_attr}">
+        // Module preload strategy
+        import data from '#{endpoint_url}';
+        window['#{window_attr}'] = data;
+
+        // Dispatch ready event
+        window.dispatchEvent(new CustomEvent('rhales:hydrated', {
+          detail: { target: '#{window_attr}', data: data }
+        }));
+        </script>
+      HTML
+
+      "#{link_tag}\n#{script_tag}"
+    end
+
+    def generate_lazy_loading(template_name, window_attr, nonce)
+      endpoint_url = "#{@api_endpoint_path}/#{template_name}"
+      mount_selector = @hydration_config.lazy_mount_selector || '#app'
+
+      # No link tag for lazy loading - purely script-driven
+      script_tag = <<~HTML.strip
+        <script#{nonce_attribute(nonce)} data-hydration-target="#{window_attr}" data-lazy-src="#{endpoint_url}">
+        // Lazy loading strategy with intersection observer
+        window.__rhales__ = window.__rhales__ || {};
+        window.__rhales__.initLazyLoading = function() {
+          const mountElement = document.querySelector('#{mount_selector}');
+          if (!mountElement) {
+            console.warn('Rhales: Mount element "#{mount_selector}" not found for lazy loading');
+            return;
+          }
+
+          const observer = new IntersectionObserver((entries) => {
+            entries.forEach(entry => {
+              if (entry.isIntersecting) {
+                fetch('#{endpoint_url}')
+                  .then(r => r.json())
+                  .then(data => {
+                    window['#{window_attr}'] = data;
+                    window.dispatchEvent(new CustomEvent('rhales:hydrated', {
+                      detail: { target: '#{window_attr}', data: data }
+                    }));
+                  })
+                  .catch(err => console.error('Rhales lazy hydration error:', err));
+
+                observer.unobserve(entry.target);
+              }
+            });
+          });
+
+          observer.observe(mountElement);
+        };
+
+        // Initialize when DOM is ready
+        if (document.readyState === 'loading') {
+          document.addEventListener('DOMContentLoaded', window.__rhales__.initLazyLoading);
+        } else {
+          window.__rhales__.initLazyLoading();
+        }
+        </script>
+      HTML
+
+      script_tag
+    end
+
+    def nonce_attribute(nonce)
+      require 'erb'
+      nonce ? " nonce=\"#{ERB::Util.html_escape(nonce)}\"" : ''
+    end
+  end
+end