<?php
/**
 * Ownership lease for the indexing job.
 *
 * @package Postlinkly
 * @since   1.14.0
 */

declare(strict_types=1);

namespace Postlinkly\Indexing;

/**
 * Grants one runner at a time the right to advance the job.
 *
 * A lock would have to be released by whoever took it, and the failures that
 * matter here — a fatal error, an out-of-memory kill, the host cutting the
 * request — never reach any cleanup code. A lease expires on its own instead,
 * so recovery never depends on the dying process doing anything: the next
 * runner takes over from the last committed cursor.
 *
 * @since 1.14.0
 */
final class JobLease {

	/**
	 * Shortest lease granted, in seconds.
	 *
	 * A lease is normally twice the batch budget, but a very small budget
	 * would produce one that expires while its own batch is still legitimately
	 * working — letting a second runner start on top of the first.
	 */
	public const FLOOR_SECONDS = 120;

	/**
	 * @var JobStateRepository
	 */
	private JobStateRepository $repository;

	/**
	 * Returns the current unix time.
	 *
	 * @var callable(): int
	 */
	private $clock;

	/**
	 * @since 1.14.0
	 *
	 * @param JobStateRepository $repository Job storage.
	 * @param callable|null      $clock      Optional. Returns the current unix time.
	 */
	public function __construct( JobStateRepository $repository, ?callable $clock = null ) {
		$this->repository = $repository;
		$this->clock      = $clock ?? static fn(): int => time();
	}

	/**
	 * Claims the job, or returns null when a live lease holds it.
	 *
	 * @since 1.14.0
	 *
	 * @param JobState $state          Current state.
	 * @param string   $owner          Claiming runner's token.
	 * @param int      $budget_seconds This batch's time budget.
	 *
	 * @return JobState|null Saved state with the lease applied, or null.
	 */
	public function claim( JobState $state, string $owner, int $budget_seconds ): ?JobState {
		$now = ( $this->clock )();

		$held_by_other = '' !== $state->lease_owner()
			&& $state->lease_owner() !== $owner
			&& $state->lease_expires() > $now;

		if ( $held_by_other ) {
			return null;
		}

		$claimed = $state->with_lease( $owner, $now + max( self::FLOOR_SECONDS, $budget_seconds * 2 ) );
		$this->repository->save( $claimed );

		return $claimed;
	}

	/**
	 * Gives up the lease.
	 *
	 * @since 1.14.0
	 *
	 * @param JobState $state State holding the lease.
	 */
	public function release( JobState $state ): JobState {
		return $state->without_lease();
	}

	/**
	 * Whether the job claims to be running but nothing is actually holding it.
	 *
	 * @since 1.14.0
	 *
	 * @param JobState $state State to inspect.
	 */
	public function is_stale( JobState $state ): bool {
		return 'running' === $state->status() && $state->lease_expires() <= ( $this->clock )();
	}
}