<?php
/**
 * Decides what to do with a request whose worker may have died.
 *
 * @package Fitzaro
 */

namespace Fitzaro\Job;

use Fitzaro\Database\Status;

defined( 'ABSPATH' ) || exit;

/**
 * A pure function of the row and the clock, so every rule is unit-tested.
 *
 * Decision 2026-10-28: a request is sent to the provider again only when it never reached it
 * (attempts = 0). Once money may have been spent, an expired synchronous request fails instead
 * of being charged twice; an asynchronous one is polled again, because polling is free.
 */
final class LeasePolicy {

	public const LEAVE            = 'leave';
	public const REQUEUE          = 'requeue';
	public const REPOLL           = 'repoll';
	public const FAIL_TIMEOUT     = 'fail_timeout';
	public const FAIL_NOT_STARTED = 'fail_not_started';

	/**
	 * Seconds after creation when a request is given up, whatever its state.
	 */
	public const MAX_AGE = 900;

	/**
	 * Seconds a request may wait in the queue before nobody is expected to pick it up.
	 */
	public const QUEUE_TIMEOUT = 600;

	/**
	 * What the reaper should do with a request.
	 *
	 * @param array<string, mixed> $row A request row.
	 * @param int                  $now Current Unix time.
	 */
	public static function decide( array $row, int $now ): string {
		$status = (string) ( $row['status'] ?? '' );
		$age    = $now - self::timestamp( $row['created_at'] ?? null, $now );

		if ( Status::QUEUED === $status ) {
			return $age > self::QUEUE_TIMEOUT ? self::FAIL_NOT_STARTED : self::LEAVE;
		}

		if ( Status::RUNNING !== $status ) {
			return self::LEAVE;
		}

		$lease = $row['lease_until'] ?? null;
		if ( null !== $lease && self::timestamp( $lease, 0 ) > $now ) {
			return self::LEAVE;
		}

		$too_old = $age > self::MAX_AGE;

		if ( 0 === (int) ( $row['attempts'] ?? 0 ) ) {
			return $too_old ? self::FAIL_NOT_STARTED : self::REQUEUE;
		}

		if ( '' !== (string) ( $row['remote_id'] ?? '' ) && ! $too_old ) {
			return self::REPOLL;
		}

		return self::FAIL_TIMEOUT;
	}

	/**
	 * Unix time of a UTC 'Y-m-d H:i:s' string, or $fallback when it cannot be read.
	 *
	 * @param mixed $value    Column value.
	 * @param int   $fallback Value for an empty or broken column.
	 */
	public static function timestamp( $value, int $fallback ): int {
		if ( ! is_string( $value ) || '' === $value ) {
			return $fallback;
		}

		$time = strtotime( $value . ' UTC' );

		return false === $time ? $fallback : $time;
	}
}