class

Session::Configuration

Inherits Reference < Object

Constants

DEFAULT_SECRET = "1sxc1aNxGHTTZKlK5cpCgufJAqGM4G13"

The secret older releases signed with when none was configured. It is public, so it is never used by default any more and is refused where require_secure_secret holds.

MIN_SECRET_BYTES = 32

AES-256 takes a 32-byte key, and the secret is that key unless use_kdf derives one. The HMAC signature always uses the secret itself, so the minimum holds with use_kdf too.

PRODUCTION_ENVIRONMENTS = ["production", "staging"] of ::String

Environments that must not run on the published default secret.

Constructors

from_preset(preset : Symbol) : Configuration

Load configuration from a preset (returns a new Configuration instance) Available presets: :development, :production, :high_security, :testing, :clustered

Class methods

process_secret

The random fallback, one per process so every configuration agrees on it; warns once.

production_environment?

Instance methods

allow_insecure_cookies

Where a secure secret is required (production, staging), insecure cookies are refused too, unless this opts out explicitly.

allow_insecure_cookies=(allow_insecure_cookies : Bool)

Where a secure secret is required (production, staging), insecure cookies are refused too, unless this opts out explicitly.

apply_preset(preset : Symbol) : self

Apply a preset's settings to this configuration instance Available presets: :development, :production, :high_security, :testing, :clustered

bind_to_ip

Session binding: bind sessions to client fingerprint for security

bind_to_ip=(bind_to_ip : Bool)

Session binding: bind sessions to client fingerprint for security

bind_to_user_agent

bind_to_user_agent=(bind_to_user_agent : Bool)

circuit_breaker_config

circuit_breaker_config=(circuit_breaker_config : CircuitBreakerConfig)

circuit_breaker_enabled

Circuit breaker configuration for Redis connections

circuit_breaker_enabled=(circuit_breaker_enabled : Bool)

Circuit breaker configuration for Redis connections

cluster

Cluster configuration for multi-node deployments with Redis Pub/Sub

cluster=(cluster : ClusterConfig)

Cluster configuration for multi-node deployments with Redis Pub/Sub

compress_data

Data compression: when enabled, session data is compressed before storage

compress_data=(compress_data : Bool)

Data compression: when enabled, session data is compressed before storage

compression_threshold

Minimum size in bytes before compression is applied (smaller data may grow with compression)

compression_threshold=(compression_threshold : Int32)

Minimum size in bytes before compression is applied (smaller data may grow with compression)

cookie_secure

Cookie attributes. Cookies are always HttpOnly. Secure keeps them off plain http (browsers still accept a Secure cookie over http on localhost); turn it off only for an http-only setup.

cookie_secure=(cookie_secure : Bool)

Cookie attributes. Cookies are always HttpOnly. Secure keeps them off plain http (browsers still accept a Secure cookie over http on localhost); turn it off only for an http-only setup.

digest_algorithm

Digest algorithm for HMAC signatures (:sha256 recommended, :sha1 for legacy)

digest_algorithm=(digest_algorithm : Symbol)

Digest algorithm for HMAC signatures (:sha256 recommended, :sha1 for legacy)

digest_fallback

Enable auto-fallback to SHA1 for migrating old sessions (logs deprecation warning)

digest_fallback=(digest_fallback : Bool)

Enable auto-fallback to SHA1 for migrating old sessions (logs deprecation warning)

enable_retry

Error handling configuration

enable_retry=(enable_retry : Bool)

Error handling configuration

encrypt_redis_data

Redis encryption: when enabled, session data stored in Redis is encrypted

encrypt_redis_data=(encrypt_redis_data : Bool)

Redis encryption: when enabled, session data stored in Redis is encrypted

encryptor

The encryptor for the current settings. It is reused while they stay the same, so PBKDF2 (use_kdf) runs once per secret, salt and iteration count, not on every encrypt and decrypt.

fail_fast_on_corruption

fail_fast_on_corruption=(fail_fast_on_corruption : Bool)

kdf_iterations

kdf_iterations=(kdf_iterations : Int32)

kdf_salt

kdf_salt=(kdf_salt : String)

log_errors

log_errors=(log_errors : Bool)

metrics_backend

Metrics backend for observability (default: NullBackend discards all metrics)

metrics_backend=(metrics_backend : Metrics::Backend)

Metrics backend for observability (default: NullBackend discards all metrics)

on_client

on_client=(on_client : Proc(String, Session::Base, Nil))

on_deleted

on_deleted=(on_deleted : Proc(String, Session::Base, Nil))

on_loaded

on_loaded=(on_loaded : Proc(String, Session::Base, Nil))

on_regenerated

on_regenerated=(on_regenerated : Proc(String, String, Session::Base, Nil))

on_started

on_started=(on_started : Proc(String, Session::Base, Nil))

require_secure_secret

require_secure_secret=(require_secure_secret : Bool | Nil)

Whether a missing or published secret is an error rather than a warning. Unless set, it holds in production and staging, read from CRYSTAL_ENV (case-insensitive) each time it is checked.

retry_config

Retry configuration for resilient operations

retry_config=(retry_config : RetryConfig)

Retry configuration for resilient operations

secret

The key sessions are encrypted and signed with: the one configured, else SESSION_SECRET. Without either, InsecureSecretException where require_secure_secret holds, and otherwise a random key for this process only (sessions do not survive a restart or reach another instance). Not memoised: the random fallback is refused again as soon as require_secure_secret holds.

secret=(secret : String | Nil)

session

session_key

session_key=(session_key : String)

sliding_expiration

Sliding expiration: when enabled, session timeout resets on each access

sliding_expiration=(sliding_expiration : Bool)

Sliding expiration: when enabled, session timeout resets on each access

timeout

timeout=(timeout : Time::Span)

trust_proxy_headers

Whether X-Forwarded-For and X-Real-IP name the client for IP binding. Any client can send them, so they are believed only when a trusted proxy in front of the app sets them.

trust_proxy_headers=(trust_proxy_headers : Bool)

Whether X-Forwarded-For and X-Real-IP name the client for IP binding. Any client can send them, so they are believed only when a trusted proxy in front of the app sets them.

use_kdf

Key Derivation Function (KDF) settings When enabled, derives cipher key from secret using PBKDF2-SHA256

use_kdf=(use_kdf : Bool)

Key Derivation Function (KDF) settings When enabled, derives cipher key from secret using PBKDF2-SHA256

using_default_secret?

Check if the current secret is the insecure default

validate_cookie_options!

Raises InvalidCookieOptions for cookie options browsers reject or that defeat the secret requirement.

validate_secret!

Validate secret security - warns or raises based on configuration

validate_secret_for!(store : Store) : Nil

Raises InsecureSecretException when store encrypts with the secret (Store#encrypts_with_secret?: a CookieStore, or a Redis store with encrypt_redis_data) and the secret is missing, published or too short.