v1.0.0

Local File Format

Last updated


This page documents the path rule and content format of the local JSON files written during fallback, for troubleshooting or manual inspection.

Path Rule


getPath (unit.go:11-24) shards files into three directory levels by the key's hexadecimal MD5:
  1. {DBPath}/{DB}/{md5[0:2]}/{md5[2:4]}/{md5[4:6]}/{md5}.json

SegmentSource
DBPathOptions.DBPath, default ./files/redisFallback/db
DBRedis.DB, default 0; files for different DBs never mix
md5The 32-character hexadecimal md5(key)

Example: when the MD5 of key user:1 is bdb1dd105679979ca82b28edd1c8ccd2, the file is ./files/redisFallback/db/0/bd/b1/dd/bdb1dd105679979ca82b28edd1c8ccd2.json.

Finding the File for a Key


  1. key="user:1"
  2. h=$(printf '%s' "$key" | md5) # on Linux use: md5sum | cut -d' ' -f1
  3. cat "./files/redisFallback/db/0/${h:0:2}/${h:2:2}/${h:4:2}/${h}.json"

File Content


Each file is the JSON of one Cache structure:
  1. {
  2. "key": "user:1",
  3. "data": {"name": "pardn"},
  4. "type": "map[string]interface {}",
  5. "timestamp": 1791139200,
  6. "ttl": 1800
  7. }

FieldTypeDescription
keystringThe original key; the recovery resync uses it as the Redis key
dataanyThe written value
typestringreflect.TypeOf(value).String() at write time; informational only, unused on read
timestampint64Unix seconds at write time
ttlint64TTL in seconds; omitted when 0, meaning no expiry

File Lifecycle


EventFile
Set in fallback modeWritten in a batch (or synchronously when the queue is full)
Del (any mode)Deleted
Expiry found on readDeleted (normal-mode memory hit, fallback-mode file read)
Background sweep finds an expired memory entryDeleted
Recovery resync completesAll deleted, along with empty subdirectories; {DBPath}/{DB} is kept

The Path type (type.go:85-89) is the return value of getPath; all its fields are unexported, so it cannot be constructed or read from outside the package.
中文