<?php
/**
 * Named MySQL advisory lock hosting the transfer's critical sections.
 *
 * @package Shiftora\Migration
 */

declare(strict_types=1);

namespace Shiftora\Migration;

use RuntimeException;

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

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

/**
 * GET_LOCK/RELEASE_LOCK mutex for a transfer's destructive phases.
 *
 * Worker lock rows only arbitrate between copies of this plugin; a named MySQL lock
 * is enforced by the server. The name includes this database's identity so two
 * sites on one MySQL host do not serialize on each other's "finalize" locks.
 */
final class TransferOperationLock {

		/**
		 * How long a guarded endpoint waits for a contended destination before answering
		 * 409. These are short HTTP calls, so a short hard wait beats a retry storm.
		 */
	public const DEFAULT_ACQUIRE_TIMEOUT = 2;

	public function __construct(
		private readonly \wpdb $wpdb
	) {}

	/**
	 * The lock name the server sees. Public so a caller can embed the exact
	 * claimed scope in later guarded writes.
	 */
	public function lock_name( string $scope ): string {
		$identity = md5( sprintf( '%s|%s', $this->wpdb->dbhost, $this->wpdb->dbname ) );
		return 'shiftora:' . $identity . ':' . $scope;
	}

	/**
	 * Claim the advisory lock for a scope. Waits up to $timeout seconds; a
	 * false return means the lock is held elsewhere, not that anything broke.
	 */
	public function acquire( string $scope, int $timeout = 0 ): bool {
		$wpdb = $this->wpdb;

		$name = $this->lock_name( $scope );
		// phpcs:ignore WordPress.DB.DirectDatabaseQuery -- a named lock, not cacheable
		$got  = $wpdb->get_var(
			$wpdb->prepare( 'SELECT GET_LOCK(%s, %d)', $name, $timeout ),
			0,
			0
		);

		if ( null === $got ) {
			throw new RuntimeException(
				sprintf( 'GET_LOCK(%s) failed: %s', $name, $wpdb->last_error ?: 'unknown error' )
			);
		}

		return 1 === (int) $got;
	}

	/**
	 * Hand the lock back. False means this session did not own it, which is
	 * itself a signal to callers that the claim was lost mid-flight.
	 */
	public function release( string $scope ): bool {
		$wpdb = $this->wpdb;

		$name = $this->lock_name( $scope );
		// query() returns the row count (1) for any SELECT, so the release
		// outcome has to come from get_var, which gives RELEASE_LOCK's 1/0.
		// phpcs:ignore WordPress.DB.DirectDatabaseQuery -- a named lock, not cacheable
		$released = $wpdb->get_var(
			$wpdb->prepare( 'SELECT RELEASE_LOCK(%s)', $name ),
			0,
			0
		);

		if ( null === $released ) {
			throw new RuntimeException(
				sprintf( 'RELEASE_LOCK(%s) failed: %s', $name, $wpdb->last_error ?: 'unknown error' )
			);
		}

		return 1 === (int) $released;
	}

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