pp-command-bus 1.2.3 → 1.3.1

package/README.md

@@ -4,39 +4,207 @@ Distributed Command Bus library supporting RPC and job queuing with BullMQ for R
 
 ## Opis
 
-**pp-command-bus** to biblioteka do obsługi rozproszonych komend zgodna ze wzorcem **CQRS (Command Query Responsibility Segregation)**. Wspiera:
+**pp-command-bus** to zaawansowana biblioteka do obsługi rozproszonych komend zgodna ze wzorcem **CQRS (Command Query Responsibility Segregation)**. Zapewnia wysoką wydajność, automatyczną optymalizację i zaawansowane funkcje produkcyjne.
+
+### Kluczowe Cechy
 
 - ✅ **Fire-and-forget commands** - wysyłanie komend bez oczekiwania na wynik
-- ✅ **RPC (Remote Procedure Call)** - synchroniczne wywołania z oczekiwaniem na odpowiedź
+- ✅ **RPC (Remote Procedure Call)** - synchroniczne wywołania przez Redis Pub/Sub z oczekiwaniem na odpowiedź
+- ✅ **Automatyczna kompresja** - gzip dla payloadów RPC >1KB (konfigurowalne)
+- ✅ **Auto-optymalizacja** - dynamiczne dostosowywanie concurrency na podstawie CPU/RAM
+- ✅ **Process isolation** - izolacja odpowiedzi RPC między procesami Node.js
 - ✅ **Job queuing** - kolejkowanie zadań z retry, backoff i delayed execution
 - ✅ **BullMQ integration** - wydajna kolejka zadań na Redis/DragonflyDB
 - ✅ **TypeScript** - pełne wsparcie typów i strict mode
 - ✅ **Memory leak protection** - zaawansowana diagnostyka i cleanup
-- ✅ **Command logging** - opcjonalne logowanie komend do plików
-- ✅ **Modularna architektura** - komponenty zgodne z zasadami SOLID i SRP
+- ✅ **Command logging** - opcjonalne logowanie komend do plików JSONL
+- ✅ **Modularna architektura** - komponenty zgodne z zasadami SOLID, DDD i SRP
 
