Relay 메시지 프로토콜

Understand how the Relay message protocol transmits data between clients and servers in the Relay service.

읽는 시간 3분

최근 업데이트: 한 달 전

프로젝트에서 Relay SDK를 UTP 또는 NGO와 함께 사용하는 경우, Relay 메시지 프로토콜은 기본적으로 지원됩니다. 그러나 대체 엔진이나 네트워킹 솔루션을 사용하려면 먼저 Relay 메시지 프로토콜을 구현해야 합니다. Relay 메시지 프로토콜 세부 사항을 사용하여 Relay 메시지 프로토콜을 구현하십시오. Relay 메시지 프로토콜은 필드 값이 빅 에디안순으로 표현된다고 간주합니다. 이를 '네트워크 순서'라고도 하는데, 가장 중요한 바이트가 가장 먼저 발생한다는 의미입니다. HMAC 서명을 사용하는

BIND

메시지를 제외하면 메시지는 인증되지 않습니다. 플레이어는 동일한 Unity 프로젝트 및 환경에 있는 다른 플레이어와만 서로 연결하고 메시지를 전달할 수 있습니다. Relay는 Unity 환경 전반에서 커뮤니케이션하려는 모든 시도를 거부합니다. 모든 메시지에는 표준 헤더와 메시지별 본문이 있습니다. 표준 헤더와 메시지 본문을 참조하십시오.

메시지 유형


BIND
BIND_RECEIVED
PING
CONNECT_REQUEST
4
5
ACCEPTED
7
8
DISCONNECT
RELAY
CLOSE
ERROR

수락 모드 유형

수락 모드는 연결을 시도하는 클라이언트의 요청을 Relay 서버가 처리하는 방식을 정의합니다. Relay는

AUTO

수락 모드만 지원합니다.

AUTO

연결 모드를 사용하면 용량이 충분한 경우, 즉 연결 수가 허용된 최대 연결 수를 초과하지 않는 경우 Relay 서버가 자동으로 연결을 수락합니다.

코드	이름	설명
`0`	`AcceptModeAuto`	`AcceptModeAuto` 는 클라이언트에 대한 연결이 Relay 서버에서 자동으로 수락된다는 것을 나타냅니다.
`1`		예약됨.

표준 헤더

모든 메시지 유형은 표준 헤더를 공유하며, 표준 헤더에는 서명, Relay 메시지 프로토콜 버전, 패킷 본문에 포함된 메시지가 있습니다.

바이트	1 .. 2	3	4
목적	`Signature`	`Version`	`Type`

다음 표는 표준 헤더에 있는 각 필드를 설명합니다.

필드	유형	설명
`Signature`	[]바이트	`Signature` 는 항상 `0xDA72` 입니다.
`Version`	uint8	`Version` 은 Relay 메시지 프로토콜 버전입니다.최초 릴리스의 경우 이 값은 0이어야 합니다.
`Type`	uint8	`Type` 은 본문에 포함된 메시지 유형을 나타내는 정수입니다. 메시지 유형을 참조하십시오.

메시지 본문

BIND 메시지

BIND

메시지는 클라이언트에서 Relay 서버로 전송되어 특정 할당을 위해 클라이언트 IP와 포트의 매핑을 생성합니다. 클라이언트의 ID를 확인하기 위해 이 메시지를 인증합니다. Allocations 서비스에서 받은 응답에는 클라이언트가

BIND

메시지를 인증하는 데 필요한 정보가 포함되어 있습니다.

BIND

메시지에 대한 Allocations 서비스의 응답은 바인딩 상태를 보여 줍니다. 클라이언트의 IP 주소와 포트가 변경되지 않았다면 클라이언트는 동일한

BIND

메시지를 전송해도 됩니다. 예를 들어 클라이언트가 IP 주소나 포트를 변경한 다음 후속 연결에서

BIND

메시지를 전송하는 경우,

Nonce

값은 이전에 전송한 값보다 커야 합니다.

바이트	1 .. 4	5	6 .. 7	8	9 .. N	N+1 .. 33
목적	헤더(유형 0)	`AcceptMode`	`Nonce`	`ConnectionDataLength`	`ConnectionData`	`HMAC`

다음 표는

