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

README.md Unescape Escape

Epirent Read‑Only Cache Proxy (Node/TS)