httpcache

Documentation

Overview

Package httpcache provides HTTP response caching with thundering herd prevention.

Index

• func FetchURL(ctx context.Context, cache Cacher, client *http.Client, req *http.Request, ...) ([]byte, error)
• func FetchURLWithValidator(ctx context.Context, cache Cacher, client *http.Client, req *http.Request, ...) ([]byte, error)
• func URLToKey(rawURL string) string
• type Cache
  • func New(ttl time.Duration) (*Cache, error)
  • func NewNull() *Cache
  • func NewWithPath(ttl time.Duration, cachePath string) (*Cache, error)
  • func (c *Cache) TTL() time.Duration
• type Cacher
• type HTTPError
  • func (e *HTTPError) Error() string
• type ResponseValidator

Functions

func FetchURL

func FetchURL(ctx context.Context, cache Cacher, client *http.Client, req *http.Request, logger *slog.Logger) ([]byte, error)

FetchURL fetches a URL with caching and thundering herd prevention. If cache is non-nil, uses GetSet to ensure only one request is made for concurrent calls.

func FetchURLWithValidator

func FetchURLWithValidator(
	ctx context.Context,
	cache Cacher,
	client *http.Client,
	req *http.Request,
	logger *slog.Logger,
	validator ResponseValidator,
) ([]byte, error)

FetchURLWithValidator fetches a URL with caching and optional response validation. If validator returns false, the response is returned but NOT cached.

func URLToKey

func URLToKey(rawURL string) string

URLToKey converts a URL to a cache key using SHA256 hash.

Types

type Cache

type Cache struct {
	*sfcache.TieredCache[string, []byte]
	// contains filtered or unexported fields
}

Cache wraps sfcache for HTTP response caching.

func New

func New(ttl time.Duration) (*Cache, error)

New creates a new Cache with disk persistence at ~/.cache/sociopath.

func NewNull

func NewNull() *Cache

NewNull creates a Cache with no persistence (all gets miss, all sets discard).

func NewWithPath

func NewWithPath(ttl time.Duration, cachePath string) (*Cache, error)

NewWithPath creates a new Cache with disk persistence at the specified path.

func (*Cache) TTL

func (c *Cache) TTL() time.Duration

TTL returns the default TTL for cache entries.

type Cacher

type Cacher interface {
	GetSet(ctx context.Context, key string, fetch func(context.Context) ([]byte, error), ttl ...time.Duration) ([]byte, error)
	TTL() time.Duration
}

Cacher allows external cache implementations for sharing across packages.

type HTTPError

type HTTPError struct {
	URL        string
	StatusCode int
}

HTTPError represents an HTTP error response.

func (*HTTPError) Error

func (e *HTTPError) Error() string

type ResponseValidator

type ResponseValidator func(body []byte) bool

ResponseValidator validates a response body. Returns true if cacheable.