Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Session

View as Markdownllms.txt

HTTP forgets everything between requests. A session is how your app remembers one browser across requests: who is signed in, the page they were going to, a “Saved!” message to show once. The browser holds only a random session id in a cookie; everything else stays on the server.

Your React UI uses a session automatically when people sign in. API clients (scripts, mobile apps, other servers) don’t: they send an API token on every request instead.

You don’t write anything to get a session: sign in to the app in your browser, then look at its cookies (your browser’s developer tools, Application → Cookies).

What you’ll see:

Name Value Flags
strutvane_session (__Host-strutvane_session over HTTPS) a long random value HttpOnly, Secure (HTTPS), SameSite=Lax, Path=/
XSRF-TOKEN the CSRF token the UI copies into a header readable by JavaScript, SameSite=Lax

HttpOnly means JavaScript in the page can’t read the session cookie, so a script injected into a page can’t steal it. The __Host- prefix (on HTTPS) means no subdomain can set or overwrite it.

Driver Stores sessions in Use it when
database (default) a sessions table Almost always: no extra service, works with several servers
file storage/framework/sessions/ One server, no database for sessions
redis Redis You already run Redis (installer question 18)
cookie an encrypted cookie in the browser Tiny apps that store very little

The installer picks database unless you chose Redis for “cache, queue and sessions”. The sessions table is an ordinary migration in your app, and it’s an internal table: it never gets a generated API or screen.

Setting Default Means
Idle timeout 120 minutes No request for that long → signed out
Absolute timeout 12 hours Signed out after that, however active
“Remember me” 30 days Both limits, for a session started with “remember me”
Strict security profile 8 hours The installer’s Strict profile shortens the absolute timeout

The session id is rotated (replaced by a new one) when someone signs in and when their privileges change, so an id someone saw before sign-in is useless afterwards (“session fixation” protection). Set these in config/auth.ts; see Authentication.

app/http/controllers/wizard.controller.ts
import { Controller, type HttpContext } from '@strutvane/framework'
export class WizardController extends Controller {
async step(ctx: HttpContext): Promise<Response> {
const session = ctx.session()
const current = session.get('wizard.step', 1) // read, with a default
session.put('wizard.step', current + 1) // write
return ctx.json({ step: current + 1 })
}
finish(ctx: HttpContext): Response {
ctx.session().forget('wizard.step') // remove one value
return ctx.noContent()
}
}
Method Does
get(key, fallback?) Read a value
put(key, value) Write a value
has(key) true when the key is set
pull(key) Read and remove
forget(key) Remove
flush() Remove every value (the user stays signed in only if you sign them in again)

Keep sessions small and never store secrets in them: an id, a step number, a few preferences.

Flash data is kept for the next request only, then removed: the classic “Post saved” message after a redirect.

ctx.session().flash('status', 'Post saved.')
return redirect().to('/posts/hello-world', 303)

On the next request ctx.session().get('status') is 'Post saved.'; on the one after, it’s gone. Old input (re-filling a plain HTML form after a validation error) works the same way. The React UI doesn’t need either: it keeps form state and messages in the browser.

ctx.session().regenerate() // new id, same values
ctx.session().invalidate() // new id, values cleared (sign-out)

Sign-in, sign-out and privilege changes already do this for you; call it yourself after any other change of trust level (switching to an impersonated user is handled by the auth package).

After a security incident, one command ends every session:

Terminal window
node strut session:flush

What you’ll see:

✔ 42 sessions deleted. Everyone signed in with a session must sign in again.
· API tokens are not affected; revoke them with the auth package (token:revoke --all).

Combine it with node strut token:revoke --all to cut off API tokens too. People can also end their own other sessions from their account settings (“Sign out other sessions”).

Two quick clicks on “Pay” send two requests at once with the same session. Laravel’s ->block() makes the second wait until the first finishes. Strutvane will offer the same on a route:

Route.post('/checkout', [CheckoutController, 'store']).block(),

For API calls today, use the idempotent middleware: a retry with the same Idempotency-Key gets the first response instead of running twice (Middleware).

A request that carries Authorization: Bearer … is treated as a token request, even if a session cookie came along too. Why: otherwise a forged cross-site request could add a junk Bearer header to skip the CSRF check while still riding on the victim’s cookie. Cookie requests must pass the CSRF check; token requests don’t need it. See CSRF Protection and API Tokens.

  • Several servers behind a load balancer: use database or redis so every server sees the same sessions (file keeps them on one server’s disk).
  • Docker changes nothing: the database driver uses the database container.
  • Tests don’t need a browser session: the test client signs in with actingAs(user) (a user model), or withToken(token) for API tokens (HTTP Tests).

Why: the idle timeout is short, or each server stores sessions separately (file driver behind a load balancer). Fix: use the database or redis driver with several servers, and check idleMinutes in config/auth.ts.

Section titled “The session cookie doesn’t arrive over plain HTTP in production”

Why: in production the cookie is Secure (HTTPS only), and over HTTPS it’s named __Host-strutvane_session. Fix: serve the app over HTTPS, and behind a proxy tell Strutvane to trust it so it knows the request was HTTPS (middleware.trustProxies({ at: [...] })).

My POST from a script gets 419 “Page expired”

Section titled “My POST from a script gets 419 “Page expired””

Why: the script sent the session cookie, so the request must pass the CSRF check. Fix: scripts should use an API token (Authorization: Bearer …) instead of a session.

I stored a big object in the session and everything got slow

Section titled “I stored a big object in the session and everything got slow”

Why: the whole session is read and written on every request. Fix: store an id in the session and the data in a table or the cache.