Jak testować złożone filtry jq w przeglądarce bez ryzyka wycieku danych produkcyjnych

Ile razy musiałeś składać długie wyrażenie jq w ciemno bezpośrednio w terminalu? To znajoma sytuacja dla wielu: wykonujesz żądanie API, otrzymujesz ścianę tekstu liczącą kilka tysięcy linii, a potem wielokrotnie naciskasz strzałkę w górę w konsoli, dodając pipes, selektory i slice. Pomyliłeś się w jednym nawiasie — terminal zwraca błąd lub pustą tablicę.

Pierwszą myślą w takiej sytuacji jest otwarcie jakiegoś online formattera. Ale jeśli pracujesz z logami produkcyjnymi, odpowiedziami płatności lub danymi osobowymi użytkowników, wklejanie ich do losowej strony z wyników wyszukiwania nie wchodzi w grę.

Zespół jq rozwiązał ten problem natywnie, wydając oficjalną piaskownicę zwaną playground. Kod źródłowy jest dostępny na GitHubie na licencji MIT, a działającą wersję można znaleźć pod adresem play.jqlang.org.

Co to jest

Projekt to interaktywna powłoka webowa do pracy z jq. Po lewej stronie ekranu wklejasz źródłowy JSON lub pobierasz go przez URL, filtr piszesz na górze, a po prawej stronie natychmiast otrzymujesz wynik transformacji.

Główna cecha tkwi pod maską. Całe parsowanie i wykonywanie filtrów odbywa się lokalnie na Twojej maszynie. Serwis nie wysyła Twojego body JSON na zdalny serwer.

Umożliwiło to przeniesienie do jq-wasm — oryginalny kod C narzędzia został skompilowany do WebAssembly. W rezultacie przeglądarka wykonuje ciężkie transformacje samodzielnie, bez natywnych zależności od strony systemu operacyjnego.

Czym piaskownica jest przydatna w praktyce

W przeciwieństwie do dziesiątek bezimiennych serwisów wątpliwego pochodzenia, to narzędzie rozwiązuje jednocześnie kilka zastosowań.

Po pierwsze, prywatność domyślnie. Ponieważ procesor działa wewnątrz WebAssembly bezpośrednio na kliencie, możesz bezpiecznie uploadować dumpy z wewnętrznych baz danych, konfiguracji infrastruktury lub dumpów API do piaskownicy. Żądania sieciowe zachodzą tylko wtedy, gdy samodzielnie wklejasz zewnętrzny URL, aby załadować JSON.

Po drugie, wygodne udostępnianie snippetów. Kiedy musisz pokazać koledze, jak poprawnie parsować krzywą odpowiedź od zewnętrznego serwisu, wystarczy nacisnąć przycisk Share. Serwer zapisze kod filtru i wygeneruje krótki link. Odbiorca linku ponownie będzie miał wyliczenia uruchomione lokalnie w swojej przeglądarce.

Po trzecie, responsywny interfejs. Dzięki brakowi narzutu sieciowego na wysyłanie danych tam i z powrotem, wynik jest przeliczany w locie podczas pisania filtru. Dla debugowania złożonych konstrukcji jak walk(), rekursywnych zejść czy funkcji niestandardowych, oszczędza to mnóstwo czasu.

Po czwarte, piaskownica może być wdrożona we własnym perymetrze. Jeśli Twoja firma działa w zamkniętym segmencie bez dostępu do internetu, projekt można łatwo uruchomić lokalnie lub na wewnętrznym serwerze zespołu.

Co w środku: architektura i stos technologiczny

Piaskownica jest napisana w TypeScript z użyciem Next.js. Struktura aplikacji jest niezwykle zwięzła:

• Frontend na React z edytorem kodu i integracją z jq-wasm.
• Baza danych PostgreSQL, potrzebna wyłącznie do przechowywania udostępnionych snippetów.
• Endpoint API po stronie serwera (POST /api/jq), który wykonuje żądania na backendzie przez pulę workerów.

Interesujący szczegół w kodzie źródłowym: puli workerów po stronie serwera dla /api/jq jest ściśle powiązana z dostępną pamięcią RAM na instancji. Ponieważ instancje WebAssembly w Node.js są pamięciochłonne, aplikacja automatycznie oblicza limit wątków na podstawie ilości RAM. Na przykład na instancji z 512 MB pamięci zostanie uruchomionych dokładnie 2 równoległe wątki, a maksymalna kolejka będzie wynosić 40 zadań.

W razie potrzeby parametry te można nadpisać za pomocą zmiennych środowiskowych:

# Максимальное число параллельных потоков jq
JQ_POOL_MAX_THREADS=4

# Максимальный размер очереди запросов
JQ_POOL_MAX_QUEUE=80

Jeśli kolejka się przepełni, API uczciwie zwraca status HTTP 429 Too Many Requests, chroniąc serwis przed awarią z powodu Out of Memory.

Jak wdrożyć projekt lokalnie

Jeśli nie chcesz korzystać z publicznego hostingu lub potrzebujesz własnej instancji w zamkniętej sieci korporacyjnej, uruchomienie zajmie tylko kilka minut.

Będziesz potrzebować Node.js w wersji 14 lub wyższej oraz Dockera (dla bazy danych).

Sklonuj repozytorium:

git clone https://github.com/jqlang/playground
cd playground

Najszybszy sposób na lokalny rozwój i testowanie to uruchomienie gotowego Docker Compose, które włączy aplikację wraz z lokalną instancją PostgreSQL:

docker compose up

Po uruchomieniu otwórz przeglądarkę pod adresem http://localhost:3000.

Aby zbudować wersję produkcyjną bez kontenerów, wystarczą standardowe polecenia:

npm run build
npm run start

Jedyną wymaganą zmienną środowiskową dla produkcji jest DATABASE_URL z ciągiem połączenia do PostgreSQL. Jeśli funkcja generowania linków nie jest potrzebna, pozostałe ustawienia można pozostawić domyślne.

Kto znajdzie to przydatne

Projekt warto dodać do zakładek każdemu, kto często zajmuje się kodem infrastruktury, logami w Kubernetes, potokami CI/CD czy złożonymi REST API.

Piaskownica eliminuje potrzebę pisania doraźnych skryptów bash tylko po to, aby sprawdzić składnię jednej linijki filtru. A możliwość uruchomienia własnej instancji w dwóch poleceniach czyni z niej doskonałego kandydata do dodania do wewnętrznego zestawu narzędzi zespołu deweloperskiego.