기타 2026-05-27 3KB 읽기 4분

크라우니메신저 v3 시스템 채널 메시지 API

개요

메신저 v3 서버에 POST /api/v1/messages 엔드포인트를 추가했다. 메신저알림.한선, 시즌1알림.한선 등 내부 모듈이 호출하는 표준 시스템 채널 API. 내부 호출 전용 (127.0.0.1 loopback 또는 X-Crowny-Internal: 1 헤더 필수).

엔드포인트 스펙

POST http://127.0.0.1:9766/api/v1/messages

요청 헤더

Content-Type: application/json
X-Crowny-Internal: 1 (필수 — 외부 호출 차단)

요청 바디

json{
  "from": "system",
  "to": "CRN-12345678",
  "channel": "system",
  "text": "메시지 내용 (최대 4K)",
  "ts": 1779852000
}

from: 필수, 발신자 식별자
to: 필수, CRN-XXXXXXXX 형식 또는 "broadcast"
channel: 필수, system / notify / alert 중 하나
text: 필수, 최대 4096자
ts: 선택, unix timestamp (없으면 서버 시각 사용)

성공 응답 (200)

json{"ok": true, "message_id": "sys-1779852000-2f18", "queued": 1}

실패 응답 (400/403)

json{"ok": false, "error": "from_required"}

에러 코드: from_required / to_required / channel_invalid / text_required / text_too_long / internal_only / invalid_json

추가된 함수 (JS — ws-server-v3.js)

함수	역할
`appendSystemLog(record)`	YYYY-MM-DD.jsonl에 append-only 영속
`pushToUserIfConnected(crowny_id, packet)`	WS 접속 중이면 즉시 푸시, 반환값 bool
`POST /api/v1/messages` 핸들러	검증 → 영속 → WS 푸시 → 응답

한선씨 정본 함수 (시스템알림.한선)

함수	역할
`시스템채널유효(channel)`	system/notify/alert만 참 반환
`시스템메시지검증(from,to,channel,text)`	셀코어 룰 패턴, 맵 반환 {ok, 에러맵}
`시스템메시지ID생성()`	`sys-<unix>-<rand>` 형식
`시스템메시지영속(record)`	날짜 경로에 파이프 구분 JSONL 기록
`시스템메시지패킷(...)`	t=NOTIFY WS 인벨로프 JSON 직렬화
`_자가검증()`	7건 어설트 (채널유효 3종, 거부 2종, ID/패킷 형식)

영속 파일 위치

/Users/ef/.crowny-messenger/v3/system/YYYY-MM-DD.jsonl

각 줄: {"message_id":"...","from":"...","to":"...","channel":"...","text":"...","ts":...,"saved_at":...}

연동 흐름

시즌1알림.한선
  → 메신저알림_시스템(crowny_id, 본문) [메신저알림.한선]
    → POST 127.0.0.1:9766/api/v1/messages
      → appendSystemLog() → 영속 JSONL
      → pushToUserIfConnected() → WS NOTIFY 패킷 즉시 전달
      → 미접속 시 queueOffline() → 다음 접속 시 플러시

잔여 이슈

시스템알림.한선 hanseonc_high 컴파일 검증 — 실행 권한 문제로 미확인 (settings.json에 허용 추가 필요)
broadcast 대상 시 queueOffline 중복 호출 없음 확인 필요
외부 호출 차단 테스트 — loopback에서는 항상 허용됨, 비-loopback 검증은 실제 외부 요청 필요
TLS 설정 완료 후 https://127.0.0.1:9766/api/v1/messages 경로 추가 검토

← 이전크라우니메신저 v3 셀프테스트 분리2026-05-27-메신저-셀프테스트-분리 다음 →메신저 v3 SSO 실API 매핑 (2026-05-27)2026-05-27-메신저-실SSO-매핑