개념

이 페이지는 Signal Lab이 무엇 위에 세워졌는지 설명하여, 나머지 문서를 쉽게 읽을 수 있게 합니다. 각 절은 그 주제를 자세히 다루는 페이지로 연결됩니다.

화면과 실험

Signal Lab에는 두 가지 작업 방식이 있으며, 둘 다 쓰게 됩니다.

• 화면은 지금 직접 하는 작업을 위한 도구입니다. 이 메시지를 보내고, 저 포트에서 듣고, 이 에뮬레이터를 시작하고, 브로커가 무엇을 가졌는지 봅니다. 시도하고, 보고, 무언가를 바꾸고 다시 시도합니다. 프로토콜과 도구마다 화면이 있습니다. 창을 참고하십시오.
• 실험은 한 번 만들어 매번 같은 방식으로 다시 실행하는 흐름입니다. 요청을 보내고, 응답을 기다리고, 검사하고, 계속하거나 분기합니다. 각 실행은 단계별로 보고되고 저장됩니다. 실험을 참고하십시오.

둘은 여러 곳에서 만납니다. HTTP와 OSC 화면에서는 실험에 추가가 방금 보낸 것을 실험의 다음 단계로 바꿉니다. OSC 모니터와 MQTT 화면에서는 이 메시지 대기가 받은 메시지를 그것을 기다리는 단계로 바꿉니다. 라이브러리의 신호도 단계가 될 수 있습니다. hex로 쓴 원시 UDP 바이트만 빼고요.

신호와 라이브러리

신호는 보관해 두는 메시지입니다. 이름, 폴더, 무엇을 일으켜야 하는지에 대한 메모, 그리고 보내는 내용(OSC 메시지, 원시 UDP 바이트, HTTP 요청 또는 MQTT 발행)으로 이루어집니다. 신호 라이브러리는 그것들을 중첩하고 이름을 바꾸고 끌어다 놓을 수 있는 폴더에 담아 둡니다.

• OSC, HTTP, MQTT 화면에서 신호를 저장하거나(저장…), 신호 화면에서 만들거나, 인스펙터가 잡은 프레임을 저장합니다(신호로 저장). 그러면 그 프레임을 바이트 그대로 재생합니다.
• 신호 화면에서, 어디서든 Ctrl+K로, 실험의 단계로, 또는 터미널에서 signallab fire로 보냅니다.
• 신호는 원래 화면이 보냈을 것을 정확히 보냅니다. 같은 바이트, 같은 경로, 인스펙터에 실제 프로토콜로 표시됩니다.

라이브러리는 데이터 폴더에 있는 파일 하나, signals.json입니다. 읽고 편집하고 다른 컴퓨터로 복사하거나 저장소에 보관할 수 있는 평범한 JSON입니다. 127.0.0.1을 향한 예시 신호 모음으로 시작합니다. 신호를 참고하십시오.

작업

버튼을 누른 뒤에도 계속 도는 것은 무엇이든 작업입니다. OSC 모니터나 생성기, 브로커나 WebSocket 연결, 비콘이나 탐색 리스너, HTTP 부하 버스트, 에뮬레이터, 네트워크 장애 릴레이, 스톰, 스캔, 실험 실행입니다.

• 각 작업에는 하단 패널 표시줄에 알약이 있으며, 번호, 무엇인지, 중지 버튼이 있습니다. 사이드바는 각 화면이 몇 개의 작업을 돌리는지 보여 줍니다.
• 헤더의 모두 중지는 모든 작업을 한꺼번에 중지합니다.
• 스스로 끝난 작업(끝난 스캔, 통과한 실행, 포트가 실패한 모니터)은 알약을 남기고, 콘솔이 어떻게 끝났는지 말합니다.
• 작업은 다른 화면에서 작업하는 동안에도 계속됩니다.
• 업데이트를 설치하면 먼저 모든 작업을 중지합니다.

서버에서는 작업이 서버에 속합니다. 로그인한 모든 페이지가 같은 작업을 보고 중지할 수 있습니다.

캡처와 인스펙터

