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

# Filter

> Request filtering middleware for conditional routing.

## Overview

The `filter` middleware provides request filtering capabilities, allowing or blocking requests based on custom conditions.

Use it when you need:

* Block specific requests
* Conditional access
* Request validation

## Installation

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

## Quick Start

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

// Block requests without API key
app.Use(filter.New(func(c *mizu.Ctx) bool {
    return c.Request().Header.Get("X-API-Key") != ""
}))
```

## Configuration

### Options

| Option | Type | Default | Description |
| - | - | - | - |
| `Allow` | `func(*mizu.Ctx) bool` | Required | Allow function |
| `ErrorHandler` | `func(*mizu.Ctx) error` | 403 | Custom rejection |

## Examples

### Allow Function

```go theme={null}
app.Use(filter.New(func(c *mizu.Ctx) bool {
    // Allow if condition is true
    return isAllowed(c)
}))
```

### Block by User-Agent

```go theme={null}
app.Use(filter.New(func(c *mizu.Ctx) bool {
    ua := c.Request().UserAgent()
    return !strings.Contains(ua, "BadBot")
}))
```

### Custom Error

```go theme={null}
app.Use(filter.WithOptions(filter.Options{
    Allow: allowFunc,
    ErrorHandler: func(c *mizu.Ctx) error {
        return c.JSON(403, map[string]string{
            "error": "Access denied",
        })
    },
}))
```

### Combine Conditions

```go theme={null}
app.Use(filter.New(func(c *mizu.Ctx) bool {
    hasKey := c.Request().Header.Get("X-API-Key") != ""
    isGet := c.Request().Method == http.MethodGet
    return hasKey || isGet
}))
```

## API Reference

### Functions

```go theme={null}
// New creates filter middleware
func New(allow func(*mizu.Ctx) bool) mizu.Middleware

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

// Block creates blocking filter
func Block(block func(*mizu.Ctx) bool) mizu.Middleware
```

## Technical Details

The filter middleware provides comprehensive request filtering through multiple criteria:

### Pattern Matching

The middleware uses glob-to-regex conversion for flexible pattern matching:

* `*` - Matches any characters except path separators (e.g., `/api/*` matches `/api/users` but not `/api/users/1`)
* `**` - Matches any characters including path separators (e.g., `/admin/**` matches `/admin/deep/nested/path`)
* `?` - Matches exactly one character

Special regex characters (`.`, `+`, `^`, `$`, `|`, etc.) are automatically escaped.

### Filter Evaluation Order

Filters are evaluated in the following order:

1. **HTTP Methods** - Check if method is in AllowedMethods (if configured)
2. **Blocked Hosts** - Check if host is in BlockedHosts (takes precedence over allowed)
3. **Allowed Hosts** - Check if host is in AllowedHosts (if configured)
4. **Blocked Paths** - Check if path matches BlockedPaths patterns (takes precedence over allowed)
5. **Allowed Paths** - Check if path matches AllowedPaths patterns (if configured)
6. **Blocked User Agents** - Check if UA matches BlockedUserAgents patterns (takes precedence over allowed)
7. **Allowed User Agents** - Check if UA matches AllowedUserAgents patterns (if configured)
8. **Custom Filter** - Execute CustomFilter function if provided

If any check fails, the request is blocked and the OnBlock handler is called (or returns 403 Forbidden by default).

### Host Normalization

Host names are normalized by:

* Converting to lowercase for case-insensitive matching
* Stripping port numbers (e.g., `example.com:8080` becomes `example.com`)

### Performance Optimization

* HTTP methods are stored in a map for O(1) lookup
* Hosts are stored in maps for O(1) lookup
* Glob patterns are compiled to regex once during initialization
* All patterns are pre-compiled to avoid runtime compilation overhead

## Best Practices

* Keep filter logic simple
* Log blocked requests
* Use descriptive error messages
* Combine with rate limiting

## Testing

The filter middleware includes comprehensive test coverage for all filtering scenarios:

| Test Case | Description | Expected Behavior |
| - | - | - |
| TestNew | Creates filter with default options | Allows all requests to pass through |
| TestMethods (allowed) | Filters by HTTP method - allowed method | Returns 200 OK for GET request |
| TestMethods (blocked) | Filters by HTTP method - blocked method | Returns 403 Forbidden for DELETE request |
| TestBlockPaths (allowed) | Blocks specific path patterns - allowed path | Returns 200 OK for root path |
| TestBlockPaths (admin) | Blocks admin paths with `*` wildcard | Returns 403 Forbidden for /admin/users |
| TestBlockPaths (deep) | Blocks deep paths with `**` wildcard | Returns 403 Forbidden for /internal/deep/path |
| TestPaths (allowed) | Allows only specific path patterns | Returns 200 OK for /api/users |
| TestPaths (blocked) | Blocks paths not in allow list | Returns 403 Forbidden for /secret |
| TestHosts (allowed) | Filters by hostname - allowed host | Returns 200 OK for example.com |
| TestHosts (blocked) | Filters by hostname - blocked host | Returns 403 Forbidden for evil.com |
| TestBlockUserAgents (allowed) | Blocks specific user agents - allowed UA | Returns 200 OK for Mozilla/5.0 |
| TestBlockUserAgents (curl) | Blocks curl user agent pattern | Returns 403 Forbidden for curl/7.68.0 |
| TestBlockUserAgents (bot) | Blocks bot user agent pattern | Returns 403 Forbidden for Googlebot/2.1 |
| TestCustomFilter (passes) | Custom filter function returns true | Returns 200 OK when X-Secret header is valid |
| TestCustomFilter (fails) | Custom filter function returns false | Returns 403 Forbidden when X-Secret header missing |
| TestCustomOnBlock | Custom OnBlock handler | Returns 405 with JSON error message |
| TestBlockedHosts (allowed) | Blocks specific hosts - allowed host | Returns 200 OK for example.com |
| TestBlockedHosts (blocked) | Blocks specific hosts - blocked host | Returns 403 Forbidden for spam.com |
| TestGlobToRegex (/api/\*) | Glob pattern with single wildcard | Matches /api/users but not /api/users/1 |
| TestGlobToRegex (/api/\*\*) | Glob pattern with double wildcard | Matches /api/users/1 (nested paths) |
| TestGlobToRegex (\*.txt) | File extension pattern | Matches file.txt but not file.json |
| TestGlobToRegex (/a?c) | Question mark single char match | Matches /abc |
| TestGlobToRegex (/a.b) | Dot character escaping | Matches literal /a.b |

## Related Middlewares

* [ipfilter](https://docs.go-mizu.dev/middlewares/ipfilter.md) - IP-based filtering
* [keyauth](https://docs.go-mizu.dev/middlewares/keyauth.md) - API key auth
* [rbac](https://docs.go-mizu.dev/middlewares/rbac.md) - Role-based access


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.