furt/devdocs/furt_konzept.md

# Furt: API-Gateway im Einklang mit digitaler Souveränität

**Erstellt:** 03. Juni 2025  
**Letzte Aktualisierung:** 17. Juni 2025  
**Version:** 2.0  
**Verantwortlich:** DAW-Team  
**Dateipfad:** devdocs/KONZEPT.md

## Zweck dieses Dokuments

Dieses Dokument definiert das überarbeitete Konzept für Furt basierend auf der Dragons@Work Tech-Reference und dem Prinzip der maximalen technologischen Souveränität. Das System wird von Go auf C + Lua umgestellt, um Corporate-Capture zu vermeiden.

## Grund für die Überarbeitung

Die ursprüngliche Go-basierte Architektur widerspricht den Prinzipien digitaler Souveränität:
- **Go ist Google-controlled** (Proxy, Module-Summen, Telemetrie)
- **Corporate-Abhängigkeit** durch Go-Ökosystem
- **Nicht im Einklang** mit der Tech-Reference

## 1. Neue Projektvision und Philosophie

Furt (germanisch für "Durchgang durch Wasser") ist ein **selbst-gehostetes API-Gateway-System** basierend auf **C + Lua**, das vollständig im Einklang mit den Prinzipien digitaler Souveränität steht:

### Kernprinzipien
- **C als Basis** - Bewährt seit 50+ Jahren, strukturell uncapturable
- **Lua für Logik** - PUC-Rio University, echte akademische Unabhängigkeit
- **Minimale Dependencies** - Nur GCC + musl, keine Corporate-Libraries
- **Maximale Transparenz** - Jede Zeile Code verstehbar und kontrollierbar
- **Ultra-Low-Tech** - Ressourcenschonend, lange Lebensdauer

### Abgrenzung zu Corporate-Lösungen
- **Keine Cloud-Dependencies** 
- **Keine Corporate-Runtimes** (Go, Node.js, etc.)
- **Keine Black-Box-Components**
- **Keine Vendor-Lock-ins**

## 2. Technische Architektur (C + Lua)

### 2.1 Technology-Stack

**Core:**
- **C (GCC + musl)** - Gateway-Kern, HTTP-Server, System-Interface
- **Lua 5.4** - Business-Logic, Konfiguration, Service-Scripts
- **LMDB** - Datenbank (Howard Chu/Symas, keine VC-Dependencies)
- **OpenBSD httpd** - Als Reverse-Proxy (langfristig, Apache-Migration)

**Konfiguration:**
- **Lua-Scripts** statt YAML (native, programmierbar, validierbar)
- **LMDB-Storage** für Konfiguration und State
- **Environment-Variables** nur für Secrets

**Services:**
- **C-Module** mit Lua-Scripten für Business-Logic
- **Minimale HTTP-Implementation** in C
- **Lua-basierte** Request-Handler

### 2.2 Projektstruktur

