<?php
/**
 * Cross-request lock.
 *
 * @package FormPilot
 * @since   1.0.0
 */

declare( strict_types = 1 );

namespace FormPilot\Database;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * A lock held in a row of the options table.
 *
 * `add_option()` looks like a lock and is not one. It first asks `get_option()`,
 * whose answer can come from this request's cache, and then writes with
 * `INSERT … ON DUPLICATE KEY UPDATE` - so two requests racing both "succeed", and
 * a request that once saw the lock keeps seeing it after it is gone. Here the
 * database decides: `INSERT IGNORE` creates the row for exactly one caller.
 *
 * The row holds the time it was taken and a random token. The token is what
 * releases it, so a holder that outlived its lifetime cannot free the lock
 * somebody else has since taken over.
 *
 * @since 1.0.0
 */
final class Lock {

	/**
	 * Takes the lock, or reports that somebody else holds it.
	 *
	 * @param string $name     Option name of the lock.
	 * @param int    $lifetime Seconds after which a held lock counts as abandoned.
	 *
	 * @return string The token that releases the lock, or an empty string when it is held.
	 */
	public static function acquire( string $name, int $lifetime ): string {
		global $wpdb;

		$now   = time();
		$token = $now . ':' . wp_generate_password( 12, false );

		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- An atomic insert is the lock; a cached answer would defeat it.
		$inserted = $wpdb->query(
			$wpdb->prepare(
				"INSERT IGNORE INTO {$wpdb->options} (option_name, option_value, autoload) VALUES (%s, %s, 'off')",
				$name,
				$token
			)
		);

		if ( 1 === (int) $inserted ) {
			self::forget( $name );

			return $token;
		}

		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Reading the live lock row, not a cacheable value.
		$held = $wpdb->get_var( $wpdb->prepare( "SELECT option_value FROM {$wpdb->options} WHERE option_name = %s", $name ) );

		if ( ! is_string( $held ) || (int) $held >= $now - $lifetime ) {
			return '';
		}

		// Abandoned. Taken over only if nobody else took it over first.
		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Compare-and-swap on the lock row.
		$taken = $wpdb->query(
			$wpdb->prepare(
				"UPDATE {$wpdb->options} SET option_value = %s WHERE option_name = %s AND option_value = %s",
				$token,
				$name,
				$held
			)
		);

		self::forget( $name );

		return 1 === (int) $taken ? $token : '';
	}

	/**
	 * Releases a lock this caller holds.
	 *
	 * @param string $name  Option name of the lock.
	 * @param string $token Token returned by {@see self::acquire()}.
	 */
	public static function release( string $name, string $token ): void {
		global $wpdb;

		if ( '' === $token ) {
			return;
		}

		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Only the holder's own row is removed.
		$wpdb->query( $wpdb->prepare( "DELETE FROM {$wpdb->options} WHERE option_name = %s AND option_value = %s", $name, $token ) );

		self::forget( $name );
	}

	/**
	 * Drops what the options cache believes about the lock row.
	 *
	 * @param string $name Option name of the lock.
	 */
	private static function forget( string $name ): void {
		wp_cache_delete( $name, 'options' );
		wp_cache_delete( 'notoptions', 'options' );
	}
}