2nd/10_Wiki/Comfyui/위키 Messages - ComfyUI 2026-05-20.md

id, title, category, status, verification_status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, created_at, updated_at, review_reason, merge_history, tags, raw_sources, applied_in, github_commit

id	title	category	status	verification_status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	created_at	updated_at	review_reason	merge_history	tags	raw_sources	applied_in	github_commit
messages---comfyui	Messages - ComfyUI	10_Wiki/Topics	draft	conceptual				B	0.8	2026-05-20	2026-05-20			web wikify	https://docs.comfy.org/development/comfyui-server/comms_messages

Messages - ComfyUI

🎯 한 줄 통찰 (One-line insight)

ComfyUI 서버와 클라이언트 간의 실시간 데이터 교환을 위해 PromptExecutor가 PromptServer를 통해 메시지를 전송하고, 클라이언트는 소켓 이벤트를 통해 이를 수신하여 처리하는 통신 메커니즘.

🧠 핵심 개념 (Core concepts)

• 메시지 전달 구조: PromptExecutor가 실행 중 또는 큐 상태 변경 시 PromptServer의 send_sync 메서드를 통해 클라이언트로 메시지를 전송함.
• 클라이언트 수신 방식: api.js에 정의된 소켓 이벤트 리스너가 CustomEvent 객체를 생성하여 등록된 리스너로 디스패치함.
• 확장성 (Extensibility): 기본 제공되는 메시지 타입 외에도 클라이언트와 서버 양측에서 사용자 정의 메시지 타입을 추가하고 처리할 수 있음.
• 데이터 구조: 메시지 핸들러는 CustomEvent를 통해 전달받으며, .detail 속성을 통해 서버가 보낸 데이터 딕셔너리에 접근 가능함.

🧩 추출된 패턴 (Extracted patterns)

• 이벤트 기반 통신: 클라이언트 측에서 api.addEventListener(message_type, messageHandler) 형식을 사용하여 특정 메시지 타입에 대한 이벤트를 등록하는 표준 JavaScript 관용구 사용.
• 자동 유형 인식: 정의되지 않은 새로운 메시지 타입이 들어오면 클라이언트는 이를 자동으로 알려진 메시지 목록에 추가함. o 서버-클라이언트 동기화: 서버 측에서는 PromptServer.instance.send_sync를 통해, 클라이언트 측에서는 리스너 등록을 통해 양방향 통신 구조를 형성함.

📖 세부 내용 (Details)

1. 내장 메시지 타입 (Built in message types)

PromptServer의 send_sync 메서드를 통해 전달되는 주요 이벤트와 그 데이터 구성은 다음과 같습니다.

event	when data
execution_start	When a prompt is about to run: prompt_id
execution_error	When an error occurs during execution: prompt_id, plus additional information
execution_interrupted	When execution is stopped by a node raising InterruptProcessingException: prompt_id, node_id, node_type and executed (a list of executed nodes)
execution_cached	At the start of execution: prompt_id, nodes (a list of nodes which are being skipped because their cached outputs can be used)
execution_success	When all nodes from the prompt have been successfully executed: prompt_id, timestamp
executing	When a new node is about to be executed: node (node id or None to indicate completion), prompt_id
executed	When a node returns a ui element: node (node id), prompt_id, output
progress	During execution of a node that implements the required hook: node (node id), prompt_id, value, max
status	When the state of the queue changes: exec_info, a dictionary holding queue_remaining (the number of entries in the queue)

2. 실행된 메시지 활용 (Using executed)

'executed' 메시지는 단순히 노드가 실행을 완료할 때 전송되는 것이 아니라, 노드가 UI 업데이트를 반환할 때만 전송됩니다. 이를 위해 메인 함수는 튜플 대신 다음과 같은 구조의 딕셔 необходимо 합니다:

• return { "ui": a_new_dictionary, "result": the_tuple_of_output_values }
• a_new_dictionary는 output 값으로 전송되며, 결과 키(result)는 출력값이 없는 경우 생략 가능합니다.

3. 사용자 정의 메시지 타입 (Custom message types)

• 클라이언트 측: api.addEventListener("my.custom.message", messageHandler);와 같이 고유한 이름으로 리스너를 등록하여 구현합니다.
• 서버 측: PromptServer.instance.send_sync("my.custom.message", a_dictionary)를 사용하여 데이터를 전송합니다.

4. 노드 ID 획득 (Getting node_id)

내장 메시지에는 현재 노드의 ID가 포함되는 경우가 많습니다. 서버 측에서 이를 활용하기 위해 INPUT_TYPES의 hidden 키를 사용하여 node_id를 가져올 수 있습니다.

@classmethod
def INPUT_TYPES(s):
    return {"required" : { }, "hidden": { "node_id": "UNIQUE_ID" } }

⚖️ 모순 및 업데이트 (Contradictions & updates)

본문에서 'executed' 메시지라는 명칭과 실제 동작(UI 업데이트가 있을 때만 전송됨) 사이의 차이점에 대해 설명하고 있습니다.

🛠️ 적용 사례 (Applied in summary)

• 커스텀 노드 개발: INPUT_TYPES 내 hidden 설정을 통해 서버 측에서 node_id를 식별하고 이를 메시지에 포함시켜 클라이언트에 전달하는 사례.
• 확장 기능(Extension) 구현: setup() 함수 내에서 api.addEventListener를 사용하여 특정 이벤트에 대한 핸들러를 등록하는 사례.

✅ 검증 상태 및 신뢰도

• 상태: draft
• 검증 단계: conceptual
• 출처 신뢰도: B (Primary Source — 웹사이트 본문 직접 추출)
• 중복 검사 결과: 신규 생성 (New discovery)

🔗 관련 문서 링크 (Related document links)

• PromptExecutor: 메시지를 클라이언트로 전송하는 주체.
• PromptServer: send_sync 메서드를 통해 메시지 전달을 담당하는 서버 구성 요소.
• api.js: 소켓 이벤트 리스너가 정의되어 있는 클라이언트 측 핵심 파일.
• InterruptProcessingException: 실행 중단 시 발생하는 예외 타입.
• INPUT_TYPES: 노드의 입력 타입을 정의하며 node_id를 숨겨진 값으로 가져오는 데 사용됨.

📝 변경 이력 (Change history)

• 2026-05-20: Astra /wikify 로 https://docs.comfy.org/development/comfyui-server/comms_messages 본문에서 초안 생성.