Wprowadzenie: po co klientowi własny rate limit

Wyobraź sobie, że przychodzisz do banku, w którym działa jedno okienko, a za tobą ustawiło się tysiąc osób. Możesz się przepychać, możesz krzyczeć, ale przepustowość okienka od tego nie wzrośnie. Możesz jedynie albo przyjść w rozsądnym tempie, albo dostać odmowę. Serwerowy rate limit (ograniczenie częstotliwości zapytań) to właśnie ten kasjer, który pewnego dnia po prostu przestaje cię obsługiwać. A rate limit po stronie klienta to twoja osobista decyzja, by nie podchodzić do okienka częściej, niż jest ono fizycznie w stanie przyjąć.

Ten artykuł jest w całości poświęcony algorytmom. Świadomie nie będziemy powtarzać materiałów o tym, jak obsługiwać kod 429 i budować wykładniczy backoff, i nie będziemy omawiać, ile wątków uruchamiać. Tutaj skupiamy się na czymś innym: jak z góry, jeszcze przed wysłaniem zapytania, obliczyć, czy można je wysłać teraz, a jeśli nie — ile czekać. Właśnie ta matematyka odróżnia klienta, który „czasem dostaje odmowy”, od klienta, który latami pracuje z tym samym API, nie irytując jego właścicieli.

Czego się dowiesz z tego materiału:

  • jak zbudowane są cztery rodziny algorytmów — fixed window, sliding window, token bucket i leaky bucket — i czym różnią się na poziomie zachowania, a nie tylko nazw;
  • dlaczego token bucket i GCRA (wariant leaky bucket) stały się standardem de facto i jak zaimplementować je w jeden wieczór, bez błędów zaokrągleń;
  • jak budować hierarchię limitów: globalny budżet, budżet per host, per endpoint, per klucz autoryzacji i per wychodzący adres IP;
  • jak wbudować rotację IP w model limitera, nie psując ani serwerowych kwot, ani własnej telemetrii;
  • które błędy projektowe wyglądają niewinnie, ale prowadzą do nieskończonego oczekiwania, „wybuchów” na początku minuty i wycieku pamięci.

Będziemy mówić językiem inżyniera-mentora: ze wzorami, ale bez zawiłości, z przykładami, ale bez lania wody. Jeśli piszesz parser, SDK do cudzego API, integrację z marketplace lub agregator, który odwiedza setki hostów — ten przewodnik warto dodać do zakładek.

Podstawy: czym jest rate limit po stronie klienta i dlaczego serwer nie wystarczy

Dwa spojrzenia na jeden problem

Serwerowy rate limit chroni infrastrukturę właściciela API: liczy twoje zapytania i odpowiada odmową, gdy kwota zostanie wyczerpana. Rate limit po stronie klienta rozwiązuje inny problem — nie doprowadzać do odmowy. Różnica jest zasadnicza. Serwer reaguje post factum: zapytanie już poszło, kanał jest zajęty, log zaśmiecony, reputacja klienta lekko nadszarpnięta. Klient zaś działa uprzedzająco: zna (lub szacuje) budżet i wydaje go ostrożnie.

Dlaczego nie można po prostu polegać na serwerowych odmowach i ponawiać próby? Bo każde odrzucone zapytanie to zużyte połączenie, zużyty token autoryzacji, wpis w cudzym dzienniku bezpieczeństwa i z reguły pogorszenie twojej pozycji w adaptacyjnych systemach ochrony. Klient, który sam przestrzega tempa, wygląda dla serwera jak dobrze wychowany partner. A klient, który „próbuje, aż go wpuszczą”, wygląda jak źródło problemów. Zgadnij, kogo ograniczą mocniej przy następnym przeglądzie polityk?

Podstawowa terminologia

  • Rate (tempo) — ustalona częstotliwość zapytań, np. „dziesięć zapytań na sekundę”. To tempo, które serwer jest gotów przyjmować bez końca.
  • Burst (wybuch, seria) — ile zapytań można wysłać naraz, pod rząd, nie czekając na uzupełnienie. Serwer często dopuszcza krótkie serie, jeśli średnie tempo nie jest naruszane.
  • Okno (window) — przedział czasu, w którym liczysz zapytania: sekunda, minuta, godzina, doba.
  • Kwota (quota) — maksymalna liczba zapytań w oknie. Kwota podzielona przez długość okna to średnie tempo.
  • Klucz limitu (limit key) — cecha, po której serwer grupuje zapytania: adres IP, token, konto, para „host plus endpoint”. Ten sam klient niemal zawsze podlega jednocześnie kilku kluczom.
  • Koszt (cost) — waga zapytania. Niektóre API liczą wyszukiwanie jako dziesięć jednostek, a odczyt karty jako jedną.

Główna zasada: limiter decyduje „kiedy”, a nie „ile”

Częstym nieporozumieniem jest mylenie limitera z semaforem. Semafor ogranicza liczbę jednoczesnych operacji i odpowiada na pytanie „ile teraz leci”. Limiter ogranicza częstotliwość i odpowiada na pytanie „czy można rozpocząć jeszcze jedną operację właśnie teraz, a jeśli nie — za ile milisekund”. Te dwa mechanizmy się uzupełniają, ale nie są wymienne. Można trzymać jedno połączenie i przy tym przekraczać limit, jeśli zapytania są krótkie. Można trzymać sto połączeń i przestrzegać limitu, jeśli zapytania są wolne.

Trzy właściwości dobrego limitera po stronie klienta

  1. Przewidywalność. Przy tym samym wejściu daje ten sam wynik. Żadnego „czasem przepuszcza trochę więcej”.
  2. TANIOŚĆ. Decyzja zapada w stałym czasie i przy stałej pamięci na klucz. Jeśli masz tysiące hostów, limiter nie może przechowywać historii wszystkich zapytań.
  3. Uczciwość. Jeśli kilka zadań czeka na zgodę, otrzymują ją w kolejności zgłoszenia, a nie „kto się szczęśliwiej obudzi”.

Miej te trzy kryteria w głowie: według nich będziemy porównywać algorytmy w kolejnej sekcji.

Głębokie zanurzenie: rodziny algorytmów i ich matematyka

