WebSocket Listener

WebSocket Listener는 연결을 유지하면서 외부 시스템과 Foundry 사이에 메시지를 양방향으로 전달합니다. 실시간 음성이나 전화 통화에서 들어오는 오디오를 처리하고, 생성한 응답 오디오를 같은 연결로 돌려보내는 용도에 적합합니다.

이 기능은 Beta이며 플랫폼 인스턴스에 따라 제공되지 않을 수 있습니다. 사용을 요청하거나 필요한 커넥터가 목록에 없는 경우 Palantir 지원팀에 문의합니다. 개발 중에는 기능이 변경될 수 있습니다.

처리 경로

HTTPS Listener가 요청을 스트림에 기록하는 것과 달리, WebSocket Listener는 Compute Module에 호스팅한 사용자 지정 WebSocket 서버로 연결을 전달합니다. Listener 생성 시 Compute Module이 자동으로 만들어지며, 현재 Listener의 WebSocket 연결을 처리하는 방식은 이 자동 생성된 모듈을 사용하는 것입니다.

Compute Module은 연결이 유지되는 동안 외부 시스템으로 응답을 보낼 수 있습니다. 외부 서비스의 메시지 프로토콜을 처리하는 서버 구현과 필요한 컨테이너를 준비해야 합니다.

Listener와 엔드포인트 생성

1. Data Connection > Listeners에서 Create new listener를 선택합니다.
2. 필요한 WebSocket 커넥터를 선택합니다.

외부 서비스용 커넥터는 전용 하위 도메인을 구성합니다.

1. Control Panel > Domains & certificates에서 Listener 하위 도메인을 생성합니다.
2. 외부 시스템의 IP 범위에서 들어오는 연결을 허용하도록 인바운드 정책을 설정합니다.
3. 하위 도메인을 Listener에 연결하고 승인을 받습니다. 승인 전에는 이 엔드포인트로 요청을 받을 수 없습니다.

Foundry 인증 유형은 기본 플랫폼 도메인을 사용하므로 전용 하위 도메인이 필요하지 않습니다. 이 경우에도 플랫폼의 인바운드 규칙과 Listener 활성화 조건이 적용됩니다.

인증과 보안 표지

Configure connection > Configure security에서 선택한 서비스에 필요한 인증 정보를 설정합니다. 이후 Configure server에서 반출을 허용할 보안 표지(Marking)를 지정합니다.

기본적으로 보안 표지가 없는 데이터만 Compute Module 입력으로 읽을 수 있습니다. 보안 표지가 있는 데이터를 사용하려면 해당 표지를 반출 가능 목록에 명시해야 하며, 그 표지를 해제할 권한이 있는 사용자만 목록에 추가할 수 있습니다. 자세한 권한 경계는 WebSocket 보안에 있습니다.

Compute Module 구성

1. Listener의 Configuration에서 연결된 Compute Module을 엽니다.
2. 서버를 실행할 컨테이너를 구성합니다. Foundry 인증 유형의 서버는 0.0.0.0:5000에 바인딩하고 /에서 WebSocket Upgrade를 받아야 합니다.
3. 필요한 Foundry 리소스를 입력과 출력으로 추가합니다. 모듈에는 기본적으로 리소스 접근 권한이 없으므로 각각 명시적으로 허용해야 합니다.
4. 모듈을 시작하고 Logs에서 서버가 정상적으로 시작되었는지 확인합니다.

지원하는 연결 유형

전용 하위 도메인의 변경 및 엔드포인트 회전은 하위 도메인 운영에서 설명합니다. 하위 도메인을 변경하는 작업은 기존 연결 경로를 즉시 중단시키므로, 만료일을 겹치는 엔드포인트 회전과 구분해야 합니다.