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

# Favicon

> Favicon serving middleware for efficient favicon.ico handling.

## Overview

The `favicon` middleware serves favicon files efficiently, caching them in memory and handling HEAD requests properly. It prevents favicon requests from reaching your application routes.

Use it when you need:

* Serve favicon from memory
* Prevent favicon 404 logs
* Custom favicon handling

## Installation

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

## Quick Start

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

// Serve favicon from file
app.Use(favicon.New("./static/favicon.ico"))
```

## Configuration

### Options

| Option         | Type     | Default                      | Description                        |
| -------------- | -------- | ---------------------------- | ---------------------------------- |
| `File`         | `string` | Required                     | Path to favicon file               |
| `Data`         | `[]byte` | `nil`                        | Favicon data (alternative to file) |
| `CacheControl` | `string` | `"public, max-age=31536000"` | Cache-Control header               |

## Examples

### From File

```go theme={null}
app.Use(favicon.New("./static/favicon.ico"))
```

### From Embedded Data

```go theme={null}
//go:embed favicon.ico
var faviconData []byte

app.Use(favicon.FromData(faviconData))
```

### Custom Cache Control

```go theme={null}
app.Use(favicon.WithOptions(favicon.Options{
    File:         "./static/favicon.ico",
    CacheControl: "public, max-age=86400", // 1 day
}))
```

### Disable Favicon

```go theme={null}
// Return empty response for favicon requests
app.Use(favicon.Disabled())
```

## API Reference

### Functions

```go theme={null}
// New creates favicon middleware from file
func New(file string) mizu.Middleware

// FromData creates middleware from byte data
func FromData(data []byte) mizu.Middleware

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

// Disabled returns empty response for favicon requests
func Disabled() mizu.Middleware
```

## Behavior

* Caches favicon in memory after first read
* Sets proper Content-Type (image/x-icon)
* Handles both GET and HEAD requests
* Only matches exact `/favicon.ico` path

## Technical Details

### Implementation

The favicon middleware implements efficient favicon serving with the following characteristics:

1. **Memory Caching**: Favicon data is loaded once during middleware initialization and cached in memory for the lifetime of the application.

2. **Content Type Detection**: Uses `http.DetectContentType()` to automatically detect the content type from the favicon data. Falls back to `image/x-icon` if detection returns `application/octet-stream` or `text/plain`.

3. **File System Support**: Supports three data sources:
   * Direct file path using `os.ReadFile`
   * Embedded data using `[]byte`
   * File system interface (`fs.FS`) for advanced use cases

4. **Request Handling**:
   * Only processes requests matching the configured URL path (default: `/favicon.ico`)
   * Only handles GET and HEAD methods, passes other methods to next handler
   * Sets appropriate headers: Content-Type, Content-Length, and Cache-Control
   * HEAD requests return headers without body

5. **Special Behaviors**:
   * Empty configuration (no data) returns HTTP 204 No Content
   * SVG middleware supports both `/favicon.ico` and `/favicon.svg` paths
   * Redirect middleware returns HTTP 301 Moved Permanently

### Performance Considerations

* Favicon is loaded once at startup (panic on file errors)
* No disk I/O during request handling
* Minimal memory allocation per request
* Early path matching prevents unnecessary processing

## Best Practices

* Use embedded data for portable deployments
* Set long cache duration for production
* Place before other middleware to avoid unnecessary processing

## Testing

The favicon middleware includes comprehensive test coverage for all features:

| Test Case                                                | Description                             | Expected Behavior                                      |
| -------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------ |
| `TestNew` - serve favicon                                | Serves favicon from file path           | Returns 200 OK with correct Content-Type (image/png)   |
| `TestNew` - other paths pass through                     | Non-favicon paths are not intercepted   | Request passes to next handler, returns route response |
| `TestFromData`                                           | Serves favicon from byte data           | Returns 200 OK with favicon data                       |
| `TestWithOptions_CustomURL` - custom url serves          | Serves favicon at custom URL path       | Returns 200 OK at `/icon.png`                          |
| `TestWithOptions_CustomURL` - default url does not serve | Default path not served with custom URL | Returns 404 at `/favicon.ico`                          |
| `TestWithOptions_FS`                                     | Serves favicon from fs.FS interface     | Returns 200 OK with data from MapFS                    |
| `TestWithOptions_MaxAge`                                 | Custom cache control max-age            | Sets `Cache-Control: public, max-age=3600`             |
| `TestWithOptions_HeadMethod`                             | HEAD request handling                   | Returns 200 OK with headers but no body                |
| `TestEmpty`                                              | Empty middleware returns no content     | Returns 204 No Content for favicon requests            |
| `TestRedirect`                                           | Redirects favicon to external URL       | Returns 301 with Location header to CDN                |
| `TestSVG` - favicon.ico serves SVG                       | SVG data served at .ico path            | Returns 200 OK with `image/svg+xml` content type       |
| `TestSVG` - favicon.svg serves SVG                       | SVG data served at .svg path            | Returns 200 OK at `/favicon.svg`                       |
| `TestWithOptions_NoData`                                 | No data provided in options             | Returns 204 No Content                                 |

## Related Middlewares

* [static](/middlewares/static) - Static file serving
* [spa](/middlewares/spa) - Single Page Application
* [cache](/middlewares/cache) - Cache headers