Fixed window — uczciwy, ale zdradliwy licznik

Najprostszy wariant: dzielisz czas na okna o stałej długości, w każdym oknie prowadzisz licznik, po osiągnięciu kwoty czekasz na początek następnego okna. Pamięci — jedna liczba i jedna znacznika czasu na klucz. Wydawałoby się, że to ideał.

Problem nazywa się efektem granicy okna. Jeśli kwota to sto zapytań na minutę, klient może wysłać sto zapytań w ostatniej sekundzie jednego okna i jeszcze sto w pierwszej sekundzie następnego. Z punktu widzenia klienta wszystko jest legalne: w każdym oknie dokładnie sto. Z punktu widzenia serwera w ciągu dwóch sekund przyszło dwieście zapytań — dwa razy więcej niż jakakolwiek rozsądna interpretacja limitu. Jeśli serwer liczy oknem przesuwnym (a większość współczesnych tak robi), dostaniesz odmowę, szczerze uważając się za niewinnego.

Druga bolączka to synchronizacja serii. Wszystkie twoje workery „budzą się” jednocześnie na początku minuty, bo właśnie wtedy zeruje się licznik. To tworzy szczyty obciążenia sieci, proxy i serwera docelowego.

Sliding window log — dokładnie, ale drogo

Przechowujemy znaczniki czasu wszystkich zapytań w ostatnim przedziale. Przed wysłaniem wyrzucamy przestarzałe i liczymy pozostałe. Absolutnie dokładne rozliczenie, żadnego efektu granicy. Ale pamięć rośnie liniowo wraz z kwotą: przy kwocie dziesięciu tysięcy zapytań na godzinę przechowujesz dziesięć tysięcy znaczników dla każdego klucza. Dla jednego hosta do zniesienia, dla tysiąca hostów — nie.

Sliding window counter — kompromis

Przechowujemy dwa liczniki: bieżącego okna i poprzedniego. Obciążenie szacujemy jako licznik bieżący plus licznik poprzedni pomnożony przez część poprzedniego okna, która jeszcze wpada w przedział przesuwny. Jeśli minęło 20 procent bieżącej minuty, bierzemy 80 procent poprzedniego licznika. To przybliżenie, ale świetnie wygładza granicę i wymaga zaledwie dwóch zmiennych. Wiele implementacji serwerowych używa właśnie jego, więc odtwarzanie go po stronie klienta to dobry sposób, by „myśleć jak serwer”.

Token bucket — wiadro z żetonami

Wyobraź sobie wiadro o pojemności B żetonów. Co sekundę wpadają do niego r żetony, nadmiar przelewa się przez brzeg. Aby wysłać zapytanie o koszcie c, trzeba pobrać c żetonów. Jeśli ich nie ma — czekasz, aż się zbiorą.

Dwa parametry dają dwie niezależne właściwości. Parametr r to ustalone tempo: ile byś nie czekał, długoterminowe tempo nie przekroczy r zapytań na sekundę. Parametr B to maksymalna seria: po przestoju można od razu wysłać B zapytań. To idealnie odpowiada temu, jak formułowane są realne polityki serwerowe: „nie więcej niż sto na minutę, nie więcej niż dziesięć naraz”.

Kluczowy szczegół implementacji to leniwe uzupełnianie. Nie potrzebujesz wątku tła, który co sekundę dodaje żetony. Wystarczy przy każdym wywołaniu obliczyć, ile czasu minęło od poprzedniego, i dodać odpowiednią liczbę: tokens = min(B, tokens + elapsed * r). Dwie liczby na klucz, obliczenie w stałym czasie. W pełni spełnia kryterium taniości.

Leaky bucket — wiadro z dziurą

Tutaj metafora jest odwrotna: zapytania wlewają się do wiadra, a przez dziurę w dnie wypływają ze stałą prędkością r. Wiadro się przepełniło — nowe zapytanie jest odrzucane lub czeka. Wyjście jest zawsze równomierne: żadnych serii, ściśle jedno zapytanie co 1/r sekund. Jeśli serwer nie toleruje serii albo chcesz, by profil ruchu był maksymalnie gładki, to twój wybór.

Istnieją dwie interpretacje leaky bucket. Pierwsza — jako kolejka: zapytania naprawdę trafiają do bufora, a osobny proces wypuszcza je według zegara. Druga — jako licznik: po prostu sprawdzamy, czy wyobrażone wiadro się nie przepełni, i albo przepuszczamy, albo nie. Druga interpretacja w telekomunikacji nazywa się GCRA (Generic Cell Rate Algorithm) i matematycznie jest równoważna token bucket z inną parametryzacją. To ważna obserwacja: jeśli już zaimplementowałeś token bucket, umiesz też robić leaky bucket.

GCRA: jeden znacznik czasu zamiast licznika

GCRA przechowuje jedyną wartość — TAT (theoretical arrival time, teoretyczny czas przybycia): moment, przed którym następne „idealne” zapytanie nie powinno przyjść. Parametry: interwał emisji T = 1/r i tolerancja τ równa (B − 1) * T. Algorytm:

  1. Pobieramy bieżący czas now.
  2. Jeśli TAT jest mniejsze niż now, przyjmujemy TAT równe now (wiadro dawno puste).
  3. Jeśli TAT − τ jest większe niż now — zapytanie przyszło zbyt wcześnie; czas oczekiwania wynosi TAT − τ − now.
  4. W przeciwnym razie przepuszczamy zapytanie i przesuwamy TAT o T do przodu.

Jedna liczba na klucz, żadnych liczników zmiennoprzecinkowych, które z czasem się rozjeżdżają. Z tego powodu GCRA to ulubiony algorytm dla rozproszonych limiterów: jego stan łatwo trzymać w jednym polu klucz-wartość i atomowo aktualizować.

Tabela porównawcza w słowach

  • Fixed window: pamięć minimalna, dokładność niska, serie na granicach, nadaje się tylko jako zgrubne zabezpieczenie.
  • Sliding log: dokładność absolutna, pamięć liniowa od kwoty, właściwy dla kilku kluczy z małymi kwotami.
  • Sliding counter: pamięć dwie zmienne, dokładność przybliżona, dobrze naśladuje logikę serwera.
  • Token bucket: pamięć dwie zmienne, jawna kontrola serii, standard dla SDK klienta.
  • Leaky bucket / GCRA: pamięć jedna zmienna, idealnie równomierne wyjście, standard dla systemów rozproszonych.

