Comment tester des filtres jq complexes dans le navigateur sans risquer de fuir des données de production

Combien de fois avez-vous dû assembler une longue expression jq à l'aveugle directement dans le terminal ? C'est une situation familière pour beaucoup : vous faites une requête API, vous obtenez un mur de texte de quelques milliers de lignes, puis vous appuyez répétitivement sur la flèche vers le haut dans la console, en ajoutant des pipes, des sélecteurs et des tranches. Fait une erreur dans un crochet — le terminal crache une erreur ou un tableau vide.

La première pensée dans une telle situation est d'ouvrir un formateur en ligne. Mais si vous travaillez avec des logs de production, des réponses de paiement ou des données personnelles d'utilisateurs, les coller dans un site aléatoire issu des résultats de recherche n'est pas une option.

L'équipe de développement de jq a résolu ce problème de manière native en publ

iant un bac à sable officiel appelé playground. Le code source est disponible sur GitHub sous licence MIT, et une version fonctionnelle est accessible à l'adresse play.jqlang.org.

Ce que c'est

Le projet est un shell web interactif pour travailler avec jq. Sur le côté gauche de l'écran, vous collez le JSON source ou vous l'importez via URL, vous écrivez le filtre en haut, et sur la droite, vous obtenez instantanément le résultat de la transformation.

La principale fonctionnalité se trouve sous le capot. Tout l'analyse et l'exécution des filtres se produisent localement sur votre machine. Le service n'envoie pas votre corps JSON à un serveur distant.

Cela a été rendu possible par le portage jq-wasm — le code C original de l'utilitaire a été compilé en WebAssembly. En conséquence, le navigateur effectue des transformations lourdes de manière indépendante, sans dépendances natives du côté du système d'exploitation.

Comment le bac à sable est utile en pratique

Contrairement à des dizaines de services anonymes d'origine douteuse, cet outil résout plusieurs tâches appliquées à la fois.

Premièrement, la confidentialité par défaut. Puisque le processeur s'exécute à l'intérieur de WebAssembly directement sur le client, vous pouvez safely charger des dumps de bases de données internes, des configurations d'infrastructure ou des dumps d'API vers le bac à sable. Les requêtes réseau ne se produisent que lorsque vous collez vous-même une URL externe pour charger du JSON.

Deuxièmement, le partage pratique de snippets. Quand vous avez besoin de montrer à un collègue comment analyser correctement une réponse tordue d'un service tiers, il suffit d'appuyer sur le bouton Partager. Le serveur enregistrera le code du filtre et générera un lien court. Le destinataire du lien verra les calculs s'exécuter localement dans son navigateur.

Troisièmement, une interface réactive. Grâce à l'absence de surcharge réseau pour l'envoi des données dans les deux sens, le résultat est recalculé à la volée au fur et à mesure que vous tapez le filtre. Pour déboguer des constructions complexes comme walk(), des descentes récursives ou des fonctions personnalisées, cela fait gagner beaucoup de temps.

Quatrièmement, le bac à sable peut être déployé dans votre propre périmètre. Si votre entreprise opère dans un segment fermé sans accès à Internet, le projet peut être facilement déployé localement ou sur un serveur d'équipe interne.

Ce qu'il y a à l'intérieur : architecture et pile technique

Le bac à sable est écrit en TypeScript en utilisant Next.js. La structure de l'application est extrêmement concise :

• Frontend en React avec un éditeur de code et une intégration jq-wasm.
• Base de données PostgreSQL, qui est nécessaire exclusivement pour stocker les snippets partagés.
• Point de terminaison API côté serveur (POST /api/jq) qui exécute les requêtes sur le backend via un pool de workers.

Un détail intéressant dans le code source : le pool de workers côté serveur pour /api/jq est étroitement couplé à la RAM disponible sur l'instance. Comme les instances WebAssembly dans Node.js sont gourmandes en mémoire, l'application calcule automatiquement la limite de threads en fonction de la quantité de RAM. Par exemple, sur une instance avec 512 Mo de mémoire, exactement 2 threads parallèles seront lancés, et la file d'attente maximale sera de 40 tâches.

Si nécessaire, ces paramètres peuvent être écrasés via des variables d'environnement :

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

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

Si la file d'attente déborde, l'API retourne honnêtement le statut HTTP 429 Too Many Requests, protégeant le service d'un crash dû à un Out of Memory.

Comment déployer le projet localement

Si vous ne voulez pas utiliser l'hébergement public ou avez besoin de votre propre instance dans un réseau d'entreprise, le démarrage ne prendra que quelques minutes.

Vous aurez besoin de Node.js version 14 ou supérieure et de Docker (pour la base de données).

Clonez le dépôt :

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

Le moyen le plus rapide pour le développement et les tests locaux est d'exécuter le Docker Compose prêt à l'emploi, qui lancera l'application ainsi qu'une instance PostgreSQL locale :

docker compose up

Après le démarrage, ouvrez votre navigateur à l'adresse http://localhost:3000.

Pour construire une version de production sans conteneurs, les commandes standard suffisent :

npm run build
npm run start

La seule variable d'environnement requise pour la production est DATABASE_URL avec la chaîne de connexion PostgreSQL. Si la fonctionnalité de génération de liens n'est pas nécessaire, les autres paramètres peuvent être laissés à leurs valeurs par défaut.

Qui trouvera cela utile

Le projet mérite d'être ajouté aux favoris pour quiconque traite fréquemment avec du code d'infrastructure, des logs dans Kubernetes, des pipelines CI/CD ou des API REST complexes.

Le bac à sable élimine le besoin d'écrire des scripts bash improvisés juste pour vérifier la syntaxe d'une seule ligne de filtre. Et la possibilité de déployer votre propre instance en deux commandes en fait un excellent candidat pour l'ajout à la boîte à outils interne d'une équipe de développement.