protocol

package
v1.2.3-fred.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 18, 2022 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package protocol implements reading/writing MongoDB wire protocol messages from/to client/server and converting them into parsed data structures.

The official Go MongoDB driver provides low-level wire message parsing primitives this package is built on top of:

https://pkg.go.dev/go.mongodb.org/mongo-driver/x/mongo/driver/wiremessage

MongoDB wire protocol documentation:

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/

We implement a subset of protocol messages: OP_MSG, OP_QUERY and OP_REPLY.

Package layout:

  • message.go: Defines wire message common interface and provides methods for reading wire messages from client/server connections.

  • opmsg.go: Contains marshal/unmarshal for OP_MSG - extensible message that MongoDB 3.6 and higher use for all commands.

  • opquery.go: Contains marshal/unmarshal for OP_QUERY - a legacy command, still used for some operations (e.g. first "isMaster" handshake message).

  • opreply.go: Contains marshal/unmarshal for OP_REPLY - a reply message sent by a database to an OP_QUERY command.

  • errors.go: Provides methods for sending errors in wire message to client connections.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ReadMsgSectionDocumentSequence 

func ReadMsgSectionDocumentSequence(src []byte) (identifier string, docs []bsoncore.Document, rem []byte, ok bool)

ReadMsgSectionDocumentSequence reads multiple documents from the source.

This function works in the same way as wiremessage.ReadMsgSectionDocumentSequence except that it validate the rem index before reading the document.

func ReadReplyDocuments 

func ReadReplyDocuments(src []byte) (docs []bsoncore.Document, rem []byte, ok bool)

ReadReplyDocuments reads multiple documents from the source.

This function works in the same way as wiremessage.ReadReplyDocuments except, it can handle document of size 0. When a document of size 0 is passed to wiremessage.ReadReplyDocuments, it will keep creating empty documents until it uses all system memory/application crash.

func ReplyError 

func ReplyError(clientConn net.Conn, replyTo Message, clientErr error) (err error)

ReplyError sends error wire message to the client.

Types

type Message 

type Message interface {
	// GetHeader returns the wire message header.
	GetHeader() MessageHeader
	// GetBytes returns raw wire message bytes read from the connection.
	GetBytes() []byte
	// ToWire returns the message as wire bytes format.
	ToWire(responseTo int32) []byte
	// MoreToCome is whether sender will send another message right after this one.
	MoreToCome(message Message) bool
	// GetDatabase returns the message's database (for client messages).
	GetDatabase() (string, error)
	// GetCommand returns the message's command (for client messages).
	GetCommand() (string, error)
	// Stringer dumps message in the readable format for logs and audit.
	fmt.Stringer
}

Message defines common interface for MongoDB wire protocol messages.

func ReadMessage 

func ReadMessage(reader io.Reader) (Message, error)

ReadMessage reads the next MongoDB wire protocol message from the reader.

func ReadServerMessage 

func ReadServerMessage(ctx context.Context, conn driver.Connection) (Message, error)

ReadServerMessage reads wire protocol message from the MongoDB server connection.

type MessageHeader 

type MessageHeader struct {
	MessageLength int32
	RequestID     int32
	ResponseTo    int32
	OpCode        wiremessage.OpCode
	// contains filtered or unexported fields
}

MessageHeader represents parsed MongoDB wire protocol message header.

https://docs.mongodb.com/master/reference/mongodb-wire-protocol/#standard-message-header

type MessageOpCompressed 

type MessageOpCompressed struct {
	Header            MessageHeader
	OriginalOpcode    wiremessage.OpCode
	UncompressedSize  int32
	CompressorID      wiremessage.CompressorID
	CompressedMessage []byte
	// contains filtered or unexported fields
}

MessageOpCompressed represents parsed OP_COMPRESSED wire message.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#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
}

func (*MessageOpCompressed) GetBytes 

func (m *MessageOpCompressed) GetBytes() []byte

GetBytes returns the message raw bytes read from the connection.

func (*MessageOpCompressed) GetCommand 

func (m *MessageOpCompressed) GetCommand() (string, error)

GetCommand returns the message's command.

func (*MessageOpCompressed) GetDatabase 

