Rate limiting

Сервис без ограничения входа подписывает опасный контракт: сколько пришло запросов, столько и обслужим. При всплеске трафика горутины копятся, очереди растут, латентность ползёт вверх, дедлайны из урока 04 срабатывают у всех, клиентские ретраи умножают поток — классическая лавина, из которой сервис без admission control не выходит сам. Идея лимитера проста и древняя, как телефонный коммутатор: измерить допустимый темп заранее и отклонить всё сверх него мгновенно и дёшево. Отклонённый запрос не расходует ни CPU, ни память, ни соединения с базой — его цена измеряется микросекундами и одной проверкой числа. Клиенту отказ тоже полезнее ожидания: честный 429 Too Many Requests с заголовком Retry-After говорит «притормози и вернись через секунду» вместо тишины и таймаута. Именно поэтому fail fast — основной принцип этого урока: лучше быстрый явный отказ, чем медленная деградация всех запросов сразу. Заметь, где ставится контроль: не в сервисе — домен не обязан знать о трафике, — и не в декодере, а на endpoint'е, тем самым механизмом endpoint.Middleware из урока 02, которым мы уже собирали логи, метрики и спаны. Обёртка go kit rate limit — четвёртая того же сорта, и это не совпадение: в go-kit вся механика вокруг запроса живёт в middleware.

Алгоритм token bucket — самая ходовая модель лимитирования, потому что описывается одной метафорой. Есть бакет ёмкостью capacity: в него с постоянной скоростью капают токены — раз в fillInterval или rate токенов в секунду; каждый запрос перед проходом берёт один токен; бакет полон — запросы идут свободно, бакет пуст — запросы отклоняются. Две ручки дают точную настройку: rate задаёт среднюю скорость, которую сервис готов переваривать, capacity — допустимый всплеск: накопившийся запас токенов позволяет пропустить burst из capacity запросов подряд, а потом темп упрётся в rate. Именно эта способность «сглаживать всплески, но разрешать их» отличает token bucket от тупого счётчика «не больше N в секунду»: API, который ходит циклами, не будет резаться на ровном месте. В Go эталонная реализация — github.com/juju/ratelimit: ratelimit.NewBucket(fillInterval, capacity) капает по таймеру, ratelimit.NewBucketWithRate(rate, capacity) принимает токенов в секунду float64 и сама вычисляет внутренний квант; методы Take и WaitMaxDuration умеют брать токены неблокирующе или с потолком ожидания, Available() показывает запас, Capacity() и Rate() возвращают настройки. Бакет потокобезопасен: все методы можно звать из любых горутин — для веб-сервиса это обязательное требование, запросы приходят параллельно. Подберёшь числа ниже, а пока — как этот бакет становится middleware.

Посмотрим, что делает middleware, когда Allower сказал нет. НовЕрный вариант — вернуть клиенту что-то осмысленное — требует, чтобы отказ был типизированной ошибкой, а не строкой. Go-kit делает ровно это: пакет объявляет var ErrLimited = errors.New("rate limit exceeded") — единственный экземпляр на весь процесс, — и NewErroringLimiter возвращает его в канал err: return nil, ErrLimited. Endpoint при этом не вызывается вовсе: сервис, база, декодеры — всё остаётся нетронутым, отказ стоил одной проверки. У единого ErrLimited два следствия. Первое — проверка на принимающей стороне: в encodeError из урока 05 отказ узнаётся через errors.Is(err, kitratelimit.ErrLimited) — errors.Is устойчив к обёрткам fmt.Errorf с %w, которые обязательно появятся, когда ошибки начнут обрастать контекстом. Второе — превращение в HTTP-ответ: сырой ErrLimited с DefaultErrorEncoder из урока 04 уехал бы в 500 text/plain — формально всё работает, но клиент не отличит лимит от бага. Честный ответ — 429 Too Many Requests с Retry-After, и для этого нужен тип-носитель из арсенала уроков 04-05: ошибка, реализующая StatusCode() и Header(), через которую кодек отдаст и статус, и заголовок. Ниже соберём такой конверт, а пока зафиксируй принцип: middleware возвращает каноническую ошибку, транспортное преобразование в статус — работа кодеков, как и для ErrEmpty.

NewErroringLimiter — не единственный ответ на пустой бакет, и противопоставление двух middleware пакета — важнейший выбор этого урока. NewDelayingLimiter принимает Waiter { Wait(ctx context.Context) error } и вместо отказа ждёт: limiter.Wait(ctx) блокирует горутину, пока не накапает токен, и лишь потом пропускает запрос к endpoint'у. Это уже не admission control, а throttling — сглаживание: запросы не отклоняются, а выстраиваются в невидимую очередь с темпом rate. Когда что выбирать. Для публичного HTTP API — erroring, почти всегда: горутины ждущих клиентов — это память и соединения, всплеск трафика превращается в всплеск горутин, и лимитер от одной беды защищает, создавая другую; клиенту честнее Retry-After, чем подвисший ответ. Для внутренних фоновых потоков — delaying — в самый раз: воркер, который перекачивает задачи, спокойно подождёт токен, ему некуда спешить и обидно падать; загруженная очередь — штатный режим, а не инцидент. Есть и промежуточные сценарии: WaitForN с потолком ожидания — подожди, но не дольше X, потом откажи. Обрати внимание на ctx в Wait: дедлайн из запроса уважается, и ожидание прервётся ошибкой context.DeadlineExceeded, когда клиент уже уехал. И держи в голове предельный случай delaying: burst приходящего трафика больше capacity — очередь растёт неограниченно, латентность p90 из метрик урока 07 улетает в космос, хотя ни один запрос не получил отказ. Отсутствие 429 — ещё не здоровье.

