Week 2 Challenge: SMTP Integration & Hugo Connection for Production Mail #65

New issue

Closed

opened 2025-06-17 20:49:00 +02:00 by Michael · 0 comments

Michael commented

2025-06-17 20:49:00 +02:00

(Migrated from gitea.dragons-at-work.de)

Objective

Transform furt-lua HTTP-Server from foundation to production-ready mail service with real SMTP integration.

Success Criteria (1 Week)

SMTP Integration: Real mail sending via mail.dragons-at-work.de:465
Environment Variables: FURT_MAIL_USERNAME/PASSWORD working
Hugo Integration: POST-based form handling from website
Production Config: HTTPS with lua-ssl
Error Handling: SMTP failures properly handled
Testing: End-to-end mail delivery verification

Technical Specifications

SMTP Configuration (Verified)

Server: mail.dragons-at-work.de:465
Security: SSL/TLS
Auth: SMTP-AUTH with ENV credentials
From: noreply@dragons-at-work.de
To: michael@dragons-at-work.de

Environment Variables Setup

export FURT_MAIL_USERNAME="your_email@dragons-at-work.de"
export FURT_MAIL_PASSWORD="your_smtp_password"

Hugo Integration Pattern

Endpoint: POST /v1/mail/send
Authentication: API-Key based (hugo-frontend-key)
Form Fields: name, email, message (+ optional subject)
Response: JSON success/error with request_id

Implementation Milestones

Day 1: SMTP Core

lua-smtp library integration or native socket SMTP
SSL/TLS connection to mail.dragons-at-work.de:465
Basic mail sending functionality

Day 2: Environment Integration

Environment variable handling in config/server.lua
Secure credential management
SMTP auth implementation

Day 3: Hugo Connection

API-Key authentication system
Hugo-compatible POST endpoint
Form validation and sanitization

Day 4: Production Hardening

HTTPS with lua-ssl
Error handling for SMTP failures
Rate limiting for mail endpoint

Day 5: Testing & Documentation

End-to-end mail delivery tests
Hugo integration testing
Documentation updates

Building on Week 1 Success

Week 1 Foundation ✅:

HTTP-Server working (< 1ms response)
JSON request/response handling
Error handling and validation
Testing framework established
Dependencies ready (lua-ssl ✅)

Week 2 Extension:

SMTP mail delivery (real functionality)
Production security (HTTPS, Auth)
Website integration (Hugo forms)

Security Requirements

API-Key Authentication for /v1/mail/send
IP Allowlisting for Hugo frontend
Input Sanitization for mail content
Rate Limiting to prevent abuse
HTTPS Only for production deployment

Testing Strategy

Unit Tests: SMTP connection and mail formatting
Integration Tests: End-to-end mail delivery
Hugo Tests: Form submission from website
Security Tests: Auth bypass attempts, injection tests

Expected Performance

Mail Delivery: < 5 seconds end-to-end
API Response: < 100ms (excluding SMTP time)
Concurrent Requests: Handle 10+ simultaneous form submissions
Memory Usage: < 15 MB total (HTTP + SMTP)

Success Definition

# End-to-end test should work:
curl -X POST https://api.dragons-at-work.de/v1/mail/send \
     -H "X-API-Key: hugo-frontend-key" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Test User",
       "email": "test@example.com",
       "message": "Hello from production Furt!"
     }'

# → Mail arrives at michael@dragons-at-work.de ✅
# → HTTP 200 with success response ✅

Dependencies on Week 1

Requires: Completed #63 (Week 1 HTTP-Server foundation)
Builds on: furt-lua/src/main.lua architecture

Next Steps After Week 2

Comment Service (sagjan integration)
Service Registry (multiple services)
C Integration (performance layer)
OpenBSD Migration (infrastructure sovereignty)

Priority: High - Production mail functionality critical for website launch
Effort: Small - Building on solid Week 1 foundation
Dependencies: Week 1 Complete ✅, SMTP credentials available

Session Goal: Ende der nächsten Session funktioniert echte Mail-Versendung von Hugo-Website zu michael@dragons-at-work.de

