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

# Response Size

> Response size tracking middleware for monitoring and metrics.

## Overview

The `responsesize` middleware tracks response sizes for monitoring, logging, and metrics collection.

Use it when you need:

* Monitor response sizes
* Collect bandwidth metrics
* Detect response size anomalies

## Installation

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

## Quick Start

```go theme={null}
app := mizu.New()

app.Use(responsesize.New())
```

## Configuration

### Options

| Option    | Type                     | Default | Description   |
| --------- | ------------------------ | ------- | ------------- |
| `Handler` | `func(*mizu.Ctx, int64)` | `nil`   | Size callback |

## Examples

### Track in Context

```go theme={null}
app.Use(responsesize.New())
```

### With Callback

```go theme={null}
app.Use(responsesize.WithHandler(func(c *mizu.Ctx, size int64) {
    metrics.RecordResponseSize(c.Request().URL.Path, size)
}))
```

### Log Large Responses

```go theme={null}
app.Use(responsesize.WithHandler(func(c *mizu.Ctx, size int64) {
    if size > 1024*1024 { // > 1MB
        log.Printf("Large response: %s %d bytes", c.Request().URL.Path, size)
    }
}))
```

## API Reference

### Functions

```go theme={null}
// New creates response size middleware
func New() mizu.Middleware

// WithHandler creates with callback
func WithHandler(handler func(*mizu.Ctx, int64)) mizu.Middleware

// Get returns response size from context
func Get(c *mizu.Ctx) int64
```

## Technical Details

### Implementation Architecture

The middleware uses a wrapping pattern to intercept and track response writes:

1. **Context Storage**: Response size information is stored in the request context using a custom `contextKey` type for type-safe retrieval.

2. **Writer Wrapping**: The middleware wraps the original `http.ResponseWriter` with a `trackingWriter` that intercepts all `Write()` calls.

3. **Atomic Tracking**: Uses `sync/atomic` operations to safely track bytes written, ensuring thread-safe counting even with concurrent writes.

4. **Callback Mechanism**: After the response is fully written, an optional callback (`OnSize`) is invoked with the total byte count.

### Key Components

* **Info struct**: Holds the `bytesWritten` counter with an atomic accessor method `BytesWritten()`.
* **trackingWriter**: A wrapper around `http.ResponseWriter` that increments the byte counter on each write.
* **contextKey**: An empty struct used as a unique key for storing size info in the context.

### Flow

1. Create `Info` instance and store in context
2. Wrap response writer with `trackingWriter`
3. Execute next handler in chain
4. Invoke `OnSize` callback with final byte count
5. Restore original writer

## Best Practices

* Track alongside request sizes
* Set alerts for unusually large responses
* Use for bandwidth billing
* Monitor compression effectiveness

## Testing

The middleware includes comprehensive test coverage:

| Test Case                  | Description                       | Expected Behavior                                                        |
| -------------------------- | --------------------------------- | ------------------------------------------------------------------------ |
| `TestNew`                  | Basic middleware creation         | Middleware executes without errors and returns 200 OK                    |
| `TestWithOptions_Callback` | OnSize callback functionality     | Callback receives correct byte count (5 bytes for "12345")               |
| `TestBytesWritten`         | BytesWritten helper function      | Returns accurate byte count matching response body length                |
| `TestGet`                  | Info retrieval from context       | Get() returns valid Info instance from context                           |
| `TestWithCallback`         | WithCallback convenience function | Callback is invoked with correct size (3 bytes for "abc")                |
| `TestEmptyResponse`        | Empty response handling           | Reports 0 bytes for 204 No Content responses                             |
| `TestMultipleWrites`       | Multiple Write() calls            | Accumulates bytes across multiple writes ("firstsecondthird" = 16 bytes) |

## Related Middlewares

* [requestsize](/middlewares/requestsize) - Request size tracking
* [compress](/middlewares/compress) - Response compression
* [metrics](/middlewares/metrics) - Metrics collection