diff --git a/Health-Endpoint.md b/Health-Endpoint.md new file mode 100644 index 0000000..1ae35e4 --- /dev/null +++ b/Health-Endpoint.md @@ -0,0 +1,366 @@ +# Health Endpoint + +**System-Monitoring und Service-Diagnostics** + +## Endpoint + +``` +GET /health +``` + +**Zweck:** Öffentlicher Health-Check für Monitoring-Systeme. Zeigt Service-Status, Version-Informationen und Feature-Verfügbarkeit. + +## Authentication + +**Keine Authentication erforderlich** - der Health-Endpoint ist öffentlich zugänglich für Monitoring-Systeme. + +**Warum öffentlich:** Monitoring-Tools müssen den Service-Status prüfen können, auch wenn die API-Authentifizierung ausgefallen ist. + +## Response Format + +### Healthy System Response (HTTP 200) + +```json +{ + "status": "healthy", + "service": "furt-lua", + "version": "0.1.2", + "content_hash": "abc123def456", + "vcs_info": { + "type": "git", + "hash": "7a8b9c0d", + "branch": "main" + }, + "timestamp": 1632150000, + "source": "merkwerk", + "features": { + "smtp_configured": true, + "auth_enabled": true, + "rate_limiting": true, + "rate_limits": { + "default_rpm": 60, + "burst_size": 10 + }, + "merkwerk_integrated": true + } +} +``` + +### Degraded System Response (HTTP 200) + +```json +{ + "status": "degraded", + "service": "furt-lua", + "version": "0.1.2", + "timestamp": 1632150000, + "features": { + "smtp_configured": false, + "auth_enabled": true, + "rate_limiting": true, + "merkwerk_integrated": false + }, + "issues": [ + "SMTP configuration missing", + "merkwerk integration not available" + ] +} +``` + +## Response Fields + +### Core Fields + +| Field | Type | Description | +|-------|------|-------------| +| `status` | string | `healthy`, `degraded`, or `unhealthy` | +| `service` | string | Service identifier (`furt-lua`) | +| `version` | string | Current service version | +| `timestamp` | integer | Unix timestamp of health check | + +### Version Information + +| Field | Type | Description | +|-------|------|-------------| +| `content_hash` | string | Content verification hash | +| `vcs_info` | object | Version control information | +| `vcs_info.type` | string | VCS type (`git`, `none`) | +| `vcs_info.hash` | string | Commit hash | +| `vcs_info.branch` | string | Git branch name | +| `source` | string | Version info source (`merkwerk`, `fallback-no-merkwerk`) | + +### Feature Status + +| Field | Type | Description | +|-------|------|-------------| +| `features.smtp_configured` | boolean | Mail service availability | +| `features.auth_enabled` | boolean | API-Key authentication status | +| `features.rate_limiting` | boolean | Rate limiting functionality | +| `features.rate_limits` | object | Rate limiting configuration | +| `features.merkwerk_integrated` | boolean | merkwerk version tracking | + +## Status Levels + +### `healthy` +- Alle Kern-Features funktionsfähig +- SMTP-Konfiguration vorhanden +- Authentication funktioniert +- Keine kritischen Issues + +### `degraded` +- Service läuft, aber mit eingeschränkter Funktionalität +- Möglicherweise fehlende SMTP-Konfiguration +- Nicht-kritische Components offline +- API bleibt verfügbar + +### `unhealthy` +- Service nicht betriebsbereit +- Kritische Components ausgefallen +- API möglicherweise nicht verfügbar + +**Warum gestufte Status:** Monitoring-Systeme können zwischen "funktioniert perfekt", "funktioniert eingeschränkt" und "ist kaputt" unterscheiden. + +## merkwerk Integration + +**merkwerk** ist das Dragons@Work Version-Tracking-System. Es bietet: + +### Version Information +- **Precise Version:** Exakte Versionsnummer (nicht nur Git-Tag) +- **Content Hash:** Verifikation des Code-Inhalts +- **VCS Integration:** Git-Commit und Branch-Information +- **Build Metadata:** Build-Zeitpunkt und Umgebung + +### Fallback Behavior +Wenn merkwerk nicht verfügbar ist: + +```json +{ + "service": "furt-lua", + "version": "?.?.?", + "content_hash": "unknown", + "vcs_info": { + "type": "none", + "hash": "", + "branch": "" + }, + "source": "fallback-no-merkwerk" +} +``` + +**Warum Fallback:** Service funktioniert auch ohne merkwerk-Integration. Version-Tracking ist nice-to-have, nicht kritisch. + +## Feature Detection + +### SMTP Configuration +```json +"smtp_configured": true/false +``` + +**Checked:** Ob `config.smtp_default.host` konfiguriert ist. +**Purpose:** Monitoring kann erkennen ob Mail-Service funktionsfähig ist. + +### Rate Limiting Details +```json +"rate_limits": { + "default_rpm": 60, + "burst_size": 10 +} +``` + +**Information:** Aktuelle Rate-Limiting-Konfiguration. +**Purpose:** Clients können ihre Request-Rate entsprechend anpassen. + +## Development Test Endpoint + +``` +GET /test +``` + +**Zweck:** Development-Testing ohne Side-Effects. +**Status:** Nur verfügbar wenn in Konfiguration aktiviert. + +### Test Response (HTTP 200) + +```json +{ + "message": "Test endpoint working", + "received_data": null, + "headers_count": 8, + "warning": "This is a development endpoint (enabled via config)" +} +``` + +### Test Disabled (HTTP 404) + +Wenn Test-Endpoint in Konfiguration deaktiviert: + +```json +{ + "error": "Endpoint not found" +} +``` + +**Warum optional:** Test-Endpoint soll in Production deaktiviert werden können. + +## Monitoring Integration + +### Nagios/Icinga + +```bash +#!/bin/bash +# check_furt_health.sh + +RESPONSE=$(curl -s http://localhost:7811/health) +STATUS=$(echo $RESPONSE | jq -r '.status') + +case $STATUS in + "healthy") + echo "OK - Furt Gateway healthy" + exit 0 + ;; + "degraded") + echo "WARNING - Furt Gateway degraded" + exit 1 + ;; + "unhealthy") + echo "CRITICAL - Furt Gateway unhealthy" + exit 2 + ;; + *) + echo "UNKNOWN - Could not determine Furt status" + exit 3 + ;; +esac +``` + +### Prometheus + +```yaml +# prometheus.yml +scrape_configs: + - job_name: 'furt-gateway' + metrics_path: '/health' + static_configs: + - targets: ['api.dragons-at-work.de:443'] +``` + +**Health-to-Metrics Mapping:** +- `status="healthy"` → `furt_health_status = 1` +- `status="degraded"` → `furt_health_status = 0.5` +- `status="unhealthy"` → `furt_health_status = 0` + +### Load Balancer Health Checks + +```nginx +# nginx upstream health check +upstream furt_backend { + server api.example.com:7811; + # Health check via /health endpoint +} +``` + +```haproxy +# HAProxy health check +backend furt_servers + option httpchk GET /health + server furt1 api.example.com:7811 check +``` + +## Integration Examples + +### Simple Status Check + +```bash +curl -s http://localhost:7811/health | jq '.status' +# Output: "healthy" +``` + +### Version Information + +```bash +curl -s http://localhost:7811/health | jq '.version' +# Output: "0.1.2" +``` + +### Feature Status + +```bash +curl -s http://localhost:7811/health | jq '.features.smtp_configured' +# Output: true +``` + +### Complete Status Script + +```bash +#!/bin/bash +# furt_status.sh - Complete health check + +HEALTH_URL="http://localhost:7811/health" +RESPONSE=$(curl -s $HEALTH_URL) + +if [ $? -ne 0 ]; then + echo "ERROR: Could not reach Furt Gateway" + exit 1 +fi + +STATUS=$(echo $RESPONSE | jq -r '.status') +VERSION=$(echo $RESPONSE | jq -r '.version') +SMTP=$(echo $RESPONSE | jq -r '.features.smtp_configured') + +echo "Furt Gateway Status: $STATUS" +echo "Version: $VERSION" +echo "SMTP Configured: $SMTP" + +if [ "$STATUS" = "healthy" ]; then + echo "✓ All systems operational" + exit 0 +elif [ "$STATUS" = "degraded" ]; then + echo "⚠ System degraded but functional" + exit 1 +else + echo "✗ System unhealthy" + exit 2 +fi +``` + +## Troubleshooting + +### Common Issues + +**Health endpoint not responding:** +- Service nicht gestartet: `systemctl status furt` +- Port nicht offen: `netstat -ln | grep 7811` +- Firewall blockiert: Prüfe iptables/pf-Regeln + +**Status "degraded":** +- SMTP-Konfiguration prüfen +- Log-Files auf Errors checken +- Disk-Space und Memory prüfen + +**merkwerk not integrated:** +- merkwerk-Package fehlt oder fehlerhaft installiert +- Funktionalität bleibt verfügbar, nur Version-Info limitiert + +### Debug Information + +```bash +# Detaillierte Response anzeigen +curl -s http://localhost:7811/health | jq . + +# Nur Feature-Status +curl -s http://localhost:7811/health | jq '.features' + +# Version-Tracking-Status +curl -s http://localhost:7811/health | jq '.source' +``` + +### Log Correlation + +Health-Endpoint-Aufrufe erscheinen in den Server-Logs: + +``` +[2024-09-10 12:34:56] Health endpoint called - Status: healthy +[2024-09-10 12:34:56] merkwerk health info: version=0.1.2, source=merkwerk +``` + +**Request-ID:** Health-Checks erhalten keine Request-ID da sie stateless sind. \ No newline at end of file