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:

# Arch Linux
pacman -S lua lua-socket lua-cjson

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

Installation

# 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

GET /health
→ {"status":"healthy","service":"furt","version":"1.0.0"}

Mail senden

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

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:

lua tests/test_http.lua

Manuelle Tests:

./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:

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

<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