```
furt/
├── src/
│   ├── core/                      # C Core-Implementation
│   │   ├── http_server.c          # Minimal HTTP-Server
│   │   ├── router.c               # Request-Routing
│   │   ├── proxy.c                # Service-Proxy
│   │   ├── auth.c                 # Authentifizierung
│   │   └── main.c                 # Entry Point
│   ├── lua/                       # Lua-Scripts
│   │   ├── gateway/               # Gateway-Logic
│   │   │   ├── config.lua         # Konfigurationsmanagement
│   │   │   ├── middleware.lua     # Middleware-Chain
│   │   │   └── services.lua       # Service-Registry
│   │   └── services/              # Service-Logic
│   │       ├── formular2mail.lua  # Mail-Service
│   │       └── sagjan.lua         # Comment-Service
│   └── include/                   # C Header-Files
│       ├── furt.h                 # Main Header
│       ├── http.h                 # HTTP Definitions
│       └── lua_bridge.h           # C ↔ Lua Interface
├── config/                        # Konfiguration
│   ├── gateway.lua                # Gateway-Konfiguration
│   └── services/                  # Service-Configs
│       ├── formular2mail.lua
│       └── sagjan.lua
├── build/                         # Build-System
│   ├── Makefile                   # Haupt-Makefile
│   ├── config.mk                  # Build-Konfiguration
│   └── deps/                      # Dependencies (Lua, LMDB)
├── docs/                          # Dokumentation
│   ├── installation.md            # Installation
│   ├── configuration.md           # Konfiguration
│   └── development.md             # Entwicklung
├── scripts/                       # Build & Deployment
│   ├── build.sh                   # Build-Script
│   ├── install.sh                 # Installation
│   └── service-generator.sh       # Service-Generator
├── tests/                         # Tests
│   ├── unit/                      # Unit-Tests (C)
│   ├── integration/               # Integration-Tests
│   └── lua/                       # Lua-Tests
└── examples/                      # Beispiele
    ├── hugo/                      # Hugo-Integration
    └── configs/                   # Beispiel-Konfigurationen
```

### 2.3 C + Lua Integration-Pattern

**C-Kern mit Lua-Logic:**
```c
// src/core/main.c
#include "furt.h"
#include "lua_bridge.h"

int main(int argc, char *argv[]) {
    furt_context_t *ctx = furt_init();
    
    // Initialize Lua state
    lua_State *L = lua_bridge_init(ctx);
    
    // Load gateway configuration
    lua_bridge_load_config(L, "config/gateway.lua");
    
    // Start HTTP server
    http_server_start(ctx, L);
    
    return 0;
}
```

**Lua-Service-Logic:**
```lua
-- config/services/formular2mail.lua
local formular2mail = {
    name = "formular2mail",
    path_prefix = "/v1/mail",
    port = 8081,
    
    -- Request-Handler
    handle_request = function(request)
        if request.method ~= "POST" then
            return { status = 405, body = "Method not allowed" }
        end
        
        local data = json.decode(request.body)
        if not validate_mail_data(data) then
            return { status = 400, body = "Invalid data" }
        end
        
        local result = send_mail(data)
        return { status = 200, body = json.encode(result) }
    end,
    
    -- Health-Check
    health_check = function()
        return { status = "healthy", timestamp = os.time() }
    end
}

return formular2mail
```

## 3. Build-System und Dependencies

### 3.1 Minimale Dependencies

**Required:**
- **GCC** (oder clang, aber nicht MSVC)
- **musl libc** (vermeidet glibc-Komplexität) 
- **Lua 5.4** (als Source eingebunden, nicht als Package)
- **LMDB** (als Source eingebunden)

**Optional:**
- **Valgrind** für Memory-Debugging
- **strace** für System-Call-Debugging

### 3.2 Build-Process

```makefile
# build/Makefile
CC = gcc
CFLAGS = -std=c99 -Wall -Wextra -O2 -DLUA_USE_POSIX
LDFLAGS = -lm -ldl

# Dependencies
LUA_DIR = deps/lua-5.4.6
LMDB_DIR = deps/lmdb

SOURCES = src/core/*.c $(LUA_DIR)/src/*.c $(LMDB_DIR)/*.c
TARGET = bin/furt-gateway

all: $(TARGET)

$(TARGET): $(SOURCES)
	$(CC) $(CFLAGS) -I$(LUA_DIR)/src -I$(LMDB_DIR) \
	      $(SOURCES) -o $(TARGET) $(LDFLAGS)

clean:
	rm -f $(TARGET)

install: $(TARGET)
	cp $(TARGET) /usr/local/bin/
	cp -r config/ /etc/furt/
	cp -r src/lua/ /usr/local/share/furt/

.PHONY: all clean install
```

### 3.3 Dependency-Management

