rhales 0.3.0 → 0.5.3

data/lib/rhales/core/view.rb

@@ -0,0 +1,529 @@
+# lib/rhales/view.rb
+#
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'forwardable'
+require_relative 'context'
+require_relative 'rue_document'
+require_relative 'template_engine'
+require_relative '../hydration/hydrator'
+require_relative 'view_composition'
+require_relative '../hydration/hydration_data_aggregator'
+require_relative '../security/csp'
+require_relative '../utils/json_serializer'
+require_relative '../integrations/refinements/require_refinements'
+
+using Rhales::Ruequire
+
+module Rhales
+  # Complete RSFC view implementation
+  #
+  # Single public interface for RSFC template rendering that handles:
+  # - Context creation (with pluggable context classes)
+  # - Template loading and parsing
+  # - Template rendering with Rhales
+  # - Data hydration and injection
+  #
+  # ## Context and Data Boundaries
+  #
+  # Views implement a two-phase security model:
+  #
+  # ### Server Templates: Full Context Access
+  # Templates have complete access to all server-side data:
+  # - All client data passed to View.new
+  # - All server data passed to View.new
+
+  # - Runtime data (CSRF tokens, nonces, request metadata)
+  # - Computed data (authentication status, theme classes)
+  # - User objects, configuration, internal APIs
+  #
+  # ### Client Data: Explicit Allowlist
+  # Only client data declared in <schema> sections reaches the browser:
+  # - Creates a REST API-like boundary
+  # - Server-side variable interpolation processes secrets safely
+  # - JSON serialization validates data structure
+  # - No accidental exposure of sensitive server data
+  #
+  # Example:
+  #   # Server template has full access:
+  #   {{user.admin?}} {{csrf_token}} {{internal_config}}
+  #
+  #   # Client only gets declared data from schema:
+  #   <schema lang="js-zod" window="data">
+  #   const schema = z.object({ userName: z.string() });
+  #   </schema>
+  #
+  # See docs/CONTEXT_AND_DATA_BOUNDARIES.md for complete details.
+  #
+  # Subclasses can override context_class to use different context implementations.
+  class View
+    extend Forwardable
+    include Rhales::Utils::LoggingHelpers
+
+    class RenderError < StandardError; end
+    class TemplateNotFoundError < RenderError; end
+
+    attr_reader :req, :rsfc_context
+
+    # Delegate context accessors to rsfc_context
+    def_delegators :@rsfc_context, :sess, :user, :client, :server, :config, :locale
+
+    def initialize(req, client: {}, server: {}, config: nil)
+      @req = req
+      @rsfc_context = context_class.for_view(req, client: client, server: server, config: config || Rhales.configuration)
+    end
+
+    # Render RSFC template with hydration using two-pass architecture
+    def render(template_name = nil)
+      start_time = now_in_μs
+      template_name ||= self.class.default_template_name
+
+      # Store template name in request env for middleware validation
+      @req.env['rhales.template_name'] = template_name if @req && @req.respond_to?(:env)
+
+      begin
+        # Phase 1: Build view composition and aggregate data
+        composition           = build_view_composition(template_name)
+        aggregator            = HydrationDataAggregator.new(@rsfc_context)
+        merged_hydration_data = aggregator.aggregate(composition)
+
+        # Phase 2: Render HTML with pre-computed data
+        # Render template content
+        template_html = render_template_with_composition(composition, template_name)
+
+        # Generate hydration HTML with merged data
+        hydration_html = generate_hydration_from_merged_data(merged_hydration_data)
+
+        # Set CSP header if enabled
+        set_csp_header_if_enabled
+
+        # Smart hydration injection with mount point detection
+        result = inject_hydration_with_mount_points(composition, template_name, template_html, hydration_html)
+
+        # Log successful render
+        duration = now_in_μs - start_time
+        hydration_size = merged_hydration_data.to_json.bytesize if merged_hydration_data
+
+        log_with_metadata(Rhales.logger, :debug, 'View rendered',
+          template: template_name,
+          layout: composition.layout,
+          partials: composition.dependencies.values.flatten.uniq,
+          duration: duration,
+          hydration_size_bytes: hydration_size
+        )
+
+        result
+      rescue StandardError => ex
+        duration = now_in_μs - start_time
+
+        log_with_metadata(Rhales.logger, :error, 'View render failed',
+          template: template_name,
+          duration: duration,
+          error: ex.message,
+          error_class: ex.class.name
+        )
+
+        raise RenderError, "Failed to render template '#{template_name}': #{ex.message}"
+      end
+    end
+
+    # Render only the template section (without data hydration)
+    def render_template_only(template_name = nil)
+      template_name ||= self.class.default_template_name
+
+      # Build composition for consistent behavior
+      composition = build_view_composition(template_name)
+      render_template_with_composition(composition, template_name)
+    end
+
+    # Render JSON response for API endpoints (link-based strategies)
+    def render_json_only(template_name = nil, additional_context = {})
+      require_relative '../hydration/hydration_endpoint'
+
+      template_name ||= self.class.default_template_name
+      endpoint = HydrationEndpoint.new(config, @rsfc_context)
+      endpoint.render_json(template_name, additional_context)
+    end
+
+    # Render ES module response for modulepreload strategy
+    def render_module_only(template_name = nil, additional_context = {})
+      require_relative '../hydration/hydration_endpoint'
+
+      template_name ||= self.class.default_template_name
+      endpoint = HydrationEndpoint.new(config, @rsfc_context)
+      endpoint.render_module(template_name, additional_context)
+    end
+
+    # Render JSONP response with callback
+    def render_jsonp_only(template_name = nil, callback_name = 'callback', additional_context = {})
+      require_relative '../hydration/hydration_endpoint'
+
+      template_name ||= self.class.default_template_name
+      endpoint = HydrationEndpoint.new(config, @rsfc_context)
+      endpoint.render_jsonp(template_name, callback_name, additional_context)
+    end
+
+    # Check if template data has changed for caching
+    def data_changed?(template_name = nil, etag = nil, additional_context = {})
+      require_relative '../hydration/hydration_endpoint'
+
+      template_name ||= self.class.default_template_name
+      endpoint = HydrationEndpoint.new(config, @rsfc_context)
+      endpoint.data_changed?(template_name, etag, additional_context)
+    end
+
+    # Calculate ETag for current template data
+    def calculate_etag(template_name = nil, additional_context = {})
+      require_relative '../hydration/hydration_endpoint'
+
+      template_name ||= self.class.default_template_name
+      endpoint = HydrationEndpoint.new(config, @rsfc_context)
+      endpoint.calculate_etag(template_name, additional_context)
+    end
+
+    # Generate only the data hydration HTML
+    def render_hydration_only(template_name = nil)
+      template_name ||= self.class.default_template_name
+
+      # Build composition and aggregate data
+      composition           = build_view_composition(template_name)
+      aggregator            = HydrationDataAggregator.new(@rsfc_context)
+      merged_hydration_data = aggregator.aggregate(composition)
+
+      # Generate hydration HTML
+      generate_hydration_from_merged_data(merged_hydration_data)
+    end
+
+    # Get processed data as hash (for API endpoints or testing)
+    def data_hash(template_name = nil)
+      template_name ||= self.class.default_template_name
+
+      # Build composition and aggregate data
+      composition = build_view_composition(template_name)
+      aggregator  = HydrationDataAggregator.new(@rsfc_context)
+      aggregator.aggregate(composition)
+    end
+
+    protected
+
+    # Return the context class to use
+    # Subclasses can override this to use different context implementations
+    def context_class
+      Context
+    end
+
+    private
+
+    # Load and parse template
+    def load_template(template_name)
+      template_path = resolve_template_path(template_name)
+
+      unless File.exist?(template_path)
+        raise TemplateNotFoundError, "Template not found: #{template_path}"
+      end
+
+      # Use refinement to load .rue file
+      require template_path
+    end
+
+    # Resolve template path
+    def resolve_template_path(template_name)
+      # Check configured template paths first
+      if config && config.template_paths && !config.template_paths.empty?
+        config.template_paths.each do |path|
+          template_path = File.join(path, "#{template_name}.rue")
+          return template_path if File.exist?(template_path)
+        end
+      end
+
+      # Fallback to default template structure
+      # First try templates/web directory
+      web_path = File.join(templates_root, 'web', "#{template_name}.rue")
+      return web_path if File.exist?(web_path)
+
+      # Then try templates directory
+      templates_path = File.join(templates_root, "#{template_name}.rue")
+      return templates_path if File.exist?(templates_path)
+
+      # Return first configured path or web path for error message
+      if config && config.template_paths && !config.template_paths.empty?
+        File.join(config.template_paths.first, "#{template_name}.rue")
+      else
+        web_path
+      end
+    end
+
+    # Get templates root directory
+    def templates_root
+      boot_root = File.expand_path('../../..', __dir__)
+      File.join(boot_root, 'templates')
+    end
+
+    # Render template section with Rhales
+    #
+    # RSFC Security Model: Templates have full server context access
+    # - Templates can access all business data, user objects, methods, etc.
+    # - This is like any server-side template (ERB, HAML, etc.)
+    # - Security boundary is at server-to-client handoff, not within server rendering
+    # - Only data declared in <schema> section reaches the client (after validation)
+    def render_template_section(parser)
+      template_content = parser.section('template')
+      return '' unless template_content
+
+      # Create partial resolver
+      partial_resolver = create_partial_resolver
+
+      # Render with full server context
+      TemplateEngine.render(template_content, @rsfc_context, partial_resolver: partial_resolver)
+    end
+
+    # Create partial resolver for {{> partial}} inclusions
+    def create_partial_resolver
+      templates_dir = File.join(templates_root, 'web')
+
+      proc do |partial_name|
+        partial_path = File.join(templates_dir, "#{partial_name}.rue")
+
+        if File.exist?(partial_path)
+          # Return full partial content so TemplateEngine can process
+          # data sections, otherwise nil.
+          File.read(partial_path)
+        end
+      end
+    end
+
+    # Smart hydration injection with mount point detection on rendered HTML
+    def inject_hydration_with_mount_points(composition, template_name, template_html, hydration_html)
+      injector = HydrationInjector.new(config.hydration, template_name)
+
+      # Check if using link-based strategy
+      if config.hydration.link_based_strategy?
+        # For link-based strategies, we need the merged data context
+        aggregator = HydrationDataAggregator.new(@rsfc_context)
+        merged_data = aggregator.aggregate(composition)
+        nonce = @rsfc_context.get('nonce')
+
+        injector.inject_link_based_strategy(template_html, merged_data, nonce)
+      else
+        # Traditional strategies (early, earliest, late)
+        mount_point = detect_mount_point_in_rendered_html(template_html)
+        injector.inject(template_html, hydration_html, mount_point)
+      end
+    end
+
+    # Detect mount points in fully rendered HTML
+    def detect_mount_point_in_rendered_html(template_html)
+      return nil unless config&.hydration
+
+      custom_selectors = config.hydration.mount_point_selectors || []
+      detector = MountPointDetector.new
+      detector.detect(template_html, custom_selectors)
+    end
+
+    # Build view composition for the given template
+    def build_view_composition(template_name)
+      loader      = method(:load_template_for_composition)
+      composition = ViewComposition.new(template_name, loader: loader, config: config)
+      composition.resolve!
+    end
+
+    # Loader proc for ViewComposition
+    def load_template_for_composition(template_name)
+      template_path = resolve_template_path(template_name)
+      return nil unless File.exist?(template_path)
+
+      require template_path
+    rescue StandardError => ex
+      raise TemplateNotFoundError, "Failed to load template #{template_name}: #{ex.message}"
+    end
+
+    # Render template using the view composition
+    def render_template_with_composition(composition, root_template_name)
+      root_parser      = composition.template(root_template_name)
+      template_content = root_parser.section('template')
+      return '' unless template_content
+
+      # Create partial resolver that uses the composition
+      partial_resolver = create_partial_resolver_from_composition(composition)
+
+      # Use existing context for rendering
+      context_with_rue_data = @rsfc_context
+
+      # Check if template has a layout
+      if root_parser.layout && composition.template(root_parser.layout)
+        # Render content template first
+        content_html = TemplateEngine.render(template_content, context_with_rue_data, partial_resolver: partial_resolver)
+
+        # Then render layout with content
+        layout_parser  = composition.template(root_parser.layout)
+        layout_content = layout_parser.section('template')
+        return '' unless layout_content
+
+        # Use builder pattern to create new context with content for layout rendering
+        layout_context = context_with_rue_data.merge_client('content' => content_html)
+
+        TemplateEngine.render(layout_content, layout_context, partial_resolver: partial_resolver)
+      else
+        # Render with full server context (no layout)
+        TemplateEngine.render(template_content, context_with_rue_data, partial_resolver: partial_resolver)
+      end
+    end
+
+    # Create partial resolver that uses pre-loaded templates from composition
+    def create_partial_resolver_from_composition(composition)
+      proc do |partial_name|
+        parser = composition.template(partial_name)
+        parser ? parser.content : nil
+      end
+    end
+
+    # Generate hydration HTML from pre-merged data
+    def generate_hydration_from_merged_data(merged_data)
+      hydration_parts = []
+
+      merged_data.each do |window_attr, data|
+        # Generate unique ID for this data block
+        unique_id = "rsfc-data-#{SecureRandom.hex(8)}"
+        nonce_attr = nonce_attribute
+
+        # Create JSON script tag with optional reflection attributes
+        json_attrs = reflection_enabled? ? " data-window=\"#{window_attr}\"" : ''
+        json_script = <<~HTML.strip
+          <script#{nonce_attr} id="#{unique_id}" type="application/json"#{json_attrs}>#{JSONSerializer.dump(data)}</script>
+        HTML
+
+        # Create hydration script with optional reflection attributes
+        hydration_attrs = reflection_enabled? ? " data-hydration-target=\"#{window_attr}\"" : ''
+        hydration_script = if reflection_enabled?
+          <<~HTML.strip
+            <script#{nonce_attr}#{hydration_attrs}>
+            var dataScript = document.getElementById('#{unique_id}');
+            var targetName = dataScript.getAttribute('data-window') || '#{window_attr}';
+            window[targetName] = JSON.parse(dataScript.textContent);
+            </script>
+          HTML
+        else
+          <<~HTML.strip
+            <script#{nonce_attr}#{hydration_attrs}>
+            window['#{window_attr}'] = JSON.parse(document.getElementById('#{unique_id}').textContent);
+            </script>
+          HTML
+        end
+
+        hydration_parts << json_script
+        hydration_parts << hydration_script
+      end
+
+      # Add reflection utilities if enabled
+      if reflection_enabled? && !merged_data.empty?
+        hydration_parts << generate_reflection_utilities
+      end
+
+      return '' if hydration_parts.empty?
+
+      hydration_content = hydration_parts.join("\n")
+      "\n\n<!-- Rhales Hydration Start -->\n#{hydration_content}\n<!-- Rhales Hydration End -->"
+    end
+
+    # Check if reflection system is enabled
+    def reflection_enabled?
+      config.hydration.reflection_enabled
+    end
+
+    # Generate JavaScript utilities for hydration reflection
+    def generate_reflection_utilities
+      nonce_attr = nonce_attribute
+
+      <<~HTML.strip
+        <script#{nonce_attr}>
+        // Rhales hydration reflection utilities
+        window.__rhales__ = window.__rhales__ || {
+          getHydrationTargets: function() {
+            return Array.from(document.querySelectorAll('[data-hydration-target]'));
+          },
+          getDataForTarget: function(target) {
+            var targetName = target.dataset.hydrationTarget;
+            return targetName ? window[targetName] : undefined;
+          },
+          getWindowAttribute: function(scriptEl) {
+            return scriptEl.dataset.window;
+          },
+          getDataScripts: function() {
+            return Array.from(document.querySelectorAll('script[data-window]'));
+          },
+          refreshData: function(target) {
+            var targetName = target.dataset.hydrationTarget;
+            var dataScript = document.querySelector('script[data-window="' + targetName + '"]');
+            if (dataScript && targetName) {
+              try {
+                window[targetName] = JSON.parse(dataScript.textContent);
+                return true;
+              } catch (e) {
+                console.error('Rhales: Failed to refresh data for ' + targetName, e);
+                return false;
+              }
+            }
+            return false;
+          },
+          getAllHydrationData: function() {
+            var data = {};
+            this.getHydrationTargets().forEach(function(target) {
+              var targetName = target.dataset.hydrationTarget;
+              if (targetName) {
+                data[targetName] = window[targetName];
+              }
+            });
+            return data;
+          }
+        };
+        </script>
+      HTML
+    end
+
+    # Get nonce attribute if available
+    def nonce_attribute
+      nonce = @rsfc_context.get('nonce')
+      nonce ? " nonce=\"#{ERB::Util.html_escape(nonce)}\"" : ''
+    end
+
+    # Set CSP header if enabled
+    def set_csp_header_if_enabled
+      return unless config.csp_enabled
+      return unless @req && @req.respond_to?(:env)
+
+      # Get nonce from context
+      nonce = @rsfc_context.get('nonce')
+
+      # Create CSP instance and build header
+      csp = CSP.new(config, nonce: nonce)
+      header_value = csp.build_header
+
+      # Set header in request environment for framework to use
+      @req.env['csp_header'] = header_value if header_value
+    end
+
+    class << self
+      # Get default template name based on class name
+      def default_template_name
+        # Convert ClassName to class_name
+        name.split('::').last
+          .gsub(/([A-Z])/, '_\1')
+          .downcase
+          .sub(/^_/, '')
+          .sub(/_view$/, '')
+      end
+
+      # Render template with client data
+      def render_with_data(req, template_name: nil, config: nil, **client_data)
+        view = new(req, client: client_data, config: config)
+        view.render(template_name)
+      end
+
+      # Create view instance with client data
+      def with_data(req, config: nil, **client_data)
+        new(req, client: client_data, config: config)
+      end
+    end
+  end
+end

