rhales 0.3.0 → 0.5.3

data/lib/rhales/hydration/mount_point_detector.rb

@@ -0,0 +1,109 @@
+# lib/rhales/hydration/mount_point_detector.rb
+#
+# frozen_string_literal: true
+
+require 'strscan'
+require_relative 'safe_injection_validator'
+
+module Rhales
+  # Detects frontend application mount points in HTML templates
+  # Used to determine optimal hydration script injection points
+  #
+  # ## Mount Point Detection Order
+  #
+  # 1. **Selector Priority**: All selectors (default + custom) are checked in parallel
+  # 2. **Position Priority**: Returns the earliest mount point by position in HTML (not selector order)
+  # 3. **Safety Validation**: Validates injection points are outside unsafe contexts (scripts/styles/comments)
+  # 4. **Safe Position Search**: If original position unsafe, searches for nearest safe alternative:
+  #    - First tries positions before the mount point (maintains earlier injection)
+  #    - Then tries positions after the mount point (fallback)
+  #    - Returns nil if no safe position found
+  #
+  # Default selectors are checked: ['#app', '#root', '[data-rsfc-mount]', '[data-mount]']
+  # Custom selectors can be added via configuration and are combined with defaults.
+  class MountPointDetector
+    DEFAULT_SELECTORS = ['#app', '#root', '[data-rsfc-mount]', '[data-mount]'].freeze
+
+    def detect(template_html, custom_selectors = [])
+      selectors = (DEFAULT_SELECTORS + Array(custom_selectors)).uniq
+      scanner = StringScanner.new(template_html)
+      validator = SafeInjectionValidator.new(template_html)
+      mount_points = []
+
+      selectors.each do |selector|
+        scanner.pos = 0
+        pattern = build_pattern(selector)
+
+        while scanner.scan_until(pattern)
+          # Calculate position where the full tag starts
+          tag_start_pos = find_tag_start(scanner, template_html)
+
+          # Only include mount points that are safe for injection
+          safe_position = find_safe_injection_position(validator, tag_start_pos)
+
+          if safe_position
+            mount_points << {
+              selector: selector,
+              position: safe_position,
+              original_position: tag_start_pos,
+              matched: scanner.matched
+            }
+          end
+        end
+      end
+
+      # Return earliest mount point by position
+      mount_points.min_by { |mp| mp[:position] }
+    end
+
+    private
+
+    def build_pattern(selector)
+      case selector
+      when /^#(.+)$/
+        # ID selector: <tag id="value">
+        id_name = Regexp.escape($1)
+        /id\s*=\s*["']#{id_name}["']/i
+      when /^\.(.+)$/
+        # Class selector: <tag class="... value ...">
+        class_name = Regexp.escape($1)
+        /class\s*=\s*["'][^"']*\b#{class_name}\b[^"']*["']/i
+      when /^\[([^\]]+)\]$/
+        # Attribute selector: <tag data-attr> or <tag data-attr="value">
+        attr_name = Regexp.escape($1)
+        /#{attr_name}(?:\s*=\s*["'][^"']*["'])?/i
+      else
+        # Invalid selector, match nothing
+        /(?!.*)/
+      end
+    end
+
+    def find_tag_start(scanner, template_html)
+      # Work backwards from current position to find the opening <
+      pos = scanner.pos - scanner.matched.length
+
+      while pos > 0 && template_html[pos - 1] != '<'
+        pos -= 1
+      end
+
+      # Return position of the < character
+      pos > 0 ? pos - 1 : 0
+    end
+
+    def find_safe_injection_position(validator, preferred_position)
+      # First check if the preferred position is safe
+      return preferred_position if validator.safe_injection_point?(preferred_position)
+
+      # Try to find a safe position before the preferred position
+      safe_before = validator.nearest_safe_point_before(preferred_position)
+      return safe_before if safe_before
+
+      # As a last resort, try after the preferred position
+      safe_after = validator.nearest_safe_point_after(preferred_position)
+      return safe_after if safe_after
+
+      # No safe position found
+      nil
+    end
+  end
+end

data/lib/rhales/hydration/safe_injection_validator.rb

@@ -0,0 +1,103 @@
+# lib/rhales/hydration/safe_injection_validator.rb
+#
+# frozen_string_literal: true
+
+require 'strscan'
+
+module Rhales
+  # Validates whether a hydration injection point is safe within HTML context
+  # Prevents injection inside script tags, style tags, comments, or other unsafe locations
+  class SafeInjectionValidator
+    UNSAFE_CONTEXTS = [
+      { start: /<script\b[^>]*>/i, end: /<\/script>/i },
+      { start: /<style\b[^>]*>/i, end: /<\/style>/i },
+      { start: /<!--/, end: /-->/ },
+      { start: /<!\[CDATA\[/, end: /\]\]>/ }
+    ].freeze
+
+    def initialize(html)
+      @html = html
+      @unsafe_ranges = calculate_unsafe_ranges
+    end
+
+    # Check if the given position is safe for injection
+    def safe_injection_point?(position)
+      return false if position < 0 || position > @html.length
+
+      # Check if position falls within any unsafe range
+      @unsafe_ranges.none? { |range| range.cover?(position) }
+    end
+
+    # Find the nearest safe injection point before the given position
+    def nearest_safe_point_before(position)
+      # Work backwards from position to find a safe point
+      (0...position).reverse_each do |pos|
+        return pos if safe_injection_point?(pos) && at_tag_boundary?(pos)
+      end
+
+      # If no safe point found before, return nil
+      nil
+    end
+
+    # Find the nearest safe injection point after the given position
+    def nearest_safe_point_after(position)
+      # Work forwards from position to find a safe point
+      (position...@html.length).each do |pos|
+        return pos if safe_injection_point?(pos) && at_tag_boundary?(pos)
+      end
+
+      # If no safe point found after, return nil
+      nil
+    end
+
+    private
+
+    def calculate_unsafe_ranges
+      ranges = []
+      scanner = StringScanner.new(@html)
+
+      UNSAFE_CONTEXTS.each do |context|
+        scanner.pos = 0
+
+        while scanner.scan_until(context[:start])
+          start_pos = scanner.pos - scanner.matched.length
+
+          # Find the corresponding end tag
+          if scanner.scan_until(context[:end])
+            end_pos = scanner.pos
+            ranges << (start_pos...end_pos)
+          else
+            # If no closing tag found, consider rest of document unsafe
+            ranges << (start_pos...@html.length)
+            break
+          end
+        end
+      end
+
+      ranges
+    end
+
+    # Check if position is at a tag boundary (before < or after >)
+    def at_tag_boundary?(position)
+      return true if position == 0 || position == @html.length
+
+      char_before = position > 0 ? @html[position - 1] : nil
+      char_at = @html[position]
+
+      # Safe positions:
+      # - Right after a closing >
+      # - Right before an opening <
+      # - At whitespace boundaries between tags
+      char_before == '>' || char_at == '<' || (char_at&.match?(/\s/) && next_non_whitespace_is_tag?(position))
+    end
+
+    def next_non_whitespace_is_tag?(position)
+      pos = position
+      while pos < @html.length && @html[pos].match?(/\s/)
+        pos += 1
+      end
+
+      pos < @html.length && @html[pos] == '<'
+    end
+  end
+end

data/lib/rhales/hydration.rb

@@ -0,0 +1,13 @@
+# lib/rhales/hydration.rb
+#
+# frozen_string_literal: true
+
+require_relative 'hydration/hydrator'
+require_relative 'hydration/hydration_data_aggregator'
+require_relative 'hydration/mount_point_detector'
+require_relative 'hydration/safe_injection_validator'
+require_relative 'hydration/earliest_injection_detector'
+require_relative 'hydration/link_based_injection_detector'
+require_relative 'hydration/hydration_injector'
+require_relative 'hydration/hydration_endpoint'
+require_relative 'hydration/hydration_registry'

data/lib/rhales/{refinements → integrations/refinements}/require_refinements.rb

@@ -1,6 +1,8 @@
 # lib/rhales/refinements/require_refinements.rb
+#
+# frozen_string_literal: true
 
-require_relative '../rue_document'
+require_relative '../../core/rue_document'
 
 module Rhales
   module Ruequire
@@ -111,11 +113,7 @@ module Rhales
 
         parser
       rescue StandardError => ex
-        if defined?(OT) && OT.respond_to?(:le)
-          OT.le "[RSFC] Failed to process .rue file #{path}: #{ex.message}"
-        else
-          puts "[RSFC] Failed to process .rue file #{path}: #{ex.message}"
-        end
+        puts "[RSFC] Failed to process .rue file #{path}: #{ex.message}"
         raise
       end
 
@@ -130,7 +128,7 @@ module Rhales
         return File.expand_path(path) if File.exist?(path)
 
         # Search in templates directory
-        boot_root      = defined?(OT) && OT.respond_to?(:boot_root) ? OT.boot_root : File.expand_path('../../..', __dir__)
+        boot_root      = File.expand_path('../../..', __dir__)
         templates_path = File.join(boot_root, 'templates', path)
         return templates_path if File.exist?(templates_path)
 
@@ -197,9 +195,7 @@ module Rhales
               current_mtime = File.mtime(full_path)
 
               if current_mtime > last_mtime
-                if defined?(OT) && OT.respond_to?(:ld)
-                  OT.ld "[RSFC] File changed, clearing cache: #{full_path}"
-                end
+                puts "[RSFC] File changed, clearing cache: #{full_path}"
 
                 # Thread-safe cache removal
                 Rhales::Ruequire.instance_variable_get(:@cache_mutex).synchronize do
@@ -210,9 +206,7 @@ module Rhales
               end
             rescue StandardError => ex
               # File might have been deleted
-              if defined?(OT) && OT.respond_to?(:ld)
-                OT.ld "[RSFC] File watcher error for #{full_path}: #{ex.message}"
-              end
+              puts "[RSFC] File watcher error for #{full_path}: #{ex.message}"
 
               # Clean up watcher entry on error
               watchers_mutex.synchronize do

data/lib/rhales/{tilt.rb → integrations/tilt.rb}

@@ -1,8 +1,9 @@
+# lib/rhales/integrations/tilt.rb
+#
 # frozen_string_literal: true
 
 require 'tilt'
-require 'rhales'
-require_relative 'adapters/base_request'
+require_relative '../adapters/base_request'
 
 module Rhales
   # Tilt integration for Rhales templates
@@ -109,7 +110,8 @@ module Rhales
         framework_env = scope.request.env.merge({
           'nonce' => shared_nonce,
           'request_id' => SecureRandom.hex(8),
-        })
+        },
+                                               )
 
         # Create wrapper that preserves original but adds our env
         wrapped_request = Class.new do