У тебя уже четыре endpoint-middleware, и порядок их сборки в main перестал быть мелочью. Правило простое: чем дешевле отказ, тем раньше обёртка. Лог из урока 06 полезен для всех исходов, включая отказы, — он снаружи. Дальше лимитер: отклонённый запрос не должен тратить ничего, кроме строки в логе. Метрики из урока 07 и спаны из урока 08 — вопрос вкуса с важным нюансом, который станет predict-задачей ниже: если instrumentingMiddleware стоит внутри лимитера, отклонённые запросы не попадают в request_count и график нагрузки рисует только пропущенное — согласованное решение стоит задокументировать в коде, например отдельным счётчиком rate_limited_total. Трейсер из урока 08 внутрь лимитера ставить стоит: отказ 429 — тоже событие, которое хочется видеть в Jaeger, и спан на него обойдётся дешевле, чем на сервис. Итоговый порядок: loggingMiddleware снаружи, затем лимитер, затем трейсер, затем instrumentingMiddleware и endpoint. Отдельно про транспорт: ServerBefore и декодер отрабатывают до endpoint-обёрток, поэтому лимитированный запрос всё равно потратит чуть-чуть — на чтение заголовков; если этого мало, переноси лимит в ServerBefore как RequestFunc, но тогда он перестанет быть endpoint-логикой и потеряет транспортную независимость. Для stringsvc честная цена в декодере — копейки, endpoint-обёртка правильнее.

Бакет в примере выше один и обслуживает endpoint целиком — это канон go-kit и правильная точка старта: у каждого endpoint свои ресурсы и свой допустимый темп. Но числа не берутся с потолка, и вот честная методика. Средний rate бери из метрик урока 07: если p90 латентности приемлема при 8 запросах в секунду, ставь 10 с запасом; capacity считай как допустимый всплеск — сколько запросов подряд сервис переварит без деградации: для быстрых in-memory методов это десятки, для походов в базу — единицы. Пер-клиентские лимиты — отдельная дисциплина: juju/ratelimit не знает про IP и ключи, поэтому per-IP лимитер — это твоя обёртка над endpoint'ом: карта «ключ клиента → свой бакет», mutex вокруг неё, чистка давних записей по таймеру, иначе карта растёт вечно, — всё как в любом лимитере на HTTP-фреймворке. Ключ честно брать из заголовков с осторожностью: X-Forwarded-For подделывается, а NAT складывает сотни людей в один адрес — per-IP на публичном API всегда компромисс, реальный идентификатор клиента — аутентификация, о которой пойдёт речь в уроке про безопасность. И ещё одна честная деталь: бакет с rate 10 пропускает ровно 10 токенов в секунду в среднем, но не гарантирует равномерность — заполнение квантуется, и burst может прийти в одну миллисекунду; если нужна строгая равномерность, это уже задача leaky bucket или планировщика, а не token bucket.

Лимитер, который молча режет трафик, хуже отсутствие лимитера: деградация клиента будет выглядеть загадкой. Поэтому отказ — это событие, и его нужно сделать видимым во всех трёх слоях, которые ты уже построил. В логах из урока 06: оберни лимитер в endpoint-middleware, которая при errors.Is(err, kitratelimit.ErrLimited) пишет logger.Log("msg", "rate limited", "method", ...) — или доверь это loggingMiddleware, если он снаружи и видит err: там же появится и took, показывающий, что отказ стоил микросекунды. В метриках из урока 07: объяви kitprometheus.NewCounterFrom с метками method и ограниченным набором исходов — limited/allowed — и инкрементируй его в той же обёртке; алерт на rate этого счётчика расскажет об атаке или кривом клиенте раньше, чем расскажет недовольный заказчик. Полезен и gauge Available() бакета: запас токенов, который изнутри сервиса показывает, насколько близко ты к отказам, — Set каждый период и дашборд готов. В трейсе из урока 08: спан лимитированного запроса обязан существовать — поэтому трейсер и стоит внутри лимитера; событие в спане с текстом ошибки появится само, если обёртка вернёт err в канал. Такая связка даёт полный цикл: метрика позвала — трейс показал, где — лог объяснил, кто. Без неё ты узнаешь о работе лимитера только из писем пользователей.

Лимитер встал в строй: token bucket с двумя ручками, неблокирующая проверка на endpoint'е, каноническая ErrLimited и честный 429 с Retry-After в кодеке из урока 05. Оборачивания из уроков 02-endpoint и 04-http-transport снова показали универсальность: ни сервис, ни транспорт не узнали о появлении лимита. Освежить кодеки ошибок — в уроке 05-codeki, счётчики и гейджи — в уроке 07-metriki, карту курса — на странице курса. Но лимитер защищает сервис от клиентов, а кто защитит клиентов от зависимостей? Если соседний сервис лёг, твой прокси будет честно ждать таймауты на каждом вызове и копить горутины. Дальше — урок 10-circuit-breaker: предохранитель на endpoint'е, состояния closed/open/half-open и мгновенный отказ, пока зависимость чинят.