furt/README.md

# Furt API Gateway

**HTTP-Server in Lua für Service-Integration**

## Überblick

Furt ist ein HTTP-Server der verschiedene Services unter einer API vereint. Aktuell unterstützt es Mail-Versendung über SMTP und bietet eine einfache JSON-API für Web-Integration.

## Features

- HTTP-Server mit JSON-APIs
- Mail-Versendung über SMTP
- Request-Routing und Authentication
- Health-Check-Endpoints
- Konfigurierbare Rate-Limiting
- Hugo/Website-Integration

## Dependencies

**Erforderlich:**
- `lua` 5.4+
- `lua-socket` (HTTP-Server)
- `lua-cjson` (JSON-Verarbeitung)

**Installation:**
```bash
# Arch Linux
pacman -S lua lua-socket lua-cjson

# Ubuntu/Debian
apt install lua5.4 lua-socket lua-cjson
```

## Installation

```bash
# Repository klonen
git clone <repository-url>
cd furt

# Scripts ausführbar machen
chmod +x scripts/*.sh

# Server starten
./scripts/start.sh
```

**Server läuft auf:** http://127.0.0.1:8080

## API-Endpoints

### Health Check
```bash
GET /health
→ {"status":"healthy","service":"furt","version":"1.0.0"}
```

### Mail senden
```bash
POST /v1/mail/send
Content-Type: application/json

{
  "name": "Name",
  "email": "sender@example.com",
  "message": "Nachricht"
}

→ {"success":true,"message":"Mail sent"}
```

## Konfiguration

**Environment Variables (.env):**
```bash
FURT_MAIL_HOST=mail.example.com
FURT_MAIL_PORT=587
FURT_MAIL_USERNAME=user@example.com
FURT_MAIL_PASSWORD=password
FURT_MAIL_TO=empfaenger@example.com
```

**Server-Config (config/server.lua):**
- Port und Host-Einstellungen
- API-Key-Konfiguration
- Rate-Limiting-Parameter

## Testing

**Automatische Tests:**
```bash
lua tests/test_http.lua
```

**Manuelle Tests:**
```bash
./scripts/test_curl.sh

# Oder direkt:
curl -X POST http://127.0.0.1:8080/v1/mail/send \
     -H "Content-Type: application/json" \
     -d '{"name":"Test","email":"test@example.com","message":"Test"}'
```

## Deployment

**OpenBSD:**
- rc.d-Script in `deployment/openbsd/`
- Systemd-Integration über Scripts

**Production-Setup:**
```bash
# Environment-Config kopieren
cp .env.example .env.production
# → SMTP-Credentials anpassen

# Production-Mode starten
export FURT_ENV=production
./scripts/start.sh
```

## Projektstruktur

```
furt/
├── src/                    # Lua-Source-Code
│   ├── main.lua           # HTTP-Server
│   ├── routes/            # API-Endpoints
│   └── smtp.lua           # Mail-Integration
├── config/                # Konfiguration
├── scripts/               # Start/Test-Scripts
├── tests/                 # Test-Suite
└── deployment/            # System-Integration
```

## Hugo-Integration

**Shortcode-Beispiel:**
```html
<form action="http://your-server:8080/v1/mail/send" method="POST">
  <input name="name" type="text" required>
  <input name="email" type="email" required>
  <textarea name="message" required></textarea>
  <button type="submit">Senden</button>
</form>
```

## Development

**Code-Struktur:**
- Module unter 200 Zeilen
- Funktionen unter 50 Zeilen
- Klare Fehlerbehandlung
- Testbare Komponenten

**Dependencies minimal halten:**
- Nur lua-socket und lua-cjson
- Keine externen HTTP-Libraries
- Standard-Lua-Funktionen bevorzugen