So testen Sie komplexe jq-Filter im Browser, ohne Produktionsdaten zu gefährden

Wie oft mussten Sie schon einen langen jq-Ausdruck blind im Terminal zusammenbauen? Das kennen viele: Sie stellen eine API-Anfrage, erhalten einen Textblock von ein paar tausend Zeilen und drücken dann wiederholt die Pfeiltaste nach oben in der Konsole, fügen Pipes, Selektoren und Slices hinzu. Ein Fehler in einer Klammer – das Terminal spuckt einen Fehler oder ein leeres Array aus.

Der erste Gedanke in einer solchen Situation ist, einen Online-Formatter zu öffnen. Aber wenn Sie mit Produktions-Logs, Zahlungsantworten oder persönlichen Benutzerdaten arbeiten, ist es keine Option, diese in eine beliebige Website aus den Suchergebnissen einzufügen.

Das jq-Entwicklungsteam hat dieses Problem nativ gelöst, indem es eine offizielle Sandbox namens Playground veröffentlicht hat. Der Quellcode ist auf GitHub unter der MIT-Lizenz verfügbar, und eine funktionierende Version ist unter play.jqlang.org erreichbar.

Was es ist

Das Projekt ist eine interaktive Web-Shell für die Arbeit mit jq. Auf der linken Seite des Bildschirms fügen Sie den Quell-JSON ein oder laden ihn via URL, Sie schreiben den Filter oben, und auf der rechten Seite erhalten Sie sofort das Transformationsergebnis.

Die Hauptfunktion liegt unter der Haube. Alle Parsing- und Filterausführungen finden lokal auf Ihrem Rechner statt. Der Dienst sendet Ihren JSON-Body nicht an einen Remote-Server.

Dies wurde durch den jq-wasm-Port ermöglicht – der ursprüngliche C-Code des Tools wurde nach WebAssembly kompiliert. Dadurch führt der Browser schwere Transformationen eigenständig durch, ohne native Abhängigkeiten vom Betriebssystem.

Wie die Sandbox in der Praxis nützlich ist

Im Gegensatz zu Dutzenden namenloser Dienste zweifelhafter Herkunft löst dieses Tool mehrere praktische Aufgaben gleichzeitig.

Erstens: Privacy by Default. Da der Prozessor innerhalb von WebAssembly direkt auf dem Client läuft, können Sie sicher Dumps aus internen Datenbanken, Infrastrukturkonfigurationen oder API-Dumps in die Sandbox hochladen. Netzwerkanfragen erfolgen nur, wenn Sie selbst eine externe URL einfügen, um JSON zu laden.

Zweitens: Bequemes Teilen von Snippets. Wenn Sie einem Kollegen zeigen müssen, wie man eine schief formatierte Antwort eines Drittanbieter-Dienstes korrekt parst, drücken Sie einfach die Share-Schaltfläche. Der Server speichert den Filtercode und generiert einen Kurzlink. Der Empfänger des Links führt die Berechnungen wieder lokal in seinem Browser durch.

Drittens: Responsive Oberfläche. Dank des fehlenden Netzwerk-Overheads für das Hin- und Herschicken von Daten wird das Ergebnis beim Tippen des Filters live neu berechnet. Für das Debuggen kniffliger Konstrukte wie walk(), rekursiver Abstiege oder benutzerdefinierter Funktionen spart das viel Zeit.

Viertens: Die Sandbox kann in Ihrem eigenen Perimeter bereitgestellt werden. Wenn Ihr Unternehmen in einem geschlossenen Segment ohne Internetzugang arbeitet, kann das Projekt einfach lokal oder auf einem internen Team-Server aufgesetzt werden.

Was drin steckt: Architektur und Stack

Die Sandbox ist in TypeScript unter Verwendung von Next.js geschrieben. Die Anwendungsstruktur ist extrem kompakt:

• Frontend auf React mit einem Code-Editor und jq-wasm-Integration.
• PostgreSQL-Datenbank, die ausschließlich zum Speichern geteilter Snippets benötigt wird.
• Serverseitiger API-Endpunkt (POST /api/jq), der Anfragen über einen Worker-Pool auf dem Backend ausführt.

Ein interessantes Detail im Quellcode: Der serverseitige Worker-Pool für /api/jq ist eng an den verfügbaren RAM der Instanz gekoppelt. Da WebAssembly-Instanzen in Node.js speicherintensiv sind, berechnet die Anwendung automatisch das Thread-Limit basierend auf der RAM-Menge. Auf einer Instanz mit 512 MB Speicher werden beispielsweise genau 2 parallele Threads gestartet, und die maximale Warteschlange beträgt 40 Aufgaben.

Bei Bedarf können diese Parameter über Umgebungsvariablen überschrieben werden:

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

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

Wenn die Warteschlange überläuft, gibt die API ehrlich den HTTP-Status 429 Too Many Requests zurück und schützt den Dienst vor Abstürzen durch Out of Memory.

So deployen Sie das Projekt lokal

Wenn Sie keinen öffentlichen Hosting nutzen möchten oder eine eigene Instanz innerhalb eines Unternehmensnetzwerks benötigen, dauert der Start ein paar Minuten.

Sie benötigen Node.js Version 14 oder höher und Docker (für die Datenbank).

Klonen Sie das Repository:

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

Der schnellste Weg für lokale Entwicklung und Tests ist das Ausführen des fertigen Docker Compose, das die Anwendung zusammen mit einer lokalen PostgreSQL-Instanz hochfährt:

docker compose up

Nach dem Start öffnen Sie Ihren Browser unter http://localhost:3000.

Um eine Produktionsversion ohne Container zu erstellen, reichen Standardbefehle aus:

npm run build
npm run start

Die einzige erforderliche Umgebungsvariable für die Produktion ist DATABASE_URL mit der PostgreSQL-Verbindungszeichenfolge. Wenn die Link-Generierungsfunktion nicht benötigt wird, können die anderen Einstellungen auf ihren Standardwerten belassen werden.

Für wen ist es nützlich

Das Projekt lohnt sich als Lesezeichen für jeden, der häufig mit Infrastrukturcode, Logs in Kubernetes, CI/CD-Pipelines oder komplexen REST-APIs zu tun hat.

Die Sandbox eliminiert die Notwendigkeit, behelfsmäßige Bash-Skripte zu schreiben, nur um die Syntax einer einzelnen Filterzeile zu überprüfen. Und die Möglichkeit, Ihre eigene Instanz in zwei Befehlen aufzusetzen, macht sie zu einem ausgezeichneten Kandidaten für die interne Tool-Sammlung eines Entwicklungsteams.