Тестируем token bucket для iOS на облачном Mac с управляемым временем

Тестируем token bucket для iOS на облачном Mac с управляемым временем

Тестируем token bucket для iOS на облачном Mac с управляемым временем

При удалённом запуске тестов ограничитель частоты запросов иногда пропускает один лишний запрос. Это легко списать на нагрузку машины. Но часто причина в другом: тест пытается угадать момент пополнения с помощью sleep. Поток просыпается на несколько миллисекунд позже — и проверка уже оказывается по другую сторону временной границы. Если выделить token bucket на входе запросов iOS в чистую машину состояний и передавать ей явные значения времени на облачном Mac, ошибки алгоритма можно отделить от задержек планировщика.

Сначала определяем ёмкость и правила пополнения

В этой статье используется дискретный token bucket: ёмкость — два токена, каждые 250 миллисекунд добавляется один токен, при создании бакет заполнен. Каждый запрос расходует заданное количество токенов; если их недостаточно, запрос сразу отклоняется, без постановки в очередь. Периоды пополнения отсчитываются от момента инициализации, а расход токенов не перезапускает этот цикл.

Такая модель подходит, если нужно ограничить кратковременные всплески, но после простоя разрешать несколько задач подряд. Если же требуется никогда не превышать фиксированное число запросов в любом скользящем окне, token bucket не подходит: поведение этих моделей на границах различается.

Ограничитель на клиенте регулирует только частоту запросов, которые отправляет сам клиент, и не заменяет проверку квот на сервере. После перезапуска процесса бакет снова заполняется, поэтому такой механизм нельзя считать общим ограничителем для нескольких устройств или процессов.

Время задаётся целым числом миллисекунд по монотонным часам, без обращения к календарному времени. Приведённая ниже реализация отклоняет значения, идущие назад во времени, чтобы ошибка в тестовых данных не могла незаметно изменить состояние.

Реализуем ядро с передачей времени извне

Сохраните код в TokenBucketChecks.swift. Ядро не обращается к сети, не приостанавливает потоки и не зависит от жизненного цикла приложения. Ёмкость и период должны быть больше нуля — это предусловие создания объекта. Внешнюю конфигурацию нужно проверить до создания экземпляра.

import Dispatch
import XCTest

struct TokenBucket {
    let capacity: UInt64
    let interval: UInt64
    private(set) var tokens: UInt64
    private var last: UInt64

    init(capacity: UInt64, interval: UInt64, now: UInt64) {
        precondition(capacity > 0 && interval > 0)
        self.capacity = capacity
        self.interval = interval
        self.tokens = capacity
        self.last = now
    }

    mutating func take(_ cost: UInt64 = 1, at now: UInt64) -> Bool {
        guard now >= last else { return false }

        let steps = (now - last) / interval
        if steps > 0 {
            let room = capacity - tokens
            if steps >= room {
                tokens = capacity
            } else {
                tokens += steps
            }
            last += steps * interval
        }

        guard cost > 0 && cost <= tokens else { return false }
        tokens -= cost
        return true
    }
}

Сначала число прошедших периодов сравнивается со свободной ёмкостью, и только затем добавляются токены. Это позволяет избежать переполнения при прямом сложении после долгого простоя. Значение steps * interval не превышает now - last, поэтому при обновлении временной отметки она также не выйдет за пределы переданного момента.

После достижения ёмкости лишние токены не накапливаются, но фаза цикла пополнения сохраняется. Например, если потратить токен на отметке 249 миллисекунд, на отметке 250 миллисекунд пополнение всё равно произойдёт. Это осознанный выбор модели, а не точная гарантия непрерывной средней скорости.

Заменяем реальные ожидания проверками на границах

Добавьте следующие тесты в тот же файл. Первый проверяет размер допустимого всплеска и границы пополнения, второй — длительный простой и некорректные входные данные. Каждая проверка использует отдельную, понятную временную отметку и не зависит от текущей загрузки облачной машины.

final class BucketTests: XCTestCase {
    func testBurstAndRefill() {
        var bucket = TokenBucket(capacity: 2, interval: 250, now: 0)
        XCTAssertTrue(bucket.take(at: 0))
        XCTAssertTrue(bucket.take(at: 0))
        XCTAssertFalse(bucket.take(at: 249))
        XCTAssertTrue(bucket.take(at: 250))
        XCTAssertTrue(bucket.take(at: 749))
        XCTAssertTrue(bucket.take(at: 750))
        XCTAssertFalse(bucket.take(at: 750))
    }