-## Struktura Projektu
+## Architektura Systemu
+
+### Diagram Komponentów
 
 ```
-src/
-├── command-bus/                # Główna logika CommandBus
-│   ├── config/                 # Konfiguracja CommandBus
-│   ├── job/                    # Przetwarzanie jobów i opcje
-│   ├── logging/                # Command logging do plików
-│   ├── queue/                  # Queue management i cache
-│   ├── rpc/                    # RPC coordination
-│   ├── worker/                 # Worker orchestration
-│   ├── types/                  # Typy TypeScript
-│   ├── docs/                   # Dokumentacja architektury
-│   ├── command.ts              # Klasa bazowa Command
-│   └── index.ts                # CommandBus główna klasa
-├── shared/                     # Wspólne komponenty
-│   ├── config/                 # Base config z Redis
-│   ├── logging/                # Logger wrapper z poziomami
-│   └── types.ts                # Współdzielone typy
-├── examples/                   # Przykłady użycia
-│   └── rpc.demo.ts             # Demo RPC calls
-└── index.ts                    # Główny export pakietu
+┌─────────────────────────────────────────────────────────────────────┐
+│                           CommandBus                                 │
+│  ┌────────────────┐  ┌──────────────┐  ┌─────────────────────────┐ │
+│  │ QueueManager   │  │ RpcCoordinator│  │ WorkerOrchestrator      │ │
+│  │ - Cache kolejek│  │ - Pub/Sub     │  │ - Dynamiczne concurrency│ │
+│  │ - BullMQ Queue │  │ - Process ID  │  │ - Worker benchmark      │ │
+│  └────────┬───────┘  └──────┬───────┘  └────────┬────────────────┘ │
+│           │                  │                    │                  │
+│           │                  │                    │                  │
+│  ┌────────▼──────────────────▼────────────────────▼───────────────┐ │
+│  │            JobProcessor (Command Handler Execution)             │ │
+│  │  - Kompresja/dekompresja payloadów                             │ │
+│  │  - Wykonywanie handlerów                                        │ │
+│  │  - Wysyłanie odpowiedzi RPC przez Pub/Sub                      │ │
+│  └──────────────────────────┬──────────────────────────────────────┘ │
+└─────────────────────────────┼────────────────────────────────────────┘
+                              │
+                    ┌─────────▼──────────┐
+                    │  PayloadCompression │
+                    │  Service            │
+                    │  - gzip compression │
+                    │  - threshold: 1KB   │
+                    └─────────────────────┘
+```
+
+### Główne Serwisy
+
+#### 1. **CommandBus** (główna klasa orkiestrująca)
+- **Odpowiedzialność**: Główny punkt wejścia dla użytkownika, orkiestracja wszystkich komponentów
+- **Metody publiczne**:
+  - `dispatch(command)` - wysyłanie fire-and-forget
+  - `call(command, timeout)` - synchroniczne RPC
+  - `handle(commandClass, handler)` - rejestracja handlerów
+  - `close()` - graceful shutdown
+- **Zarządzanie połączeniami**: 3 dedykowane połączenia Redis (Queue, Worker, RPC)
+
+#### 2. **RpcCoordinator** (zarządzanie RPC)
+- **Odpowiedzialność**: Zarządzanie cyklem życia wywołań RPC przez Redis Pub/Sub
+- **Kluczowe funkcje**:
+  - **Shared Subscriber** - jeden subscriber dla wszystkich RPC calls (pattern matching)
+  - **Process Isolation** - UUID procesu Node.js dla izolacji odpowiedzi między procesami
+  - **Timeout Management** - automatyczne cleanup po timeout
+  - **Multiplexing** - routing odpowiedzi do odpowiednich promises
+- **Kanały**: `rpc:response:{processId}:{correlationId}`
+
+#### 3. **WorkerOrchestrator** (orkiestracja workerów)
+- **Odpowiedzialność**: Zarządzanie workerami BullMQ i dynamiczna optymalizacja
+- **Kluczowe funkcje**:
+  - **WorkerBenchmark** - automatyczny benchmark przy rejestracji handlera
+  - **WorkerMetricsCollector** - event-driven metrics collection
+  - **Dynamic Concurrency** - dostosowywanie concurrency +/-20% co 30s
+  - **Event Handlers** - obsługa zdarzeń: active, completed, failed, stalled
+- **Limity concurrency**: min 10, max 2000
+
+#### 4. **JobProcessor** (wykonywanie handlerów)
+- **Odpowiedzialność**: Wykonywanie handlerów komend i obsługa odpowiedzi RPC
+- **Flow przetwarzania**:
+  1. Dekompresja payloadu (jeśli skompresowany)
+  2. Rekonstrukcja obiektów Date
+  3. Opcjonalne logowanie komendy
+  4. Wykonanie handlera
+  5. Wysłanie odpowiedzi RPC przez Pub/Sub (jeśli RPC)
+- **Kompresja odpowiedzi**: automatyczna kompresja przez PayloadCompressionService
+
+#### 5. **QueueManager** (zarządzanie kolejkami)
+- **Odpowiedzialność**: Cache kolejek BullMQ dla optymalizacji pamięci
+- **Funkcje**:
+  - `getOrCreateQueue(commandName)` - lazy loading kolejek
+  - `closeAllQueues()` - graceful shutdown wszystkich kolejek
+- **Naming**: `{CommandName}` jako nazwa kolejki
+
+#### 6. **PayloadCompressionService** (kompresja)
+- **Odpowiedzialność**: Automatyczna kompresja/dekompresja payloadów gzip
+- **Threshold**: 1024 bajty (1KB) domyślnie, konfigurowalne przez ENV
+- **Metody**:
+  - `compressCommand(command)` - dodaje flagę `__compressed`
+  - `decompressCommand(command)` - dekompresja i usunięcie flagi
+  - `compress(data)` - generyczna kompresja do base64
+  - `decompress(data, compressed)` - generyczna dekompresja
+- **Współdzielony serwis**: jedna instancja dla całego CommandBus
+
+#### 7. **CommandLogger** (opcjonalne logowanie)
+- **Odpowiedzialność**: Persystencja komend do plików JSONL
+- **Format**: `{timestamp}.jsonl` - rotacja co godzinę
+- **Zawartość**: pełny payload komendy z metadanymi
+- **Aktywacja**: przez ENV `COMMAND_BUS_LOG=./command-logs`
+
+#### 8. **AutoConfigOptimizer** (auto-optymalizacja)
+- **Odpowiedzialność**: Obliczanie optymalnego concurrency na podstawie zasobów systemowych
+- **Heurystyka**:
+  - I/O-heavy workload (Redis/BullMQ)
+  - `concurrency = CPU cores * 2 + (availableMemory / 512MB)`
+  - Zakładane 512MB RAM per worker
+- **Aktywacja**: domyślnie włączone (ENV `COMMAND_BUS_AUTO_OPTIMIZE=false` wyłącza)
+
+### Flow Przepływu Danych
+
+#### Flow 1: dispatch() - Fire-and-forget
+
+```
+User Code
+   │
+   ├─→ 1. commandBus.dispatch(command)
+   │
+   ├─→ 2. PayloadCompressionService.compressCommand(command)
+   │      └─→ Jeśli payload >1KB → gzip → base64 → __compressed: true
+   │
+   ├─→ 3. QueueManager.getOrCreateQueue(commandName)
+   │      └─→ Cache hit/miss → zwraca Queue
+   │
+   ├─→ 4. queue.add(commandName, compressedCommand, options)
+   │      └─→ BullMQ dodaje job do Redis
+   │
+   └─→ 5. Promise<void> resolved (nie czekamy na wynik)
+
+Worker Side (asynchronicznie)
+   │
+   ├─→ 6. Worker pobiera job z kolejki
+   │
+   ├─→ 7. JobProcessor.process(job)
+   │      ├─→ Dekompresja (jeśli __compressed)
+   │      ├─→ Rekonstrukcja Date
+   │      ├─→ Opcjonalne logowanie (CommandLogger)
+   │      └─→ Wykonanie handlera
+   │
+   └─→ 8. Worker kończy job (success/fail)
+```
+
+#### Flow 2: call() - RPC przez Redis Pub/Sub
+
+```
+User Code
+   │
+   ├─→ 1. commandBus.call(command, timeout)
+   │
+   ├─→ 2. RpcCoordinator.registerCall(correlationId, commandName, timeout)
+   │      ├─→ Oczekiwanie na gotowość shared subscriber (5s timeout)
+   │      ├─→ Utworzenie Promise<T> dla odpowiedzi
+   │      ├─→ Zapisanie pending call w Map
+   │      └─→ Zwrócenie responsePromise (bez blokowania)
+   │
+   ├─→ 3. PayloadCompressionService.compressCommand(command)
+   │      └─→ Jeśli payload >1KB → gzip → __compressed: true
+   │
+   ├─→ 4. RpcCoordinator.prepareRpcCommand(compressedCommand)
+   │      └─→ Dodaje __rpcMetadata: { correlationId, responseChannel, timestamp }
+   │
+   ├─→ 5. QueueManager.getOrCreateQueue(commandName)
+   │      └─→ Cache hit/miss → zwraca Queue
+   │
+   ├─→ 6. queue.add(commandName, commandWithMetadata, options)
+   │      └─→ BullMQ dodaje job do Redis
+   │
+   └─→ 7. await responsePromise (czeka na odpowiedź z Worker)
+
+Worker Side
+   │
+   ├─→ 8. Worker pobiera job z kolejki
+   │
+   ├─→ 9. JobProcessor.process(job)
+   │      ├─→ Dekompresja payloadu (jeśli __compressed)
+   │      ├─→ Rekonstrukcja Date
+   │      ├─→ Wykonanie handlera → result
+   │      │
+   │      └─→ 10. JobProcessor.sendRpcResponse(rpcMetadata, result, null)
+   │             ├─→ PayloadCompressionService.compress({ correlationId, result, error })
+   │             ├─→ Wrapper: { data, compressed }
+   │             └─→ redis.publish(responseChannel, JSON.stringify(wrapper))
+   │
+Shared Subscriber (RpcCoordinator)
+   │
+   ├─→ 11. pmessage event → handleRpcMessage(channel, message)
+   │      ├─→ Ekstraktuj correlationId z channel
+   │      ├─→ Weryfikuj processInstanceId (process isolation)
+   │      ├─→ Znajdź pending call w Map
+   │      ├─→ PayloadCompressionService.decompress(wrapper.data, wrapper.compressed)
+   │      ├─→ resolve(result) lub reject(error)
+   │      └─→ Cleanup: clearTimeout, delete z Map
+   │
+   └─→ 12. User Code otrzymuje wynik → Promise<T> resolved
 ```
 
 ## Instalacja