모든 도구(송신기, 모니터, 리스너, 에뮬레이터, 릴레이, 실험 실행)는 보내거나 받는 각 프레임을 하나의 캡처로 넘기고, 인스펙터가 그것을 하나의 타임라인에 보여 줍니다.

• 캡처는 캡처 켜기로 켜기 전까지 꺼져 있으며, 꺼져 있는 동안에는 비용이 들지 않습니다. 해제할 때까지 어느 화면에 있든 켜진 채로 있습니다.
• 최대 8192개 프레임과 그 바이트 64 MiB를 보관하며, 가장 오래된 프레임이 새 것 자리를 내줍니다. 프레임은 각각 자기 바이트를 최대 256 KiB까지 보관하고, 목록은 처음 1 KiB를 보여 줍니다.
• 보기 일시 정지는 목록이 움직이지 않게 해 읽을 수 있게 합니다. 캡처는 그 아래에서 계속됩니다.
• 실행이 쓰는 시크릿 값은 모든 프레임에서 마스킹됩니다.
• 전체 캡처를 보관된 모든 바이트와 함께 .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, 그리고 램프: lab/<name>/set에 발행한 ON 또는 OFF를 lab/<name>/state로 응답합니다

에뮬레이터를 참고하십시오.

네트워크 장애 릴레이

네트워크 장애 릴레이는 클라이언트와 그 대상 사이에 앉습니다. 클라이언트를 실제 대상 대신 릴레이의 수신 주소로 가리키면, 릴레이가 양방향으로 전달하면서 통과하는 것을 프로필에 따라 열화시킵니다:

• UDP에서는 각 데이터그램이 자기 운명을 맞습니다. 지연과 지터, 손실과 손실 버스트, 중복, 손상, 순서 바뀜, 대역폭 제한, 또는 아무것도 지나가지 않음(오프라인)입니다.
• TCP에서는 각 연결이 대상으로 가는 자기 연결과 이어지고, 두 스트림이 지연되거나, 대역폭 제한에 묶이거나, 리셋되거나, 반열린 상태로 남습니다.

프리셋은 케이블부터 위성 링크까지 프로필을 한 번의 클릭으로 설정합니다. 변경은 릴레이가 도는 동안 포트를 끊지 않고 적용됩니다. 모든 결정은 시드에서 뽑으므로, 같은 트래픽이 같은 운명을 다시 맞습니다.

네트워크 장애 화면에서는 릴레이가 작업으로 돕니다. 실험에서는 네트워크 장애 노드가 실행을 위해 하나를 열고, 장애 변경가 실행 도중 프로필을 바꿉니다. 네트워크 장애와 장애 주입을 참고하십시오.

실험

노드와 연결선

실험은 연결선으로 이어진 노드의 그래프입니다. 각 노드는 한 단계입니다. 무언가를 보내거나, 기다리거나, 값을 검사하거나, 값을 추출하거나, 흐름을 바꾸거나, 실행을 준비합니다(에뮬레이터, 네트워크 장애 릴레이). 모든 실험에는 시작와 종료가 정확히 하나씩 있고, 최대 64개 노드를 담습니다. 편집기에서 연 실험은 편집하는 대로 저장됩니다. 노드를 참고하십시오.

출력

연결선은 노드의 출력에서 다른 노드의 입력으로 이어집니다. 대부분의 노드는 출력이 하나이고, 다른 노드들은 여럿 중에서 고릅니다. 분기에는 예와 아니요, 기다리기에는 일치와 시간 초과, 루프에는 본문, 완료, 한도, 병렬 분기에는 분기 1과 분기 2입니다.

한 출력에 여러 연결선이 있을 수 있습니다. 각각은 병렬로 도는 자기 분기가 되고, 분기 합류은 그리로 들어오는 모든 연결선을 기다립니다. 루프의 본문만 되돌아갈 수 있으며, 그 밖의 순환은 오류입니다. 흐름을 참고하십시오.

매개변수와 프로필

