Surrogate

​

Overview

• CDN cache purging
• Edge cache control
• Cache tagging

​

Installation

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

​

Quick Start

app := mizu.New()

app.Use(surrogate.New())

app.Get("/article/:id", func(c *mizu.Ctx) error {
    surrogate.Key(c, "article-"+c.Param("id"))
    return c.JSON(200, article)
})

​

Configuration

​

Options

​

Examples

​

Set Surrogate Keys

app.Get("/article/:id", func(c *mizu.Ctx) error {
    surrogate.Key(c, "article-"+c.Param("id"))
    surrogate.Key(c, "articles")
    return c.JSON(200, article)
})
// Surrogate-Key: article-123 articles

​

Surrogate Control

app.Use(surrogate.WithOptions(surrogate.Options{
    MaxAge:               time.Hour,
    StaleWhileRevalidate: 10 * time.Minute,
}))
// Surrogate-Control: max-age=3600, stale-while-revalidate=600

​

Per-Route Control

app.Get("/dynamic", func(c *mizu.Ctx) error {
    surrogate.Control(c, "no-store")
    return c.JSON(200, data)
})

app.Get("/static", func(c *mizu.Ctx) error {
    surrogate.Control(c, "max-age=86400")
    return c.JSON(200, data)
})

​

API Reference

​

Functions

// New creates surrogate middleware
func New() mizu.Middleware

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

// Key adds surrogate key
func Key(c *mizu.Ctx, keys ...string)

// Control sets surrogate control
func Control(c *mizu.Ctx, control string)

​

CDN Integration

​

Fastly

Surrogate-Key: article-123 homepage
Surrogate-Control: max-age=3600

​

Varnish

​

Technical Details

​

Architecture

• Context Storage: Uses Go’s context.Context to store surrogate keys during request processing
• Keys Structure: Maintains a Keys type that holds a slice of string keys
• Header Management: Automatically sets headers after handler execution using middleware pattern

​

Implementation Details

1. Initialization: The middleware creates a Keys instance and stores it in the request context
2. Default Keys: If configured, default keys are added to every response
3. Handler Execution: The next handler in the chain executes, allowing route handlers to add keys via Add()
4. Header Setting: After handler completion, the middleware:
   • Joins all keys with spaces and sets the configured header (default: Surrogate-Key)
   • Builds and sets the Surrogate-Control header based on options (MaxAge, StaleWhileRevalidate, StaleIfError)

​

Control Header Format

• max-age=N: Set via Options.MaxAge
• stale-while-revalidate=N: Set via Options.StaleWhileRevalidate
• stale-if-error=N: Set via Options.StaleIfError

​

CDN Presets

• Fastly(): Uses Surrogate-Key header
• Varnish(): Uses xkey header
• CloudFront(): Uses x-amz-meta-surrogate-key header

​

Best Practices

• Use meaningful, granular keys
• Group related content with shared keys
• Set appropriate TTLs
• Plan purge strategy

​

Testing

​

Related Middlewares

• cache - Cache-Control headers
• etag - ETag generation
• vary - Vary headers