O zegarach: monotoniczność i dryf

Wszystkie algorytmy opierają się na „bieżącym czasie”. Używaj zegara monotonicznego (monotonic clock), a nie czasu systemowego. Czas systemowy może skoczyć do tyłu przy synchronizacji, a twój limiter uzna, że minęła ujemna liczba sekund, wyzeruje uzupełnianie lub wręcz przeciwnie — wygeneruje gigantyczną serię. Zegar monotoniczny z założenia nie cofa się. Jedyny wyjątek to rozproszony limiter we wspólnym magazynie, gdzie czas bierze się po stronie magazynu, a nie po stronie klientów, żeby nie zależeć od rozbieżności zegarów między maszynami.

Metoda 1: token bucket w praktyce — implementacja bez pułapek

Krok 1. Wybór parametrów

Przełóż politykę serwera na parę (r, B). Jeśli dokumentacja mówi „sto zapytań na minutę”, bazowe tempo r = 100/60 żetonów na sekundę. Pojemność B to osobna decyzja. Bezpieczny wybór dla nieznanego API — B równa od pięciu do dziesięciu procent kwoty okna, czyli pięć-dziesięć żetonów przy kwocie sto. To pozwala szybko obsłużyć małą paczkę, ale nie tworzy szczytów, które serwer z oknem przesuwnym odbierze jako naruszenie.

Jeszcze lepiej — licz z zapasem: używaj 80–90 procent zadeklarowanego tempa. Liczniki serwera, opóźnienia sieciowe i zaokrąglenia po obu stronach nieuchronnie wprowadzają błąd, a zapas go pochłania.

Krok 2. Struktura stanu

Dla każdego klucza przechowuj: tokens (liczba zmiennoprzecinkowa, bieżąca liczba żetonów), last (monotoniczny znacznik ostatniego przeliczenia), rate, capacity. Chroń stan mutexem albo, w kodzie asynchronicznym, jednym zadaniem-arbitrem, przez które przechodzą wszystkie prośby o żetony.

Krok 3. Algorytm acquire(cost)

  1. Zakładamy blokadę.
  2. now = monotonic(); elapsed = now − last; last = now.
  3. tokens = min(capacity, tokens + elapsed * rate).
  4. Jeśli tokens ≥ cost: tokens −= cost; zwalniamy blokadę; zwracamy „zero oczekiwania”.
  5. W przeciwnym razie: wait = (cost − tokens) / rate; spisujemy żetony na minus: tokens −= cost; zwalniamy blokadę; zwracamy wait.
  6. Wywołująca strona śpi wait sekund, a następnie wysyła zapytanie.

Zwróć uwagę na punkt piąty. Spisanie na minus to rezerwacja. Gwarantuje uczciwość: następne wywołanie zobaczy ujemny stan i dostanie jeszcze większe oczekiwanie, czyli ustawi się w kolejce za poprzednim. Bez rezerwacji pojawia się klasyczny błąd: dziesięć zadań jednocześnie widzi zero żetonów, wszystkie obliczają takie samo oczekiwanie, wszystkie budzą się jednocześnie i robią serię, której limiter miał zapobiec.

Krok 4. Ograniczenie głębokości rezerwacji

Rezerwacja na minus może uciec w nieskończoność: jeśli zadania przychodzą szybciej, niż uzupełniają się żetony, kolejka oczekujących rośnie, a czas oczekiwania ostatniego dąży do godzin. Wprowadź maksymalne opóźnienie (max_delay). Jeśli obliczone wait przekracza próg, nie rezerwuj, tylko zwróć błąd „limiter przeciążony”. Niech scheduler zdecyduje, co dalej: odłożyć, obniżyć priorytet, przełączyć na inny host. To właśnie ten punkt, w którym limiter po stronie klienta zmienia się z pasywnego hamulca w narzędzie zarządzania obciążeniem.

Krok 5. Koszt ważony

Pozwól zapytaniom mieć różny cost. Endpointy wyszukiwania, masowe selekcje, operacje zapisu są zwykle „droższe” dla serwera, a wiele API odzwierciedla to w swoich politykach. Jeśli dokumentacja milczy, ustalaj wagę po własnych obserwacjach czasu odpowiedzi: zapytanie, które serwer obsługuje dłużej, rozsądnie uznać za droższe. Wzór na oczekiwanie się nie zmienia — cost po prostu wchodzi do niego jako mnożnik.

Krok 6. Rozgrzewka i zimny start

Wartość początkowa tokens to osobna decyzja. Pełne wiadro na starcie oznacza natychmiastową serię B zapytań, gdy tylko proces się uruchomi. To może być niepożądane, jeśli dziesiątki procesów startują jednocześnie po wdrożeniu. Bezpieczniej zaczynać od zera lub od połowy pojemności. A jeśli wiadomo, że serwer liczy kwotę według okna niezależnego od twojego startu, start od zera jest jeszcze uczciwszy.

Lista kontrolna token bucket

  • Używane są zegary monotoniczne.
  • Uzupełnianie jest leniwe, według różnicy czasu, bez zegarów tła.
  • Rezerwacja na minus dla uczciwej kolejki.
  • Istnieje max_delay i jawna odmowa przy przepełnieniu.
  • Tempo ustawione z zapasem względem serwerowego.
  • Pojemność ograniczona do rozsądnej części kwoty okna.
  • Obsługiwany cost dla zapytań ważonych.
  • Stan początkowy nie tworzy serii przy wdrożeniu.

Metoda 2: leaky bucket i GCRA — gdy potrzebny jest równomierny strumień

Kiedy wybrać leaky bucket

Token bucket dopuszcza serie. To wygodne, ale są sytuacje, w których sama seria szkodzi: serwer agresywnie reaguje na krótkotrwałe szczyty, kanał proxy ma ograniczoną przepustowość, chcesz, by wzorzec ruchu wyglądał jak u zwykłego, niespiesznego klienta. We wszystkich tych przypadkach potrzebne jest wyjście ze ściśle stałym odstępem między zapytaniami. To właśnie leaky bucket.

