v1.0.0

Fallback-Mode Read

Last updated


This page explains how Get reads from memory and local JSON files in fallback mode, and what types values restored from files have.

Flow


graph TB
    Start[Get key] --> M{Memory hit?}
    M -->|Hit, valid| Ret[Return Data]
    M -->|Hit, expired| Exp[Delete memory, return Not found]
    M -->|Miss| F[Read MD5-sharded path]
    F -->|File missing| NF[Not found]
    F -->|JSON parse error| PF[Failed to parse]
    F -->|Expired| FE[Delete file, return Not found]
    F -->|Valid| Back[Backfill memory and return]
  1. graph TB
  2. Start[Get key] --> M{Memory hit?}
  3. M -->|Hit, valid| Ret[Return Data]
  4. M -->|Hit, expired| Exp[Delete memory, return Not found]
  5. M -->|Miss| F[Read MD5-sharded path]
  6. F -->|File missing| NF[Not found]
  7. F -->|JSON parse error| PF[Failed to parse]
  8. F -->|Expired| FE[Delete file, return Not found]
  9. F -->|Valid| Back[Backfill memory and return]

Steps


StepConditionBehaviorSource
1Memory hit, not expiredReturn immediatelyget.go:64-75
2Memory hit, expiredDelete the memory entry and return Not found; the file is not checked and is left to the background sweepget.go:68-72
3Memory missRead {DBPath}/{DB}/{md5[0:2]}/{md5[2:4]}/{md5[4:6]}/{md5}.jsonget.go:81-86
4File missingReturn Not foundget.go:85-87
5Content is not valid Cache JSONReturn Failed to parseget.go:89-93
6ExpiredDelete the file, return Not foundget.go:95-100
7ValidStore in the memory cache (the next read hits memory) and return Dataget.go:102-106

What Data Is Readable


Data sourceReadable in fallback mode
Values this instance Set during fallbackYes. Set writes memory first and then enqueues the file write, so the value is readable before the file exists
Values this instance read or wrote during normal modeYes, still in the memory cache
Files written by a previous process during fallbackYes, restored from file
Values that exist only in Redis and this instance never readNo; fallback mode does not touch Redis

Types After Restoring from File


The memory cache keeps the original Go value from write time; values restored from files are decoded by encoding/json into interface{}, so their types change:
Value at write timeOn a memory hitRestored from file
"hello"stringstring
42intfloat64
map[string]any{"uid": 1}map[string]any (uid is int)map[string]interface{} (uid is float64)
Custom structThe original structmap[string]interface{}

When a fixed type is required, convert with json.Marshal → json.Unmarshal into the target type instead of a direct type assertion.

Example: Reading from File After a Restart


  1. // Process A writes while Redis is down, flushes the batch, then exits
  2. if err := rf.Set("session:abc", map[string]any{"uid": 1}, time.Hour); err != nil {
  3. log.Fatal(err)
  4. }
  5. // Process B starts while Redis is still down → fallback mode; memory is empty, so it reads the file
  6. value, err := rf.Get("session:abc")
  7. if err != nil {
  8. log.Fatal(err)
  9. }
  10. uid := value.(map[string]interface{})["uid"].(float64) // float64 after restoring from file
  11. fmt.Println(uid)
中文