Как тестировать сложные фильтры jq в браузере без риска слить рабочие данные

Сколько раз вам приходилось собирать длинное jq-выражение вслепую прямо в терминале? Типичный сценарий знаком многим: делаем запрос к API, получаем полотно на пару тысяч строк, а потом раз за разом жмем стрелку вверх в консоли, дописывая пайпы, селекторы и срезы. Ошиблись в одной скобке — терминал выплевывает ошибку или пустой массив.

Первая мысль в такой ситуации — открыть какой-нибудь онлайн-форматтер. Но если вы работаете с боевыми логами, платежными ответами или персональными данными пользователей, вставлять их в случайный сайт из выдачи поисковика нельзя.

Команда разработчиков jq решила эту проблему нативно, выкатив официальную песочницу под названием playground. Исходники лежат на GitHub под лицензией MIT, а рабочая версия доступна на play.jqlang.org.

Что это такое

Проект представляет собой интерактивную веб-оболочку для работы с jq. В левой части экрана вы вставляете исходный JSON или подтягиваете его по URL, вверху пишете фильтр, а справа мгновенно получаете результат трансформации.

Главная фишка здесь кроется под капотом. Весь парсинг и выполнение фильтров происходят локально на вашей машине. Сервис не отправляет тело вашего JSON на удаленный сервер.

Это стало возможным благодаря порту jq-wasm — оригинальный C-код утилиты скомпилировали в WebAssembly. В итоге браузер выполняет тяжелые преобразования самостоятельно, без нативных зависимостей на стороне операционной системы.

Чем песочница полезна на практике

В отличие от десятков безымянных сервисов сомнительного происхождения, этот инструмент решает сразу несколько прикладных задач.

Во-первых, приватность по умолчанию. Поскольку обработчик работает внутри WebAssembly прямо на клиенте, в песочницу можно без опаски загружать выгрузки из внутренних баз, конфигурации инфраструктуры или дампы API. Запросы к сети происходят только тогда, когда вы сами вставляете внешний URL для загрузки JSON.

Во-вторых, удобный шаринг сниппетов. Когда нужно показать коллеге, как правильно распарсить кривой ответ стороннего сервиса, достаточно нажать кнопку Share. Сервер сохранит код фильтра и сгенерирует короткую ссылку. При этом у получателя ссылки вычисления снова запустятся локально в его браузере.

В-третьих, отзывчивый интерфейс. За счет отсутствия сетевого оверхенда на пересылку данных туда и обратно результат пересчитывается буквально на лету, пока вы печатаете фильтр. Для отладки хитрых конструкций вроде walk(), рекурсивных спусков или самописных функций это экономит кучу времени.

В-четвертых, песочницу можно развернуть у себя в контуре. Если ваша компания работает в закрытом сегменте без доступа в интернет, проект элементарно поднимается локально или на внутреннем сервере команды.

Что внутри: архитектура и стек

Песочница написана на TypeScript с использованием Next.js. Структура приложения предельно лаконична:

Фронтенд на React с редактором кода и интеграцией jq-wasm.
База данных PostgreSQL, которая нужна исключительно для хранения расшаренных сниппетов.
Серверный API-эндпоинт (POST /api/jq), который выполняет запросы на бэкенде через пул воркеров.

Интересная деталь в исходниках: серверный пул воркеров для /api/jq жестко привязан к доступной оперативной памяти инстанса. Поскольку инстансы WebAssembly в Node.js требовательны к памяти, приложение автоматически рассчитывает лимит потоков исходя из объема RAM. Например, на инстансе с 512 МБ памяти запустится ровно 2 параллельных потока, а максимальная очередь составит 40 задач.

При необходимости эти параметры можно переопределить через переменные окружения:

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

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

Если очередь переполняется, API честно отдает HTTP-статус 429 Too Many Requests, защищая сервис от падения по Out of Memory.

Как развернуть проект локально

Если вам не хочется использовать публичный хостинг или нужен собственный инстанс внутри корпоративной сети, запуск займет пару минут.

Для работы потребуется Node.js версии 14 или выше и Docker (для базы данных).

Клонируем репозиторий:

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

Самый быстрый способ для локальной разработки и тестов — запустить готовый Docker Compose, который поднимет приложение вместе с локальным инстансом PostgreSQL:

docker compose up

После старта открываем браузер по адресу http://localhost:3000.

Для сборки продакшн-версии без контейнеров достаточно стандартных команд:

npm run build
npm run start

Единственная обязательная переменная окружения для продакшна — это DATABASE_URL со строкой подключения к PostgreSQL. Если функционал генерации ссылок не нужен, остальные настройки можно оставить по умолчанию.

Кому пригодится

Проект стоит положить в закладки каждому, кто часто возится с инфраструктурным кодом, логами в Kubernetes, пайплайнами CI/CD или сложными REST API.

Песочница избавляет от необходимости писать костыльные bash-скрипты просто ради того, чтобы проверить синтаксис одной строчки фильтра. А возможность поднять собственный инстанс за две команды делает ее отличным кандидатом для добавления во внутренний инструментарий команды разработки.