/app/chrome-extension/entrypoints/offscreen/rr-keepalive.ts

/**
 * @fileoverview Offscreen Keepalive
 * @description Keeps the MV3 service worker alive using an Offscreen Document + Port heartbeat.
 *
 * Architecture:
 * - Offscreen connects to Background (Service Worker) via a named Port.
 * - Offscreen sends periodic `keepalive.ping` messages while keepalive is enabled.
 * - Background replies with `keepalive.pong` to confirm the channel is alive.
 *
 * Contract:
 * - After `stop`, keepalive must fully stop: no ping loop, no Port, and no reconnection attempts.
 * - After `start`, keepalive must (re)connect if needed and resume the ping loop.
 */

import {
  RR_V3_KEEPALIVE_PORT_NAME,
  DEFAULT_KEEPALIVE_PING_INTERVAL_MS,
  type KeepaliveMessage,
} from '@/common/rr-v3-keepalive-protocol';

// ==================== Runtime Control Protocol ====================

const KEEPALIVE_CONTROL_MESSAGE_TYPE = 'rr_v3_keepalive.control' as const;

type KeepaliveControlCommand = 'start' | 'stop';

interface KeepaliveControlMessage {
  type: typeof KEEPALIVE_CONTROL_MESSAGE_TYPE;
  command: KeepaliveControlCommand;
}

function isKeepaliveControlMessage(value: unknown): value is KeepaliveControlMessage {
  if (!value || typeof value !== 'object') return false;
  const v = value as Record<string, unknown>;
  if (v.type !== KEEPALIVE_CONTROL_MESSAGE_TYPE) return false;
  return v.command === 'start' || v.command === 'stop';
}

// ==================== State ====================

let initialized = false;
let keepalivePort: chrome.runtime.Port | null = null;
let pingTimer: ReturnType<typeof setInterval> | null = null;
/** Whether keepalive is desired (set by start/stop commands from Background) */
let keepaliveDesired = false;
let reconnectTimer: ReturnType<typeof setTimeout> | null = null;

// ==================== Type Guards ====================

/**
 * Type guard for KeepaliveMessage.
 */
function isKeepaliveMessage(value: unknown): value is KeepaliveMessage {
  if (!value || typeof value !== 'object') return false;
  const v = value as Record<string, unknown>;

  const type = v.type;
  if (
    type !== 'keepalive.ping' &&
    type !== 'keepalive.pong' &&
    type !== 'keepalive.start' &&
    type !== 'keepalive.stop'
  ) {
    return false;
  }

  return typeof v.timestamp === 'number' && Number.isFinite(v.timestamp);
}

// ==================== Port Management ====================

/**
 * Schedule a reconnect attempt to maintain the Port connection.
 * Only reconnect while keepalive is desired.
 */
function scheduleReconnect(delayMs = 1000): void {
  if (!initialized) return;
  if (!keepaliveDesired) return;
  if (reconnectTimer) return;

  reconnectTimer = setTimeout(() => {
    reconnectTimer = null;
    if (!initialized) return;
    if (!keepaliveDesired) return;
    if (!keepalivePort) {
      console.log('[rr-keepalive] Attempting scheduled reconnect...');
      keepalivePort = connectToBackground();
    }
  }, delayMs);
}

/**
 * Create a Port connection to Background.
 */
function connectToBackground(): chrome.runtime.Port | null {
  if (typeof chrome === 'undefined' || !chrome.runtime?.connect) {
    console.warn('[rr-keepalive] chrome.runtime.connect not available');
    return null;
  }

  try {
    const port = chrome.runtime.connect({ name: RR_V3_KEEPALIVE_PORT_NAME });

    port.onMessage.addListener((msg: unknown) => {
      if (!isKeepaliveMessage(msg)) return;

      if (msg.type === 'keepalive.start') {
        console.log('[rr-keepalive] Received start command via Port');
        startPingLoop();
      } else if (msg.type === 'keepalive.stop') {
        console.log('[rr-keepalive] Received stop command via Port');
        stopPingLoop();
      } else if (msg.type === 'keepalive.pong') {
        // Background replied to our ping.
        console.debug('[rr-keepalive] Received pong');
      }
    });

    port.onDisconnect.addListener(() => {
      console.log('[rr-keepalive] Port disconnected');
      keepalivePort = null;
      // Only reconnect if keepalive is still desired.
      scheduleReconnect(1000);
    });

    console.log('[rr-keepalive] Connected to background');
    return port;
  } catch (e) {
    console.warn('[rr-keepalive] Failed to connect:', e);
    return null;
  }
}

