Основные понятия

На этой странице объясняются идеи, на которых построен Signal Lab, чтобы остальная документация читалась легко. Каждый раздел ссылается на страницу, где его тема разобрана полностью.

Экраны и эксперименты

В Signal Lab два способа работы, и пользоваться вы будете обоими.

• Экраны — инструменты для работы, которую вы делаете прямо сейчас, руками: отправить это сообщение, слушать тот порт, запустить этот эмулятор, посмотреть, что держит брокер. Вы пробуете, смотрите, что-то меняете и пробуете снова. У каждого протокола и инструмента есть свой экран; см. Окно.
• Эксперименты — сценарии, которые вы собираете один раз и запускаете снова, каждый раз одинаково: отправить запрос, дождаться ответа, проверить его, идти дальше или свернуть в другую ветку. Каждый запуск отражается в отчёте шаг за шагом и сохраняется. См. Эксперименты.

Они пересекаются в нескольких местах. На экранах HTTP и OSC кнопка В эксперимент превращает только что отправленное в следующий шаг эксперимента. В мониторе OSC и на экране MQTT кнопка Ждать это превращает полученное сообщение в шаг, который его ждёт. А сигнал из библиотеки тоже может стать шагом — любой, кроме «сырых» байтов UDP, записанных шестнадцатеричным кодом.

Сигналы и библиотека

Сигнал — это сообщение, которое вы храните: имя, папка, заметка о том, что оно должно вызвать, и то, что оно отправляет, — OSC-сообщение, «сырые» байты UDP, HTTP-запрос или публикацию MQTT. Библиотека сигналов держит их в папках, которые можно вкладывать друг в друга, переименовывать и перетаскивать.

• Сигнал сохраняют на экранах OSC, HTTP и MQTT (Сохранить…), создают на экране Сигналы или сохраняют кадр, пойманный Инспектором (Сохранить как сигнал), — тогда сигнал воспроизводит его байт в байт.
• Его отправляют с экрана Сигналы, из любого места по Ctrl+K, шагом эксперимента или командой signallab fire в терминале.
• Сигнал отправляет ровно то же, что отправил бы его экран: те же байты, тем же путём; в Инспекторе он виден под своим настоящим протоколом.

Библиотека — один файл, signals.json, в папке данных: обычный JSON, который можно читать, править, копировать на другую машину или хранить в репозитории. Вначале в ней лежит набор примеров, все они направлены на 127.0.0.1. См. Сигналы.

Задачи

Задача — всё, что продолжает работать после нажатия кнопки: монитор или генератор OSC, подключение к брокеру или по WebSocket, маяк или приёмник обнаружения, нагрузочный поток HTTP, эмулятор, реле помех, шторм, сканирование, запуск эксперимента.

• У каждой задачи есть плашка в полосе нижней панели: с номером, названием и кнопкой остановки. Боковая панель показывает, сколько задач работает на каждом экране.
• Кнопка Остановить всё в шапке останавливает все задачи сразу.
• Задача, которая закончилась сама — завершившееся сканирование, пройденный запуск, монитор, у которого не открылся порт, — убирает свою плашку, а консоль сообщает, чем всё кончилось.
• Задача продолжает работать, пока вы занимаетесь другими экранами.
• Перед установкой обновления все задачи останавливаются.

На сервере задачи принадлежат серверу: каждая страница, вошедшая на него, видит те же задачи и может их остановить.

Захват и Инспектор

Каждый инструмент — отправители, мониторы, слушатели, эмуляторы, реле, запуски экспериментов — передаёт каждый отправленный или полученный кадр в единый захват, а Инспектор показывает его на одной ленте.

• Захват выключен, пока вы его не включите кнопкой Включить захват, и пока он выключен, ничего не стоит. Включённый, он работает на любом экране, пока вы его не выключите.
• Он хранит до 8192 кадров и 64 МиБ их байтов; самые старые кадры уступают место новым. Каждый кадр хранит до 256 КиБ своих байтов, а список показывает первый КиБ.
• Кнопка Пауза останавливает движение списка, чтобы его можно было прочитать; захват при этом продолжается.
• Значения секретов, которыми пользуется запуск, маскируются в каждом кадре.
• Весь захват можно выгрузить со всеми байтами в файл .jsonl или .txt.

Эмуляторы

Эмулятор играет другую сторону: API, устройство или сервис, с которыми разговаривает ваша система. Каждый эмулятор — документ с протоколом, адресом, на котором он слушает, и правилами, что отвечать:

Протокол	Что он эмулирует
HTTP	API: маршруты по методу и пути, ответы последовательностью, по кругу или случайно, с задержками и сбоями
OSC	Устройство, которое отвечает на OSC-сообщения по адресу и аргументам
UDP	Устройство, которое отвечает на датаграммы по их содержимому
TCP	Устройство, которое отвечает на строки в TCP-соединении, с приветствием
MQTT	Брокер, который маршрутизирует то, что публикуют клиенты, и отвечает по правилам, как устройство

