Complexe jq-filters testen in de browser zonder risico op het lekken van productiegegevens

Hoe vaak heb je een lange jq-expressie blind in de terminal moeten samenstellen? Dit is een bekend scenario voor velen: je doet een API-verzoek, krijgt een muur van tekst van een paar duizend regels, en dan herhaaldelijk de pijl-omhoog indrukt in de console, waarbij je pipes, selectors en slices toevoegt. Een fout in één haakje gemaakt — de terminal spuugt een foutmelding uit of een lege array.

De eerste gedachte in zo'n situatie is om een online formatter te openen. Maar als je met productielogs, betalingsresponsen of persoonlijke gebruikersgegevens werkt, is het plakken ervan in een willekeurige site uit zoekresultaten geen optie.

Het jq-ontwikkelteam heeft dit probleem native opgelost door een officiële sandbox genaamd playground uit te brengen. De broncode is beschikbaar op GitHub onder de MIT-licentie, en een werkende versie is toegankelijk op play.jqlang.org.

Wat het is

Het project is een interactieve web-shell voor het werken met jq. Aan de linkerkant van het scherm plak je de bron-JSON of haal je het op via URL, je schrijft de filter bovenaan, en aan de rechterkant krijg je direct het transformatieresultaat.

Het belangrijkste kenmerk zit onder de motorkap. Alle parsing en filteruitvoering vinden lokaal plaats op je machine. De service stuurt je JSON-body niet naar een externe server.

Dit werd mogelijk gemaakt door de jq-wasm-port — de originele C-code van het hulpprogramma werd gecompileerd naar WebAssembly. Als gevolg daarvan voert de browser zware transformaties zelfstandig uit, zonder native afhankelijkheden aan de besturingssysteemkant.

Hoe de sandbox in de praktijk nuttig is

In tegenstelling tot tientallen naamloze diensten van twijfelachtige oorsprong, lost dit hulpmiddel tegelijkertijd verschillende praktische taken op.

Ten eerste, privacy standaard. Omdat de processor binnen WebAssembly direct op de client draait, kun je veilig dumps van interne databases, infrastructuurconfiguraties of API-dumps naar de sandbox uploaden. Netwerkverzoeken vinden alleen plaats wanneer je zelf een externe URL plakt om JSON te laden.

Ten tweede, handig snippet delen. Wanneer je een collega moet laten zien hoe je een kromme respons van een externe dienst correct kunt parsen, druk je gewoon op de Share-knop. De server slaat de filtercode op en genereert een kort linkje. De ontvanger van de link zal de berekeningen opnieuw lokaal in hun browser uitvoeren.

Ten derde, een responsieve interface. Dankzij de afwezigheid van netwerkoverhead voor het heen en weer sturen van gegevens, wordt het resultaat direct herberekend terwijl je de filter typt. Voor het debuggen van lastige constructies zoals walk(), recursieve afdalingen of aangepaste functies bespaart dit veel tijd.

Ten vierde kan de sandbox binnen je eigen perimeter worden ingezet. Als je bedrijf in een gesloten segment zonder internettoegang opereert, kan het project eenvoudig lokaal of op een interne teamsserver worden opgezet.

Wat er binnen zit: architectuur en stack

De sandbox is geschreven in TypeScript met Next.js. De applicatiestructuur is uiterst beknopt:

• Frontend op React met een code-editor en jq-wasm-integratie.
• PostgreSQL-database, die uitsluitend nodig is voor het opslaan van gedeelde snippets.
• Server-side API-endpoint (POST /api/jq) dat verzoeken op de backend uitvoert via een worker pool.

Een interessant detail in de broncode: de server-side worker pool voor /api/jq is nauw gekoppeld aan beschikbaar RAM op de instantie. Omdat WebAssembly-instanties in Node.js geheugenintensief zijn, berekent de applicatie automatisch de thread-limiet op basis van de hoeveelheid RAM. Op een instantie met 512 MB geheugen worden bijvoorbeeld precies 2 parallelle threads gestart, met een maximale queue van 40 taken.

Indien nodig kunnen deze parameters worden overschreven via omgevingsvariabelen:

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

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

Als de queue overloopt, retourneert de API eerlijk HTTP-status 429 Too Many Requests, waardoor de service wordt beschermd tegen crashen door Out of Memory.

Hoe het project lokaal te deployen

Als je geen gebruik wilt maken van publieke hosting of een eigen instantie binnen een bedrijfsnetwerk nodig hebt, duurt de opstart een paar minuten.

Je hebt Node.js versie 14 of hoger en Docker (voor de database) nodig.

Clone de repository:

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

De snelste manier voor lokale ontwikkeling en testing is om de kant-en-klare Docker Compose uit te voeren, die de applicatie samen met een lokale PostgreSQL-instantie opstart:

docker compose up

Na het opstarten open je je browser op http://localhost:3000.

Om een productieversie zonder containers te bouwen, volstaan standaard commando's:

npm run build
npm run start

De enige vereiste omgevingsvariabele voor productie is DATABASE_URL met de PostgreSQL-verbindingsstring. Als de linkgeneratiefunctionaliteit niet nodig is, kunnen de andere instellingen op hun standaardwaarden blijven.

Wie zal het nuttig vinden

Het project is het bookmarken waard voor iedereen die regelmatig te maken heeft met infrastructuurcode, logs in Kubernetes, CI/CD-pipelines of complexe REST API's.

De sandbox elimineert de noodzaak om improviserende bash-scripts te schrijven om alleen de syntaxis van één filterregel te controleren. En de mogelijkheid om je eigen instantie op te zetten met twee commando's maakt het een uitstekende kandidaat voor toevoeging aan de interne gereedschapskist van een ontwikkelteam.