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

# Header

> Request and response header manipulation middleware.

## Overview

The `header` middleware provides flexible request and response header manipulation. Add, modify, or remove headers for security, caching, or custom requirements.

## Installation

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

## Quick Start

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

// Set response header
app.Use(header.Set("X-Powered-By", "Mizu"))
```

## Functions

### Response Headers

| Function          | Description                   |
| ----------------- | ----------------------------- |
| `Set(key, value)` | Set response header           |
| `New(headers)`    | Set multiple response headers |
| `Remove(keys...)` | Remove response headers       |

### Request Headers

| Function                 | Description            |
| ------------------------ | ---------------------- |
| `SetRequest(key, value)` | Set request header     |
| `RemoveRequest(keys...)` | Remove request headers |

### Security Headers

| Function                            | Header                      |
| ----------------------------------- | --------------------------- |
| `XSSProtection()`                   | X-XSS-Protection            |
| `NoSniff()`                         | X-Content-Type-Options      |
| `FrameDeny()`                       | X-Frame-Options: DENY       |
| `FrameSameOrigin()`                 | X-Frame-Options: SAMEORIGIN |
| `HSTS(maxAge, subdomains, preload)` | Strict-Transport-Security   |
| `CSP(policy)`                       | Content-Security-Policy     |
| `ReferrerPolicy(policy)`            | Referrer-Policy             |
| `PermissionsPolicy(policy)`         | Permissions-Policy          |

### Content Headers

| Function | Content-Type     |
| -------- | ---------------- |
| `JSON()` | application/json |
| `HTML()` | text/html        |
| `Text()` | text/plain       |
| `XML()`  | application/xml  |

## Examples

### Set Single Header

```go theme={null}
app.Use(header.Set("X-Custom-Header", "value"))
```

### Set Multiple Headers

```go theme={null}
app.Use(header.New(map[string]string{
    "X-App-Name":    "MyApp",
    "X-App-Version": "1.0.0",
}))
```

### Remove Headers

```go theme={null}
// Remove sensitive headers
app.Use(header.Remove("Server", "X-Powered-By"))
```

### Security Headers

```go theme={null}
app.Use(header.XSSProtection())
app.Use(header.NoSniff())
app.Use(header.FrameDeny())
```

### HSTS

```go theme={null}
app.Use(header.HSTS(31536000, true, true)) // 1 year, subdomains, preload
```

### Content Security Policy

```go theme={null}
app.Use(header.CSP("default-src 'self'; script-src 'self' cdn.example.com"))
```

### Full Configuration

```go theme={null}
app.Use(header.WithOptions(header.Options{
    Response: map[string]string{
        "X-Frame-Options":        "DENY",
        "X-Content-Type-Options": "nosniff",
    },
    ResponseRemove: []string{"Server"},
    Request: map[string]string{
        "X-Request-Source": "web",
    },
}))
```

## API Reference

```go theme={null}
func Set(key, value string) mizu.Middleware
func SetRequest(key, value string) mizu.Middleware
func New(headers map[string]string) mizu.Middleware
func Remove(keys ...string) mizu.Middleware
func RemoveRequest(keys ...string) mizu.Middleware
func WithOptions(opts Options) mizu.Middleware
```

## Technical Details

### Architecture

The header middleware is built on the `WithOptions` function, which serves as the core implementation. All other functions (`Set`, `New`, `Remove`, etc.) are convenience wrappers that delegate to `WithOptions` with specific configurations.

### Options Structure

```go theme={null}
type Options struct {
    Request        map[string]string // Request headers to set
    Response       map[string]string // Response headers to set
    RequestRemove  []string          // Request headers to remove
    ResponseRemove []string          // Response headers to remove
}
```

### Execution Flow

1. **Request Phase** (before handler):
   * Sets request headers from `Options.Request`
   * Removes request headers from `Options.RequestRemove`
   * Sets response headers from `Options.Response`

2. **Handler Execution**: Calls the next middleware/handler

3. **Response Phase** (after handler):
   * Removes response headers from `Options.ResponseRemove`

### Implementation Notes

* Request headers are set before the handler executes, making them available to downstream handlers
* Response headers are set before the handler but can be overridden by the handler
* Response header removal happens after the handler executes to ensure headers set by the handler are properly removed
* The middleware uses a custom `itoa` function for integer-to-string conversion to avoid unnecessary allocations in HSTS header generation

### Best Practices

* Use `WithOptions` for complex configurations involving multiple header operations
* Use convenience functions (`Set`, `Remove`, etc.) for simple single-header operations
* Set security headers at the application level rather than per-route
* Remove sensitive headers (e.g., `Server`, `X-Powered-By`) to avoid information disclosure
* Chain multiple header middlewares when you need different headers for different routes

## Testing

The header middleware includes comprehensive test coverage for all functions:

| Test Case                        | Description                                 | Expected Behavior                                                                      |
| -------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------- |
| `TestNew`                        | Tests setting multiple response headers     | Headers `X-Custom` and `X-Another` are set in response                                 |
| `TestWithOptions_RequestHeaders` | Tests setting request headers               | Header `X-Injected` is available in request context                                    |
| `TestWithOptions_RemoveHeaders`  | Tests removing request and response headers | Request header `X-Remove-Me` and response header `X-Server` are removed                |
| `TestSet`                        | Tests setting a single response header      | Header `X-Test` is set in response                                                     |
| `TestSetRequest`                 | Tests setting a single request header       | Header `X-Request-Custom` is available in request                                      |
| `TestRemove`                     | Tests removing multiple response headers    | Headers `Server` and `X-Powered-By` are removed from response                          |
| `TestRemoveRequest`              | Tests removing request headers              | Header `Cookie` is removed from request                                                |
| `TestXSSProtection`              | Tests XSS protection header                 | Header `X-XSS-Protection` is set to `1; mode=block`                                    |
| `TestNoSniff`                    | Tests content type sniffing protection      | Header `X-Content-Type-Options` is set to `nosniff`                                    |
| `TestFrameDeny`                  | Tests frame options deny                    | Header `X-Frame-Options` is set to `DENY`                                              |
| `TestFrameSameOrigin`            | Tests frame options same origin             | Header `X-Frame-Options` is set to `SAMEORIGIN`                                        |
| `TestHSTS`                       | Tests HTTP Strict Transport Security        | Header `Strict-Transport-Security` is set with max-age, includeSubDomains, and preload |
| `TestCSP`                        | Tests Content Security Policy               | Header `Content-Security-Policy` is set with custom policy                             |
| `TestReferrerPolicy`             | Tests referrer policy                       | Header `Referrer-Policy` is set to `strict-origin`                                     |
| `TestJSON`                       | Tests JSON content type                     | Header `Content-Type` is set to `application/json; charset=utf-8`                      |
| `TestHTML`                       | Tests HTML content type                     | Header `Content-Type` is set to `text/html; charset=utf-8`                             |
| `TestText`                       | Tests text content type                     | Header `Content-Type` is set to `text/plain; charset=utf-8`                            |
| `TestXML`                        | Tests XML content type                      | Header `Content-Type` is set to `application/xml; charset=utf-8`                       |

## Related Middlewares

* [helmet](/middlewares/helmet) - Comprehensive security headers