@@ -118,8 +120,8 @@ module Rhales
             @custom_env = custom_env
           end
 
-          def method_missing(method, *args, &block)
-            @original.send(method, *args, &block)
+          def method_missing(method, *, &)
+            @original.send(method, *, &)
           end
 
           def respond_to_missing?(method, include_private = false)
@@ -141,11 +143,11 @@ module Rhales
           env: {
             'nonce' => shared_nonce,
             'request_id' => SecureRandom.hex(8),
-          }
+          },
         )
       end
 
-      # Use proper session adapter
+      # Build session and auth adapters
       session_data = if scope.respond_to?(:logged_in?) && scope.logged_in?
         Rhales::Adapters::AuthenticatedSession.new(
           {
@@ -157,25 +159,31 @@ module Rhales
         Rhales::Adapters::AnonymousSession.new
       end
 
-      # Use proper auth adapter
-      if scope.respond_to?(:logged_in?) && scope.logged_in? && scope.respond_to?(:current_user)
-        user      = scope.current_user
-        auth_data = Rhales::Adapters::AuthenticatedAuth.new({
+      auth_data = if scope.respond_to?(:logged_in?) && scope.logged_in? && scope.respond_to?(:current_user)
+        user = scope.current_user
+        Rhales::Adapters::AuthenticatedAuth.new({
           id: user[:id],
           email: user[:email],
           authenticated: true,
-        },
-                                                           )
+        })
       else
-        auth_data = Rhales::Adapters::AnonymousAuth.new
+        Rhales::Adapters::AnonymousAuth.new
       end
 
+      # Extend request_data to expose session and user
+      request_data.define_singleton_method(:session) { session_data }
+      request_data.define_singleton_method(:user) { auth_data }
+
+      # Split props into client (serialized) and server (template-only) data
+      # By default, all Tilt locals go to client for backward compatibility
+      # Frameworks can use :server_data and :client_data keys to override
+      client_data = props.delete(:client_data) || props.dup
+      server_data = props.delete(:server_data) || {}
+
       ::Rhales::View.new(
         request_data,
-        session_data,
-        auth_data,
-        nil, # locale_override
-        props: props,
+        client: client_data,
+        server: server_data,
       )
     end
 

data/lib/rhales/integrations.rb

@@ -0,0 +1,6 @@
+# lib/rhales/integrations.rb
+#
+# frozen_string_literal: true
+
+require_relative 'integrations/tilt'
+require_relative 'integrations/refinements/require_refinements'

data/lib/rhales/middleware/json_responder.rb

@@ -0,0 +1,191 @@
+# lib/rhales/middleware/json_responder.rb
+#
+# frozen_string_literal: true
+
+require_relative '../utils/json_serializer'
+
+module Rhales
+  module Middleware
+    # Rack middleware that returns hydration data as JSON when Accept: application/json
+    #
+    # When a request has Accept: application/json header, this middleware
+    # intercepts the response and returns just the hydration data as JSON
+    # instead of rendering the full HTML template.
+    #
+    # This enables:
+    # - API clients to fetch data from the same endpoints
+    # - Testing hydration data without parsing HTML
+    # - Development inspection of data flow
+    # - Mobile/native clients using the same routes
+    #
+    # @example Basic usage with Rack
+    #   use Rhales::Middleware::JsonResponder,
+    #     enabled: true,
+    #     include_metadata: false
+    #
+    # @example With Roda
+    #   use Rhales::Middleware::JsonResponder,
+    #     enabled: ENV['RACK_ENV'] != 'production',
+    #     include_metadata: ENV['RACK_ENV'] == 'development'
+    #
+    # @example Response format (single window)
+    #   GET /dashboard
+    #   Accept: application/json
+    #
+    #   {
+    #     "user": {"id": 1, "name": "Alice"},
+    #     "authenticated": true
+    #   }
+    #
+    # @example Response format (multiple windows)
+    #   {
+    #     "appData": {"user": {...}},
+    #     "config": {"theme": "dark"}
+    #   }
+    #
+    # @example Response with metadata (development)
+    #   {
+    #     "template": "dashboard",
+    #     "data": {"user": {...}}
+    #   }
+    class JsonResponder
+      # Initialize the middleware
+      #
+      # @param app [#call] The Rack application
+      # @param options [Hash] Configuration options
+      # @option options [Boolean] :enabled Whether JSON responses are enabled (default: true)
+      # @option options [Boolean] :include_metadata Whether to include metadata in responses (default: false)
+      def initialize(app, options = {})
+        @app = app
+        @enabled = options.fetch(:enabled, true)
+        @include_metadata = options.fetch(:include_metadata, false)
+      end
+
+      # Process the Rack request
+      #
+      # @param env [Hash] The Rack environment
+      # @return [Array] Rack response tuple [status, headers, body]
+      def call(env)
+        return @app.call(env) unless @enabled
+        return @app.call(env) unless accepts_json?(env)
+
+        # Get the response from the app
+        status, headers, body = @app.call(env)
+
+        # Only process successful HTML responses
+        return [status, headers, body] unless status == 200
+        return [status, headers, body] unless html_response?(headers)
+
+        # Extract hydration data from HTML
+        html_body = extract_body(body)
+        hydration_data = extract_hydration_data(html_body)
+
+        # Return empty object if no hydration data found
+        if hydration_data.empty?
+          return json_response({}, env)
+        end
+
+        # Build response data
+        response_data = if @include_metadata
+          {
+            template: env['rhales.template_name'],
+            data: hydration_data
+          }
+        else
+          # Flatten if single window, or return all windows
+          hydration_data.size == 1 ? hydration_data.values.first : hydration_data
+        end
+
+        json_response(response_data, env)
+      end
+
+      private
+
+      # Check if request accepts JSON
+      #
+      # Parses Accept header and checks for application/json.
+      # Handles weighted preferences (e.g., "application/json;q=0.9")
+      #
+      # @param env [Hash] Rack environment
+      # @return [Boolean] true if application/json is accepted
+      def accepts_json?(env)
+        accept = env['HTTP_ACCEPT']
+        return false unless accept
+
+        # Check if application/json is requested
+        # Handle weighted preferences (e.g., "application/json;q=0.9")
+        accept.split(',').any? do |type|
+          type.strip.start_with?('application/json')
+        end
+      end
+
+      # Check if response is HTML
+      #
+      # @param headers [Hash] Response headers
+      # @return [Boolean] true if Content-Type is text/html
+      def html_response?(headers)
+        # Support both uppercase and lowercase header names for compatibility
+        content_type = headers['content-type'] || headers['Content-Type']
+        content_type && content_type.include?('text/html')
+      end
+
+      # Extract response body as string
+      #
+      # Handles different Rack body types (Array, IO, String)
+      #
+      # @param body [Array, IO, String] Rack response body
+      # @return [String] Body content as string
+      def extract_body(body)
+        if body.respond_to?(:each)
+          body.each.to_a.join
+        elsif body.respond_to?(:read)
+          body.read
+        else
+          body.to_s
+        end
+      end
+
+      # Extract hydration JSON blocks from HTML
+      #
+      # Looks for <script type="application/json" data-window="varName"> tags
+      # and parses their JSON content. Returns a hash keyed by window variable name.
+      #
+      # @param html [String] HTML response body
+      # @return [Hash] Hydration data keyed by window variable name
+      def extract_hydration_data(html)
+        hydration_blocks = {}
+
+        # Match script tags with data-window attribute
+        html.scan(/<script[^>]*type=["']application\/json["'][^>]*data-window=["']([^"']+)["'][^>]*>(.*?)<\/script>/m) do |window_var, json_content|
+          begin
+            hydration_blocks[window_var] = JSONSerializer.parse(json_content.strip)
+          rescue JSON::ParserError => e
+            # Skip malformed JSON blocks
+            warn "Rhales::JsonResponder: Failed to parse hydration JSON for window.#{window_var}: #{e.message}"
+          end
+        end
+
+        hydration_blocks
+      end
+
+      # Build JSON response
+      #
+      # @param data [Hash, Array, Object] Response data
+      # @param env [Hash] Rack environment
+      # @return [Array] Rack response tuple
+      def json_response(data, env)
+        json_body = JSONSerializer.dump(data)
+
+        [
+          200,
+          {
+            'content-type' => 'application/json',
+            'content-length' => json_body.bytesize.to_s,
+            'cache-control' => 'no-cache'
+          },
+          [json_body]
+        ]
+      end
+    end
+  end
+end