## Objective Transform furt-lua HTTP-Server from foundation to production-ready mail service with real SMTP integration. ## Success Criteria (1 Week) - [x] **SMTP Integration**: Real mail sending via mail.dragons-at-work.de:465 - [x] **Environment Variables**: FURT_MAIL_USERNAME/PASSWORD working - [x] **Hugo Integration**: POST-based form handling from website - [x] **Production Config**: HTTPS with lua-ssl - [x] **Error Handling**: SMTP failures properly handled - [x] **Testing**: End-to-end mail delivery verification ## Technical Specifications ### SMTP Configuration (Verified) - **Server:** mail.dragons-at-work.de:465 - **Security:** SSL/TLS - **Auth:** SMTP-AUTH with ENV credentials - **From:** noreply@dragons-at-work.de - **To:** michael@dragons-at-work.de ### Environment Variables Setup ```bash export FURT_MAIL_USERNAME="your_email@dragons-at-work.de" export FURT_MAIL_PASSWORD="your_smtp_password" ``` ### Hugo Integration Pattern - **Endpoint:** POST /v1/mail/send - **Authentication:** API-Key based (hugo-frontend-key) - **Form Fields:** name, email, message (+ optional subject) - **Response:** JSON success/error with request_id ## Implementation Milestones **Day 1: SMTP Core** - lua-smtp library integration or native socket SMTP - SSL/TLS connection to mail.dragons-at-work.de:465 - Basic mail sending functionality **Day 2: Environment Integration** - Environment variable handling in config/server.lua - Secure credential management - SMTP auth implementation **Day 3: Hugo Connection** - API-Key authentication system - Hugo-compatible POST endpoint - Form validation and sanitization **Day 4: Production Hardening** - HTTPS with lua-ssl - Error handling for SMTP failures - Rate limiting for mail endpoint **Day 5: Testing & Documentation** - End-to-end mail delivery tests - Hugo integration testing - Documentation updates ## Building on Week 1 Success **Week 1 Foundation ✅:** - HTTP-Server working (< 1ms response) - JSON request/response handling - Error handling and validation - Testing framework established - Dependencies ready (lua-ssl ✅) **Week 2 Extension:** - SMTP mail delivery (real functionality) - Production security (HTTPS, Auth) - Website integration (Hugo forms) ## Security Requirements - [ ] **API-Key Authentication** for /v1/mail/send - [ ] **IP Allowlisting** for Hugo frontend - [ ] **Input Sanitization** for mail content - [ ] **Rate Limiting** to prevent abuse - [ ] **HTTPS Only** for production deployment ## Testing Strategy - **Unit Tests:** SMTP connection and mail formatting - **Integration Tests:** End-to-end mail delivery - **Hugo Tests:** Form submission from website - **Security Tests:** Auth bypass attempts, injection tests ## Expected Performance - **Mail Delivery:** < 5 seconds end-to-end - **API Response:** < 100ms (excluding SMTP time) - **Concurrent Requests:** Handle 10+ simultaneous form submissions - **Memory Usage:** < 15 MB total (HTTP + SMTP) ## Success Definition ```bash # End-to-end test should work: curl -X POST https://api.dragons-at-work.de/v1/mail/send \ -H "X-API-Key: hugo-frontend-key" \ -H "Content-Type: application/json" \ -d '{ "name": "Test User", "email": "test@example.com", "message": "Hello from production Furt!" }' # → Mail arrives at michael@dragons-at-work.de ✅ # → HTTP 200 with success response ✅ ``` ## Dependencies on Week 1 **Requires:** Completed #63 (Week 1 HTTP-Server foundation) **Builds on:** furt-lua/src/main.lua architecture ## Next Steps After Week 2 1. **Comment Service** (sagjan integration) 2. **Service Registry** (multiple services) 3. **C Integration** (performance layer) 4. **OpenBSD Migration** (infrastructure sovereignty) **Priority:** High - Production mail functionality critical for website launch **Effort:** Small - Building on solid Week 1 foundation **Dependencies:** Week 1 Complete ✅, SMTP credentials available Session Goal: Ende der nächsten Session funktioniert echte Mail-Versendung von Hugo-Website zu michael@dragons-at-work.de