Implementacja jako kolejki

Wariant klasyczny: bufor o stałej pojemności i jeden konsument, który co T sekund wyciąga element i wysyła go. Zaleta — prostota i czytelność. Wady — potrzebny osobny wątek lub zadanie, a przy zatrzymaniu konsumenta bufor „zamarza”. To podejście nadaje się, gdy masz wyraźny potok: kolejkę zadań, z której zapytania i tak są pobierane po jednym.

Implementacja jako GCRA

Dla większości scenariuszy klienta wygodniejsza jest interpretacja licznikowa. Algorytm opisaliśmy wyżej; omówmy, jak ustawić parametry. Jeśli wymagany jest ścisły odstęp, ustaw τ = 0: wtedy tolerancja jest zerowa i zapytania przechodzą nie częściej niż raz na T. Jeśli chcesz dopuścić niewielką serię, zwiększ τ. Tak jedna implementacja pokrywa i ścisły leaky bucket, i token bucket. Dlatego właśnie GCRA to dobry „jeden silnik” dla biblioteki limitowania.

Procedura krok po kroku GCRA z rezerwacją

  1. Odczytać TAT dla klucza; jeśli go nie ma, przyjąć TAT = now.
  2. new_TAT = max(TAT, now) + T * cost.
  3. allow_at = new_TAT − τ − T * cost; to moment, w którym zapytanie o takim koszcie można by wysłać bez oczekiwania.
  4. Jeśli allow_at ≤ now: zapisać new_TAT, zwrócić „zero oczekiwania”.
  5. W przeciwnym razie: wait = allow_at − now; jeśli wait przekracza max_delay — zwrócić odmowę bez zapisu; inaczej zapisać new_TAT i zwrócić wait.

W rozproszonym magazynie kroki od pierwszego do piątego wykonuje jedna atomowa operacja — na przykład skrypt po stronie magazynu. Tak gwarantuje się, że dwóch klientów nie odczyta tego samego TAT i nie „zduplikuje” zgody.

Równoważność i wybór według charakteru obciążenia

Warto rozumieć: token bucket z parametrami (r, B) i GCRA z parametrami (T = 1/r, τ = (B − 1)/r) przepuszczają dokładnie te same sekwencje zapytań. Różnica jest tylko w reprezentacji stanu. Dlatego pytanie „co lepsze” brzmi tak naprawdę inaczej: czy potrzebujesz serii. Potrzebujesz — ustaw B większe niż jeden. Nie potrzebujesz — ustaw B = 1 (τ = 0). Reszta to kwestia gustu i wygody przechowywania.

Lista kontrolna leaky bucket / GCRA

  • Zdecydowano, czy potrzebna jest seria, czy ściśle równomierny strumień.
  • Stan — jedna wartość TAT na klucz.
  • Operacja odczytu-sprawdzenia-zapisu jest atomowa.
  • Istnieje max_delay i jawna odmowa.
  • W wariancie rozproszonym czas pobierany jest po stronie magazynu.

Metoda 3: limity per host — rejestr, hierarchia i kompozycja

Dlaczego „jeden limiter na wszystko” nie działa

Jeśli twój klient odwiedza tylko jedno API, wystarczy jedno wiadro. Ale agregatory, parsery i szyny integracyjne sięgają do dziesiątek i setek hostów, z których każdy ma własną politykę. Jeden globalny limit albo nie wykorzystuje szybkich hostów, albo przeciąża wolne. Potrzebny jest rejestr limiterów: odwzorowanie „klucz limitu — stan wiadra”, gdzie klucz buduje się z cech zapytania.

Klucz limitu: od hosta do endpointu

Minimalny klucz — schemat plus host plus port. Dwie domeny jednego właściciela często dzielą kwotę, a subdomeny mogą być liczone osobno; trzeba to wiedzieć z dokumentacji albo ustalić przez obserwację. Klucz subtelniejszy — host plus wzorzec ścieżki: np. endpoint wyszukiwania i endpoint karty produktu mają różne kwoty. Jeszcze subtelniejszy — host plus token autoryzacji, jeśli serwer liczy kwotę na klucz API, a ty masz ich kilka.

Praktyczna zasada: buduj klucz z tych samych cech, po których liczy serwer. Jeśli serwer liczy po IP, do klucza wchodzi twój wychodzący adres IP. Jeśli po tokenie — token. Jeśli po jednym i drugim jednocześnie — potrzebne są dwa limitery, a zapytanie musi przejść przez oba.

Hierarchia limitów

Dobrze zaprojektowany system układa limitery poziomami:

  1. Globalny — wspólny budżet procesu. Chroni twoje własne zasoby: gniazda, pamięć, przepustowość kanału.
  2. Per wychodzący IP — ile zapytań wychodzi przez konkretny adres. Kluczowy poziom przy pracy przez pulę adresów.
  3. Per host — polityka serwera docelowego jako całości.
  4. Per endpoint — osobne kwoty na drogie metody.
  5. Per dane uwierzytelniające — kwoty na token lub konto.

Zapytanie musi uzyskać zgodę na każdym poziomie. To właśnie kompozycja limiterów.

Kompozycja bez wzajemnej blokady

Naiwne podejście — kolejno wywołać acquire u każdego limitera i zsumować oczekiwania. Jest błędne: pierwszy limiter już spisał żeton, a drugi każe czekać dziesięć sekund, przez które żeton pierwszego „przeterminowuje się” z punktu widzenia uczciwości. Co gorsza, dwa zadania zajmujące limitery w różnej kolejności mogą się wzajemnie blokować w nieskończoność.

Poprawna procedura:

  1. Dla każdego limitera obliczyć oczekiwanie bez spisania (operacja peek).
  2. Wziąć maksimum oczekiwań — to jest łączne wait.
  3. Jeśli wait przekracza max_delay — odmowa.
  4. W przeciwnym razie wykonać spisanie we wszystkich limiterach, przekazując im jednolity czas przybycia now + wait, żeby każdy zarezerwował zasób na ten sam moment.
  5. Spać wait i wysłać.

