<?php
/**
 * Storage of try-on requests, with the atomic state changes the job runner relies on.
 *
 * @package Fitzaro
 */

namespace Fitzaro\Job;

defined( 'ABSPATH' ) || exit;

/**
 * Every state change is a conditional update that reports whether it applied, so two workers
 * can never both move the same request: the one whose update matched no row backs off.
 *
 * Times are UTC strings in MySQL format (Y-m-d H:i:s).
 */
interface Requests {

	/**
	 * Inserts a queued request and returns its UUID.
	 *
	 * @param array<string, mixed> $fields visitor_hash, user_id, product_id, variation_id, upload_path, provider, model, prompt_version, params.
	 */
	public function create( array $fields ): string;

	/**
	 * A request row, or null.
	 *
	 * @param string $id Request UUID.
	 * @return array<string, mixed>|null
	 */
	public function find( string $id ): ?array;

	/**
	 * Queued → running under $token. False when someone else claimed it or it is not queued.
	 *
	 * @param string $id          Request UUID.
	 * @param string $token       Claim token for this worker.
	 * @param string $lease_until Lease expiry.
	 * @param string $now         Current time.
	 */
	public function claim( string $id, string $token, string $lease_until, string $now ): bool;

	/**
	 * Increments attempts right before the provider is called: the point after which money may be spent.
	 *
	 * @param string $id    Request UUID.
	 * @param string $token Claim token.
	 */
	public function mark_sent( string $id, string $token ): bool;

	/**
	 * Records the provider's job ID for an asynchronous generation and renews the lease.
	 *
	 * @param string $id          Request UUID.
	 * @param string $token       Claim token.
	 * @param string $remote_id   Provider job ID.
	 * @param string $lease_until New lease expiry.
	 */
	public function set_pending( string $id, string $token, string $remote_id, string $lease_until ): bool;

	/**
	 * Renews the lease of a running request.
	 *
	 * @param string $id          Request UUID.
	 * @param string $token       Claim token.
	 * @param string $lease_until New lease expiry.
	 */
	public function extend_lease( string $id, string $token, string $lease_until ): bool;

	/**
	 * Running → done. False when the request was cancelled meanwhile.
	 *
	 * @param string      $id          Request UUID.
	 * @param string      $token       Claim token.
	 * @param string      $result_path Stored result file.
	 * @param string      $model       Model that produced it.
	 * @param string|null $cost        USD, or null when unknown.
	 * @param string      $now         Current time.
	 */
	public function complete( string $id, string $token, string $result_path, string $model, ?string $cost, string $now ): bool;

	/**
	 * Stores what a generation cost even when its result was thrown away (the provider still charged).
	 *
	 * @param string      $id    Request UUID.
	 * @param string      $model Model.
	 * @param string|null $cost  USD, or null when unknown.
	 */
	public function record_cost( string $id, string $model, ?string $cost ): void;

	/**
	 * Queued or running → failed with an error code. Never overwrites a finished request.
	 *
	 * @param string $id    Request UUID.
	 * @param string $error Error code.
	 * @param string $now   Current time.
	 */
	public function fail( string $id, string $error, string $now ): bool;

	/**
	 * Running → queued, only when the provider was never called (attempts = 0).
	 *
	 * @param string $id Request UUID.
	 */
	public function requeue( string $id ): bool;

	/**
	 * Number of queued and running requests of a visitor.
	 *
	 * @param string $visitor_hash Visitor.
	 */
	public function active_for_visitor( string $visitor_hash ): int;

	/**
	 * The shopper threw a request away: an unfinished one becomes cancelled, a finished one expired,
	 * and the result path is cleared. The caller deletes the file.
	 *
	 * @param string $id  Request UUID.
	 * @param string $now Current time.
	 */
	public function discard( string $id, string $now ): void;

	/**
	 * Requests created at or after $since, optionally only those of one visitor or IP.
	 *
	 * @param string $since  Start of the window.
	 * @param string $column '' for all, 'visitor_hash' or 'ip_hash'.
	 * @param string $value  Hash to match.
	 */
	public function count_created_since( string $since, string $column = '', string $value = '' ): int;

	/**
	 * Spending of requests created at or after $since.
	 *
	 * @param string $since Start of the window.
	 * @return array{micros: int, unpriced: int} Known cost in micro-dollars, and the number of requests
	 *                                           that may cost money but have no cost yet (in progress, or
	 *                                           sent to a provider that reports none).
	 */
	public function spend_since( string $since ): array;

	/**
	 * Marks done requests finished before $before as expired and clears their result path.
	 *
	 * @param string $before Cut-off.
	 * @return int Number of requests expired.
	 */
	public function expire_results( string $before ): int;

	/**
	 * Deletes requests created before $before.
	 *
	 * @param string $before Cut-off.
	 * @return int Number of rows deleted.
	 */
	public function delete_created_before( string $before ): int;

	/**
	 * Requests of a logged-in user, newest first (privacy export and erasure).
	 *
	 * @param int $user_id User ID.
	 * @param int $limit   Maximum rows.
	 * @return list<array<string, mixed>>
	 */
	public function for_user( int $user_id, int $limit ): array;

	/**
	 * Deletes one request row. The caller deletes its files.
	 *
	 * @param string $id Request UUID.
	 */
	public function delete( string $id ): bool;

	/**
	 * Queued and running requests, oldest first, for the reaper.
	 *
	 * @param int $limit Maximum rows.
	 * @return list<array<string, mixed>>
	 */
	public function unfinished( int $limit ): array;
}