replay

README

Replay

Configurable http caching middleware for Go servers.
Improve API throughput, reduce latency, and save on third-party resources.

Features

• Eviction Policy: FIFO, LRU
• Cache Size: Based on number of entries, or memory usage
• Cache Filters: Filter on URL, method, or header fields
• TTL + Max TTL: Cache expiration and renewal
• Logger: Pass any logger package
• Metrics: Track cache hits, misses, and evictions

Example

import (
	"log"
	"net/http"
	"os"
	"time"
	"github.com/Ztkent/replay"
	"github.com/go-chi/chi/v5"
)

func main() {
	r := chi.NewRouter()
	c := replay.NewCache(
		replay.WithMaxSize(100),
		replay.WithMaxMemory(100*1024*1024),
		replay.WithCacheFilters([]string{"URL", "Method"}),
		replay.WithCacheFailures(false),
		replay.WithEvictionPolicy("LRU"),
		replay.WithTTL(5*time.Minute),
		replay.WithMaxTTL(30*time.Minute),
		replay.WithLogger(log.New(os.Stdout, "replay: ", log.LstdFlags)),
	)

	// Apply the middleware to the entire router
	r.Use(c.Middleware)
	// Or apply it to a specific endpoint
	r.Get("/test-endpoint", c.MiddlewareFunc(testHandlerFunc()))
	http.ListenAndServe(os.Getenv("SERVER_PORT"), r)
}

Options

The cache configured with the following options:

• WithMaxSize(maxSize int): Set the maximum number of entries in the cache.
• WithMaxMemory(maxMemory uint64): Set the maximum memory usage of the cache.
• WithEvictionPolicy(evictionPolicy string): Set the eviction policy for the cache [FIFO, LRU].
• WithEvictionTimer(evictionTimer time.Duration): Set the time between cache eviction checks.
• WithTTL(ttl time.Duration): Set the time a cache entry can live without being accessed.
• WithMaxTTL(maxTtl time.Duration): Set the maximum time a cache entry can live, including renewals.
• WithCacheFilters(cacheFilters []string): Set the cache filters to use for generating cache keys.
• WithCacheFailures(cacheFailures bool): Set whether to cache failed requests.
• WithLogger(l *log.Logger): Set the logger to use for cache logging.

Metrics

You can access cache metrics to monitor cache performance:

metrics := c.Metrics()

Fields Available:

• Hits: Total number of cache hits.
• Misses: Total number of cache misses.
• Evictions: Total umber of cache evictions.
• CurrentSize: Number of entries in the cache.
• CurrentMemory: Current memory usage of the cache.

Documentation

Index

• Constants
• type Cache
  • func NewCache(options ...CacheOption) *Cache
  • func (c *Cache) Metrics() *CacheMetrics
  • func (c *Cache) Middleware(next http.Handler) http.Handler
  • func (c *Cache) MiddlewareFunc(next http.HandlerFunc) http.HandlerFunc
• type CacheConfig
• type CacheEntry
• type CacheMetrics
• type CacheOption
  • func WithCacheFailures(cacheFailures bool) CacheOption
  • func WithCacheFilters(cacheFilters []string) CacheOption
  • func WithEvictionPolicy(evictionPolicy string) CacheOption
  • func WithEvictionTimer(evictionTimer time.Duration) CacheOption
  • func WithLogger(l *log.Logger) CacheOption
  • func WithMaxMemory(maxMemory uint64) CacheOption
  • func WithMaxSize(maxSize int) CacheOption
  • func WithMaxTTL(maxTtl time.Duration) CacheOption
  • func WithTTL(ttl time.Duration) CacheOption
• type CacheResponse
• type EvictionPolicy

Constants

const (
	DefaultMaxSize        = 25
	DefaultMaxMemory      = 100 * 1024 * 1024
	DefaultEvictionPolicy = LRU
	DefaultEvictionTimer  = 1 * time.Minute
	DefaultTTL            = 5 * time.Minute
	DefaultMaxTTL         = 10 * time.Minute
	DefaultFilter         = "URL"
)

Types

type Cache

type Cache struct {
	*sync.Mutex // Mutex for synchronizing access to the cache
	CacheConfig // Cache configuration options
	// contains filtered or unexported fields
}

Cache stores the cache configuration and data

func NewCache

func NewCache(options ...CacheOption) *Cache

NewCache initializes a new instance of Cache with given options

func (*Cache) Metrics

func (c *Cache) Metrics() *CacheMetrics

func (*Cache) Middleware

func (c *Cache) Middleware(next http.Handler) http.Handler

Middleware function to intercept all HTTP requests on a handler.

func (*Cache) MiddlewareFunc

func (c *Cache) MiddlewareFunc(next http.HandlerFunc) http.HandlerFunc

Middleware function to intercept HTTP requests to a given route

type CacheConfig

type CacheConfig struct {
	// contains filtered or unexported fields
}

CacheConfig stores the configuration options for the cache All of these options can be set using CacheOption functions

type CacheEntry

type CacheEntry struct {
	// contains filtered or unexported fields
}

CacheEntry stores a single cache item

type CacheMetrics

type CacheMetrics struct {
	Hits          int
	Misses        int
	Evictions     int
	CurrentSize   int
	CurrentMemory uint64
}

CacheMetrics stores the cache metrics

type CacheOption

type CacheOption func(*Cache)

func WithCacheFailures

func WithCacheFailures(cacheFailures bool) CacheOption

Set whether to cache failed requests

func WithCacheFilters

func WithCacheFilters(cacheFilters []string) CacheOption

Set the cache filters to use for generating cache keys

func WithEvictionPolicy

func WithEvictionPolicy(evictionPolicy string) CacheOption

Set the eviction policy for the cache [FIFO, LRU]

func WithEvictionTimer

func WithEvictionTimer(evictionTimer time.Duration) CacheOption

Set the time between cache eviction checks

func WithLogger

func WithLogger(l *log.Logger) CacheOption

Set the logger to use for cache logging

func WithMaxMemory

func WithMaxMemory(maxMemory uint64) CacheOption

Set the maximum memory usage of the cache

func WithMaxSize

func WithMaxSize(maxSize int) CacheOption

Set the maximum number of entries in the cache

func WithMaxTTL

func WithMaxTTL(maxTtl time.Duration) CacheOption

Set the maximum time a cache entry can live, including renewals

func WithTTL

func WithTTL(ttl time.Duration) CacheOption

Set the time a cache entry can live without being accessed

type CacheResponse

type CacheResponse struct {
	StatusCode int
	Header     http.Header
	Body       []byte
}

CacheResponse stores the response info to be cached

type EvictionPolicy

type EvictionPolicy string

const (
	LRU  EvictionPolicy = "LRU"
	FIFO EvictionPolicy = "FIFO"
)