Zawsze przechodź przez limitery w tej samej, ustalonej kolejności (na przykład od globalnego do najwęższego). To wyklucza wzajemne blokady przy dostępie współbieżnym.

Konfiguracja i wartości domyślne

Rejestr powinien umieć utworzyć limiter dla nieznanego wcześniej hosta. Ustaw konserwatywną domyślną wartość: niskie tempo, minimalna seria. Dla znanych hostów — jawna konfiguracja. Dobrą praktyką jest trzymanie polityki w formie deklaratywnej: host lub wzorzec, rate, burst, cost według wzorców ścieżek, znacznik „liczyć po IP” i „liczyć po tokenie”. Wtedy przy zmianie polityki serwera zmienia się jeden plik, a nie kod.

Wypychanie i wycieki

Rejestr z tysiącami hostów to kandydat na wyciek pamięci. Hosty, do których dawno nie zaglądano, trzeba usuwać. Ponieważ stan wiadra po długim przestoju i tak jest „pełny” (lub TAT w przeszłości), wypchnięcie nie traci informacji: przy następnym wywołaniu limiter utworzy się od nowa w tym samym stanie. Używaj cache LRU z ograniczeniem rozmiaru albo okresowego czyszczenia wpisów, których last jest starsze niż kilka okien.

Lista kontrolna limitów per host

  • Klucz limitu powtarza cechy, po których liczy serwer.
  • Są poziomy: globalny, IP, host, endpoint, dane uwierzytelniające.
  • Kompozycja przez peek — maksimum — jednolite spisanie.
  • Limitery przechodzone są w ustalonej kolejności.
  • Konserwatywne wartości domyślne dla nieznanych hostów.
  • Polityki wyniesione do konfiguracji.
  • Rejestr ograniczony rozmiarem i usuwa nieaktywne klucze.

Metoda 4: limiter i rotacja IP — jak uwzględnić zmianę adresu w modelu

Dlaczego rotacja psuje naiwny limiter

Jeśli serwer docelowy liczy kwotę po IP, zmiana adresu zmienia klucz limitu po stronie serwera. Naiwny klient, który prowadzi jeden licznik na host, po zmianie IP będzie dalej hamował, choć serwer widzi już „nowego” gościa. Odwrotny błąd jest groźniejszy: klient resetuje wszystkie limity przy zmianie IP, w tym te, które serwer liczy po tokenie lub koncie — i dostaje odmowę z powodu kwoty, która nie ma nic wspólnego z IP. Wniosek: rotacja powinna wpływać tylko na poziom „per wychodzący IP” w hierarchii, a pozostałe poziomy żyją własnym życiem.

Dwa tryby zmiany adresu

W infrastrukturze Proxeon IP na porcie zmienia się albo według zegara, albo przez link/API (według danych na 22.09.2026). To dwa zasadniczo różne scenariusze dla limitera. Przy zmianie zegarowej klient nie kontroluje momentu: adres zmienia się „z zewnątrz”, a limiter po IP musi się o tym dowiedzieć — przez zdarzenie, odpytywanie bieżącego adresu albo według harmonogramu, jeśli interwał jest znany. Przy zmianie przez link klient sam inicjuje przełączenie i może zsynchronizować je z własnym stanem: doczekać zakończenia zapytań w locie, zafiksować moment, założyć nowy klucz „host plus epoka IP”.

Jak powszechny jest każdy tryb? Według danych na 14.11.2026 udział zmian IP według zegara wynosi 51,1 %, reszta przypada na link/API. Czyli obie strategie występują mniej więcej po równo, a uniwersalny limiter musi obsługiwać obie.

Epoka adresu jako część klucza

Zamiast trzymać w kluczu sam IP (którego można nie znać z góry), użyj epoki — licznika zwiększanego przy każdej zmianie. Klucz poziomu „per IP” staje się parą „port plus epoka”. Przy zmianie epoki stary klucz po prostu przestaje być używany i później jest usuwany przez rejestr, a nowy powstaje w stanie początkowym. Uwaga: stan początkowy znów musi być konserwatywny. Nowy adres dla serwera to nieznajomy, a pierwsze, co zobaczy, to twój wzorzec ruchu.

Dopasowanie okna limitera do zegara rotacji

Według danych na 14.11.2026 mediana interwału między zmianami IP według zegara wynosi 120 s, a 78,1 % interwałów zegarowych jest wielokrotnością dokładnie minuty. To bardzo wygodne dla projektowania. Jeśli masz kwotę na host „N zapytań na minutę po IP”, a adres żyje dwie minuty, to budżet jednego adresu to dokładnie dwa okna minutowe. Limiter po IP może działać jak token bucket z tempem N/60 i pojemnością obliczoną tak, by w czasie życia adresu nie przekroczyć 2N. Ważne, żeby nie „nadrabiać” zaległości: jeśli w pierwszej minucie wysłałeś mało, w drugiej nie można wysłać dwa razy więcej, bo serwer liczy według okna minutowego, a nie według twojej epoki.

Pauza na czas przełączenia

Zmiana adresu nie jest natychmiastowa. Według danych na 14.11.2026 średni czas samej zmiany — od polecenia do nowego adresu — to 4,56 s, a 80,8 % zmian mieści się w 5 sekundach. Co to znaczy dla limitera? W czasie przełączenia zapytania albo pójdą przez stary adres, albo w ogóle nie pójdą. Właściwa strategia — potraktować przełączenie jako krótki przedział „drenażu”: przed poleceniem zmiany limiter przestaje wydawać nowe zgody, czeka na zakończenie zapytań w locie, wykonuje zmianę, po czym otwiera nową epokę. Ponieważ cztery na pięć przełączeń kończą się w ciągu pięciu sekund, rozsądnie jest założyć timeout oczekiwania na nowy adres nieco powyżej tej wartości i przejść do obsługi wyjątku, jeśli zostanie przekroczony.

Ogranicz częstość samego polecenia zmiany

