Filter

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.

​

Overview

• Block specific requests
• Conditional access
• Request validation

​

Installation

import "github.com/go-mizu/mizu/middlewares/filter"

​

Quick Start

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

​

Examples

​

Allow Function

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

​

Block by User-Agent

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

​

Custom Error

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

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

// 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

​

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

​

Filter Evaluation 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

​

Host Normalization

• 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

​

Related Middlewares

• ipfilter - IP-based filtering
• keyauth - API key auth
• rbac - Role-based access