    func testIdleCapAndInvalidInputs() {
        var bucket = TokenBucket(capacity: 2, interval: 250, now: 0)
        XCTAssertTrue(bucket.take(2, at: 0))
        XCTAssertTrue(bucket.take(at: 10_000))
        XCTAssertTrue(bucket.take(at: 10_000))
        XCTAssertFalse(bucket.take(at: 10_000))

        let before = bucket.tokens
        XCTAssertFalse(bucket.take(at: 9_999))
        XCTAssertEqual(bucket.tokens, before)
        XCTAssertFalse(bucket.take(0, at: 10_000))
        XCTAssertFalse(bucket.take(3, at: 10_000))
    }
}

XCTMain([
    testCase([
        ("testBurstAndRefill", BucketTests.testBurstAndRefill),
        ("testIdleCapAndInvalidInputs", BucketTests.testIdleCapAndInvalidInputs)
    ])
])

Запустите файл средствами разработки из полной установки Xcode:

xcrun swift TokenBucketChecks.swift

Оценивайте результат по коду завершения команды, а не по наличию определённого слова в журнале. Этот скрипт проверяет общий алгоритм на Swift. При переносе в тестовый таргет iOS сохраните тестовые методы и удалите XCTMain в конце скрипта: обнаружением тестов займётся тестовый раннер.

Рекомендуется также добавить случаи с ёмкостью в один токен, списанием всей ёмкости за один вызов, ненулевым временем инициализации и входными значениями, близкими к UInt64.max. Не вводите «допуск в несколько миллисекунд», чтобы заставить падающий тест пройти: иначе детерминированная проверка снова превратится в тест, зависящий от реальных задержек.

Подключаем монотонные часы и сериализуем доступ

В рабочем коде миллисекунды можно получать через DispatchTime.now().uptimeNanoseconds / 1_000_000. При инициализации и последующих запросах нужно использовать один и тот же источник времени, не смешивая его с серверным временем, настенными часами или относительным счётчиком от запуска приложения.

Если один бакет используется несколькими задачами, получение времени, пополнение и списание токенов должны выполняться в одном методе актора без await внутри. При использовании блокировки время также нужно считывать уже после её захвата. Иначе вызов, получивший время раньше, может войти в критическую секцию позже и быть отклонён как возвращающий время назад.

Определяем правила сна и пересоздания

Эта модель не гарантирует накопление токенов во время сна системы. Если продукт должен учитывать время сна, нужно выбрать часы с соответствующей семантикой и отдельно проверить это поведение. Пересоздание бакета после завершения приложения восстанавливает полный запас токенов. Если это неприемлемо, потребуется дополнительный протокол сохранения и восстановления состояния: одного сохранённого остатка недостаточно.

Превращаем сбои в конкретные выводы

Перед отправкой изменений проверьте каждый пункт: начальный всплеск в точности равен ёмкости; за одну миллисекунду до пополнения запрос отклоняется; на самой границе — разрешается; после нескольких периодов запас не превышает ёмкость; запросы с нулевой стоимостью и стоимостью выше ёмкости отклоняются; время, идущее назад, не меняет состояние.

Если сбои появляются только после подключения к приложению, сначала проверьте, не создано ли несколько бакетов, не пересоздаётся ли экземпляр перед каждым запросом и не обходят ли повторные попытки общую точку входа. Если тесты проходят, но запросы всё равно идут слишком часто, пересмотрите ёмкость и период, а не добавляйте ожидания, маскирующие расхождение.

В конце отдельно зафиксируйте результаты тестов алгоритма и интеграционных тестов. Первые отвечают на вопрос «верны ли переходы состояния?», вторые — «действительно ли все запросы проходят через одну точку ограничения частоты?». Такое разделение делает удалённые тесты воспроизводимыми и упрощает поиск причины следующей регрессии.

Часто задаваемые вопросы

Почему не стоит проверять пополнение через sleep?

Поток может возобновиться позже ожидаемого. Передавая целочисленные отметки времени, можно точно проверить момент перед пополнением, саму границу и несколько прошедших периодов.

Безопасна ли эта реализация при конкурентном доступе?

Сама по себе нет. Чтение часов, пополнение и списание токенов должны выполняться одной последовательной операцией внутри одного actor или под одним замком.

Пусть ваш проект решит, какой Mac арендовать

Для нативной сборки и отладки в симуляторе арендуйте выделенный Mac с Apple Silicon и проверьте проект. Если вы разрабатываете постоянно и работаете в одном месте, сравните аренду с покупкой. Аренда на день даёт больше гибкости, а при длительном использовании рассмотрите оплату за месяц или квартал.

Арендовать удалённый Mac

Следующий шаг — выберите тариф под этап проекта

Сначала изучите модели, сроки аренды и способы подключения, а затем решите, подходит ли вам аренда.