<?php
/**
 * CSDT_Alert_Window, quiet windows for alerts, kept where a cache flush cannot erase them.
 *
 * WHY THIS EXISTS
 * ---------------
 * An alert cooldown stored in a transient is not a cooldown on this install. A persistent
 * object cache holds transients, and every deploy flushes it, so each deploy erased every quiet
 * window and the next failure of an ongoing incident was reported as new (2026-08-13). The
 * central ceiling moved into CSDT_Telegram::send() then, but five feature-level windows
 * here stayed transients: the CVE-feed and AI-timeout alerts, the auto-block digest backstop,
 * the front-end error report and the paste-guard report.
 *
 * All windows live in one non-autoloaded option. Expired entries are pruned on every write and
 * the table is capped, because two keys are derived from what a request reports (a JavaScript
 * error type, a paste-guard layer) and must not grow a row per distinct value.
 *
 * Not for per-address or per-account state (login lockouts and their notices): that key space
 * is unbounded, and those stay transients by design. tests/alert-window-test.php holds the
 * exemption list and fails the build on any other alert throttle kept in a transient.
 *
 * @package CloudScale_Cyber_DevTools
 * @since   1.10.938
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Option-backed alert windows and counters.
 */
final class CSDT_Alert_Window {

	/** The one option all windows live in. */
	const OPTION = 'csdt_alert_windows';

	/** Most windows kept at once; the soonest to expire are dropped first beyond this. */
	const MAX_KEYS = 200;

	/**
	 * Claims a quiet window: true when the caller may alert now, which also starts the window.
	 *
	 * @param string   $key     Window name.
	 * @param int      $seconds Window length.
	 * @param int|null $now     Clock, for the tests.
	 * @return bool
	 */
	public static function claim( string $key, int $seconds, ?int $now = null ): bool {
		$now = $now ?? time();
		$all = self::load( $now );
		if ( isset( $all[ $key ] ) ) {
			return false;
		}
		$all[ $key ] = array(
			'until' => $now + max( 1, $seconds ),
			'n'     => 1,
		);
		self::save( $all, $key );
		return true;
	}

	/**
	 * How many times a counter has been bumped inside its current window, 0 when none is open.
	 *
	 * @param string   $key Counter name.
	 * @param int|null $now Clock, for the tests.
	 * @return int
	 */
	public static function count( string $key, ?int $now = null ): int {
		$all = self::load( $now ?? time() );
		return isset( $all[ $key ] ) ? (int) $all[ $key ]['n'] : 0;
	}

	/**
	 * Adds one to a counter, opening a window of $seconds when none is open. The window does not
	 * slide: it ends $seconds after the first bump, as the transient it replaces did.
	 *
	 * @param string   $key     Counter name.
	 * @param int      $seconds Window length.
	 * @param int|null $now     Clock, for the tests.
	 * @return int The count after this bump.
	 */
	public static function bump( string $key, int $seconds, ?int $now = null ): int {
		$now = $now ?? time();
		$all = self::load( $now );
		if ( isset( $all[ $key ] ) ) {
			++$all[ $key ]['n'];
		} else {
			$all[ $key ] = array(
				'until' => $now + max( 1, $seconds ),
				'n'     => 1,
			);
		}
		self::save( $all, $key );
		return (int) $all[ $key ]['n'];
	}

	/**
	 * The open windows, expired ones dropped. A corrupt option reads as empty.
	 *
	 * @param int $now Clock.
	 * @return array<string,array{until:int,n:int}>
	 */
	private static function load( int $now ): array {
		$raw = get_option( self::OPTION, array() );
		$out = array();
		foreach ( is_array( $raw ) ? $raw : array() as $k => $v ) {
			if ( is_array( $v ) && isset( $v['until'] ) && (int) $v['until'] > $now ) {
				$out[ (string) $k ] = array(
					'until' => (int) $v['until'],
					'n'     => (int) ( $v['n'] ?? 1 ),
				);
			}
		}
		return $out;
	}

	/**
	 * Writes the windows back, keeping at most MAX_KEYS: the one just written always, then the
	 * longest-lived. Dropping the new entry would reopen its window at once.
	 *
	 * @param array<string,array{until:int,n:int}> $all  Windows.
	 * @param string                               $keep Key written by this call.
	 * @return void
	 */
	private static function save( array $all, string $keep ): void {
		if ( count( $all ) > self::MAX_KEYS ) {
			$mine = $all[ $keep ];
			unset( $all[ $keep ] );
			uasort(
				$all,
				static function ( array $a, array $b ): int {
					return $b['until'] <=> $a['until'];
				}
			);
			$all          = array_slice( $all, 0, self::MAX_KEYS - 1, true );
			$all[ $keep ] = $mine;
		}
		update_option( self::OPTION, $all, false );
	}
}