**Statically Linked:**
- Lua-Source direkt eingebunden
- LMDB-Source direkt eingebunden  
- Keine Package-Manager-Dependencies

**Why Static Linking:**
- Vermeidet Library-Version-Konflikte
- Reduziert Runtime-Dependencies
- Maximale Kontrolle über Code-Path

## 4. Service-Entwicklung-Pattern

### 4.1 Service als C-Module + Lua-Script

**Service-Interface in C:**
```c
// src/core/service.h
typedef struct {
    char *name;
    char *path_prefix;
    int port;
    lua_State *lua_state;
} furt_service_t;

// Service-Lifecycle
int service_init(furt_service_t *service, const char *config_path);
int service_handle_request(furt_service_t *service, http_request_t *req, http_response_t *res);
int service_health_check(furt_service_t *service);
void service_cleanup(furt_service_t *service);
```

**Service-Logic in Lua:**
```lua
-- src/lua/services/base.lua
local base_service = {
    -- Standard Request-Verarbeitung
    process_request = function(self, request)
        -- Input-Validation
        if not self:validate_input(request) then
            return self:error_response(400, "Invalid input")
        end
        
        -- Business-Logic
        local result = self:handle_business_logic(request)
        
        -- Response-Formatting
        return self:format_response(result)
    end,
    
    -- Standard Error-Handling
    error_response = function(self, status, message)
        return {
            status = status,
            headers = { ["Content-Type"] = "application/json" },
            body = json.encode({ error = message })
        }
    end
}

return base_service
```

### 4.2 Service-Generator (Shell + Lua)

```bash
#!/bin/bash
# scripts/service-generator.sh

SERVICE_NAME=$1
if [ -z "$SERVICE_NAME" ]; then
    echo "Usage: $0 <service_name>"
    exit 1
fi

# Create service Lua file
cat > "src/lua/services/${SERVICE_NAME}.lua" << EOF
local base = require("services.base")
local ${SERVICE_NAME} = {}

setmetatable(${SERVICE_NAME}, { __index = base })

function ${SERVICE_NAME}:handle_business_logic(request)
    -- TODO: Implement ${SERVICE_NAME} logic
    return { message = "Hello from ${SERVICE_NAME}" }
end

function ${SERVICE_NAME}:validate_input(request)
    -- TODO: Implement validation
    return true
end

return ${SERVICE_NAME}
EOF

# Create config file
cat > "config/services/${SERVICE_NAME}.lua" << EOF
return {
    name = "${SERVICE_NAME}",
    path_prefix = "/v1/${SERVICE_NAME}",
    port = 808X, -- TODO: Set port
    enabled = true,
    
    -- Service-specific config
    config = {
        -- TODO: Add service configuration
    }
}
EOF

echo "Created service: ${SERVICE_NAME}"
```

## 5. Konfigurationsmanagement (Lua-basiert)

### 5.1 Lua-Konfiguration statt YAML

**Gateway-Konfiguration:**
```lua
-- config/gateway.lua
return {
    server = {
        host = "127.0.0.1",
        port = 8080,
        max_connections = 1000,
        request_timeout = 30
    },
    
    security = {
        api_keys = {
            {
                key = os.getenv("HUGO_API_KEY"),
                name = "hugo-frontend",
                permissions = { "mail:send", "comments:read" },
                allowed_ips = { "127.0.0.1", "10.0.0.0/8" }
            }
        }
    },
    
    services = {
        require("services.formular2mail"),
        require("services.sagjan")
    },
    
    logging = {
        level = "info",
        file = "/var/log/furt/gateway.log"
    }
}
```

**Vorteile Lua-Config:**
- **Native Programmierbarkeit** (Loops, Conditions, Functions)
- **Environment-Variable-Access** direkt in Config
- **Validation** durch Lua-Logic möglich
- **Kommentare und Dokumentation** integriert
- **Modularität** durch require()

### 5.2 Config-Validation

