cache

Documentation

Overview

Package cache provides a generic, auto-refreshing in-memory cache for a resource fetched from a URL.

The core of the package is the Controller, a scheduler.Tick that periodically fetches a remote resource, parses it, and caches it in memory. It is designed to be resilient, with a built-in, configurable retry mechanism for handling transient network failures.

The refresh interval is intelligently determined by the resource's caching headers (e.g., Cache-Control, Expires), but can be clamped within a specified min/max range. The controller also handles conditional requests using ETag and Last-Modified headers to reduce bandwidth and server load.

Usage

A typical use case involves creating a scheduler, defining a Mapper function to parse the HTTP response, creating and configuring a Controller, and then dispatching it to run in the background.

Example:

type Resource struct {
	// fields for the parsed data
}

// 1. Create a scheduler to manage the refresh ticks.
sched := scheduler.New(context.Background())
defer sched.Shutdown()

// 2. Define a mapper to parse the response body into your target type.
var mapper cache.Mapper[Resource] = func(body []byte) (Resource, error) {
	var data Resource
	err := json.Unmarshal(body, &data)
	return data, err
}

// 3. Create and configure the cache controller.
ctrl := cache.NewController(
	"https://api.example.com/resource",
	mapper,
	cache.WithMinInterval(5*time.Minute),
	cache.WithHeader("Authorization", "Bearer *****"),
)

// 4. Dispatch the controller to start fetching in the background.
sched.Dispatch(ctrl)

// 5. You can wait for the first successful fetch.
<-ctrl.Ready()

// 6. Get the cached data.
if data, ok := ctrl.Get(); ok {
	fmt.Printf("Successfully fetched and cached data: %+v\n", data)
}

Index

• Constants
• type Controller
  • func NewController[T any](url string, mapper Mapper[T], opts ...Option) Controller[T]
• type Mapper
• type Option
  • func WithClient(client *http.Client) Option
  • func WithHeader(k, v string) Option
  • func WithLogger(log *slog.Logger) Option
  • func WithMaxInterval(d time.Duration) Option
  • func WithMinInterval(d time.Duration) Option
  • func WithRetryOptions(opts ...retry.Option) Option
  • func WithTLSConfig(tls *tls.Config) Option
  • func WithTimeout(d time.Duration) Option
• type Response

Constants

const (
	// DefaultTimeout is the default timeout for a single HTTP request.
	DefaultTimeout = 30 * time.Second
	// DefaultMinInterval is the default lower bound for the refresh interval.
	DefaultMinInterval = 15 * time.Minute
	// DefaultMaxInterval is the default upper bound for the refresh interval.
	DefaultMaxInterval = 24 * time.Hour
)

Default configuration values for the cache controller.

Types

type Controller

type Controller[T any] interface {
	scheduler.Tick
	// Get retrieves the currently cached resource. The boolean return value is
	// true if the cache has been successfully populated at least once.
	Get() (T, bool)
	// Ready returns a channel that is closed once the first successful fetch of
	// the resource is complete. This allows consumers to block until the cache
	// is warmed up.
	Ready() <-chan struct{}
}

Controller manages the lifecycle of a cached resource. It implements scheduler.Tick, allowing it to be run by a scheduler to periodically refresh the resource from a URL.

func NewController

func NewController[T any](
	url string,
	mapper Mapper[T],
	opts ...Option,
) Controller[T]

NewController creates and configures a new cache Controller.

It requires a URL for the resource to fetch and a Mapper function to parse the response. If no http.Client is provided via options, it creates a default one with a sensible timeout and a retry transport.

type Mapper

type Mapper[T any] func(r *Response) (T, error)

Mapper is a function that parses a response's raw response body into the target type T. It is responsible for decoding the data (e.g., from JSON or XML) and returning the structured result. An error should be returned if parsing fails fatally. For warnings or debug information, invoke the logger contained in the Response. If the mapping takes a considerable amount of time, it should generally respect the context contained in the Response.

type Option

type Option func(*config)

Option is a function that configures the cache Controller.

func WithClient

func WithClient(client *http.Client) Option

WithClient provides a custom http.Client to be used for requests. This is useful for advanced configurations, such as custom transports or connection pooling. If not provided, a default client with retry logic is created.

func WithHeader

func WithHeader(k, v string) Option

WithHeader adds a static header to every request sent by the controller. This can be called multiple times to add multiple headers.

func WithLogger

func WithLogger(log *slog.Logger) Option

WithLogger provides a custom slog.Logger for the controller. If not provided, slog.Default() is used.

func WithMaxInterval

func WithMaxInterval(d time.Duration) Option

WithMaxInterval sets the maximum duration between refresh attempts. The refresh delay will not be longer than this value.

func WithMinInterval

func WithMinInterval(d time.Duration) Option

WithMinInterval sets the minimum duration between refresh attempts. The refresh delay, typically determined by caching headers, will not be shorter than this.

func WithRetryOptions

func WithRetryOptions(opts ...retry.Option) Option

WithRetryOptions configures the retry mechanism for the default HTTP client. These options are ignored if a custom client is provided via WithClient.

func WithTLSConfig

func WithTLSConfig(tls *tls.Config) Option

WithTLSConfig provides a custom tls.Config for the default HTTP transport. This is ignored if a custom client is provided via WithClient.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the total timeout for a single HTTP fetch attempt, including connection, redirects, and reading the response body. This is ignored if a custom client is provided via WithClient.

type Response

type Response struct {
	Body   []byte          // Raw response payload to be mapped.
	Ctx    context.Context // Context controlling the HTTP exchange.
	Logger *slog.Logger    // Logger instance inherited from the Controller.
}

Response provides contextual information to a Mapper function, including the response body, request context, and a logger.