epirent-cache-proxy/README.md

Epirent Read‑Only Cache Proxy (Node/TS)

Reverse‑Proxy mit zentralem Cache (TTL + stale‑while‑revalidate) für die Epirent‑API. Alle GET/HEAD‑Requests werden 1:1 an Epirent weitergereicht, Antworten werden zwischengespeichert. Authentifizierung erfolgt serverseitig via X-EPI-NO-SESSION: True und X-EPI-ACC-TOK: <token>.

---

Features

• 100 % dynamischer Read‑Only‑Proxy
• Zentraler Cache mit TTL und stale‑while‑revalidate
• ETag/Last‑Modified‑Revalidation (falls vom Upstream geliefert)
• Schutz vor Thundering‑Herd durch pro‑Key In‑Flight‑Lock
• Optional: Redis als Shared Cache
• Ausführliches Debug‑Logging (DEBUG=1/2)
• Metriken (Prometheus + kleines Web‑Dashboard) auf zweitem Port (optional)

---

Voraussetzungen

• Node.js 20+ (oder Docker)
• Optional: Redis 7+ (für Shared Cache)

---

Konfiguration

.env anlegen (Beispiel in der .env.sample).

Hinweis: .env wird über dotenv geladen. Alternativ können Variablen vor dem Start im Shell‑Environment gesetzt werden.

---

Installation (ohne Docker)

npm ci
npm run build
npm start

Entwicklung

Zwei Debug Level (1 und 2) sind implementiert

• Linux/macOS:

DEBUG=1 npm run dev

• Windows PowerShell:

$env:DEBUG="1"; npm run dev

---

Docker

Build & Run

docker build -t epirent-cache .
docker run --rm -p 8080:8080 --env-file .env epirent-cache

docker-compose (mit Redis & Metriken)

services:
  cache-api:
    build: .
    env_file: .env
    ports:
      - "8080:8080"
      - "9090:9090"
    depends_on: [ redis ]

  redis:
    image: redis:7-alpine
    command: ["redis-server","--appendonly","yes"]
    volumes:
      - ./data/redis:/data

Start:

docker compose up -d

---

Endpunkte

• Proxy: GET /… → X-Cache-Status: HIT|MISS|MISS-EXPIRED|STALE|STALE-ERROR
• Health: GET /_healthz
• Purge: POST /_purge?secret=<PURGE_SECRET>&url=<VOLLE_UPSTREAM_URL>
• Metriken (zweiter Port): GET /metrics (Prometheus), GET / (Dashboard)

---

Systemd (optional)

[Unit]
Description=Epirent Read-Only Cache Proxy
After=network.target

[Service]
WorkingDirectory=/opt/epirent-cache
ExecStart=/usr/bin/node dist/server.js
EnvironmentFile=/opt/epirent-cache/.env
Restart=always
RestartSec=3
User=www-data
Group=www-data

[Install]
WantedBy=multi-user.target

Aktivieren:

sudo systemctl daemon-reload
sudo systemctl enable --now epirent-cache

---

Troubleshooting

502 Bad Gateway

• UPSTREAM_BASE prüfen (Schema/Host/Port)
• Direkt via curl testen:

curl -v "http://epirent.host.local:8080/api/..." -H "X-EPI-NO-SESSION: True" -H "X-EPI-ACC-TOK: DEIN_TOKEN"

• DEBUG=2 aktivieren und Logs prüfen
• Interne Zertifikate? Testweise TLS_REJECT_UNAUTHORIZED=0 (nicht dauerhaft!)

Keine Cache‑Treffer

• Accept unterscheidet sich zwischen Clients → gleiche Werte nutzen oder Vary‑Liste erweitern

Redis wird nicht genutzt

• REDIS_URL leer → In‑Memory LRU aktiv. REDIS_URL setzen und Service neu starten