```lua
-- src/lua/gateway/config_validator.lua
local validator = {}

function validator.validate_gateway_config(config)
    assert(config.server, "server config required")
    assert(config.server.port, "server.port required")
    assert(type(config.server.port) == "number", "server.port must be number")
    
    for _, service in ipairs(config.services) do
        validator.validate_service_config(service)
    end
    
    return true
end

function validator.validate_service_config(service)
    assert(service.name, "service.name required")
    assert(service.path_prefix, "service.path_prefix required")
    assert(service.port, "service.port required")
    
    return true
end

return validator
```

## 6. Authentifizierung und Sicherheit

### 6.1 C-basierte Auth-Implementation

```c
// src/core/auth.c
#include "auth.h"
#include <string.h>

typedef struct {
    char key[64];
    char name[32];
    char **permissions;
    char **allowed_ips;
} api_key_t;

int auth_validate_api_key(const char *key, const char *client_ip) {
    // Load API keys from Lua config
    // Validate key and IP
    // Return permissions mask
}

int auth_check_permission(int permissions_mask, const char *permission) {
    // Check if permission is allowed
}
```

### 6.2 IP-Allowlisting in C

```c
// src/core/ip_filter.c
#include <arpa/inet.h>

int ip_is_allowed(const char *client_ip, char **allowed_ips) {
    for (int i = 0; allowed_ips[i] != NULL; i++) {
        if (ip_matches_cidr(client_ip, allowed_ips[i])) {
            return 1;
        }
    }
    return 0;
}

int ip_matches_cidr(const char *ip, const char *cidr) {
    // CIDR matching implementation
}
```

## 7. Performance und Ressourcen

### 7.1 Memory-Management

**C-Memory-Management:**
- **Stack-Allocation** wo möglich
- **Explicit malloc/free** für dynamische Allocations
- **Memory-Pools** für häufige Allocations
- **Valgrind-Testing** mandatory

**Lua-Integration:**
- **Lua-GC-Tuning** für Server-Workloads
- **C ↔ Lua** Memory-Boundary klar definiert
- **Lua-State-Isolation** zwischen Services

### 7.2 Performance-Charakteristika

**Erwartete Performance:**
- **Memory:** < 10 MB für Gateway + 3 Services
- **CPU:** < 1% bei 100 req/s
- **Startup:** < 100ms Cold-Start
- **Latency:** < 1ms Gateway-Overhead

**vs. Go-Implementation:**
- **10x weniger Memory** (keine GC, kein Runtime)
- **5x weniger CPU** (native Code, keine Abstractions)
- **100x schneller Startup** (kein Runtime-Init)

## 8. Testing-Strategy

### 8.1 C-Code-Testing

```c
// tests/unit/test_auth.c
#include "auth.h"
#include "test_framework.h"

void test_api_key_validation() {
    // Setup
    auth_init_test_keys();
    
    // Test valid key
    assert_true(auth_validate_api_key("valid-key", "127.0.0.1"));
    
    // Test invalid key
    assert_false(auth_validate_api_key("invalid-key", "127.0.0.1"));
    
    // Test IP restriction
    assert_false(auth_validate_api_key("valid-key", "192.168.1.1"));
}
```

### 8.2 Lua-Logic-Testing

```lua
-- tests/lua/test_services.lua
local service = require("services.formular2mail")

function test_mail_service_validation()
    local request = {
        method = "POST",
        body = '{"name":"Test","email":"test@example.com","message":"Test"}'
    }
    
    local response = service:process_request(request)
    assert(response.status == 200)
end
```

### 8.3 Integration-Testing

```bash
#!/bin/bash
# tests/integration/test_gateway.sh

# Start test gateway
./bin/furt-gateway &
GATEWAY_PID=$!

# Test API endpoint
curl -X POST http://localhost:8080/v1/mail/send \
     -H "X-API-Key: test-key" \
     -d '{"name":"Test","email":"test@example.com","message":"Test"}'

# Cleanup
kill $GATEWAY_PID
```

