cachecontrol

README

Cache-Control middleware for Gin

This Gin middleware generates cache-control headers.

Setup

go get -u go.eigsys.de/gin-cachecontrol/v2

import "go.eigsys.de/gin-cachecontrol/v2"

Usage

With a preset

// Apply globally:
r.Use(cachecontrol.New(cachecontrol.NoCachePreset))

// Apply to specific routes:
cacheForever := cachecontrol.New(cachecontrol.CacheAssetsForeverPreset)
r.GET("/favicon.ico", cacheForever, faviconHandler)

Supported presets (documentation):

• cachecontrol.NoCachePreset
• cachecontrol.CacheAssetsForeverPreset (you may only want this for carefully selected routes)

With a custom configuration

r.Use(
    cachecontrol.New(
        cachecontrol.Config{
            MustRevalidate:       true,
            NoCache:              false,
            NoStore:              false,
            NoTransform:          false,
            Public:               true,
            Private:              false,
            ProxyRevalidate:      true,
            MaxAge:               cachecontrol.Duration(30 * time.Minute),
            SMaxAge:              nil,
            Immutable:            false,
            StaleWhileRevalidate: cachecontrol.Duration(2 * time.Hour),
            StaleIfError:         cachecontrol.Duration(2 * time.Hour),
        }
    )
)

Documentation

See Go reference.

Documentation

Index

• Constants
• Variables
• func Duration(duration time.Duration) *time.Duration
• func New(config Config) gin.HandlerFunc
• type Config

Examples

• New

Constants

const CacheControlHeader = "Cache-Control"

Variables

var CacheAssetsForeverPreset = Config{
	Public:    true,
	MaxAge:    Duration(8760 * time.Hour),
	Immutable: true,
}

CacheAssetsForeverPreset is a cache-control configuration preset which advices the HTTP client and all caches in between to cache the object forever without revalidation. Technically, "forever" means 1 year, in order to comply with common CDN limits.

var NoCachePreset = Config{
	MustRevalidate: true,
	NoCache:        true,
	NoStore:        true,
}

NoCachePreset is a cache-control configuration preset which advices the HTTP client not to cache at all.

Functions

func Duration

func Duration(duration time.Duration) *time.Duration

Duration is a helper function which returns a time.Duration pointer.

func New

func New(config Config) gin.HandlerFunc

New creates a new Gin middleware which generates a cache-control header. Existing cache-control headers are removed. Other caching-related headers, such as `Expires` and `Pragma`, remain unchanged.

Example

package main

import (
	"github.com/gin-gonic/gin"
	cachecontrol "go.eigsys.de/gin-cachecontrol/v2"
	"net/http"
	"time"
)

func main() {
	router := gin.Default()

	router.Use(cachecontrol.New(cachecontrol.Config{
		MustRevalidate:       true,
		NoCache:              false,
		NoStore:              false,
		NoTransform:          false,
		Public:               true,
		Private:              false,
		ProxyRevalidate:      true,
		MaxAge:               cachecontrol.Duration(30 * time.Minute),
		SMaxAge:              nil,
		Immutable:            false,
		StaleWhileRevalidate: cachecontrol.Duration(2 * time.Hour),
		StaleIfError:         cachecontrol.Duration(2 * time.Hour),
	}))

	router.GET("/", func(ginCtx *gin.Context) {
		ginCtx.String(http.StatusOK, "Hello, Gopher!")
	})

	_ = router.Run()
}

Types

type Config

type Config struct {
	MustRevalidate       bool
	NoCache              bool
	NoStore              bool
	NoTransform          bool
	Public               bool
	Private              bool
	ProxyRevalidate      bool
	MaxAge               *time.Duration
	SMaxAge              *time.Duration
	Immutable            bool
	StaleWhileRevalidate *time.Duration
	StaleIfError         *time.Duration
}

Config defines a cache-control configuration.

References: https://datatracker.ietf.org/doc/html/rfc7234#section-5.2.2 https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control