:"`; on increment the window stays anchored to the * first hit, and an expired bucket opens a fresh window. * * @package PixelYourSite\MCP */ declare( strict_types = 1 ); namespace PixelYourSite\MCP; if ( !defined( 'ABSPATH' ) ) { exit; // Exit if accessed directly. } final class RateLimit { /** Storage key prefix for rate-limit buckets (added on top of Storage::KV_PREFIX). */ private const BUCKET_PREFIX = 'rl_'; /** * Increment the counter for `$bucket` and return whether we are still * under `$limit`. Opens a fixed `$windowSeconds` window on the first hit; * an over-limit bucket returns false without extending the window. * * @param string $bucket Logical bucket name. * @param int $limit Max hits allowed within the window. * @param int $windowSeconds Window length in seconds. * @return bool True if the hit is allowed, false if over limit. */ public static function checkAndIncrement( string $bucket, int $limit, int $windowSeconds ): bool { $key = self::BUCKET_PREFIX . $bucket; $now = time(); $state = self::read( $key, $now ); if ( null === $state ) { Storage::setValue( $key, self::encode( 1, $now + $windowSeconds ) ); return 1 <= $limit; } if ( $state[ 'count' ] >= $limit ) { return false; } Storage::setValue( $key, self::encode( $state[ 'count' ] + 1, $state[ 'exp' ] ) ); return true; } /** * Current counter value for `$bucket`. Returns 0 if the bucket does * not exist or its window has expired. Read-only — does not increment * or open a new window. * * @param string $bucket Logical bucket name. * @return int Current hit count within the window. */ public static function current( string $bucket ): int { $state = self::read( self::BUCKET_PREFIX . $bucket, time() ); return null === $state ? 0 : $state[ 'count' ]; } /** * Forget the bucket — next `checkAndIncrement` opens a new window. * Used by LoopGuard to clear failure counters on success. * * @param string $bucket Logical bucket name. * @return void */ public static function reset( string $bucket ): void { Storage::deleteValue( self::BUCKET_PREFIX . $bucket ); } /** * Parse the stored payload, ignoring buckets whose window has expired. * * @param string $key Full storage key (prefix already applied). * @param int $now Current Unix timestamp. * @return array{count:int, exp:int}|null Parsed state, or null if missing/expired. */ private static function read( string $key, int $now ): ?array { $raw = Storage::getValue( $key ); if ( null === $raw ) { return null; } $parts = explode( ':', $raw, 2 ); if ( 2 !== count( $parts ) ) { return null; } $count = (int) $parts[ 0 ]; $exp = (int) $parts[ 1 ]; if ( $exp <= $now ) { return null; } return array( 'count' => $count, 'exp' => $exp ); } /** * Encode counter state into the `":"` storage payload. * * @param int $count Current hit count. * @param int $exp Window expiry Unix timestamp. * @return string Encoded payload. */ private static function encode( int $count, int $exp ): string { return $count . ':' . $exp; } }