Skip to content

basic.md

Latest commit

 

History

History
131 lines (101 loc) · 3.7 KB

basic.md

File metadata and controls

131 lines (101 loc) · 3.7 KB
Raw

Basic Configuration

Configure Session to match your application's requirements.

Minimal Configuration

Session.configure do |config|
  # The secret is read from SESSION_SECRET (random per process in development without it)
  config.store = Session::MemoryStore(UserSession).new
end

Configuration Presets (Recommended)

Session provides presets for common scenarios, reducing configuration from 14+ lines to just 3-4 lines:

Development Preset

Session.configure do |config|
  config.apply_preset(:development)
  config.store = Session::MemoryStore(UserSession).new
end

Production Preset

Session.configure do |config|
  config.apply_preset(:production)
  # The secret is read from SESSION_SECRET (random per process in development without it)
  config.store = Session::RedisStore(UserSession).new(client: Redis.new)
end

Available Presets

Preset Use Case Key Features
:development Local development 30min timeout, no encryption, minimal security
:production Production deployments 1hr timeout, encryption, circuit breaker, retry
:high_security Sensitive applications 15min timeout, KDF, client binding, max security
:testing Test suites 5min timeout, fast, no logging
:clustered Multi-node deployments Production settings + clustering + local cache

Customizing Presets

Start with a preset and override specific settings:

Session.configure do |config|
  config.apply_preset(:production)

  # Override specific settings
  config.timeout = 8.hours
  config.bind_to_user_agent = true

  # The secret is read from SESSION_SECRET (random per process in development without it)
  config.store = Session::RedisStore(UserSession).new
end

Full Configuration

Session.configure do |config|
  # Core settings
  # The secret is read from SESSION_SECRET (random per process in development without it)
  config.timeout = 1.hour                     # Session lifetime
  config.session_key = "_session"             # Cookie name

  # Storage store
  config.store = Session::RedisStore(UserSession).new(
    client: Redis.new
  )
end

Configuration Properties

Property Type Default Description
secret String SESSION_SECRET Encryption and signing secret (32+ bytes, also with use_kdf)
timeout Time::Span 1.hour Session lifetime
session_key String "_session" Cookie name
store Store nil Storage backend (typed by Session.use_store)
cookie_secure Bool true Secure attribute of the session cookies
cookie_same_site HTTP::Cookie::SameSite Strict SameSite attribute of the session cookies

Environment-Based Configuration

Session.configure do |config|
  # The secret is read from SESSION_SECRET (random per process in development without it)

  case ENV["APP_ENV"]?
  when "production"
    config.timeout = 24.hours
    config.require_secure_secret = true
    config.store = Session::RedisStore(UserSession).new(
      client: Redis.new(url: ENV["REDIS_URL"])
    )
  when "test"
    config.timeout = 5.minutes
    config.store = Session::MemoryStore(UserSession).new
  else # development
    config.timeout = 1.hour
    config.store = Session::MemoryStore(UserSession).new
  end
end

Accessing Configuration

# Get current configuration
config = Session.config

puts config.timeout        # => 1.hour
puts config.session_key    # => "_session"

# Get configured store
store = Session.config.store.not_nil!

Related