Session - 💧 Mizu

Overview

The session middleware provides server-side session management with secure cookie-based tracking. Sessions can store user data across requests with configurable storage backends. Use it when you need:

User login sessions
Shopping cart persistence
Multi-step form wizards

Installation

import "github.com/go-mizu/mizu/middlewares/session"

Quick Start

app := mizu.New()

// Enable sessions
app.Use(session.New(session.Options{}))

app.Get("/login", func(c *mizu.Ctx) error {
    sess := session.Get(c)
    sess.Set("user_id", "123")
    return c.Text(200, "Logged in")
})

app.Get("/profile", func(c *mizu.Ctx) error {
    sess := session.Get(c)
    userID, _ := sess.Get("user_id").(string)
    return c.Text(200, "User: "+userID)
})

Configuration

Options

Option	Type	Default	Description
`CookieName`	`string`	`"session_id"`	Session cookie name
`CookiePath`	`string`	`"/"`	Cookie path
`CookieDomain`	`string`	`""`	Cookie domain
`CookieSecure`	`bool`	`false`	HTTPS only
`CookieHTTPOnly`	`bool`	`true`	HTTP only (no JS access)
`SameSite`	`http.SameSite`	`Lax`	SameSite policy
`MaxAge`	`time.Duration`	`24h`	Session lifetime

Examples

Basic Sessions

app.Use(session.New(session.Options{}))

app.Post("/login", func(c *mizu.Ctx) error {
    sess := session.Get(c)
    sess.Set("user", "john")
    sess.Set("role", "admin")
    return c.JSON(200, map[string]string{"status": "logged in"})
})

app.Use(session.New(session.Options{
    CookieName:   "my_app_session",
    CookieSecure: true,
    CookiePath:   "/",
    SameSite:     http.SameSiteStrictMode,
    MaxAge:       7 * 24 * time.Hour, // 1 week
}))

Custom Store

store := session.NewMemoryStore()

app.Use(session.WithStore(store, session.Options{}))

Session Operations

app.Get("/session", func(c *mizu.Ctx) error {
    sess := session.Get(c)

    // Set value
    sess.Set("key", "value")

    // Get value
    val := sess.Get("key")

    // Delete value
    sess.Delete("key")

    // Clear all values
    sess.Clear()

    // Get session ID
    id := sess.ID

    return c.Text(200, id)
})

Logout

app.Post("/logout", func(c *mizu.Ctx) error {
    sess := session.Get(c)
    sess.Clear()
    return c.JSON(200, map[string]string{"status": "logged out"})
})

API Reference

Functions

// New creates session middleware
func New(opts Options) mizu.Middleware

// WithStore creates middleware with custom store
func WithStore(store Store, opts Options) mizu.Middleware

// Get returns session from context
func Get(c *mizu.Ctx) *Session

// FromContext returns session from context (alias)
func FromContext(c *mizu.Ctx) *Session

// NewMemoryStore creates in-memory session store
func NewMemoryStore() *MemoryStore

Session Methods

type Session struct {
    ID string
}

func (s *Session) Set(key string, value any)
func (s *Session) Get(key string) any
func (s *Session) Delete(key string)
func (s *Session) Clear()

Store Interface

type Store interface {
    Get(id string) (*Session, error)
    Save(sess *Session) error
    Delete(id string) error
}

Technical Details

Session Lifecycle

The session middleware manages a complete lifecycle for each session:

Session Creation: When a new request arrives without a session cookie, a new session ID is generated using crypto/rand (32 bytes, 64 hex characters) and stored in the context
Cookie Management: Session cookies are set before the handler executes to ensure headers are properly sent
Data Persistence: Session data is saved to the store only when changes are detected via the changed flag
Cleanup: The memory store includes automatic cleanup that runs every 10 minutes to remove sessions inactive for more than 24 hours

Thread Safety

The Session struct uses sync.RWMutex for concurrent access:

Read operations (Get): Use read locks to allow multiple concurrent reads
Write operations (Set, Delete, Clear, Destroy): Use write locks for exclusive access
The changed flag tracks modifications to optimize store operations

Store Implementation

The package includes a MemoryStore implementation with:

Deep copying: Get returns a deep copy of session data to prevent external mutations
Background cleanup: Automatic goroutine removes expired sessions every 10 minutes
Concurrent safety: All operations are protected by sync.RWMutex

Session ID Generation

Session IDs are generated using:

crypto/rand.Read(32 bytes) -> hex.EncodeToString() = 64 character ID

This provides cryptographically secure random IDs suitable for production use.

Context Integration

Sessions are stored in the request context using a private contextKey{} struct, preventing collisions with other middleware or application code.

Security Considerations

Use HTTPS - Always set CookieSecure: true in production
HTTPOnly cookies - Keep default to prevent XSS access
Strict SameSite - Use SameSiteStrictMode for sensitive apps
Regenerate ID - After login to prevent session fixation
Set expiration - Don’t use infinite sessions

Best Practices

Use secure cookie settings in production
Store minimal data in sessions
Implement session store cleanup for expired sessions
Consider Redis or database store for distributed systems

Testing

The session middleware includes comprehensive test coverage for all operations:

Test Case	Description	Expected Behavior
`TestNew`	Set and get session value	Session values persist across requests with the same session cookie
`TestSession_Clear`	Clear all session values	All session values are removed after calling `Clear()`
`TestSession_Delete`	Delete specific session value	Individual session value is removed after calling `Delete(key)`
`TestWithStore`	Custom store integration	Session middleware works with custom Store implementations
`TestSession_CustomCookie`	Custom cookie configuration	Cookie settings (name, path, secure, SameSite) are applied correctly
`TestFromContext`	Context retrieval alias	`Get()` and `FromContext()` return the same session instance
`TestGenerateSessionID`	Session ID generation	Generates unique 64-character hex IDs without duplicates

jwt - Stateless token authentication
csrf - CSRF protection
secure - Security settings

​Overview

​Installation

​Quick Start

​Configuration

​Options

​Examples

​Basic Sessions

​Secure Cookie Settings

​Custom Store

​Session Operations

​Logout

​API Reference

​Functions

​Session Methods

​Store Interface

​Technical Details

​Session Lifecycle

​Thread Safety

​Store Implementation

​Session ID Generation

​Context Integration

​Security Considerations

​Best Practices

​Testing

​Related Middlewares