← Blog
DevOps11 min czytania

Wait4X — czekanie na gotowość usług przed startem aplikacji

Każdy napisał kiedyś w potoku CI „uśpij na trzydzieści sekund". Jest albo za krótkie, i test miga, albo za długie, i płacisz za minuty bezczynności. Wait4X zamienia zgadywanie na sprawdzanie — i sięga głębiej niż tylko otwarty port.

Jest w każdym projekcie taka linijka, której nikt się nie chwali. W potoku ciągłej integracji, między uruchomieniem kontenerów a testami, stoi sleep 30.

Ma dwie wady i obie kosztują. Jest za krótka — bo baza raz startuje w pięć sekund, a raz w czterdzieści, więc testy migają i ktoś raz w tygodniu klika „uruchom ponownie". Albo jest za długa — bo na wszelki wypadek wpisano minutę, którą teraz płacisz przy każdym z kilkuset przebiegów miesięcznie.

Wait4X zamienia to zgadywanie na sprawdzanie. Narzędzie jest małe i robi jedną rzecz, ale przy przeglądaniu okazało się, że robi ją głębiej, niż zakładałem — i o tym będzie ten wpis.

Stan projektu

wait4x/wait4x ma 1378 gwiazdek i 54 forki — to najmniejszy projekt z ostatnich kilkunastu, jakie opisywałem. Ale ma też coś, czego brakowało większości: historię od listopada 2019, czyli niemal siedem lat. Licencja to Apache 2.0, język Go.

Wydania wymagają uczciwego komentarza. Najnowsze, v3.7.1, jest z 19 sierpnia 2026 — ale poprzednie, v3.6.0, z października 2025. Między wydaniami funkcjonalnymi minęło więc dziesięć miesięcy, a commity z ostatnich tygodni to prawie wyłącznie podbicia zależności.

Nie czytam tego jako niepokojącego sygnału i wyjaśnię dlaczego. To narzędzie kompletne funkcjonalnie: czeka na gotowość usług i tę pracę wykonuje. Nie ma tu czego dodawać poza obsługą kolejnych systemów, a te dochodzą, gdy staną się popularne. Jednocześnie zależności są podbijane co tydzień, więc ktoś pilnuje bezpieczeństwa łańcucha dostaw. Dla narzędzia, które ma jedno zadanie i siedem lat historii, jest to profil właściwy, a nie objaw zwolnienia.

Dowodem, że narzędzie jest naprawdę używane, jest jego obecność w menedżerach pakietów: Homebrew, Alpine, AUR, NixOS, Scoop oraz oficjalny obraz kontenera. Każde wydanie ma przy tym dwadzieścia dziewięć plików binarnych — po jednym na platformę.

Jedenaście rodzajów sprawdzeń

Zakres jest szerszy, niż sugeruje nazwa kojarząca się z portami:

  • Protokoły: TCP, HTTP i HTTPS, DNS.
  • Bazy danych: MySQL, PostgreSQL, MongoDB, Redis, InfluxDB.
  • Kolejki i systemy rozproszone: RabbitMQ, Kafka, Temporal.
  • Dowolne polecenie powłoki — osobny tryb czekający, aż polecenie zwróci sukces albo wskazany kod wyjścia.

Wywołanie jest tak proste, jak można oczekiwać: podajesz adres i tyle. Kilka adresów w jednym poleceniu oznacza sprawdzanie równoległe — narzędzie czeka, aż wszystkie będą gotowe.

Otwarty port to nie gotowa usługa

A teraz rzecz, która czyni to narzędzie wartościowym, i która odróżnia je od skryptu pukającego w port pętlą.

Każdy, kto się na tym przewrócił, wie, o czym mówię: baza przyjmuje połączenia, ale migracje jeszcze nie przeszły. Port jest otwarty, a aplikacja i tak wywala się na brakującej tabeli. Czekanie na port rozwiązało jedną trzecią problemu i dało fałszywe poczucie bezpieczeństwa.

