# 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 classes 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 classes          |
| 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

```crystal
require "session"

# Define your session data
class UserSession < Session::Base
  property? authenticated : Bool = false
  property user_id : Int64? = nil
  property username : String? = nil
  property role : String = "guest"
end

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

# Use sessions
store = Session.config.store.not_nil!
session = store.create
session.user_id = 12345
session.username = "alice"
```

## Architecture Overview

{% @mermaid/diagram content="flowchart LR
subgraph Application
Store\["Store API"]
Security\["Security Layer<br/>(Encryption/HMAC)"]
end

```
subgraph Backends
    Cookie["Cookie Store"]
    Memory["Memory Store"]
    Redis["Redis Store"]
    Cluster["Clustered Redis"]
end

Store --> Security
Security --> Cookie
Security --> Memory
Security --> Redis
Security --> Cluster" %}
```

## Framework Integrations

Session integrates with popular Crystal web frameworks:

* [**AZU Framework**](https://azutopia.gitbook.io/session/integrations/azu-framework) - Type-safe endpoint integration with helper modules
* [**HTTP::Server**](https://azutopia.gitbook.io/session/integrations/http-server) - Crystal's built-in HTTP server

## Getting Started

Continue to the [Installation](https://azutopia.gitbook.io/session/getting-started/installation) guide to add Session to your project.