cache

package
v0.0.0-...-79da9bc Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 12, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BucketCacheClient 

type BucketCacheClient interface {
	ListCollections(ctx context.Context, req *manager_pb.ListCollectionsRequest) (manager_pb.ManagerService_ListCollectionsClient, error)
	GetCollection(ctx context.Context, req *manager_pb.GetCollectionRequest) (*manager_pb.GetCollectionResponse, error)
}

BucketCacheClient defines the manager operations needed by GlobalBucketCache. This is a subset of manager_pb.ManagerServiceClient, allowing the use of ManagerClientPool (which provides leader-aware routing) or direct proto clients.

type BucketCacheEntry 

type BucketCacheEntry struct {
	Name       string `json:"name"`
	OwnerID    string `json:"owner_id"`
	Location   string `json:"location"`
	CreateTime string `json:"create_time"`
	HasPolicy  bool   `json:"has_policy"`
	HasACL     bool   `json:"has_acl"`
}

BucketCacheEntry represents a bucket entry for cache dump

type BucketIterFunc 

type BucketIterFunc func(ctx context.Context) iter.Seq2[*types.BucketInfo, error]

BucketIterFunc returns an iterator that yields buckets from the database. This is more memory-efficient than returning slices as it streams results.

type BucketLoader 

type BucketLoader struct {
	// contains filtered or unexported fields
}

BucketLoader loads buckets from the database into the BucketStore cache. It runs periodically to keep the cache in sync with the database.

func NewBucketLoader 

func NewBucketLoader(iterFunc BucketIterFunc, bucketStore *BucketStore) *BucketLoader

NewBucketLoader creates a new BucketLoader. The iterFunc should return an iterator that yields buckets from the database.

func (*BucketLoader) LoadBuckets 

func (bl *BucketLoader) LoadBuckets(ctx context.Context, refreshInterval time.Duration)

LoadBuckets runs a background loop that periodically refreshes the bucket cache. It loads all buckets from the database and populates the BucketStore. Config fields (Tagging, CORS, etc.) are loaded lazily on first access.

type BucketStore 

type BucketStore struct {
	// contains filtered or unexported fields
}

func NewBucketStore 

func NewBucketStore(cache *Cache[string, s3types.Bucket]) *BucketStore

NewBucketStore creates a new BucketStore wrapping the given cache. The cache should be populated by background refresh goroutines.

func (*BucketStore) Cache 

func (bs *BucketStore) Cache() *Cache[string, s3types.Bucket]

Cache returns the underlying Cache for direct access if needed

func (*BucketStore) DeleteBucket 

func (bs *BucketStore) DeleteBucket(bucket string)

DeleteBucket removes a bucket from the cache and owner index

func (*BucketStore) DumpCache 

func (bs *BucketStore) DumpCache() []BucketCacheEntry

DumpCache returns all cached buckets for debugging

func (*BucketStore) GetBucket 

func (bs *BucketStore) GetBucket(bucket string) (s3types.Bucket, bool)

GetBucket returns the bucket from cache, or nil if not found. This is cache-only - no lazy loading is performed.

func (*BucketStore) GetBucketACL 

func (bs *BucketStore) GetBucketACL(ctx context.Context, bucket string) (*s3types.AccessControlList, bool)

GetBucketACL returns the ACL for a bucket

func (*BucketStore) GetBucketPolicy 

func (bs *BucketStore) GetBucketPolicy(ctx context.Context, bucket string) (*s3types.BucketPolicy, bool)

GetBucketPolicy returns the bucket policy, or nil if none exists

func (*BucketStore) GetObjectACL 

func (bs *BucketStore) GetObjectACL(ctx context.Context, bucket, key string) (*s3types.AccessControlList, bool)

GetObjectACL returns the ACL for an object. Object ACLs are stored per-object in the metadata DB, not in the bucket cache. This is a stub that returns nil - object ACLs should be fetched from the object metadata during request handling.

func (*BucketStore) IsReady 

func (bs *BucketStore) IsReady() bool

IsReady returns true if the cache has completed initial load

func (*BucketStore) ListBucketsByOwner 

func (bs *BucketStore) ListBucketsByOwner(ownerID string) []s3types.Bucket

ListBucketsByOwner returns all buckets for a given owner from cache

func (*BucketStore) SetBucket 

func (bs *BucketStore) SetBucket(bucket string, b s3types.Bucket)

SetBucket updates or adds a bucket in the cache and updates the owner index

func (*BucketStore) UpdateBucketACL 

func (bs *BucketStore) UpdateBucketACL(ctx context.Context, bucket string, acl *s3types.AccessControlList) error

UpdateBucketACL updates just the ACL field for a cached bucket

func (*BucketStore) UpdateBucketPolicy 

func (bs *BucketStore) UpdateBucketPolicy(ctx context.Context, bucket string, policy *s3types.BucketPolicy) error

UpdateBucketPolicy updates just the policy field for a cached bucket

type Cache 

type Cache[K comparable, V any] struct {
	// contains filtered or unexported fields
}