BIND

메시지에 있는 각 필드를 설명합니다.

필드	유형	설명
`AcceptMode`	uint8	`AcceptMode` 는 Relay 서버가 할당의 소유자에게 연결하려는 클라이언트의 요청을 처리하는 방식을 정의합니다.현재 `AUTO` 수락 모드만 지원됩니다.수락 모드 유형을 참조하십시오.
`Nonce`	uint16	`Nonce` 는 일회용 암호화 nonce입니다. 이후의 각 `BIND` 메시지는 nonce 값이 증가해야 합니다. 일반적으로 nonce 값은 0부터 시작합니다.
`ConnectionDataLength`	uint8	`ConnectionDataLength` 는 `ConnectionData` 의 바이트 길이를 나타냅니다.최대 허용 값은 255입니다.
`ConnectionData`	[]바이트	`ConnectionData` 는 <madcap:glossaryterm glossterm="relay-glossary.Term4">연결 클라이언트</madcap:glossaryterm>의 암호화된 연결 데이터입니다.필드의 길이는 가변적이며, 최대 길이는 255바이트입니다.
`HMAC`	[32]바이트	`HMAC` 는 해시 기반 메시지 인증 코드로, 알려진 키와 함께 메시지(헤더 포함)의 선행 바이트를 사용하여 생성된 것입니다.인증을 참조하십시오.

보안

Allocations 서비스에서 반환된 비밀 키로 HMAC에 서명해야 합니다. HMAC가 유효하지 않은 경우, Relay 서버는

BIND message

를 거부합니다. Relay 서버는 nonce 값이 유효한지 검사해서 악의적인 행위자의 메시지 리플레이 공격을 완화합니다. Relay 서버에서 nonce가 유효하지 않다고 판단한다면 묵시적으로 nonce를 거부합니다. 클라이언트가

BIND message

로 Relay 서버에 처음 바인드하는 경우, nonce 값은 0이 될 수 있습니다.

BIND_RECEIVED 메시지

Relay 서버는 요청 클라이언트가

BIND message

를 통해 Relay 서버에 성공적으로 바인드되었다는 것을 확인하기 위해 요청 클라이언트에

BIND_RECEIVED

메시지를 전송합니다. 확인을 수신한 후 요청 클라이언트는

CONNECT_REQUEST message

를 사용하여 타겟 클라이언트와 커뮤니케이션을 시작할 수 있습니다.

참고

참고: Relay 서버는 성공적으로 처리된

BIND request

마다 클라이언트에

BIND_RECEIVED

메시지를 전송합니다.

바이트	1 .. 4
목적	헤더(유형 1)

PING 메시지

PING

메시지는 클라이언트 시간 초과를 재설정하여 클라이언트와 Relay 서버 사이의 바인딩을 유지하는 간단한 메시지입니다. Relay 서버는 10초 동안 활동이 없으면 자동으로 클라이언트 연결을 해제합니다. 발송자든 수신자든 해당 클라이언트와 관련되어 Relay 서버가 수신하는 모든 메시지는 이 시간 초과를 재설정합니다. 메시지 빈도가 낮은 게임의 경우, 클라이언트는

PING

메시지를 전송하여 연결 해제 타이머를 재설정할 수 있습니다.

팁

팁: 클라이언트는 연결이 시간 초과되지 않도록 다른 메시지 외에도

PING

메시지를 1-2초마다 전송해야 합니다. Relay를 NGO와 함께 사용하는 경우, 네트워크 관리자가 연결 상태를 자동으로 유지합니다. 하지만 Relay를 UTP와 함께 사용하는 경우, 직접 연결 상태를 유지해야 합니다.

각

PING

메시지에는 클라이언트의 할당 ID와 메시지를 식별하는 임의의 숫자가 있습니다. Relay 서버가 클라이언트로부터

PING

메시지를 받으면, 패킷을 변경하지 않고 클라이언트로 다시 보냅니다. 이를 통해

PING

메시지를 사용하여 연결을 확인하고 라운드 트립 시간을 측정할 수 있습니다. 할당 ID가 만료되어도 Relay 서버는 오류 메시지를 전송하지 않습니다.

경고

경고: 클라이언트는

PING

