<?php
/**
 * Detects and auto-resumes stalled migrations.
 *
 * A migration is stalled when its status is 'running' but last_heartbeat_at is
 * older than the stall threshold (default 2 min). Its next chunk is re-scheduled
 * and a warning is logged. A 'cancelling' migration whose worker is gone is
 * handed to the caller to finish, since only a worker resolves that state.
 *
 * @package Shiftora\Migration
 */

declare(strict_types=1);

namespace Shiftora\Migration;

use Shiftora\Logging\MigrationLogger;

// Prevent direct file access.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Re-schedules stalled running migrations. Runs from WP-Cron via
 * 'shiftora_recover_stalled', scheduled every 2 minutes by schedule_cron().
 */
final class StallRecovery {

	/** WP cron hook name. */
	public const CRON_HOOK = 'shiftora_recover_stalled';

	/** WP cron interval name (2 minutes). */
	public const CRON_INTERVAL = 'shiftora_two_minutes';

	/** Default stall threshold in seconds (2 minutes). */
	private const DEFAULT_THRESHOLD = 120;

		/**
		 * Scan for stalled migrations and re-schedule each one, then finish any cancel
		 * that no worker is left to complete.
		 *
		 * @param callable(int): void|null $finish_cancel Settles a stuck cancelling migration.
		 */
	public static function run( \wpdb $wpdb, ?callable $finish_cancel = null ): void {
		$threshold = (int) apply_filters( 'shiftora_stall_threshold_seconds', self::DEFAULT_THRESHOLD );
		if ( $threshold < 30 ) {
			// Never treat a migration as stalled after fewer than 30 s.
			$threshold = 30;
		}

		// UTC_TIMESTAMP, not NOW(): heartbeats are written in UTC, and a MySQL
		// server on local time would read them as hours old and flag healthy
		// transfers as stalled.
		// phpcs:ignore WordPress.DB.DirectDatabaseQuery -- custom table, fresh read required
		$rows = $wpdb->get_results(
			$wpdb->prepare(
				"SELECT id, file_offsets_json FROM %i
				  WHERE status            = 'running'
				    AND last_heartbeat_at IS NOT NULL
				    AND last_heartbeat_at < DATE_SUB( UTC_TIMESTAMP(), INTERVAL %d SECOND )",
				$wpdb->prefix . 'shiftora_migrations',
				$threshold
			)
		);

		foreach ( (array) $rows as $row ) {
			$migration_id  = (int) $row->id;
			$in_file_stage = isset( $row->file_offsets_json ) && null !== $row->file_offsets_json;

			// Pick the hook that matches the current stage.
			$scheduled = false;
			if ( $in_file_stage ) {
				$scheduled = MigrationJob::schedule_file( $migration_id );
			} else {
				$scheduled = MigrationJob::schedule( $migration_id );
			}

			if ( ! $scheduled ) {
				( new MigrationLogger( $migration_id ) )->error(
					'Stall recovery: failed to re-schedule migration. Scheduler unavailable.',
					[ 'migration_id' => $migration_id ]
				);
				continue;
			}

			( new MigrationLogger( $migration_id ) )->warning(
				"Stalled migration detected and re-scheduled (no heartbeat for {$threshold}s).",
				[ 'migration_id' => $migration_id ]
			);
		}

		if ( null !== $finish_cancel ) {
			self::finish_stuck_cancels( $wpdb, $finish_cancel, $threshold );
		}
	}

	/**
	 * Whether a cancelling migration has no worker left. Cancel parks the row until a
	 * worker or a retry settles it; if the worker died, nothing else ever will.
	 * Judged on the row alone: a held lock or a recent heartbeat means someone is on it.
	 */
	public static function is_cancel_orphaned( object $row, int $now, int $threshold ): bool {
		$lock = isset( $row->worker_lock_expires ) ? strtotime( (string) $row->worker_lock_expires . ' UTC' ) : false;
		if ( false !== $lock && $lock > $now ) {
			return false;
		}

		// A migration cancelled before its first heartbeat has none; its last update is the next best clock.
		$seen = $row->last_heartbeat_at ?? $row->updated_at ?? null;
		$last = null !== $seen ? strtotime( (string) $seen . ' UTC' ) : false;

		return false === $last || ( $now - $last ) >= $threshold;
	}

	private static function finish_stuck_cancels( \wpdb $wpdb, callable $finish_cancel, int $threshold ): void {
		// phpcs:ignore WordPress.DB.DirectDatabaseQuery -- custom table, fresh read required
		$rows = (array) $wpdb->get_results(
			$wpdb->prepare(
				"SELECT id, last_heartbeat_at, updated_at, worker_lock_expires FROM %i
				  WHERE status = 'cancelling'",
				$wpdb->prefix . 'shiftora_migrations'
			)
		);

		foreach ( $rows as $row ) {
			if ( ! self::is_cancel_orphaned( $row, time(), $threshold ) ) {
				continue;
			}

			$migration_id = (int) $row->id;
			( new MigrationLogger( $migration_id ) )->warning(
				"Cancelling migration has no worker (no heartbeat for {$threshold}s); finishing the cancel.",
				[ 'migration_id' => $migration_id ]
			);
			$finish_cancel( $migration_id );
		}
	}

		/**
		 * Register the 2-minute WP-Cron schedule if not already registered. Call on
		 * 'admin_init' and after activation.
		 */
	public static function schedule_cron(): void {
		if ( ! wp_next_scheduled( self::CRON_HOOK ) ) {
			wp_schedule_event( time(), self::CRON_INTERVAL, self::CRON_HOOK );
		}
	}

		/**
		 * Remove the WP-Cron event. Call on deactivation.
		 */
	public static function unschedule_cron(): void {
		wp_clear_scheduled_hook( self::CRON_HOOK );
	}
}