Initial Commit with Working server and metrics

README.md

@@ -0,0 +1,146 @@
+# 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