// ==================== Ping Loop ====================

/**
 * Send a ping message to Background.
 */
function sendPing(): void {
  if (!keepalivePort) {
    keepalivePort = connectToBackground();
  }

  if (!keepalivePort) return;

  const msg: KeepaliveMessage = {
    type: 'keepalive.ping',
    timestamp: Date.now(),
  };

  try {
    keepalivePort.postMessage(msg);
    console.debug('[rr-keepalive] Sent ping');
  } catch (e) {
    console.warn('[rr-keepalive] Failed to send ping:', e);
    keepalivePort = null;
    scheduleReconnect(1000);
  }
}

/**
 * Start the ping loop.
 */
function startPingLoop(): void {
  if (pingTimer) return;

  keepaliveDesired = true;

  // Ensure we have a Port connection.
  if (!keepalivePort) {
    keepalivePort = connectToBackground();
  }

  // Send one ping immediately.
  sendPing();

  // Start the interval timer.
  pingTimer = setInterval(() => {
    sendPing();
  }, DEFAULT_KEEPALIVE_PING_INTERVAL_MS);

  console.log(
    `[rr-keepalive] Ping loop started (interval=${DEFAULT_KEEPALIVE_PING_INTERVAL_MS}ms)`,
  );
}

/**
 * Stop the ping loop.
 * This must fully stop keepalive: no timer, no Port, and no reconnection attempts.
 */
function stopPingLoop(): void {
  keepaliveDesired = false;

  if (pingTimer) {
    clearInterval(pingTimer);
    pingTimer = null;
  }

  if (reconnectTimer) {
    clearTimeout(reconnectTimer);
    reconnectTimer = null;
  }

  // Disconnect the Port to fully stop keepalive.
  if (keepalivePort) {
    try {
      keepalivePort.disconnect();
    } catch {
      // Ignore
    }
    keepalivePort = null;
  }

  console.log('[rr-keepalive] Ping loop stopped');
}

// ==================== Public API ====================

/**
 * Initialize keepalive control handlers.
 * @description Registers the runtime control listener and waits for start/stop commands.
 */
export function initKeepalive(): void {
  if (initialized) return;
  initialized = true;

  // Check Chrome API availability.
  if (typeof chrome === 'undefined' || !chrome.runtime?.onMessage) {
    console.warn('[rr-keepalive] chrome.runtime.onMessage not available');
    return;
  }

  // Listen for runtime control messages from Background.
  // This allows Background to send start/stop even when Port is not connected.
  chrome.runtime.onMessage.addListener((msg: unknown, _sender, sendResponse) => {
    if (!isKeepaliveControlMessage(msg)) return;

    if (msg.command === 'start') {
      console.log('[rr-keepalive] Received runtime start command');
      startPingLoop();
    } else {
      console.log('[rr-keepalive] Received runtime stop command');
      stopPingLoop();
    }

    try {
      sendResponse({ ok: true });
    } catch {
      // Ignore
    }
  });

  // Also establish initial Port connection for backwards compatibility.
  if (chrome.runtime?.connect) {
    keepalivePort = connectToBackground();
  }

  console.log('[rr-keepalive] Keepalive initialized');
}

/**
 * Check whether keepalive is active.
 */
export function isKeepaliveActive(): boolean {
  return keepaliveDesired && pingTimer !== null && keepalivePort !== null;
}

/**
 * Get the active port count (for debugging).
 * @deprecated Use isKeepaliveActive() instead
 */
export function getActivePortCount(): number {
  return keepalivePort ? 1 : 0;
}

// Re-export for backwards compatibility
export {
  RR_V3_KEEPALIVE_PORT_NAME,
  type KeepaliveMessage,
} from '@/common/rr-v3-keepalive-protocol';