메시지를 전송하기 전에

BIND

메시지를 통해 Relay 서버에 바인드되어야 합니다. 다음 시나리오에서는 Relay 서버가

ErrClientPlayerMismatch

ERROR

메시지를 반환합니다.

```
BIND
```
메시지를 통해 Relay 서버에 바인드되기 전에 클라이언트가
```
PING
```
메시지를 전송합니다.
클라이언트 IP 주소가 변경된 후 새 IP 주소로 Relay 서버에 리바인드하기 전에 클라이언트가
```
PING
```
메시지를 전송합니다.

바이트	1 .. 4	5 .. 20	21 .. 22
목적	헤더(유형 2)	`AllocationID`	`Number`

다음 표는

PING

메시지에 있는 각 필드를 설명합니다.

필드	유형	설명
`AllocationID`	[16]바이트	`AllocationID` 는 16바이트 UUID로, 핑을 전송하는 할당된 클라이언트를 식별합니다.
`Number`	uint16	`Number` 는 Relay 서버가 클라이언트에 되돌려 보내는 부호 없는 임의의 정수입니다. 클라이언트는 이 값을 사용하여 송수신하는 `PING` 메시지의 상관관계를 파악할 수 있습니다.

CONNECT_REQUEST 메시지

CONNECT_REQUEST

메시지는 요청 클라이언트에서 Relay 서버로 전송되어 타겟 클라이언트에 대한 연결을 구축합니다. 요청 클라이언트가 연결하려는 타겟 플레이어(또는 타겟 클라이언트)는

ToConnectionData

로 표현되며, Relay 서버는 이 데이터의 암호화를 해제하여 연결할 플레이어를 결정합니다.

경고

경고: 타겟 클라이언트와 요청 클라이언트는 동일한 Unity 프로젝트 및 환경에 있어야 합니다.

참고

참고: Relay 서버에는 플레이어 그룹(보통 세션이라고도 함)에 대한 공식적인 개념이 없습니다. 논리적 게임 세션 내의 모든 플레이어는 같은 Relay 서버에 바인드됩니다. 이러한 맥락에서 Relay는 게임 세션과 관련하여 플레이어의 바인딩 및 연결 기간에 대해 어떠한 가정도 하지 않습니다. 세션이 끝날 때 플레이어가 Relay 서버에서 언바인드될 것인지, 아니면 여러 세션에 같은 바인딩을 사용할 것인지는 게임 클라이언트에서 결정합니다.

바이트	1 .. 4	5 .. 20	21	22 ..
목적	헤더(유형 3)	`AllocationID`	`ToConnectionData Length`	`ToConnectionData`

다음 표는

CONNECT_REQUEST

메시지에 있는 각 필드를 설명합니다.

필드	유형	설명
`AllocationID`	[16]바이트	`AllocationID` 는 16바이트 UUID로, 연결을 요청하는 할당된 클라이언트를 식별합니다.
`ToConnectionDataLength`	uint8	`ToConnectionDataLength` 는 `ToConnectionData` 의 바이트 길이입니다.최대 허용 값은 255입니다.
`ToConnectionData`	[]바이트	`ToConnectionData` 는 연결할 클라이언트를 나타내는 암호화된 데이터 블롭입니다. 연결 데이터를 참조하십시오.이 필드의 길이는 가변적이며, 최대 바이트 길이는 255입니다.

ACCEPTED 메시지

Relay 서버는 타겟 클라이언트에 성공적으로 연결한 후에 요청 클라이언트에

ACCEPTED

메시지를 전송합니다.

참고

참고: Relay 서버는 지정된 최대 연결 수보다 타겟 클라이언트에 연결된 수가 적으면 요청 클라이언트에

ACCEPTED

메시지를 반환합니다.

바이트	1 .. 4	5 .. 20	21 .. 36
목적	헤더(유형 6)	`FromAllocationID`	`ToAllocationID`

다음 표는

ACCEPTED

메시지에 있는 각 필드를 설명합니다.

필드	유형	설명
`FromAllocationID`	[16]바이트	`FromAllocationID` 는 16바이트 UUID로, 타겟 클라이언트를 식별합니다.
`ToAllocationID`	[16]바이트	`ToAllocationID` 는 16바이트 UUID로, 연결을 요청한 할당된 클라이언트(요청 클라이언트)를 식별합니다.