func (m *MessageOpCompressed) GetDatabase() (string, error)

GetDatabase returns database for the wrapped message.

func (*MessageOpCompressed) GetHeader 

func (m *MessageOpCompressed) GetHeader() MessageHeader

GetHeader returns the wire message header.

func (*MessageOpCompressed) GetOriginal 

func (m *MessageOpCompressed) GetOriginal() Message

GetOriginal returns original decompressed message.

func (*MessageOpCompressed) MoreToCome 

func (m *MessageOpCompressed) MoreToCome(msg Message) bool

MoreToCome is whether sender will send another message right after this one.

func (*MessageOpCompressed) String 

func (m *MessageOpCompressed) String() string

String returns the message string representation.

func (*MessageOpCompressed) ToWire 

func (m *MessageOpCompressed) ToWire(responseTo int32) (dst []byte)

ToWire converts this message to wire protocol message bytes.

type MessageOpDelete 

type MessageOpDelete struct {
	Header             MessageHeader
	Zero               int32
	FullCollectionName string
	Flags              int32
	Selector           bsoncore.Document
	// contains filtered or unexported fields
}

MessageOpDelete represents parsed OP_DELETE wire message.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#op_delete 

struct {
    MsgHeader header;             // standard message header
    int32     ZERO;               // 0 - reserved for future use
    cstring   fullCollectionName; // "dbname.collectionname"
    int32     flags;              // bit vector - see below for details.
    document  selector;           // query object.  See below for details.
}

OP_DELETE is deprecated starting MongoDB 5.0 in favor of OP_MSG.

func (*MessageOpDelete) GetBytes 

func (m *MessageOpDelete) GetBytes() []byte

GetBytes returns the message raw bytes read from the connection.

func (*MessageOpDelete) GetCommand 

func (m *MessageOpDelete) GetCommand() (string, error)

GetCommand returns the message's command.

func (*MessageOpDelete) GetDatabase 

func (m *MessageOpDelete) GetDatabase() (string, error)

GetDatabase returns the command's database.

func (*MessageOpDelete) GetHeader 

func (m *MessageOpDelete) GetHeader() MessageHeader

GetHeader returns the wire message header.

func (*MessageOpDelete) MoreToCome 

func (m *MessageOpDelete) MoreToCome(_ Message) bool

MoreToCome is whether sender will send another message right after this one.

func (*MessageOpDelete) String 

func (m *MessageOpDelete) String() string

String returns the message string representation.

func (*MessageOpDelete) ToWire 

func (m *MessageOpDelete) ToWire(responseTo int32) (dst []byte)

ToWire converts this message to wire protocol message bytes.

type MessageOpGetMore 

type MessageOpGetMore struct {
	Header             MessageHeader
	Zero               int32
	FullCollectionName string
	NumberToReturn     int32
	CursorID           int64
	// contains filtered or unexported fields
}

MessageOpGetMore represents parsed OP_GET_MORE wire message.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#op_get_more 

struct {
    MsgHeader header;             // standard message header
    int32     ZERO;               // 0 - reserved for future use
    cstring   fullCollectionName; // "dbname.collectionname"
    int32     numberToReturn;     // number of documents to return
    int64     cursorID;           // cursorID from the OP_REPLY
}

OP_GET_MORE is deprecated starting MongoDB 5.0 in favor of OP_MSG.

func (*MessageOpGetMore) GetBytes 

func (m *MessageOpGetMore) GetBytes() []byte

GetBytes returns the message raw bytes read from the connection.

func (*MessageOpGetMore) GetCommand 

func (m *MessageOpGetMore) GetCommand() (string, error)

GetCommand returns the message's command.

func (*MessageOpGetMore) GetDatabase 

func (m *MessageOpGetMore) GetDatabase() (string, error)

GetDatabase returns the command's database.

func (*MessageOpGetMore) GetHeader 

func (m *MessageOpGetMore) GetHeader() MessageHeader

GetHeader returns the wire message header.

func (*MessageOpGetMore) MoreToCome 

func (m *MessageOpGetMore) MoreToCome(_ Message) bool

MoreToCome is whether sender will send another message right after this one.

func (*MessageOpGetMore) String 

