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 ResolveRedirects(ctx context.Context, rawURL string, logger *slog.Logger) string
• 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 ResolveRedirects

func ResolveRedirects(ctx context.Context, rawURL string, logger *slog.Logger) string

ResolveRedirects follows HTTP, HTML meta refresh, and JavaScript redirects. Returns the final URL after following all redirects (up to maxRedirects). If no redirects are found, returns the original URL unchanged.

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.