Wait4X pozwala sprawdzić warstwę wyżej i to jest jego najlepsza cecha:

  • Istnienie tabeli w MySQL-u i PostgreSQL-u — czyli można poczekać nie na bazę, ale na zmigrowaną bazę. W PostgreSQL-u da się przy tym wskazać schemat parametrem połączenia.
  • Istnienie klucza w Redisie, a nawet klucza o wartości pasującej do wyrażenia regularnego — więc można czekać na sygnał zapisany przez inny proces.
  • Treść odpowiedzi HTTP na trzy sposoby: wyrażeniem regularnym, ścieżką w strukturze JSON oraz zapytaniem XPath dla odpowiedzi w XML-u i HTML-u. Do tego oczekiwany kod statusu i oczekiwany nagłówek odpowiedzi.
  • Konkretne wartości rekordów DNS — adres dla rekordu A i AAAA, domena dla CNAME i MX, serwer nazw dla NS, wartość tekstowa dla TXT. Z możliwością wskazania serwera, którego ma zapytać.
  • Obecność pracownika w Temporalu w danej przestrzeni nazw i kolejce zadań, z dopasowaniem jego tożsamości wyrażeniem regularnym.

Sprawdzenie po ścieżce JSON zasługuje na wyróżnienie, bo pokrywa najczęstszy realny przypadek. Twoja usługa ma punkt kontrolny zwracający strukturę ze stanem kilku podsystemów. Nie chcesz czekać, aż odpowie — chcesz czekać, aż w tej odpowiedzi stan bazy będzie gotowy. Jedna flaga i po sprawie, bez sklejania potoku z narzędzi do przetwarzania JSON-a.

Do połączeń HTTP dochodzą jeszcze własne nagłówki żądania — czyli punkt kontrolny za uwierzytelnianiem tokenem też da się sprawdzić — oraz obsługa certyfikatu klienta i własnego urzędu certyfikacji. Ta ostatnia rzecz jest istotna w sieci wewnętrznej z własnym urzędem, o którym pisałem przy okazji narzędzi PKI.

Tryb uniwersalny i jego haczyk

Skoro obsługiwanych systemów jest jedenaście, a twoich pewnie więcej, przydaje się wyjście awaryjne — i ono jest. Osobny tryb czeka, aż dowolne polecenie zwróci sukces albo wskazany kod wyjścia. Tym da się sprawdzić wszystko, dla czego nie ma gotowego modułu.

Zajrzałem, jak to jest zrobione, bo sposób uruchamiania polecenia ma tu praktyczne skutki. Otóż podany napis jest rozdzielany na słowa według zasad składni powłoki — więc cudzysłowy działają tak, jak się spodziewasz — ale program uruchamiany jest bezpośrednio, bez pośrednictwa /bin/sh.

Skutek dobry: narzędzie działa w obrazach kontenerów, w których powłoki w ogóle nie ma — a takich, budowanych z minimalnych podstaw, jest coraz więcej. Nie musisz dokładać powłoki tylko po to, by uruchomić sprawdzenie.

Skutek, o którym trzeba wiedzieć: konstrukcje wymagające żywej powłoki nie zadziałają. Potok, przekierowanie do pliku, łączenie poleceń warunkowym „i", rozwijanie gwiazdki w nazwach plików — nie ma tam nikogo, kto by je zinterpretował. Jeśli twoje sprawdzenie jest potokiem dwóch poleceń, opakuj je we własny skrypt i podaj ścieżkę do niego, zamiast liczyć na to, że napis zostanie oddany powłoce.

Jako opakowanie punktu wejścia

Ostatni wzorzec użycia, moim zdaniem najbardziej praktyczny, a w opisie schowany w jednym przykładzie. Po dwóch myślnikach można podać polecenie, które zostanie uruchomione po udanym sprawdzeniu.