Oto spostrzeżenie, które często umyka: polecenie zmiany IP to też zapytanie do API i też trzeba je limitować. Według danych na 14.11.2026 udział zduplikowanych wpisów o zmianach przez link (interwał nie większy niż 2 s, ten sam IP) wynosi 1,2 %. To ślady sytuacji, w których klient pociągnął link dwa razy pod rząd: z powodu wyścigu między workerami, powtórzenia po timeoucie, braku pojedynczego punktu decyzyjnego. Rozwiązanie — osobne wiadro o pojemności jeden i ścisłym interwale (czysty leaky bucket z τ = 0) na polecenie rotacji, plus deduplikacja: jeśli zmiana już trwa, pozostałe workery czekają na jej wynik, a nie inicjują nowej. Ta sama zasada co dla hostów docelowych, tylko zastosowana do twojej własnej infrastruktury.

Skala i planowanie budżetu

Żeby poczuć skalę: według danych na 14.11.2026 w ciągu doby w całej sieci Proxeon wykonano 2 196 242 zmiany IP, uczestniczyło w nich 7 924 porty proxy, a mediana unikalnych IP na jeden modem na dobę to 95. Dla projektanta limitera oznacza to, że jeden port na dobę przechodzi przez dziesiątki epok adresowych, a stan „per IP” musi być lekki i szybko usuwany: nie ma sensu trzymać historii wszystkich epok, ale zapewnienie stałego kosztu utworzenia nowej epoki — obowiązkowe.

Protokoły i adresacja portów

Drobiazg, który upraszcza konfigurację: w Proxeon port SOCKS5 jest równy portowi HTTP plus jeden (według danych na 22.09.2026). Jeśli używasz obu protokołów dla tego samego kanału, limiter po IP powinien liczyć je jako jeden klucz, a nie dwa: adres jest wspólny, więc i budżet wspólny. Zapisz w rejestrze normalizację: klucz buduje się po porcie HTTP, a port SOCKS5 sprowadza się do niego, odejmując jeden.

Rozproszony limiter po IP

Gdy przez jeden port chodzi kilka procesów lub maszyn, wiadro musi być wspólne. Używaj magazynu z operacjami atomowymi, trzymaj TAT (GCRA) pod kluczem „port plus epoka plus host”, aktualizuj skryptem po stronie magazynu i bierz czas także stamtąd. Epokę również trzymaj centralnie i zmieniaj atomowo razem z poleceniem rotacji — wtedy wszystkie procesy zgodnie przechodzą na nowy klucz.

Lista kontrolna limitera przy rotacji

  • Rotacja wpływa tylko na poziom „per IP”, pozostałe poziomy nie są resetowane.
  • Obsługiwane są oba tryby: zegar i zmiana przez link/API.
  • Klucz poziomu IP zawiera epokę adresu.
  • Nowa epoka startuje w stanie konserwatywnym.
  • Tempo po IP jest zgodne z oknem serwera, a nie z długością epoki.
  • Na czas przełączenia wydawanie zgód jest wstrzymane.
  • Polecenie rotacji samo jest limitowane i deduplikowane.
  • Porty HTTP i SOCKS5 jednego kanału są normalizowane do jednego klucza.
  • Dla scenariuszy wieloprocesowych stan jest wyniesiony do wspólnego magazynu.

Typowe błędy w projektowaniu rate limit po stronie klienta

Błąd 1. Sleep zamiast limitera

„Ustawimy pauzę stu milisekund między zapytaniami” — najczęstsze rozwiązanie i najkruchsze. Nie uwzględnia czasu samego zapytania, nie działa przy kilku workerach, nie daje serii tam, gdzie są dozwolone, i nie chroni przed nimi tam, gdzie są zabronione. Pauza to nie limiter, tylko jego imitacja.

Błąd 2. Liczenie po oknie, gdy serwer liczy przesuwnie

Efekt granicy okna omówiono wyżej. Jeśli nie jesteś pewien, jak liczy serwer, zakładaj najgorsze — okno przesuwne — i używaj token bucket ze skromną pojemnością.

Błąd 3. Wyścig bez rezerwacji

Kilka zadań jednocześnie oblicza takie samo oczekiwanie, zasypia i budzi się razem. Wynik — dokładnie ta seria, której limiter miał zapobiec. Leczenie to rezerwacja (spisanie na minus lub przesunięcie TAT) pod blokadą.

Błąd 4. Nieskończona kolejka oczekiwania

Bez max_delay kolejka rośnie nieograniczenie, a zadania czekają minuty i godziny, zajmując pamięć i połączenia. Limiter musi umieć odmówić.

Błąd 5. Zegar systemowy

Jeden skok czasu przy synchronizacji — i wiadro albo się przepełnia, albo „zamarza”. Tylko zegary monotoniczne po stronie klienta; tylko czas magazynu w wariancie rozproszonym.

Błąd 6. Reset wszystkich limitów przy zmianie IP

Kwoty po tokenie i koncie nie zależą od adresu. Resetując je, od razu naruszysz politykę, która cię nie dotyczyła.

Błąd 7. Pełne wiadro przy starcie

Dziesiątki procesów po wdrożeniu startują z pełnymi wiadrami i jednocześnie robią serię. Zaczynaj od pustego wiadra albo dodaj losowe opóźnienie startu.

Błąd 8. Rejestr bez usuwania

Każdy nowy host to nowy wpis na zawsze. Po tygodniach pracy proces trzyma w pamięci limitery dla hostów, które już nigdy się nie przydadzą.

Błąd 9. Ignorowanie kosztu zapytania

Jeśli serwer liczy wyszukiwanie jako dziesięć jednostek, a ty jako jedną, twój limiter przepuści dziesięć razy więcej niż trzeba i będzie szczerze zdziwiony odmową.

Błąd 10. Nieograniczone polecenie rotacji

Powtórzenie polecenia zmiany adresu po timeoucie lub z kilku workerów prowadzi do duplikatów i zbędnych przełączeń. Polecenie to też zasób; daj mu wiadro.

Narzędzia i zasoby do implementacji