@@ -64,7 +232,7 @@ const config = new CommandBusConfig({
   logger: console, // ILogger interface
   logLevel: 'log', // debug | log | warn | error
   concurrency: 5,
-  maxAttempts: 3,
+  maxAttempts: 1,
 });
 
 // Utwórz instancję CommandBus
@@ -116,31 +284,164 @@ const result = await commandBus.call<{ userId: string }>(command, 5000); // time
 console.log(`User created with ID: ${result.userId}`);
 ```
 
+## Zmienne Środowiskowe
+
+Biblioteka wspiera konfigurację poprzez zmienne środowiskowe z prefiksem `COMMAND_BUS_` (z fallbackiem do starszych nazw `EVENT_BUS_*`):
+
+### Kompletna Lista Zmiennych
+
+| Zmienna | Typ | Wartość Domyślna | Opis |
+|---------|-----|------------------|------|
+| `REDIS_URL` | string | `redis://localhost:6379` | URL połączenia Redis/DragonflyDB (wspiera username, password, db) |
+| `LOG_LEVEL` | enum | `log` | Poziom logowania: `debug`, `log`, `warn`, `error` |
+| `COMMAND_BUS_CONCURRENCY` | number | `1` (lub auto) | Liczba równoległych workerów do przetwarzania komend |
+| `COMMAND_BUS_MAX_ATTEMPTS` | number | `1` | Maksymalna liczba prób przetworzenia zadania |
+| `COMMAND_BUS_BACKOFF_DELAY` | number | `2000` | Opóźnienie między próbami w milisekundach |
+| `COMMAND_BUS_QUEUE_MODE` | enum | `fifo` | Tryb przetwarzania kolejki: `fifo` (First In First Out) lub `lifo` (Last In First Out) |
+| `COMMAND_BUS_LOG` | string | _(puste)_ | Ścieżka do katalogu logów komend (JSONL format, rotacja co godzinę) |
+| `COMMAND_BUS_AUTO_OPTIMIZE` | boolean | `true` | Włącz auto-optymalizację concurrency na podstawie CPU/RAM |
+| `COMMAND_BUS_COMPRESSION_THRESHOLD` | number | `1024` | Próg kompresji gzip dla payloadów RPC w bajtach (1KB domyślnie) |
+
+### Fallback do Starszych Nazw
+
+Dla kompatybilności wstecznej obsługiwane są również prefiksy `EVENT_BUS_*`:
+
+- `EVENT_BUS_CONCURRENCY` → `COMMAND_BUS_CONCURRENCY`
+- `EVENT_BUS_MAX_ATTEMPTS` → `COMMAND_BUS_MAX_ATTEMPTS`
+- `EVENT_BUS_BACKOFF_DELAY` → `COMMAND_BUS_BACKOFF_DELAY`
+- `EVENT_BUS_QUEUE_MODE` → `COMMAND_BUS_QUEUE_MODE`
+- `EVENT_BUS_LOG` → `COMMAND_BUS_LOG`
+
+### Przykład Konfiguracji .env
+
+```bash
+# Połączenie Redis
+REDIS_URL=redis://username:password@localhost:6379/0
+
+# Poziom logowania
+LOG_LEVEL=log                              # debug | log | warn | error
+
+# Auto-optymalizacja (domyślnie włączona)
+COMMAND_BUS_AUTO_OPTIMIZE=true
+
+# Concurrency (opcjonalnie - auto-optymalizacja ustawi optymalną wartość)
+# COMMAND_BUS_CONCURRENCY=10
+
+# Retry i backoff
+COMMAND_BUS_MAX_ATTEMPTS=1                 # Maksymalna liczba prób
+COMMAND_BUS_BACKOFF_DELAY=3000             # Opóźnienie między próbami (3s)
+
+# Tryb kolejki
+COMMAND_BUS_QUEUE_MODE=fifo                # fifo lub lifo
+
+# Kompresja payloadów (próg w bajtach)
+COMMAND_BUS_COMPRESSION_THRESHOLD=2048     # 2KB (domyślnie 1KB)
+
+# Logowanie komend do plików
+COMMAND_BUS_LOG=./command-logs             # Ścieżka do katalogu logów
+```
+
+### Priorytety Konfiguracji
+
+1. **Parametry konstruktora** - najwyższy priorytet
+2. **Zmienne środowiskowe** - średni priorytet
+3. **Wartości domyślne** - najniższy priorytet
+
+```typescript
+// Przykład: parametry konstruktora nadpisują ENV
+const config = new CommandBusConfig({
+  redisUrl: 'redis://localhost:6379',
+  concurrency: 20, // Nadpisuje COMMAND_BUS_CONCURRENCY
+  autoOptimize: false, // Wyłącza auto-optymalizację
+});
+```
+
 ## Konfiguracja zaawansowana
 
