callsign-wire/1 · 갱신 2026-11-03 · 문의 wks0968@gmail.com

콜사인 통신 규약 — callsign-wire/1

TL;DR - 전송은 WebSocket 위 UTF-8 JSON 텍스트 프레임 하나뿐이다. 바이너리 프레임·전용 직렬화·OS API 가 없다 — WebSocket 과 JSON 을 다루는 언어라면 어디서든(마이크로컨트롤러 포함) 노드를 새로 짤 수 있다. - 노드는 밖으로 걸기만 한다(허브 → 노드 인바운드 포트 0개). 방화벽·NAT·통신사 망 뒤에서도 붙는다. - 메시지는 다섯 가지: 노드 → 허브 hello·beat·attr·endpoints·result, 허브 → 노드 요청 {id, verb, args} 하나. - 동사는 Matter 에서 빌린 넷: read·write·invoke·subscribe. 기기마다 다른 일은 invoke 의 클러스터 이름(shell.run·screen.shot…)으로만 갈린다.

규약을 지키는 실제 구현: 노드 agent-rs/src/main.rs(session)·agent-rs/src/proto.rs, 허브 server/src/adapters/http_fleet.rs(line)·server/src/domain/fleet.rs. 이 문서와 코드가 어긋나면 코드가 맞다 — 문서를 고쳐라.

1. 왜 이 모양인가

2. 주소와 인증

노드 줄:   wss://<허브>/api/fleet/ws         (테일넷·LAN 안이면 ws://<허브>:8788/api/fleet/ws)
부르는 쪽: https://<허브>/api/fleet/*         (HTTP JSON)
머리글:    Authorization: Bearer <열쇠>

열쇠는 세 가지다.

2.1 설정 코드로 들이기(마스터 토큰을 기기에 복사하지 않는다)

허브 주인:  csn fabric commission newpi        → 8자리 코드(10분·한 번)
새 기기:    POST https://<허브>/api/fleet/join
            {"code":"12345678","node":"newpi","os":"linux"}
허브 답:    200 {"node":"newpi","token":"<기기 열쇠>"}

기기는 받은 열쇠를 자기 설정(~/.callsign-agent/agent.json, 권한 0600)에 적고 그 열쇠로 WebSocket 을 연다. callsign-agent join <허브> <코드> 가 이 일을 한다(agent-rs/src/join.rs). 회수는 허브에서 그 줄을 지우면 끝 — 이 기기만 끊긴다.

3. 노드 줄(WebSocket)

3.1 순서

노드                                    허브
 │── (TLS + Upgrade, Authorization) ──▶ │   열쇠 검사. 모르면 401
 │── hello ───────────────────────────▶ │   첫 프레임은 반드시 hello. 아니면 {"error":…} 후 닫음
 │── beat (10초마다) + WS Ping ────────▶ │   30초(3번) 못 들으면 죽은 노드
 │── attr (값이 바뀔 때만) ─────────────▶ │
 │◀────────────────────── {id,verb,args} │   일 시키기(여러 개가 동시에 올 수 있다)
 │── {m:"result",id,ok,res|error,ms} ──▶ │   id 로 짝을 맞춘다. 순서는 상관없다

• 모든 프레임은 텍스트 프레임 하나에 JSON 객체 하나다. 메시지·프레임 상한은 64 MiB(파일 조각이 base64 로 실린다).
• 노드는 요청을 동시에 처리해도 된다. 허브는 id 로만 짝을 맞춘다.
• 노드가 30초 동안 프레임(Pong 포함)을 하나도 못 받으면 줄이 죽은 것으로 보고 다시 건다(와이파이를 갈아타면 TCP 는 15분을 버틴다).
• 같은 이름이 새 줄로 붙으면 허브는 옛 줄을 닫는다. 다시 붙을 때 hello 부터 새로 한다.

3.2 hello — 노드 → 허브, 첫 프레임

{
  "node": "pi",
  "os": "linux",
  "caps": ["shell", "files", "gpio"],
  "clusters": ["shell.run", "file.get", "file.put", "gpio.read", "gpio.write", "sys.info"],
  "taints": [],
  "endpoints": [{"id": 1, "type": "ir-bridge", "clusters": ["onoff"]}]
}

3.3 노드 → 허브

모르는 m 은 허브가 버린다 — 새 메시지를 더해도 옛 허브가 죽지 않는다.

3.4 허브 → 노드

