inspect

type Cache interface {
	Policy() CachePolicy
	Stats() CacheStats
	// Clear drops every entry and returns how many there were. Entries being
	// filled right now are invalidated too, so the fill in flight cannot land
	// afterwards and resurrect what was just dropped.
	Clear() int
	Invalidate(key string)
	InvalidatePrefix(prefix string)
}

type CacheClass string

type CacheMetadata struct {
	Policy             string     `json:"policy"`
	State              CacheState `json:"state"`
	Cached             bool       `json:"cached"`
	Refreshing         bool       `json:"refreshing,omitempty"`
	LoadedAt           time.Time  `json:"loadedAt"`
	FreshUntil         time.Time  `json:"freshUntil"`
	LastChangedAt      time.Time  `json:"lastChangedAt"`
	LastRefreshAttempt *time.Time `json:"lastRefreshAttempt,omitempty"`
	LastRefreshError   string     `json:"lastRefreshError,omitempty"`
	AgeMS              int64      `json:"ageMs"`
	RetryAfterMS       int64      `json:"retryAfterMs,omitempty"`
	UnchangedRefreshes int        `json:"unchangedRefreshes,omitempty"`
}

type CachePolicy struct {
	Name            string
	InitialFreshFor time.Duration
	MaximumFreshFor time.Duration
	FillTimeout     time.Duration
	MaxEntries      int
	MaxWeight       int
}

type CacheState string

type CacheStats struct {
	Policy     string `json:"policy"`
	Entries    int    `json:"entries"`
	MaxEntries int    `json:"maxEntries"`
	Weight     int    `json:"weight"`
	MaxWeight  int    `json:"maxWeight"`
	// Filling counts loads in flight. A cache that is always filling is one
	// whose freshness window is shorter than the thing it caches takes to build.
	Filling int `json:"filling"`
	// Oldest is when the least recently loaded entry was filled, and is zero for
	// an empty cache.
	Oldest time.Time `json:"oldest,omitempty"`
	// FreshFor and MaxFreshFor are the policy's window, reported so a console can
	// explain a stale read without a second lookup.
	FreshForSeconds    int64 `json:"freshForSeconds"`
	MaxFreshForSeconds int64 `json:"maxFreshForSeconds"`
}

type FlushOptions struct {
	Policy string
	Key    string
	Prefix string
}

type FlushResult struct {
	Caches  []FlushedCache `json:"caches"`
	Entries int            `json:"entries"`
}

type FlushedCache struct {
	Policy  string `json:"policy"`
	Entries int    `json:"entries"`
}

type GetOptions[T any] struct {
	Key     string
	Refresh bool
	Load    func(context.Context) (T, error)
}

type Memo[T any] struct {
	// contains filtered or unexported fields
}

type MemoOptions[T any] struct {
	Policy      CachePolicy
	Weight      func(T) int
	Fingerprint func(T) (string, error)
	Now         func() time.Time
}

type Observation struct {
	// Policy is the cache class (see CacheClass), and Key the entry within it.
	Policy string
	Key    string

	// Elapsed is the wall time this caller waited. A cached read is ~0; a miss
	// pays the whole fill, which is the number worth looking at.
	Elapsed time.Duration

	Cache CacheMetadata

	// Err is the fill failure, if the caller got one. A stale entry served after
	// a failed refresh reports the failure on Cache.LastRefreshError instead and
	// leaves this empty — the caller was not failed, only served older facts.
	Err error
}

type Observer func(Observation)

type ObserverKey struct{}

type RefreshKey struct{}

type Result[T any] struct {
	Value T
	Cache CacheMetadata
}