AZU Framework

Integrate Session with the AZU web framework for type-safe session management in your Crystal applications.

Overview

Installation

Add both dependencies to your shard.yml:

dependencies:
  azu:
    github: azutoolkit/azu
  session:
    github: azutoolkit/session

Quick Start

1. Define Your Session Data

# src/sessions/user_session.cr
struct UserSession
  include Session::SessionData

  property user_id : Int64?
  property username : String?
  property email : String?
  property roles : Array(String) = [] of String
  property logged_in_at : Time?

  def authenticated? : Bool
    !user_id.nil?
  end

  def admin? : Bool
    roles.includes?("admin")
  end
end

2. Configure Session

# src/config/session.cr
require "session"

Session.configure do |config|
  config.secret = ENV["SESSION_SECRET"]
  config.timeout = 24.hours
  config.session_key = "myapp_session"
  config.sliding_expiration = true

  # Use Redis for production
  if Azu.env.production?
    config.provider = Session::RedisStore(UserSession).provider(
      client: Redis.new(url: ENV["REDIS_URL"])
    )
  else
    config.provider = Session::MemoryStore(UserSession).provider
  end
end

3. Create the Session Handler

# src/handlers/session_handler.cr
class AzuSessionHandler
  include HTTP::Handler

  def initialize(@provider : Session::Provider(UserSession))
  end

  def call(context : HTTP::Server::Context)
    # Load session from cookies
    @provider.load_from(context.request.cookies)

    # Store provider in context for endpoint access
    context.set("session_provider", @provider)

    # Process request
    call_next(context)

    # Set session cookie in response
    @provider.set_cookies(context.response.cookies)
  rescue Session::SessionExpiredException
    # Handle expired session - create new one
    @provider.create
    call_next(context)
    @provider.set_cookies(context.response.cookies)
  rescue Session::SessionCorruptionException
    # Handle corrupted session - create new one
    @provider.create
    call_next(context)
    @provider.set_cookies(context.response.cookies)
  end
end

4. Register the Handler

# src/app.cr
require "azu"
require "./config/session"
require "./handlers/session_handler"

Azu.configure do
  port = ENV.fetch("PORT", "4000").to_i
end

Azu.start [
  Azu::Handler::RequestId.new,
  Azu::Handler::Rescuer.new,
  AzuSessionHandler.new(Session.provider),  # Add session handler
  Azu::Handler::Logger.new,
]

5. Use Sessions in Endpoints

# src/endpoints/login_endpoint.cr
struct LoginEndpoint
  include Azu::Endpoint(LoginRequest, LoginResponse)
  post "/login"

  def call : LoginResponse
    # Get session provider from context
    provider = context.get("session_provider").as(Session::Provider(UserSession))

    # Authenticate user
    user = authenticate(request.email, request.password)

    if user
      # Regenerate session ID after login (security best practice)
      provider.regenerate_id

      # Set session data
      provider.data.user_id = user.id
      provider.data.username = user.username
      provider.data.email = user.email
      provider.data.roles = user.roles
      provider.data.logged_in_at = Time.utc

      # Set flash message
      provider.flash["notice"] = "Welcome back, #{user.username}!"

      LoginResponse.new(success: true, message: "Logged in successfully")
    else
      provider.flash["error"] = "Invalid credentials"
      LoginResponse.new(success: false, message: "Invalid email or password")
    end
  end

  private def authenticate(email : String, password : String) : User?
    # Your authentication logic
  end
end

Helper Module

Create a helper module to simplify session access in endpoints:

# src/helpers/session_helper.cr
module SessionHelper
  def session_provider : Session::Provider(UserSession)
    context.get("session_provider").as(Session::Provider(UserSession))
  end

  def current_session : Session::SessionId(UserSession)
    session_provider.current_session
  end

  def session_data : UserSession
    session_provider.data
  end

  def flash : Session::Flash
    session_provider.flash
  end

  def authenticated? : Bool
    session_data.authenticated?
  end

  def current_user_id : Int64?
    session_data.user_id
  end

  def require_authentication! : Nil
    unless authenticated?
      raise Azu::Unauthorized.new("Authentication required")
    end
  end

  def require_admin! : Nil
    require_authentication!
    unless session_data.admin?
      raise Azu::Forbidden.new("Admin access required")
    end
  end
end

Use the helper in your endpoints:

struct ProfileEndpoint
  include Azu::Endpoint(EmptyRequest, ProfileResponse)
  include SessionHelper
  get "/profile"

  def call : ProfileResponse
    require_authentication!

    user = User.find(current_user_id)
    ProfileResponse.new(user)
  end
end

