<?php
/**
 * @package PlugixaCrm
 */

declare( strict_types = 1 );

namespace PlugixaCrm\Core\Database;

use WP_Error;

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

/**
 * A MySQL named lock around a check-then-write that two overlapping requests would both pass.
 *
 * WHY THIS EXISTS. Several guards in the plugin read a row, decide, then write — "has this lead been
 * converted?", "is this send still a draft?", "has this import batch run?". Each is correct for one
 * request and wrong for two that arrive together: both read the same state, both pass, both write. A
 * double-click is enough. The Linux E2E run of 2026-09-11 turned ten simultaneous `queue` calls into
 * 2,000 queue items for 200 people (one inbox received the newsletter eighteen times) and ten
 * simultaneous conversions into ten companies and ten contacts.
 *
 * WHY A NAMED LOCK AND NOT A TRANSACTION. The tables are InnoDB, but WordPress gives no transaction API,
 * the test suite already wraps every test in one (a nested START TRANSACTION would commit it), and the
 * guarded work calls services that fire hooks other plugins listen to. `GET_LOCK()` serialises exactly the
 * section that needs it, is released when the connection closes even if PHP dies mid-way, and needs no
 * schema. Every MySQL and MariaDB version WordPress supports has it.
 *
 * RE-ENTRANT BY COUNTING HERE, NOT IN THE SERVER. MySQL 5.7+ counts repeated GET_LOCK calls per session;
 * older MariaDB treats a second call as a no-op, so a single RELEASE_LOCK would drop a lock an outer
 * caller still believes it holds. The depth is therefore tracked in PHP and the server is asked once.
 *
 * A server that cannot lock at all (GET_LOCK returns NULL) is treated as "proceed unguarded" rather than
 * as a refusal: a CRM that stops converting leads because a database proxy rejects named locks is worse
 * than the race.
 */
final class Lock {

	/**
	 * Lock name prefix. The rest is an md5, so the name stays inside MySQL's 64-character limit.
	 */
	private const PREFIX = 'pcrm_';

	/**
	 * Names this request holds => nesting depth.
	 *
	 * @var array<string, int>
	 */
	private static array $held = array();

	/**
	 * Run $work while holding the lock for $key.
	 *
	 * @template T
	 *
	 * @param string              $key     What is being guarded, e.g. `lead_convert:12`.
	 * @param callable(): T       $work    The check-then-write.
	 * @param int|null            $timeout Seconds to wait for another request to finish. Null = default.
	 *
	 * @return T|WP_Error The work's result, or `plugixa_crm_busy` (409) when the lock never came free.
	 */
	public static function run( string $key, callable $work, ?int $timeout = null ): mixed {
		if ( ! self::acquire( $key, $timeout ) ) {
			return self::busy();
		}

		try {
			return $work();
		} finally {
			self::release( $key );
		}
	}

	/**
	 * Take the lock and keep it until this request ends.
	 *
	 * For a guard whose write happens later in the request than the check — the edit-conflict check runs
	 * in the permission callback, the save in the controller. The server releases it when the connection
	 * closes; the shutdown hook only makes that explicit for long-lived processes.
	 *
	 * @param string   $key     What is being guarded.
	 * @param int|null $timeout Seconds to wait.
	 */
	public static function hold( string $key, ?int $timeout = null ): bool {
		if ( ! self::acquire( $key, $timeout ) ) {
			return false;
		}

		add_action(
			'shutdown',
			static function () use ( $key ): void {
				self::release( $key );
			}
		);

		return true;
	}

	/**
	 * @param string   $key     What is being guarded.
	 * @param int|null $timeout Seconds to wait.
	 */
	public static function acquire( string $key, ?int $timeout = null ): bool {
		$name = self::name( $key );

		if ( isset( self::$held[ $name ] ) ) {
			++self::$held[ $name ];

			return true;
		}

		global $wpdb;

		/**
		 * How long a request waits for an overlapping one to finish before answering 409.
		 *
		 * @param int    $seconds Default 10.
		 * @param string $key     The guarded key.
		 */
		$timeout = null === $timeout ? (int) apply_filters( 'plugixa_crm_lock_timeout', 10, $key ) : $timeout;

		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- a lock, not data; nothing to cache.
		$result = $wpdb->get_var( $wpdb->prepare( 'SELECT GET_LOCK(%s, %d)', $name, max( 0, $timeout ) ) );

		if ( '0' === (string) $result && null !== $result ) {
			return false;
		}

		self::$held[ $name ] = 1;

		return true;
	}

	/**
	 * @param string $key What was guarded.
	 */
	public static function release( string $key ): void {
		$name = self::name( $key );

		if ( ! isset( self::$held[ $name ] ) ) {
			return;
		}

		if ( --self::$held[ $name ] > 0 ) {
			return;
		}

		unset( self::$held[ $name ] );

		global $wpdb;

		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- a lock, not data; nothing to cache.
		$wpdb->query( $wpdb->prepare( 'DO RELEASE_LOCK(%s)', $name ) );
	}

	/**
	 * The server-side name for a key: per site, so two sites sharing a database never block each other.
	 *
	 * @param string $key What is being guarded.
	 */
	public static function name( string $key ): string {
		global $wpdb;

		return self::PREFIX . md5( $wpdb->prefix . $key );
	}

	/**
	 * The error a request gets when an overlapping one held the lock for the whole timeout.
	 */
	public static function busy(): WP_Error {
		return new WP_Error(
			'plugixa_crm_busy',
			__( 'Someone else is changing this right now. Try again in a moment.', 'plugixa-crm' ),
			array( 'status' => 409 )
		);
	}
}