Throttler.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Auth;
 
use BagOStuff;
use MediaWiki\Logger\LoggerFactory;
use MediaWiki\MediaWikiServices;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\LogLevel;
 
class Throttler implements LoggerAwareInterface {
    protected $type;
    protected $conditions;
    protected $cache;
    protected $logger;
    protected $warningLimit;
 
    public function __construct( array $conditions = null, array $params = [] ) {
        $invalidParams = array_diff_key( $params,
            array_fill_keys( [ 'type', 'cache', 'warningLimit' ], true ) );
        if ( $invalidParams ) {
            throw new \InvalidArgumentException( 'unrecognized parameters: '
                . implode( ', ', array_keys( $invalidParams ) ) );
        }
 
        if ( $conditions === null ) {
            $config = MediaWikiServices::getInstance()->getMainConfig();
            $conditions = $config->get( 'PasswordAttemptThrottle' );
            $params += [
                'type' => 'password',
                'cache' => \ObjectCache::getLocalClusterInstance(),
                'warningLimit' => 50,
            ];
        } else {
            $params += [
                'type' => 'custom',
                'cache' => \ObjectCache::getLocalClusterInstance(),
                'warningLimit' => INF,
            ];
        }
 
        $this->type = $params['type'];
        $this->conditions = static::normalizeThrottleConditions( $conditions );
        $this->cache = $params['cache'];
        $this->warningLimit = $params['warningLimit'];
 
        $this->setLogger( LoggerFactory::getInstance( 'throttler' ) );
    }
 
    public function setLogger( LoggerInterface $logger ) {
        $this->logger = $logger;
    }
 
    public function increase( $username = null, $ip = null, $caller = null ) {
        if ( $username === null && $ip === null ) {
            throw new \InvalidArgumentException( 'Either username or IP must be set for throttling' );
        }
 
        $userKey = $username ? md5( $username ) : null;
        foreach ( $this->conditions as $index => $throttleCondition ) {
            $ipKey = isset( $throttleCondition['allIPs'] ) ? null : $ip;
            $count = $throttleCondition['count'];
            $expiry = $throttleCondition['seconds'];
 
            // a limit of 0 is used as a disable flag in some throttling configuration settings
            // throttling the whole world is probably a bad idea
            if ( !$count || $userKey === null && $ipKey === null ) {
                continue;
            }
 
            $throttleKey = $this->cache->makeGlobalKey( 'throttler', $this->type, $index, $ipKey, $userKey );
            $throttleCount = $this->cache->get( $throttleKey );
 
            if ( !$throttleCount ) { // counter not started yet
                $this->cache->add( $throttleKey, 1, $expiry );
            } elseif ( $throttleCount < $count ) { // throttle limited not yet reached
                $this->cache->incr( $throttleKey );
            } else { // throttled
                $this->logRejection( [
                    'throttle' => $this->type,
                    'index' => $index,
                    'ipKey' => $ipKey,
                    'username' => $username,
                    'count' => $count,
                    'expiry' => $expiry,
                    // @codeCoverageIgnoreStart
                    'method' => $caller ?: __METHOD__,
                    // @codeCoverageIgnoreEnd
                ] );
 
                return [
                    'throttleIndex' => $index,
                    'count' => $count,
                    'wait' => $expiry,
                ];
            }
        }
        return false;
    }
 
    public function clear( $username = null, $ip = null ) {
        $userKey = $username ? md5( $username ) : null;
        foreach ( $this->conditions as $index => $specificThrottle ) {
            $ipKey = isset( $specificThrottle['allIPs'] ) ? null : $ip;
            $throttleKey = $this->cache->makeGlobalKey( 'throttler', $this->type, $index, $ipKey, $userKey );
            $this->cache->delete( $throttleKey );
        }
    }
 
    protected static function normalizeThrottleConditions( $throttleConditions ) {
        if ( !is_array( $throttleConditions ) ) {
            return [];
        }
        if ( isset( $throttleConditions['count'] ) ) { // old style
            $throttleConditions = [ $throttleConditions ];
        }
        return $throttleConditions;
    }
 
    protected function logRejection( array $context ) {
        $logMsg = 'Throttle {throttle} hit, throttled for {expiry} seconds due to {count} attempts '
            . 'from username {username} and IP {ipKey}';
 
        // If we are hitting a throttle for >= warningLimit attempts, it is much more likely to be
        // an attack than someone simply forgetting their password, so log it at a higher level.
        $level = $context['count'] >= $this->warningLimit ? LogLevel::WARNING : LogLevel::INFO;
 
        // It should be noted that once the throttle is hit, every attempt to login will
        // generate the log message until the throttle expires, not just the attempt that
        // puts the throttle over the top.
        $this->logger->log( $level, $logMsg, $context );
    }
 
}