MessagePack protocol

Introduction

MsgPack (aka “MessagePack”) is a binary exchange format that provides better performance and lower bandwidth usage comparing to JSON. To make a struct MsgPack-compatible, add tags to the struct in the same way you add JSON tags.

NOTE: For the post-4.4 control-plane msgpack coverage that spans multiple packages and uses *_wire.go and *_msg.go, see scripts/msgp/README.md.

Example from cmn/objlist.go:

1
type LsObjEntry struct {
2
	Name      string `json:"name" msg:"n"`
3
	Size      int64  `json:"size,string,omitempty" msg:"s,omitempty"`
4
	// the rest struct fields

Note msg:"n" tag value - in the resulting binary data, the field Name is marked with n title.

Code generation

After you change a struct that supports MsgPack, encoding and decoding functions are not updated automatically. You have to run MsgPack generator for the changed file.

First, install the generator if you haven’t done it yet:

1
$ make msgp-update

Second, generate the encoding and decoding functions. For better compatibility and to minimize the diff size, use the same flags as in the example:

1
$ msgp -file <PATH_TO_CHANGED_FILE> -tests=false -marshal=false -unexported

When the generation completes, msgp creates a file with the original name and _gen prefix. Do not forget to prepend a common AIS header to the generated file and commit it to the repository.

Workflow example:

1
$ ls cmn/objlist*
2
objlist.go
3
$ msgp -file cmn/objlist.go -tests=false -marshal=false -unexported
4
5
$ ls cmn/objlist*
6
objlist.go  objlist.go