class Session::Configuration

• Session::Configuration
• Reference
• Object

Defined in:

configuration.cr

Constant Summary

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 Method Summary

• .process_secret : String

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

• .production_environment? : Bool

Instance Method Summary

• #allow_insecure_cookies : Bool

  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 : Bool

  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 : Bool
• #bind_to_user_agent=(bind_to_user_agent : Bool)
• #circuit_breaker_config : CircuitBreakerConfig
• #circuit_breaker_config=(circuit_breaker_config : CircuitBreakerConfig)
• #circuit_breaker_enabled : Bool

  Circuit breaker configuration for Redis connections

• #circuit_breaker_enabled=(circuit_breaker_enabled : Bool)

  Circuit breaker configuration for Redis connections

• #cluster : ClusterConfig

  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 : Bool

  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 : Int32

  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_same_site : HTTP::Cookie::SameSite
• #cookie_same_site=(cookie_same_site : HTTP::Cookie::SameSite)
• #cookie_secure : Bool

  Cookie attributes.

• #cookie_secure=(cookie_secure : Bool)

  Cookie attributes.

• #digest_algorithm : Symbol

  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 : Bool

  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 : Bool

  Error handling configuration

• #enable_retry=(enable_retry : Bool)

  Error handling configuration

• #encrypt_redis_data : Bool

  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 : Message::Encryptor

  The encryptor for the current settings.

• #fail_fast_on_corruption : Bool
• #fail_fast_on_corruption=(fail_fast_on_corruption : Bool)
• #kdf_iterations : Int32
• #kdf_iterations=(kdf_iterations : Int32)
• #kdf_salt : String
• #kdf_salt=(kdf_salt : String)
• #log_errors : Bool
• #log_errors=(log_errors : Bool)
• #metrics_backend : 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 : Proc(String, Session::Base, Nil)
• #on_client=(on_client : Proc(String, Session::Base, Nil))
• #on_deleted : Proc(String, Session::Base, Nil)
• #on_deleted=(on_deleted : Proc(String, Session::Base, Nil))
• #on_loaded : Proc(String, Session::Base, Nil)
• #on_loaded=(on_loaded : Proc(String, Session::Base, Nil))
• #on_regenerated : Proc(String, String, Session::Base, Nil)
• #on_regenerated=(on_regenerated : Proc(String, String, Session::Base, Nil))
• #on_started : Proc(String, Session::Base, Nil)
• #on_started=(on_started : Proc(String, Session::Base, Nil))
• #require_secure_secret : Bool
• #require_secure_secret=(require_secure_secret : Bool | Nil)

  Whether a missing or published secret is an error rather than a warning.

• #retry_config : RetryConfig

  Retry configuration for resilient operations

• #retry_config=(retry_config : RetryConfig)

  Retry configuration for resilient operations

• #secret : String

  The key sessions are encrypted and signed with: the one configured, else SESSION_SECRET.

• #secret=(secret : String | Nil)
• #session
• #session_key : String
• #session_key=(session_key : String)
• #sliding_expiration : Bool

  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 : Time::Span
• #timeout=(timeout : Time::Span)
• #trust_proxy_headers : Bool

  Whether X-Forwarded-For and X-Real-IP name the client for IP binding.

• #trust_proxy_headers=(trust_proxy_headers : Bool)

  Whether X-Forwarded-For and X-Real-IP name the client for IP binding.

• #use_kdf : Bool

  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? : Bool

  Check if the current secret is the insecure default

• #validate_cookie_options! : Nil

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

• #validate_secret! : Nil

  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.

Constructor Detail

Class Method Detail

Instance Method Detail