MongoDB Wire ProtocolMongoDB有线协议
On this page本页内容
This MongoDB Wire Protocol Specification is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License本MongoDB Wire协议规范是根据知识共享归因非商业性股票3.0美国许可证.
授权的。
You may not use or adapt this material for any commercial purpose, such as to create a commercial database or database-as-a-service offering.您不得将本材料用于任何商业目的,例如创建商业数据库或数据库即服务。
Introduction介绍
The MongoDB Wire Protocol is a simple socket-based, request-response style protocol. Clients communicate with the database server through a regular TCP/IP socket.MongoDB Wire协议是一个简单的基于套接字的请求-响应风格的协议。客户端通过常规TCP/IP套接字与数据库服务器通信。
TCP/IP SocketTCP/IP套接字
Clients should connect to the database with a regular TCP/IP socket.客户端应使用常规TCP/IP套接字连接到数据库。
Port端口
The default port number for mongod
and mongos
instances is 27017. mongod
和mongos
实例的默认端口号是27017。The port number for mongod
and mongos
is configurable and may vary.mongod
和mongos
的端口号是可配置的,可能会有所不同。
Byte Ordering字节排序
All integers in the MongoDB wire protocol use little-endian byte order: that is, least-significant byte first.MongoDB wire协议中的所有整数都使用小端字节顺序:也就是说,最低有效字节优先。
Messages Types and Formats消息类型和格式
MongoDB uses the OP_MSG opcode for both client requests and database replies. MongoDB对客户端请求和数据库回复都使用OP_MSG操作码。There are several message formats used in older versions of MongoDB which have been deprecated in favor of 旧版本的MongoDB中使用了几种消息格式,这些格式已被弃用,取而代之的是OP_MSG
.OP_MSG
。
This page uses a C-like 此页面使用类似C的struct
to describe the message structure.struct
来描述消息结构。
The types used in this document (for example, 本文档中使用的类型(例如,int32
) are the same as those defined in the BSON specification.
int32
)与BSON规范中定义的类型相同。
Standard Message Header标准邮件头
In general, each message consists of a standard message header followed by request-specific data. 通常,每条消息都包含一个标准消息头,后跟特定于请求的数据。The standard message header is structured as follows:标准消息头的结构如下:
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 | |
requestID | |
responseTo | requestID taken from the messages from the client.requestID 。 |
opCode |
Opcodes机器码
MongoDB uses these MongoDB使用以下opCode
values:opCode
值:
OP_COMPRESSED | 2012 | |
OP_MSG | 2013 | |
OP_REPLY | 1 | responseTo is set.responseTo 已设置。 |
OP_UPDATE | 2001 | |
OP_INSERT | 2002 | |
RESERVED | 2003 | |
OP_QUERY | 2004 | |
OP_GET_MORE | 2005 | |
OP_DELETE | 2006 | |
OP_KILL_CURSORS | 2007 |
OP_COMPRESSED
New in version MongoDB: 3.4
Any opcode can be compressed and wrapped in an 任何操作码都可以压缩并封装在OP_COMPRESSED
header. OP_compressed
头中。The OP_COMPRESSED
message contains the original compressed opcode message alongside the metadata necessary to process and decompress it.OP_COMPRESSED
消息包含原始压缩操作码消息以及处理和解压缩它所需的元数据。
The format of the OP_COMPRESSED
message is: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 , which excludes the MsgHeader .compressedMessage 的大小,不包括MsgHeader 。 |
compressorId | compressorId values is provided below.compressorId 值的列表。 |
compressedMessage | MsgHeader .MsgHeader 。 |
Each compressor is assigned a predefined compressor ID as follows:每个压缩程序都分配了一个预定义的压缩程序ID,如下所示:
0 | noop | |
1 | snappy | |
2 | zlib | |
3 | zstd | |
4-255 | reserved |
OP_MSG
OP_MSG
is an extensible message format used to encode both client requests and server replies on the wire.是一种可扩展的消息格式,用于对网络上的客户端请求和服务器回复进行编码。
OP_MSG
has the following format:具有以下格式:
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 |
Flag Bits标志位
The flagBits
integer is a bitmask encoding flags that modify the format and behavior of OP_MSG
.flagBits
整型是对修改OP_MSG
的格式和行为的标志进行编码的位掩码。
The first 16 bits (0-15) are required and parsers MUST error if an unknown bit is set.前16位(0-15)是必需的,如果设置了未知位,则解析器必须出错。
The last 16 bits (16-31) are optional, and parsers MUST ignore any unknown set bits. 最后16位(16-31)是可选的,解析器必须忽略任何未知的设置位。Proxies and other message forwarders MUST clear any unknown optional bits before forwarding messages.在转发消息之前,代理和其他消息转发器必须清除任何未知的可选位。
Bit | Request | Response | ||
---|---|---|---|---|
0 | checksumPresent | ✓ | ✓ | |
1 | moreToCome | ✓ | ✓ | moreToCome set to 0 as sends may block, causing deadlock. moreToCome 设置为0的消息之前,接收方不得再发送另一条消息,因为发送可能会阻塞,从而导致死锁。moreToCome bit set will not receive a reply. moreToCome 位的请求将不会收到回复。exhaustAllowed bit set.exhaustAllowed 位的请求时才会有此设置。 |
16 | exhaustAllowed | ✓ | moreToCome bit. moreToCome 位对此请求进行多次回复。moreToCome bit set unless the request has this bit set.moreToCome 位,否则服务器永远不会生成带有该位的回复。 |
Sections
An OP_MSG
message contains one or more sections. OP_MSG
消息包含一个或多个部分。Each section starts with a 每个部分都以一个指示其类型的kind
byte indicating its type. kind
字节开始。Everything after the kind
byte constitutes the section's payload.kind
字节之后的所有内容都构成了部分的有效负载。
The available kinds of sections follow.以下是可用的部分类型。
Kind 0: Body
A body section is encoded as a single BSON object. 主体部分被编码为单个BSON对象。The size in the BSON object also serves as the size of the section. BSON对象中的大小也用作截面的大小。This section kind is the standard command request and reply body.此部分类型是标准的命令请求和回复主体。
All top-level fields MUST have a unique name.所有顶级字段必须具有唯一的名称。
Kind 1: Document Sequence类型1:文档序列
int32 | |
C String | |
|
Kind 2
This section is used for internal purposes.本节用于内部目的。
Checksum校验和
Each message MAY end with a CRC-32C [2] checksum that covers all bytes in the message except for the checksum itself.每个消息可能以CRC-32C[2]校验和结束,该校验和覆盖消息中除校验和本身之外的所有字节。
Starting in MongoDB 4.2:从MongoDB 4.2开始:
如果不使用TLS/SSL连接,mongod
instances andmongos
instances will exchange messages with checksums if not using TLS/SSL connection.mongod
实例和mongos
实例将使用校验和交换消息。如果使用TLS/SSL连接,mongod
instances andmongos
instances will skip the checksum if using TLS/SSL connection.mongod
实例和mongos
实例将跳过校验和。
Drivers and older binaries will ignore the checksum if presented with messages with checksum.如果显示带有校验和的消息,则驱动程序和较旧的二进制文件将忽略校验和。
The presence of a checksum is indicated by the 校验和的存在由checksumPresent
flag bit.checksumPresent
标志位指示。
Legacy Opcodes遗留操作码
Starting in MongoDB 5.1, these opcodes are removed in favor of OP_MSG:从MongoDB 5.1开始,为了支持OP_MSG,删除了这些操作码:
OP_DELETE
OP_GET_MORE
OP_INSERT
OP_KILL_CURSORS
OP_QUERY
[1]OP_REPLY
OP_UPDATE
If you are running an older version of MongoDB and need detailed information on the previous opcodes, see Legacy Opcodes.如果您运行的是旧版本的MongoDB,并且需要有关以前操作码的详细信息,请参阅遗留操作码。
Opcode Considerations操作码注意事项
In version 4.2, MongoDB removes the deprecated internal 在4.2版本中,MongoDB删除了不推荐使用的内部OP_COMMAND
and OP_COMMANDREPLY
protocol.OP_COMMAND
和OP_COMMANDREPLY
协议。
Footnotes脚注
[1] | OP_QUERY find operations and OP_QUERY commands. OP_QUERY 查找操作和OP_QUERY 命令的支持。OP_QUERY is still supported for running the hello and isMaster commands as part of the connection handshake.OP_QUERY 仍然支持作为连接握手的一部分运行hello 和isMaster 命令。 |
[2] | (1, 2) |