data/lib/rhales/{view_composition.rb → core/view_composition.rb}

@@ -1,7 +1,9 @@
 # lib/rhales/view_composition.rb
+#
+# frozen_string_literal: true
 
 require_relative 'rue_document'
-require_relative 'refinements/require_refinements'
+require_relative '../integrations/refinements/require_refinements'
 
 using Rhales::Ruequire
 
@@ -23,14 +25,17 @@ module Rhales
   # - Immutable: Once created, the composition is read-only
   # - Cacheable: Can be cached in production for performance
   class ViewComposition
+    include Rhales::Utils::LoggingHelpers
+
     class TemplateNotFoundError < StandardError; end
     class CircularDependencyError < StandardError; end
 
     attr_reader :root_template_name, :templates, :dependencies
 
-    def initialize(root_template_name, loader:)
+    def initialize(root_template_name, loader:, config: nil)
       @root_template_name = root_template_name
       @loader             = loader
+      @config             = config
       @templates          = {}
       @dependencies       = {}
       @loading            = Set.new
@@ -38,9 +43,23 @@ module Rhales
 
     # Resolve all template dependencies
     def resolve!
-      load_template_recursive(@root_template_name)
-      freeze_composition
-      self
+      log_timed_operation(Rhales.logger, :debug, 'Template dependency resolution',
+        root_template: @root_template_name
+      ) do
+        load_template_recursive(@root_template_name)
+        freeze_composition
+
+        # Log resolution results
+        log_with_metadata(Rhales.logger, :debug, 'Template composition resolved',
+          root_template: @root_template_name,
+          total_templates: @templates.size,
+          total_dependencies: @dependencies.values.sum(&:size),
+          partials: @dependencies.values.flatten.uniq,
+          layout: layout
+        )
+
+        self
+      end
     end
 
     # Iterate through all documents in render order
