Session

What a session is

A session stores data across requests for one browser (or client) under a session id. Kona attaches the session to the request as attribute "session" via the StartSession middleware.

Drivers

Configure with session.driver:

Driver	Behavior
array / memory	In-process map (tests / single process)
file	JSON files under storage/framework/sessions (or session.files)
cookie	JSON payload in the session cookie (signed or encrypted when app.key is set)
redis	Keys on a Redis connection (session.connection_prefix, default kona_session:)

For redis, register RedisServiceProvider before SessionServiceProvider so SessionManager can resolve a RedisConnection / RedisManager from the container.

Cookie integrity

Apps from kona new emit a random APP_KEY and default to session.driver=cookie. Cookie payloads are protected as follows:

1. Encrypted when an Encrypter is bound (for example via AuthServiceProvider + app.key), or when session.encrypt=true plus app.key.
2. HMAC-signed (payload.mac) when encryption is off but app.key is set.
3. Plain Base64 only when no key is available (tests / local experiments).

Other keys: session.lifetime (minutes), session.cookie, session.path, session.secure, session.http_only, session.same_site, session.encrypt.

Usage

Kotlin

val session = request.session()!! // or getAttribute(StartSession.ATTRIBUTE) as Session
session.put("user_id", 1)
session.flash("status", "Saved")
session.flashInput(mapOf("email" to "ada@example.com"))
val email = request.old("email") // "ada@example.com" on the next request

Java

Session session = (Session) request.getAttribute(StartSession.ATTRIBUTE);
session.put("user_id", 1);
session.flash("status", "Saved");
session.flashInput(Map.of("email", "ada@example.com"));
String email = request.old("email"); // next request

Redirect flash, old input, and previous URL

StartSession also:

1. Applies pending Response.with / withInput / withErrors bags before save (so Response.redirect("/home").with("status", "Saved") flashes for the next request).
2. Records _previous.url on successful GET responses (used by Response.back(request) and validation redirect-back).

Use session.flashInput(...), session.old("field"), and request.old("field") to redisplay form values after a failed POST. Validation errors flash under the key errors.

kona new registers SessionServiceProvider and wires StartSession plus VerifyCsrfToken (except /api/* and /brew/*) in bootstrap.Middleware. Manual apps: register the provider, resolve SessionManager, and add StartSession(manager) to the kernel.