<?php
/**
 * A ceiling on how often one caller may make us create something.
 *
 * @package SharelyAI
 */

namespace SharelyAI;

defined( 'ABSPATH' ) || exit;

/**
 * Counts requests per caller, per window, and says when to stop.
 *
 * Written for one job: the token route mints a platform space for a visitor
 * it has not seen before, and "a visitor it has not seen before" is decided by
 * a cookie. A browser gets that cookie on its first call and comes back with
 * it; a crawler, or a loop in a terminal, ignores it and is new every single
 * time. Three cookieless calls made three spaces when this was found, and
 * nothing stood between a one-line script and as many as it cared to ask for.
 *
 * So the count is kept against the caller's address rather than their cookie,
 * because the cookie is exactly what is not being honoured. The address is
 * hashed before it is stored: this plugin keeps no visitor addresses anywhere
 * — not in the statistics table, not in the log — and a rate limiter is not
 * the place to start. The hash is enough to recognise the same caller within
 * the window and worth nothing afterwards.
 *
 * A transient, so it works on any host, costs one row, and clears itself up.
 * It fails open on purpose: if the counter cannot be read or written, Ask
 * keeps working. A broken object cache should not take a feature down.
 */
final class Throttle {

	/**
	 * Transient prefix. The bucket and the caller's hash complete the key.
	 */
	private const PREFIX = 'sharelyai_rate_';

	/**
	 * Whether this caller may do the thing, counting the attempt.
	 *
	 * @param string $bucket What is being limited, as a short slug.
	 * @param int    $limit  How many are allowed in one window.
	 * @param int    $window How long the window is, in seconds.
	 */
	public static function allow( string $bucket, int $limit, int $window ): bool {
		if ( $limit <= 0 ) {
			return true;
		}

		$key  = self::PREFIX . $bucket . '_' . self::caller();
		$seen = (int) get_transient( $key );
		if ( $seen >= $limit ) {
			return false;
		}

		// The window starts at the first attempt and is not extended by the
		// ones after it. A caller who is refused at the limit waits out what
		// is left of the window rather than restarting it with every try,
		// which is what makes the ceiling a ceiling.
		set_transient( $key, $seen + 1, $window );
		return true;
	}

	/**
	 * Forgets one caller's count. For tests, and for a support request.
	 *
	 * @param string $bucket What was being limited.
	 */
	public static function forget( string $bucket ): void {
		delete_transient( self::PREFIX . $bucket . '_' . self::caller() );
	}

	/**
	 * Who is asking, as a hash that means nothing outside this window.
	 *
	 * `REMOTE_ADDR` and nothing else. `X-Forwarded-For` is written by whoever
	 * is calling unless a proxy in front of us overwrites it, so trusting it
	 * would let the very caller being counted hand us a new identity per
	 * request. Sites behind a reverse proxy that puts the real address
	 * somewhere else can say so through the filter below; the default has to
	 * be the value that cannot be forged.
	 */
	private static function caller(): string {
		$address = isset( $_SERVER['REMOTE_ADDR'] )
			? sanitize_text_field( wp_unslash( $_SERVER['REMOTE_ADDR'] ) )
			: '';

		/**
		 * Filters the address a rate limit is counted against.
		 *
		 * For sites behind a proxy or load balancer that puts the visitor's
		 * address in a header it controls — and only where that header cannot
		 * be set by the visitor.
		 *
		 * @param string $address The address, as PHP sees it.
		 */
		$address = (string) apply_filters( 'sharelyai_client_address', $address );

		return substr( md5( $address . '|' . wp_salt() ), 0, 16 );
	}
}