rhales 0.4.0 → 0.5.3

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

@@ -1,5 +1,9 @@
-require 'json'
+# 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
@@ -48,7 +52,7 @@ module Rhales
       merged_data = process_template_data(template_name, additional_context)
 
       {
-        content: JSON.generate(merged_data),
+        content: JSONSerializer.dump(merged_data),
         content_type: 'application/json',
         headers: json_headers(merged_data)
       }
@@ -63,7 +67,7 @@ module Rhales
       }
 
       {
-        content: JSON.generate(error_data),
+        content: JSONSerializer.dump(error_data),
         content_type: 'application/json',
         headers: json_headers(error_data)
       }
@@ -78,7 +82,7 @@ module Rhales
       }
 
       {
-        content: JSON.generate(error_data),
+        content: JSONSerializer.dump(error_data),
         content_type: 'application/json',
         headers: json_headers(error_data)
       }
@@ -89,7 +93,7 @@ module Rhales
       merged_data = process_template_data(template_name, additional_context)
 
       {
-        content: "export default #{JSON.generate(merged_data)};",
+        content: "export default #{JSONSerializer.dump(merged_data)};",
         content_type: 'text/javascript',
         headers: module_headers(merged_data)
       }
@@ -100,7 +104,7 @@ module Rhales
       merged_data = process_template_data(template_name, additional_context)
 
       {
-        content: "#{callback_name}(#{JSON.generate(merged_data)});",
+        content: "#{callback_name}(#{JSONSerializer.dump(merged_data)});",
         content_type: 'application/javascript',
         headers: jsonp_headers(merged_data),
       }
@@ -116,7 +120,7 @@ module Rhales
     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))
+      Digest::MD5.hexdigest(JSONSerializer.dump(merged_data))
     end
 
     private
@@ -126,7 +130,7 @@ module Rhales
       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: {})
+      view = View.new(@context.req, client: {})
       aggregator = HydrationDataAggregator.new(template_context)
 
       # Build composition to get template dependencies
@@ -149,11 +153,11 @@ module Rhales
     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)
+        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(props: additional_context)
+        Context.minimal(client: additional_context)
       end
     end
 
@@ -170,7 +174,7 @@ module Rhales
       end
 
       # Add ETag for caching
-      headers['ETag'] = %("#{Digest::MD5.hexdigest(JSON.generate(data))}")
+      headers['ETag'] = %("#{Digest::MD5.hexdigest(JSONSerializer.dump(data))}")
 
       headers
     end

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

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

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/{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

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