v1.0.0

pardnchiu/go-redis-fallback

Last updated

NoteThis README was generated by SKILL, get the ZH version from here.

WarningArchived on 2026-10-30. go-redis-fallback is no longer maintained. The final release is v1.0.0; go get github.com/pardnchiu/go-redis-fallback remains available, but no new features, bug fixes, or security updates will be published, and issues and pull requests are no longer accepted.



KEEP READING WHEN REDIS GOES DOWN!


Go ReferenceReleaseLicense




A Go Redis fallback library with in-memory and local file tiers, health-check recovery, and TTL-preserving resync

Table of Contents



Features


go get github.com/pardnchiu/go-redis-fallback · Documentation

  • Three-Tier Read Fallback — Get queries the memory cache, Redis, and local JSON files in order and returns on the first hit, so reads keep working while Redis is unreachable.
  • Mode Switch on Read Failure — When Redis reads exhaust their retries, the call switches to fallback mode on the spot, starts the health checker, and answers from the local tiers in the same call.
  • Read-Repair — In normal mode, memory-cache hits are written back to Redis in the background, filling in keys the recovery batch did not cover.
  • Full Resync on Recovery — Once a health-check ping succeeds, the library loads local JSON files into memory, pipelines them to Redis in batches of 100 with their remaining TTL, then removes the local files.
  • Lazy Expiry on Read — Every tier checks TTL on read and drops expired entries from both memory and disk, backed by a background sweep every 30 seconds.

Architecture


Full Architecture

graph TB
    Get[Get] --> Mode{Health State}
    Mode -->|Normal| Mem1[Memory Cache]
    Mem1 -->|Miss| Redis[(Redis with MaxRetry)]
    Mem1 -->|Hit| Repair[Background write-back to Redis]
    Redis -->|Retries exhausted| Fallback[Switch to Fallback Mode]
    Mode -->|Fallback| Mem2[Memory Cache]
    Fallback --> Mem2
    Mem2 -->|Miss| File[Local JSON File]
    Fallback --> Checker[Health-Check Ticker]
    Checker -->|Ping OK| Recover[Resync Redis and Remove Files]
  1. graph TB
  2. Get[Get] --> Mode{Health State}
  3. Mode -->|Normal| Mem1[Memory Cache]
  4. Mem1 -->|Miss| Redis[(Redis with MaxRetry)]
  5. Mem1 -->|Hit| Repair[Background write-back to Redis]
  6. Redis -->|Retries exhausted| Fallback[Switch to Fallback Mode]
  7. Mode -->|Fallback| Mem2[Memory Cache]
  8. Fallback --> Mem2
  9. Mem2 -->|Miss| File[Local JSON File]
  10. Fallback --> Checker[Health-Check Ticker]
  11. Checker -->|Ping OK| Recover[Resync Redis and Remove Files]

License


This project is licensed under the MIT LICENSE.

Author


Just open an issue to share an idea.
go-redis-fallback contributors


©️ 2025 邱敬幃 Pardn Chiu
中文