michael
be3b9614d0
- Remove Go artifacts (cmd/, internal/, pkg/, go.mod) - Move furt-lua/* content to repository root - Restructure as clean src/, config/, scripts/, tests/ layout - Rewrite README.md as practical tool documentation - Remove timeline references and marketing language - Clean .gitignore from Go-era artifacts - Update config/server.lua with example.org defaults - Add .env.production to .gitignore for security Repository now ready for open source distribution with minimal, focused structure and generic configuration templates. close issue DAW/furt#86
160 lines
3.2 KiB
Markdown
160 lines
3.2 KiB
Markdown
# 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
|
|
|