rhales 0.4.0 → 0.5.4

data/lib/rhales/{link_based_injection_detector.rb → hydration/link_based_injection_detector.rb}

@@ -1,3 +1,7 @@
+# lib/rhales/hydration/link_based_injection_detector.rb
+#
+# frozen_string_literal: true
+
 require 'strscan'
 require_relative 'safe_injection_validator'
 

data/lib/rhales/{mount_point_detector.rb → hydration/mount_point_detector.rb}

@@ -1,3 +1,7 @@
+# lib/rhales/hydration/mount_point_detector.rb
+#
+# frozen_string_literal: true
+
 require 'strscan'
 require_relative 'safe_injection_validator'
 

data/lib/rhales/{safe_injection_validator.rb → hydration/safe_injection_validator.rb}

@@ -1,3 +1,7 @@
+# lib/rhales/hydration/safe_injection_validator.rb
+#
+# frozen_string_literal: true
+
 require 'strscan'
 
 module Rhales
@@ -51,16 +55,21 @@ module Rhales
     def calculate_unsafe_ranges
       ranges = []
       scanner = StringScanner.new(@html)
+      byte_to_char_map = build_byte_to_char_map(@html)
 
       UNSAFE_CONTEXTS.each do |context|
         scanner.pos = 0
 
         while scanner.scan_until(context[:start])
-          start_pos = scanner.pos - scanner.matched.length
+          # Convert byte position to character position using pre-built map
+          byte_start_pos = scanner.pos - scanner.matched.length
+          start_pos = byte_to_char_map[byte_start_pos]
 
           # Find the corresponding end tag
           if scanner.scan_until(context[:end])
-            end_pos = scanner.pos
+            # Convert byte position to character position using pre-built map
+            byte_end_pos = scanner.pos
+            end_pos = byte_to_char_map[byte_end_pos]
             ranges << (start_pos...end_pos)
           else
             # If no closing tag found, consider rest of document unsafe
@@ -95,5 +104,43 @@ module Rhales
 
       pos < @html.length && @html[pos] == '<'
     end
+
+    # Builds a mapping from byte positions to character positions for efficient
+    # conversion when processing UTF-8 strings with StringScanner.
+    #
+    # This method creates a hash where keys are byte positions and values are
+    # the corresponding character positions. For multibyte UTF-8 characters,
+    # only the starting byte position has an entry in the map.
+    #
+    # @param str [String] The UTF-8 encoded string to map
+    # @return [Hash<Integer, Integer>] A hash mapping byte positions to character positions
+    #
+    # @example ASCII string
+    #   build_byte_to_char_map("Hello")
+    #   # => {0=>0, 1=>1, 2=>2, 3=>3, 4=>4, 5=>5}
+    #
+    # @example UTF-8 with multibyte characters
+    #   build_byte_to_char_map("café")  # é is 2 bytes
+    #   # => {0=>0, 1=>1, 2=>2, 3=>3, 5=>4}  # Note: byte 4 is continuation byte
+    #
+    def build_byte_to_char_map(str)
+      map = {}
+      char_pos = 0
+      byte_pos = 0
+
+      # Iterate through each character (not byte) in the string
+      str.each_char do |char|
+        # Map the starting byte position of this character
+        map[byte_pos] = char_pos
+
+        # Advance byte position by the byte size of this character
+        byte_pos += char.bytesize
+        char_pos += 1
+      end
+
+      # Add final mapping for the end of the string
+      map[byte_pos] = char_pos
+      map
+    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

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

