*/ private static $held = array(); /** * Take the user's code-check mutex, or report that another request holds it. * * The row is written with INSERT IGNORE against the options table's unique option_name key, * so exactly one of any number of simultaneous callers inserts it. add_option() cannot do * this: it writes with ON DUPLICATE KEY UPDATE, which reports success to every caller. * * The row holds ":". The time is the database's own clock, written and compared * in SQL, so web servers whose clocks disagree cannot mistake a live mutex for a stale one. * The token is random per hold, so release() can tell its own row from a successor's. * * One immediate retry, after deleting the row only if it is older than MUTEX_STALE: a request * that died holding the mutex must not lock the user out of checking codes for good. The * delete is conditional in the same statement, so a fresh holder is never removed. * * @param int $user_id The user. * @return bool True when this request now holds it; release() it in a finally block. */ public static function acquire( $user_id ) { global $wpdb; $token = bin2hex( random_bytes( 8 ) ); if ( ! self::insert_mutex( $user_id, $token ) ) { // SUBSTRING_INDEX hands CAST digits only, so no server mode can object to truncating // ":" in a DELETE. $wpdb->query( // phpcs:ignore WordPress.DB.DirectDatabaseQuery $wpdb->prepare( "DELETE FROM {$wpdb->options} WHERE option_name = %s AND CAST(SUBSTRING_INDEX(option_value, ':', 1) AS UNSIGNED) < UNIX_TIMESTAMP() - %d", self::MUTEX_PREFIX . (int) $user_id, self::MUTEX_STALE ) ); if ( ! self::insert_mutex( $user_id, $token ) ) { return false; } } self::$held[ (int) $user_id ] = $token; return true; } /** * Give the user's code-check mutex back: delete the row this request inserted, and only that. * * A holder that stalled past MUTEX_STALE may have been taken over; its row is gone and the one * there now belongs to another request, which keeps it. * * @param int $user_id The user. * @return void */ public static function release( $user_id ) { global $wpdb; $user_id = (int) $user_id; if ( ! isset( self::$held[ $user_id ] ) ) { return; } $wpdb->query( // phpcs:ignore WordPress.DB.DirectDatabaseQuery $wpdb->prepare( "DELETE FROM {$wpdb->options} WHERE option_name = %s AND SUBSTRING_INDEX(option_value, ':', -1) = %s", self::MUTEX_PREFIX . $user_id, self::$held[ $user_id ] ) ); unset( self::$held[ $user_id ] ); } /** * Insert the mutex row unless it exists. * * @param int $user_id The user. * @param string $token This hold's random token. * @return bool True when this call inserted it. */ private static function insert_mutex( $user_id, $token ) { global $wpdb; $inserted = $wpdb->query( // phpcs:ignore WordPress.DB.DirectDatabaseQuery $wpdb->prepare( "INSERT IGNORE INTO {$wpdb->options} (option_name, option_value, autoload) VALUES (%s, CONCAT(UNIX_TIMESTAMP(), ':', %s), 'off')", self::MUTEX_PREFIX . (int) $user_id, $token ) ); return 1 === $inserted; } /** * Count a wrong code, and lock the user when it is the one that reaches the limit. * * @param int $user_id The user. * @return bool True when this wrong code locked the user. */ public static function note_wrong( $user_id ) { $record = self::read( $user_id ); $locked = false; ++$record['wrong']; if ( $record['wrong'] >= self::WRONG_LIMIT ) { ++$record['strikes']; $record['wrong'] = 0; $record['until'] = time() + self::duration( $record['strikes'] ); $locked = true; } set_transient( self::key( $user_id ), $record, max( $record['until'] - time(), self::MEMORY ) ); return $locked; } /** * When the user's lock ends. * * @param int $user_id The user. * @return int A Unix timestamp, or 0 when the user is not locked. */ public static function locked_until( $user_id ) { $until = self::read( $user_id )['until']; return $until > time() ? $until : 0; } /** * Wrong codes the user may still enter before the next lock. * * @param int $user_id The user. * @return int */ public static function tries_left( $user_id ) { return max( 0, self::WRONG_LIMIT - self::read( $user_id )['wrong'] ); } /** * Forget the user's wrong codes and strikes, after a correct code. * * @param int $user_id The user. * @return void */ public static function clear( $user_id ) { delete_transient( self::key( $user_id ) ); } /** * How long the lock lasts for this strike: BASE, doubled per strike after the first, capped. * * @param int $strikes Locks so far, this one included. * @return int Seconds. */ private static function duration( $strikes ) { // Past the cap the doubling no longer matters, and stopping there keeps the shift small. $doublings = min( max( 0, $strikes - 1 ), 16 ); return (int) min( self::BASE * ( 2 ** $doublings ), self::MAX ); } /** * The user's record, or an empty one. * * @param int $user_id The user. * @return array{wrong: int, until: int, strikes: int} */ private static function read( $user_id ) { $record = get_transient( self::key( $user_id ) ); $record = is_array( $record ) ? $record : array(); return array( 'wrong' => isset( $record['wrong'] ) ? (int) $record['wrong'] : 0, 'until' => isset( $record['until'] ) ? (int) $record['until'] : 0, 'strikes' => isset( $record['strikes'] ) ? (int) $record['strikes'] : 0, ); } /** * Transient key. * * @param int $user_id The user. * @return string */ private static function key( $user_id ) { return self::PREFIX . (int) $user_id; } }