RAWP 1.0.2

1.0.2 ko public

5. Phase 3: 세션 라이프사이클 및 연결 (Session & I/O)

세션 생명주기: INIT → RUNNING → DETACHED(소켓 단절 시) → TERMINATED

5.1. 세션 초기화 및 재연결 (Session Initialization)

신규 에이전트 실행 또는 DETACHED 상태 프로세스에 WSS 바인딩을 위한 티켓을 발급한다.

Endpoint: POST /v1/session/init (Local Client 제공)

Request:

{
  "session_id": "String (필수, UUID v4)",
  "agent_name": "String (reattach: false 시 필수)",
  "workspace_path": "String (reattach: false 시 필수)",
  "ticket": "String (필수, WSS 연결 인증용 난수 티켓)",
  "reattach": "Boolean (선택, 기본값 false. true 시 기존 구동 중 프로세스 바인딩)",
  "last_sync_timestamp": "String (선택, ISO 8601)",
  "last_message_id": "String (선택, UUID)"
}

제약 조건: reattach: true이나 해당 session_id가 존재하지 않거나 종료된 경우 404 Not Found 반환 (MUST).

Config 바인딩 제약 조건: 마스터 서버는 reattach: false로 세션을 초기화할 때, §4.1.8에 따라 양쪽 Config Scope(limits, capabilities)의 최신 스냅샷을 해당 세션에 바인딩해야 한다 (MUST). 양쪽 스코프의 초기 동기화(§4.1.2)가 완료되지 않은 클라이언트에 대해서는 세션 초기화를 시도해서는 안 된다 (MUST NOT).

5.2. 세션 명시적 종료 (Session Termination)

Endpoint: DELETE /v1/session/{session_id} (Local Client 제공)

제약 조건: 클라이언트는 자식 프로세스에 SIGTERM을 전송하고, 5초 내 종료되지 않으면 SIGKILL로 강제 종료 후 메모리 버퍼 및 소켓을 파기해야 한다 (MUST).

WSS 알림 의무: 세션 종료 처리 후 WSS 연결을 닫기 전에, 해당 세션에 바인딩된 모든 WSS Connection에 RAWP-DPS 1.0.1 §7.7의 session.deleted 이벤트를 발송해야 한다 (MUST). 발송 순서는 RAWP-DPS 1.0.1 §7.5.3(진행 중 항목 정리) → session.deleted → WSS 종료이다.

5.3. WebSocket 연결 수립 (WebSocket Upgrade)

Connection URI: wss://{client_address}/v1/ws/stream?ticket={ticket}&session_id={session_id}

인가 절차 (MUST):

클라이언트는 HTTP Upgrade 요청 수신 시 HTTP 헤더의 Sec-WebSocket-Protocol을 확인해야 한다. RAWP-DPS 1.0.1 적용 시 rawp-dps-1.0을 우선 수락하고, 미지원 시 rawp-1.0으로 폴백한다. 양측 모두 미지원 시 426 또는 400을 반환해야 한다.
Query Parameter의 ticket과 session_id를 검증하고, 만료되거나 불일치 시 401 Unauthorized를 반환 후 연결을 거절한다.
사용된 티켓은 1회 사용 시 즉시 무효화(Burn)해야 한다.

5.4. 세션 이름 변경 (Session Rename)

세션에 사용자 친화적 이름을 부여하고, 변경 사항을 모든 참여자에게 전파한다.

5.4.1. 마스터 → 클라이언트 이름 변경

Endpoint: PATCH /v1/session/{session_id} (Local Client 제공)

Request:

{
  "name": "String (필수, 새 세션 이름. 최대 200자)"
}

Response (200 OK):

{
  "session_id": "String (필수)",
  "name": "String (필수, 변경된 이름)",
  "updated_at": "String (필수, ISO 8601)"
}

제약 조건: 존재하지 않거나 TERMINATED 상태인 세션에 대한 요청은 404 Not Found를 반환한다 (MUST).

WSS 알림 의무: HTTP 응답 후, 클라이언트는 해당 세션에 바인딩된 모든 WSS Connection에 RAWP-DPS 1.0.1 §7.6의 session.renamed 이벤트를 발송해야 한다 (MUST). 이는 로컬 UI WSS(§10.6)와 마스터 WSS를 모두 포함한다.

5.4.2. 엣지 → 마스터 이름 변경

Endpoint: PATCH /v1/edge/sessions/{session_id} (Master Server 제공)

Request/Response: §5.4.1과 동일한 스키마.

마스터는 이름 변경 수신 시 대상 로컬 클라이언트의 PATCH /v1/session/{session_id}를 호출하여 전파하고, 해당 세션에 연결된 모든 엣지 WSS에 RAWP-DPS 1.0.1 §7.6의 session.renamed 이벤트를 브로드캐스트해야 한다 (MUST).

5.4.3. 로컬 세션 이름 변경

Endpoint: PATCH /local/v1/sessions/{session_id} (Local Client 제공)