Documentation
¶
Overview ¶
Package session provides server-side and cookie sessions with flash messages, old input, regeneration (anti-fixation) and idle/absolute timeouts. Sessions are loaded lazily and written only when modified.
Index ¶
- Variables
- type Config
- type Manager
- type MemoryStore
- type SQLOption
- type SQLStore
- func (s *SQLStore) CreateTable(ctx context.Context) error
- func (s *SQLStore) Delete(ctx context.Context, id string) error
- func (s *SQLStore) Load(ctx context.Context, id string) ([]byte, bool, error)
- func (s *SQLStore) Prune(ctx context.Context) (int64, error)
- func (s *SQLStore) Save(ctx context.Context, id string, data []byte, expiry time.Time) error
- type Session
- func (s *Session) All() map[string]any
- func (s *Session) Flash(key string, value any)
- func (s *Session) Forget(keys ...string)
- func (s *Session) Get(key string) any
- func (s *Session) GetInt64(key string) (int64, bool)
- func (s *Session) GetString(key string) string
- func (s *Session) Has(key string) bool
- func (s *Session) ID() string
- func (s *Session) Invalidate()
- func (s *Session) Pull(key string) any
- func (s *Session) Put(key string, value any)
- func (s *Session) Reflash()
- func (s *Session) Regenerate()
- type Store
Constants ¶
This section is empty.
Variables ¶
var ErrCookieTooLarge = errors.New("session: cookie session data exceeds 4 KB; use a server-side store")
ErrCookieTooLarge is returned when cookie session data exceeds 4 KB.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// CookieName defaults to "vukem_session"; with Secure, Path "/" and no
// Domain the "__Host-" prefix is added automatically.
CookieName string
// Path defaults to "/".
Path string
// Domain is empty (host-only cookie) by default.
Domain string
// Secure sends the cookie over HTTPS only. Required in production.
Secure bool
// SameSite defaults to Lax.
SameSite http.SameSite
// IdleTimeout ends sessions after inactivity (default 2h).
IdleTimeout time.Duration
// Lifetime ends sessions this long after creation (default 24h).
Lifetime time.Duration
// Store keeps sessions server-side; nil stores them in an encrypted
// cookie (CookieKey required).
Store Store
// CookieKey is the 32-byte AES-256-GCM key for cookie sessions; derive
// it from APP_KEY: app.Key.Derive("session.cookie", 32).
CookieKey []byte
// Production enables boot-time checks (Secure must be true).
Production bool
// Now is the clock (tests); defaults to time.Now.
Now func() time.Time
// Log receives security events and storage errors.
Log *slog.Logger
}
Config configures a Manager. Zero values use secure defaults.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager loads and saves sessions around each request.
func New ¶
New validates cfg and returns a Manager. Insecure production settings are boot errors (docs/security.md, A02/A07).
func (*Manager) CookieName ¶
CookieName returns the effective cookie name.
func (*Manager) Cookies ¶ added in v0.5.0
Cookies returns the cookies of a new session holding data, as the middleware would set them. Tests use it to start a request already logged in (vukemtest Client.ActingAs).
func (*Manager) Middleware ¶
Middleware loads the session lazily, exposes it through web.Ctx (and web.SessionFrom), installs the flash-and-redirect validation hook, and saves it before the response headers are sent.
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore keeps sessions in process memory (development and tests).
func NewMemoryStore ¶
func NewMemoryStore() *MemoryStore
NewMemoryStore returns an empty MemoryStore.
func (*MemoryStore) Delete ¶
func (m *MemoryStore) Delete(_ context.Context, id string) error
Delete implements Store.
func (*MemoryStore) Len ¶
func (m *MemoryStore) Len() int
Len returns the number of stored sessions (tests).
type SQLOption ¶
type SQLOption func(*SQLStore)
SQLOption configures NewSQLStore.
func WithDollarPlaceholders ¶
func WithDollarPlaceholders() SQLOption
WithDollarPlaceholders uses $1, $2... (PostgreSQL) instead of ?.
type SQLStore ¶
type SQLStore struct {
// contains filtered or unexported fields
}
SQLStore keeps sessions in a SQL table (SQLite or PostgreSQL):
CREATE TABLE sessions (id TEXT PRIMARY KEY, data TEXT NOT NULL, expires_at BIGINT NOT NULL)
func NewSQLStore ¶
NewSQLStore returns a SQLStore. The table name is validated because it is interpolated into SQL (A05).
func (*SQLStore) CreateTable ¶
CreateTable creates the sessions table if it does not exist.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is one user's session. It is safe for concurrent use within a request.
func (*Session) Invalidate ¶
func (s *Session) Invalidate()
Invalidate clears all data and issues a new id (logout).
func (*Session) Reflash ¶
func (s *Session) Reflash()
Reflash keeps the current flash data for one more request.
func (*Session) Regenerate ¶
func (s *Session) Regenerate()
Regenerate issues a new id and keeps the data. Call it after login and any privilege change (session fixation, A07).
type Store ¶
type Store interface {
// Load returns the data saved for id; found is false when the session
// does not exist or expired.
Load(ctx context.Context, id string) (data []byte, found bool, err error)
// Save stores data for id until expiry.
Save(ctx context.Context, id string, data []byte, expiry time.Time) error
// Delete removes id.
Delete(ctx context.Context, id string) error
}
Store persists server-side sessions.