## 9. Deployment und Installation

### 9.1 Native Installation (Single Binary)

```bash
# Build from source
git clone https://gitea.dragons-at-work.de/DAW/furt.git
cd furt
make clean all

# Install
sudo make install

# Configure
sudo cp examples/configs/* /etc/furt/

# Start
sudo systemctl enable furt-gateway
sudo systemctl start furt-gateway
```

### 9.2 Systemd-Integration

```ini
# /etc/systemd/system/furt-gateway.service
[Unit]
Description=Furt API Gateway
After=network.target

[Service]
Type=simple
User=furt
Group=furt
ExecStart=/usr/local/bin/furt-gateway
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
```

### 9.3 OpenBSD-Integration (langfristig)

```bash
# /etc/rc.d/furt_gateway
#!/bin/ksh
daemon="/usr/local/bin/furt-gateway"
daemon_user="_furt"

. /etc/rc.d/rc.subr

rc_cmd $1
```

## 10. Migration von Go zu C + Lua

### 10.1 Migration-Strategy

**Phase 1: C-Grundgerüst**
- HTTP-Server in C implementieren
- Basis-Routing implementieren
- Lua-Integration testen

**Phase 2: Service-Migration**
- Formular2Mail-Service als Lua-Script
- Auth-System in C + Lua
- Tests migrieren

**Phase 3: Feature-Parität**
- Alle Go-Features in C + Lua
- Performance-Optimierung
- Dokumentation-Update

**Phase 4: Deployment**
- Production-Deployment
- Go-Version deprecaten
- Community-Feedback integrieren

### 10.2 Kompatibilität

**API-Compatibility:**
- Gleiche HTTP-APIs wie Go-Version
- Gleiche Konfiguration-Semantik (aber Lua statt YAML)
- Gleiche Integration mit Hugo-Shortcodes

**Migration-Pfad:**
- Side-by-Side-Deployment möglich
- Graduelle Service-Migration
- Zero-Downtime-Umstellung

## 11. Langfristige Vision

### 11.1 Souveräne Technologie-Stack

**Complete Independence:**
- **Compiler:** GCC (GNU, nicht Corporate)
- **Libc:** musl (minimal, secure)
- **Database:** LMDB (academic, proven)
- **Scripting:** Lua (university-backed)
- **HTTP-Server:** Eigene Implementation (< 1000 Zeilen C)

### 11.2 Community und Open Source

**Authentic Open Source:**
- Apache 2.0 License
- Keine Corporate-Contributors
- Community-driven Development
- Educational Documentation

**Biocodie-Integration:**
- Furt als Referenz-Implementation für "Organische Software"
- Minimale Komplexität, maximale Transparenz
- Natürliche Wachstums-Pattern

## 12. Nächste Schritte

### 12.1 Unmittelbare Implementierung

1. **C-HTTP-Server** - Minimal-Implementation (< 500 Zeilen)
2. **Lua-Integration** - C ↔ Lua Bridge etablieren
3. **Build-System** - Makefile-basiertes Build
4. **Basic-Routing** - Request-Routing in C + Lua

### 12.2 Service-Implementation

1. **Formular2Mail** als erstes Lua-Service
2. **Authentication** in C mit Lua-Config
3. **Hugo-Integration** - Shortcodes adaptieren
4. **Testing-Framework** - C + Lua Tests

### 12.3 Production-Readiness

1. **Performance-Tuning** - Memory, CPU optimieren
2. **Security-Hardening** - Input-Validation, Memory-Safety
3. **Documentation** - Installation, Configuration, Development
4. **Deployment-Automation** - Scripts für Production

---

**Diese überarbeitete Architektur entspricht vollständig der Dragons@Work Tech-Reference und ermöglicht echte digitale Souveränität durch Corporate-freie Technologien.**