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

# Keep-Alive

> Connection keep-alive control middleware for HTTP connections.

## Overview

The `keepalive` middleware controls HTTP keep-alive behavior, managing connection persistence for performance optimization.

Use it when you need:

* Connection persistence control
* Resource management
* Performance optimization

## Installation

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

## Quick Start

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

// Enable keep-alive with defaults
app.Use(keepalive.New())
```

## Configuration

### Options

| Option        | Type            | Default | Description                 |
| ------------- | --------------- | ------- | --------------------------- |
| `Enabled`     | `bool`          | `true`  | Enable keep-alive           |
| `MaxRequests` | `int`           | `100`   | Max requests per connection |
| `Timeout`     | `time.Duration` | `5s`    | Keep-alive timeout          |

## Examples

### Enable Keep-Alive

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

### Custom Settings

```go theme={null}
app.Use(keepalive.New(keepalive.Options{
    Timeout:     10 * time.Second,
    MaxRequests: 200,
}))
```

### Disable Keep-Alive

```go theme={null}
app.Use(keepalive.New(keepalive.Options{
    Enabled: false,
}))
```

### Per-Route Control

```go theme={null}
// Disable for long-polling
app.Get("/events", handler, keepalive.Disable())

// Enable for API
app.Get("/api", handler, keepalive.New())
```

## API Reference

### Functions

```go theme={null}
// New creates keep-alive middleware
func New(opts ...Options) mizu.Middleware

// Disable creates middleware that disables keep-alive
func Disable() mizu.Middleware
```

## HTTP Headers

```
Connection: keep-alive
Keep-Alive: timeout=5, max=100
```

## Technical Details

### Implementation Overview

The keepalive middleware manages HTTP connection persistence by controlling the `Connection` and `Keep-Alive` headers. The middleware follows a request-response flow:

1. **Configuration Initialization**: Default values are set during middleware creation (60s timeout, 100 max requests)
2. **Request Processing**: For each incoming request, the middleware:
   * Checks if keep-alive is disabled via `DisableKeepAlive` option
   * Inspects the client's `Connection` header to detect if the client requested connection closure
   * Sets appropriate response headers based on configuration and client preferences
3. **Header Management**: The middleware sets:
   * `Connection: keep-alive` to indicate persistent connection support
   * `Keep-Alive: timeout={seconds}, max={requests}` to specify connection parameters

### Key Components

* **Options struct**: Configures timeout duration, maximum requests per connection, and enable/disable flag
* **Default values**: 60 seconds timeout, 100 maximum requests when not specified
* **Client negotiation**: Respects client's `Connection: close` header to gracefully close connections
* **Helper functions**: Provides `Disable()`, `WithTimeout()`, and `WithMax()` for common configurations

### Header Format

The `Keep-Alive` header uses the format: `timeout={seconds}, max={requests}` where:

* `timeout`: Duration in seconds that the connection should remain open
* `max`: Maximum number of requests allowed on this connection

## Best Practices

* Use for high-traffic APIs
* Set reasonable timeouts
* Monitor connection counts
* Consider disabling for long-polling

## Testing

The keepalive middleware includes comprehensive test coverage:

| Test Case                       | Description                       | Expected Behavior                                                                         |
| ------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------- |
| `TestNew`                       | Default middleware creation       | Sets `Connection: keep-alive` and `Keep-Alive` headers with default values (60s, 100 max) |
| `TestWithOptions_CustomTimeout` | Custom timeout configuration      | Sets `Keep-Alive: timeout=120, max=100` when 120s timeout is specified                    |
| `TestWithOptions_CustomMax`     | Custom max requests configuration | Sets `Keep-Alive: timeout=60, max=500` when 500 max requests is specified                 |
| `TestWithOptions_Disable`       | Disable keep-alive option         | Sets `Connection: close` header when `DisableKeepAlive` is true                           |
| `TestWithOptions_ClientClose`   | Client requests connection close  | Honors client's `Connection: close` header and responds with `Connection: close`          |
| `TestDisable`                   | Disable() helper function         | Sets `Connection: close` header using convenience function                                |
| `TestWithTimeout`               | WithTimeout() helper function     | Sets `Keep-Alive: timeout=30, max=100` when using 30s timeout helper                      |
| `TestWithMax`                   | WithMax() helper function         | Sets `Keep-Alive: timeout=60, max=200` when using 200 max requests helper                 |

## Related Middlewares

* [timeout](/middlewares/timeout) - Request timeout
* [maxconns](/middlewares/maxconns) - Connection limits