Documentation
¶
Overview ¶
Package httpcache provides a generic caching HTTP fetcher.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CacheConfig ¶
type CacheConfig struct {
// StaticExpiry defines a fixed cache duration (e.g., 1 hour)
StaticExpiry time.Duration
// ReturnStale controls whether stale data should be returned while refreshing
// If true, returns stale data immediately and refreshes in background
// If false, blocks until fresh data is fetched
ReturnStale bool
}
CacheConfig configures the caching behavior of a CachingFetcher
type CacheResult ¶
type CacheResult int
CacheResult indicates the status of cached data
const ( // CacheResultFresh indicates data was freshly fetched CacheResultFresh CacheResult = iota // CacheResultCached indicates data was returned from cache CacheResultCached // CacheResultStale indicates stale data was returned due to fetch error CacheResultStale )
type CachingFetcher ¶
type CachingFetcher[T any] struct { // contains filtered or unexported fields }
CachingFetcher is a generic caching HTTP fetcher that handles HTTP requests with caching
func NewCachingFetcher ¶
func NewCachingFetcher[T any](url string, config CacheConfig) *CachingFetcher[T]
NewCachingFetcher creates a new caching fetcher for the specified URL and type. It uses JSON unmarshaling by default to decode the response body into type T.
func NewCachingFetcherWithFunc ¶
func NewCachingFetcherWithFunc[T any](url string, config CacheConfig, fetchFunc FetchFunc[T]) *CachingFetcher[T]
NewCachingFetcherWithFunc creates a new caching fetcher with a custom fetch function. If fetchFunc is nil, it defaults to JSON unmarshaling. This allows for custom parsing of the HTTP response (e.g., plain text lines).
func (*CachingFetcher[T]) Get ¶
func (f *CachingFetcher[T]) Get(ctx context.Context) (T, CacheResult, error)
Get fetches data from the URL with caching. It returns the data, cache result status (Fresh, Cached, or Stale), and any error encountered. If ReturnStale is enabled, it may return stale data immediately and start a background refresh.
CacheResultStale is always returned with a nil error: the data is valid and safe to use even though it came from a failed refresh attempt rather than from fresh cache. This holds whether the stale data was returned immediately (ReturnStale) or as a fallback after a blocking refresh failed. A caller that follows the common `if err != nil { return }` pattern must not have that discard perfectly usable stale data; check the returned CacheResult, not just err, to distinguish "no data at all" from "stale but usable."
func (*CachingFetcher[T]) GetCacheInfo ¶
func (f *CachingFetcher[T]) GetCacheInfo() (cachedAt, expiresAt time.Time, hasData bool)
GetCacheInfo returns information about the current cache status. It returns the time the data was cached, the time it expires, and whether data is present.
func (*CachingFetcher[T]) GetCachedData ¶
func (f *CachingFetcher[T]) GetCachedData() *T
GetCachedData returns the currently cached data without performing a fetch. It returns nil if no data is currently cached.
func (*CachingFetcher[T]) LastError ¶ added in v0.67.3
func (f *CachingFetcher[T]) LastError() error
LastError returns the error from the most recently completed fetch attempt (nil if the last attempt succeeded, or no fetch has completed yet). Use this to inspect why Get returned a CacheResultStale result -- Get itself never pairs stale-but-usable data with a non-nil error.
type FetchResult ¶
type FetchResult[T any] struct { Data T Result CacheResult Error error }
FetchResult contains the fetched data and metadata about the fetch
Source Files