1. 개요 (Introduction)
RAWP 1.0은 중앙 제어 서버(Master Server)가 원격지의 게이트웨이(Local Client)를 안전하게 제어하기 위한 Push 기반의 분산 제어 프로토콜이다. 제어 및 상태 모니터링을 위한 Stateless HTTP 통신과, 실시간 데이터 입출력을 위한 Stateful WebSocket 통신으로 제어 평면(Control Plane)과 데이터 평면(Data Plane)을 분리한다.
1.1. 요구사항 표기 규약 (Requirements Notation)
본 문서의 "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "OPTIONAL"은 RFC 2119를 따른다.
1.2. 용어 정의 (Terminology)
| 용어 | 정의 |
|---|---|
| Master Server | 클라이언트 노드를 관리하고 제어 명령을 하달하는 중앙 서버 (Control Plane). |
| Local Client | 마스터 서버의 명령을 수신하는 HTTP 엔드포인트를 소유하며, 로컬 프로세스(Agent)의 실행 및 I/O를 담당하는 에지 게이트웨이 (Execution Plane). |
| Agent | 클라이언트 환경에서 실행되는 실제 단위 작업 프로세스 (예: LLM, 스크립트 등). |
| Agent Session | 특정 에이전트의 실행부터 종료까지의 라이프사이클 및 I/O 스트림의 논리적 단위. session_id(UUID v4)로 식별한다. 상태 머신: INIT → RUNNING → DETACHED → TERMINATED. 하나의 Agent Session에 복수의 WSS Connection이 바인딩될 수 있다. 본 문서에서 "세션"은 별도 명시가 없는 한 Agent Session을 의미한다. |
| WSS Connection | Agent Session에 바인딩된 WebSocket 전송 채널. 티켓(§5.3)을 통해 수립되며, 네트워크 단절 시 소멸하고 재연결(reattach)으로 재수립할 수 있다. 동일 Agent Session에 여러 WSS Connection이 동시에 존재할 수 있다 (예: 마스터 연결 + 로컬 UI 연결, 또는 다중 엣지 연결). |
| Config Scope | 클라이언트 설정의 논리적 분류 단위. 각 스코프는 독립된 엔드포인트, 독립된 config_version, 독립된 갱신 주기를 갖는다. |
| Session-Pinned Config | 세션 초기화 시점에 바인딩된 설정 스냅샷. 해당 세션의 전체 라이프사이클 동안 불변이다. |
Agent Session과 WSS Connection의 관계: Agent Session은 에이전트의 논리적 생명주기이고, WSS Connection은 그 세션의 데이터를 전달하는 전송 채널이다. Agent Session이 RUNNING 상태에서 WSS Connection이 단절되면 Agent Session은 DETACHED로 전이하지만 에이전트 프로세스는 계속 실행된다. WSS Connection이 재수립(reattach)되면 Agent Session은 RUNNING으로 복귀한다. Agent Session이 TERMINATED되면 모든 WSS Connection이 종료된다.
1.3. 호환성 및 파싱 규약 (Forward Compatibility)
- 필드 무시 원칙 (Postel's Law): 클라이언트와 서버의 JSON 파서는 스펙에 정의되지 않은 알 수 없는 키(Unknown Key)를 수신하더라도 파싱 에러를 발생시키지 않고 조용히 무시해야 한다 (MUST).
- API 단종 예고: 서버는 향후 지원이 중단될 API 응답에
Warning: 299 - "Deprecated API"HTTP 헤더를 포함할 수 있으며, 수신자는 이를 감지 시 시스템 로그에 기록해야 한다 (MUST).