{"id": 17, "verb": "invoke", "args": {"cluster": "shell.run", "cmd": "uptime", "timeout": 30}}

4. 동사

5. 클러스터(invoke) — 모든 OS 공통 이름

노드는 할 수 있는 것만 hello.clusters 에 싣는다. 이름은 같고 OS 마다 속만 다르다 (screen.shot 은 맥에선 ScreenCaptureKit, 윈도우에선 GDI, 리눅스에선 grim, 폰에선 adb/WDA).

새 클러스터는 묶음.동작 꼴로 이름 짓고, 모르는 이름이 오면 아는 목록을 붙여 실패로 답한다. 노드 설정의 deny(클러스터 글롭)에 걸린 것은 "모른다"가 아니라 "거부한다"고 답한다.

6. 부르는 쪽(HTTP) — POST /api/fleet/call

CLI(csn)·에이전트·스크립트는 노드 줄을 직접 열지 않고 허브에 HTTP 로 부탁한다.

POST /api/fleet/call
Authorization: Bearer <조작 열쇠>
Content-Type: application/json

{"requires":["gpu"], "os":"linux", "tolerate":["hot"], "selector":{"room":"lab"},
 "verb":"invoke", "args":{"cluster":"shell.run","cmd":"nvidia-smi"},
 "wait_s":30, "timeout_s":90, "all":false}

답은 노드의 result 를 그대로 싣는다. 줄이 없던 것(noline, 다른 노드로 넘겨도 안전)과 보낸 뒤 끊긴 것(dropped, 돌았을 수 있음)을 구분해 알린다.

그 밖의 노선: GET /api/fleet/nodes(목록)·status·events(SSE)·audit·cordon·claim·join.

7. 새 OS 에 노드를 짜는 최소 구현

아래 다섯 가지만 하면 csn ls 에 뜨고 csn sh <노드> -- … 가 돈다. 파이썬 40줄이면 된다.

1. wss://<허브>/api/fleet/ws 에 Authorization: Bearer <기기 열쇠> 로 붙는다.
2. hello 를 보낸다(clusters: ["shell.run"]).
3. 10초마다 {"m":"beat","taints":[]} 와 WebSocket Ping 을 보낸다.
4. {id, verb:"invoke", args:{cluster:"shell.run", cmd}} 를 받으면 돌리고 {"m":"result","id":…,"ok":true,"res":{"code":0,"out":"…","err":""}} 로 답한다.
5. 줄이 끊기면 1~5초 뒤 처음부터 다시 붙는다.

import asyncio, json, subprocess, websockets   # pip install websockets

HUB, KEY, NODE = "wss://hub.example.com/api/fleet/ws", "<기기 열쇠>", "mybox"

async def main():
    while True:
        try:
            async with websockets.connect(HUB, additional_headers={"Authorization": f"Bearer {KEY}"}) as ws:
                await ws.send(json.dumps({"node": NODE, "os": "linux", "caps": ["shell"], "clusters": ["shell.run"], "taints": []}))
                async def beat():
                    while True:
                        await ws.send(json.dumps({"m": "beat", "taints": []})); await asyncio.sleep(10)
                asyncio.create_task(beat())
                async for raw in ws:
                    r = json.loads(raw)
                    if "id" not in r: continue
                    a = r.get("args") or {}
                    if r.get("verb") == "invoke" and a.get("cluster") == "shell.run":
                        p = subprocess.run(a["cmd"], shell=True, capture_output=True, text=True, timeout=a.get("timeout", 120))
                        out = {"m": "result", "id": r["id"], "ok": True, "res": {"code": p.returncode, "out": p.stdout, "err": p.stderr}}
                    else:
                        out = {"m": "result", "id": r["id"], "ok": False, "error": f"{NODE} 는 {a.get('cluster')} 를 모릅니다. 아는 것: shell.run"}
                    await ws.send(json.dumps(out))
        except Exception:
            await asyncio.sleep(3)

asyncio.run(main())

8. 호환 규칙

• 더하기만 한다. 키를 새로 더할 수는 있어도 있던 키의 뜻을 바꾸거나 빼지 않는다. 받는 쪽은 모르는 키를 무시한다.
• 빈 배열·없는 키는 같은 뜻이다(endpoints 가 없으면 끝점 0 만).
• 버전 번호를 주고받지 않는다 — 능력은 caps·clusters 로 알린다. 뜻이 깨지는 변경이 필요하면 노선을 새로 연다(/api/fleet/ws2).