Gotowe biblioteki według ekosystemów

  • Go: pakiet golang.org/x/time/rate — wzorcowa implementacja token bucket z metodami Allow, Reserve i Wait. Metoda Reserve zwraca obiekt z czasem oczekiwania i możliwością anulowania — dokładnie to, czego potrzeba do kompozycji.
  • Python: biblioteka limits udostępnia fixed window, sliding window i GCRA z różnymi backendami; aiolimiter implementuje leaky bucket dla asyncio; pyrate-limiter obsługuje kilka okien jednocześnie.
  • Java/Kotlin: Bucket4j — dojrzały token bucket z obsługą rozproszonych magazynów; Resilience4j RateLimiter — wariant z ustalonymi cyklami odświeżania.
  • JavaScript/TypeScript: bottleneck umie limitować po grupach kluczy i klastrować się przez wspólny magazyn; p-throttle — minimalistyczny wariant dla prostych przypadków.
  • Rust: governor — implementacja GCRA z kluczami i bez, nadająca się do kodu asynchronicznego.
  • .NET: wbudowana przestrzeń System.Threading.RateLimiting z token bucket, sliding window i partitioned-limiterami po kluczach.

Magazyny dla stanu rozproszonego

Redis i kompatybilne magazyny ze skryptami serwerowymi to standard dla wspólnego GCRA: jedna atomowa operacja, czas pobierany poleceniem magazynu, klucze z TTL usuwane automatycznie. Dla scenariuszy wewnątrz jednego klastra aplikacji wystarczą też wbudowane mechanizmy, jak rozproszone cache z operacjami atomowymi.

Narzędzia obserwowalności

Limiter bez metryk to czarna skrzynka. Eksportuj: liczbę zgód bez oczekiwania, rozkład czasu oczekiwania, liczbę odmów po max_delay, bieżące wypełnienie wiader po kluczach, częstość zmian epok adresów. Histogram oczekiwania po hostach natychmiast pokaże, gdzie polityka jest zbyt sztywna, a gdzie jesteś na granicy.

Infrastruktura adresowa

Dla scenariuszy z rotacją przyda się dostawca, który daje dwa tryby zmiany adresu — według zegara i przez link/API — oraz przewidywalną adresację portów. W Proxeon oba tryby są dostępne, a port SOCKS5 jest oddalony od portu HTTP dokładnie o jeden (według danych na 22.09.2026), co ułatwia normalizację kluczy w rejestrze limiterów.

Co czytać

  • Opis GCRA w specyfikacjach standardów telekomunikacyjnych — źródło pierwotne dla leaky bucket jako licznika.
  • Dokumentacja pakietu x/time/rate — wzorcowe sformułowanie semantyki Reserve i Wait.
  • Rozdziały o limitach w dokumentacji dużych publicznych API — tam spotyka się wszystkie modele liczenia i to najlepszy sposób, by nauczyć się przekładać politykę na parametry wiadra.

Przypadki i scenariusze zastosowań

Scenariusz 1. Agregator cen na setki hostów

Zadanie: regularnie obchodzić karty produktów na wielu platformach, z których każda ma własną politykę. Rozwiązanie: rejestr limiterów z kluczem „host plus wzorzec ścieżki”, konserwatywna wartość domyślna dla nowych platform, jawne polityki dla znanych. Kompozycja z globalnym limitem po liczbie gniazd. Efekt, którego dążą takie systemy: równomierne obciążenie wszystkich hostów bez przestojów na szybkich i bez przeciążania wolnych; przy zmianie polityki platformy poprawia się jedna linia konfiguracji. Główna lekcja — przejście od jednego globalnego limitu do hierarchii drastycznie zmniejsza udział zapytań wysłanych „na darmo”.

Scenariusz 2. SDK do partnerskiego API z kwotą na token i na IP

Zadanie: biblioteka dla klientów, którzy mają kilka tokenów i kilka wychodzących adresów. Rozwiązanie: dwa poziomy limiterów — po tokenie i po adresie — z kompozycją przez peek i jednolitym czasem przybycia. Scheduler wybiera parę „token plus adres” z najmniejszym oczekiwaniem. Lekcja — limiter zmienia się w narzędzie routingu: zamiast „czekać” podpowiada „gdzie wysłać, żeby nie czekać”.

Scenariusz 3. Parser na mobilnych adresach z rotacją zegarową

Zadanie: obchodzenie otwartych stron przez pulę portów, adresy zmieniają się według zegara. Rozwiązanie: limiter po IP z kluczem „port plus epoka”, tempo zgodne z oknem minutowym hosta docelowego. Biorąc pod uwagę, że według danych na 14.11.2026 mediana interwału zegarowego to 120 s, a 78,1 % interwałów jest wielokrotnością minuty, budżet na epokę oblicza się jako całkowitą liczbę okien minutowych. Na czas przełączenia — a 80,8 % zmian mieści się w 5 sekundach (według danych na 14.11.2026) — wydawanie zgód jest wstrzymywane z timeoutem nieco powyżej tego progu. Lekcja — dopasowanie okna limitera do rytmu rotacji eliminuje „nadrabiające” serie na początku nowej epoki.

Scenariusz 4. Workery z rotacją przez link i zduplikowane polecenia

Zadanie: kilka workerów dzieli jeden port i każdy w razie potrzeby inicjuje zmianę adresu. Objaw — ślady powtórzonych poleceń w logach. Rozwiązanie: pojedynczy punkt rotacji z leaky bucket (τ = 0) i deduplikacją: jeśli zmiana trwa, pozostali czekają na jej zakończenie. Według danych na 14.11.2026 udział zduplikowanych wpisów o zmianach przez link w sieci wynosi 1,2 %; to dokładnie te sytuacje, które eliminuje pojedynczy punkt decyzyjny. Lekcja — limitować trzeba nie tylko zapytania do cudzych API, ale też polecenia do własnej infrastruktury.

Scenariusz 5. Jeden silnik na GCRA dla wszystkich poziomów

Zadanie: uprościć bazę kodu, w której historycznie współistniały fixed window, pauzy sleep i ręczne liczniki. Rozwiązanie: jedna implementacja GCRA z parametrami (T, τ), stosowana na wszystkich poziomach hierarchii, z przechowywaniem stanu we wspólnym magazynie dla kluczy rozproszonych i w pamięci — dla lokalnych. Lekcja — jeden wzór zastępuje zoo rozwiązań i czyni zachowanie systemu przewidywalnym.

FAQ: odpowiedzi na trudne pytania

Czym token bucket zasadniczo różni się od leaky bucket, jeśli są równoważne?

