model

Documentation

Index

• type BatchError
  • func NewBatchError(total int) *BatchError
  • func (e *BatchError) Add(key string, err error)
  • func (e *BatchError) Error() string
  • func (e *BatchError) OrNil() error
• type CacheBucket
• type CacheClient
• type CacheCollection
• type CacheDoc
• type CacheExpire
• type CacheTime
• type CacheTimeline
• type Coder
• type Decoder
• type Encoder
• type LabelSet
  • func (ls LabelSet) CheckAnd(labels []string) bool
  • func (ls LabelSet) CheckOr(labels []string) bool
  • func (ls LabelSet) Copy() LabelSet
  • func (ls LabelSet) Format() string
  • func (ls LabelSet) From(labels []string) LabelSet
  • func (ls LabelSet) FromStr(labels string) LabelSet
  • func (ls LabelSet) List() []string
• type Logger
• type MembersMap
  • func (smm MembersMap) Exists(mem string) bool
  • func (smm MembersMap) List() []string
• type RetentionPolicy
• type RetentionStrategy
• type TimeValue

Types

type BatchError

type BatchError struct {
	// Total is the number of keys in the batch request.
	Total int
	// Failed is the number of keys that encountered a real retrieval error.
	Failed int
	// KeyErrors maps each failed key to its specific error.
	KeyErrors map[string]error
}

BatchError reports partial failures in batch operations. When a batch method returns a non-nil error that is a *BatchError, the result slice still contains valid data for keys that succeeded. Callers SHOULD type-assert to *BatchError to access per-key detail and SHOULD use partial results for the successful positions.

nil results in the batch result slice mean "key has no data" — that is a normal condition and is NOT counted as a failure.

func NewBatchError

func NewBatchError(total int) *BatchError

NewBatchError creates an empty BatchError for a batch of size total.

func (*BatchError) Add

func (e *BatchError) Add(key string, err error)

Add records a failure for key with the given error.

func (*BatchError) Error

func (e *BatchError) Error() string

func (*BatchError) OrNil

func (e *BatchError) OrNil() error

OrNil returns nil if no failures were recorded, otherwise returns e.

type CacheBucket

type CacheBucket interface {
	Name() string
	// Docs returns docs parallel to keys. nil at index i means keys[i] not found (not an error).
	// Returns *BatchError if one or more keys encountered real retrieval errors.
	Docs(ctx context.Context, keys []string) ([]CacheDoc, error)
	// Values returns values parallel to keys. nil at index i means keys[i] not found (not an error).
	// Returns *BatchError if one or more keys encountered real retrieval errors.
	Values(ctx context.Context, keys []string) ([]any, error)
	Update(ctx context.Context, key string, data any) (CacheDoc, error)
	// UpdateWithTs return doc, updated flag, and error
	UpdateWithTs(ctx context.Context, key string, data any, ts time.Time) (CacheDoc, bool, error)
	//Filter return all keys that match the given label filters
	Filter(ctx context.Context, labelFilters ...[]string) ([]string, error)
	// Scan return all keys that match the given pattern
	Scan(ctx context.Context, match string) ([]string, error)
	Remove(ctx context.Context, keys []string) error
	Clear(ctx context.Context) error
	Delete(ctx context.Context) error
}

type CacheClient

type CacheClient interface {
	WithBucket(CacheBucket) CacheBucket
	Bucket(name string) CacheBucket
	Buckets() []CacheBucket
	RemoveBucket(bktName string)

	Collection(name string) CacheCollection
	Collections() []CacheCollection
	RemoveCollection(name string)

	Timeline(name string) CacheTimeline
	Timelines() []CacheTimeline
	RemoveTimeline(name string) error
}

type CacheCollection

type CacheCollection interface {
	Name() string
	Keys(ctx context.Context) ([]string, error)
	MembersMap(ctx context.Context, key string) (MembersMap, error)
	MembersMaps(ctx context.Context, keys []string) ([]MembersMap, error)
	Add(ctx context.Context, key string, members []string) error
	Remove(ctx context.Context, key string, members []string) error
	Clear(ctx context.Context, key string) error
	ClearAll(ctx context.Context) error
	Delete(ctx context.Context) error
}

