pp-command-bus 1.3.2 → 1.5.0

package/README.md

@@ -18,6 +18,7 @@ Distributed Command Bus library supporting RPC and job queuing with BullMQ for R
 - ✅ **TypeScript** - pełne wsparcie typów i strict mode
 - ✅ **Memory leak protection** - zaawansowana diagnostyka i cleanup
 - ✅ **Command logging** - opcjonalne logowanie komend do plików JSONL
+- ✅ **RPC Job Cancellation** - automatyczne usuwanie niepodjętych jobów RPC przy timeout
 - ✅ **Modularna architektura** - komponenty zgodne z zasadami SOLID, DDD i SRP
 
 ## Architektura Systemu
@@ -67,6 +68,7 @@ Distributed Command Bus library supporting RPC and job queuing with BullMQ for R
   - **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
+  - **Job Cancellation** - usuwanie niepodjętych jobów przy timeout (optymalizacja zasobów)
   - **Multiplexing** - routing odpowiedzi do odpowiednich promises
 - **Kanały**: `rpc:response:{processId}:{correlationId}`
 
@@ -83,11 +85,13 @@ Distributed Command Bus library supporting RPC and job queuing with BullMQ for R
 - **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)
+  2. Sprawdzenie flagi cancellation (pomijanie anulowanych RPC)
+  3. Rekonstrukcja obiektów Date
+  4. Opcjonalne logowanie komendy
+  5. Wykonanie handlera
+  6. Wysłanie odpowiedzi RPC przez Pub/Sub (jeśli RPC)
 - **Kompresja odpowiedzi**: automatyczna kompresja przez PayloadCompressionService
+- **RPC Cancellation**: pomijanie jobów oznaczonych jako anulowane (timeout)
 
 #### 5. **QueueManager** (zarządzanie kolejkami)
 - **Odpowiedzialność**: Cache kolejek BullMQ dla optymalizacji pamięci
@@ -106,13 +110,24 @@ Distributed Command Bus library supporting RPC and job queuing with BullMQ for R
   - `decompress(data, compressed)` - generyczna dekompresja
 - **Współdzielony serwis**: jedna instancja dla całego CommandBus
 
-#### 7. **CommandLogger** (opcjonalne logowanie)
+#### 7. **RpcJobCancellationService** (anulowanie jobów RPC)
+- **Odpowiedzialność**: Zarządzanie anulowaniem niepodjętych jobów RPC przy timeout
+- **Kluczowe funkcje**:
+  - **markAsCancelled(correlationId)** - oznacza job jako anulowany w Redis
+  - **isCancelled(correlationId)** - sprawdza flagę cancellation
+  - **clearCancellation(correlationId)** - usuwa flagę po przetworzeniu/usunięciu
+  - **tryRemoveJob(jobId, queueName, callback)** - próba usunięcia joba z kolejki
+- **TTL kluczy Redis**: 24 godziny (automatyczne wygaśnięcie)
+- **Graceful degradation**: błędy Redis nie blokują przetwarzania (zwraca false)
+- **Klucze Redis**: `rpc:cancelled:{correlationId}`
+
+#### 8. **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)
+#### 9. **AutoConfigOptimizer** (auto-optymalizacja)
 - **Odpowiedzialność**: Obliczanie optymalnego concurrency na podstawie zasobów systemowych
 - **Heurystyka**:
   - I/O-heavy workload (Redis/BullMQ)
@@ -120,7 +135,7 @@ Distributed Command Bus library supporting RPC and job queuing with BullMQ for R
   - Zakładane 512MB RAM per worker
 - **Aktywacja**: domyślnie włączone (ENV `COMMAND_BUS_AUTO_OPTIMIZE=false` wyłącza)
 
-#### 9. **RedisConnectionFactory** (fabryka połączeń Redis)
+#### 10. **RedisConnectionFactory** (fabryka połączeń Redis)
 - **Odpowiedzialność**: Tworzenie połączeń Redis z wbudowaną obsługą błędów i eventów
 - **Zgodność z SRP**: CommandBus nie zarządza bezpośrednio połączeniami
 - **Kluczowe funkcje**:
@@ -256,12 +271,9 @@ const commandBus = new CommandBus(config);
 ### 2. Definiowanie komend
 
 ```typescript
-class CreateUserCommand extends Command {
-  constructor(
-    public readonly email: string,
-    public readonly name: string,
-  ) {
-    super();
+class CreateUserCommand extends Command<{ email: string; name: string }> {
+  constructor(payload: { email: string; name: string }) {
+    super(payload);
   }
 }
 ```