DISCONNECT 메시지

DISCONNECT

메시지는

CONNECT_REQUEST

핸드셰이크의 인버스로, 클라이언트가 다른 클라이언트와의 연결을 해제하도록 합니다. 클라이언트는 Relay 서버에

DISCONNECT

메시지를 전송하여 다른 클라이언트와의 연결을 해제할 수 있습니다. Relay 서버가 메시지를 수신하면 요청 클라이언트의 연결된 플레이어 목록에서 지정된 할당 ID를 제거합니다. 또한 Relay 서버는 클라이언트가 연결된 플레이어 매핑을 업데이트하여 요청 클라이언트의 할당 ID를 제거할 수 있도록

DISCONNECT

요청을 호스트 클라이언트에 전달합니다. 그런 다음 Relay 서버는 확인을 위해

DISCONNECT

메시지를 다시 클라이언트에 전송합니다. 메시지 본문의 할당 ID 중 하나가 유효하지 않은 경우, Relay 서버는 대신

ERROR message

를 전송합니다. 클라이언트의 연결이 해제되면 Relay 서버는 해당 클라이언트의 할당 ID로 전송된 모든

RELAY

메시지를 거부합니다. 연결이 해제된 클라이언트는

CONNECT_REQUEST message

를 통해 연결을 다시 구축할 수 있습니다.

참고

참고: 호스트 클라이언트와 연결 클라이언트 모두

DISCONNECT

메시지를 전송할 수 있습니다. 하지만 호스트 클라이언트가

DISCONNECT

메시지를 보낸 경우, 클라이언트는 참여한 플레이어를 새 호스트로 마이그레이션하거나 참여한 플레이어 모두의 연결을 해제해야 합니다. Relay는 호스트 마이그레이션을 처리하지 않습니다.

바이트	1 .. 4	5 .. 20	21 .. 36
목적	헤더(유형 9)	`FromAllocationID`	`ToAllocationID`

다음 표는

DISCONNECT

메시지에 있는 각 필드를 설명합니다.

필드	유형	설명
`FromAllocationID`	[16]바이트	`FromAllocationID` 는 16바이트 UUID로, 연결 종료를 요청하는 할당된 클라이언트(요청 클라이언트)를 식별합니다.
`ToAllocationID`	[16]바이트	`ToAllocationID` 는 16바이트 UUID로, 연결이 종료될 할당된 클라이언트(타겟 클라이언트)를 식별합니다.

RELAY 메시지

클라이언트는

RELAY

메시지를 통해 다른 클라이언트의 IP 주소와 포트를 모르는 상태에서도 임의의 바이트 페이로드가 포함된 메시지를 전송할 수 있습니다. 클라이언트 간에

RELAY

메시지를 전송하기 전에 Relay 서버는 패킷을 전송하는 클라이언트가 이전에

BIND message

를 통해

FromAllocationID

로 인증되었는지 확인합니다. 클라이언트가 이전에 바인드되지 않은 경우, Relay 서버는

ErrClientPlayerMismatch

ERROR

메시지를 반환합니다. 또한 Relay 서버는 두 클라이언트가 이전의

CONNECT_REQUEST

교환을 통해 연결을 구축했는지 확인합니다. 클라이언트가 연결되어 있지 않은 경우, Relay 서버는

ErrNotConnected

ERROR message

를 반환합니다. 모든 유효성 검사를 통과하면 Relay 서버는 전체 메시지를

ToAllocationID

에 그대로 전송합니다. Relay 서버는 확인 메시지를

FromAllocationID

에 전송하지 않습니다.

바이트	1 .. 4	5 .. 20	21 .. 36	37 .. 38	39 ..
목적	헤더(유형 10)	`FromAllocationID`	`ToAllocationID`	`Length`	`Content`

참고

참고:

RELAY

메시지의 최대 길이는 프로토콜 수준에서 보장되지 않고, Relay 서버 자체의 설정에 따라 정의됩니다. 기본 최대 콘텐츠 길이는 **1,400**바이트이며, 따라서

RELAY