type CacheDoc

type CacheDoc interface {
	CacheTime
	CacheExpire
	Key() string
	Val(ctx context.Context) (any, error)
	SetValue(ctx context.Context, val any) error
	Labels(ctx context.Context) (LabelSet, error)
	AddLabels(ctx context.Context, labels []string) error
	RemoveLabels(ctx context.Context, labels []string) error
	Delete(ctx context.Context) error
}

type CacheExpire

type CacheExpire interface {
	Expire(d time.Duration, onExpire func(CacheDoc)) error
	CancelExpire() error
}

type CacheTime

type CacheTime interface {
	WithTime(ctx context.Context, ts time.Time) error
	// SetValueWithTs returns updated flag and error
	SetValueWithTs(ctx context.Context, val any, ts time.Time) (bool, error)
	Time(ctx context.Context) (time.Time, error)
}

type CacheTimeline

type CacheTimeline interface {
	// Name returns the timeline name.
	Name() string

	// Append adds or updates fields at the specified timestamp.
	// Optimized for chronological writes (ts >= last timestamp).
	// If force is false, returns error if any field already exists at timestamp.
	// If force is true, overwrites existing fields.
	Append(ctx context.Context, key string, ts time.Time, data map[string]string, force bool) error

	// Insert adds or updates fields at the specified timestamp.
	// Supports out-of-order writes at any historical position.
	// If force is false, returns error if any field already exists at timestamp.
	// If force is true, overwrites existing fields.
	Insert(ctx context.Context, key string, ts time.Time, data map[string]string, force bool) error

	// GetAt returns the complete merged state at or before ts for each key.
	// Results are parallel to keys: results[i] corresponds to keys[i].
	// nil at results[i] means keys[i] has no state at or before ts (not an error).
	// Returns *BatchError if one or more keys encountered retrieval errors.
	GetAt(ctx context.Context, keys []string, ts time.Time) ([]map[string]string, error)

	// GetExact returns the raw sparse fields at the exact timestamp for each key.
	// Results are parallel to keys: results[i] corresponds to keys[i].
	// nil at results[i] means keys[i] has no time point at exactly ts (not an error).
	// Returns *BatchError if one or more keys encountered retrieval errors.
	GetExact(ctx context.Context, keys []string, ts time.Time) ([]map[string]string, error)

	// GetRange returns all complete states in [start, end] for each key.
	// Results are parallel to keys: results[i] corresponds to keys[i].
	// nil at results[i] means keys[i] has no time points in the range (not an error).
	// Non-nil inner slices contain only non-nil *TimeValue pointers.
	// Returns *BatchError if one or more keys encountered retrieval errors.
	GetRange(ctx context.Context, keys []string, start, end time.Time) ([][]*TimeValue, error)

	// GetLatest returns the complete merged state at the most recent timestamp for each key.
	// Results are parallel to keys: results[i] corresponds to keys[i].
	// nil at results[i] means keys[i] has no time-series data (not an error).
	// Returns *BatchError if one or more keys encountered retrieval errors.
	GetLatest(ctx context.Context, keys []string) ([]map[string]string, error)

	// Timeline returns all complete states for the key in chronological order.
	// Each element is a non-nil *TimeValue pointer.
	Timeline(ctx context.Context, key string) ([]*TimeValue, error)

	// GetAffectedRange returns all states from insertedAt (inclusive) to end of timeline.
	// Used for recomputation after historical insertion.
	// Each element is a non-nil *TimeValue pointer.
	GetAffectedRange(ctx context.Context, key string, insertedAt time.Time) ([]*TimeValue, error)

	// WithRetention sets the retention policy for the timeline and returns self for method chaining.
	// The policy applies to all keys in the timeline.
	// Retention policy is stored in-memory only and must be set after timeline creation.
	WithRetention(policy RetentionPolicy) CacheTimeline

	// GetRetention returns the timeline's retention policy.
	// Returns zero values (MaxCount: 0, MaxDuration: 0) if no policy has been set, meaning unlimited retention.
	GetRetention() RetentionPolicy

	// Keys returns all logical keys in the timeline.
	// With no label filter arguments, all keys are returned.
	// Labels within a single []string argument are OR'd together.
	// Multiple arguments are AND'd: Keys(ctx, []string{"a","b"}, []string{"c"})
	// returns keys that have (a OR b) AND c.
	Keys(ctx context.Context, labelFilters ...[]string) ([]string, error)

	// AddKeyLabels associates labels with a logical key.
	// Empty strings in labels are ignored. Adding an existing label is a no-op.
	AddKeyLabels(ctx context.Context, key string, labels []string) error

	// RemoveKeyLabels removes labels from a logical key.
	// Removing a non-existent label is a no-op.
	RemoveKeyLabels(ctx context.Context, key string, labels []string) error

	// KeyLabels returns the set of labels associated with a logical key.
	// Returns an empty LabelSet if the key has no labels or does not exist.
	KeyLabels(ctx context.Context, key string) (LabelSet, error)

	// GetUpdatedKeys returns all keys that have been updated after the specified timestamp.
	// The timestamp boundary is exclusive: only keys with updates strictly after the timestamp are returned.
	// Each key appears at most once in the result, even if it was updated multiple times.
	// Result order is unordered and implementation-defined.
	// Returns an empty slice if no keys were updated after the timestamp.
	GetUpdatedKeys(ctx context.Context, after time.Time) ([]string, error)

	// Remove removes the specified keys from the timeline.
	Remove(ctx context.Context, keys []string) error

	// Clear removes all data from the timeline but keeps the timeline instance.
	Clear(ctx context.Context) error

	// Delete removes the timeline instance from the client.
	Delete(ctx context.Context) error
}