@@ -270,10 +282,11 @@ class CreateUserCommand extends Command {
 
 ```typescript
 commandBus.handle(CreateUserCommand, async (command) => {
-  console.log(`Creating user: ${command.name} (${command.email})`);
+  const { name, email } = command.__payload;
+  console.log(`Creating user: ${name} (${email})`);
 
   // Twoja logika biznesowa
-  const user = await createUser(command.email, command.name);
+  const user = await createUser(email, name);
 
   // Zwróć wynik (opcjonalnie)
   return { userId: user.id };
@@ -283,7 +296,10 @@ commandBus.handle(CreateUserCommand, async (command) => {
 ### 4. Wysyłanie komend (Fire-and-forget)
 
 ```typescript
-const command = new CreateUserCommand('jan.kowalski@example.com', 'Jan Kowalski');
+const command = new CreateUserCommand({
+  email: 'jan.kowalski@example.com',
+  name: 'Jan Kowalski'
+});
 
 // Wyślij komendę bez oczekiwania na wynik
 await commandBus.dispatch(command);
@@ -307,6 +323,8 @@ Biblioteka wspiera konfigurację poprzez zmienne środowiskowe z prefiksem `COMM
 | Zmienna | Typ | Wartość Domyślna | Opis |
 |---------|-----|------------------|------|
 | `REDIS_URL` | string | `redis://localhost:6379` | URL połączenia Redis/DragonflyDB (wspiera username, password, db) |
+| `REDIS_RETRY_DELAY` | number | `5000` | Opóźnienie między próbami reconnect do Redis w milisekundach |
+| `REDIS_MAX_RETRIES` | number | `0` | Maksymalna liczba prób reconnect (0 = nieskończoność) |
 | `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 |
@@ -332,6 +350,10 @@ Dla kompatybilności wstecznej obsługiwane są również prefiksy `EVENT_BUS_*`
 # Połączenie Redis
 REDIS_URL=redis://username:password@localhost:6379/0
 
+# Strategia reconnect Redis (stałe opóźnienie)
+REDIS_RETRY_DELAY=5000                     # 5 sekund między próbami (domyślnie)
+REDIS_MAX_RETRIES=0                        # 0 = nieskończoność (domyślnie)
+
 # Poziom logowania
 LOG_LEVEL=log                              # debug | log | warn | error
 
@@ -528,7 +550,10 @@ Wysyła komendę do kolejki bez oczekiwania na wynik (fire-and-forget).
 4. Natychmiastowy return
 
 ```typescript
-await commandBus.dispatch(new CreateUserCommand('email@example.com', 'Jan Kowalski'));
+await commandBus.dispatch(new CreateUserCommand({
+  email: 'email@example.com',
+  name: 'Jan Kowalski'
+}));
 ```
 
 #### `call<T>(command: Command, timeout?: number): Promise<T>`
@@ -561,7 +586,8 @@ Rejestruje handler dla określonej klasy komendy. Tylko jeden handler per typ ko
 
 ```typescript
 commandBus.handle(CreateUserCommand, async (command) => {
-  const user = await createUser(command.email, command.name);
+  const { email, name } = command.__payload;
+  const user = await createUser(email, name);
   return { userId: user.id };
 });
 ```
@@ -582,23 +608,105 @@ await commandBus.close();
 
 ### Command
 
-Klasa bazowa dla wszystkich komend. Każda komenda dziedziczy po `Command`:
+Klasa bazowa dla wszystkich komend. Każda komenda dziedziczy po `Command<T>` gdzie `T` to typ danych biznesowych:
 
 ```typescript
-class MyCommand extends Command {
-  constructor(public readonly data: string) {
-    super();
+class MyCommand extends Command<{ data: string }> {
+  constructor(payload: { data: string }) {
+    super(payload);
   }
 }
+
+// Uzycie
+const cmd = new MyCommand({ data: 'hello' });
+console.log(cmd.__payload.data); // 'hello'
+```
+
+#### Struktura Komendy
+
+Kazda komenda po serializacji ma nastepujaca strukture:
+
+```typescript
+{
+  "__name": "MyCommand",           // Nazwa klasy komendy
+  "__id": "550e8400-e29b-41d4-a716-446655440000",  // UUID komendy
+  "__time": 1706347200000,         // Timestamp utworzenia (ms)
+  "__payload": {                   // Dane biznesowe komendy
+    "data": "hello"
+  }
+}
+```
+
+#### Opis Pol Komendy
+
+| Pole | Typ | Opis |
+|------|-----|------|
+| `__name` | `string` | Nazwa klasy komendy (automatycznie ustawiana z `constructor.name`). Uzywana do routowania do odpowiedniego handlera. |
+| `__id` | `string` | Unikalny identyfikator komendy (UUID v4). Generowany automatycznie przy tworzeniu komendy. Uzywany do korelacji RPC i logowania. |
+| `__time` | `number` | Timestamp utworzenia komendy w milisekundach (`Date.now()`). Uzywany do audytu i debugowania. |
+| `__payload` | `T` | Dane biznesowe komendy. Wszystkie dane specyficzne dla komendy powinny byc przechowywane tutaj. Typ `T` jest generyczny i definiowany przy tworzeniu klasy komendy. |
+
+#### Przyklad Definicji Komendy
+
+```typescript
+// Komenda z prostym payloadem
+class CreateUserCommand extends Command<{ name: string; email: string }> {
+  constructor(payload: { name: string; email: string }) {
+    super(payload);
+  }
+}
+
+// Komenda ze zlozonym payloadem
+class ProcessOrderCommand extends Command<{
+  orderId: string;
+  items: Array<{ productId: string; quantity: number }>;
+  shippingAddress: {
+    street: string;
+    city: string;
+    postalCode: string;
+  };
+}> {
+  constructor(payload: {
+    orderId: string;
+    items: Array<{ productId: string; quantity: number }>;
+    shippingAddress: { street: string; city: string; postalCode: string };
+  }) {
+    super(payload);
+  }
+}
+
+// Uzycie
+const createUser = new CreateUserCommand({
+  name: 'Jan Kowalski',
+  email: 'jan@example.com'
+});
+
+console.log(createUser.__name);          // 'CreateUserCommand'
+console.log(createUser.__id);            // '550e8400-e29b-41d4-...'
+console.log(createUser.__time);          // 1706347200000
+console.log(createUser.__payload.name);  // 'Jan Kowalski'
+console.log(createUser.__payload.email); // 'jan@example.com'
 ```
 
-**Właściwości automatyczne**:
-- `__id` - unikalny UUID (randomUUID)
-- `__name` - nazwa klasy komendy (constructor.name)
-- `__time` - timestamp utworzenia (Date.now())
+#### Dostep do Danych w Handlerze
+
+```typescript
+commandBus.handle(CreateUserCommand, async (command) => {
+  // Dostep do danych biznesowych przez __payload
+  const { name, email } = command.__payload;
+
+  // Dostep do metadanych komendy
+  console.log(`Processing command ${command.__id} (${command.__name})`);
+  console.log(`Created at: ${new Date(command.__time).toISOString()}`);
+
+  // Logika biznesowa
+  const user = await createUser(name, email);
+  return { userId: user.id };
+});
+```
 
 **Metody statyczne**:
-- `reconstructDates(obj)` - rekonstrukcja obiektów Date z serializowanych danych
+- `reconstructDates(obj)` - rekonstrukcja obiektow Date z serializowanych danych (uzywane wewnetrznie przez JobProcessor)
 
 ### CommandBusConfig
 
@@ -621,19 +729,19 @@ interface CommandBusConfigOptions {
 
 ## Przykłady Użycia
 
-### Podstawowy przykład z RPC
+### Podstawowy przyklad z RPC
 
 ```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();
+// Definicja komendy z payloadem
+class CalculateCommand extends Command<{
+  a: number;
+  b: number;
+  operation: 'add' | 'multiply';
+}> {
+  constructor(payload: { a: number; b: number; operation: 'add' | 'multiply' }) {
+    super(payload);
   }
 }
 
@@ -645,64 +753,69 @@ const commandBus = new CommandBus(config);
 
 // Rejestracja handlera
 commandBus.handle(CalculateCommand, async (command) => {
-  console.log(`Calculating: ${command.a} ${command.operation} ${command.b}`);
+  const { a, b, operation } = command.__payload;
+  console.log(`Calculating: ${a} ${operation} ${b}`);
 
-  switch (command.operation) {
+  switch (operation) {
     case 'add':
-      return command.a + command.b;
+      return a + b;
     case 'multiply':
-      return command.a * command.b;
+      return a * b;
   }
 });
 
 // Fire-and-forget
-await commandBus.dispatch(new CalculateCommand(5, 3, 'add'));
+await commandBus.dispatch(new CalculateCommand({ a: 5, b: 3, operation: 'add' }));
 
 // RPC - czekamy na wynik
 const result = await commandBus.call<number>(
-  new CalculateCommand(5, 3, 'multiply'),
+  new CalculateCommand({ a: 5, b: 3, operation: 'multiply' }),
   5000 // timeout 5s
 );
 console.log(`Result: ${result}`); // Result: 15
 ```
 
-### Równoległe wywołania RPC
+### Rownolegle wywolania RPC
 
 ```typescript
-// Wiele równoległych RPC calls
+// Wiele rownoległ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)),
+  commandBus.call<number>(new CalculateCommand({ a: 10, b: 5, operation: 'add' })),
+  commandBus.call<UserInfo>(new GetUserInfoCommand({ userId: 'user-1' })),
+  commandBus.call<ValidationResult>(new ValidateUserCommand({ email: 'jan@example.com', age: 30 })),
 ]);
 
 console.log('All results:', { result1, result2, result3 });
 ```
 
-### Obsługa błędów
+### Obsluga bledow
 
 ```typescript
 commandBus.handle(CreateUserCommand, async (command) => {
   try {
+    const { email, name } = command.__payload;
+
     // Walidacja
-    if (!command.email.includes('@')) {
+    if (!email.includes('@')) {
       throw new Error('Invalid email format');
     }
 
-    const user = await createUser(command.email, command.name);
+    const user = await createUser(email, name);
     return { userId: user.id };
   } catch (error) {
-    // Loguj błąd
+    // Loguj blad
     console.error('Failed to create user:', error);
 
-    // Rzuć błąd - BullMQ spróbuje ponownie (maxAttempts)
+    // Rzuc blad - BullMQ sprobuje ponownie (maxAttempts)
     throw error;
   }
 });
 
-// Obsługa błędów w RPC
+// Obsluga bledow w RPC
 try {
-  const result = await commandBus.call(new CreateUserCommand('invalid-email', 'Jan'));
+  const result = await commandBus.call(
+    new CreateUserCommand({ email: 'invalid-email', name: 'Jan' })
+  );
 } catch (error) {
   console.error('RPC failed:', error.message);
 }
@@ -809,6 +922,45 @@ const config = new CommandBusConfig({
 - Debugging produkcyjnych problemów
 - Analiza przepływu komend
 
+### 6. RPC Job Cancellation
+
+Automatyczne usuwanie niepodjętych jobów RPC przy timeout:
+
+```
+RPC Timeout Flow:
+
+User Code         RpcCoordinator          Redis           JobProcessor
+    │                   │                   │                   │
+    │── call(cmd) ─────▶│                   │                   │
+    │                   │── registerCall ──▶│                   │
+    │                   │── queue.add ─────▶│                   │
+    │                   │                   │                   │
+    │   [timeout]       │                   │                   │
+    │                   │                   │                   │
+    │                   │── markCancelled ─▶│ SET rpc:cancelled:xxx
+    │                   │── tryRemoveJob ──▶│ (próba usunięcia)
+    │◀── Error ─────────│                   │                   │
+    │                   │                   │                   │
+    │                   │                   │   [job picked up] │
+    │                   │                   │──────────────────▶│
+    │                   │                   │                   │── isCancelled?
+    │                   │                   │◀──────────────────│   → true
+    │                   │                   │                   │── SKIP handler
+    │                   │                   │                   │── clearCancellation
+```
+
+**Kluczowe cechy**:
+- **Dwufazowe anulowanie**: Flaga Redis + próba usunięcia joba z kolejki
+- **Graceful degradation**: Błędy Redis nie blokują przetwarzania
+- **TTL 24h**: Automatyczne wygaśnięcie kluczy cancellation
+- **Aktywne czyszczenie**: Klucze usuwane po przetworzeniu lub usunięciu joba
+- **Kompatybilność wsteczna**: Funkcjonalność jest opcjonalna
+
+**Korzyści**:
+- Oszczędność zasobów - nieprzetworzone joby nie obciążają workerów
+- Brak efektów ubocznych - handler nie wykonuje się dla timeout'owanych RPC
+- Lepsza diagnostyka - logi pokazują pominięte joby
+
 ## Best Practices
 
 ### 1. Używaj TypeScript
@@ -826,18 +978,20 @@ const result = await commandBus.call<UserCreatedResult>(command);
 
 ### 2. Idempotentne handlery
 
-Handlery powinny być idempotentne (wielokrotne wykonanie = ten sam rezultat):
+Handlery powinny byc idempotentne (wielokrotne wykonanie = ten sam rezultat):
 
 ```typescript
 commandBus.handle(CreateUserCommand, async (command) => {
-  // Sprawdź czy użytkownik już istnieje
-  const existing = await findUserByEmail(command.email);
+  const { email, name } = command.__payload;
+
+  // Sprawdz czy uzytkownik juz istnieje
+  const existing = await findUserByEmail(email);
   if (existing) {
-    return { userId: existing.id }; // Zwróć istniejącego
+    return { userId: existing.id }; // Zwroc istniejacego
   }
 
-  // Utwórz nowego
-  const user = await createUser(command.email, command.name);
+  // Utworz nowego
+  const user = await createUser(email, name);
   return { userId: user.id };
 });
 ```
@@ -857,17 +1011,19 @@ const result2 = await commandBus.call(longRunningCommand, 60000); // 60s dla dł
 
 ```typescript
 commandBus.handle(CreateUserCommand, async (command) => {
-  // Walidacja na początku
-  if (!command.email || !command.email.includes('@')) {
+  const { email, name } = command.__payload;
+
+  // Walidacja na poczatku
+  if (!email || !email.includes('@')) {
     throw new Error('Invalid email');
   }
 
-  if (!command.name || command.name.length < 2) {
+  if (!name || name.length < 2) {
     throw new Error('Invalid name');
   }
 
   // Logika biznesowa
-  return await createUser(command.email, command.name);
+  return await createUser(email, name);
 });
 ```
 
@@ -875,14 +1031,16 @@ commandBus.handle(CreateUserCommand, async (command) => {
 
 ```typescript
 commandBus.handle(CreateUserCommand, async (command) => {
+  const { email, name } = command.__payload;
+
   console.log('Processing CreateUserCommand', {
     commandId: command.__id,
     timestamp: command.__time,
-    email: command.email,
+    email: email,
   });
 
   // Logika biznesowa
-  const user = await createUser(command.email, command.name);
+  const user = await createUser(email, name);
 
   console.log('User created successfully', {
     commandId: command.__id,
@@ -900,6 +1058,13 @@ commandBus.handle(CreateUserCommand, async (command) => {
 ```typescript
 import { CommandBus, CommandBusConfig, Command } from 'pp-command-bus';
 
+// Definicja komendy testowej
+class CreateUserCommand extends Command<{ email: string; name: string }> {
+  constructor(payload: { email: string; name: string }) {
+    super(payload);
+  }
+}
+
 describe('User Commands', () => {
   let commandBus: CommandBus;
 
@@ -907,7 +1072,7 @@ describe('User Commands', () => {
     const config = new CommandBusConfig({
       redisUrl: 'redis://localhost:6379',
       logger: console,
-      logLevel: 'error', // Tylko błędy w testach
+      logLevel: 'error', // Tylko bledy w testach
     });
 
     commandBus = new CommandBus(config);
@@ -923,7 +1088,10 @@ describe('User Commands', () => {
   });
 
   it('should create user', async () => {
-    const command = new CreateUserCommand('test@example.com', 'Test User');
+    const command = new CreateUserCommand({
+      email: 'test@example.com',
+      name: 'Test User'
+    });
     const result = await commandBus.call<{ userId: string }>(command, 5000);
 
     expect(result.userId).toBeDefined();
@@ -932,9 +1100,9 @@ describe('User Commands', () => {
 
   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'),
+      new CreateUserCommand({ email: 'user1@example.com', name: 'User 1' }),
+      new CreateUserCommand({ email: 'user2@example.com', name: 'User 2' }),
+      new CreateUserCommand({ email: 'user3@example.com', name: 'User 3' }),
     ];
 
     const results = await Promise.all(
@@ -1037,7 +1205,8 @@ src/
 │   │   └── queue-manager.ts
 │   ├── rpc/                    # RPC coordination
 │   │   ├── rpc-coordinator.ts
-│   │   └── payload-compression.service.ts
+│   │   ├── payload-compression.service.ts
+│   │   └── rpc-job-cancellation.service.ts  # Anulowanie jobów RPC przy timeout
 │   ├── worker/                 # Worker orchestration
 │   │   ├── worker-orchestrator.ts
 │   │   ├── worker-benchmark.ts
@@ -1139,6 +1308,7 @@ Szczegółowa dokumentacja architektury systemu, wzorców projektowych i zasad S
 - **WorkerOrchestrator** - orkiestracja workerów, dynamiczne concurrency, benchmark
 - **JobProcessor** - przetwarzanie jobów i wykonanie handlerów
 - **RpcCoordinator** - zarządzanie wywołaniami RPC przez Redis Pub/Sub
+- **RpcJobCancellationService** - anulowanie niepodjętych jobów RPC przy timeout
 - **JobOptionsBuilder** - konfiguracja opcji dla jobów BullMQ
 - **CommandLogger** - persystencja komend do plików JSONL
 - **PayloadCompressionService** - automatyczna kompresja gzip