Introduction

A production-ready, type-safe session management library for Crystal applications.

Session provides enterprise-grade session handling with multiple storage backends, built-in security features, and resilience patterns. Whether you're building a simple web application or a distributed microservices architecture, Session offers the flexibility and reliability your application demands.

Why Session?

• Type Safety - Define your session data as Crystal structs with compile-time guarantees

• Multiple Backends - Choose from Cookie, Memory, Redis, or Clustered Redis storage

• Security First - AES-256 encryption, HMAC-SHA256 signatures, and configurable key derivation

• Production Ready - Circuit breakers, retry logic, and graceful degradation built-in

• Clustering Support - Multi-node session synchronization with Redis Pub/Sub

• Developer Experience - Clean API, comprehensive documentation, and extensive test coverage

Features at a Glance

Feature	Description
Type-Safe Sessions	Define session data as Crystal structs
Multiple Storage Backends	Cookie, Memory, Redis, Clustered Redis
Session Clustering	Multi-node synchronization via Redis Pub/Sub
Local Caching	Configurable TTL-based cache with LRU eviction
Encryption	AES-256-CBC encryption with HMAC-SHA256 signing
Key Derivation	PBKDF2-SHA256 for enhanced security
Client Binding	Bind sessions to IP and/or User-Agent
Flash Messages	One-request-only message storage
Circuit Breaker	Prevent cascading failures
Retry Logic	Exponential backoff with jitter
Compression	Gzip compression for large payloads
Connection Pooling	Efficient Redis connection management
Metrics	Pluggable metrics backend

Quick Example

require "session"

# Define your session data
struct UserSession
  include Session::SessionData
  property user_id : Int64?
  property username : String?
  property role : String = "guest"
end

# Configure session management
Session.configure do |config|
  config.secret = ENV["SESSION_SECRET"]
  config.timeout = 24.hours
  config.provider = Session::RedisStore(UserSession).provider(
    client: Redis.new
  )
end

# Use sessions
provider = Session.provider
session = provider.create
session.data.user_id = 12345
session.data.username = "alice"

Architecture Overview

Framework Integrations

Session integrates with popular Crystal web frameworks:

• AZU Framework - Type-safe endpoint integration with helper modules

• HTTP::Server - Crystal's built-in HTTP server

Getting Started

Continue to the Installation guide to add Session to your project.