@robiki/proxy 1.0.2 → 1.0.3

package/README.de.md

@@ -1,11 +1,11 @@
 # 🚀 Robiki Proxy
 
-> Ein leistungsstarker, flexibler HTTP/2-Reverse-Proxy mit WebSocket-Unterstützung, konfigurierbarem Routing, CORS und Anforderungsvalidierung. Verwenden Sie es als npm-Paket in Ihrer Node.js-Anwendung oder als eigenständigen Docker-Container. Nur für die Verwendung als Domain-Proxy in lokalen Entwicklungsumgebungen vorgesehen.
+> Ein leistungsstarker HTTP/2-Reverse-Proxy mit WebSocket-Unterstützung, konfigurierbarem Routing, CORS und Anforderungsvalidierung. Als npm-Paket oder Docker-Container für lokale Entwicklungsumgebungen verwendbar.
 
 [![npm version](https://img.shields.io/npm/v/@robiki/proxy.svg)](https://www.npmjs.com/package/@robiki/proxy)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## 🌍 Sprachen / Languages / 语言 / 言語 / Języki / Idiomas / Языки
+## 🌍 Sprachen
 
 [English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | [日本語](README.ja.md) | [Polski](README.pl.md) | [Español](README.es.md) | [Русский](README.ru.md)
 
@@ -18,54 +18,29 @@
 - **✅ Anforderungsvalidierung**: Benutzerdefinierte Validierungslogik für Authentifizierung, Rate Limiting usw.
 - **🔄 URL-Remapping**: URLs vor der Weiterleitung an Zieldienste transformieren
 - **📦 Duale Nutzung**: Als npm-Paket oder Docker-Container verwenden
+- **⚙️ JavaScript & TypeScript-Konfigurationsunterstützung**: Verwenden Sie `.cjs` oder `.ts`-Konfigurationsdateien mit Funktionen in Docker
 - **🎯 Multi-Port-Unterstützung**: Gleichzeitiges Lauschen auf mehreren Ports
 - **⚡ Hohe Leistung**: Basiert auf der nativen HTTP/2-Implementierung von Node.js
 
 ## 📦 Installation
 
-### Als npm-Paket
+### npm-Paket
 
 ```bash
 npm install @robiki/proxy
-```
-
-```bash
+# oder
 yarn add @robiki/proxy
 ```
 
-### Als Docker-Container
+### Docker
 
 ```bash
 docker pull robiki/proxy:latest
 ```
 
-### Als Docker Compose Service
-
-```yaml
-services:
-  proxy:
-    image: robiki/proxy:latest
-    container_name: robiki-proxy
-    restart: unless-stopped
-    ports:
-      - '443:443'
-      - '8080:8080'
-      - '9229:9229'
-    volumes:
-      - ./proxy.config.json:/app/proxy.config.json:ro
-      - ./certs:/app/certs:ro
-    networks:
-      - app-network
-```
-
-## Hinweise
-
-- Hosts, die lokal konfiguriert sind, sollten zu Ihrer lokalen `hosts`-Datei hinzugefügt werden.
-- Wenn Sie benutzerdefinierte Zertifikate verwenden, müssen Sie die Zertifikatdateien zum `certs`-Verzeichnis hinzufügen.
-
 ## 🚀 Schnellstart
 
-### Verwendung als npm-Paket
+### npm-Paket
 
 ```javascript
 import { createProxy } from '@robiki/proxy';
@@ -88,13 +63,11 @@ const proxy = await createProxy({
     },
   },
 });
-
-console.log('Proxy-Server läuft!');
 ```
 
-### Verwendung mit Docker
+### Docker
 
-1. Erstellen Sie eine `proxy.config.json`-Datei:
+Erstellen Sie `proxy.config.json`:
 
 ```json
 {
@@ -108,20 +81,14 @@ console.log('Proxy-Server läuft!');
     "api.example.com": {
       "target": "backend-service:3000",
       "ssl": true
-    },
-    "example.com": {
-      "target": "frontend-service:8080",
-      "ssl": false
     }
   }
 }
 ```
 
-2. Erstellen Sie eine `docker-compose.yml`:
+Erstellen Sie `docker-compose.yml`:
 
 ```yaml
-version: '3.8'
-
 services:
   proxy:
     image: robiki/proxy:latest
@@ -133,25 +100,9 @@ services:
       - ./certs:/app/certs:ro
     environment:
       - PROXY_CONFIG=/app/proxy.config.json
-    networks:
-      - app-network
-
-  backend-service:
-    image: your-backend-image
-    networks:
-      - app-network
-
-  frontend-service:
-    image: your-frontend-image
-    networks:
-      - app-network
-
-networks:
-  app-network:
-    driver: bridge
 ```
 
-3. Starten Sie die Dienste:
+Starten:
 
 ```bash
 docker-compose up -d
@@ -159,9 +110,9 @@ docker-compose up -d
 
 ## 📖 Konfiguration
 
-### Konfigurationsdatei
+### JSON-Konfiguration
 
-Erstellen Sie eine `proxy.config.json`-Datei mit folgender Struktur:
+Einfache deklarative Konfiguration:
 
 ```json
 {
@@ -169,24 +120,17 @@ Erstellen Sie eine `proxy.config.json`-Datei mit folgender Struktur:
   "ssl": {
     "key": "./certs/key.pem",
     "cert": "./certs/cert.pem",
-    "ca": "./certs/ca.pem",
     "allowHTTP1": true
   },
   "cors": {
     "origin": "*",
-    "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
-    "allowedHeaders": ["Content-Type", "Authorization"],
-    "credentials": true,
-    "maxAge": 86400
+    "methods": ["GET", "POST", "PUT", "DELETE"],
+    "credentials": true
   },
   "routes": {
     "api.example.com": {
-      "target": "backend-service:3000",
-      "ssl": true,
-      "cors": {
-        "origin": ["https://example.com"],
-        "credentials": true
-      }
+      "target": "backend:3000",
+      "ssl": true
     },
     "*.example.com": {
       "target": "wildcard-service:4000",
@@ -196,78 +140,32 @@ Erstellen Sie eine `proxy.config.json`-Datei mit folgender Struktur:
 }
 ```
 
-### Umgebungsvariablen
-
-Sie können den Proxy auch über Umgebungsvariablen konfigurieren:
-
-```bash
-# SSL-Konfiguration
-SSL_KEY=/app/certs/key.pem
-SSL_CERT=/app/certs/cert.pem
-SSL_CA=/app/certs/ca.pem
-SSL_ALLOW_HTTP1=true
-
-# CORS-Konfiguration
-CORS_ORIGIN=*
-CORS_METHODS=GET,POST,PUT,DELETE,OPTIONS
-CORS_HEADERS=Content-Type,Authorization
-CORS_CREDENTIALS=true
-
-# Debug-Modus
-DEBUG=true  # Aktiviert detailliertes Logging für Proxy-Verbindungen und Fehler
-```
-
-## 🎯 Erweiterte Verwendung
-
-### URL-Remapping
-
-URLs vor der Weiterleitung an Zieldienste transformieren:
-
-```javascript
-const config = {
-  routes: {
-    'api.example.com': {
-      target: 'backend:3000',
-      ssl: true,
-      remap: (url) => {
-        // /api-Präfix entfernen
-        return url.replace(/^\/api/, '');
-      },
-    },
-  },
-};
-```
-
-### Anforderungsvalidierung
+### JavaScript-Konfiguration
 
-Benutzerdefinierte Validierungslogik für Authentifizierung, Rate Limiting usw. hinzufügen:
+Für erweiterte Funktionen wie URL-Remapping und Validierung:
 
 ```javascript
-const config = {
-  // Globale Validierung
-  validate: async (info) => {
-    if (!info.headers.authorization) {
-      return {
-        status: false,
-        code: 401,
-        message: 'Nicht autorisiert',
-        headers: { 'www-authenticate': 'Bearer' },
-      };
-    }
-    return { status: true };
+// proxy.config.cjs
+module.exports = {
+  ports: [443, 8080],
+  ssl: {
+    key: './certs/key.pem',
+    cert: './certs/cert.pem',
+    allowHTTP1: true,
   },
   routes: {
     'api.example.com': {
       target: 'backend:3000',
       ssl: true,
-      // Routenspezifische Validierung
+      // URL-Remapping
+      remap: (url) => url.replace(/^\/api/, ''),
+      // Anforderungsvalidierung
       validate: async (info) => {
-        const rateLimit = await checkRateLimit(info.remoteAddress);
-        if (!rateLimit.allowed) {
+        if (!info.headers.authorization) {
           return {
             status: false,
-            code: 429,
-            message: 'Zu viele Anfragen',
+            code: 401,
+            message: 'Unauthorized',
           };
         }
         return { status: true };
@@ -277,93 +175,80 @@ const config = {
 };
 ```
 
-### Benutzerdefinierte CORS-Konfiguration
+### TypeScript-Konfiguration
 
-CORS global oder pro Route konfigurieren:
+Typsichere Konfiguration mit vollständiger IDE-Unterstützung:
 
-```javascript
-const config = {
-  // Globales CORS
-  cors: {
-    origin: ['https://example.com', 'https://www.example.com'],
-    methods: ['GET', 'POST', 'PUT', 'DELETE'],
-    allowedHeaders: ['Content-Type', 'Authorization'],
-    credentials: true,
-    maxAge: 86400,
+```typescript
+// proxy.config.ts
+import type { ServerConfig, ConnectionInfo } from '@robiki/proxy';
+
+const config: ServerConfig = {
+  ports: [443, 8080],
+  ssl: {
+    key: './certs/key.pem',
+    cert: './certs/cert.pem',
+    allowHTTP1: true,
   },
   routes: {
     'api.example.com': {
       target: 'backend:3000',
       ssl: true,
-      // Routenspezifisches CORS (überschreibt global)
-      cors: {
-        origin: '*',
-        credentials: false,
+      remap: (url: string) => url.replace(/^\/api/, ''),
+      validate: async (info: ConnectionInfo) => {
+        if (!info.headers['x-api-key']) {
+          return { status: false, code: 401, message: 'API Key Required' };
+        }
+        return { status: true };
       },
     },
   },
 };
-```
 
-### Benutzerdefinierte Handler
+export default config;
+```
 
-Benutzerdefinierte Request-Handler für erweiterte Anwendungsfälle erstellen:
+### Umgebungsvariablen
 
-```javascript
-import { createCustomProxy } from '@robiki/proxy';
+```bash
+# SSL-Konfiguration
+SSL_KEY=/app/certs/key.pem
+SSL_CERT=/app/certs/cert.pem
+SSL_ALLOW_HTTP1=true
 
-const customRestHandler = async (req, res) => {
-  if (req.url === '/health') {
-    res.writeHead(200, { 'content-type': 'application/json' });
-    return res.end(JSON.stringify({ status: 'ok' }));
-  }
-  // Auf Standard-Proxy-Verhalten zurückfallen
-  const { restAPIProxyHandler } = await import('@robiki/proxy/connections');
-  return restAPIProxyHandler(req, res);
-};
+# CORS-Konfiguration
+CORS_ORIGIN=*
+CORS_METHODS=GET,POST,PUT,DELETE
+CORS_CREDENTIALS=true
 
-const proxy = await createCustomProxy(config, {
-  rest: customRestHandler,
-  websocket: customWebSocketHandler,
-  stream: customStreamHandler,
-});
+# Debug-Modus
+DEBUG=true
 ```
 
 ## 🔧 API-Referenz
 
-### `createProxy(config: ServerConfig): Promise<ProxyServer>`
-
-Erstellt und startet einen Proxy-Server mit der angegebenen Konfiguration.
-
-**Parameter:**
-
-- `config`: Server-Konfigurationsobjekt
-
-**Rückgabe:** Promise, das zu einer `ProxyServer`-Instanz aufgelöst wird
-
-### `ProxyServer`
-
-**Methoden:**
-
-- `start()`: Proxy-Server starten
-- `stop()`: Proxy-Server stoppen
-- `getConfig()`: Aktuelle Konfiguration abrufen
+### `createProxy(config: ServerConfig)`
 
-### Konfigurationstypen
+Erstellt und startet einen Proxy-Server.
 
-#### `ServerConfig`
+**ServerConfig:**
 
 ```typescript
 interface ServerConfig {
   ports?: number[];
-  ssl?: CertificateConfig;
+  ssl?: {
+    key: string;
+    cert: string;
+    ca?: string;
+    allowHTTP1?: boolean;
+  };
   routes: Record<string, RouteConfig>;
   cors?: CorsConfig;
   validate?: (info: ConnectionInfo) => Promise<ForwardValidationResult>;
 }
 ```
 
-#### `RouteConfig`
+**RouteConfig:**
 
 ```typescript
 interface RouteConfig {
@@ -375,265 +260,86 @@ interface RouteConfig {
 }
 ```
 
-#### `CorsConfig`
-
-```typescript
-interface CorsConfig {
-  origin?: string | string[];
-  methods?: string[];
-  allowedHeaders?: string[];
-  exposedHeaders?: string[];
-  credentials?: boolean;
-  maxAge?: number;
-}
-```
-
-#### `ConnectionInfo`
-
-```typescript
-interface ConnectionInfo {
-  id: number;
-  method: string;
-  path: string;
-  remoteAddress: string;
-  scheme: string;
-  authority: string;
-  origin: string;
-  headers: IncomingHttpHeaders;
-  query: URLSearchParams;
-  type: RequestType;
-}
-```
-
 ## 🐳 Docker-Verwendung
 
-### Verwendung in einem anderen Projekt
-
-1. Fügen Sie den Proxy zu Ihrer `docker-compose.yml` hinzu:
+Mounten Sie Ihre Konfigurationsdatei (JSON, .cjs oder .ts):
 
 ```yaml
 services:
   proxy:
     image: robiki/proxy:latest
-    ports:
-      - '443:443'
-      - '8080:8080'
     volumes:
-      - ./proxy.config.json:/app/proxy.config.json:ro
+      - ./proxy.config.cjs:/app/proxy.config.cjs:ro
       - ./certs:/app/certs:ro
-    networks:
-      - your-network
-
-  your-service:
-    image: your-service-image
-    networks:
-      - your-network
-```
-
-2. Konfigurieren Sie Routen in `proxy.config.json`, um auf Ihre Dienste zu verweisen
-
-3. Starten Sie Ihren Stack:
-
-```bash
-docker-compose up -d
-```
-
-### Benutzerdefiniertes Image erstellen
-
-Erstellen Sie ein benutzerdefiniertes Dockerfile:
-
-```dockerfile
-FROM robiki/proxy:latest
-
-# Kopieren Sie Ihre Konfiguration
-COPY proxy.config.json /app/proxy.config.json
-COPY certs /app/certs
-
-# Umgebungsvariablen setzen
-ENV PROXY_CONFIG=/app/proxy.config.json
+    environment:
+      - PROXY_CONFIG=/app/proxy.config.cjs
 ```
 
-## 📚 Beispiele
-
-Weitere Verwendungsbeispiele finden Sie im Verzeichnis `examples/`:
-
-- `basic-usage.js` - Einfache Proxy-Einrichtung
-- `advanced-usage.js` - Erweiterte Funktionen (Validierung, CORS, Remapping)
-- `custom-handlers.js` - Benutzerdefinierte Request-Handler
-- `docker-compose.example.yml` - Vollständige Docker-Einrichtung
-
-## 🔐 SSL/TLS-Zertifikate
-
-### Selbstsignierte Zertifikate generieren
+## 🔐 SSL-Zertifikate
 
-Für die Entwicklung:
+### Entwicklung (Self-Signed)
 
 ```bash
 mkdir -p certs
 openssl req -x509 -newkey rsa:4096 -keyout certs/key.pem -out certs/cert.pem -days 365 -nodes
 ```
 
-### Let's Encrypt verwenden
-
-Für die Produktion verwenden Sie Let's Encrypt-Zertifikate:
+### Produktion (Let's Encrypt)
 
 ```bash
 certbot certonly --standalone -d example.com
 ```
 
-Verweisen Sie dann in Ihrer Konfiguration darauf:
-
-```json
-{
-  "ssl": {
-    "key": "/etc/letsencrypt/live/example.com/privkey.pem",
-    "cert": "/etc/letsencrypt/live/example.com/fullchain.pem"
-  }
-}
-```
-
-## 🤝 Mitwirken
-
-Beiträge sind willkommen! Bitte zögern Sie nicht, einen Pull Request einzureichen.
-
-## 📄 Lizenz
-
-MIT © Robiki sp. z o.o.
-
-## 🔗 Links
-
-- [GitHub-Repository](https://github.com/robiki-ai/robiki-proxy)
-- [npm-Paket](https://www.npmjs.com/package/@robiki/proxy)
-- [Issue-Tracker](https://github.com/robiki-ai/robiki-proxy/issues)
-
-## 💡 Anwendungsfälle
-
-- **Microservices-Architektur**: Anfragen basierend auf Domain/Pfad an verschiedene Dienste weiterleiten
-- **Entwicklungsumgebung**: Lokaler Proxy zum Testen mehrerer Dienste
-- **API-Gateway**: Zentraler Einstiegspunkt mit Authentifizierung und Rate Limiting
-- **SSL-Terminierung**: SSL/TLS auf Proxy-Ebene verarbeiten
-- **CORS-Verwaltung**: Zentralisierte CORS-Konfiguration
-- **Load Balancing**: Verkehr auf mehrere Instanzen verteilen (mit benutzerdefinierten Handlern)
-
 ## 🛠️ Fehlerbehebung
 
 ### Debug-Modus
 
-Aktivieren Sie detailliertes Logging zur Fehlerbehebung bei Verbindungsproblemen:
+Detaillierte Protokollierung aktivieren:
 
 ```bash
-# Debug-Modus aktivieren
-DEBUG=true node your-proxy-script.js
-
-# Oder mit Docker
+DEBUG=true node your-script.js
+# oder
 docker run -e DEBUG=true robiki/proxy:latest
-
-# Oder in docker-compose.yml
-services:
-  proxy:
-    image: robiki/proxy:latest
-    environment:
-      - DEBUG=true
 ```
 
-Wenn `DEBUG=true`, protokolliert der Proxy:
-- Alle Proxy-Verbindungsversuche (REST, WebSocket, HTTP/2-Streams)
-- Anfrage- und Antwortdetails
-- Verbindungsfehler und Timeouts
-- Proxy-Fehler und Client-Fehler
-
 ### Port bereits in Verwendung
 
-Der Proxy versucht automatisch, Prozesse auf den konfigurierten Ports zu beenden. Wenn dies fehlschlägt, geben Sie die Ports manuell frei:
-
 ```bash
 lsof -ti:443 | xargs kill -9
-lsof -ti:8080 | xargs kill -9
 ```
 
-### SSL-Zertifikatfehler
-
-Stellen Sie sicher, dass Ihre Zertifikatdateien lesbar und im richtigen Format (PEM) sind. Verwenden Sie für die Entwicklung selbstsignierte Zertifikate.
-
-### WebSocket-Verbindungsprobleme
-
-Stellen Sie sicher, dass Ihre WebSocket-Routen mit dem richtigen Protokoll (ws/wss) konfiguriert sind und dass der Zieldienst WebSocket-Verbindungen unterstützt.
-
-## 🧪 Testen
-
-Robiki Proxy enthält eine umfassende Testsuite mit Unit-Tests, Integrationstests und erweiterten Szenarien.
-
-### Tests ausführen
+## 🧪 Tests
 
 ```bash
 # Alle Tests ausführen
 yarn test
 
-# Tests im Watch-Modus ausführen
-yarn test:watch
-
-# Tests mit Coverage ausführen
+# Mit Coverage
 yarn test:coverage
 
-# Tests mit UI ausführen
-yarn test:ui
-```
-
-### Test-Coverage
-
-Die Testsuite umfasst:
-
-- **Unit-Tests**: Konfiguration, Utilities, Header-Konvertierung, CORS-Behandlung
-- **Integrationstests**: HTTP-Proxying, Routenauflösung, Validierung, Config-Loading
-- **Erweiterte Tests**: WebSocket-Proxying, HTTP/2-Streams, gleichzeitige Verbindungen
-- **Docker-Tests**: Container-Builds, Config-Loading, Laufzeitverhalten
-
-### Docker-Tests
-
-Docker-Integrationstests ausführen:
-
-```bash
-# Vollständiger Docker-Integrationstest
+# Docker-Tests
 yarn test:docker
-
-# Config-Loading spezifisch testen
-yarn test:docker:config
-
-# Alle Tests ausführen (Unit + Integration + Docker)
-yarn test:all
 ```
 
-Oder mit Make:
-
-```bash
-# Schneller Docker-Build-Test
-make test-docker
-
-# Vollständige Integrationstestsuite
-make test-docker-full
-
-# Config-Loading-Test
-make test-docker-config
+## 📚 Beispiele
 
-# Docker Compose-Test
-make test-docker-compose
-```
+Siehe das `examples/`-Verzeichnis:
 
-Weitere Details finden Sie im [Docker Tests README](tests/docker/README.md).
+- `basic-usage.js` - Einfaches Proxy-Setup
+- `advanced-usage.js` - Validierung, CORS, Remapping
+- `custom-handlers.js` - Benutzerdefinierte Request-Handler
+- `docker-compose.example.yml` - Docker-Setup
 
-## 📊 Leistung
+## 🤝 Mitwirken
 
-Der Proxy basiert auf der nativen HTTP/2-Implementierung von Node.js und ist für hohe Leistung konzipiert:
+Beiträge willkommen! Siehe [CONTRIBUTING.md](CONTRIBUTING.md) für Details.
 
-- Effiziente Stream-Verarbeitung
-- Minimaler Overhead
-- Connection Pooling
-- Automatischer HTTP/1.1-Fallback
+## 📄 Lizenz
 
-Für Produktionsbereitstellungen berücksichtigen Sie:
+MIT © Robiki sp. z o.o.
 
-- Verwendung eines Prozessmanagers (PM2, systemd)
-- Aktivierung von Clustering für Multi-Core-Systeme
-- Überwachung mit Health Checks
-- Einrichtung eines ordnungsgemäßen Loggings
+## 🔗 Links
 
+- [GitHub Repository](https://github.com/robiki-ai/robiki-proxy)
+- [npm Package](https://www.npmjs.com/package/@robiki/proxy)
+- [Issue Tracker](https://github.com/robiki-ai/robiki-proxy/issues)