Znaczy to, że Wait4X może być punktem wejścia twojego kontenera: najpierw czeka na bazę, potem podaje sterowanie właściwej aplikacji. Zamiast skryptu startowego z pętlą, którą każdy pisze inaczej i nikt nie testuje, masz jedno polecenie z jawnym limitem czasu i sensownym kodem wyjścia. W układzie, gdzie orkiestrator restartuje kontener po niepowodzeniu, to zachowanie dokładnie takie, jakiego się chce.

Kod wyjścia 124

Detal, który znalazłem w kodzie i który uważam za świadectwo dobrego rzemiosła.

Narzędzie ma dwa kody błędu, nie jeden. Zwykły błąd to jedynka, ale przekroczenie limitu czasu zwraca 124. To nie jest liczba wzięta z powietrza — jest to konwencja polecenia timeout z podstawowego zestawu narzędzi systemowych, znana każdemu, kto pisał skrypty powłoki.

Praktyczna korzyść jest bezpośrednia: w potoku CI możesz odróżnić „usługa nie wstała w wyznaczonym czasie" od „wywołałem narzędzie źle". Pierwsze to problem ze środowiskiem albo zbyt krótki limit, drugie to literówka w adresie albo złe hasło. Bez tego rozróżnienia oba przypadki wyglądają w logu identycznie, a diagnozuje się je zupełnie inaczej. Trzymanie się przy tym konwencji zamiast wymyślania własnej numeracji to dokładnie to, czego oczekuję od narzędzia wiersza poleceń.

Czekanie na to, żeby czegoś nie było

Flaga odwracająca sprawdzenie wygląda na ciekawostkę, dopóki nie trafi się na przypadek, w którym jest jedynym rozwiązaniem.

Odwrócone sprawdzenie czeka, aż warunek przestanie być spełniony — na przykład aż port zwolni się. Przydaje się w dwóch sytuacjach, które w potokach wdrożeniowych wracają regularnie: przy sprzątaniu, gdzie trzeba poczekać na faktyczne zamknięcie usługi przed usunięciem zasobów, oraz przy restarcie kroczącym, gdzie stara instancja musi oddać port, zanim nowa spróbuje go zająć. Bez tego dostaje się błąd o zajętym adresie i restart, który „czasem nie działa".

Obok tego jest wykładnicze wycofywanie: wydłużanie przerw między próbami, ze współczynnikiem i maksymalnym odstępem do ustawienia. Przy usłudze, o której wiadomo, że startuje długo, oszczędza to i obciążenia, i wpisów w logu.

Budowanie okrojonej wersji

Drugie znalezisko z kodu, tym razem takie, o którym nie piszą w opisie, a które doceni każdy, kto pilnuje rozmiaru obrazów i listy zależności.

Przeglądając strukturę projektu, natknąłem się na podwójne pliki: obok modułu każdego systemu leży jego wariant „wyłączony". Mechanizm okazał się prosty i elegancki — to znaczniki budowania, którymi można wyłączyć poszczególne sprawdzenia przy kompilacji. Wyłączasz obsługę Redisa, a wraz z nią z pliku wykonywalnego znika sterownik Redisa.

Ma to dwie konsekwencje, obie dobre. Pierwsza to rozmiar: obraz kontenera, który czeka wyłącznie na port i punkt kontrolny HTTP, nie musi nieść w sobie sterowników pięciu baz danych. Druga jest ciekawsza i dotyczy powierzchni zależności: mniej wkompilowanego kodu to mniej bibliotek podlegających przeglądowi bezpieczeństwa i mniej ostrzeżeń w skanerze.

Doceniam przy tym rozwiązanie szczegółu: przy wyłączonym sprawdzeniu polecenie nie znika, ale zgłasza, że funkcja została wyłączona. Różnica jest niebagatelna dla osoby diagnozującej problem — „nie znam takiego polecenia" prowadzi do szukania literówki, a „ta funkcja jest wyłączona" prowadzi wprost do przyczyny.

Także jako biblioteka

Na koniec możliwość, która rozszerza zastosowanie poza potoki: Wait4X jest publikowany także jako biblioteka Go, z osobnym pakietem dla każdego rodzaju sprawdzenia i osobnym mechanizmem czekania.