@@ -69,7 +88,7 @@ module Rhales
     end
 
     # Check if a template exists in the composition
-    def has_template?(name)
+    def template?(name)
       @templates.key?(name)
     end
 
@@ -83,24 +102,50 @@ module Rhales
       @dependencies[template_name] || []
     end
 
+    # Get the layout for the root template (if any)
+    def layout
+      root_template = @templates[@root_template_name]
+      return nil unless root_template
+
+      root_template.layout
+    end
+
     private
 
     def load_template_recursive(template_name, parent_path = nil)
+      depth = @loading.size
+
       # Check for circular dependencies
       if @loading.include?(template_name)
+        log_with_metadata(Rhales.logger, :error, 'Circular dependency detected',
+          template: template_name,
+          dependency_chain: @loading.to_a,
+          depth: depth
+        )
         raise CircularDependencyError, "Circular dependency detected: #{template_name} -> #{@loading.to_a.join(' -> ')}"
       end
 
-      # Skip if already loaded
-      return if @templates.key?(template_name)
+      # Skip if already loaded (cache hit)
+      if @templates.key?(template_name)
+        Rhales.logger.debug("Template cache hit: template=#{template_name}")
+        return
+      end
 
       @loading.add(template_name)
 
       begin
         # Load template using the provided loader
