Come testare filtri jq complessi nel browser senza rischiare di perdere dati di produzione

Quante volte hai dovuto assemblare un'espressione jq lunga alla cieca direttamente nel terminale? Questo è uno scenario familiare per molti: fai una richiesta API, ottieni una parete di testo di un paio di migliaia di righe, e poi premi ripetutamente la freccia su nella console, aggiungendo pipe, selettori e slice. Hai sbagliato una parentesi — il terminale sputa fuori un errore o un array vuoto.

Il primo pensiero in una situazione del genere è aprire qualche formattatore online. Ma se stai lavorando con log di produzione, risposte di pagamento o dati personali degli utenti, incollarli in un sito casuale dai risultati di ricerca non è un'opzione.

Il team di sviluppo di jq ha risolto questo problema in modo nativo rilasciando un sandbox ufficiale chiamato playground. Il codice sorgente è disponibile su GitHub sotto licenza MIT, e una versione funzionante è accessibile su play.jqlang.org.

Cos'è

Il progetto è una shell web interattiva per lavorare con jq. Sul lato sinistro dello schermo incolli il JSON sorgente o lo carichi tramite URL, scrivi il filtro in alto, e sulla destra ottieni istantaneamente il risultato della trasformazione.

La caratteristica principale è sotto il cofano. Tutta la parsing e l'esecuzione dei filtri avvengono localmente sulla tua macchina. Il servizio non invia il tuo corpo JSON a un server remoto.

Questo è stato reso possibile dalla porta in jq-wasm — il codice C originale dell'utility è stato compilato in WebAssembly. Di conseguenza, il browser esegue trasformazioni pesanti in modo indipendente, senza dipendenze native dal lato del sistema operativo.

Come il sandbox è utile in pratica

A differenza di decine di servizi senza nome di dubbia origine, questo strumento risolve diversi compiti applicati contemporaneamente.

Prima di tutto, privacy di default. Poiché il processore gira all'interno di WebAssembly direttamente sul client, puoi caricare in sicurezza dump da database interni, configurazioni di infrastruttura o dump di API nel sandbox. Le richieste di rete avvengono solo quando incolli tu stesso un URL esterno per caricare JSON.

Secondo, condivisione comoda di snippet. Quando devi mostrare a un collega come parsare correttamente una risposta complicata da un servizio di terze parti, basta premere il pulsante Share. Il server salverà il codice del filtro e genererà un link breve. Il destinatario del link avrà i calcoli eseguiti nuovamente in locale nel suo browser.

Terzo, un'interfaccia reattiva. Grazie all'assenza di overhead di rete per l'invio dei dati avanti e indietro, il risultato viene ricalcolato al volo mentre digiti il filtro. Per il debug di costrutti complessi come walk(), discese ricorsive o funzioni personalizzate, questo fa risparmiare molto tempo.

Quarto, il sandbox può essere distribuito all'interno del tuo perimetro. Se la tua azienda opera in un segmento chiuso senza accesso a internet, il progetto può essere facilmente avviato localmente o su un server team interno.

Cosa c'è dentro: architettura e stack

Il sandbox è scritto in TypeScript usando Next.js. La struttura dell'applicazione è estremamente concisa:

• Frontend su React con un editor di codice e integrazione jq-wasm.
• Database PostgreSQL, necessario esclusivamente per memorizzare gli snippet condivisi.
• Endpoint API lato server (POST /api/jq) che esegue le richieste sul backend attraverso un pool di worker.

Un dettaglio interessante nel codice sorgente: il pool di worker lato server per /api/jq è strettamente accoppiato alla RAM disponibile sull'istanza. Poiché le istanze WebAssembly in Node.js sono pesanti in termini di memoria, l'applicazione calcola automaticamente il limite di thread in base alla quantità di RAM. Ad esempio, su un'istanza con 512 MB di memoria, verranno avviati esattamente 2 thread paralleli, e la coda massima sarà di 40 task.

Se necessario, questi parametri possono essere sovrascritti tramite variabili d'ambiente:

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

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

Se la coda si riempie, l'API restituisce onestamente lo stato HTTP 429 Too Many Requests, proteggendo il servizio da crash dovuti a Out of Memory.

Come distribuire il progetto localmente

Se non vuoi usare hosting pubblico o hai bisogno di un'istanza tua all'interno di una rete aziendale, l'avvio richiederà un paio di minuti.

Avrai bisogno di Node.js versione 14 o superiore e Docker (per il database).

Clona il repository:

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

Il modo più veloce per lo sviluppo locale e il testing è eseguire il Docker Compose già pronto, che avvierà l'applicazione insieme a un'istanza PostgreSQL locale:

docker compose up

Dopo l'avvio, apri il browser su http://localhost:3000.

Per buildare una versione di produzione senza container, sono sufficienti i comandi standard:

npm run build
npm run start

L'unica variabile d'ambiente richiesta per la produzione è DATABASE_URL con la stringa di connessione PostgreSQL. Se la funzionalità di generazione link non è necessaria, le altre impostazioni possono essere lasciate ai valori predefiniti.

A chi tornerà utile

Il progetto vale la pena di essere aggiunto ai preferiti per chiunque si occupi frequentemente di codice infrastrutturale, log in Kubernetes, pipeline CI/CD o API REST complesse.

Il sandbox elimina la necessità di scrivere script bash improvvisati solo per controllare la sintassi di una singola riga di filtro. E la possibilità di avviare la tua istanza in due comandi lo rende un candidato eccellente per l'aggiunta al toolkit interno di un team di sviluppo.