Znaczy to, że logikę czekania na gotowość można wstawić do własnego programu, zamiast wywoływać zewnętrzny plik wykonywalny. Przy narzędziu wdrożeniowym albo usłudze, która sama musi poczekać na zależności przed przyjęciem ruchu, jest to czystsze niż uruchamianie podprocesu — i pozwala korzystać z tych samych sprawdzeń, które przetestowano w narzędziu.

Pułapki w jednym miejscu

  • Uważaj na hasła w wierszu poleceń. Łańcuchy połączeń do baz zawierają dane uwierzytelniające, a te trafiają do listy procesów na maszynie i do logów potoku CI. Podawaj je przez zmienne środowiskowe albo mechanizm sekretów swojego systemu, nie wprost w skrypcie.
  • Otwarty port to nie gotowa usługa. Jeśli aplikacja zależy od migracji, czekaj na istnienie tabeli, a nie na port.
  • Tryb dowolnego polecenia nie używa powłoki. Potoki, przekierowania i łączenie poleceń nie zadziałają — opakuj je we własny skrypt.
  • Kod wyjścia 124 oznacza limit czasu, jedynka — inny błąd. Obsłuż je osobno, bo diagnozuje się je inaczej.
  • Sprawdzanie równoległe wymaga gotowości wszystkich podanych adresów. Jeden niedostępny zablokuje całość do wyczerpania limitu.
  • Domyślny odstęp między próbami to sekunda. Przy dziesiątkach usług i krótkim limicie warto go przemyśleć razem z wycofywaniem wykładniczym.
  • Wydania funkcjonalne wychodzą rzadko — między dwoma ostatnimi minęło dziesięć miesięcy. Przy narzędziu kompletnym to nie problem, ale nie licz na szybkie dodanie obsługi twojego systemu.
  • Okrojony plik wykonywalny trzeba zbudować samemu. Gotowe wydania zawierają wszystkie sprawdzenia.

Podsumowanie

Wait4X jest narzędziem, które zastępuje jedną linijkę wstydliwego kodu w twoim potoku — i robi to lepiej, niż ta linijka kiedykolwiek działała. Kto ma w CI usypianie na wszelki wypadek, odzyska minuty w każdym przebiegu i pozbędzie się jednej kategorii migających testów.

  • Jedenaście rodzajów sprawdzeń, od portu TCP po pracownika w Temporalu.
  • Sprawdzenia sięgające warstwy wyżej — istnienie tabeli, klucz w Redisie, ścieżka w JSON-ie, wartość rekordu DNS.
  • Kod wyjścia 124 przy limicie czasu, zgodnie z konwencją narzędzi systemowych.
  • Odwrócone sprawdzanie do sprzątania i restartów kroczących.
  • Znaczniki budowania pozwalające wyciąć nieużywane sprawdzenia razem z ich sterownikami.
  • Dostępność jako biblioteka Go, jeśli logika czekania ma trafić do twojego programu.
  • Siedem lat historii i obecność w pięciu menedżerach pakietów.

Licencja to Apache 2.0, czyli przy narzędziu wchodzącym do infrastruktury wybór wygodny. Wolno je używać komercyjnie, rozprowadzać z własnym produktem i modyfikować bez obowiązku otwierania własnego kodu, a dodatkowo licencja zawiera wyraźne udzielenie licencji patentowej przez współtwórców — czego licencje typu MIT nie mają. Obowiązki są dwa i łagodne: zachowanie informacji o prawach autorskich wraz z plikiem uzupełniającym oraz oznaczenie zmian, jeśli rozprowadzasz wersję zmodyfikowaną. To ostatnie warto zapamiętać właśnie w kontekście okrojonego pliku wykonywalnego: budowanie własnego wariantu na potrzeby wewnętrzne nie rodzi żadnych obowiązków, ale jeśli taki plik zaczniesz rozprowadzać dalej, zmianę trzeba oznaczyć.