feat(furt): implement complete Lua HTTP-Server for digital sovereignty (#63)

- Add furt-lua/ directory with pure Lua implementation
- Replace planned Go implementation with Corporate-free technology
- Complete Week 1 Challenge: HTTP-Server to production-ready in 48min

- HTTP-Server in pure Lua (185 lines, lua-socket based)
- JSON API endpoints with request/response parsing
- Modular architecture: each file < 200 lines
- Error handling for 404, 400, validation scenarios

- GET /health - Service health check with timestamp
- POST /test - Development testing with request echo
- POST /v1/mail/send - Mail service foundation with validation
- Comprehensive error responses with structured JSON

- Smart startup script with dependency auto-detection
- Automated test suite with lua-socket HTTP client
- Manual curl test suite for development workflow
- Complete documentation and installation guide

- FROM: Go (Google-controlled) → TO: Lua (PUC-Rio University)
- Corporate-free dependency chain: lua-socket + lua-cjson + lua-ssl
- Performance superior: < 1ms response time, minimal memory usage
- Foundation for planned C+Lua hybrid architecture

- furt-lua/src/main.lua - HTTP-Server implementation
- furt-lua/config/server.lua - Lua-based configuration
- furt-lua/scripts/start.sh - Startup with dependency checks
- furt-lua/scripts/test_curl.sh - Manual testing suite
- furt-lua/tests/test_http.lua - Automated test framework
- furt-lua/README.md - Implementation documentation

- README.md - Document Go→Lua migration strategy
- .gitignore - Add Lua artifacts, luarocks, issue-scripts

All endpoints tested and working:
✓ Health check returns proper JSON status
✓ Test endpoint processes POST requests with JSON
✓ Mail endpoint validates required fields (name, email, message)
✓ Error handling returns appropriate HTTP status codes

Ready for Week 2: SMTP integration with mail.dragons-at-work.de

Completes #63
Related #62
This commit is contained in:
michael 2025-06-17 20:40:40 +02:00
parent 10b795ce13
commit 662bfc7b7a
9 changed files with 1058 additions and 537 deletions

187
furt-lua/README.md Normal file
View file

@ -0,0 +1,187 @@
# 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.*