<?php
/**
 * Stores normalized feed content in transients.
 *
 * @package PulseCast
 */

namespace PulseCast\Feeds;

/**
 * One transient per feed URL. Reading never makes a network request.
 *
 * The transient's own expiry is a long hard limit used only for cleanup. Freshness is decided
 * by the entry's `fetched_at` (see `Refresh_Policy`), so a failed refresh can keep serving the
 * last good items.
 *
 * Entry shape: `title`, `items`, `fetched_at` (last success), `last_attempt`, `failures`
 * (consecutive) and `error` (last error code, empty when the last attempt succeeded).
 */
final class Feed_Cache {

	public const PREFIX   = 'pulsecast_feed_';
	public const HARD_TTL = 604800;

	/**
	 * Transient name for a feed URL.
	 *
	 * @param string $url Feed URL.
	 */
	public function key( string $url ): string {
		return self::PREFIX . substr( hash( 'sha256', trim( $url ) ), 0, 40 );
	}

	/**
	 * The cache entry for a feed, or null if there is none.
	 *
	 * @param string $url Feed URL.
	 * @return array<string,mixed>|null
	 */
	public function get( string $url ): ?array {
		$stored = get_transient( $this->key( $url ) );

		if ( ! is_array( $stored ) ) {
			return null;
		}

		return array(
			'title'        => is_string( $stored['title'] ?? null ) ? $stored['title'] : '',
			'items'        => is_array( $stored['items'] ?? null ) ? array_values( $stored['items'] ) : array(),
			'fetched_at'   => (int) ( $stored['fetched_at'] ?? 0 ),
			'last_attempt' => (int) ( $stored['last_attempt'] ?? 0 ),
			'failures'     => (int) ( $stored['failures'] ?? 0 ),
			'error'        => is_string( $stored['error'] ?? null ) ? $stored['error'] : '',
		);
	}

	/**
	 * Records a successful fetch, replacing the stored items.
	 *
	 * @param string       $url    Feed URL.
	 * @param Fetch_Result $result Successful result.
	 * @param int          $now    Current Unix time.
	 */
	public function store_success( string $url, Fetch_Result $result, int $now ): void {
		$this->write(
			$url,
			array(
				'title'        => $result->title,
				'items'        => $result->items,
				'fetched_at'   => $now,
				'last_attempt' => $now,
				'failures'     => 0,
				'error'        => '',
			)
		);
	}

	/**
	 * Records a failed fetch. The previously stored items are kept.
	 *
	 * @param string $url   Feed URL.
	 * @param string $error Error code.
	 * @param int    $now   Current Unix time.
	 */
	public function store_failure( string $url, string $error, int $now ): void {
		$entry = $this->get( $url ) ?? array(
			'title'      => '',
			'items'      => array(),
			'fetched_at' => 0,
			'failures'   => 0,
		);

		$entry['last_attempt'] = $now;
		$entry['failures']     = (int) $entry['failures'] + 1;
		$entry['error']        = $error;

		$this->write( $url, $entry );
	}

	/**
	 * Removes a feed's entry.
	 *
	 * @param string $url Feed URL.
	 */
	public function delete( string $url ): void {
		delete_transient( $this->key( $url ) );
	}

	/**
	 * Writes an entry.
	 *
	 * @param string              $url   Feed URL.
	 * @param array<string,mixed> $entry Entry.
	 */
	private function write( string $url, array $entry ): void {
		set_transient( $this->key( $url ), $entry, self::HARD_TTL );
	}
}