메시지의 최대 크기는 1,438바이트입니다.

다음 표는

RELAY

메시지에 있는 각 필드를 설명합니다.

필드	유형	설명
`FromAllocationID`	[16]바이트	`FromAllocationID` 는 16바이트 UUID로, 메시지를 전송하는 할당된 클라이언트(요청 클라이언트)를 식별합니다.
`ToAllocationID`	[16]바이트	`ToAllocateID` 는16바이트 UUID로, 메시지를 수신하는 할당된 클라이언트(타겟 클라이언트)를 식별합니다.
`Length`	uint16	`Length` 는 메시지 콘텐츠의 길이를 바이트 단위로 지정합니다.최댓값은 1,400입니다.
`Content`	[]바이트	`Content` 는 메시지의 콘텐츠입니다.

CLOSE 메시지

CLOSE

메시지는 멱등성 메시지로, 클라이언트가 Relay 서버에서 언바인드되고 할당 해제되도록 합니다. 클라이언트는 게임 세션에서 나가거나 게임 클라이언트를 종료할 때 Relay 서버에

CLOSE

메시지를 전송해야 합니다. 클라이언트는 Relay 서버에 대한 자신의 바인딩만 닫을 수 있으며, 다른 클라이언트의 바인딩은 닫을 수 없습니다. 클라이언트는

CLOSE

메시지를 여러 번 보내서 메시지가 성공적으로 전달될 확률을 높여야 합니다.

CLOSE

메시지는 멱등성 메시지이기 때문에, 클라이언트가 이미 연결 해제된 상태라면 Relay 서버에서

ERROR

메시지를 전송할 위험이 없습니다.

CLOSE

메시지는 할당을 정상적으로 종료할 수 있는 가장 좋은 방법이지만 이 메시지가 성공적으로 전달된다는 보장은 없습니다. Relay 서버가 시간 초과로 클라이언트를 할당 해제할 수도 있기 때문에, Relay 서버가

CLOSE

메시지만 사용하여 클라이언트 할당을 제거하는 것은 아닙니다.

CLOSE

메시지를 전송하는 클라이언트는 앞선

BIND

요청을 통해 Relay 서버에 바인드되어 있어야 합니다. 클라이언트가 Relay 서버에 바인드되어 있지 않거나 클라이언트의 IP 주소가 변경된 경우, Relay 서버는 메시지를 묵시적으로 거부합니다. 의도치 않은 할당 시간 초과를 방지하려면

PING

메시지를 사용하십시오.

참고

참고: 언바인드된 클라이언트도 시간 초과를 통해 만료됩니다. 클라이언트 시간 초과를 참조하십시오.

바이트	1 .. 4	5 .. 20
목적	헤더(유형 11)	`AllocationID`

다음 표는

CLOSE

메시지에 있는 각 필드를 설명합니다.

필드	유형	설명
`AllocationID`	[16]바이트	`AllocationID` 는 16바이트 UUID로, 클라이언트 할당을 식별합니다.

ERROR 메시지

Relay 서버는

ERROR

메시지를 엄격하게 사용하여 클라이언트에 오류가 발생했다고 알립니다.

바이트	1 .. 4	5 .. 20	21
목적	헤더(유형 12)	`AllocationID`	`ErrorCode`

다음 표는

ERROR

메시지에 있는 각 필드를 설명합니다.

필드	유형	설명
`AllocationID`	[16]바이트	`AllocationID` 는 16바이트 UUID로, 클라이언트 할당을 식별합니다.
`ErrorCode`	uint8	`ErrorCode` 는 오류 코드를 나타냅니다. 오류 코드를 참조하십시오.

오류 코드

다음 표는 Relay 서버가 클라이언트에 전송할 수 있는 오류 메시지를 설명합니다.


ErrInvalidProtocolVersion
ErrTimeout
ErrUnauthorized
ErrClientPlayerMismatch
ErrAllocationNotFound
ErrNotConnected
ErrSelfConnectNotAllowed

