<?php
/**
 * Per-agent cap on recorded refusals.
 *
 * @package AgentFirewall
 */

declare(strict_types=1);

namespace AgentFirewall\Ledger;

use AgentFirewall\Repository\LedgerRepository;
use DateTimeImmutable;

defined( 'ABSPATH' ) || exit; // @codeCoverageIgnore

/**
 * Caps how many refused attempts are ledgered per agent, per kind of
 * target, per window (ADR-13).
 *
 * A refusal spends no write budget - nothing reached the site - so without a
 * cap an agent could append hash-chained rows as fast as it could send
 * requests. The first refusals in a burst are the probing signal; the rest
 * only bury it. Counting per kind of target keeps a pivot visible: an agent
 * that exhausts the cap on settings and turns to user accounts is recorded
 * doing so. A flood stays bounded, since there are few kinds of target and
 * every unrecognized route shares "unknown". Both doors share the cap: the
 * REST gatekeeper and the ability door's AbilityRejectionRecorder count the
 * same rows.
 *
 * Best effort: counting and writing are not atomic, so concurrent refusals
 * can overshoot the cap by a request or two. It limits noise; it is not a
 * security boundary.
 */
final class RefusalThrottle {

	/**
	 * Default refusals recorded per agent per window.
	 */
	public const LIMIT = 20;

	/**
	 * Default window, in seconds.
	 */
	public const WINDOW = 600;

	/**
	 * Constructor.
	 *
	 * @param LedgerRepository $ledger Ledger repository.
	 * @param int              $limit  Refusals recorded per window.
	 * @param int              $window Window length in seconds.
	 */
	public function __construct(
		private readonly LedgerRepository $ledger,
		private readonly int $limit = self::LIMIT,
		private readonly int $window = self::WINDOW
	) {
	}

	/**
	 * Whether another refusal may be recorded for this agent now.
	 *
	 * @param int               $agent_id    Acting agent.
	 * @param string            $entity_type Kind of target refused.
	 * @param DateTimeImmutable $now         Time of the refusal.
	 * @return array<string, string>|null Null to skip recording; otherwise
	 *                                    fields to add to the row's result - a
	 *                                    note on the last row the cap admits,
	 *                                    so the gap after it explains itself.
	 */
	public function admit( int $agent_id, string $entity_type, DateTimeImmutable $now ): ?array {
		$since    = $now->modify( sprintf( '-%d seconds', $this->window ) );
		$recorded = $this->ledger->count_status_since( $agent_id, 'refused', $entity_type, $since );

		if ( $recorded >= $this->limit ) {
			return null;
		}

		if ( $recorded === $this->limit - 1 ) {
			return array(
				'further_refusals_not_recorded_until' => $now->modify( sprintf( '+%d seconds', $this->window ) )->format( 'Y-m-d H:i:s' ),
			);
		}

		return array();
	}
}