rhales 0.3.0

data/lib/rhales/tilt.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require 'tilt'
+require 'rhales'
+require_relative 'adapters/base_request'
+
+module Rhales
+  # Tilt integration for Rhales templates
+  #
+  # This allows Rhales to be used with any framework that supports Tilt,
+  # including Roda's render plugin, Sinatra, and others.
+  #
+  # Usage in Roda:
+  #   require 'rhales/tilt'
+  #   plugin :render, engine: 'rhales'
+  #
+  # Usage in Sinatra:
+  #   require 'rhales/tilt'
+  #   set :template_engine, :rhales
+  #
+  class TiltTemplate < Tilt::Template
+    self.default_mime_type = 'text/html'
+
+    # Parse template during initialization
+    def prepare
+      # Store the template content - parsing happens during render
+      @template_content = data
+    end
+
+    # Render the template with given scope and locals
+    #
+    # @param scope [Object] The scope object (usually the Roda/Sinatra app instance)
+    # @param locals [Hash] Local variables for the template
+    # @param block [Proc] Optional block content
+    # @return [String] Rendered HTML
+    def evaluate(scope, locals = {}, &)
+      # Build template props from locals and scope
+      props = build_props(scope, locals, &)
+
+      # Create Rhales context adapters from scope
+      rhales_context = build_rhales_context(scope, props)
+
+      # Get template name from file path
+      template_name = derive_template_name
+
+      # Render the template
+      rhales_context.render(template_name)
+    end
+
+    private
+
+    # Get shared nonce from scope if available, otherwise generate one
+    def get_shared_nonce(scope)
+      # Try to get nonce from scope's CSP nonce or instance variable
+      if scope.respond_to?(:csp_nonce) && scope.csp_nonce
+        scope.csp_nonce
+      elsif scope.respond_to?(:request) && scope.request.env['csp.nonce']
+        scope.request.env['csp.nonce']
+      elsif scope.instance_variable_defined?(:@csp_nonce)
+        scope.instance_variable_get(:@csp_nonce)
+      else
+        # Generate a new nonce and store it for consistency
+        nonce = SecureRandom.hex(16)
+        scope.instance_variable_set(:@csp_nonce, nonce) if scope.respond_to?(:instance_variable_set)
+        nonce
+      end
+    end
+
+    # Build props hash from locals and scope context
+    def build_props(scope, locals, &block)
+      props = locals.dup
+
+      # Add block content if provided
+      props['content'] = yield if block
+
+      # Add scope-specific data
+      if scope.respond_to?(:request)
+        props['current_path']   = scope.request.path
+        props['request_method'] = scope.request.request_method
+      end
+
+      # Add flash messages if available
+      if scope.respond_to?(:flash)
+        props['flash_notice'] = scope.flash['notice']
+        props['flash_error']  = scope.flash['error']
+      end
+
+      # Add rodauth object if available
+      if scope.respond_to?(:rodauth)
+        props['rodauth'] = scope.rodauth
+      end
+
+      # Add authentication status
+      if scope.respond_to?(:logged_in?)
+        props['authenticated'] = scope.logged_in?
+      end
+
+      props
+    end
+
+    # Build Rhales context objects from scope
+    def build_rhales_context(scope, props)
+      # Get shared nonce from scope if available, otherwise generate one
+      shared_nonce = get_shared_nonce(scope)
+
+      # Use proper request adapter
+      request_data = if scope.respond_to?(:request)
+        # Add CSP nonce to framework request env
+        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
+          def initialize(original, custom_env)
+            @original = original
+            @custom_env = custom_env
+          end
+
+          def method_missing(method, *args, &block)
+            @original.send(method, *args, &block)
+          end
+
+          def respond_to_missing?(method, include_private = false)
+            @original.respond_to?(method, include_private)
+          end
+
+          def env
+            @custom_env
+          end
+        end.new(scope.request, framework_env)
+
+        Rhales::Adapters::FrameworkRequest.new(wrapped_request)
+      else
+        Rhales::Adapters::SimpleRequest.new(
+          path: '/',
+          method: 'GET',
+          ip: '127.0.0.1',
+          params: {},
+          env: {
+            'nonce' => shared_nonce,
+            'request_id' => SecureRandom.hex(8),
+          }
+        )
+      end
+
+      # Use proper session adapter
+      session_data = if scope.respond_to?(:logged_in?) && scope.logged_in?
+        Rhales::Adapters::AuthenticatedSession.new(
+          {
+            id: SecureRandom.hex(8),
+            created_at: Time.now,
+          },
+        )
+      else
+        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({
+          id: user[:id],
+          email: user[:email],
+          authenticated: true,
+        },
+                                                           )
+      else
+        auth_data = Rhales::Adapters::AnonymousAuth.new
+      end
+
+      ::Rhales::View.new(
+        request_data,
+        session_data,
+        auth_data,
+        nil, # locale_override
+        props: props,
+      )
+    end
+
+    # Derive template name from file path
+    def derive_template_name
+      return @template_name if @template_name
+
+      if file
+        # Remove extension and get relative path from template directory
+        template_path = File.basename(file, '.*')
+
+        # Check if this is in a subdirectory (relative to configured paths)
+        if ::Rhales.configuration.template_paths
+          ::Rhales.configuration.template_paths.each do |path|
+            next unless file.start_with?(path)
+
+            relative_path = file.sub(path + '/', '')
+            template_path = if File.dirname(relative_path) == '.'
+            File.basename(relative_path, '.*')
+          else
+            File.join(File.dirname(relative_path), File.basename(relative_path, '.*'))
+          end
+            break
+          end
+        end
+
+        @template_name = template_path
+      else
+        @template_name = 'unknown'
+      end
+    end
+  end
+end
+
+# Register the template with Tilt
+Tilt.register Rhales::TiltTemplate, 'rue'

