<?php
/**
 * When a feed is due for refresh, and how healthy it is.
 *
 * @package PulseCast
 */

namespace PulseCast\Feeds;

/**
 * Pure scheduling and health rules over a cache entry.
 *
 * An entry is the array stored by `Feed_Cache`: `items`, `title`, `fetched_at` (last success),
 * `last_attempt`, `failures` (consecutive) and `error` (last error code).
 */
final class Refresh_Policy {

	public const MIN_INTERVAL     = 300;
	public const FAILURE_LIMIT    = 3;
	public const BACKOFF_INTERVAL = 3600;
	public const STALE_FACTOR     = 3;

	public const STATUS_PENDING = 'pending';
	public const STATUS_OK      = 'ok';
	public const STATUS_STALE   = 'stale';
	public const STATUS_FAILING = 'failing';

	/**
	 * Seconds to wait after the last attempt before trying again.
	 *
	 * Never less than five minutes. After repeated consecutive failures the feed is retried
	 * hourly instead, so a dead feed does not consume refresh time.
	 *
	 * @param int $interval_seconds Configured refresh interval.
	 * @param int $failures         Consecutive failures so far.
	 */
	public static function effective_interval( int $interval_seconds, int $failures ): int {
		$interval = max( self::MIN_INTERVAL, $interval_seconds );

		return $failures >= self::FAILURE_LIMIT ? max( $interval, self::BACKOFF_INTERVAL ) : $interval;
	}

	/**
	 * Whether a feed should be fetched now.
	 *
	 * @param array<string,mixed>|null $entry            Cache entry, or null when there is none.
	 * @param int                      $interval_seconds Configured refresh interval.
	 * @param int                      $now              Current Unix time.
	 */
	public static function is_due( ?array $entry, int $interval_seconds, int $now ): bool {
		if ( null === $entry || (int) ( $entry['last_attempt'] ?? 0 ) <= 0 ) {
			return true;
		}

		$wait = self::effective_interval( $interval_seconds, (int) ( $entry['failures'] ?? 0 ) );

		return $now - (int) $entry['last_attempt'] >= $wait;
	}

	/**
	 * Health of a feed: pending, ok, stale or failing.
	 *
	 * @param array<string,mixed>|null $entry            Cache entry, or null when there is none.
	 * @param int                      $interval_seconds Configured refresh interval.
	 * @param int                      $now              Current Unix time.
	 */
	public static function status( ?array $entry, int $interval_seconds, int $now ): string {
		if ( null === $entry || (int) ( $entry['last_attempt'] ?? 0 ) <= 0 ) {
			return self::STATUS_PENDING;
		}

		if ( (int) ( $entry['failures'] ?? 0 ) > 0 ) {
			return self::STATUS_FAILING;
		}

		$age = $now - (int) ( $entry['fetched_at'] ?? 0 );

		return $age > self::STALE_FACTOR * max( self::MIN_INTERVAL, $interval_seconds ) ? self::STATUS_STALE : self::STATUS_OK;
	}
}