<?php
/**
 * Lock — a tiny cross-request mutex for long-running jobs.
 *
 * Backs onto the options table: acquire() uses add_option() (a single INSERT with a
 * UNIQUE option_name key) so two concurrent requests can never both win the row.
 * A held lock carries an expiry so a crashed/abandoned job can never wedge future
 * work — touch() extends it while a job makes progress, and a lapsed lock is stolen
 * on the next acquire().
 *
 * @package AI_SiteArk
 * Copyright (c) 2026 AtoZ INFOWAY INC.
 * Licensed under the GNU General Public License, version 2 or later.
 */

namespace AtoZ\SiteArk\Helpers;

defined( 'ABSPATH' ) || exit;

/**
 * Class Lock
 */
class Lock {

	const PREFIX = 'aisiteark_lock_';

	/**
	 * Option name for a lock.
	 *
	 * @param string $name Lock name.
	 * @return string
	 */
	private static function key( $name ) {
		return self::PREFIX . preg_replace( '/[^a-z0-9_]/', '', (string) $name );
	}

	/**
	 * Try to acquire a lock. Returns true if this caller now holds it.
	 *
	 * @param string $name  Lock name.
	 * @param int    $ttl   Seconds before the lock is considered stale.
	 * @param string $owner Optional owner tag (e.g. a job id) for holder().
	 * @return bool
	 */
	public static function acquire( $name, $ttl = 900, $owner = '' ) {
		$key = self::key( $name );
		$now = time();
		$rec = wp_json_encode( array( 'owner' => (string) $owner, 'at' => $now, 'exp' => $now + max( 60, (int) $ttl ) ) );

		// Atomic insert: fails (returns false) if the row already exists.
		if ( add_option( $key, $rec, '', 'no' ) ) {
			return true;
		}

		// Row exists — steal it only if the previous holder let it lapse.
		$cur = json_decode( (string) get_option( $key, '' ), true );
		if ( ! is_array( $cur ) || empty( $cur['exp'] ) || (int) $cur['exp'] < $now ) {
			update_option( $key, $rec, false );
			return true;
		}
		return false;
	}

	/**
	 * Extend a held lock's expiry (call as a job makes progress).
	 *
	 * @param string $name Lock name.
	 * @param int    $ttl  Seconds to extend from now.
	 * @return void
	 */
	public static function touch( $name, $ttl = 900 ) {
		$key = self::key( $name );
		$cur = json_decode( (string) get_option( $key, '' ), true );
		if ( ! is_array( $cur ) ) {
			return; // Not held — don't resurrect a released lock.
		}
		$cur['exp'] = time() + max( 60, (int) $ttl );
		update_option( $key, wp_json_encode( $cur ), false );
	}

	/**
	 * Release a lock.
	 *
	 * @param string $name Lock name.
	 * @return void
	 */
	public static function release( $name ) {
		delete_option( self::key( $name ) );
	}

	/**
	 * Whether a lock is currently held (and not lapsed).
	 *
	 * @param string $name Lock name.
	 * @return bool
	 */
	public static function is_held( $name ) {
		$cur = json_decode( (string) get_option( self::key( $name ), '' ), true );
		return is_array( $cur ) && ! empty( $cur['exp'] ) && (int) $cur['exp'] >= time();
	}

	/**
	 * The current holder record, or null.
	 *
	 * @param string $name Lock name.
	 * @return array|null
	 */
	public static function holder( $name ) {
		$cur = json_decode( (string) get_option( self::key( $name ), '' ), true );
		return is_array( $cur ) ? $cur : null;
	}
}