struct AdminDashboardEndpoint
  include Azu::Endpoint(EmptyRequest, DashboardResponse)
  include SessionHelper
  get "/admin/dashboard"

  def call : DashboardResponse
    require_admin!

    stats = AdminService.get_dashboard_stats
    DashboardResponse.new(stats)
  end
end

Logout Endpoint

struct LogoutEndpoint
  include Azu::Endpoint(EmptyRequest, LogoutResponse)
  include SessionHelper
  post "/logout"

  def call : LogoutResponse
    if authenticated?
      username = session_data.username
      session_provider.delete  # Destroy session
      flash["notice"] = "Goodbye, #{username}!"
    end

    LogoutResponse.new(success: true)
  end
end

Flash Messages in Templates

Access flash messages in your views:

# src/endpoints/home_endpoint.cr
struct HomeEndpoint
  include Azu::Endpoint(EmptyRequest, HomeResponse)
  include SessionHelper
  get "/"

  def call : HomeResponse
    HomeResponse.new(
      flash_notice: flash.now["notice"]?,
      flash_error: flash.now["error"]?,
      user: authenticated? ? session_data.username : nil
    )
  end
end

<!-- src/templates/home.jinja -->
{% if flash_notice %}
  <div class="alert alert-success">{{ flash_notice }}</div>
{% endif %}

{% if flash_error %}
  <div class="alert alert-danger">{{ flash_error }}</div>
{% endif %}

{% if user %}
  <p>Welcome, {{ user }}!</p>
{% else %}
  <p>Please <a href="/login">log in</a>.</p>
{% endif %}

Production Configuration

With Redis and Clustering

Session.configure do |config|
  config.secret = ENV["SESSION_SECRET"]
  config.timeout = 24.hours
  config.session_key = "myapp_session"

  # Security settings
  config.use_kdf = true
  config.kdf_iterations = 100_000
  config.bind_to_ip = true
  config.bind_to_user_agent = true
  config.sliding_expiration = true

  # Resilience
  config.enable_retry = true
  config.circuit_breaker_enabled = true

  # Clustering for multi-node deployments
  config.cluster.enabled = true
  config.cluster.node_id = ENV["POD_NAME"]? || ENV["HOSTNAME"]? || UUID.random.to_s
  config.cluster.local_cache_ttl = 30.seconds
  config.cluster.local_cache_max_size = 10_000

  config.provider = Session::ClusteredRedisStore(UserSession).new(
    client: Redis.new(url: ENV["REDIS_URL"])
  )
end

With Cookie Store (Stateless)

For serverless or edge deployments:

Session.configure do |config|
  config.secret = ENV["SESSION_SECRET"]
  config.timeout = 24.hours
  config.compress_data = true  # Keep cookies small

  config.provider = Session::CookieStore(UserSession).provider
end

Testing

Test Helper

# spec/support/session_helper.cr
def with_session(data : UserSession? = nil, &)
  provider = Session::Provider(UserSession).new(
    Session::MemoryStore(UserSession).new
  )
  provider.create

  if data
    provider.data.user_id = data.user_id
    provider.data.username = data.username
    provider.data.roles = data.roles
  end

  yield provider
end

def authenticated_session(user : User) : Session::Provider(UserSession)
  provider = Session::Provider(UserSession).new(
    Session::MemoryStore(UserSession).new
  )
  provider.create
  provider.data.user_id = user.id
  provider.data.username = user.username
  provider.data.roles = user.roles
  provider
end

Endpoint Tests

# spec/endpoints/profile_endpoint_spec.cr
require "./spec_helper"

describe ProfileEndpoint do
  it "returns profile for authenticated user" do
    user = User.create(username: "alice", email: "[e-mail]")

    with_session do |provider|
      provider.data.user_id = user.id
      provider.data.username = user.username

      # Mock the context with session provider
      context = create_test_context("/profile")
      context.set("session_provider", provider)

      endpoint = ProfileEndpoint.new(context)
      response = endpoint.call

      response.username.should eq("alice")
    end
  end

  it "rejects unauthenticated requests" do
    with_session do |provider|
      context = create_test_context("/profile")
      context.set("session_provider", provider)

      endpoint = ProfileEndpoint.new(context)

      expect_raises(Azu::Unauthorized) do
        endpoint.call
      end
    end
  end
end

Graceful Shutdown

Handle server shutdown to properly close cluster connections:

# src/app.cr
at_exit do
  if provider = Session.config.provider
    if clustered = provider.as?(Session::ClusteredRedisStore(UserSession))
      clustered.shutdown
    end
  end
end

Signal::INT.trap do
  Azu.stop
  exit
end

Signal::TERM.trap do
  Azu.stop
  exit
end

Complete Example

See the azu-session-example repository for a complete working example with:

• User authentication (login/logout)

• Protected routes

• Flash messages

• Admin authorization

• Redis session storage

• Test coverage