# 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**](/session/integrations/azu-framework.md) - Type-safe endpoint integration with helper modules
* [**HTTP::Server**](/session/integrations/http-server.md) - Crystal's built-in HTTP server

## Getting Started

Continue to the [Installation](/session/getting-started/installation.md) guide to add Session to your project.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://azutopia.gitbook.io/session/getting-started/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.