<?php
/**
 * Idempotent SQL chunk replay guard.
 *
 * @package Shiftora\Migration
 */

declare(strict_types=1);

namespace Shiftora\Migration;

use RuntimeException;
use Throwable;

// phpcs:disable WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Exception messages are caught and handled internally, not printed.

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

/**
 * Commit-plus-receipt flow for a single SQL chunk, so INSERTs never run twice.
 *
 * A committed chunk returns its saved receipt. Otherwise the guard takes the
 * exclusive claim: a live claim held elsewhere is waited on for a bounded time
 * then this worker fails; a stale claim (crashed worker) is scrubbed and retaken.
 * Success promotes pending to committed; failure releases the claim and rethrows.
 */
final class SqlChunkReplayGuard {

		/**
		 * A pending claim older than this is presumed abandoned and may be taken over.
		 * Trade-off: a chunk that legitimately runs longer, with a second request live,
		 * can be replayed twice.
		 */
	private const CLAIM_STALE_AFTER_SECONDS = 60;

	public function __construct(
		private readonly ChunkReceiptStore $store,
		private readonly int $contention_attempts = 2,
		private readonly int $contention_wait_usec = 200_000
	) {}

		/**
		 * Run a chunk exactly once and return the applied row count.
		 *
		 * @param string      $chunk_key     Content-addressed chunk identity.
		 * @param string      $table         Bare target table name (for the ledger row).
		 * @param callable    $execute       Executes the chunk and returns inserted rows.
		 * @param string|null $transfer_uuid Receiver-owned transfer identity. Kept out of the content hash so
		 *                                   replays deduplicate within one transfer but never satisfy another's.
		 *
		 * @throws RuntimeException When another worker holds a live claim past the
		 *                          contention budget, or a ledger read fails.
		 */
	public function run( int $migration_id, string $chunk_key, string $table, callable $execute, ?string $transfer_uuid = null ): int {
		$receipt = $this->store->committed_rows( $migration_id, $chunk_key, $transfer_uuid );
		if ( null !== $receipt ) {
			// Replay of an already-committed chunk: serve the saved receipt.
			return $receipt;
		}

		$claimed = false;
		for ( $attempt = 0; $attempt < $this->contention_attempts && ! $claimed; $attempt++ ) {
			$claim_age = $this->store->pending_updated_at( $migration_id, $chunk_key, $transfer_uuid );
			if ( null !== $claim_age && ( time() - $claim_age ) > self::CLAIM_STALE_AFTER_SECONDS ) {
				// The previous holder never finished; scrub its claim so a
				// retry re-runs the chunk exactly once.
				$this->store->clear_pending( $migration_id, $chunk_key, $transfer_uuid );
			}

			if ( $this->store->set_pending( $migration_id, $chunk_key, $table, $transfer_uuid ) ) {
				$claimed = true;
				break;
			}

			// Another worker holds the live claim. Give it a bounded chance to
			// commit, then use its receipt instead of re-running.
			$receipt = $this->store->committed_rows( $migration_id, $chunk_key, $transfer_uuid );
			if ( null !== $receipt ) {
				return $receipt;
			}
			if ( $attempt + 1 < $this->contention_attempts ) {
				usleep( $this->contention_wait_usec );
			}
		}

		if ( ! $claimed ) {
			throw new RuntimeException(
				"Chunk {$chunk_key} is being replayed by another worker; refusing to run it twice."
			);
		}

		try {
			$rows = (int) $execute();
		} catch ( Throwable $e ) {
			// Release the claim so a retry is the only run. A failing cleanup write
			// must not mask the real import error.
			try {
				$this->store->clear_pending( $migration_id, $chunk_key, $transfer_uuid );
			} catch ( Throwable $ignored ) {
				// Intentionally ignored.
			}
			throw $e;
		}

		// Only the claim owner promotes pending to committed. If that write fails,
		// release the claim so a retry re-runs the chunk instead of deadlocking the
		// row. A receipt that landed is untouched, since clear_pending only deletes
		// status = 'pending' rows.
		try {
			$this->store->set_committed( $migration_id, $chunk_key, $rows, $transfer_uuid );
		} catch ( Throwable $e ) {
			try {
				$this->store->clear_pending( $migration_id, $chunk_key, $transfer_uuid );
			} catch ( Throwable $ignored ) {
				// Intentionally ignored.
			}
			throw $e;
		}

		return $rows;
	}

// phpcs:enable WordPress.Security.EscapeOutput.ExceptionNotEscaped
}