<?php
/**
 * Time budget for one indexing batch.
 *
 * @package Postlinkly
 * @since   1.14.0
 */

declare(strict_types=1);

namespace Postlinkly\Indexing;

/**
 * Bounds a batch by elapsed time instead of item count.
 *
 * A fixed batch size cannot be right for every site: 50 posts is wasteful on a
 * fast VPS and exceeds the request limit on a slow shared host. Budgeting by
 * time makes the item count an outcome, so one implementation behaves sanely
 * across both without a setting for the owner to get wrong.
 *
 * @since 1.14.0
 */
final class Deadline {

	/**
	 * Budget used when PHP reports no execution limit.
	 *
	 * An unlimited limit must not mean an unlimited batch: a run that never
	 * returns leaves the owner with no progress and no way to intervene.
	 */
	public const SELF_CAP_SECONDS = 90;

	/**
	 * Seconds held back from the limit so committing state and returning a
	 * response happen inside the request, not after it is killed.
	 */
	public const SAFETY_PAD_SECONDS = 10;

	/**
	 * Smallest usable budget, for hosts whose limit is at or below the pad.
	 */
	public const MIN_BUDGET_SECONDS = 5;

	/**
	 * Timestamp the batch must stop by.
	 *
	 * @var float
	 */
	private float $expires_at;

	/**
	 * Returns the current time as a float.
	 *
	 * Injected so tests can advance time without sleeping.
	 *
	 * @var callable(): float
	 */
	private $clock;

	/**
	 * Seconds of work this deadline was built from.
	 *
	 * @var int
	 */
	private int $budget_seconds;

	/**
	 * @since 1.14.0
	 *
	 * @param float    $expires_at     Timestamp the batch must stop by.
	 * @param callable $clock          Returns the current time as a float.
	 * @param int      $budget_seconds Optional. Budget this was built from.
	 */
	public function __construct( float $expires_at, callable $clock, int $budget_seconds = 0 ) {
		$this->expires_at     = $expires_at;
		$this->clock          = $clock;
		$this->budget_seconds = $budget_seconds;
	}

	/**
	 * Builds a deadline from PHP's execution limit.
	 *
	 * @since 1.14.0
	 *
	 * @param callable|null $clock     Optional. Defaults to microtime.
	 * @param int|null      $php_limit Optional. Defaults to ini max_execution_time.
	 *
	 * @return self
	 */
	public static function from_php_limit( ?callable $clock = null, ?int $php_limit = null ): self {
		$clock = $clock ?? static fn(): float => microtime( true );

		if ( null === $php_limit ) {
			$php_limit = (int) ini_get( 'max_execution_time' );
		}

		// 0 means unlimited; an absurdly long limit is treated the same way,
		// because a batch measured in minutes is indistinguishable from a hang
		// to the person watching the progress bar.
		$limit = ( $php_limit <= 0 || $php_limit > self::SELF_CAP_SECONDS )
			? self::SELF_CAP_SECONDS
			: $php_limit;

		$budget = max( self::MIN_BUDGET_SECONDS, $limit - self::SAFETY_PAD_SECONDS );

		/**
		 * Filters the per-batch time budget in seconds.
		 *
		 * @since 1.14.0
		 *
		 * @param int $budget Seconds of work allowed in one batch.
		 */
		$budget = (int) apply_filters( 'postlinkly_index_batch_budget', $budget );
		$budget = max( self::MIN_BUDGET_SECONDS, $budget );

		return new self( $clock() + $budget, $clock, $budget );
	}

	/**
	 * Whether the batch has run out of time.
	 *
	 * @since 1.14.0
	 */
	public function expired(): bool {
		return ( $this->clock )() >= $this->expires_at;
	}

	/**
	 * Seconds left before the batch must stop; never negative.
	 *
	 * @since 1.14.0
	 */
	public function remaining(): float {
		return max( 0.0, $this->expires_at - ( $this->clock )() );
	}

	/**
	 * Seconds of work this deadline allows in total.
	 *
	 * @since 1.14.0
	 */
	public function budget_seconds(): int {
		return $this->budget_seconds;
	}
}