코드	이름	설명
`0`	`BIND 메시지`	`BIND` 메시지는 클라이언트에서 Relay 서버로 전송된 바인드 요청을 나타냅니다.
`1`	`BIND_RECEIVED 메시지`	`BIND_RECEIVED` 메시지는 `BIND 요청` 을 수신한 후 Relay 서버가 클라이언트에 응답 성공을 알리는 메시지입니다.
`2`	`PING 메시지`	`PING` 메시지는 연결 상태를 유지하기 위해서 클라이언트와 Relay 서버 간에 양방향으로 전송하는 핑 메시지를 말합니다.
`3`	`CONNECT_REQUEST 메시지`	`CONNECT_REQUEST` 메시지는 다른 플레이어(타겟 클라이언트)에게 연결하라는 플레이어(요청 클라이언트)의 요청을 나타냅니다.
`4`	예약됨.
`5`	예약됨.
`6`	`ACCEPTED 메시지`	`ACCEPTED` 메시지는 타겟 클라이언트에 성공적으로 연결한 후에 Relay 서버에서 요청 클라이언트에 보내는 확인 메시지를 나타냅니다.
`7`	예약됨.
`8`	예약됨.
`9`	`DISCONNECT 메시지`	`DISCONNECT` 메시지는 연결된 두 플레이어의 연결을 해제하라는 요청을 나타냅니다.
`10`	`RELAY 메시지`	`RELAY` 메시지는 두 플레이어(클라이언트) 사이의 메시지 전송 요청을 나타냅니다.
`11`	`CLOSE 메시지`	`CLOSE` 메시지는 Relay 서버에서 언바인드하라는 클라이언트의 요청을 나타냅니다.
`12`	`ERROR 메시지`	`ERROR` 메시지는 오류가 발생했음을 나타냅니다.

코드	이름	설명
`0`	잘못된 프로토콜 버전( `ErrInvalidProtocolVersion` )	`ErrInvalidProtocolVersion` 은 파싱된 메시지에 예상치 못한 프로토콜 버전이 있을 때 반환됩니다.
`1`	비활성 상태로 인한 플레이어 시간 초과( `ErrTimeout` )	`ErrTimeout` 은 Relay 서버에 대한 클라이언트의 바인딩이 시간 초과되었을 때 반환됩니다. 클라이언트 시간 초과를 참조하십시오.이 오류를 방지하려면 클라이언트는 `PING 메시지` 를 사용해야 합니다.
`2`	권한 없음( `ErrUnauthorized` )	`ErrUnauthorized` 는 클라이언트에서 수행할 권한이 없는 작업을 수행하려고 할 때 반환됩니다.
`3`	할당 ID 클라이언트 불일치( `ErrClientPlayerMismatch` )	`ErrClientPlayerMismatch` 는 클라이언트가 알 수 없는 네트워크 연결을 사용하여 서버에 `RELAY` 메시지를 전송했을 때 반환됩니다.이 오류의 목적은 클라이언트에서 사용 중인 IP 주소가 Relay 서버가 알고 있는 주소에서 변경되었음을 알리는 것입니다.이 오류 메시지는 클라이언트가 새 `BIND 메시지` 를 통해 리바인드해야 함을 의미합니다.
`4`	할당 ID를 찾을 수 없음( `ErrAllocationNotFound` )	`ErrAllocationNotFound` 는 Relay 서버가 지정된 할당 ID에 대한 할당을 찾을 수 없을 때 반환됩니다.
`5`	연결되지 않음( `ErrNotConnected` )	`ErrNotConnected` 는 클라이언트가 연결되지 않은 클라이언트와 커뮤니케이션하려고 할 때 반환됩니다.
`6`	허용되지 않은 자체 연결( `ErrSelfConnectNotAllowed` )	`ErrSelfConnectNotAllowed` 는 클라이언트가 동일한 할당 ID를 가진 클라이언트에 `CONNECT_REQUEST 메시지` 를 전송할 때 반환됩니다.

기술 자료

엔진

서비스

Grow

산업 분야

지원

Relay

Relay

Relay 메시지 프로토콜

메시지 유형

수락 모드 유형

표준 헤더

메시지 본문

BIND 메시지

보안

BIND_RECEIVED 메시지

PING 메시지

CONNECT_REQUEST 메시지

ACCEPTED 메시지

DISCONNECT 메시지

RELAY 메시지

CLOSE 메시지

ERROR 메시지

오류 코드