@@ -1,8 +1,9 @@
-# lib/rhales/tilt.rb
+# 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
@@ -146,7 +147,7 @@ module Rhales
         )
       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(
           {
@@ -158,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

data/lib/rhales/middleware/schema_validator.rb

@@ -0,0 +1,300 @@
+# lib/rhales/middleware/schema_validator.rb
+#
+# frozen_string_literal: true
+
+require 'json_schemer'
+require_relative '../utils/json_serializer'
+
+module Rhales
+  module Middleware
+    # Rack middleware that validates hydration data against JSON Schemas
+    #
+    # This middleware extracts hydration JSON from HTML responses and validates
+    # it against the JSON Schema for the template. In development, it fails
+    # loudly on mismatches. In production, it logs warnings but continues serving.
+    #
+    # @example Basic usage with Rack
+    #   use Rhales::Middleware::SchemaValidator,
+    #     schemas_dir: './public/schemas',
+    #     fail_on_error: ENV['RACK_ENV'] == 'development'
+    #
+    # @example With Roda
+    #   use Rhales::Middleware::SchemaValidator,
+    #     schemas_dir: File.expand_path('../public/schemas', __dir__),
+    #     fail_on_error: ENV['RACK_ENV'] == 'development',
+    #     enabled: true
+    #
+    # @example Accessing statistics
+    #   validator = app.middleware.find { |m| m.is_a?(Rhales::Middleware::SchemaValidator) }
+    #   puts validator.stats
+    class SchemaValidator
+      # Raised when schema validation fails in development mode
+      class ValidationError < StandardError; end
+
+      # Initialize the middleware
+      #
+      # @param app [#call] The Rack application
+      # @param options [Hash] Configuration options
+      # @option options [String] :schemas_dir Path to JSON schemas directory
+      # @option options [Boolean] :fail_on_error Whether to raise on validation errors
+      # @option options [Boolean] :enabled Whether validation is enabled
+      # @option options [Array<String>] :skip_paths Additional paths to skip validation
+      def initialize(app, options = {})
+        @app = app
+        # Default to public/schemas in implementing project's directory
+        @schemas_dir = options.fetch(:schemas_dir, './public/schemas')
+        @fail_on_error = options.fetch(:fail_on_error, false)
+        @enabled = options.fetch(:enabled, true)
+        @skip_paths = options.fetch(:skip_paths, [])
+        @schema_cache = {}
+        @stats = {
+          total_validations: 0,
+          total_time_ms: 0,
+          failures: 0
+        }
+      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) if skip_validation?(env)
+
+        status, headers, body = @app.call(env)
+
+        # Only validate HTML responses
+        content_type = headers['Content-Type']
+        return [status, headers, body] unless content_type&.include?('text/html')
+
+        # Get template name from env (set by View)
+        template_name = env['rhales.template_name']
+        return [status, headers, body] unless template_name
+
+        # Get template path if available (for better error messages)
+        template_path = env['rhales.template_path']
+
+        # Load schema for template
+        schema = load_schema_cached(template_name)
+        return [status, headers, body] unless schema
+
+        # Extract hydration data from response
+        html_body = extract_body(body)
+        hydration_data = extract_hydration_data(html_body)
+        return [status, headers, body] if hydration_data.empty?
+
+        # Validate each hydration block
+        start_time = Time.now
+        errors = validate_hydration_data(hydration_data, schema, template_name)
+        elapsed_ms = ((Time.now - start_time) * 1000).round(2)
+
+        # Update stats
+        @stats[:total_validations] += 1
+        @stats[:total_time_ms] += elapsed_ms
+        @stats[:failures] += 1 if errors.any?
+
+        # Handle errors
+        handle_errors(errors, template_name, template_path, elapsed_ms) if errors.any?
+
+        [status, headers, body]
+      end
+
+      # Get validation statistics
+      #
+      # @return [Hash] Statistics including avg_time_ms and success_rate
+      def stats
+        avg_time = @stats[:total_validations] > 0 ?
+          (@stats[:total_time_ms] / @stats[:total_validations]).round(2) : 0
+
+        @stats.merge(
+          avg_time_ms: avg_time,
+          success_rate: @stats[:total_validations] > 0 ?
+            ((@stats[:total_validations] - @stats[:failures]).to_f / @stats[:total_validations] * 100).round(2) : 0
+        )
+      end
+
+      private
+
+      # Check if validation should be skipped for this request
+      def skip_validation?(env)
+        path = env['PATH_INFO']
+
+        # Skip static assets, APIs, public files
+        return true if path.start_with?('/assets', '/api', '/public')
+
+        # Skip configured custom paths
+        return true if @skip_paths.any? { |skip_path| path.start_with?(skip_path) }
+
+        # Skip files with extensions typically not rendered by templates
+        return true if path.match?(/\.(css|js|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)\z/i)
+
+        false
+      end
+
+      # Load and cache JSON schema for template
+      def load_schema_cached(template_name)
+        @schema_cache[template_name] ||= begin
+          schema_path = File.join(@schemas_dir, "#{template_name}.json")
+
+          return nil unless File.exist?(schema_path)
+
+          schema_json = File.read(schema_path)
+          schema_hash = JSONSerializer.parse(schema_json)
+
+          # Create JSONSchemer validator
+          # Note: json_schemer handles $schema and $id properly
+          JSONSchemer.schema(schema_hash)
+        rescue JSON::ParserError => e
+          warn "Rhales::SchemaValidator: Failed to parse schema for #{template_name}: #{e.message}"
+          nil
+        rescue StandardError => e
+          warn "Rhales::SchemaValidator: Failed to load schema for #{template_name}: #{e.message}"
+          nil
+        end
+      end
+
+      # Extract response body 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
+      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
+            warn "Rhales::SchemaValidator: Failed to parse hydration JSON for window.#{window_var}: #{e.message}"
+          end
+        end
+
+        hydration_blocks
+      end
+
+      # Validate hydration data against schema
+      def validate_hydration_data(hydration_data, schema, template_name)
+        errors = []
+
+        hydration_data.each do |window_var, data|
+          # Validate data against schema using json_schemer
+          begin
+            validation_errors = schema.validate(data).to_a
+
+            if validation_errors.any?
+              errors << {
+                window: window_var,
+                template: template_name,
+                errors: format_errors(validation_errors)
+              }
+            end
+          rescue StandardError => e
+            warn "Rhales::SchemaValidator: Schema validation error for #{template_name}: #{e.message}"
+            # Don't add to errors array - this is a schema definition problem, not data problem
+          end
+        end
+
+        errors
+      end
+
+      # Format json_schemer errors for display
+      def format_errors(validation_errors)
+        validation_errors.map do |error|
+          # json_schemer provides detailed error hash
+          # Example: { "data" => value, "data_pointer" => "/user/id", "schema" => {...}, "type" => "required", "error" => "..." }
+
+          path = error['data_pointer'] || '/'
+          type = error['type']
+          schema = error['schema'] || {}
+          data = error['data']
+
+          # For type validation errors, format like json-schema did
+          # "The property '#/count' of type string did not match the following type: number"
+          if schema['type'] && data
+            expected = schema['type']
+            actual = case data
+                     when String then 'string'
+                     when Integer, Float then 'number'
+                     when TrueClass, FalseClass then 'boolean'
+                     when Array then 'array'
+                     when Hash then 'object'
+                     when NilClass then 'null'
+                     else data.class.name.downcase
+                     end
+
+            "The property '#{path}' of type #{actual} did not match the following type: #{expected}"
+          elsif type == 'required'
+            details = error['details'] || {}
+            missing = details['missing_keys']&.join(', ') || 'unknown'
+            "The property '#{path}' is missing required field(s): #{missing}"
+          elsif schema['enum']
+            expected = schema['enum'].join(', ')
+            "The property '#{path}' must be one of: #{expected}"
+          elsif schema['minimum']
+            min = schema['minimum']
+            "The property '#{path}' must be >= #{min}"
+          elsif schema['maximum']
+            max = schema['maximum']
+            "The property '#{path}' must be <= #{max}"
+          elsif type == 'additionalProperties'
+            "The property '#{path}' is not defined in the schema and the schema does not allow additional properties"
+          else
+            # Fallback: use json_schemer's built-in error message
+            error['error'] || "The property '#{path}' failed '#{type}' validation"
+          end
+        end
+      end
+
+      # Handle validation errors
+      def handle_errors(errors, template_name, template_path, elapsed_ms)
+        error_message = build_error_message(errors, template_name, template_path, elapsed_ms)
+
+        if @fail_on_error
+          # Development: Fail loudly
+          raise ValidationError, error_message
+        else
+          # Production: Log warning
+          warn error_message
+        end
+      end
+
+      # Build detailed error message
+      def build_error_message(errors, template_name, template_path, elapsed_ms)
+        msg = ["Schema validation failed for template: #{template_name}"]
+        msg << "Template path: #{template_path}" if template_path
+        msg << "Validation time: #{elapsed_ms}ms"
+        msg << ""
+
+        errors.each do |error|
+          msg << "Window variable: #{error[:window]}"
+          msg << "Errors:"
+          error[:errors].each do |err|
+            msg << "  - #{err}"
+          end
+          msg << ""
+        end
+
+        msg << "This means your backend is sending data that doesn't match the contract"
+        msg << "defined in the <schema> section of #{template_name}.rue"
+        msg << ""
+        msg << "To fix:"
+        msg << "1. Check the schema definition in #{template_name}.rue"
+        msg << "2. Verify the data passed to render('#{template_name}', ...)"
+        msg << "3. Ensure types match (string vs number, required fields, etc.)"
+
+        msg.join("\n")
+      end
+    end
+  end
+end

data/lib/rhales/middleware.rb

@@ -0,0 +1,6 @@
+# lib/rhales/middleware.rb
+#
+# frozen_string_literal: true
+
+require_relative 'middleware/json_responder'
+require_relative 'middleware/schema_validator'