세션 수명주기¶

생성¶

세션 생성은 인증과 자원 생성 순서를 엄격히 지킵니다.

SDP 요청과 query parameter를 검증합니다.
Bearer credential을 분류하고 /sohri WSS를 다이얼합니다.
백엔드 인증이 성공하면 PeerConnection, outbound audio track과 codec을 생성합니다.
세션을 registry에 등록하고 oai-events·remote audio track callback을 연결합니다.
remote offer를 적용하고 answer·ICE 수집을 완료합니다.
outbound event/TTS/RTCP pump를 시작합니다.

서버가 shutdown 상태로 전환된 뒤에는 새 세션을 등록하지 않습니다. 생성 중 어느 단계든 실패하면 이미 만든 WSS, PeerConnection과 세션 상태를 정리합니다.

연결 상태¶

Pion 상태	Gateway 동작
`Connected`	실행 중인 disconnect timer를 취소
`Disconnected`	복구 유예 timer 시작
`Failed` / `Closed`	timer를 취소하고 즉시 세션 종료

PEER_DISCONNECTED_GRACE 기본값은 10초입니다. 이 값은 모바일 네트워크 전환이나 일시적 ICE 경로 단절에서 같은 PeerConnection이 복구될 시간을 줍니다. timer 만료 시 상태를 다시 읽어 이미 Connected이면 종료를 취소하고, 그렇지 않으면 세션을 닫습니다. 0s로 설정하면 Disconnected에서 즉시 닫는 레거시 동작입니다.

이 유예는 ICE restart 시그널링을 제공한다는 뜻이 아닙니다. 현재 SDP API는 한 번의 비-트리클 offer/answer만 지원하며 restart endpoint는 없습니다.

세션 종료¶

close()는 여러 goroutine에서 호출되어도 한 번만 수행되는 멱등 연산입니다.

flowchart TD
    A["close 시작"] --> B["closing 표시·session gauge 감소"]
    B --> C["disconnect/setup/response/input timer 정지"]
    C --> D["playout generation 취소"]
    D --> E["필요 시 dialog end 알림"]
    E --> F["세션 전용 /sohri WSS 닫기"]
    F --> G["DataChannel terminal 이벤트 제한 시간 flush"]
    G --> H["PeerConnection 닫기"]
    H --> I["서버 session registry 해제"]

종료 중에는 stale generation TTS와 새 이벤트가 다시 재생되지 않습니다. 백엔드 대화 완료가 아직 오지 않았다면 제한 시간 안에서 dialog end를 알리고, SCTP buffered amount도 무한히 기다리지 않습니다.

프로세스 shutdown¶

SIGINT 또는 SIGTERM을 받으면 전체 shutdown timeout 10초 안에서 HTTP 서버와 WebRTC 서버를 병렬 종료합니다.

WebRTC 서버가 shuttingDown을 설정해 새 세션 등록을 차단합니다.
활성 세션마다 데이터채널로 error{type:"server_error",code:"server_shutting_down"}을 보냅니다.
모든 세션을 병렬로 닫고 registry에서 해제되기를 기다립니다.
동시에 HTTP server가 listener와 진행 중 HTTP 요청을 graceful shutdown합니다.
timeout이면 남은 세션 수를 포함한 오류를 기록하고 프로세스를 종료합니다.

클라이언트는 server_shutting_down을 재연결 가능한 오류로 처리해야 합니다. 롤링 배포 시 terminationGracePeriodSeconds는 애플리케이션의 10초 timeout보다 짧아서는 안 되며, LB drain 시간도 별도로 고려해야 합니다.

백엔드·provider 오류¶

세션 WSS가 끝나면 해당 WebRTC 세션도 더 이상 정상 처리할 수 없습니다. 특히 통합 브랜치의 OPENAI_REALTIME_DISCONNECTED와 OPENAI_REALTIME_SESSION_EXPIRED 같은 server fault는 진행 중 응답을 실패 terminal로 닫고 세션 자체를 종료합니다. 일반 4xx형 session parameter 오류는 데이터채널 error로 전달하되 오류 종류와 setup 단계에 따라 기존 세션을 유지할 수 있습니다.

종료·연결 상태는 운영·메트릭, ICE 경로는 시그널링·ICE·TURN을 참고하세요.