Component Session Requirements

This document describes how Folio handles session requirements from components using a clean polymorphic architecture, allowing form atoms and interactive components to work correctly on cached pages.

Overview

When cache optimization is enabled (FOLIO_CACHE_SKIP_SESSION=true), Folio normally skips session cookies for anonymous users to improve Cloudflare cache hit rates. However, some components (like forms) require session state for CSRF tokens, captcha validation, or flash messages.

The Component Session Requirements system uses polymorphic override pattern - atom models that need session include a concern and override methods, which are automatically detected by the cache headers system without manual class name checking.

How It Works

1. Atom Models Declare Session Requirements

Atom models that correspond to form components include the helper concern and override the session_requirement_reason method:

class YourApp::Atom::Forms::Contact::Form < Folio::Atom::Base
  include Folio::ComponentSessionHelper

  def session_requirement_reason
    "contact_form_csrf"
  end
end

2. Automatic Detection via Polymorphism

Controllers automatically include the ComponentSessionRequirements concern via ApplicationControllerBase. This concern provides a polymorphic override of the cache headers system:

# Automatically included in all controllers
include Folio::ComponentSessionRequirements

# Provides polymorphic override
def should_skip_session_for_cache?
  # Auto-analyze @page if it exists and has atoms
  if defined?(@page) && @page&.respond_to?(:atoms)
    analyze_page_session_requirements(@page)
  end
  
  # Check if any component requires session
  return false if component_requires_session?

  # Delegate to parent (Headers concern)
  super if defined?(super)
end

3. Clean Architecture - No Manual Class Checking

The system automatically detects session requirements without fragile class name matching:

def analyze_page_session_requirements(page)
  return unless page.respond_to?(:atoms)

  page.atoms.each do |atom|
    # Polymorphic check - no string matching!
    if atom.respond_to?(:requires_session?) && atom.requires_session?
      @component_session_requirements ||= []
      @component_session_requirements << atom.session_requirement
    end
  end
end

Usage Examples

Architecture Overview

There are two different approaches for different component types:

Atom-based Components - Have both atom model and ViewComponent
Standalone Components - Only have ViewComponent, no model

The key difference is timing: cache headers must be set before component rendering, but components render during the view phase. Therefore:

Atom models enable automatic detection before rendering
Standalone components require manual controller registration

1. Atom-based Components (Recommended)

For atom-based components, add ComponentSessionHelper only to the atom model:

# ATOM MODEL - handles session requirements for cache headers
class YourApp::Atom::Forms::Leads::Form < Folio::Atom::Base
  include Folio::ComponentSessionHelper

  def session_requirement_reason
    "lead_atom_form_csrf"
  end
end

The corresponding ViewComponent doesn't need any session-related code - it just handles rendering.

2. Standalone Components

For components without atom models, use manual registration in the controller:

# CONTROLLER - register session requirements manually
class SomeController < ApplicationController
  before_action :register_form_session_requirement, only: [:form_page]
  
  private
    def register_form_session_requirement
      require_session_for_component!("standalone_form_csrf")
    end
end

The ViewComponent itself doesn't need any session-related code.

Additional Atom Model Examples

# Newsletter subscription atom model  
class YourApp::Atom::Forms::Newsletters::Form < Folio::Atom::Base
  include Folio::ComponentSessionHelper

  def session_requirement_reason
    "newsletter_subscription_csrf_and_turnstile"
  end
end

# Lead form atom model
class YourApp::Atom::Forms::Leads::Form < Folio::Atom::Base
  include Folio::ComponentSessionHelper

  def session_requirement_reason
    "lead_form_csrf_and_flash"
  end
end

How It Works

Session requirements are handled at different points in the request lifecycle depending on component type:

For atom-based components:

Session requirements are declared in the atom model using ComponentSessionHelper
The controller automatically analyzes @page.atoms during before_action
Cache headers are set accordingly in after_action

For standalone components:

Session requirements must be registered manually in the controller
Use require_session_for_component!("reason") in a before_action callback

Implementation Details

ComponentSessionHelper (for Atom Models Only)

module Folio::ComponentSessionHelper
  extend ActiveSupport::Concern

  # Default implementation - components can override
  def requires_session?
    true
  end

  # Default session requirement details - components should override  
  def session_requirement
    {
      reason: session_requirement_reason,
      component: "#{self.class.name}_atom",
      timestamp: Time.current
    }
  end

  # Override this in your component to specify the reason
  def session_requirement_reason
    "unknown_session_requirement"
  end
end