flagtide.
Publiczne repozytorium
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.
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 GitHubieKilka 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 GitHubie5000 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/resultsCzego 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łemTechnologie
- Angular
- TypeScript
- RxJS
- Signals
- Angular Material
- Java
- Quarkus
- WebSockets
- REST API
- Docker
- Cypress
- Monorepo Nx
- Architektura heksagonalna
- DDD
Porozmawiajmy o roli.
Napisz, jaki to zespół, jaki produkt i jaki stack.