@kangwifi-pro/waliwa 1.0.0

package/src/recovery/index.ts

@@ -0,0 +1,704 @@
+/**
+ * Waliwa - Multi-Branch SKDM Recovery System
+ *
+ * Unlike basic reconnect yang cuma coba 1 path, ini implementasi full multi-branch
+ * Session Key & Device Management (SKDM) recovery system.
+ *
+ * Saat disconnect terjadi, sistem mencoba multiple recovery strategies in order:
+ *
+ * ┌──────────────────────────┬───────────────────────────────────────────────────────────────┐
+ * │ Disconnect Reason        │ Recovery Branches (in order)                                    │
+ * ├──────────────────────────┼───────────────────────────────────────────────────────────────┤
+ * │ Connection lost          │ Immediate retry → Stream reconnect → Backoff → Key refresh →   │
+ * │                          │ Pre-key fetch → Full re-auth                                    │
+ * ├──────────────────────────┼───────────────────────────────────────────────────────────────┤
+ * │ Rate limited (429)       │ Wait cooldown (5min) → Backoff retry                            │
+ * ├──────────────────────────┼───────────────────────────────────────────────────────────────┤
+ * │ Restart required (428)   │ Update app version → Key refresh → Full re-auth QR              │
+ * ├──────────────────────────┼───────────────────────────────────────────────────────┤
+ * │ Logged out (401/403)     │ Key refresh → No recovery (fatal)                               │
+ * ├──────────────────────────┼───────────────────────────────────────────────────────────────┤
+ * │ Forbidden (511)          │ Immediate retry → Key refresh → No recovery                      │
+ * ├──────────────────────────┼───────────────────────────────────────────────────────────────┤
+ * │ Multi-device mismatch    │ Key refresh → Full re-auth QR → No recovery                      │
+ * │ (409)                    │                                                                  │
+ * ├──────────────────────────┼───────────────────────────────────────────────────────────────┤
+ * │ Bad session              │ Key refresh → Pre-key fetch → Full re-auth QR                   │
+ * ├──────────────────────────┼───────────────────────────────────────────────────────────────┤
+ * │ Connection replaced (440)│ Key refresh → Full re-auth QR                                   │
+ * └──────────────────────────┴───────────────────────────────────────────────────────────────┘
+ *
+ * Each branch punya retry limit sendiri (default 3).
+ * Total attempts across all branches di-cap (default 20).
+ */
+
+import { EventEmitter } from 'events';
+import type { WALogger } from '../types/index.js';
+import { SilentLogger } from '../utils/logger.js';
+import { sleep } from '../utils/retry.js';
+
+// ============== Disconnect Reasons ==============
+
+export type DisconnectReason =
+  | 'connection_lost'      // 1006, 1001, atau no code
+  | 'rate_limited'          // 429
+  | 'restart_required'     // 428
+  | 'logged_out'           // 401, 403
+  | 'forbidden'            // 511
+  | 'multi_device_mismatch' // 409
+  | 'bad_session'          // generic
+  | 'connection_replaced'  // 440
+  | 'normal'               // 1000 - intentional close, no recovery
+  | 'unknown';
+
+/**
+ * Map WhatsApp disconnect code ke DisconnectReason
+ */
+export function mapCodeToReason(code: number | undefined, reason?: string): DisconnectReason {
+  if (reason === 'normal' || code === 1000) return 'normal';
+  if (code === 429) return 'rate_limited';
+  if (code === 428) return 'restart_required';
+  if (code === 401 || code === 403) return 'logged_out';
+  if (code === 511) return 'forbidden';
+  if (code === 409) return 'multi_device_mismatch';
+  if (code === 440) return 'connection_replaced';
+  if (code === 1006 || code === 1001 || code === undefined || code === 0) return 'connection_lost';
+
+  // Check reason string untuk more context
+  if (reason) {
+    const r = reason.toLowerCase();
+    if (r.includes('logged out') || r.includes('unauthorized')) return 'logged_out';
+    if (r.includes('rate limit') || r.includes('too many')) return 'rate_limited';
+    if (r.includes('restart') || r.includes('update')) return 'restart_required';
+    if (r.includes('forbidden')) return 'forbidden';
+    if (r.includes('multi-device') || r.includes('mismatch')) return 'multi_device_mismatch';
+    if (r.includes('replaced') || r.includes('another device')) return 'connection_replaced';
+    if (r.includes('bad session') || r.includes('invalid session')) return 'bad_session';
+  }
+
+  return 'unknown';
+}
+
+// ============== Recovery Actions ==============
+
+export type RecoveryAction =
+  | 'immediate_retry'
+  | 'stream_reconnect'
+  | 'backoff_retry'
+  | 'wait_cooldown'
+  | 'update_app_version'
+  | 'key_refresh'
+  | 'prekey_fetch'
+  | 'full_reauth_qr'
+  | 'no_recovery';
+
+/**
+ * Recovery context - passed ke setiap action handler
+ */
+export interface RecoveryContext {
+  reason: DisconnectReason;
+  code?: number;
+  errorMessage?: string;
+  attempt: number;
+  totalAttempts: number;
+  branchIndex: number;
+  lastAttemptTime: number;
+  startTime: number;
+  history: Array<{
+    action: RecoveryAction;
+    success: boolean;
+    duration: number;
+    error?: string;
+    timestamp: number;
+  }>;
+}
+
+/**
+ * Recovery branch - ordered list of actions untuk a reason
+ */
+export interface RecoveryBranch {
+  reason: DisconnectReason;
+  actions: RecoveryAction[];
+  maxAttempts?: number;
+  fatal?: boolean;
+}
+
+// ============== Recovery Branch Definitions ==============
+
+export const DEFAULT_RECOVERY_BRANCHES: RecoveryBranch[] = [
+  {
+    reason: 'connection_lost',
+    actions: [
+      'immediate_retry',
+      'stream_reconnect',
+      'backoff_retry',
+      'key_refresh',
+      'prekey_fetch',
+      'full_reauth_qr'
+    ],
+    maxAttempts: 3
+  },
+  {
+    reason: 'rate_limited',
+    actions: [
+      'wait_cooldown',
+      'backoff_retry'
+    ],
+    maxAttempts: 3
+  },
+  {
+    reason: 'restart_required',
+    actions: [
+      'update_app_version',
+      'key_refresh',
+      'full_reauth_qr'
+    ],
+    maxAttempts: 3
+  },
+  {
+    reason: 'logged_out',
+    actions: [
+      'key_refresh'
+    ],
+    maxAttempts: 1,
+    fatal: true
+  },
+  {
+    reason: 'forbidden',
+    actions: [
+      'immediate_retry',
+      'key_refresh'
+    ],
+    maxAttempts: 3
+  },
+  {
+    reason: 'multi_device_mismatch',
+    actions: [
+      'key_refresh',
+      'full_reauth_qr'
+    ],
+    maxAttempts: 3
+  },
+  {
+    reason: 'bad_session',
+    actions: [
+      'key_refresh',
+      'prekey_fetch',
+      'full_reauth_qr'
+    ],
+    maxAttempts: 3
+  },
+  {
+    reason: 'connection_replaced',
+    actions: [
+      'key_refresh',
+      'full_reauth_qr'
+    ],
+    maxAttempts: 3
+  },
+  {
+    reason: 'unknown',
+    actions: [
+      'backoff_retry',
+      'key_refresh',
+      'full_reauth_qr'
+    ],
+    maxAttempts: 3
+  }
+];
+
+// ============== Recovery Config ==============
+
+export interface RecoveryConfig {
+  enabled?: boolean;
+  maxAttemptsPerBranch?: number;
+  maxTotalAttempts?: number;
+  initialDelayMs?: number;
+  maxDelayMs?: number;
+  rateLimitedDelayMs?: number;
+  branches?: RecoveryBranch[];
+  logger?: WALogger;
+  actionHandlers?: Partial<Record<RecoveryAction, (ctx: RecoveryContext) => Promise<boolean>>>;
+}
+
+export const DEFAULT_RECOVERY_CONFIG: Required<Omit<RecoveryConfig, 'logger' | 'branches' | 'actionHandlers'>> = {
+  enabled: true,
+  maxAttemptsPerBranch: 3,
+  maxTotalAttempts: 20,
+  initialDelayMs: 1000,
+  maxDelayMs: 60000,
+  rateLimitedDelayMs: 300000
+};
+
+// ============== Recovery Manager ==============
+
+export class RecoveryManager extends EventEmitter {
+  private config: Required<Omit<RecoveryConfig, 'logger' | 'branches' | 'actionHandlers'>>;
+  private branches: RecoveryBranch[];
+  private logger: WALogger;
+  private actionHandlers: Partial<Record<RecoveryAction, (ctx: RecoveryContext) => Promise<boolean>>>;
+  private defaultHandlers: Record<RecoveryAction, (ctx: RecoveryContext) => Promise<boolean>>;
+
+  private isRecovering: boolean = false;
+  private currentContext: RecoveryContext | null = null;
+  private recoveryStats: {
+    totalRecoveries: number;
+    successfulRecoveries: number;
+    failedRecoveries: number;
+    byReason: Map<DisconnectReason, { success: number; failure: number }>;
+  };
+
+  // Action callbacks - di-set oleh WASocket saat integrate
+  public connect: () => Promise<boolean> = async () => false;
+  public streamReconnect: () => Promise<boolean> = async () => false;
+  public refreshKeys: () => Promise<void> = async () => {};
+  public fetchPreKeys: () => Promise<void> = async () => {};
+  public startFullReauth: () => Promise<void> = async () => {};
+  public updateAppVersion: () => Promise<void> = async () => {};
+
+  constructor(config: RecoveryConfig = {}) {
+    super();
+    this.config = { ...DEFAULT_RECOVERY_CONFIG, ...config } as any;
+    this.branches = config.branches ?? DEFAULT_RECOVERY_BRANCHES;
+    this.logger = config.logger ?? new SilentLogger();
+    this.actionHandlers = config.actionHandlers ?? {};
+
+    this.defaultHandlers = this.createDefaultHandlers();
+    this.recoveryStats = {
+      totalRecoveries: 0,
+      successfulRecoveries: 0,
+      failedRecoveries: 0,
+      byReason: new Map()
+    };
+  }
+
+  // ============== Public API ==============
+
+  async recover(reason: DisconnectReason, code?: number, errorMessage?: string): Promise<boolean> {
+    if (!this.config.enabled || reason === 'normal') {
+      this.logger.debug(`Recovery skipped (enabled=${this.config.enabled}, reason=${reason})`);
+      return false;
+    }
+
+    if (this.isRecovering) {
+      this.logger.warn('Recovery already in progress, ignoring new recovery request');
+      return false;
+    }
+
+    this.isRecovering = true;
+    this.recoveryStats.totalRecoveries++;
+
+    const ctx: RecoveryContext = {
+      reason,
+      code,
+      errorMessage,
+      attempt: 0,
+      totalAttempts: 0,
+      branchIndex: 0,
+      lastAttemptTime: Date.now(),
+      startTime: Date.now(),
+      history: []
+    };
+    this.currentContext = ctx;
+
+    this.emit('recovery:start', { reason, code, message: errorMessage });
+    this.logger.info(`Starting multi-branch recovery for reason: ${reason}${code ? ` (code ${code})` : ''}`);
+
+    const branch = this.branches.find(b => b.reason === reason);
+    if (!branch) {
+      this.logger.error(`No recovery branch found for reason: ${reason}`);
+      await this.failRecovery(ctx, false);
+      return false;
+    }
+
+    if (branch.fatal) {
+      this.logger.error(`Fatal disconnect reason: ${reason} - no recovery possible`);
+      for (const action of branch.actions) {
+        await this.runAction(action, ctx);
+      }
+      await this.failRecovery(ctx, true);
+      return false;
+    }
+
+    const maxPerBranch = branch.maxAttempts ?? this.config.maxAttemptsPerBranch;
+    const branchActions = branch.actions;
+
+    this.emit('recovery:branch:start', {
+      reason,
+      branchIndex: 0,
+      actions: branchActions
+    });
+    this.logger.info(`Recovery branch for ${reason}: ${branchActions.join(' → ')}`);
+
+    for (let actionIdx = 0; actionIdx < branchActions.length; actionIdx++) {
+      const action = branchActions[actionIdx];
+      let branchSuccess = false;
+
+      for (let attempt = 1; attempt <= maxPerBranch; attempt++) {
+        if (ctx.totalAttempts >= this.config.maxTotalAttempts) {
+          this.logger.error(`Total max attempts (${this.config.maxTotalAttempts}) reached`);
+          await this.failRecovery(ctx, false);
+          return false;
+        }
+
+        ctx.attempt = attempt;
+        ctx.totalAttempts++;
+
+        const progress = (ctx.totalAttempts / this.config.maxTotalAttempts) * 100;
+        this.emit('recovery:progress', {
+          currentAction: action,
+          totalAttempts: ctx.totalAttempts,
+          maxTotalAttempts: this.config.maxTotalAttempts,
+          progress
+        });
+
+        const success = await this.runAction(action, ctx);
+
+        if (success) {
+          branchSuccess = true;
+          break;
+        }
+
+        if (attempt < maxPerBranch) {
+          const delay = this.calculateDelay(action, attempt);
+          this.logger.debug(`Waiting ${delay}ms before next attempt`);
+          await sleep(delay);
+        }
+      }
+
+      if (branchSuccess) {
+        await this.succeedRecovery(ctx);
+        return true;
+      }
+
+      if (actionIdx < branchActions.length - 1) {
+        this.logger.info(`Action ${action} exhausted, moving to next action: ${branchActions[actionIdx + 1]}`);
+      }
+    }
+
+    this.emit('recovery:branch:exhausted', {
+      reason,
+      branchIndex: 0,
+      attempts: ctx.totalAttempts
+    });
+    await this.failRecovery(ctx, false);
+    return false;
+  }
+
+  private async runAction(action: RecoveryAction, ctx: RecoveryContext): Promise<boolean> {
+    const startTime = Date.now();
+    this.emit('recovery:action:start', {
+      action,
+      attempt: ctx.attempt,
+      branchIndex: ctx.branchIndex
+    });
+    this.logger.info(`Recovery action: ${action} (attempt ${ctx.attempt})`);
+
+    try {
+      const handler = this.actionHandlers[action] ?? this.defaultHandlers[action];
+      if (!handler) {
+        throw new Error(`No handler for action: ${action}`);
+      }
+
+      const success = await handler(ctx);
+      const duration = Date.now() - startTime;
+
+      ctx.history.push({
+        action,
+        success,
+        duration,
+        timestamp: Date.now()
+      });
+
+      if (success) {
+        this.emit('recovery:action:success', { action, attempt: ctx.attempt, duration });
+        this.logger.info(`Recovery action ${action} succeeded in ${duration}ms`);
+      } else {
+        this.emit('recovery:action:failed', {
+          action,
+          attempt: ctx.attempt,
+          error: 'Action returned false',
+          duration
+        });
+        this.logger.warn(`Recovery action ${action} failed (attempt ${ctx.attempt})`);
+      }
+
+      return success;
+    } catch (err: any) {
+      const duration = Date.now() - startTime;
+      ctx.history.push({
+        action,
+        success: false,
+        duration,
+        error: err.message,
+        timestamp: Date.now()
+      });
+      this.emit('recovery:action:failed', {
+        action,
+        attempt: ctx.attempt,
+        error: err.message,
+        duration
+      });
+      this.logger.error(`Recovery action ${action} threw error: ${err.message}`);
+      return false;
+    }
+  }
+
+  private calculateDelay(action: RecoveryAction, attempt: number): number {
+    switch (action) {
+      case 'wait_cooldown':
+        return this.config.rateLimitedDelayMs;
+      case 'immediate_retry':
+        return 0;
+      case 'stream_reconnect':
+        return Math.min(this.config.initialDelayMs, 500);
+      case 'backoff_retry':
+      case 'key_refresh':
+      case 'prekey_fetch':
+      case 'full_reauth_qr':
+      case 'update_app_version':
+        return Math.min(
+          this.config.initialDelayMs * Math.pow(2, attempt - 1),
+          this.config.maxDelayMs
+        );
+      default:
+        return this.config.initialDelayMs;
+    }
+  }
+
+  // ============== Default Action Handlers ==============
+
+  private createDefaultHandlers(): Record<RecoveryAction, (ctx: RecoveryContext) => Promise<boolean>> {
+    return {
+      immediate_retry: async (ctx) => {
+        this.logger.info('Immediate retry: attempting reconnect...');
+        try {
+          return await this.connect();
+        } catch (err: any) {
+          this.logger.error(`Immediate retry failed: ${err.message}`);
+          return false;
+        }
+      },
+
+      stream_reconnect: async (ctx) => {
+        this.logger.info('Stream reconnect: attempting to resume stream state...');
+        try {
+          return await this.streamReconnect();
+        } catch (err: any) {
+          this.logger.error(`Stream reconnect failed: ${err.message}`);
+          return false;
+        }
+      },
+
+      backoff_retry: async (ctx) => {
+        const delay = Math.min(
+          this.config.initialDelayMs * Math.pow(2, ctx.attempt - 1),
+          this.config.maxDelayMs
+        );
+        this.logger.info(`Backoff retry: waiting ${delay}ms before retry...`);
+        await sleep(delay);
+        try {
+          return await this.connect();
+        } catch (err: any) {
+          this.logger.error(`Backoff retry failed: ${err.message}`);
+          return false;
+        }
+      },
+
+      wait_cooldown: async (ctx) => {
+        this.logger.info(`Rate limited: waiting ${this.config.rateLimitedDelayMs}ms cooldown...`);
+        await sleep(this.config.rateLimitedDelayMs);
+        try {
+          return await this.connect();
+        } catch (err: any) {
+          this.logger.error(`Cooldown retry failed: ${err.message}`);
+          return false;
+        }
+      },
+
+      update_app_version: async (ctx) => {
+        this.logger.info('Updating app version (browser identification)...');
+        try {
+          await this.updateAppVersion();
+          return await this.connect();
+        } catch (err: any) {
+          this.logger.error(`Update app version failed: ${err.message}`);
+          return false;
+        }
+      },
+
+      key_refresh: async (ctx) => {
+        this.logger.info('Refreshing keys (SKDM)...');
+        try {
+          await this.refreshKeys();
+          return await this.connect();
+        } catch (err: any) {
+          this.logger.error(`Key refresh failed: ${err.message}`);
+          return false;
+        }
+      },
+
+      prekey_fetch: async (ctx) => {
+        this.logger.info('Fetching pre-keys...');
+        try {
+          await this.fetchPreKeys();
+          return await this.connect();
+        } catch (err: any) {
+          this.logger.error(`Pre-key fetch failed: ${err.message}`);
+          return false;
+        }
+      },
+
+      full_reauth_qr: async (ctx) => {
+        this.logger.info('Starting full re-authentication (new QR)...');
+        try {
+          await this.startFullReauth();
+          await sleep(5000);
+          return await this.connect();
+        } catch (err: any) {
+          this.logger.error(`Full re-auth failed: ${err.message}`);
+          return false;
+        }
+      },
+
+      no_recovery: async (ctx) => {
+        this.logger.error('No recovery possible for this disconnect reason');
+        return false;
+      }
+    };
+  }
+
+  // ============== Success/Failure Handling ==============
+
+  private async succeedRecovery(ctx: RecoveryContext): Promise<void> {
+    const duration = Date.now() - ctx.startTime;
+    this.isRecovering = false;
+    this.currentContext = null;
+    this.recoveryStats.successfulRecoveries++;
+    this.recordReasonResult(ctx.reason, true);
+
+    this.emit('recovery:success', {
+      reason: ctx.reason,
+      totalAttempts: ctx.totalAttempts,
+      duration
+    });
+    this.logger.info(`Recovery succeeded after ${ctx.totalAttempts} attempts in ${duration}ms`);
+  }
+
+  private async failRecovery(ctx: RecoveryContext, fatal: boolean): Promise<void> {
+    const duration = Date.now() - ctx.startTime;
+    this.isRecovering = false;
+    this.currentContext = null;
+    this.recoveryStats.failedRecoveries++;
+    this.recordReasonResult(ctx.reason, false);
+
+    this.emit('recovery:failed', {
+      reason: ctx.reason,
+      totalAttempts: ctx.totalAttempts,
+      duration,
+      fatal
+    });
+    this.logger.error(`Recovery failed after ${ctx.totalAttempts} attempts in ${duration}ms (fatal: ${fatal})`);
+  }
+
+  private recordReasonResult(reason: DisconnectReason, success: boolean): void {
+    let stats = this.recoveryStats.byReason.get(reason);
+    if (!stats) {
+      stats = { success: 0, failure: 0 };
+      this.recoveryStats.byReason.set(reason, stats);
+    }
+    if (success) stats.success++;
+    else stats.failure++;
+  }
+
+  // ============== Public Helpers ==============
+
+  isCurrentlyRecovering(): boolean {
+    return this.isRecovering;
+  }
+
+  getCurrentContext(): RecoveryContext | null {
+    return this.currentContext;
+  }
+
+  getStats(): {
+    totalRecoveries: number;
+    successfulRecoveries: number;
+    failedRecoveries: number;
+    successRate: number;
+    byReason: Record<string, { success: number; failure: number }>;
+  } {
+    const byReasonObj: Record<string, { success: number; failure: number }> = {};
+    for (const [reason, stats] of this.recoveryStats.byReason.entries()) {
+      byReasonObj[reason] = stats;
+    }
+    return {
+      totalRecoveries: this.recoveryStats.totalRecoveries,
+      successfulRecoveries: this.recoveryStats.successfulRecoveries,
+      failedRecoveries: this.recoveryStats.failedRecoveries,
+      successRate: this.recoveryStats.totalRecoveries === 0
+        ? 0
+        : this.recoveryStats.successfulRecoveries / this.recoveryStats.totalRecoveries,
+      byReason: byReasonObj
+    };
+  }
+
+  getBranchForReason(reason: DisconnectReason): RecoveryBranch | undefined {
+    return this.branches.find(b => b.reason === reason);
+  }
+
+  cancel(): void {
+    if (!this.isRecovering) return;
+    this.logger.warn('Recovery cancelled by user');
+    this.isRecovering = false;
+    this.currentContext = null;
+    this.emit('recovery:failed', {
+      reason: 'unknown',
+      totalAttempts: 0,
+      duration: 0,
+      fatal: false
+    });
+  }
+
+  resetStats(): void {
+    this.recoveryStats = {
+      totalRecoveries: 0,
+      successfulRecoveries: 0,
+      failedRecoveries: 0,
+      byReason: new Map()
+    };
+  }
+}
+
+// ============== Helpers ==============
+
+export function getActionDescription(action: RecoveryAction): string {
+  const descriptions: Record<RecoveryAction, string> = {
+    immediate_retry: 'Coba reconnect langsung tanpa delay',
+    stream_reconnect: 'Resume koneksi dari stream state yang tersimpan',
+    backoff_retry: 'Reconnect dengan exponential backoff',
+    wait_cooldown: 'Tunggu cooldown 5 menit (untuk rate limit)',
+    update_app_version: 'Update identifikasi browser/app version',
+    key_refresh: 'Refresh Signal keys via SKDM',
+    prekey_fetch: 'Fetch pre-keys baru dari server',
+    full_reauth_qr: 'Full re-authentication dengan QR code baru',
+    no_recovery: 'Tidak ada recovery yang possible (fatal)'
+  };
+  return descriptions[action] || action;
+}
+
+export function getReasonDescription(reason: DisconnectReason): string {
+  const descriptions: Record<DisconnectReason, string> = {
+    connection_lost: 'Koneksi terputus tanpa alasan spesifik',
+    rate_limited: 'Rate limited oleh server (HTTP 429)',
+    restart_required: 'Server memerlukan restart/update (HTTP 428)',
+    logged_out: 'Logged out dari WhatsApp (HTTP 401/403) - fatal',
+    forbidden: 'Akses forbidden (HTTP 511)',
+    multi_device_mismatch: 'Multi-device state mismatch (HTTP 409)',
+    bad_session: 'Session tidak valid',
+    connection_replaced: 'Koneksi diganti dengan device lain (HTTP 440)',
+    normal: 'Normal close (intentional)',
+    unknown: 'Unknown disconnect reason'
+  };
+  return descriptions[reason] || reason;
+}