시그널링·ICE·TURN¶

비-트리클 SDP 계약¶

POST /v1/realtime/calls는 offer SDP 본문을 받고 answer SDP를 반환합니다. 양쪽 모두 후보를 SDP에 모아 한 번에 교환하는 비-트리클 ICE 흐름을 사용합니다. 별도 candidate PATCH/POST 엔드포인트는 없습니다.

sequenceDiagram
    autonumber
    participant C as 클라이언트
    participant G as Gateway HTTP
    participant B as socket-backend /sohri
    participant P as Pion PeerConnection
    participant STUN as STUN / 선택적 TURN

    C->>C: PeerConnection, 오디오 트랙, oai-events 생성
    C->>C: createOffer + setLocalDescription
    C->>STUN: 로컬 ICE 후보 수집
    STUN-->>C: host/srflx/(선택 시 relay) 후보
    C->>C: ICE gathering 완료 대기
    C->>G: POST offer SDP + Bearer credential
    G->>B: WSS /sohri + 같은 Bearer
    B-->>G: 101 Switching Protocols (인증 성공)
    G->>P: PeerConnection 생성 후 offer 적용
    P->>STUN: Gateway ICE 후보 수집
    STUN-->>P: host/srflx 후보
    G->>G: GatheringCompletePromise 완료 대기
    G-->>C: 201 application/sdp + 완성 answer
    C->>C: setRemoteDescription(answer)
    C->>P: ICE/DTLS/SRTP/SCTP 연결
    P-->>C: 양방향 미디어·데이터채널

Note

백엔드 WSS 인증이 먼저입니다. credential이 401 또는 403으로 거절되면 PeerConnection, 트랙, ICE agent를 만들지 않고 SDP 요청을 401로 끝냅니다.

요청 형식¶

POST /v1/realtime/calls HTTP/1.1
Authorization: Bearer <sr_... 또는 client-secret JWT>
Content-Type: application/sdp

v=0
...

성공 응답은 201 Created, Content-Type: application/sdp입니다. offer 본문 상한은 1 MiB이며 빈 본문이나 유효하지 않은 세션 쿼리는 400입니다. 상세 상태 코드는 엔드포인트 참조를 참고하세요.

ICE 서버와 후보¶

코드 기본값은 STUN_URL=stun:stun.l.google.com:19302입니다. Gateway는 이 URL 하나를 Pion ICEServer에 넣습니다.

NAT_1TO1_IP가 없으면 Pion이 로컬 인터페이스 host 후보를 수집합니다.
값이 있으면 해당 외부 IP를 host 후보로 광고합니다.
UDP_PORT_MIN과 UDP_PORT_MAX가 모두 양수이면 Gateway 미디어 포트를 그 범위로 제한합니다.
LB·방화벽 허용 범위와 Pion 범위가 다르면 SDP는 성공해도 ICE가 연결되지 않습니다.

표준 배포의 기본은 STUN으로 srflx 후보를 얻고 Gateway UDP로 직접 연결하는 방식입니다. 시그널링 HTTPS 경로와 SRTP UDP 경로는 서로 다른 Load Balancer를 사용할 수 있습니다.

coturn의 위치¶

coturn은 Gateway 프로세스 밖의 선택적 STUN/TURN 인프라입니다. 대칭 NAT, 기업망 UDP 제한 등으로 직접 후보가 실패할 때 relay 후보를 제공합니다.

현재 통합 브랜치의 Gateway 설정은 STUN_URL 한 개와 URL만 지원하며 TURN username/credential 필드는 없습니다. 따라서 인증형 coturn을 Gateway 측 ICE server로 사용하려면 배포 계층에서 지원되는 인증 방식이 있어야 하거나 코드·설정 확장이 필요합니다. 클라이언트 측 PeerConnection ICE 서버에 coturn을 주입하는 것도 별도 클라이언트 책임입니다. coturn이 존재한다고 자동으로 relay 후보가 생기지는 않습니다.

배포 점검¶

answer SDP의 후보 IP가 외부에서 도달 가능한지 확인합니다.
후보 포트가 UDP_PORT_MIN..UDP_PORT_MAX 안인지 확인합니다.
UDP LB backend가 모든 미디어 노드로 연결되는지 확인합니다.
host networking 사용 시 포트 충돌과 노드 방화벽을 확인합니다.
connected → disconnected 전환 후 기본 10초 안에 복구되는지 확인합니다.

ICE는 연결 설정일 뿐 미디어 변환은 하지 않습니다. 코덱과 청크 계약은 미디어 파이프라인에 설명되어 있습니다.