Эмулятор может отвечать медленно, отказывать, закрывать соединение, присылать некорректное тело или уходить в отключение по расписанию. Каждый обмен подсчитывается, выводится на его экране и попадает в захват для Инспектора.

Эмулятор запускают на экране Эмуляторы, где он работает как задача; узлом Эмулятор эксперимента, где он отвечает на протяжении всего запуска; или командой signallab emulate. Библиотека эмуляторов — это emulators.json в папке данных. Вначале в ней по одному эмулятору каждого вида, все на 127.0.0.1:

Эмулятор	Слушает на	Что делает
Демо API	127.0.0.1:8080 (HTTP)	Проверка работоспособности, пользователь по id, создание, медленный ответ и маршрут, который дважды отказывает, а потом работает
Демо OSC-устройство	127.0.0.1:9100 (OSC)	Отвечает на /ping сообщением /pong со счётчиком, на /fader/… подтверждает /ack, /cue/… принимает молча
Демо UDP-устройство	127.0.0.1:7100 (UDP)	На PING отвечает PONG и счётчиком, на всё остальное — числом полученных байтов
Демо TCP-устройство	127.0.0.1:7200 (TCP)	Строковый протокол, как у проектора: приветствует READY, сообщает и переключает питание, на QUIT говорит BYE и разрывает соединение
Демо MQTT-брокер	127.0.0.1:1883 (MQTT)	Retained-сообщение lab/status и лампа: ON или OFF, опубликованные в lab/<name>/set, подтверждаются в lab/<name>/state

См. Эмуляторы.

Реле помех

Реле помех стоит между клиентом и его целью. Вы направляете клиента на адрес, который реле слушает, вместо настоящей цели; реле пересылает трафик в обе стороны и ухудшает то, что через него проходит, по профилю:

• по UDP у каждой датаграммы своя судьба: задержка и джиттер, потери и пачки потерь, дублирование, искажение, перестановка, ограничение полосы или ничего вообще (нет связи);
• по TCP каждое соединение связывается с собственным соединением к цели, и оба потока задерживаются, ограничиваются по полосе, сбрасываются или остаются полуоткрытыми.

Пресеты задают профиль одним щелчком — от кабеля до спутниковой связи. Изменение применяется, пока реле работает, и порт при этом не освобождается. Каждое решение берётся из seed, поэтому тот же трафик снова встречает ту же судьбу.

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

Эксперименты

Узлы и связи

Эксперимент — это граф из узлов, соединённых связями. Каждый узел — один шаг: он что-то отправляет, чего-то ждёт, проверяет значение, извлекает его, меняет ход выполнения или настраивает запуск — эмулятор, реле помех. В каждом эксперименте ровно один узел Старт и один Финиш, а всего их до 64. Эксперимент, открытый в редакторе, сохраняется по мере правки. См. Узлы.

Выходы

Связь идёт от выхода одного узла ко входу другого. У большинства узлов один выход; другие выбирают из нескольких: Да и Нет у ветвления, Получено и Таймаут у ожидания, Тело, Готово и Лимит у цикла, Поток 1 и Поток 2 у параллельного запуска.

У выхода может быть несколько связей: каждая выполняется как отдельная ветка, параллельно, а узел Слияние потоков ждёт все связи, которые в него входят. Назад может вести только тело узла Цикл; любой другой цикл — ошибка. См. Как идёт запуск.

Параметры и профили

Параметр — именованное значение (хост, порт, имя пользователя), которое записывают один раз в разделе Параметры и используют в любом поле как {{name}}. Профиль сразу меняет несколько параметров: один для ноутбука, один для сцены, один для площадки. Вы выбираете профиль, которым пользуются запуски, или применяете Запустить с…: профиль, другие значения или seed только для одного запуска, не меняя сам эксперимент. В эксперименте может быть до 64 параметров и 32 профилей. См. Данные.

Шаблоны

Большинство текстовых полей узлов — шаблоны: обычный текст с выражениями в двойных фигурных скобках, которые подставляются по мере выполнения шага.

• {{host}} — параметр или переменная, заданная раньше в запуске, например значение, которое узел Извлечь значение взял из ответа, или ответ, полученный ожиданием ({{reply.args[0]}}).
• {{secret.API_TOKEN}} — секрет.
• {{run.id}}, {{run.seed}}, {{now}}, {{now.iso}}, {{counter}} — запуск и текущий момент.
• {{uuid}}, {{random_int(1, 10)}}, {{random_float(0, 1, 2)}}, {{pick("a", "b")}} — сгенерированные значения.

Шаблоны подставляет только движок, поэтому поле означает одно и то же в запуске, в предпросмотре редактора и по кнопке Отправить сейчас. Неизвестное имя — ошибка, а не пустая строка. См. Данные.

Секреты

Секрет — значение, которым эксперимент пользуется, но не хранит: токен, пароль. Эксперимент хранит только его имя; поля используют его как {{secret.NAME}}; а каждый текст, о котором сообщает запуск, — каждый шаг, отчёт и каждый кадр Инспектора, — показывает его замаскированным. Ни одна команда не возвращает значение секрета.