func (m *MessageOpGetMore) String() string

String returns the message string representation.

func (*MessageOpGetMore) ToWire 

func (m *MessageOpGetMore) ToWire(responseTo int32) (dst []byte)

ToWire converts this message to wire protocol message bytes.

type MessageOpInsert 

type MessageOpInsert struct {
	Header             MessageHeader
	Flags              int32
	FullCollectionName string
	Documents          []bsoncore.Document
	// contains filtered or unexported fields
}

MessageOpInsert represents parsed OP_INSERT wire message.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#op_insert 

struct {
    MsgHeader header;             // standard message header
    int32     flags;              // bit vector - see below
    cstring   fullCollectionName; // "dbname.collectionname"
    document* documents;          // one or more documents to insert into the collection
}

OP_INSERT is deprecated starting MongoDB 5.0 in favor of OP_MSG.

func (*MessageOpInsert) GetBytes 

func (m *MessageOpInsert) GetBytes() []byte

GetBytes returns the message raw bytes read from the connection.

func (*MessageOpInsert) GetCommand 

func (m *MessageOpInsert) GetCommand() (string, error)

GetCommand returns the message's command.

func (*MessageOpInsert) GetDatabase 

func (m *MessageOpInsert) GetDatabase() (string, error)

GetDatabase returns the command's database.

func (*MessageOpInsert) GetHeader 

func (m *MessageOpInsert) GetHeader() MessageHeader

GetHeader returns the wire message header.

func (*MessageOpInsert) MoreToCome 

func (m *MessageOpInsert) MoreToCome(_ Message) bool

MoreToCome is whether sender will send another message right after this one.

func (*MessageOpInsert) String 

func (m *MessageOpInsert) String() string

String returns the message string representation.

func (*MessageOpInsert) ToWire 

func (m *MessageOpInsert) ToWire(responseTo int32) (dst []byte)

ToWire converts this message to wire protocol message bytes.

type MessageOpKillCursors 

type MessageOpKillCursors struct {
	Header            MessageHeader
	Zero              int32
	NumberOfCursorIDs int32
	CursorIDs         []int64
	// contains filtered or unexported fields
}

MessageOpKillCursors represents parsed OP_KILL_CURSORS wire message.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#op_kill_cursors 

struct {
    MsgHeader header;            // standard message header
    int32     ZERO;              // 0 - reserved for future use
    int32     numberOfCursorIDs; // number of cursorIDs in message
    int64*    cursorIDs;         // sequence of cursorIDs to close
}

OP_KILL_CURSORS is deprecated starting MongoDB 5.0 in favor of OP_MSG.

func (*MessageOpKillCursors) GetBytes 

func (m *MessageOpKillCursors) GetBytes() []byte

GetBytes returns the message raw bytes read from the connection.

func (*MessageOpKillCursors) GetCommand 

func (m *MessageOpKillCursors) GetCommand() (string, error)

GetCommand returns the message's command.

func (*MessageOpKillCursors) GetDatabase 

func (m *MessageOpKillCursors) GetDatabase() (string, error)

GetDatabase returns the command's database.

func (*MessageOpKillCursors) GetHeader 

func (m *MessageOpKillCursors) GetHeader() MessageHeader

GetHeader returns the wire message header.

func (*MessageOpKillCursors) MoreToCome 

func (m *MessageOpKillCursors) MoreToCome(_ Message) bool

MoreToCome is whether sender will send another message right after this one.

func (*MessageOpKillCursors) String 

func (m *MessageOpKillCursors) String() string

String returns the message string representation.

func (*MessageOpKillCursors) ToWire 

func (m *MessageOpKillCursors) ToWire(responseTo int32) (dst []byte)

ToWire converts this message to wire protocol message bytes.

type MessageOpMsg 

type MessageOpMsg struct {
	Header                   MessageHeader
	Flags                    wiremessage.MsgFlag
	BodySection              SectionBody
	DocumentSequenceSections []SectionDocumentSequence
	Checksum                 uint32
	// contains filtered or unexported fields
}

MessageOpMsg represents parsed OP_MSG wire message.

https://docs.mongodb.com/master/reference/mongodb-wire-protocol/#op-msg 

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

