<?php

namespace Yoast\WP\SEO\Helpers;

use Yoast\WP\SEO\Exceptions\Locking\Lock_Timeout_Exception;
use Yoast\WP\SEO\Expiring_Store\Application\Expiring_Store;

/**
 * Distributed exclusive lock backed by the expiring store.
 *
 * Acquires a network-scoped lock in the expiring store table, executes the
 * callback, and releases the lock in a finally block.
 *
 * The lock has a TTL so that it self-expires if the owning process crashes without
 * releasing it. Other processes retry with a configurable delay between attempts.
 */
class Lock_Helper {

	/**
	 * The expiring store.
	 *
	 * @var Expiring_Store
	 */
	private $store;

	/**
	 * The constructor.
	 *
	 * @param Expiring_Store $store The expiring store.
	 */
	public function __construct( Expiring_Store $store ) {
		$this->store = $store;
	}

	/**
	 * Acquires a lock, executes the callback, and releases the lock.
	 *
	 * @template T
	 *
	 * @param string        $lock_key                 The lock key.
	 * @param callable(): T $callback                 The callback to execute while holding the lock.
	 * @param int           $ttl_in_seconds           The lock TTL in seconds. Defaults to 30.
	 * @param int           $max_attempts             The maximum number of acquisition attempts. Defaults to 5.
	 * @param int           $retry_delay_microseconds The delay between attempts in microseconds. Defaults to 20000 (20ms).
	 *
	 * @return T The callback's return value.
	 * @throws Lock_Timeout_Exception When the lock cannot be acquired within the allowed attempts.
	 */
	public function execute( string $lock_key, callable $callback, int $ttl_in_seconds = 30, int $max_attempts = 5, int $retry_delay_microseconds = 20_000 ) {
		$this->acquire( $lock_key, $ttl_in_seconds, $max_attempts, $retry_delay_microseconds );

		try {
			return $callback();
		}
		finally {
			$this->store->delete_for_multisite( $lock_key );
		}
	}

	/**
	 * Attempts to acquire the lock with retries.
	 *
	 * @param string $lock_key                 The lock key.
	 * @param int    $ttl_in_seconds           The lock TTL in seconds.
	 * @param int    $max_attempts             The maximum number of attempts.
	 * @param int    $retry_delay_microseconds The delay between attempts in microseconds.
	 *
	 * @return void
	 * @throws Lock_Timeout_Exception When all attempts are exhausted.
	 */
	private function acquire( string $lock_key, int $ttl_in_seconds, int $max_attempts, int $retry_delay_microseconds ): void {
		for ( $attempt = 1; $attempt <= $max_attempts; $attempt++ ) {
			if ( $this->store->persist_if_absent_for_multisite( $lock_key, true, $ttl_in_seconds ) ) {
				return;
			}

			if ( $attempt < $max_attempts ) {
				\usleep( $retry_delay_microseconds );
			}
		}

		// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- This is an exception message, not output.
		throw new Lock_Timeout_Exception( $lock_key, $max_attempts );
	}
}