Documentation
¶
Overview ¶
Package session provides cookie-backed sessions modelled on Laravel's Session facade.
A session is a map[string]any persisted server-side under an opaque ID. The client carries the ID in an HttpOnly+Secure cookie. The default store is in-memory (suitable for single-replica apps and tests); the Store interface is small enough that a Redis or DB driver can plug in without changing call sites.
Sessions are short-lived: the cookie's MaxAge equals the store's TTL, and stale records are GC'd in the background. To survive restarts or run multi-replica, swap NewMemoryStore() for an external store implementation.
Index ¶
- Variables
- type Manager
- type MemoryStore
- type Options
- type Session
- func (s *Session) All() map[string]any
- func (s *Session) Destroy(ctx context.Context, w http.ResponseWriter) error
- func (s *Session) Flush()
- func (s *Session) Forget(key string)
- func (s *Session) Get(key string) (any, bool)
- func (s *Session) GetString(key string) string
- func (s *Session) ID() string
- func (s *Session) IsNew() bool
- func (s *Session) Put(key string, value any)
- func (s *Session) Regenerate(ctx context.Context) error
- func (s *Session) Save(ctx context.Context, w http.ResponseWriter) error
- type Store
Constants ¶
This section is empty.
Variables ¶
var ErrMissing = errors.New("session: key not set")
ErrMissing is returned by Get when the requested key isn't set.
Functions ¶
This section is empty.
Types ¶
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager owns the cookie configuration and a Store. A single Manager is shared across requests; per-request access happens through Session below.
func NewManager ¶
NewManager returns a Manager with the given store and options.
func (*Manager) Middleware ¶
Middleware returns a framework-agnostic net/http middleware. It starts the session at the top of each request, makes the *Session available via session.FromRequest(r), and saves the session before the handler returns.
The middleware is compatible with any router that speaks the stdlib http.Handler interface (Gin, Fiber adapters, Chi, Echo, plain net/http, lagodev's web package). Use it once per app:
mw := session.Middleware(mgr)
mux.Handle("/", mw(http.HandlerFunc(handler)))
If Save fails (store unreachable), the failure is silently absorbed — the response has already begun streaming by the time the handler returns. Wrap a custom logger via FailureHandler if you need to be notified.
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore is a sync.RWMutex-backed in-process Store with lazy expiry and a periodic sweeper.
func NewMemoryStore ¶
func NewMemoryStore(defaultTTL time.Duration) *MemoryStore
NewMemoryStore returns a MemoryStore with the given default TTL. Pass 0 for "no expiry" (entries live until Destroy).
type Options ¶
type Options struct {
CookieName string
TTL time.Duration
Insecure bool // when true, cookies are not marked Secure
SameSite http.SameSite
}
Options configures Manager. Zero values use safe defaults (cookie="lagodev_session", TTL=2h, Secure=true, SameSite=Lax).
Note the inverted `Insecure` flag: cookies default to Secure=true so production code is correct without extra setup. Pass Insecure=true only for local HTTP development.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is the per-request handle. Not safe for concurrent use across goroutines.
func FromContext ¶
FromContext is the bare-ctx variant. Returns nil when no session is attached.
func FromRequest ¶
FromRequest pulls the *Session attached by Middleware. Returns nil if the middleware was not applied to the request.
func (*Session) Flush ¶
func (s *Session) Flush()
Flush clears the session contents (the ID is preserved).
func (*Session) GetString ¶
GetString is a convenience for string-typed values; returns "" if the key is missing or the wrong type.
func (*Session) IsNew ¶
IsNew reports whether the session was created during this request (no prior cookie or stale cookie).
func (*Session) Regenerate ¶
Regenerate issues a new session ID, preserving the data. Call after privilege escalation (login/logout) to mitigate session fixation.
type Store ¶
type Store interface {
// Read returns the session data for id. ok=false on miss.
Read(ctx context.Context, id string) (map[string]any, bool, error)
// Write replaces the session data for id. ttl=0 means use the
// store's default.
Write(ctx context.Context, id string, data map[string]any, ttl time.Duration) error
// Destroy removes the session.
Destroy(ctx context.Context, id string) error
}
Store persists per-session data. Implementations must be safe for concurrent use.
Source Files