Skip to main content

​
Overview

The vary middleware manages the Vary HTTP header, telling caches which request headers affect response content. Use it when you need:
  • Proper cache control
  • Content negotiation
  • CDN configuration

​
Installation

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

​
Quick Start

app := mizu.New()

// Vary by Accept-Encoding
app.Use(vary.New("Accept-Encoding"))

​
Configuration

​
Options

OptionTypeDefaultDescription
Headers[]stringRequiredHeaders to vary by

​
Examples

​
Single Header

app.Use(vary.New("Accept-Encoding"))
// Vary: Accept-Encoding

​
Multiple Headers

app.Use(vary.New("Accept-Encoding", "Accept-Language", "Authorization"))
// Vary: Accept-Encoding, Accept-Language, Authorization

​
Common Patterns

// API with auth
app.Use(vary.New("Authorization"))

// Multilingual site
app.Use(vary.New("Accept-Language"))

// Compression
app.Use(vary.New("Accept-Encoding"))

​
API Reference

​
Functions

// New creates vary middleware
func New(headers ...string) mizu.Middleware

// Add adds to existing Vary header
func Add(c *mizu.Ctx, header string)

​
Technical Details

​
Implementation Overview

The vary middleware manages the Vary HTTP response header by:
  1. Header Management: Maintains a set of headers that affect response content
  2. Duplicate Prevention: Uses case-insensitive comparison to prevent duplicate headers
  3. Header Merging: Combines new Vary headers with existing ones from the response
  4. Execution Order: Processes after the handler executes to capture all Vary requirements

​
Key Functions

​
add(c *mizu.Ctx, headers ...string)

  • Adds headers to the Vary response header
  • Parses existing Vary header and creates a set for deduplication
  • Uses case-insensitive comparison (strings.ToLower)
  • Joins headers with comma-space separator

​
autoDetect(c *mizu.Ctx)

  • Automatically detects content negotiation headers from the request
  • Checks for: Accept, Accept-Encoding, Accept-Language
  • Only adds headers that are present in the request

​
Options Structure

type Options struct {
    Headers []string  // Explicit headers to add to Vary
    Auto    bool      // Enable automatic detection
}

​
Convenience Functions

The middleware provides several preset functions:
  • AcceptEncoding(): Adds Accept-Encoding to Vary
  • Accept(): Adds Accept to Vary
  • AcceptLanguage(): Adds Accept-Language to Vary
  • Origin(): Adds Origin to Vary (useful for CORS)
  • All(): Adds common headers: Accept, Accept-Encoding, Accept-Language
  • Auto(): Enables automatic header detection

​
Best Practices

  • Include all headers that affect response
  • Use with compression middleware
  • Consider CDN caching implications
  • Don’t over-vary (reduces cache effectiveness)

​
Testing

The middleware includes comprehensive tests covering various scenarios:
Test CaseDescriptionExpected Behavior
TestNewBasic middleware with multiple headersSets Vary header with Accept-Encoding and Accept-Language
TestNoDuplicatesSame header specified twicePrevents duplicates; header appears only once in Vary
TestWithOptions_AutoAuto-detection with request headersAutomatically adds Accept and Accept-Encoding based on request
TestAddHelper function within handlerAdds custom header X-Custom-Header to Vary
TestAcceptEncodingAcceptEncoding convenience functionSets Vary header to Accept-Encoding
TestAcceptAccept convenience functionSets Vary header to Accept
TestAcceptLanguageAcceptLanguage convenience functionSets Vary header to Accept-Language
TestOriginOrigin convenience functionSets Vary header to Origin
TestAllAll convenience functionSets Vary header with Accept, Accept-Encoding, and Accept-Language
TestAutoAuto convenience function with request headerAuto-detects and adds Accept-Language when present in request
TestCombineWithExistingCombining with existing Vary headerPreserves existing X-Custom and adds Accept-Encoding