Cache is a high-performance concurrent cache with lock striping.

Features:

  • Lock striping: Keys distributed across shards for reduced contention
  • Optional TTL: Entries expire after a configurable duration
  • Optional max size: LRU eviction when capacity is reached (per-shard)
  • Bulk loading: Efficiently load many entries with minimal lock contention

Usage: 

// Simple cache with max size
c := cache.New[string, User](ctx, cache.WithMaxSize[string, User](10000))

// Cache with TTL expiry
c := cache.New[string, Token](ctx, cache.WithExpiry[string, Token](5*time.Minute))

// Cache with both
c := cache.New[string, Session](ctx,
    cache.WithMaxSize[string, Session](1000),
    cache.WithExpiry[string, Session](time.Hour),
)

func New 

func New[K comparable, V any](ctx context.Context, opts ...Option[K, V]) *Cache[K, V]

New creates a new Cache with the given options.

func (*Cache[K, V]) Clear 

func (c *Cache[K, V]) Clear()

Clear removes all entries from the cache.

func (*Cache[K, V]) Delete 

func (c *Cache[K, V]) Delete(key K)

Delete removes a key from the cache.

func (*Cache[K, V]) Get 

func (c *Cache[K, V]) Get(key K) (V, bool)

Get retrieves a value from the cache. Returns the value and true if found (and not expired), or zero value and false otherwise.

func (*Cache[K, V]) GetOrLoad 

func (c *Cache[K, V]) GetOrLoad(ctx context.Context, key K) (V, error)

GetOrLoad retrieves a value from the cache, loading it if not present. Requires WithLoadFunc to be set.

func (*Cache[K, V]) HasLoaded 

func (c *Cache[K, V]) HasLoaded() bool

HasLoaded returns true if Load() has been called at least once.

func (*Cache[K, V]) Iter 

func (c *Cache[K, V]) Iter() iter.Seq2[K, V]

Iter returns an iterator over all non-expired cache entries. Note: This acquires read locks on all shards sequentially, so avoid calling during high-traffic periods. Useful for debugging.

func (*Cache[K, V]) Load 

func (c *Cache[K, V]) Load(seq iter.Seq2[Entity[K, V], error]) error

Load bulk loads entries into the cache from an iterator. This is optimized for minimal lock contention by grouping entries by shard.

func (*Cache[K, V]) MarkLoaded 

func (c *Cache[K, V]) MarkLoaded()

MarkLoaded marks the cache as having completed initial load. This is useful when the cache is populated via Set() calls rather than Load().

func (*Cache[K, V]) Set 

func (c *Cache[K, V]) Set(key K, value V)

Set adds or updates a value in the cache.

func (*Cache[K, V]) Size 

func (c *Cache[K, V]) Size() int

Size returns the current number of entries across all shards.

func (*Cache[K, V]) Stop 

func (c *Cache[K, V]) Stop()

Stop stops the cleanup goroutine. Call this when the cache is no longer needed.

type Entity 

type Entity[K, V any] struct {
	Key       K
	Value     V
	IsDeleted bool
}

Entity represents a cache entry for bulk loading

type GlobalBucketCache 

type GlobalBucketCache struct {
	// contains filtered or unexported fields
}

func NewGlobalBucketCache 

func NewGlobalBucketCache(ctx context.Context, managerClient BucketCacheClient) *GlobalBucketCache

func (*GlobalBucketCache) Delete 

func (gbc *GlobalBucketCache) Delete(bucket string)

func (*GlobalBucketCache) Get 

func (gbc *GlobalBucketCache) Get(bucket string) (string, bool)

func (*GlobalBucketCache) IsReady 

func (gbc *GlobalBucketCache) IsReady() bool

func (*GlobalBucketCache) LoadBuckets 

func (gbc *GlobalBucketCache) LoadBuckets(ctx context.Context, refreshInterval time.Duration)

func (*GlobalBucketCache) Set 

func (gbc *GlobalBucketCache) Set(bucket string, owner string)

type Option 

type Option[K comparable, V any] func(*Cache[K, V])

Option configures a Cache

func WithExpiry 

func WithExpiry[K comparable, V any](expiry time.Duration) Option[K, V]

WithExpiry sets the TTL for cache entries. Entries older than this duration are considered expired and won't be returned by Get(). A background cleanup goroutine removes expired entries periodically.

func WithLoadFunc 

func WithLoadFunc[K comparable, V any](loadFunc func(ctx context.Context, key K) (V, error)) Option[K, V]

WithLoadFunc sets a function to call on cache misses. If set, Get() will call this function when an entry is not found and cache the result for future requests.

func WithMaxSize 

func WithMaxSize[K comparable, V any](maxSize int) Option[K, V]

WithMaxSize sets the maximum total number of entries in the cache. When capacity is reached, the least recently accessed entry is evicted.

func WithNumShards 

func WithNumShards[K comparable, V any](numShards int) Option[K, V]

WithNumShards sets the number of shards for lock striping. More shards = less contention but slightly more memory overhead. Default is 64 shards.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.