매개변수는 이름이 붙은 값입니다. 호스트, 포트, 사용자 이름처럼 매개변수 아래에 한 번 적어 두고 아무 필드에서나 {{name}}으로 씁니다. 프로필은 매개변수 일부를 한꺼번에 바꿉니다. 노트북용 하나, 무대용 하나, 공연장용 하나 하는 식입니다. 실험이 쓰는 프로필을 고르거나, 실험을 바꾸지 않고 한 번의 실행에만 쓸 프로필·다른 값·시드를 값 지정 실행…로 정합니다. 실험은 매개변수 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>)에서 읽기 전용으로 읽습니다. 브라우저에서는 설정할 수 없습니다.
• 명령줄은 서버와 같은 방식으로, 또는 요청하면 시스템의 자격 증명 저장소에서 읽습니다. 명령줄을 참고하십시오.

시드

모든 실행에는 시드가 있습니다. 그 안의 모든 무작위를 결정하는 숫자로, 생성되는 값, Repeat의 지터, 에뮬레이터의 무작위 응답 선택, 네트워크 장애 릴레이의 모든 결정을 정합니다. 같은 시드와 같은 트래픽은 같은 실행을 줍니다. 실험이 하나를 고정하지 않는 한 실행마다 새 시드를 뽑습니다. 실행 타임라인의 고정는 마지막 실행의 시드를 고정하고, 매개변수 아래의 시드는 하나를 설정합니다.

실행과 보고서

실행은 시작에서 시작해 연결선을 따라가며, 실패한 단계 없이 종료에 도달하면 통과합니다. 300초보다 오래 걸리면 중지됩니다. 각 단계는 시작하고 끝날 때 실행 타임라인에 나타납니다.

통과했든 실패했든 끝난 실행은 데이터 폴더의 runs 폴더에 보고서를 하나 씁니다. 실험 이름, 시드, 프로필, 사용한 값, 시작과 종료 시각, 결과와 그 오류, 모든 단계, 에뮬레이터와 릴레이가 집계한 것이 담깁니다. 같은 실험의 두 실행을 비교할 수 있습니다. 실행과 보고서를 참고하십시오.

데이터 폴더

Signal Lab이 보관하는 모든 것은 한 폴더의 파일입니다. Windows와 Linux 모두에서 홈 폴더의 Documents/SignalLab입니다. 서버는 자기 것을 가지며, 시작할 때 고릅니다(Docker 이미지에서는 /data).

파일 또는 폴더	담는 것
experiment.json	편집기에서 연 실험
signals.json	신호 라이브러리
emulators.json	에뮬레이터 라이브러리
runs/	실행마다 보고서 하나
exports/	실험 대화 상자에서 내보낸 실험
capture-….jsonl, capture-….txt	인스펙터 내보내기

파일은 JSON이며 통째로 씁니다. 하나를 읽을 수 없으면 Signal Lab은 어느 파일이고 오류가 어디인지 말하고, 처음부터 다시 시작하지 않고 그대로 둡니다. 파일과 폴더를 참고하십시오.

데스크톱과 서버

데스크톱 앱과 서버는 같은 인터페이스 뒤에서 같은 엔진을 돌립니다. 다른 점은 다음과 같습니다:

	데스크톱 앱	브라우저의 서버
트래픽이 시작하는 곳, 모니터가 듣는 곳	이 컴퓨터	서버
데이터 폴더	Documents/SignalLab	서버의 것. 헤더의 서버에 포인터를 올리면 보입니다
시크릿	Windows 자격 증명 관리자, 앱에서 설정. Linux에는 없음	서버의 환경이나 시크릿 파일에서 읽기 전용
보고서, 내보내기, 캡처	데이터 폴더에 씁니다. 경로가 표시됩니다	브라우저가 내려받습니다
로그인	—	서버에 접근 토큰이 있으면 그 토큰으로
작업, 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개 패킷을 보냅니다.

안전 장치는 허가가 아닙니다. 스톰, 스캐너, 브로드캐스트는 실제 트래픽을 보냅니다. 소유했거나 테스트가 허가된 네트워크와 호스트에서만 쓰십시오.