func MakeOpMsg 

func MakeOpMsg(document bsoncore.Document) *MessageOpMsg

MakeOpMsg is a shorthand to create OP_MSG message from a single document.

func (*MessageOpMsg) GetBytes 

func (m *MessageOpMsg) GetBytes() []byte

GetBytes returns the message raw bytes read from the connection.

func (*MessageOpMsg) GetCommand 

func (m *MessageOpMsg) GetCommand() (string, error)

GetCommand returns the message's command.

func (*MessageOpMsg) GetDatabase 

func (m *MessageOpMsg) GetDatabase() (string, error)

GetDatabase returns the message's database.

func (*MessageOpMsg) GetHeader 

func (m *MessageOpMsg) GetHeader() MessageHeader

GetHeader returns the wire message header.

func (*MessageOpMsg) MoreToCome 

func (m *MessageOpMsg) MoreToCome(_ Message) bool

MoreToCome is whether sender will send another message right after this one.

func (*MessageOpMsg) String 

func (m *MessageOpMsg) String() string

String returns the message string representation.

func (*MessageOpMsg) ToWire 

func (m *MessageOpMsg) ToWire(responseTo int32) (dst []byte)

ToWire converts this message to wire protocol message bytes.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#op_msg

type MessageOpQuery 

type MessageOpQuery struct {
	Header               MessageHeader
	Flags                wiremessage.QueryFlag
	FullCollectionName   string
	NumberToSkip         int32
	NumberToReturn       int32
	Query                bsoncore.Document
	ReturnFieldsSelector bsoncore.Document
	// contains filtered or unexported fields
}

MessageOpQuery represents parsed OP_QUERY wire message.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#op_query

OP_QUERY is generally deprecated by MongoDB in favor of extensible OP_MSG message but it still seems to be used by Mongo clients and drivers during initial connection establishment.

func (*MessageOpQuery) GetBytes 

func (m *MessageOpQuery) GetBytes() []byte

GetBytes returns the message raw bytes read from the connection.

func (*MessageOpQuery) GetCommand 

func (m *MessageOpQuery) GetCommand() (string, error)

GetCommand returns the message's command.

func (*MessageOpQuery) GetDatabase 

func (m *MessageOpQuery) GetDatabase() (string, error)

GetDatabase returns the command's database.

func (*MessageOpQuery) GetHeader 

func (m *MessageOpQuery) GetHeader() MessageHeader

GetHeader returns the wire message header.

func (*MessageOpQuery) MoreToCome 

func (m *MessageOpQuery) MoreToCome(_ Message) bool

MoreToCome is whether sender will send another message right after this one.

func (*MessageOpQuery) String 

func (m *MessageOpQuery) String() string

String returns the message string representation.

func (*MessageOpQuery) ToWire 

func (m *MessageOpQuery) ToWire(responseTo int32) (dst []byte)

ToWire converts this message to wire protocol message bytes.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#op_query

type MessageOpReply 

type MessageOpReply struct {
	Header         MessageHeader
	Flags          wiremessage.ReplyFlag
	CursorID       int64
	StartingFrom   int32
	NumberReturned int32
	Documents      []bsoncore.Document
	// contains filtered or unexported fields
}

MessageOpReply represents parsed OP_REPLY wire message.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#op_reply

func MakeOpReply 

func MakeOpReply(document bsoncore.Document) *MessageOpReply

MakeOpReply is a shorthand to create OP_REPLY message from a single document.

func MakeOpReplyWithFlags 

func MakeOpReplyWithFlags(document bsoncore.Document, flags wiremessage.ReplyFlag) *MessageOpReply

MakeOpReplyWithFlags is a shorthand to create OP_REPLY message from a single document with provided flags.

func (*MessageOpReply) GetBytes 

func (m *MessageOpReply) GetBytes() []byte

GetBytes returns the message raw bytes read from the connection.

func (*MessageOpReply) GetCommand 

func (m *MessageOpReply) GetCommand() (string, error)

GetCommand is a no-op for OpReply since this is a server message.

func (*MessageOpReply) GetDatabase 

func (m *MessageOpReply) GetDatabase() (string, error)

