> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Session

> Server-side session management middleware with cookie-based tracking.

## 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

```go theme={null}
import "github.com/go-mizu/mizu/middlewares/session"
```

## Quick Start

```go theme={null}
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

```go theme={null}
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"})
})
```

### Secure Cookie Settings

```go theme={null}
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

```go theme={null}
store := session.NewMemoryStore()

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

### Session Operations

```go theme={null}
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

```go theme={null}
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

```go theme={null}
// 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

```go theme={null}
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

```go theme={null}
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:

1. **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
2. **Cookie Management**: Session cookies are set before the handler executes to ensure headers are properly sent
3. **Data Persistence**: Session data is saved to the store only when changes are detected via the `changed` flag
4. **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:

```go theme={null}
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

1. **Use HTTPS** - Always set `CookieSecure: true` in production
2. **HTTPOnly cookies** - Keep default to prevent XSS access
3. **Strict SameSite** - Use `SameSiteStrictMode` for sensitive apps
4. **Regenerate ID** - After login to prevent session fixation
5. **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             |

## Related Middlewares

* [jwt](/middlewares/jwt) - Stateless token authentication
* [csrf](/middlewares/csrf) - CSRF protection
* [secure](/middlewares/secure) - Security settings