RESTForge

Cache

Layer caching berbasis Redis dengan TTL, invalidasi otomatis, dan graceful degradation

RESTForge menyediakan Redis-based caching layer yang bekerja otomatis pada operasi READ dan melakukan invalidasi otomatis pada operasi WRITE. Cache meningkatkan performa API dengan menyimpan hasil query di Redis sehingga request berikutnya dengan parameter yang sama tidak perlu mengakses database.

Referensi Cepat (Quick Reference)

PropertiNilai
DependencyRedis Server 6.0+
AktivasiCACHE_ENABLED=true di file .env
Default TTL300 detik (5 menit)
InvalidasiOtomatis saat operasi WRITE (INSERT/UPDATE/DELETE)
Graceful degradationJika Redis down saat runtime, request langsung ke database
Endpoint di-cache/datatables, /read, /lookup (static dan filter), processor
Endpoint tidak di-cache/first, /lookup (dynamic keystroke), /read-composite, operasi WRITE

Konfigurasi (Configuration)

Koneksi Redis (Redis Connection)

config/production.env
REDIS_HOST=localhost
REDIS_PORT=6380
REDIS_PASSWORD=
REDIS_DB=0

Pengaturan Cache (Cache Settings)

config/production.env
CACHE_ENABLED=true
CACHE_TTL=300
VariableTipeDefaultKeterangan
CACHE_ENABLEDbooleanfalseAktifkan/nonaktifkan cache secara global
CACHE_TTLnumber300TTL (Time-To-Live) dalam detik, berlaku untuk semua operasi

RESTForge menggunakan satu nilai TTL untuk semua operasi karena semua endpoint yang di-cache query ke tabel yang sama, dan saat operasi WRITE terjadi, semua cache endpoint tersebut di-invalidasi sekaligus.

Endpoint yang Di-cache (Cached Endpoints)

EndpointCache TypeIdentifier
POST /datatablesdatatablesMD5 hash dari parameter (search, filter, pagination, sort)
POST /readlistMD5 hash dari parameter (filter, pagination)
POST /lookup (static)lookup_staticall (seluruh data)
POST /lookup (filter)lookup_filterMD5 hash dari where clause

Endpoint yang Tidak Di-cache

EndpointAlasan
POST /firstSingle record, selalu butuh data terbaru
GET /lookup (keystroke)Variasi input terlalu tinggi, hit rate rendah
POST /read-compositeData composite (header + detail), kompleksitas tinggi
Operasi WRITE/create, /update, /delete tidak di-cache

Cara Kerja (How It Works)

Alur Operasi READ

POST /api/{project}/{endpoint}/datatables
  │
  ├── Cache ENABLED?
  │     ├── Ya → Build cache key → Cek Redis
  │     │         ├── HIT  → Return cached result (~1-3ms)
  │     │         └── MISS → Query database (~50-200ms) → Simpan ke Redis → Return
  │     └── Tidak → Query database langsung
  │
  └── HTTP Response

Alur Invalidasi saat WRITE

POST /api/{project}/{endpoint}/create (atau /update, /delete)
  │
  ├── Execute SQL (INSERT/UPDATE/DELETE)
  │     ├── COMMIT berhasil
  │     │     ├── Self invalidation: hapus rf:{project}:{endpoint}:*
  │     │     └── Cascade invalidation: hapus cache processor yang bergantung pada tabel ini
  │     └── ROLLBACK → Tidak ada invalidasi
  │
  └── HTTP Response

Format Cache Key

rf:{project}:{endpoint}:{type}:{identifier}

Contoh:

rf:mini-inventory:supplier:datatables:a1b2c3d4
rf:mini-inventory:supplier:read:e5f6g7h8
rf:mini-inventory:supplier:lookup_static:all

Cache pada Processor

Processor dapat memanfaatkan cache melalui konfigurasi cache di file payload JSON:

payload/stock-management.json (processor section)
{
    "name": "stock-card",
    "method": "POST",
    "cache": {
        "enabled": true,
        "ttl": 300,
        "invalidates": ["stock_inbound", "stock_outbound", "item_product"]
    }
}
PropertyTipeKeterangan
cache.enabledbooleanAktifkan cache untuk processor ini
cache.ttlnumberTTL dalam detik (override global CACHE_TTL)
cache.invalidatesstring[]Daftar nama endpoint CRUD yang memicu invalidasi cache processor ini

Array invalidates berisi nama-nama endpoint CRUD. Saat salah satu endpoint tersebut melakukan operasi WRITE, cache processor ini ikut ter-invalidasi. Contoh: jika ada INSERT di endpoint stock-inbound, cache processor stock-card otomatis dihapus.

File processor tidak perlu dimodifikasi karena cache handling sepenuhnya ditangani oleh router yang di-generate. Generator juga memiliki mutation guard yang otomatis mengabaikan cache.enabled pada processor bertipe mutasi (PUT/DELETE atau SQL mengandung INSERT/UPDATE/DELETE).

Graceful Degradation

Cache dirancang dengan prinsip non-blocking. Kegagalan cache tidak mengganggu operasi utama.

SkenarioPerilaku
Redis tidak tersedia saat startupServer berhenti dengan error message
Redis terputus saat runtimeCache GET return null, request langsung ke database
Cache SET errorDiabaikan, response tetap dikirim ke client
Registry population errorCascade invalidation di-skip, cache expire via TTL

Monitoring dan Debugging

Log Messages

EventLevelKeterangan
cache_hitinfoData ditemukan di cache
cache_missinfoData tidak ada di cache, query ke database
cache_setinfoData disimpan ke cache
cache_invalidate_patterninfoCache di-invalidasi setelah operasi WRITE

Redis CLI

# Lihat semua cache key untuk satu endpoint
redis-cli -p 6380 KEYS "rf:mini-inventory:supplier:*"

# Cek sisa TTL
redis-cli -p 6380 TTL "rf:mini-inventory:supplier:datatables:a1b2c3d4"

# Hapus semua cache satu endpoint
redis-cli -p 6380 --scan --pattern "rf:mini-inventory:supplier:*" | xargs redis-cli -p 6380 DEL

Panduan TTL (TTL Guide)

TTLSkenarioTrade-off
60 detikData sering berubah, freshness prioritasHit rate lebih rendah
300 detik (default)Keseimbangan freshness dan performaCocok untuk sebagian besar kasus
1800 detikData stabil, performa prioritasData bisa stale sampai 30 menit
3600 detikData hampir tidak pernah berubahCocok untuk data referensi/master

Langkah Selanjutnya (Next Steps)

On this page

Referensi Cepat (Quick Reference)Konfigurasi (Configuration)Koneksi Redis (Redis Connection)Pengaturan Cache (Cache Settings)Endpoint yang Di-cache (Cached Endpoints)Endpoint yang Tidak Di-cacheCara Kerja (How It Works)Alur Operasi READAlur Invalidasi saat WRITEFormat Cache KeyCache pada ProcessorGraceful DegradationMonitoring dan DebuggingLog MessagesRedis CLIPanduan TTL (TTL Guide)Langkah Selanjutnya (Next Steps)