Documentation
¶
Overview ¶
Package session provides a flexible, secure HTTP session layer for the Astra framework.
It supports multiple backend drivers via the `Store` interface, shipping with both a zero-state, AES-256-GCM encrypted `CookieStore` and a fast, stateful `RedisStore`.
Sessions in Astra are lazily decoded and automatically persisted at the end of the request lifecycle via the session Middleware.
Example usage:
// Set values and flash messages
sess := ctx.Session()
sess.Set("user_id", 123)
sess.SetFlash("success", "Logged in successfully!")
// Redirecting will auto-save the session state
return ctx.Redirect(302, "/dashboard")
Index ¶
- func WithCookieName(name string) func(*CookieOptions)
- func WithSecure(secure bool) func(*CookieOptions)
- type CookieOptions
- type CookieStore
- type RedisStore
- type Session
- func (s *Session) Clear()
- func (s *Session) Delete(key string)
- func (s *Session) Flash(key string) any
- func (s *Session) Get(key string) any
- func (s *Session) GetInt(key string) int
- func (s *Session) GetString(key string) string
- func (s *Session) Has(key string) bool
- func (s *Session) ID() string
- func (s *Session) Regenerate(w http.ResponseWriter) error
- func (s *Session) Save(w http.ResponseWriter) error
- func (s *Session) Set(key string, value any)
- type Store
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WithCookieName ¶
func WithCookieName(name string) func(*CookieOptions)
WithCookieName sets the session cookie name.
func WithSecure ¶
func WithSecure(secure bool) func(*CookieOptions)
WithSecure marks the cookie Secure (HTTPS only).
Types ¶
type CookieOptions ¶
type CookieOptions struct {
Name string
Path string
Domain string
MaxAge time.Duration
Secure bool
HttpOnly bool
SameSite http.SameSite
}
CookieOptions controls the session cookie attributes.
type CookieStore ¶
type CookieStore struct {
// contains filtered or unexported fields
}
CookieStore is a stateless session store that encrypts session data into the cookie itself. No server-side state is required.
Cookies are: AES-256-GCM encrypted + HMAC-SHA256 signed. The key is derived from appKey using HKDF-SHA256.
Limitations:
- Maximum cookie size ~4 KB (browser cookie limit)
- Cannot invalidate individual sessions without rotating the key
func NewCookieStore ¶
func NewCookieStore(appKey []byte, options ...func(*CookieOptions)) *CookieStore
NewCookieStore creates a CookieStore with the given app key (any length). Two 32-byte keys are derived: one for AES-256-GCM, one for HMAC-SHA256.
func (*CookieStore) Destroy ¶
func (s *CookieStore) Destroy(w http.ResponseWriter, sess *Session) error
Destroy clears the session cookie.
func (*CookieStore) Load ¶
func (s *CookieStore) Load(r *http.Request) (*Session, error)
Load reads and decrypts the session cookie from the request. Returns an empty session if the cookie is absent or invalid.
func (*CookieStore) Regenerate ¶
func (s *CookieStore) Regenerate(w http.ResponseWriter, sess *Session) error
Regenerate issues a new session ID (for compatibility) and re-encrypts session data.
func (*CookieStore) Save ¶
func (s *CookieStore) Save(w http.ResponseWriter, sess *Session) error
Save encodes and encrypts the session data into the response cookie.
type RedisStore ¶
type RedisStore struct {
// contains filtered or unexported fields
}
RedisStore is a server-side session store backed by Redis. It stores serialised session data in Redis under a key of the form:
{prefix}:{sessionID}
The session ID is stored in a plain (non-sensitive) HTTP cookie. The cookie itself does NOT contain any session data.
func NewRedisStore ¶
func NewRedisStore(client redis.UniversalClient, ttl time.Duration, options ...func(*CookieOptions)) *RedisStore
NewRedisStore creates a RedisStore backed by the given Redis client. ttl controls how long sessions live in Redis (renewed on every Save).
func (*RedisStore) Destroy ¶
func (s *RedisStore) Destroy(w http.ResponseWriter, sess *Session) error
Destroy deletes the session from Redis and clears the cookie.
func (*RedisStore) Load ¶
func (s *RedisStore) Load(r *http.Request) (*Session, error)
Load reads the session ID cookie and loads session data from Redis. Returns an empty session with a fresh ID if the cookie is absent or Redis has no entry.
func (*RedisStore) Regenerate ¶
func (s *RedisStore) Regenerate(w http.ResponseWriter, sess *Session) error
Regenerate issues a new session ID, migrates data in Redis, and updates the cookie.
func (*RedisStore) Save ¶
func (s *RedisStore) Save(w http.ResponseWriter, sess *Session) error
Save serialises the session data to Redis and sets/refreshes the ID cookie.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session holds the session data for one request and knows how to persist itself back to the HTTP response.
func (*Session) ID ¶
ID returns the session ID (meaningful for server-side stores; empty for CookieStore).
func (*Session) Regenerate ¶
func (s *Session) Regenerate(w http.ResponseWriter) error
Regenerate issues a new session ID for the current session while preserving its data. This should be called after login or privilege escalation.
type Store ¶
type Store interface {
// Load reads a session from the request. Returns an empty session if none found.
Load(r *http.Request) (*Session, error)
// Save writes the session to the response (sets cookies, updates Redis, etc.)
Save(w http.ResponseWriter, s *Session) error
// Destroy invalidates the session and clears the cookie.
Destroy(w http.ResponseWriter, s *Session) error
// Regenerate issues a new session ID while preserving data.
Regenerate(w http.ResponseWriter, s *Session) error
}
Store is the low-level backend for session persistence.
Source Files