MongoDB 유선 프로토콜

이 페이지의 내용

서론

TCP/IP 소켓
메시지 유형과 형식
표준 메시지 헤더
옵코드

참고

이 MongoDB 유선 프로토콜 사양은 Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License에 따라 사용이 허가되었습니다. 이 자료는 상업용 데이터베이스 또는 DBaaS(Database-as-a-Service) 제품군을 만드는 것과 같은 상업적 목적으로 사용하거나 변경할 수 없습니다.

서론

MongoDB 유선 프로토콜은 간단한 소켓 기반, 요청-응답 스타일의 프로토콜입니다. 클라이언트는 일반 TCP/IP 소켓을 통해 데이터베이스 서버와 통신합니다.

TCP/IP 소켓

클라이언트는 일반 TCP/IP 소켓으로 데이터베이스에 연결해야 합니다.

포트

mongod 및 mongos 인스턴스의 기본 포트 번호는 27017입니다. mongod 및 mongos의 포트 번호는 구성 가능하며 다를 수 있습니다.

바이트 순서 지정

MongoDB 유선 프로토콜의 모든 정수는 리틀 엔디안 바이트 순서, 즉 제일 낮은 바이트를 먼저 사용합니다.

메시지 유형과 형식

MongoDB는 클라이언트 요청과 데이터베이스 응답 모두에 OP_MSG 옵코드를 사용합니다. 오래된 MongoDB 버전에서는 사용되었지만 현재는 사용이 중단되고 OP_MSG로 대체된 메시지 형식이 몇 가지 있습니다.

참고

이 페이지에서는 C형 struct를 사용해 메시지 구조를 설명합니다.

이 문서 에서 사용된 유형(예:int32 및)은 cstring BSON 사양에 정의된 유형과 동일합니다.

표준 메시지 헤더

일반적으로 각 메시지에는 표준 메시지 헤더가 있고 그 뒤에 요청별 데이터가 뒤따릅니다. 표준 메시지 헤더의 구조는 다음과 같습니다.

struct MsgHeader {
    int32   messageLength; // total message size, including this
    int32   requestID;     // identifier for this message
    int32   responseTo;    // requestID from the original request
                           //   (used in responses from the database)
    int32   opCode;        // message type
}

필드	설명
`messageLength`	메시지의 총 크기(바이트)입니다. 이 총계에는 메시지 길이를 보관하는 4바이트가 포함됩니다.
`requestID`	메시지를 고유하게 식별하는 클라이언트 또는 데이터베이스 생성 식별자입니다.
`responseTo`	클라이언트가 보낸 메시지에서 가져온 `requestID`입니다.
`opCode`	메시지 유형. 자세한 내용은 옵코드를 참조하세요.

옵코드

MongoDB는 이 opCode 값을 사용합니다.

옵코드 이름	값	Comment
`OP_COMPRESSED`	2012	압축을 사용하여 다른 명령 코드를 래핑합니다.
`OP_MSG`	2013	표준 형식을 사용하여 메시지를 보냅니다. 클라이언트 요청과 데이터베이스 응답 모두에 사용됩니다.
`OP_REPLY` Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.	1	클라이언트 요청에 응답합니다. `responseTo`가 설정되었습니다.
`OP_UPDATE` Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.	2001	Update document.
`OP_INSERT` Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.	2002	새 문서를 삽입합니다.
`RESERVED`	2003	이전에는 OP_GET_BY_OID에 사용되었습니다.
`OP_QUERY` Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.	2004	컬렉션을 쿼리합니다.
`OP_GET_MORE` Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.	2005	쿼리에서 더 많은 데이터를 가져옵니다. 커서를 참조하세요.
`OP_DELETE` Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.	2006	문서를 삭제합니다.
`OP_KILL_CURSORS` Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.	2007	클라이언트가 커서 작업을 완료했음을 데이터베이스에 알립니다.

`OP_COMPRESSED`

