Documentation
¶
Index ¶
- Constants
- type Controller
- 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.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶
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 ¶
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 ¶
WithHeader adds a static header to every request sent by the controller. This can be called multiple times to add multiple headers.
func WithLogger ¶
WithLogger provides a custom slog.Logger for the controller. If not provided, slog.Default() is used.
func WithMaxInterval ¶
WithMaxInterval sets the maximum duration between refresh attempts. The refresh delay will not be longer than this value.
func WithMinInterval ¶
WithMinInterval sets the minimum duration between refresh attempts. The refresh delay, typically determined by caching headers, will not be shorter than this.
func WithRetryOptions ¶
WithRetryOptions configures the retry mechanism for the default HTTP client. These options are ignored if a custom client is provided via WithClient.
func WithTLSConfig ¶
WithTLSConfig provides a custom tls.Config for the default HTTP transport. This is ignored if a custom client is provided via WithClient.
func WithTimeout ¶
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.
Source Files