-### Opcje Redis
+### Auto-optymalizacja Concurrency
+
+Auto-optymalizacja automatycznie oblicza optymalną wartość concurrency na podstawie zasobów systemowych:
 
 ```typescript
+// Auto-optymalizacja włączona (domyślnie)
 const config = new CommandBusConfig({
-  redisUrl: 'redis://username:password@localhost:6379/0',
-  // Parsuje się do:
-  // - host: localhost
-  // - port: 6379
-  // - username: username (opcjonalnie)
-  // - password: password (opcjonalnie)
-  // - db: 0 (opcjonalnie)
+  redisUrl: 'redis://localhost:6379',
+  autoOptimize: true, // Domyślnie true
+  // concurrency zostanie obliczone jako: CPU cores * 2 + (availableMemory / 512MB)
+});
+
+// Wyłączenie auto-optymalizacji
+const config2 = new CommandBusConfig({
+  redisUrl: 'redis://localhost:6379',
+  autoOptimize: false,
+  concurrency: 10, // Ręczna wartość
 });
 ```
 
+**Algorytm auto-optymalizacji**:
+```
+concurrency = (CPU cores * 2) + Math.floor(availableMemory / 512MB)
+
+Przykład:
+- 8 CPU cores
+- 16GB RAM dostępne
+- concurrency = (8 * 2) + Math.floor(16384 / 512) = 16 + 32 = 48
+```
+
+### Kompresja Payloadów
+
+Automatyczna kompresja gzip dla payloadów RPC większych niż threshold:
+
+```typescript
+const config = new CommandBusConfig({
+  redisUrl: 'redis://localhost:6379',
+  compressionThreshold: 2048, // 2KB (domyślnie 1KB)
+});
+
+// Przykład: payload 3KB zostanie automatycznie skompresowany
+const largeCommand = new ProcessReportCommand(largeData); // 3KB
+const result = await commandBus.call(largeCommand); // Automatyczna kompresja/dekompresja
+```
+
+**Korzyści kompresji**:
+- Redukcja transferu danych przez Redis
+- Szybsze przesyłanie dużych payloadów
+- Niższe zużycie pamięci Redis
+- Transparent dla użytkownika (automatyczna dekompresja)
+
 ### Command Logging
 
-Logowanie komend do plików (lokalizacja katalogu):
+Logowanie komend do plików JSONL (rotacja co godzinę):
 
 ```typescript
 const config = new CommandBusConfig({
   redisUrl: 'redis://localhost:6379',
   commandLog: './command-logs', // Ścieżka do katalogu logów
 });
+
+// Struktura plików:
+// ./command-logs/2025-01-27T10.jsonl
+// ./command-logs/2025-01-27T11.jsonl
+```
+
+**Format JSONL (JSON Lines)**:
+```json
+{"__name":"CreateUserCommand","__id":"uuid","__time":1706347200000,"email":"jan@example.com","name":"Jan"}
+{"__name":"ProcessOrderCommand","__id":"uuid","__time":1706347201000,"orderId":"12345"}
+```
+
+### Opcje Redis
+
+```typescript
+const config = new CommandBusConfig({
+  redisUrl: 'redis://username:password@localhost:6379/0',
+  // Parsuje się do:
+  // - host: localhost
+  // - port: 6379
+  // - username: username (opcjonalnie)
+  // - password: password (opcjonalnie)
+  // - db: 0 (opcjonalnie)
+});
 ```
 
 ### Concurrency i Retry