모든 옵코드는 OP_COMPRESSED 헤더로 압축하여 래핑할 수 있습니다. OP_COMPRESSED 메시지에는 압축된 원본 옵코드 메시지와 함께 이를 처리하고 압축을 푸는 데 필요한 메타데이터가 포함되어 있습니다.

OP_COMPRESSED 메시지의 형식은 다음과 같습니다.

struct {
    MsgHeader header;            // standard message header
    int32  originalOpcode;       // value of wrapped opcode
    int32  uncompressedSize;     // size of deflated compressedMessage, excluding MsgHeader
    uint8  compressorId;         // ID of compressor that compressed message
    char    *compressedMessage;  // opcode itself, excluding MsgHeader
}

필드	설명
`MsgHeader`	표준 메시지헤더에 설명된 대로 메시지 헤더입니다.
`originalOpcode`	래핑된 옵코드의 값을 포함합니다.
`uncompressedSize`	`compressedMessage`를 제외한 수축된 `MsgHeader`의 크기입니다.
`compressorId`	메시지를 압축한 압축기의 ID입니다. `compressorId` 값 목록이 아래에 제공됩니다.
`compressedMessage`	`MsgHeader`를 제외한 옵코드입니다.

각 압축기에는 다음과 같이 사전 정의된 압축기 ID가 할당됩니다.

compressorId	핸드셰이크 값	설명
`0`	눕	메시지 내용은 압축되지 않습니다. 테스트에 사용됩니다.
`1`	스내피	메시지 내용은 스내피를 사용해 압축됩니다.
`2`	zlib	메시지의 내용은 zlib를 사용하여 압축됩니다.
`3`	zstd	메시지 내용은 zstd를 사용하여 압축됩니다.
`4-255`	예약됨	향후 사용을 위해 예약되었습니다.

`OP_MSG`

OP_MSG 클라이언트 요청과 서버 응답을 모두 유선으로 인코딩하는 데 사용되는 확장 가능한 메시지 형식입니다.

OP_MSG 는 다음과 같은 형식을 갖습니다.

OP_MSG {
    MsgHeader header;           // standard message header
    uint32 flagBits;            // message flags
    Sections[] sections;        // data sections
    optional<uint32> checksum;  // optional CRC-32C checksum
}

필드	설명
`header`	표준 메시지 헤더에 설명된 표준 메시지 헤더입니다.
`flagBits`	플래그 비트에 설명된 대로 메시지 플래그를 포함하는 정수 비트마스크입니다.
`sections`	섹션에 설명된 메시지 본문 섹션입니다.
`checksum`	체크섬에 설명된 대로 선택 사항인 CRC-32C 체크섬입니다.

플래그 비트

flagBits 정수는 OP_MSG의 형식과 동작을 수정하는 비트마스크 인코딩 플래그입니다.

처음 16비트(0~15)는 필수이며, 알 수 없는 비트가 설정된 경우 파서에서 반드시 오류가 발생해야 합니다.

마지막 16비트(16-31)는 선택 사항이며 구문 분석기는 알 수 없는 설정 비트를 모두 무시해야 합니다. 프록시 및 기타 메시지 전달자는 메시지를 전달하기 전에 알 수 없는 선택적 비트를 모두 지워야 합니다.

비트	이름	요청	응답	설명
0	`checksumPresent`	✓	✓	메시지는 CRC-32C [2] 체크섬이 포함된 4 바이트로 끝납니다. 자세한 내용은 체크섬을 참조하세요.
1	`moreToCome`	✓	✓	수신자의 추가 조치 없이 다른 메시지가 이 메시지에 이어서 전송됩니다. 수신자는 전송이 차단되어 교착 상태가 발생할 수 있으므로 `moreToCome`이 0으로 설정된 메시지를 받을 때까지 다른 메시지를 보내지 않아야 합니다. `moreToCome` 비트가 설정된 요청은 회신을 받지 못합니다. 응답은 `exhaustAllowed` 비트가 설정된 요청에 대한 응답으로만 이 설정을 갖습니다.
16	`exhaustAllowed`	✓		클라이언트는 `moreToCome` 비트를 사용하여 이 요청에 대한 여러 응답을 준비합니다. 요청에 이 비트가 설정되어 있지 않으면 서버는 `moreToCome` 비트 세트로 응답을 생성하지 않습니다. 이렇게 하면 요청자의 네트워크 계층이 준비된 경우에만 여러 응답이 전송됩니다.