data/lib/rhales/version.rb

@@ -0,0 +1,6 @@
+# lib/rhales/version.rb
+
+module Rhales
+  # Version information for the RSFC gem
+  VERSION = '0.3.0'
+end

data/lib/rhales/view.rb

@@ -0,0 +1,412 @@
+# lib/rhales/view.rb
+
+require 'securerandom'
+require_relative 'context'
+require_relative 'rue_document'
+require_relative 'template_engine'
+require_relative 'hydrator'
+require_relative 'view_composition'
+require_relative 'hydration_data_aggregator'
+require_relative 'csp'
+require_relative '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 props passed to View.new
+  # - Data from .rue file's <data> section (processed server-side)
+  # - Runtime data (CSRF tokens, nonces, request metadata)
+  # - Computed data (authentication status, theme classes)
+  # - User objects, configuration, internal APIs
+  #
+  # ### Client Data: Explicit Allowlist
+  # Only data declared in <data> sections reahas_role?ches 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:
+  #   { "user_name": "{{user.name}}", "theme": "{{user.theme}}" }
+  #
+  # See docs/CONTEXT_AND_DATA_BOUNDARIES.md for complete details.
+  #
+  # Subclasses can override context_class to use different context implementations.
+  class View
+    class RenderError < StandardError; end
+    class TemplateNotFoundError < RenderError; end
+
+    attr_reader :req, :sess, :cust, :locale, :rsfc_context, :props, :config
+
+    def initialize(req, sess = nil, cust = nil, locale_override = nil, props: {}, config: nil)
+      @req           = req
+      @sess          = sess
+      @cust          = cust
+      @locale        = locale_override
+      @props         = props
+      @config        = config || Rhales.configuration
+
+      # Create context using the specified context class
+      @rsfc_context = create_context
+    end
+
+    # Render RSFC template with hydration using two-pass architecture
+    def render(template_name = nil)
+      template_name ||= self.class.default_template_name
+
+      # 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
+
+      # Combine template and hydration
+      inject_hydration_into_template(template_html, hydration_html)
+    rescue StandardError => ex
+      raise RenderError, "Failed to render template '#{template_name}': #{ex.message}"
+    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
+
+    # 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
+
+    # Create the appropriate context for this view
+    # Subclasses can override this to use different context types
+    def create_context
+      context_class.for_view(@req, @sess, @cust, @locale, config: @config, **@props)
+    end
+
+    # 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 = if defined?(OT) && OT.respond_to?(:boot_root)
+                    OT.boot_root
+                  else
+                    File.expand_path('../../..', __dir__)
+                  end
+      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.
+    # - Templates can access data from .rue file's <data> section (processed server-side)
+    # - 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 <data> section reaches the client (after processing)
+    def render_template_section(parser)
+      template_content = parser.section('template')
+      return '' unless template_content
+
+      # Create partial resolver
+      partial_resolver = create_partial_resolver
+
+      # Merge .rue file data with existing context
+      context_with_rue_data = create_context_with_rue_data(parser)
+
+      # Render with full server context (props + computed context + rue data)
+      TemplateEngine.render(template_content, context_with_rue_data, 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)
+          # Parse partial and return template section
+          partial_parser = require(partial_path)
+          partial_parser.section('template')
+        else
+          nil
+        end
+      end
+    end
+
+    # Generate data hydration HTML
+    def generate_hydration(parser)
+      Hydrator.generate(parser, @rsfc_context)
+    end
+
+    # Create context that includes data from .rue file's data section
+    def create_context_with_rue_data(parser)
+      # Get data from .rue file's data section
+      rue_data = extract_rue_data(parser)
+
+      # Merge rue data with existing props (rue data takes precedence)
+      merged_props = @props.merge(rue_data)
+
+      # Create new context with merged data
+      context_class.for_view(@req, @sess, @cust, @locale, config: @config, **merged_props)
+    end
+
+    # Extract and process data from .rue file's data section
+    def extract_rue_data(parser)
+      data_content = parser.section('data')
+      return {} unless data_content
+
+      # Process the data section as JSON and parse it
+      hydrator = Hydrator.new(parser, @rsfc_context)
+      hydrator.processed_data_hash
+    rescue JSON::ParserError, Hydrator::JSONSerializationError => ex
+      # If data section isn't valid JSON, return empty hash
+      # This allows templates to work even with malformed data sections
+      {}
+    end
+
+    # Inject hydration HTML into template
+    def inject_hydration_into_template(template_html, hydration_html)
+      # Try to inject before closing </body> tag
+      if template_html.include?('</body>')
+        template_html.sub('</body>', "#{hydration_html}\n</body>")
+      # Otherwise append to end
+      else
+        "#{template_html}\n#{hydration_html}"
+      end
+    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)
+      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)
+
+      # Merge .rue file data with existing context
+      context_with_rue_data = create_context_with_rue_data(root_parser)
+
+      # 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
+
+        # Create new context with content for layout rendering
+        layout_props   = context_with_rue_data.props.merge('content' => content_html)
+        layout_context = Context.new(
+          context_with_rue_data.req,
+          context_with_rue_data.sess,
+          context_with_rue_data.cust,
+          context_with_rue_data.locale,
+          props: layout_props,
+          config: context_with_rue_data.config,
+        )
+
+        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.section('template') : 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)}"
+
+        # Create JSON script tag
+        json_script = <<~HTML.strip
+          <script id="#{unique_id}" type="application/json">#{JSON.generate(data)}</script>
+        HTML
+
+        # Create hydration script
+        nonce_attr       = nonce_attribute
+        hydration_script = <<~HTML.strip
+          <script#{nonce_attr}>
+          window.#{window_attr} = JSON.parse(document.getElementById('#{unique_id}').textContent);
+          </script>
+        HTML
+
+        hydration_parts << json_script
+        hydration_parts << hydration_script
+      end
+
+      hydration_parts.join("\n")
+    end
+
+    # Get nonce attribute if available
+    def nonce_attribute
+      nonce = @rsfc_context.get('nonce')
+      nonce ? " nonce=\"#{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 props
+      def render_with_data(req, sess, cust, locale, template_name: nil, config: nil, **props)
+        view = new(req, sess, cust, locale, props: props, config: config)
+        view.render(template_name)
+      end
+
+      # Create view instance with props
+      def with_data(req, sess, cust, locale, config: nil, **props)
+        new(req, sess, cust, locale, props: props, config: config)
+      end
+    end
+  end
+end