Como testar filtros jq complexos no navegador sem arriscar vazar dados de produção

Quantas vezes você teve que montar uma expressão jq longa às cegas diretamente no terminal? Este é um cenário familiar para muitos: você faz uma requisição à API, recebe uma parede de texto com alguns milhares de linhas, e então pressiona repetidamente a seta para cima no console, adicionando pipes, seletores e slices. Cometeu um erro em um colchete — o terminal cospe um erro ou um array vazio.

O primeiro pensamento em tal situação é abrir algum formatador online. Mas se você está trabalhando com logs de produção, respostas de pagamento ou dados pessoais de usuários, colá-los em um site aleatório dos resultados de busca não é uma opção.

A equipe de desenvolvimento do jq resolveu esse problema nativamente lançando um sandbox oficial chamado playground. O código-fonte está disponível no GitHub sob a licença MIT, e uma versão funcional está acessível em play.jqlang.org.

O que é

O projeto é um shell web interativo para trabalhar com jq. No lado esquerdo da tela você cola o JSON fonte ou puxa via URL, você escreve o filtro no topo, e na direita você obtém instantaneamente o resultado da transformação.

A principal característica aqui está sob o capô. Todo o parsing e execução de filtros acontecem localmente na sua máquina. O serviço não envia seu corpo JSON para um servidor remoto.

Isso foi possível graças à porta jq-wasm — o código C original do utilitário foi compilado para WebAssembly. Como resultado, o navegador executa transformações pesadas de forma independente, sem dependências nativas do lado do sistema operacional.

Como o sandbox é útil na prática

Ao contrário de dezenas de serviços sem nome de origem duvidosa, esta ferramenta resolve várias tarefas aplicadas de uma vez.

Primeiro, privacidade por padrão. Como o processador roda dentro do WebAssembly diretamente no cliente, você pode fazer upload seguro de dumps de bancos de dados internos, configurações de infraestrutura ou dumps de API para o sandbox. Requisições de rede só acontecem quando você mesmo cola uma URL externa para carregar JSON.

Segundo, compartilhamento conveniente de snippets. Quando você precisa mostrar a um colega como analisar corretamente uma resposta torta de um serviço de terceiros, basta pressionar o botão Share. O servidor salvará o código do filtro e gerará um link curto. O destinatário do link terá os cálculos executados localmente no navegador dele novamente.

Terceiro, uma interface responsiva. Graças à ausência de overhead de rede para enviar dados de um lado para outro, o resultado é recalculado em tempo real conforme você digita o filtro. Para depurar construções complicadas como walk(), descidas recursivas ou funções personalizadas, isso economiza muito tempo.

Quarto, o sandbox pode ser implantado dentro do seu próprio perímetro. Se sua empresa opera em um segmento fechado sem acesso à internet, o projeto pode ser facilmente iniciado localmente ou em um servidor interno da equipe.

Por dentro: arquitetura e stack

O sandbox é escrito em TypeScript usando Next.js. A estrutura da aplicação é extremamente concisa:

• Frontend em React com um editor de código e integração com jq-wasm.
• Banco de dados PostgreSQL, que é necessário exclusivamente para armazenar snippets compartilhados.
• Endpoint de API do lado do servidor (POST /api/jq) que executa requisições no backend através de um pool de workers.

Um detalhe interessante no código-fonte: o pool de workers do lado do servidor para /api/jq é fortemente acoplado à RAM disponível na instância. Como instâncias WebAssembly em Node.js são intensivas em memória, a aplicação calcula automaticamente o limite de threads baseado na quantidade de RAM. Por exemplo, em uma instância com 512 MB de memória, exatamente 2 threads paralelas serão iniciadas, e a fila máxima será de 40 tarefas.

Se necessário, esses parâmetros podem ser sobrescritos via variáveis de ambiente:

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

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

Se a fila transbordar, a API retorna honestamente o status HTTP 429 Too Many Requests, protegendo o serviço de crash devido a Out of Memory.

Como fazer deploy do projeto localmente

Se você não quer usar hospedagem pública ou precisa da sua própria instância dentro de uma rede corporativa, a inicialização levará alguns minutos.

Você vai precisar do Node.js versão 14 ou superior e Docker (para o banco de dados).

Clone o repositório:

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

A forma mais rápida para desenvolvimento local e testes é executar o Docker Compose pronto, que vai iniciar a aplicação junto com uma instância PostgreSQL local:

docker compose up

Após a inicialização, abra seu navegador em http://localhost:3000.

Para construir uma versão de produção sem containers, comandos padrão são suficientes:

npm run build
npm run start

A única variável de ambiente necessária para produção é DATABASE_URL com a string de conexão do PostgreSQL. Se a funcionalidade de geração de link não for necessária, as outras configurações podem ser deixadas em seus padrões.

Para quem é útil

O projeto vale a pena favoritar para qualquer pessoa que lida frequentemente com código de infraestrutura, logs no Kubernetes, pipelines de CI/CD ou APIs REST complexas.

O sandbox elimina a necessidade de escrever scripts bash improvisados só para verificar a sintaxe de uma única linha de filtro. E a capacidade de iniciar sua própria instância em dois comandos o torna um excelente candidato para adicionar ao toolkit interno de uma equipe de desenvolvimento.