furt/docs/lua-implementation-reference.md

# Furt Lua HTTP-Server

**Pure Lua HTTP-Server für Dragons@Work API-Gateway**  
*Week 1 Implementation - Digital Sovereignty Project*

## Überblick

Furt ist der erste Schritt zur Migration des API-Gateways von Go auf C+Lua für maximale digitale Souveränität. Diese Implementierung startet mit reinem Lua und bildet die Grundlage für die spätere C+Lua-Hybridarchitektur.

## Funktionen

- ✅ **HTTP-Server** mit lua-socket
- ✅ **JSON API** Endpoints
- ✅ **Request/Response Parsing**
- ✅ **Basic Routing**
- ✅ **Mail-Service-Grundgerüst** 
- ✅ **Health-Check**
- ✅ **Error Handling**
- ✅ **Automated Tests**

## Dependencies

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

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

**Ubuntu:**
```bash
apt install lua5.4 lua-socket lua-cjson
```

## Projektstruktur

```
furt-lua/
├── src/
│   └── main.lua              # HTTP-Server (< 200 Zeilen)
├── config/
│   └── server.lua            # Konfiguration 
├── scripts/
│   ├── start.sh              # Server starten
│   └── test_curl.sh          # Manuelle Tests
├── tests/
│   └── test_http.lua         # Automatische Tests
└── README.md
```

## Installation & Start

**1. Repository Setup:**
```bash
mkdir furt-lua
cd furt-lua

# Dateien erstellen (aus Claude-Artefakten)
# main.lua, config/server.lua, scripts/start.sh, etc.
```

**2. Executable machen:**
```bash
chmod +x scripts/start.sh
chmod +x scripts/test_curl.sh
```

**3. Server starten:**
```bash
./scripts/start.sh
```

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

## API-Endpoints

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

### Test Endpoint
```bash
POST /test
Content-Type: application/json
{"test": "data"}
→ {"message":"Test endpoint working"}
```

### Mail Service
```bash
POST /v1/mail/send
Content-Type: application/json
{
  "name": "Test User",
  "email": "test@example.com", 
  "message": "Test message"
}
→ {"success":true,"message":"Mail queued for sending"}
```

## Testing

**Automatische Tests:**
```bash
# Server muss laufen!
lua tests/test_http.lua
```

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

**Quick Test:**
```bash
curl -X POST http://127.0.0.1:8080/test \
     -H "Content-Type: application/json" \
     -d '{"test":"data"}'
```

## Konfiguration

**Mail-SMTP (Environment Variables):**
```bash
export FURT_MAIL_USERNAME="your_email@dragons-at-work.de"
export FURT_MAIL_PASSWORD="your_password"
```

**Server-Config:** `config/server.lua`
- Port, Host ändern
- API-Keys definieren  
- SMTP-Einstellungen

## Week 1 Status

✅ **Tag 1:** HTTP-Server basic functionality  
✅ **Tag 2:** Request/Response parsing  
✅ **Tag 3:** JSON handling, Mail endpoint structure  
✅ **Tag 4:** Routing, Error handling  
✅ **Tag 5:** Testing, Documentation  

**Success Criteria erreicht:**
- ✅ `curl -X POST http://localhost:8080/test` → HTTP 200 ✓
- ✅ Alle Module < 200 Zeilen ✓
- ✅ JSON Request/Response ✓
- ✅ /v1/mail/send Endpoint ✓

## Nächste Schritte (Week 2)

1. **SMTP-Integration** - Echte Mail-Versendung
2. **API-Key-Authentication** - Security-Layer
3. **Hugo-Integration** - POST-based Form-Handling
4. **HTTPS** mit lua-ssl

## Technologie-Philosophie

- **Lua:** PUC-Rio University (echte Unabhängigkeit)
- **Minimale Dependencies:** < 5 externe Libraries
- **Modulare Architektur:** < 200 Zeilen pro Datei
- **Transparenter Code:** Jede Zeile verstehbar
- **Corporate-frei:** Keine Google/Microsoft/etc. Dependencies

**Teil der Dragons@Work Tech-Souveränitätsstrategie**

## Development

**Code-Stil:**
- Module < 200 Zeilen
- Funktionen < 50 Zeilen
- Klare, lesbare Namen
- Error-Handling für alles

**Testing-Pattern:**
- Jede Funktion testbar
- HTTP-Integration-Tests
- curl-basierte Verifikation

---

**Week 1 Challenge: COMPLETE ✅**  
*Foundation für souveräne API-Gateway-Architektur gelegt.*