Protocolo de conexão do MongoDB

Nesta página

Introdução

Soquete TCP/IP
Tipos e formatos de mensagens
Cabeçalho de Mensagem Padrão
Códigos de Operação

Observação

Esta Especificação do Protocolo de Fio MongoDB está licenciada sob uma Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Licença dos Estados Unidos . Você não pode usar ou adaptar este material para qualquer finalidade comercial, como criar um banco de dados comercial ou uma oferta de banco de dados como serviço.

Introdução

O MongoDB Wire Protocol é um protocolo simples de estilo solicitação-resposta baseado em soquete. Os clientes se comunicam com o servidor do banco de dados por meio de um soquete TCP/IP regular.

Soquete TCP/IP

Os clientes devem se conectar ao banco de dados com um soquete TCP/IP regular.

Porta

O número de porta padrão para instâncias do mongod e mongos é 27017. O número da porta para mongod e mongos é configurável e pode variar.

Ordenação de bytes

Todos os números inteiros no protocolo de conexão do MongoDB usam a ordem de bytes little-endian: ou seja, primeiro o byte menos significativo.

Tipos e formatos de mensagens

O MongoDB usa o código de operação OP_MSG para solicitações de clientes e respostas ao banco de dados. Existem vários formatos de mensagem usados em versões mais antigas do MongoDB que foram preteridos em favor de OP_MSG.

Observação

Esta página usa um struct tipo C para descrever a estrutura da mensagem.

Os tipos utilizados neste documento (por exemplo, int32) são os mesmos definidos na especificação BSON.

Cabeçalho de Mensagem Padrão

Em geral, cada mensagem consiste em um cabeçalho de mensagem padrão seguido de dados específicos do solicitante. O cabeçalho da mensagem padrão é estruturado da seguinte forma:

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
}

Campo	Descrição
`messageLength`	O tamanho total da mensagem em bytes. Este total inclui os bytes que contêm o comprimento da mensagem.
`requestID`	Um identificador gerado pelo cliente ou pelo banco de dados que identifica exclusivamente a mensagem.
`responseTo`	O `requestID` retirado das mensagens do cliente.
`opCode`	Tipo de mensagem. Consulte Códigos de opção para obter detalhes.

Códigos de Operação

O MongoDB usa estes valores opCode:

Nome do Código de Operação	Valor	Comentário
`OP_COMPRESSED`	2012	Envolve outros códigos de operação usando compressão
`OP_MSG`	2013	Envie uma mensagem usando o formato padrão. Usado para solicitações do cliente e respostas do banco de dados.
`OP_REPLY` Preterido no MongoDB 5.0. Removido no MongoDB 5.1.	1	Responda a uma solicitação do cliente. `responseTo` está definido.
`OP_UPDATE` Preterido no MongoDB 5.0. Removido no MongoDB 5.1.	2001	Atualizar documento.
`OP_INSERT` Preterido no MongoDB 5.0. Removido no MongoDB 5.1.	2002	Inserir novo documento.
`RESERVED`	2003	Anteriormente usado para OP_GET_BY_OID.
`OP_QUERY` Preterido no MongoDB 5.0. Removido no MongoDB 5.1.	2004	Consultar uma coleção.
`OP_GET_MORE` Preterido no MongoDB 5.0. Removido no MongoDB 5.1.	2005	Obtenha mais dados de uma consulta. Consulte Cursores.
`OP_DELETE` Preterido no MongoDB 5.0. Removido no MongoDB 5.1.	2006	Excluir documentos.
`OP_KILL_CURSORS` Preterido no MongoDB 5.0. Removido no MongoDB 5.1.	2007	Notifique o banco de dados que o cliente terminou com o cursor.

`OP_COMPRESSED`

Novidades na versão MongoDB: 3,4

Qualquer código de opção pode ser comprimido e envolto em um cabeçalho OP_COMPRESSED. A mensagem OP_COMPRESSED contém a mensagem de opcode comprimida original juntamente com os metadados necessários para processá-la e descompactá-la.

O formato da mensagem 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
}

Campo	Descrição
`MsgHeader`	Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão.
`originalOpcode`	Contém o valor do código de operação envolto.
`uncompressedSize`	O tamanho do `compressedMessage` deflacionado, que exclui o `MsgHeader`.
`compressorId`	O ID do compressor que comprimiu a mensagem. Uma lista de `compressorId` valores é fornecida abaixo.
`compressedMessage`	O código de operação em si, excluindo o `MsgHeader`.

Cada compressor recebe um ID de compressor pré-definido da seguinte forma:

compressorId	Valor do Handshake	Descrição
`0`	noop	O conteúdo da mensagem é descompactado. Isso é usado para testar.
`1`	snappy	O conteúdo da mensagem é comprimido usando snappy.
`2`	zlib	O conteúdo da mensagem é comprimido usando zlib.
`3`	zstd	O conteúdo da mensagem é comprimido usando zstd.
`4-255`	reservado	Reservado para uso futuro.

`OP_MSG`