GetDatabase is a no-op for OpReply since this is a server message.

func (*MessageOpReply) GetDocumentsAsStrings 

func (m *MessageOpReply) GetDocumentsAsStrings() (documents []string)

GetDocumentsAsStrings is a convenience method to return all message bson documents converted to their string representations.

func (*MessageOpReply) GetHeader 

func (m *MessageOpReply) GetHeader() MessageHeader

GetHeader returns the wire message header.

func (*MessageOpReply) MoreToCome 

func (m *MessageOpReply) MoreToCome(msg Message) bool

MoreToCome is whether sender will send another message right after this one.

func (*MessageOpReply) String 

func (m *MessageOpReply) String() string

String returns the message string representation.

func (*MessageOpReply) ToWire 

func (m *MessageOpReply) ToWire(responseTo int32) (dst []byte)

ToWire converts this message to wire protocol message bytes.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#op_reply

type MessageOpUpdate 

type MessageOpUpdate struct {
	Header             MessageHeader
	Zero               int32
	FullCollectionName string
	Flags              int32
	Selector           bsoncore.Document
	Update             bsoncore.Document
	// contains filtered or unexported fields
}

MessageOpUpdate represents parsed OP_UPDATE wire message.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#op_update 

struct OP_UPDATE {
    MsgHeader header;             // standard message header
    int32     ZERO;               // 0 - reserved for future use
    cstring   fullCollectionName; // "dbname.collectionname"
    int32     flags;              // bit vector. see below
    document  selector;           // the query to select the document
    document  update;             // specification of the update to perform
}

OP_UPDATE is deprecated starting MongoDB 5.0 in favor of OP_MSG.

func (*MessageOpUpdate) GetBytes 

func (m *MessageOpUpdate) GetBytes() []byte

GetBytes returns the message raw bytes read from the connection.

func (*MessageOpUpdate) GetCommand 

func (m *MessageOpUpdate) GetCommand() (string, error)

GetCommand returns the message's command.

func (*MessageOpUpdate) GetDatabase 

func (m *MessageOpUpdate) GetDatabase() (string, error)

GetDatabase returns the command's database.

func (*MessageOpUpdate) GetHeader 

func (m *MessageOpUpdate) GetHeader() MessageHeader

GetHeader returns the wire message header.

func (*MessageOpUpdate) MoreToCome 

func (m *MessageOpUpdate) MoreToCome(_ Message) bool

MoreToCome is whether sender will send another message right after this one.

func (*MessageOpUpdate) String 

func (m *MessageOpUpdate) String() string

String returns the message string representation.

func (*MessageOpUpdate) ToWire 

func (m *MessageOpUpdate) ToWire(responseTo int32) (dst []byte)

ToWire converts this message to wire protocol message bytes.

type Section 

type Section interface {
	GetType() wiremessage.SectionType
	ToWire() []byte
}

Section represents a single OP_MSG wire message section.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#sections

type SectionBody 

type SectionBody struct {
	Document bsoncore.Document
}

SectionBody represents OP_MSG Body section that contains a single bson document.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#kind-0--body

func (*SectionBody) GetType 

func (s *SectionBody) GetType() wiremessage.SectionType

GetType returns this section type.

func (SectionBody) String 

func (s SectionBody) String() string

String returns the section's string representation.

func (*SectionBody) ToWire 

func (s *SectionBody) ToWire() (dst []byte)

ToWire encodes this section to wire protocol message bytes.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#kind-0--body

type SectionDocumentSequence 

type SectionDocumentSequence struct {
	Identifier string
	Documents  []bsoncore.Document
}

SectionDocumentSequence represents OP_MSG Document Sequence section that contains multiple bson documents.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#kind-1--document-sequence

func (*SectionDocumentSequence) GetType 

func (s *SectionDocumentSequence) GetType() wiremessage.SectionType

GetType returns this section type.

func (SectionDocumentSequence) String 

func (s SectionDocumentSequence) String() string

String returns the section's string representation.

func (*SectionDocumentSequence) ToWire 

func (s *SectionDocumentSequence) ToWire() (dst []byte)

ToWire encodes this section to wire protocol message bytes.

https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/#kind-1--document-sequence

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.