<?php
/**
 * A mutex so two requests cannot step the same job at once.
 *
 * @package Transtrix
 */

namespace Transtrix\Runner;

defined( 'ABSPATH' ) || exit;

/**
 * Built on add_option(), not wp_cache_add().
 *
 * The options table has a unique index on option_name, so add_option() either
 * inserts or returns false — a real compare-and-set. wp_cache_add() is not
 * atomic under the default non-persistent array cache, which is precisely the
 * configuration most sites run.
 *
 * The stored value is a timestamp so a lock orphaned by a fatal can be stolen
 * rather than wedging the job forever.
 */
class Step_Lock {

	/**
	 * Option name prefix.
	 */
	const PREFIX = 'transtrix_step_lock_';

	/**
	 * Seconds after which an unreleased lock is assumed dead.
	 *
	 * Budget caps a step's run time below this, so a slow step is never
	 * mistaken for a dead one and run a second time alongside itself.
	 */
	const TTL = 300;

	/**
	 * Take the lock, stealing it if the holder is long gone.
	 *
	 * @param string $job_id Job id.
	 * @param int    $ttl    Seconds before a held lock is considered stale.
	 * @return bool
	 */
	public static function acquire( string $job_id, int $ttl = self::TTL ): bool {
		$option = self::option( $job_id );

		if ( add_option( $option, (string) time(), '', false ) ) {
			self::release_on_shutdown( $job_id );

			return true;
		}

		$held = (int) get_option( $option );

		if ( $held > 0 && ( time() - $held ) < $ttl ) {
			return false;
		}

		update_option( $option, (string) time(), false );
		self::release_on_shutdown( $job_id );

		return true;
	}

	/**
	 * Give the lock back.
	 *
	 * @param string $job_id Job id.
	 * @return void
	 */
	public static function release( string $job_id ): void {
		delete_option( self::option( $job_id ) );
	}

	/**
	 * Release the lock even if this request dies mid-step.
	 *
	 * @param string $job_id Job id.
	 * @return void
	 */
	private static function release_on_shutdown( string $job_id ): void {
		register_shutdown_function(
			static function () use ( $job_id ) {
				self::release( $job_id );
			}
		);
	}

	/**
	 * Option name for a job.
	 *
	 * @param string $job_id Job id.
	 * @return string
	 */
	private static function option( string $job_id ): string {
		return self::PREFIX . preg_replace( '/[^A-Za-z0-9_.]/', '', $job_id );
	}
}