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

# Body Dump

> Request/response body dumping middleware for debugging.

## Overview

The `bodydump` middleware captures and logs request and response bodies for debugging purposes.

Use it when you need:

* Debug API requests
* Log request/response pairs
* Troubleshoot integrations

## Installation

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

## Quick Start

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

app.Use(bodydump.New(func(c *mizu.Ctx, reqBody, resBody []byte) {
    log.Printf("Request: %s", reqBody)
    log.Printf("Response: %s", resBody)
}))
```

## Configuration

### Options

| Option             | Type                              | Default  | Description              |
| ------------------ | --------------------------------- | -------- | ------------------------ |
| `Request`          | `bool`                            | `true`   | Dump request body        |
| `Response`         | `bool`                            | `true`   | Dump response body       |
| `MaxSize`          | `int64`                           | `64KB`   | Max body size to capture |
| `Handler`          | `func(*mizu.Ctx, []byte, []byte)` | Required | Dump callback            |
| `SkipPaths`        | `[]string`                        | `nil`    | Paths to skip            |
| `SkipContentTypes` | `[]string`                        | `nil`    | Content types to skip    |

## Examples

### Basic Logging

```go theme={null}
app.Use(bodydump.New(func(c *mizu.Ctx, req, res []byte) {
    log.Printf("[%s %s] Req: %s Res: %s",
        c.Request().Method,
        c.Request().URL.Path,
        req, res)
}))
```

### Skip Large Bodies

```go theme={null}
app.Use(bodydump.WithOptions(bodydump.Options{
    Handler: dumpHandler,
    MaxSize: 1024, // Only dump first 1KB
}))
```

### Skip Specific Paths

```go theme={null}
app.Use(bodydump.WithOptions(bodydump.Options{
    Handler:   dumpHandler,
    SkipPaths: []string{"/health", "/metrics"},
}))
```

### Skip Content Types

```go theme={null}
app.Use(bodydump.WithOptions(bodydump.Options{
    Handler:          dumpHandler,
    SkipContentTypes: []string{"image/jpeg", "image/png"},
}))
```

### Request Only

```go theme={null}
app.Use(bodydump.RequestOnly(func(c *mizu.Ctx, body []byte) {
    log.Printf("Request: %s", body)
}))
```

### Response Only

```go theme={null}
app.Use(bodydump.ResponseOnly(func(c *mizu.Ctx, body []byte) {
    log.Printf("Response: %s", body)
}))
```

### JSON Formatting

```go theme={null}
app.Use(bodydump.New(func(c *mizu.Ctx, req, res []byte) {
    entry := map[string]any{
        "method":   c.Request().Method,
        "path":     c.Request().URL.Path,
        "request":  string(req),
        "response": string(res),
    }
    json.NewEncoder(os.Stdout).Encode(entry)
}))
```

## API Reference

### Functions

```go theme={null}
// New creates body dump middleware
func New(handler func(*mizu.Ctx, []byte, []byte)) mizu.Middleware

// WithOptions creates with configuration
func WithOptions(opts Options) mizu.Middleware

// RequestOnly dumps only request bodies
func RequestOnly(handler func(*mizu.Ctx, []byte)) mizu.Middleware

// ResponseOnly dumps only response bodies
func ResponseOnly(handler func(*mizu.Ctx, []byte)) mizu.Middleware
```

## Technical Details

### Implementation Overview

The bodydump middleware uses a capture mechanism to intercept and store request/response bodies:

1. **Request Body Capture**: Reads the request body using `io.LimitReader` to respect the `MaxSize` limit, then restores it using `io.NopCloser` with a bytes reader so downstream handlers can still access it.

2. **Response Body Capture**: Implements a custom `responseCapture` wrapper that implements `http.ResponseWriter`. It intercepts `Write()` calls to capture the response body up to the configured `MaxSize` while still writing to the original response writer.

3. **Filtering Mechanisms**:
   * **Path Filtering**: Uses a map lookup for O(1) skip path checks
   * **Content-Type Filtering**: Skips configured content types to avoid dumping binary data
   * **Size Limiting**: Enforces maximum capture size on both request (via `io.LimitReader`) and response (via byte counting)

### Default Values

* `MaxSize`: 64KB (65,536 bytes)
* `Request`: true (enabled)
* `Response`: true (enabled)

### Performance Considerations

* Path and content-type skipping uses hash maps for efficient lookups
* Body capture is limited by `MaxSize` to prevent memory issues
* Request body is read once and restored for handler use
* Response capture adds minimal overhead as it writes through to the original writer

## Security Warning

Body dump may capture sensitive data. Never use in production without proper filtering.

## Best Practices

* Only enable in development/debugging
* Filter sensitive data
* Set reasonable size limits
* Skip high-volume endpoints

## Testing

The bodydump middleware includes comprehensive test coverage for all major functionality:

| Test Case                      | Description                                    | Expected Behavior                                                  |
| ------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------ |
| `TestNew`                      | Basic middleware creation with default options | Captures both request and response bodies correctly                |
| `TestWithOptions_RequestOnly`  | Request-only dumping configuration             | Dumps only request body, response body is empty                    |
| `TestWithOptions_ResponseOnly` | Response-only dumping configuration            | Dumps only response body, request body is empty                    |
| `TestWithOptions_MaxSize`      | Maximum size limit enforcement                 | Request body is truncated to MaxSize bytes (5 bytes in test)       |
| `TestWithOptions_SkipPaths`    | Path skipping functionality                    | Handler is not called for paths in SkipPaths array                 |
| `TestRequestOnly`              | RequestOnly helper function                    | Captures only request body using simplified API                    |
| `TestResponseOnly`             | ResponseOnly helper function                   | Captures only response body using simplified API                   |
| `TestBodyPreserved`            | Request body preservation                      | Request body remains readable by downstream handlers after dumping |

## Related Middlewares

* [logger](/middlewares/logger) - Request logging
* [audit](/middlewares/audit) - Audit logging
* [requestlog](/middlewares/requestlog) - Detailed logging