Где живут значения, зависит от того, где работает Signal Lab:

• Настольное приложение в Windows хранит их в Диспетчере учётных данных Windows. Вы задаёте их в разделе Параметры → Секреты.
• В настольном приложении в Linux хранилища учётных данных для них нет, поэтому эксперименты с секретами там запускают из командной строки или на сервере.
• Сервер читает их, только для чтения, из своего окружения (SIGNALLAB_SECRET_<NAME>) или из файла на каждое имя в своей папке секретов (по умолчанию /run/secrets/signallab/<NAME>); из браузера их задать нельзя.
• Командная строка читает их так же, как сервер, а по запросу — из системного хранилища учётных данных. См. Командная строка.

Seed

У каждого запуска есть seed — число, которое определяет в нём всё случайное: сгенерированные значения, разброс повтора, случайный выбор ответа эмулятора, каждое решение реле помех. Тот же seed и тот же трафик дают тот же запуск. Для каждого запуска выбирается новый seed, если эксперимент не закрепил свой: кнопка Закрепить в ленте запуска закрепляет seed последнего запуска, а поле Seed в разделе Параметры задаёт его.

Запуски и отчёты

Запуск начинается с узла Старт, идёт по связям и считается пройденным, если дошёл до узла Финиш и ни один шаг не завершился неудачей. Если он длится дольше 300 секунд, его останавливают. Каждый шаг появляется в ленте запуска, когда начинается и когда заканчивается.

Запуск, который закончился, пройденным или нет, записывает отчёт в папку runs внутри папки данных: название эксперимента, seed, профиль и использованные значения, время начала и конца, исход и его ошибку, каждый шаг и то, что насчитали его эмуляторы и реле. Два запуска одного эксперимента можно сравнить. См. Запуски и отчёты.

Папка данных

Всё, что хранит Signal Lab, — файлы в одной папке: Documents/SignalLab в вашей домашней папке, одинаково в Windows и в Linux. У сервера своя папка, которую вы выбираете при его запуске (/data в образе Docker).

Файл или папка	Что в ней
experiment.json	Эксперимент, открытый в редакторе
signals.json	Библиотека сигналов
emulators.json	Библиотека эмуляторов
runs/	Отчёт о каждом запуске
exports/	Эксперименты, экспортированные из диалога экспериментов
capture-….jsonl, capture-….txt	Выгрузки Инспектора

Файлы — это JSON, записываемый целиком. Если какой-то файл не читается, Signal Lab называет его и место ошибки и оставляет как есть, а не начинает с чистого листа. См. Файлы и папки.

Настольное приложение и сервер

Настольное приложение и сервер работают на одном движке за одним интерфейсом. Различия такие:

	Настольное приложение	Сервер, в браузере
Откуда уходит трафик, где слушают мониторы	Этот компьютер	Сервер
Папка данных	Documents/SignalLab	Папка сервера; наведите курсор на Сервер в шапке, чтобы увидеть её
Секреты	Диспетчер учётных данных Windows, задаются в приложении; в Linux их нет	Только для чтения, из окружения сервера или файлов секретов
Отчёты, экспорт, захваты	Записываются в папку данных; путь показан	Скачиваются браузером
Вход	—	С токеном доступа сервера, если он у него есть
Задачи, банка cookie экрана HTTP	Этого приложения	Сервера, общие для всех вошедших на него страниц
Брандмауэр	Уведомление предлагает разрешить Signal Lab (Windows)	Signal Lab его никогда не меняет
Обновления	Устанавливает подписанные выпуски по вашему щелчку	Обновляется вместе со своим образом

См. Сервер и Безопасность сервера.

Чего Signal Lab не делает сам

• Отправляет только по вашему действию и только на адреса, которые вы вводите. Запуск приложения ничего не отправляет — кроме ежедневной проверки обновлений в настольном приложении, которую можно отключить. Обратная связь уходит только тогда, когда вы отправляете форму.
• Его примеры остаются на этом компьютере. Стартовые сигналы, стартовые эмуляторы, новые эмуляторы и шаблоны экспериментов используют 127.0.0.1. Слушатели, которые вы запускаете, — монитор OSC, приёмник обнаружения, реле помех, — по умолчанию слушают на 0.0.0.0, на всех сетевых картах, чтобы до них могли достучаться другие машины; введите 127.0.0.1, чтобы оставить слушателя на этом компьютере.
• Меняет брандмауэр только по вашему щелчку: когда вы нажимаете Разрешить и подтверждаете запрос администратора Windows или запускаете signallab firewall allow. Сервер никогда не меняет брандмауэр своего хоста.
• Сервер без токена доступа слушает только 127.0.0.1 и отказывается запускаться на любом другом адресе.
• Держится в рамках ограничителей: обход подсети при широковещании охватывает не более 1024 хостов, а маяк отправляет не более 50 000 пакетов в секунду на все свои цели.

Ограничители — это не разрешение: Шторм, Сканер и Броадкаст отправляют настоящий трафик. Пользуйтесь ими только в сетях и на хостах, которые принадлежат вам или которые вам разрешено тестировать.