OP_MSG é um formato de mensagem extensível usado para codificar as solicitações do cliente e as respostas do servidor no fio.

OP_MSG tem o seguinte formato:

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

Campo	Descrição
`header`	Cabeçalho de mensagem padrão, conforme descrito em Cabeçalho de mensagem padrão.
`flagBits`	Uma máscara de bits inteiros contendo sinalizadores de mensagem, conforme descrito em Bits de sinalização.
`sections`	Seções do corpo da mensagem, conforme descrito em Seções.
`checksum`	Uma soma de verificação CRC-32C opcional, conforme descrito em Soma de verificação.

Sinalizar Bits

O número inteiro flagBits é um sinalizador de codificação bitmask que modifica o formato e comportamento de OP_MSG.

Os primeiros 16 bits (0-15) são obrigatórios e os analisadores DEVEM apresentar erro se um bit desconhecido for definido.

Os últimos 16 bits (16-31) são opcionais, e os analisadores DEVEM ignorar qualquer conjunto de bits desconhecido. Os proxies e outros encaminhadores de mensagens DEVEM limpar todos os bits opcionais desconhecidos antes de encaminhar as mensagens.

Bit	Nome	Solicitar	Resposta	Descrição
0	`checksumPresent`	✓	✓	A mensagem termina com 4 bytes contendo uma soma de verificação CRC-32C [2] . Consulte Checksum para obter detalhes.
1	`moreToCome`	✓	✓	Outra mensagem seguirá esta sem qualquer ação adicional do receptor. O receptor NÃO DEVE enviar outra mensagem até receber uma com `moreToCome` definido como 0, pois os envios podem bloquear, causando impasse. As solicitações com o conjunto de `moreToCome` bits não receberão uma resposta. As respostas só terão esta definição em resposta a pedidos com o conjunto de `exhaustAllowed` bits.
16	`exhaustAllowed`	✓		O cliente está preparado para múltiplas respostas a esta solicitação usando o bit `moreToCome`. O servidor nunca produzirá respostas com o bit `moreToCome` definido, a menos que a solicitação tenha esse bit definido. Isso garante que várias respostas só sejam enviadas quando a camada de rede do solicitante estiver preparada para eles.

Seções

Uma mensagem OP_MSG contém uma ou mais seções. Cada seção começa com um byte kind indicando seu tipo. Tudo após o byte de kind constitui a carga útil da seção.

Seguem os tipos de seções disponíveis.

Tipo 0: Corpo

Uma seção do corpo é codificada como um único objeto BSON. O tamanho no objeto BSON também serve como tamanho da seção. Este tipo de seção é a solicitação de comando padrão e o corpo de resposta.

Todos os campos de nível superior DEVEM ter um nome exclusivo.

Tipo 1: Sequência de Documentos

Tipo	Descrição
int32	Tamanho da seção em bytes.
Cadeia C	Identificador de sequência do documento. Em todos os comandos atuais este campo é o campo (possivelmente aninhado) que ele está substituindo da seção do corpo. Este campo NÃO PODE existir na seção do corpo.
Zero ou mais objetos BSON	Objetos são sequenciados de trás para frente sem separadores. Cada objeto é limitado a `maxBSONObjectSize` do servidor. A combinação de todos os objetos não está limitada a `maxBSONObjSize`. A sequência do documento termina assim que bytes `size` forem consumidos. Os analisadores PODEM optar por mesclar esses objetos no corpo como uma array no caminho especificado pelo identificador de sequência ao converter em objetos de nível de idioma.

Tipo 2

Esta seção é usada para fins internos.

Checksum

Cada mensagem PODE terminar com uma soma de verificação CRC-32C [2] que abrange todos os bytes da mensagem, exceto a própria soma de verificação.

Se você não usar conexões TLS/SSL, as instâncias mongod e mongos trocarão mensagens com checksums.

Se você usar conexões TLS/SSL, as instâncias mongod e mongos ignorarão a soma de verificação.

Drivers e binários mais antigos ignorarão a soma de verificação se houver mensagens com soma de verificação.

A presença de uma checksum é indicada pelo bit de sinalização checksumPresent.

Códigos operacionais legados

A partir do MongoDB 5.1, estes códigos de operação são removidos a favor de OP_MSG:

OP_DELETE
OP_GET_MORE
OP_INSERT
OP_KILL_CURSORS
OP_QUERY [1]
OP_REPLY
OP_UPDATE

Se você estiver executando uma versão mais antiga do MongoDB e precisar de informações detalhadas sobre os opcodes anteriores, consulte Opcodes legados.

Notas de rodapé

[1]	O MongoDB 5.1 remove o suporte para `OP_QUERY` operações de localização e comandos `OP_QUERY`. Como uma exceção, o `OP_QUERY` ainda é suportado para executar os comandos `hello` e `isMaster` como parte do handshake de conexão.

[2]	(1, 2) 32-bit CRC computado com o polinômio Castagnoli conforme descrito por https://tools.ietf.org/html/rfc4960#page-140.

← Parâmetros do servidor MongoDB

Códigos operacionais legados →