@@ -148,19 +449,18 @@ const config = new CommandBusConfig({
 ```typescript
 const config = new CommandBusConfig({
   redisUrl: 'redis://localhost:6379',
-  concurrency: 10, // Liczba równoległych workerów dla komend
+  concurrency: 10, // Liczba równoległych workerów (lub auto)
   maxAttempts: 5, // Maksymalna liczba prób przetworzenia zadania
-  backoffDelay: 2000, // Opóźnienie między próbami (ms)
+  backoffDelay: 3000, // Opóźnienie między próbami (3s)
 });
 ```
 
-### Tryb kolejki i RPC TTL
+### Tryb kolejki
 
 ```typescript
 const config = new CommandBusConfig({
   redisUrl: 'redis://localhost:6379',
   queueMode: 'fifo', // 'fifo' (First In First Out) lub 'lifo' (Last In First Out)
-  rpcReplyTtl: 60000, // TTL dla odpowiedzi RPC w milisekundach (1 minuta)
 });
 ```
 
@@ -207,24 +507,46 @@ const config2 = new CommandBusConfig({
 
 Wysyła komendę do kolejki bez oczekiwania na wynik (fire-and-forget).
 
+**Flow**:
+1. Kompresja payloadu (jeśli >threshold)
+2. Pobranie/utworzenie kolejki z cache
+3. Dodanie job do BullMQ
+4. Natychmiastowy return
+
 ```typescript
 await commandBus.dispatch(new CreateUserCommand('email@example.com', 'Jan Kowalski'));
 ```
 
 #### `call<T>(command: Command, timeout?: number): Promise<T>`
 
-Wywołuje komendę synchronicznie i czeka na odpowiedź (RPC). Domyślny timeout: 30000ms (30s).
+Wywołuje komendę synchronicznie i czeka na odpowiedź przez Redis Pub/Sub (RPC). Domyślny timeout: 30000ms (30s).
+
+**Flow**:
+1. Rejestracja pending call z timeoutem
+2. Kompresja payloadu (jeśli >threshold)
+3. Przygotowanie metadanych RPC (correlationId, responseChannel)
+4. Dodanie job do BullMQ
+5. Oczekiwanie na odpowiedź przez shared subscriber
+6. Dekompresja odpowiedzi
+7. Zwrócenie wyniku lub błędu
 
 ```typescript
 const result = await commandBus.call<{ userId: string }>(command, 5000);
 ```
 
-#### `handle<T>(commandClass, handler): Promise<void>`
+#### `handle<T>(commandClass, handler): void`
+
+Rejestruje handler dla określonej klasy komendy. Tylko jeden handler per typ komendy.
 
-Rejestruje handler dla określonej klasy komendy.
+**Automatyczne akcje**:
+1. Rejestracja handlera w Map
+2. Utworzenie workera BullMQ
+3. Uruchomienie benchmarku dla optymalnego concurrency
+4. Utworzenie metrics collector
+5. Setup event handlers
 
 ```typescript
-await commandBus.handle(CreateUserCommand, async (command) => {
+commandBus.handle(CreateUserCommand, async (command) => {
   const user = await createUser(command.email, command.name);
   return { userId: user.id };
 });
@@ -232,7 +554,13 @@ await commandBus.handle(CreateUserCommand, async (command) => {
 
 #### `close(): Promise<void>`
 
-Zamyka wszystkie połączenia i workery.
+Zamyka wszystkie połączenia i workery z graceful shutdown.
+
+**Cleanup**:
+1. Zamknięcie wszystkich workerów BullMQ
+2. Zamknięcie wszystkich kolejek z cache
+3. Zamknięcie RpcCoordinator (reject pending calls)
+4. Zamknięcie 3 połączeń Redis (Queue, Worker, RPC)
 
 ```typescript
 await commandBus.close();
@@ -250,10 +578,13 @@ class MyCommand extends Command {
 }
 ```
 
-Każda komenda ma:
-- `__id` - unikalny UUID
-- `__name` - nazwa klasy komendy
-- `__timestamp` - timestamp utworzenia
+**Właściwości automatyczne**:
+- `__id` - unikalny UUID (randomUUID)
+- `__name` - nazwa klasy komendy (constructor.name)
+- `__time` - timestamp utworzenia (Date.now())
+
+**Metody statyczne**:
+- `reconstructDates(obj)` - rekonstrukcja obiektów Date z serializowanych danych
 
 ### CommandBusConfig
 
@@ -264,72 +595,205 @@ interface CommandBusConfigOptions {
   redisUrl?: string; // URL Redis (domyślnie: 'redis://localhost:6379' lub REDIS_URL)
   logger?: ILogger; // Logger (domyślnie console)
   logLevel?: 'debug' | 'log' | 'warn' | 'error'; // Poziom logowania (domyślnie 'log')
-  concurrency?: number; // Liczba workerów komend (domyślnie 1)
-  maxAttempts?: number; // Maksymalna liczba prób (domyślnie 3)
+  concurrency?: number; // Liczba workerów (domyślnie 1 lub auto)
+  maxAttempts?: number; // Maksymalna liczba prób (domyślnie 1)
   backoffDelay?: number; // Opóźnienie między próbami w ms (domyślnie 2000)
   queueMode?: 'fifo' | 'lifo'; // Tryb kolejki (domyślnie 'fifo')
   commandLog?: string; // Ścieżka do katalogu logów komend (opcjonalnie)
+  autoOptimize?: boolean; // Auto-optymalizacja concurrency (domyślnie true)
+  compressionThreshold?: number; // Próg kompresji w bajtach (domyślnie 1024)
 }
 ```
 
-## Migracja z pp-event-bus 1.x
+## Przykłady Użycia
 
-Jeśli używałeś Command Bus z pakietu `pp-event-bus` w wersji 1.x:
+### Podstawowy przykład z RPC
 
-### Przed:
+```typescript
+import { CommandBus, CommandBusConfig, Command } from 'pp-command-bus';
+
+// Definicja komendy
+class CalculateCommand extends Command {
+  constructor(
+    public readonly a: number,
+    public readonly b: number,
+    public readonly operation: 'add' | 'multiply',
+  ) {
+    super();
+  }
+}
+
+// Konfiguracja
+const config = new CommandBusConfig({
+  redisUrl: 'redis://localhost:6379',
+});
+const commandBus = new CommandBus(config);
+
+// Rejestracja handlera
+commandBus.handle(CalculateCommand, async (command) => {
+  console.log(`Calculating: ${command.a} ${command.operation} ${command.b}`);
+
+  switch (command.operation) {
+    case 'add':
+      return command.a + command.b;
+    case 'multiply':
+      return command.a * command.b;
+  }
+});
+
+// Fire-and-forget
+await commandBus.dispatch(new CalculateCommand(5, 3, 'add'));
+
+// RPC - czekamy na wynik
+const result = await commandBus.call<number>(
+  new CalculateCommand(5, 3, 'multiply'),
+  5000 // timeout 5s
+);
+console.log(`Result: ${result}`); // Result: 15
+```
+
+### Równoległe wywołania RPC
 
 ```typescript
-import { CommandBus, Command, CommandBusConfig } from 'pp-event-bus';
+// Wiele równoległych RPC calls
+const [result1, result2, result3] = await Promise.all([
+  commandBus.call<number>(new CalculateCommand(10, 5, 'add')),
+  commandBus.call<UserInfo>(new GetUserInfoCommand('user-1')),
+  commandBus.call<ValidationResult>(new ValidateUserCommand('jan@example.com', 30)),
+]);
+
+console.log('All results:', { result1, result2, result3 });
 ```
 
-### Po:
+### Obsługa błędów
 
-```bash
-npm install pp-command-bus
+```typescript
+commandBus.handle(CreateUserCommand, async (command) => {
+  try {
+    // Walidacja
+    if (!command.email.includes('@')) {
+      throw new Error('Invalid email format');
+    }
+
+    const user = await createUser(command.email, command.name);
+    return { userId: user.id };
+  } catch (error) {
+    // Loguj błąd
+    console.error('Failed to create user:', error);
+
+    // Rzuć błąd - BullMQ spróbuje ponownie (maxAttempts)
+    throw error;
+  }
+});
+
+// Obsługa błędów w RPC
+try {
+  const result = await commandBus.call(new CreateUserCommand('invalid-email', 'Jan'));
+} catch (error) {
+  console.error('RPC failed:', error.message);
+}
 ```
 
+### Graceful Shutdown
+
 ```typescript
-import { CommandBus, Command, CommandBusConfig } from 'pp-command-bus';
+process.on('SIGTERM', async () => {
+  console.log('Shutting down CommandBus...');
+  await commandBus.close();
+  process.exit(0);
+});
+
+process.on('SIGINT', async () => {
+  console.log('Shutting down CommandBus...');
+  await commandBus.close();
+  process.exit(0);
+});
 ```
 
-**Pełna zgodność API** - jedyna zmiana to źródło importu.
+## Zaawansowane Funkcje
 
-## Zmienne środowiskowe
+### 1. Dynamiczne Concurrency
 
-Biblioteka wspiera konfigurację poprzez zmienne środowiskowe z prefiksem `COMMAND_BUS_` (z fallbackiem do starszych nazw `EVENT_BUS_*`):
+WorkerOrchestrator automatycznie dostosowuje concurrency na podstawie metryk:
 
-```bash
-# Połączenie Redis
-REDIS_URL=redis://localhost:6379
+- **Benchmark przy starcie** - optymalny concurrency dla każdego workera
+- **Event-driven metrics** - zbieranie metryk z workerów
+- **Dynamiczne dostosowanie** - +/-20% co 30s (cooldown)
+- **Limity** - min 10, max 2000
 
-# Poziom logowania
-LOG_LEVEL=log                              # debug | log | warn | error
+```typescript
+// Automatyczne - benchmark ustali optymalną wartość
+const config = new CommandBusConfig({
+  redisUrl: 'redis://localhost:6379',
+  // concurrency zostanie ustalone przez benchmark (np. 15-20)
+});
+```
 
-# Concurrency
-COMMAND_BUS_CONCURRENCY=5                  # Liczba workerów komend (fallback: EVENT_BUS_CONCURRENCY)
+### 2. Process Isolation w RPC
 
-# Retry i backoff
-COMMAND_BUS_MAX_ATTEMPTS=3                 # Maksymalna liczba prób (fallback: EVENT_BUS_MAX_ATTEMPTS)
-COMMAND_BUS_BACKOFF_DELAY=2000             # Opóźnienie między próbami w ms (fallback: EVENT_BUS_BACKOFF_DELAY)
+Każdy proces Node.js ma unikalny UUID - odpowiedzi RPC są izolowane między procesami:
 
-# Tryb kolejki
-COMMAND_BUS_QUEUE_MODE=fifo                # fifo lub lifo (fallback: EVENT_BUS_QUEUE_MODE)
+```
+Process A (UUID: abc-123):
+- Kanał: rpc:response:abc-123:*
+- Otrzymuje tylko swoje odpowiedzi
 
-# Logowanie komend
-COMMAND_BUS_LOG=./command-logs             # Ścieżka do katalogu logów (fallback: EVENT_BUS_LOG)
+Process B (UUID: def-456):
+- Kanał: rpc:response:def-456:*
+- Otrzymuje tylko swoje odpowiedzi
 ```
 
-### Wartości domyślne
+### 3. Shared Subscriber Pattern
+
+Jeden shared subscriber dla wszystkich RPC calls zamiast N subskrybentów:
 
-| Zmienna | Wartość domyślna | Opis |
-|---------|------------------|------|
-| `REDIS_URL` | `redis://localhost:6379` | URL połączenia Redis |
-| `LOG_LEVEL` | `log` | Poziom logowania |
-| `COMMAND_BUS_CONCURRENCY` | `1` | Liczba workerów komend |
-| `COMMAND_BUS_MAX_ATTEMPTS` | `3` | Maksymalna liczba prób |
-| `COMMAND_BUS_BACKOFF_DELAY` | `2000` | Opóźnienie między próbami (ms) |
-| `COMMAND_BUS_QUEUE_MODE` | `fifo` | Tryb kolejki |
-| `COMMAND_BUS_LOG` | _(puste)_ | Brak logowania komend |
+**Tradycyjne podejście** (N subskrybentów):
+```
+1000 RPC calls → 1000 Redis subscriptions → duże obciążenie
+```
+
+**Shared Subscriber** (1 subskrybent):
+```
+1000 RPC calls → 1 Redis pattern subscription → multiplexing w pamięci
+```
+
+### 4. Automatyczna Kompresja
+
+PayloadCompressionService automatycznie kompresuje duże payloady:
+
+```typescript
+// Mała komenda (<1KB) - brak kompresji
+const smallCommand = new CreateUserCommand('jan@example.com', 'Jan');
+await commandBus.call(smallCommand); // Bez kompresji
+
+// Duża komenda (>1KB) - automatyczna kompresja
+const largeCommand = new ProcessReportCommand(largeData); // 5KB
+await commandBus.call(largeCommand); // Automatyczna kompresja gzip → base64
+```
+
+**Flagi kompresji**:
+- `__compressed: true` - payload został skompresowany
+- Automatyczna dekompresja w JobProcessor
+- Transparent dla użytkownika
+
+### 5. Command Logging
+
+Persystencja wszystkich komend do plików JSONL:
+
+```typescript
+const config = new CommandBusConfig({
+  commandLog: './command-logs',
+});
+
+// Każda komenda jest logowana do pliku:
+// ./command-logs/2025-01-27T10.jsonl
+```
+
+**Use cases**:
+- Auditing i compliance
+- Replay komend
+- Debugging produkcyjnych problemów
+- Analiza przepływu komend
 
 ## Best Practices
 
@@ -364,42 +828,55 @@ commandBus.handle(CreateUserCommand, async (command) => {
 });
 ```
 
-### 3. Obsługa błędów
+### 3. Monitorowanie RPC timeoutów
 
 ```typescript
-commandBus.handle(CreateUserCommand, async (command) => {
-  try {
-    const user = await createUser(command.email, command.name);
-    return { userId: user.id };
-  } catch (error) {
-    // Loguj błąd
-    console.error('Failed to create user:', error);
+// Ustaw timeout dostosowany do czasu przetwarzania komendy
+const shortCommand = new QuickCommand();
+const result1 = await commandBus.call(shortCommand, 1000); // 1s dla szybkich operacji
 
-    // Rzuć błąd - BullMQ spróbuje ponownie (maxAttempts)
-    throw error;
-  }
-});
+const longRunningCommand = new ProcessReportCommand();
+const result2 = await commandBus.call(longRunningCommand, 60000); // 60s dla długich operacji
 ```
 
-### 4. Graceful shutdown
+### 4. Walidacja w handlerach
 
 ```typescript
-process.on('SIGTERM', async () => {
-  console.log('Shutting down CommandBus...');
-  await commandBus.close();
-  process.exit(0);
+commandBus.handle(CreateUserCommand, async (command) => {
+  // Walidacja na początku
+  if (!command.email || !command.email.includes('@')) {
+    throw new Error('Invalid email');
+  }
+
+  if (!command.name || command.name.length < 2) {
+    throw new Error('Invalid name');
+  }
+
+  // Logika biznesowa
+  return await createUser(command.email, command.name);
 });
 ```
 
-### 5. Monitorowanie RPC timeoutów
+### 5. Logowanie kontekstu
 
 ```typescript
-// Ustaw timeout dostosowany do czasu przetwarzania komendy
-const shortCommand = new QuickCommand();
-const result1 = await commandBus.call(shortCommand, 1000); // 1s dla szybkich operacji
+commandBus.handle(CreateUserCommand, async (command) => {
+  console.log('Processing CreateUserCommand', {
+    commandId: command.__id,
+    timestamp: command.__time,
+    email: command.email,
+  });
 
-const longRunningCommand = new ProcessReportCommand();
-const result2 = await commandBus.call(longRunningCommand, 60000); // 60s dla długich operacji
+  // Logika biznesowa
+  const user = await createUser(command.email, command.name);
+
+  console.log('User created successfully', {
+    commandId: command.__id,
+    userId: user.id,
+  });
+
+  return { userId: user.id };
+});
 ```
 
 ## Testing
@@ -416,12 +893,13 @@ describe('User Commands', () => {
     const config = new CommandBusConfig({
       redisUrl: 'redis://localhost:6379',
       logger: console,
+      logLevel: 'error', // Tylko błędy w testach
     });
 
     commandBus = new CommandBus(config);
 
     // Zarejestruj handler
-    await commandBus.handle(CreateUserCommand, async (command) => {
+    commandBus.handle(CreateUserCommand, async (command) => {
       return { userId: 'test-user-id' };
     });
   });
@@ -435,6 +913,24 @@ describe('User Commands', () => {
     const result = await commandBus.call<{ userId: string }>(command, 5000);
 
     expect(result.userId).toBeDefined();
+    expect(result.userId).toBe('test-user-id');
+  });
+
+  it('should handle multiple commands in parallel', async () => {
+    const commands = [
+      new CreateUserCommand('user1@example.com', 'User 1'),
+      new CreateUserCommand('user2@example.com', 'User 2'),
+      new CreateUserCommand('user3@example.com', 'User 3'),
+    ];
+
+    const results = await Promise.all(
+      commands.map((cmd) => commandBus.call<{ userId: string }>(cmd, 5000))
+    );
+
+    expect(results).toHaveLength(3);
+    results.forEach((result) => {
+      expect(result.userId).toBeDefined();
+    });
   });
 });
 ```
@@ -459,7 +955,7 @@ Zwiększ timeout lub sprawdź czy handler został zarejestrowany:
 const result = await commandBus.call(command, 60000); // 60s
 
 // Sprawdź czy handler został zarejestrowany PRZED wywołaniem
-await commandBus.handle(MyCommand, async (command) => {
+commandBus.handle(MyCommand, async (command) => {
   // Handler implementation
   return { result: 'success' };
 });
@@ -475,19 +971,102 @@ Upewnij się że handler został zarejestrowany przed wysłaniem komendy:
 ```typescript
 // ❌ ŹLE - handler po dispatch
 await commandBus.dispatch(new MyCommand());
-await commandBus.handle(MyCommand, async (cmd) => { ... }); // Za późno!
+commandBus.handle(MyCommand, async (cmd) => { ... }); // Za późno!
 
 // ✅ DOBRZE - handler przed dispatch
-await commandBus.handle(MyCommand, async (cmd) => { ... });
+commandBus.handle(MyCommand, async (cmd) => { ... });
 await commandBus.dispatch(new MyCommand()); // Teraz OK
 ```
 
-## Licencja
+### Wysokie zużycie pamięci
 
-MIT
+1. **Wyłącz command logging** jeśli nie jest potrzebne
+2. **Zmniejsz concurrency** jeśli workery używają dużo pamięci
+3. **Zwiększ compressionThreshold** jeśli duże payloady powodują problemy
 
-## Autorzy
-- Mariusz Lejkowski <m.lejkowski@polskiepolisy.pl>
+```typescript
+const config = new CommandBusConfig({
+  commandLog: undefined, // Wyłącz logging
+  concurrency: 5, // Zmniejsz concurrency
+  compressionThreshold: 512, // Kompresuj już od 512B
+});
+```
+
+### Worker stalled
+
+Worker został zatrzymany (prawdopodobnie crashed). BullMQ automatycznie przeniesie job do innego workera.
+
+**Przyczyny**:
+- Out of memory
+- Uncaught exception w handlerze
+- Timeout w handlerze
+
+**Rozwiązanie**:
+- Dodaj try/catch w handlerze
+- Zwiększ pamięć dla procesu
+- Zmniejsz concurrency
+
+## Struktura Projektu
+
+```
+src/
+├── command-bus/                # Główna logika CommandBus
+│   ├── config/                 # Konfiguracja CommandBus
+│   │   ├── command-bus-config.ts
+│   │   └── auto-config-optimizer.ts
+│   ├── job/                    # Przetwarzanie jobów i opcje
+│   │   ├── job-processor.ts
+│   │   └── job-options-builder.ts
+│   ├── logging/                # Command logging do plików
+│   │   └── command-logger.ts
+│   ├── queue/                  # Queue management i cache
+│   │   └── queue-manager.ts
+│   ├── rpc/                    # RPC coordination
+│   │   ├── rpc-coordinator.ts
+│   │   └── payload-compression.service.ts
+│   ├── worker/                 # Worker orchestration
+│   │   ├── worker-orchestrator.ts
+│   │   ├── worker-benchmark.ts
+│   │   └── worker-metrics-collector.ts
+│   ├── types/                  # Typy TypeScript
+│   │   └── index.ts
+│   ├── command.ts              # Klasa bazowa Command
+│   └── index.ts                # CommandBus główna klasa
+├── shared/                     # Wspólne komponenty
+│   ├── config/                 # Base config z Redis
+│   │   └── base-config.ts
+│   ├── logging/                # Logger wrapper z poziomami
+│   │   ├── logger.ts
+│   │   └── log-level.ts
+│   └── types.ts                # Współdzielone typy
+├── examples/                   # Przykłady użycia
+│   ├── rpc.demo.ts             # Demo RPC calls
+│   ├── rpc-throughput.demo.ts  # Demo wydajności RPC
+│   └── rpc-compression.demo.ts # Demo kompresji
+└── index.ts                    # Główny export pakietu
+```
+
+## Migracja z pp-event-bus 1.x
+
+Jeśli używałeś Command Bus z pakietu `pp-event-bus` w wersji 1.x:
+
+### Przed:
+
+```typescript
+import { CommandBus, Command, CommandBusConfig } from 'pp-event-bus';
+```
+
+### Po:
+
+```bash
+npm install pp-command-bus
+```
+
+```typescript
+import { CommandBus, Command, CommandBusConfig } from 'pp-command-bus';
+```
+
+**Pełna zgodność API** - jedyna zmiana to źródło importu.
 
 ## Wersjonowanie i Releases
 
@@ -528,56 +1107,6 @@ test: dodano testy dla command logging
 - `chore:` - inne zmiany (bez release)
 - `!` lub `BREAKING CHANGE:` - breaking change (→ major release)
 
-### Proces release
-
-1. **Commituj zgodnie z konwencją** - husky sprawdzi format commita
-2. **Merge do master** - GitLab CI automatycznie:
-   - Uruchomi testy i linting
-   - Zbuduje projekt
-   - Wygeneruje nową wersję (semantic-release)
-   - Zaktualizuje CHANGELOG.md
-   - Opublikuje do npm
-   - Utworzy GitLab release
-
-### Branch model
-
-- `master` - branch produkcyjny (→ release do npm)
-- `beta` - branch pre-release (→ beta release do npm)
-- feature branches - tworzenie nowych funkcjonalności
-
-### CI/CD Pipeline
-
-GitLab CI wykonuje następujące etapy:
-
-**Quality Stage:**
-- `lint` - sprawdzenie jakości kodu (ESLint + Prettier)
-- `test` - testy jednostkowe i coverage
-
-**Build Stage:**
-- `build` - kompilacja TypeScript do JavaScript
-
-**Release Stage:**
-- `release:production` - automatyczny release z master
-- `release:beta` - automatyczny release z beta
-- `release:dry-run` - podgląd zmian (manual trigger)
-
-### Zmienne środowiskowe w GitLab
-
-Aby pipeline działał, skonfiguruj w GitLab CI/CD Settings → Variables:
-
-- `NPM_TOKEN` - token do publikacji w npm (z scope publish)
-- `GITLAB_TOKEN` - token do tworzenia release'ów w GitLab
-
-### Testowanie release lokalnie
-
-```bash
-# Podgląd co zostanie wypuszczone
-npm run semantic-release:dry-run
-
-# Sprawdzenie ostatniego release
-git tag --sort=-v:refname | head -n 1
-```
-
 ## Dokumentacja
 
 ### Architektura
@@ -587,12 +1116,21 @@ Szczegółowa dokumentacja architektury systemu, wzorców projektowych i zasad S
 
 ### Komponenty
 
-- **QueueManager** - zarządzanie kolejkami BullMQ i cache reply queues
-- **WorkerOrchestrator** - orkiestracja workerów i obsługa zdarzeń
+- **QueueManager** - zarządzanie kolejkami BullMQ i cache kolejek
+- **WorkerOrchestrator** - orkiestracja workerów, dynamiczne concurrency, benchmark
 - **JobProcessor** - przetwarzanie jobów i wykonanie handlerów
-- **RpcCoordinator** - zarządzanie wywołaniami RPC i timeoutami
+- **RpcCoordinator** - zarządzanie wywołaniami RPC przez Redis Pub/Sub
 - **JobOptionsBuilder** - konfiguracja opcji dla jobów BullMQ
 - **CommandLogger** - persystencja komend do plików JSONL
+- **PayloadCompressionService** - automatyczna kompresja gzip
+- **AutoConfigOptimizer** - optymalizacja concurrency na podstawie zasobów
+
+## Licencja
+
+MIT
+
+## Autorzy
+- Mariusz Lejkowski <m.lejkowski@polskiepolisy.pl>
 
 ## Linki