CacheTimeline provides time-indexed state storage where multiple versions of state coexist at different timestamps. It supports sparse field updates, out-of-order insertion, and time-based queries.

type Coder

type Coder interface {
	Encoder
	Decoder
}

type Decoder

type Decoder interface {
	Decode(data string, out any) error
}

type Encoder

type Encoder interface {
	Encode(data any) (string, error)
}

type LabelSet

type LabelSet map[string]bool

func (LabelSet) CheckAnd

func (ls LabelSet) CheckAnd(labels []string) bool

func (LabelSet) CheckOr

func (ls LabelSet) CheckOr(labels []string) bool

func (LabelSet) Copy

func (ls LabelSet) Copy() LabelSet

func (LabelSet) Format

func (ls LabelSet) Format() string

func (LabelSet) From

func (ls LabelSet) From(labels []string) LabelSet

func (LabelSet) FromStr

func (ls LabelSet) FromStr(labels string) LabelSet

func (LabelSet) List

func (ls LabelSet) List() []string

type Logger

type Logger interface {
	// Debug logs a debug message with optional key-value pairs
	Debug(msg string, keysAndValues ...any)
	// Info logs an informational message with optional key-value pairs
	Info(msg string, keysAndValues ...any)
	// Error logs an error message with optional key-value pairs
	Error(msg string, keysAndValues ...any)
	// Fatal logs an error message and then panics
	// This is used for critical errors that should stop execution
	Fatal(msg string, keysAndValues ...any)
}

Logger is an interface for logging in the cache system. Users can provide their own implementation to integrate with their logging framework.

type MembersMap

type MembersMap map[string]struct{}

func (MembersMap) Exists

func (smm MembersMap) Exists(mem string) bool

func (MembersMap) List

func (smm MembersMap) List() []string

type RetentionPolicy

type RetentionPolicy struct {
	MaxCount    int               // Maximum number of time points per key (0 = unlimited)
	MaxDuration time.Duration     // Maximum age of time points (0 = unlimited)
	Strategy    RetentionStrategy // Strategy for applying count and duration constraints
}

RetentionPolicy defines automatic data lifecycle management rules.

type RetentionStrategy

type RetentionStrategy int

RetentionStrategy defines how retention boundaries are calculated.

const (
	// RetentionMax keeps points that satisfy EITHER count OR duration constraint (safer, keeps more data).
	RetentionMax RetentionStrategy = iota
	// RetentionMin keeps points that satisfy BOTH count AND duration constraints (aggressive, keeps less data).
	RetentionMin
)

type TimeValue

type TimeValue struct {
	Time  time.Time
	Value map[string]string
}

TimeValue represents a moment in time with its associated complete state.