+        start_time = now_in_μs
         parser = @loader.call(template_name)
+        load_duration = now_in_μs - start_time
 
         unless parser
+          log_with_metadata(Rhales.logger, :error, 'Template not found',
+            template: template_name,
+            parent: parent_path,
+            depth: depth,
+            search_duration: load_duration
+          )
           raise TemplateNotFoundError, "Template not found: #{template_name}"
         end
 
@@ -109,15 +154,42 @@ module Rhales
         @dependencies[template_name] = []
 
         # Extract and load partials
-        extract_partials(parser).each do |partial_name|
+        partials = extract_partials(parser)
+
+        if partials.any?
+          log_with_metadata(Rhales.logger, :debug, 'Resolved partial',
+            template: template_name,
+            partials_found: partials,
+            partial_count: partials.size,
+            depth: depth,
+            load_duration: load_duration
+          )
+        end
+
+        partials.each do |partial_name|
           @dependencies[template_name] << partial_name
           load_template_recursive(partial_name, template_name)
         end
 
         # Load layout if specified and not already loaded
         if parser.layout && !@templates.key?(parser.layout)
+          log_with_metadata(Rhales.logger, :debug, 'Layout resolution',
+            template: template_name,
+            layout: parser.layout,
+            depth: depth
+          )
           load_template_recursive(parser.layout, template_name)
         end
+
+        # Log successful template load
+        log_with_metadata(Rhales.logger, :debug, 'Template loaded',
+          template: template_name,
+          parent: parent_path,
+          depth: depth,
+          has_partials: partials.any?,
+          has_layout: !parser.layout.nil?,
+          load_duration: load_duration
+        )
       ensure
         @loading.delete(template_name)
       end

data/lib/rhales/core.rb

@@ -0,0 +1,9 @@
+# lib/rhales/core.rb
+#
+# frozen_string_literal: true
+
+require_relative 'core/context'
+require_relative 'core/rue_document'
+require_relative 'core/template_engine'
+require_relative 'core/view_composition'
+require_relative 'core/view'