Skip to main content

​
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

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

​
Quick Start

app := mizu.New()

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

​
Configuration

​
Options

OptionTypeDefaultDescription
FilestringRequiredPath to favicon file
Data[]bytenilFavicon data (alternative to file)
CacheControlstring"public, max-age=31536000"Cache-Control header

​
Examples

​
From File

app.Use(favicon.New("./static/favicon.ico"))

​
From Embedded Data

//go:embed favicon.ico
var faviconData []byte

app.Use(favicon.FromData(faviconData))

​
Custom Cache Control

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

​
Disable Favicon

// Return empty response for favicon requests
app.Use(favicon.Disabled())

​
API Reference

​
Functions

// 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 CaseDescriptionExpected Behavior
TestNew - serve faviconServes favicon from file pathReturns 200 OK with correct Content-Type (image/png)
TestNew - other paths pass throughNon-favicon paths are not interceptedRequest passes to next handler, returns route response
TestFromDataServes favicon from byte dataReturns 200 OK with favicon data
TestWithOptions_CustomURL - custom url servesServes favicon at custom URL pathReturns 200 OK at /icon.png
TestWithOptions_CustomURL - default url does not serveDefault path not served with custom URLReturns 404 at /favicon.ico
TestWithOptions_FSServes favicon from fs.FS interfaceReturns 200 OK with data from MapFS
TestWithOptions_MaxAgeCustom cache control max-ageSets Cache-Control: public, max-age=3600
TestWithOptions_HeadMethodHEAD request handlingReturns 200 OK with headers but no body
TestEmptyEmpty middleware returns no contentReturns 204 No Content for favicon requests
TestRedirectRedirects favicon to external URLReturns 301 with Location header to CDN
TestSVG - favicon.ico serves SVGSVG data served at .ico pathReturns 200 OK with image/svg+xml content type
TestSVG - favicon.svg serves SVGSVG data served at .svg pathReturns 200 OK at /favicon.svg
TestWithOptions_NoDataNo data provided in optionsReturns 204 No Content
  • static - Static file serving
  • spa - Single Page Application
  • cache - Cache headers