섹션

OP_MSG 메시지에 하나 이상의 섹션이 포함되어 있습니다. 각 섹션은 해당 유형을 나타내는 kind 바이트로 시작합니다. kind 바이트 이후의 모든 항목이 섹션의 페이로드를 구성합니다.

사용 가능한 섹션의 종류는 다음과 같습니다.

Kind 0: Body

본문 섹션은 단일 BSON 객체로 인코딩됩니다. BSON 객체의 크기는 섹션의 크기로도 사용됩니다. 이 섹션 종류는 표준 명령 요청 및 회신 본문입니다.

모든 최상위 필드에는 고유한 이름이 있어야 합니다.

종류 1: 문서 시퀀스

유형	설명
int32	섹션의 크기(바이트)입니다.
C 문자열	문서 시퀀스 식별자입니다. 모든 현재 명령에서 이 필드는 본문 섹션에서 대체되는 필드(중첩될 수 있음)입니다. 이 필드는 본문 섹션에도 존재하면 안 됩니다.
0개 이상의 BSON 객체	객체는 구분 기호 없이 연속으로 정렬됩니다. 각 객체는 서버의 `maxBSONObjectSize`로 제한됩니다. 모든 객체의 조합은 `maxBSONObjSize`로 제한되지 않습니다. 문서 시퀀스는 `size` 바이트가 소비되면 종료됩니다. 구문 분석기는 이러한 객체를 언어 수준 객체로 변환할 때 시퀀스 식별자가 지정한 경로에 있는 배열로 본문에 병합하도록 선택할 수 있습니다.

Kind 2

이 섹션은 내부 용도로 사용됩니다.

체크섬

각 메시지는 체크섬 자체를 제외한 메시지의 모든 바이트를 포함하는 CRC-32C[2] 체크섬으로 끝날 수 있습니다.

TLS/SSL 연결을 사용하지 않는 경우 mongod 인스턴스와 mongos 인스턴스는 체크섬을 사용하여 메시지를 교환합니다.

TLS/SSL 연결을 사용하는 경우 mongod 인스턴스와 mongos 인스턴스는 체크섬을 건너뜁니다.

드라이버 및 이전 바이너리는 체크섬이 포함된 메시지가 표시되는 경우 체크섬을 무시합니다.

체크섬의 존재 여부는 checksumPresent 플래그 비트로 표시됩니다.

레거시 옵코드

MongoDB 5.1부터는 OP_MSG를 위해 다음 옵코드가 제거되었습니다.

OP_DELETE
OP_GET_MORE
OP_INSERT
OP_KILL_CURSORS
OP_QUERY [1]
OP_REPLY
OP_UPDATE

이전 버전의 MongoDB를 실행 중이고 이전 명령 코드에 대한 자세한 정보가 필요한 경우 레거시 명령 코드를 참조하세요.

각주

[1]	MongoDB 5.1에서는 `OP_QUERY` 찾기 작업과 `OP_QUERY` 명령에 대한 지원이 제거됩니다. 예외적으로 `OP_QUERY` 는 연결 핸드셰이크의 일부로 `hello` 및 `isMaster` 명령을 실행하는 데 계속 지원됩니다.

[2]	(1, 2) 32-비트 CRC는 https://tools.ietf.org/html/rfc4960#page-140에 설명된 대로 Castagnoli 다항식으로 계산됩니다.

돌아가기

제한 및 임계값

레거시 옵코드