flagtide.

Wszystkie projekty

Publiczne repozytorium

Feature flagi w czasie rzeczywistym

Samodzielnie hostowany serwis feature flag: Quarkus wypycha zmiany do każdej otwartej przeglądarki przez WebSockety, a SDK w Angularze liczy flagi lokalnie z tym samym wynikiem co serwer.

Po lewej admin, po prawej sklep demo. Flaga zostaje wyłączona i włączona, rollout idzie z 20 na 60 i z powrotem na 30 procent, a na końcu monitor propagacji pokazuje p50, p95 i p99.

Demo na żywo to admin i sklep obok siebie, na tych samych obrazach produkcyjnych. Każdy może edytować flagi, a dane wracają do stanu startowego co godzinę. Nagranie z repozytorium, bez dźwięku.

Po co to zrobiłem.

Feature flagi są w moim codziennym stacku. Nie dawały mi spokoju dwa pytania. Jak dostarczyć zmianę flagi do tysięcy otwartych przeglądarek w dużo mniej niż sekundę? I skąd wiadomo, że Java na serwerze i TypeScript w przeglądarce dają tę samą odpowiedź dla tej samej flagi?

Pracuję głównie w Angularze, a back-endy buduję też w Javie i Quarkusie, więc ten projekt stoi po obu stronach tej granicy. Chciałem jednego zwartego projektu, który pokazuje architekturę heksagonalną i DDD na prawdziwej domenie z prawdziwymi regułami, a nie na zabawkowym CRUD-zie.

Sprawdź w demo.

Admin pisze do jednej instancji serwera, a sklep słucha drugiej, więc każda zmiana przechodzi przez PostgreSQL.

Przełącznik flagi
Wyłącz „promo-banner” w adminie po lewej. Baner znika ze sklepu po prawej, chociaż sklep słucha innej instancji serwera.
Rollout procentowy
Otwórz „beta-recommendations” i zmień procent w regule domyślnej. Link „Recommended” w sklepie pojawia się albo znika, a pole „Browsing as” w stopce sklepu zmienia gościa.
Test kontekstu
W edytorze flagi wpisz klucz i atrybuty w „Try a context”. Szkic, także niezapisany, liczy ten sam ewaluator, którego używa SDK w przeglądarce.
Monitor propagacji
Zakładka „Propagation” w adminie pokazuje czas od commitu do potwierdzenia od klienta: p50, p95 i p99.
Nadpisania i status
Panel „Flags” w rogu sklepu nadpisuje flagę tylko w twojej przeglądarce. Odznaka w nagłówku mówi, czy flagi są na żywo, z pamięci czy offline.

flagtide.adrianturbinski.pl

Trzy trudne miejsca.

Każda decyzja ma w repozytorium swój ADR, razem z alternatywami, które przegrały.

  • Dwa języki, jedna odpowiedź.

    Rollout haszuje klucz kontekstu, a każda różnica w arytmetyce ze znakiem, w UTF-8 albo w porządku semver wysyła użytkownika do innego wariantu na serwerze niż w przeglądarce. Algorytm jest spisany jako specyfikacja, oba silniki to mój kod, a 616 wspólnych wektorów leci w obu językach w CI. Oczekiwane hasze liczy niezależna wyrocznia w Pythonie, więc błąd wspólny dla obu silników nie przejdzie.

    Cena: dwie własne implementacje MurmurHash3 zamiast biblioteki i specyfikacja z numerem wersji.

    Przegrały procenty zmiennoprzecinkowe (różne zaokrąglenia w różnych językach), gotowe hasze z Guavy albo npm (ukryłyby decyzje o Unicode i znaku) i oczekiwane wartości liczone silnikiem w Javie (wspólny błąd przeszedłby niezauważony).

    ADR 0009 na GitHubie
  • Kilka instancji bez brokera.

    PostgreSQL NOTIFY zachowuje kolejność, ale nie jest trwały i mieści najwyżej 8000 bajtów. Powiadomienie niesie więc tylko wskaźnik, każda instancja czyta dziennik zmian od wersji, którą zna, a każde ponowne połączenie słuchacza uruchamia resynchronizację. Test zabija backend słuchacza i sprawdza, że następna zmiana i tak dochodzi.

    Cena: instancja, która zapisała zmianę, robi jedną dodatkową rundę przez bazę, zanim zobaczą ją jej klienci. W compose to kilka milisekund.

    Przegrały zewnętrzny broker (Redis, NATS, Kafka), bo to kolejny ruchomy element, a prawdę i tak trzyma PostgreSQL, cała zmiana w powiadomieniu, bo nie mieści się w 8000 bajtów, i odpytywanie, bo dokłada opóźnienie i stałe obciążenie bazy.

    ADR 0008 na GitHubie
  • 5000 gniazd i jedno wolne.

    Zmiana jest serializowana raz na instancję i ten sam tekst idzie do każdego gniazda. Połączenie, w którym czeka ponad 256 ramek, jest zamykane, więc jeden zablokowany klient nie wstrzymuje reszty.

    Cena: każda instancja rozsyła z jednego wątku, a klient, który nie nadąża, traci połączenie.

    Przegrały osobna ramka dla każdego klienta (przy 5000 klientów kilka razy więcej alokacji) i wątek na każde środowisko (praca na jedno powiadomienie to jedno zapytanie i jeden tekst, a rozsyłanie i tak zależy od zapisów do gniazd).

    ADR 0017 na GitHubie

