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:

// 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:

-- 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

# 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:

// 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:

-- 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)

#!/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:

-- 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

-- 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

// 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

// 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

// 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

-- 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

#!/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)

# 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

# /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)

# /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.