Są równoważne jako obiekty matematyczne: przy właściwym dopasowaniu parametrów przepuszczają te same sekwencje. Różnica tkwi w intuicji i w tym, który parametr kontrolujesz bezpośrednio. Token bucket myśli w kategoriach „tempo i seria”, leaky bucket — w kategoriach „interwał i tolerancja”. Dla polityk typu „N na minutę, nie więcej niż M naraz” wygodniejszy jest pierwszy; dla „dokładnie jedno zapytanie co T” — drugi. GCRA łączy obie intuicje w jednym stanie.

Jak wybrać pojemność wiadra, jeśli serwer nie publikuje dopuszczalnej serii?

Zacznij od małej części kwoty okna — rzędu pięciu-dziesięciu procent — i obserwuj. Jeśli nie ma odmów, a opóźnienia oczekiwania są duże, ostrożnie zwiększaj. Pamiętaj, że serwer z oknem przesuwnym nie toleruje serii przekraczających kwotę w krótkim podprzedziale, więc pojemność nigdy nie powinna zbliżać się do pełnej kwoty.

Czy limiter jest potrzebny, jeśli mam tylko jeden wątek?

Tak. Jeden wątek z krótkimi zapytaniami łatwo przekracza kwotę: jeśli odpowiedź przychodzi w dwadzieścia milisekund, wyślesz pięćdziesiąt zapytań na sekundę, nawet o tym nie myśląc. Limiter jest potrzebny niezależnie od liczby wątków; rozwiązuje inny problem niż semafor.

Jak limitować zapytania o różnym koszcie, jeśli serwer liczy je różnie?

Przekazuj cost w acquire. Żetony spisuje się proporcjonalnie, oczekiwanie oblicza się tym samym wzorem. Jeśli koszt jest nieznany, szacuj go po czasie odpowiedzi lub po rozmiarze odpowiedzi i uściślaj wraz z obserwacjami. Lepiej przeszacować niż niedoszacować.

Co zrobić, jeśli jedno zapytanie musi przejść pięć limiterów i każdy daje inne oczekiwanie?

Najpierw u wszystkich zapytać o oczekiwanie bez spisania, wziąć maksimum, następnie spisać u wszystkich na ten sam moment przybycia. Przechodzić przez limitery zawsze w tej samej kolejności. Jeśli maksimum przekracza próg — odmowa bez spisania, inaczej zasoby zostaną zarezerwowane „na darmo”.

Jak limiter powinien reagować na zmianę IP według zegara, jeśli nie znam dokładnego momentu?

Używaj zdarzenia lub odpytywania bieżącego adresu, a jeśli interwał jest znany — harmonogramu z zapasem. W Proxeon zmiana według zegara i przez link/API to oba tryby standardowe (według danych na 22.09.2026), a jeśli potrzebna jest dokładna synchronizacja, lepszy jest tryb przez link: wtedy moment zmiany określasz ty i otwierasz nową epokę w swoim rejestrze dokładnie wtedy, gdy przełączenie zostało potwierdzone.

Dlaczego nie można resetować wszystkich limitów po zmianie adresu?

Ponieważ serwer może liczyć kwotę po kilku cechach jednocześnie. Adres się zmienił — kwota po IP zaczyna się od nowa, ale kwota po tokenie, koncie lub sesji liczy dalej. Resetując wszystko, naruszysz te polityki, które nie zależą od adresu. Rotacja powinna dotykać tylko poziomu „per IP” w hierarchii.

Co lepsze dla rozproszonego limitera — token bucket czy GCRA?

GCRA. Ma jedną wartość stanu, łatwiej go aktualizować atomowo i łatwiej przechowywać z TTL. Token bucket wymaga dwóch wartości i nieco bardziej złożonej logiki uzupełniania, co komplikuje atomowy skrypt. Semantycznie oba dają ten sam wynik.

Jak sprawdzić, że limiter działa poprawnie, przed wdrożeniem produkcyjnym?

Napisz test z podmienialnymi zegarami: podawaj zapytania w zadanych momentach i porównuj decyzje z wzorcową sekwencją. Sprawdź przypadki brzegowe: zerowy czas, długi przestój, jednoczesne przybycie wielu zapytań, koszt większy niż pojemność (powinna być jawna odmowa, a nie nieskończone oczekiwanie). Osobno przetestuj kompozycję: dwa limitery o różnych tempach i sprawdzenie, że żaden nie przepuszcza więcej niż jego kwota.

Zakończenie: co robić dalej

Rate limit po stronie klienta to nie hamulec, a system zarządzania. Dobrze zbudowany limiter robi trzy rzeczy: nie doprowadza do odmowy, równomiernie wykorzystuje dostępny budżet i podpowiada schedulerowi, gdzie i kiedy wysłać następne zapytanie. U podstaw leży jeden wzór, czy to token bucket, czy GCRA, ale trzeba go otoczyć dyscypliną: zegary monotoniczne, rezerwacja pod blokadą, maksymalne opóźnienie, hierarchia kluczy i usuwanie.

Krótkie podsumowanie:

  • Fixed window jest prosty, ale zdradliwy na granicach; preferuj token bucket lub GCRA.
  • Token bucket daje osobno kontrolę tempa i serii; GCRA — to samo w jednej liczbie stanu.
  • Klucz limitu powtarza cechy, po których liczy serwer; limitery układa się w hierarchię i komponuje przez peek — maksimum — jednolite spisanie.
  • Rotacja adresu zmienia tylko poziom „per IP”; polecenie rotacji samo zasługuje na własne wiadro.
  • Metryki oczekiwania i odmów to jedyny uczciwy sposób zrozumienia, na ile twoja polityka pokrywa się z serwerową.

Twoje następne kroki: wybierz jeden silnik (radzimy GCRA), opisz polityki znanych hostów w konfiguracji, dodaj konserwatywną wartość domyślną, włącz metryki i przepuść testy z podmienialnymi zegarami. Jeśli pracujesz przez pulę adresów, dodaj epokę do klucza i osobne wiadro na polecenie zmiany. Potem twój klient będzie wyglądał dla każdego serwera jak najgrzeczniejszy gość — ten, któremu nigdy się nie odmawia.