# 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)

```bash
npm ci
npm run build
npm start
```

### Entwicklung
Zwei Debug Level (1 und 2) sind implementiert

- Linux/macOS:
```bash
DEBUG=1 npm run dev
```

- Windows PowerShell:
```powershell
$env:DEBUG="1"; npm run dev
```

---

## Docker

### Build & Run

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

### docker-compose (mit Redis & Metriken)

```yaml
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:
```bash
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)

```ini
[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:
```bash
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:
```bash
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