Documentation
¶
Overview ¶
Package cache provides user data caching functionality. Supports both in-memory cache and Redis cache implementations, as well as Redis-based distributed locks.
Package cache provides user data caching functionality. Supports both in-memory cache and Redis cache implementations, as well as Redis-based distributed locks.
Package cache provides user data caching functionality. Supports both in-memory cache and Redis cache implementations, as well as Redis-based distributed locks.
Package cache provides user data caching functionality. Supports both in-memory cache and Redis cache implementations, as well as Redis-based distributed locks.
Index ¶
- Constants
- func AcceptableCount(users []define.AllowListUser) int
- func HashUserList(users []define.AllowListUser) string
- type LocalLocker
- type Locker
- type RedisUserCache
- type SafeUserCache
- func (c *SafeUserCache) Get() []define.AllowListUser
- func (c *SafeUserCache) GetByMail(mail string) (define.AllowListUser, bool)
- func (c *SafeUserCache) GetByPhone(phone string) (define.AllowListUser, bool)
- func (c *SafeUserCache) GetByUserID(userID string) (define.AllowListUser, bool)
- func (c *SafeUserCache) GetHash() string
- func (c *SafeUserCache) GetReadOnly() []define.AllowListUser
- func (c *SafeUserCache) Iterate(fn func(user define.AllowListUser) bool)
- func (c *SafeUserCache) Len() int
- func (c *SafeUserCache) Set(users []define.AllowListUser)
- func (c *SafeUserCache) SetValidated(users []define.AllowListUser, opts identity.Options) error
Constants ¶
const ( // REDIS_CACHE_KEY Redis key for storing user data REDIS_CACHE_KEY = "warden:users:cache" // REDIS_CACHE_VERSION_KEY Redis key for storing cache version REDIS_CACHE_VERSION_KEY = "warden:users:cache:version" // REDIS_CACHE_TTL Redis cache expiration time (1 hour) REDIS_CACHE_TTL = 1 * time.Hour // REDIS_OPERATION_TIMEOUT Redis operation timeout REDIS_OPERATION_TIMEOUT = 5 * time.Second )
const ( IndexPhone = "phone" IndexMail = "mail" IndexUserID = "user_id" )
Index names for multi-index cache
Variables ¶
This section is empty.
Functions ¶
func AcceptableCount ¶ added in v1.3.0
func AcceptableCount(users []define.AllowListUser) int
AcceptableCount reports how many records of users would survive a Set: how large the effective rule set becomes once empty-identifier records are dropped, per-record format validation has run, and duplicates sharing a primary key have collapsed.
It exists so a caller can learn "this load would leave the cache empty" BEFORE mutating the cache. Set is the single atomic swap point, so probing by writing and inspecting the result would expose an empty rule set to concurrent readers for as long as the caller takes to undo it. AcceptableCount answers the same question with no window at all.
It deliberately stays silent: the records it inspects are validated again for real by Set, which logs every rejection. Counting here must not duplicate those warnings.
The steps mirror SafeUserCache.Set and the cache-kit Set it delegates to, in the same order (normalize, validate, primary key, dedup); acceptable_count_test.go pins the two against each other so they cannot drift apart.
func HashUserList ¶ added in v0.9.0
func HashUserList(users []define.AllowListUser) string
HashUserList computes SHA256 hash of user list for change detection. Sorts by primary key (phone or mail), normalizes each user, then hashes. Used by SafeUserCache internally and by main for backgroundTask comparison.
Types ¶
type LocalLocker ¶
type LocalLocker struct {
// contains filtered or unexported fields
}
LocalLocker provides local lock functionality, compatible with gocron.Locker interface Suitable for single-machine deployment scenarios, does not support distributed environments
func NewLocalLocker ¶
func NewLocalLocker() *LocalLocker
NewLocalLocker creates a new local lock instance
func (*LocalLocker) Lock ¶
func (l *LocalLocker) Lock(key string) (success bool, err error)
Lock acquires local lock, compatible with gocron.Locker interface
This function implements sync.Mutex-based local lock, suitable for single-machine deployment scenarios. In distributed environments, multiple instances cannot coordinate, may lead to duplicate execution.
Parameters:
- key: lock key name, used to identify different locks
Returns:
- success: true means successfully acquired lock, false means lock is already held
- err: error occurred when acquiring lock (local lock will not return error)
Notes:
- Local lock only suitable for single-machine deployment, cannot prevent duplicate execution in multi-instance scenarios
- Lock will be automatically released when process exits
func (*LocalLocker) Unlock ¶
func (l *LocalLocker) Unlock(key string) error
Unlock releases local lock, compatible with gocron.Locker interface
Parameters:
- key: lock key name, must match the key name used in Lock
Returns:
- error: error occurred when releasing lock (local lock will not return error)
type Locker ¶
type Locker struct {
Cache *redis.Client // Redis client, if nil then use local lock
// contains filtered or unexported fields
}
Locker provides distributed lock functionality, compatible with gocron.Locker interface Supports both Redis distributed lock and local lock modes
func (*Locker) Lock ¶
Lock acquires distributed lock, compatible with gocron.Locker interface
This function uses redis-kit's HybridLocker which automatically falls back to local lock if Redis is unavailable. Lock default expiration time is DefaultLockTime seconds.
Parameters:
- key: lock key name, used to identify different locks
Returns:
- success: true means successfully acquired lock, false means lock is held by another process
- err: error occurred when acquiring lock (e.g., Redis connection error)
Notes:
- Lock has automatic expiration time, even if process crashes won't cause permanent deadlock (Redis mode)
- Local lock only suitable for single-machine deployment, cannot prevent duplicate execution in multi-instance scenarios
func (*Locker) Unlock ¶
Unlock releases distributed lock
This function uses redis-kit's HybridLocker which automatically falls back to local lock if Redis is unavailable.
Parameters:
- key: lock key name, must match the key name used in Lock
Returns:
- error: error occurred when releasing lock
Notes:
- Must use the same key as in Lock
- If lock has expired or is held by another process, will return error (Redis mode)
type RedisUserCache ¶
type RedisUserCache struct {
// contains filtered or unexported fields
}
RedisUserCache provides Redis-based user cache using cache-kit
func NewRedisUserCache ¶
func NewRedisUserCache(client *redis.Client) *RedisUserCache
NewRedisUserCache creates a new Redis user cache
func (*RedisUserCache) Exists ¶
func (c *RedisUserCache) Exists() (bool, error)
Exists checks if cache exists
func (*RedisUserCache) Get ¶
func (c *RedisUserCache) Get() ([]define.AllowListUser, error)
Get gets user list from Redis
func (*RedisUserCache) GetVersion ¶
func (c *RedisUserCache) GetVersion() (int64, error)
GetVersion gets cache version number
func (*RedisUserCache) Set ¶
func (c *RedisUserCache) Set(users []define.AllowListUser) error
Set stores user list to Redis and updates version number
type SafeUserCache ¶
type SafeUserCache struct {
// contains filtered or unexported fields
}
SafeUserCache provides thread-safe user cache using cache-kit MultiIndexCache Maintains multiple indexes to support fast queries by phone, mail, user_id
func NewSafeUserCache ¶
func NewSafeUserCache() *SafeUserCache
NewSafeUserCache creates a new thread-safe user cache
func (*SafeUserCache) Get ¶
func (c *SafeUserCache) Get() []define.AllowListUser
Get gets a copy of user list (thread-safe) Returns slice format to maintain API compatibility Return order matches the order when Set was called
func (*SafeUserCache) GetByMail ¶
func (c *SafeUserCache) GetByMail(mail string) (define.AllowListUser, bool)
GetByMail gets user by email (thread-safe, O(1) lookup)
func (*SafeUserCache) GetByPhone ¶
func (c *SafeUserCache) GetByPhone(phone string) (define.AllowListUser, bool)
GetByPhone gets user by phone number (thread-safe, O(1) lookup)
func (*SafeUserCache) GetByUserID ¶
func (c *SafeUserCache) GetByUserID(userID string) (define.AllowListUser, bool)
GetByUserID gets user by user ID (thread-safe, O(1) lookup)
func (*SafeUserCache) GetHash ¶
func (c *SafeUserCache) GetHash() string
GetHash gets cached hash value (thread-safe) If hash value is not calculated, returns empty string Using cached hash value can avoid redundant calculations and improve performance
func (*SafeUserCache) GetReadOnly ¶
func (c *SafeUserCache) GetReadOnly() []define.AllowListUser
GetReadOnly gets read-only view (actually returns copy, but semantically represents read-only) For read-only scenarios, recommend using Iterate method to avoid copying
func (*SafeUserCache) Iterate ¶
func (c *SafeUserCache) Iterate(fn func(user define.AllowListUser) bool)
Iterate iterates all users, avoiding copying entire slice (thread-safe) Callback function receives user data in insertion order If callback function returns false, iteration will stop
func (*SafeUserCache) Set ¶
func (c *SafeUserCache) Set(users []define.AllowListUser)
Set sets user list (thread-safe) Accepts slice format, internally converts to map for storage Preserves input order. Keeps users with at least one of phone or mail (email-only users supported).
func (*SafeUserCache) SetValidated ¶ added in v0.14.0
func (c *SafeUserCache) SetValidated(users []define.AllowListUser, opts identity.Options) error
SetValidated runs centralized identity validation (identifier uniqueness, optional explicit user_id requirement) BEFORE swapping the data into the shared cache. On a uniqueness/missing-id conflict it returns a typed error and leaves the existing cache contents untouched, so a bad remote/local rule set can never overwrite good data with a partially-deduped ("last-write-wins") set. On success the cache is replaced with the deterministically-ordered validated set.