Liczby.

Tylko to, co zmierzyły skrypty z repozytorium.

77 ms
p95 od commitu do odbioru w przeglądarce. 5000 WebSocketów na dwóch instancjach, 30 zmian, 150 000 ramek, p50 38 ms, p99 90 ms. Cel: poniżej 300 ms. Sześć przebiegów na tej maszynie dało p95 od 77 do 169 ms.
412 ns
Średni czas oceny flagi z rolloutem procentowym w @flagtide/core, w Node. W headless Chromium 315 ns. Cel: poniżej 5 µs.
616
Wspólnych wektorów zgodności, w tym 419 przypadków oceny. Lecą w Javie i w TypeScripcie, a każda różnica zatrzymuje CI.
30 do 80 ms
Od kliknięcia w adminie do zmienionego DOM w sklepie, w teście Cypress na całym stosie. Budżet: jedna sekunda.
1327
Testów w modułach serwera. Do tego 199 w @flagtide/core, 39 w @flagtide/angular, 200 w adminie i 64 w sklepie. Pokrycie linii: 98,7% w @flagtide/core i 99,1% w domenie serwera.
100
Dostępność w Lighthouse na sześciu stronach admina i dwóch stronach sklepu, na obrazach produkcyjnych.

Zmierzone na jednym laptopie: Intel Core i7-12700H, 20 rdzeni logicznych, 15,5 GiB RAM, Linux pod WSL2, Docker 29.1.3, Node 24.21. Klienci, serwery i PostgreSQL działały na tej samej maszynie, więc to liczby dla niej, nie dla sieci między serwerownią a telefonem.

Pliki z wynikami w bench/results

Czego nie ma.

Cele dodatkowe wypadały pierwsze. Testy i poprawność nie wypadły nigdy.

Flagi zależne od innych flag
Wymagają zmiany specyfikacji, wykrywania cykli i nowych wektorów w obu językach. To jeszcze jedno miejsce, w którym Java i TypeScript mogłyby się rozjechać.
Zmiany zaplanowane w czasie
Potrzebują harmonogramu, który na dwóch instancjach odpali zmianę dokładnie raz. To osobny projekt.
Adapter Oracle
Porty mają już testy kontraktowe, więc cel jest jasny. Kontener Oracle w CI jest jednak ciężki dla współdzielonego laptopa.
Zapasowe SSE
Drugi transport obok WebSocketów podwoiłby testy ponownego łączenia i statusu, a potwierdzenia dla monitora propagacji wracają tym samym gniazdem.
Logowanie do admina
Klucze admina trafiają do przeglądarki w pliku config.json. Na demo to wystarcza, prawdziwe wdrożenie potrzebuje logowania przed adminem.
Inne przeglądarki
Testy end to end i wszystkie liczby z przeglądarki pochodzą z Chrome. Firefox, Safari i czytniki ekranu nie są przetestowane.

Co dalej.

Najpierw adapter Oracle, bo testy kontraktowe już mówią, co ma robić. Potem flagi zależne z kontrolą cykli, czyli zmiana specyfikacji i nowe wektory w obu językach. Potem zmiany zaplanowane, z jednym wykonawcą na wszystkie instancje.

ADR 0021: czego nie zbudowałem

Technologie

  • Angular
  • TypeScript
  • RxJS
  • Signals
  • Angular Material
  • Java
  • Quarkus
  • WebSockets
  • REST API
  • Docker
  • Cypress
  • Monorepo Nx
  • Architektura heksagonalna
  • DDD

Porozmawiajmy o roli.

contact@adrianturbinski.pl

Napisz, jaki to zespół, jaki produkt i jaki stack.

Masz projekt do zrobienia? Jest też edycja dla klienta.