[go] shamaton/msgpack で Extension Type を使う

github.com/shamaton/msgpack で Extension Type を使いたいときの encoder/decoder の追加方法のメモ。

msgpack extension types の仕様

この仕様に従う。

環境

go version devel go1.25-583d586ef9 Wed Mar 5 03:28:07 2025 -0800 darwin/arm64
github.com/shamaton/msgpack/v2 v2.2.3

サンプルコード

以下にサンプルコード全体を置いておく。対象データを msgpack 形式で encode し、さらに decode で元データに戻している。

https://github.com/egawata/hatena_blog/blob/master/go/msgpack_ext/main.go

なおサンプルとしての簡潔性を優先し、エラーハンドリングは最小限としている。
実際には元データのバリデーションなどを適切に行う必要がある。

実行結果は以下の通り。msgpack 形式のデータと、それを内部表現に戻したものが出力されている。


bash-3.2$ go run main.go
    0: 81a85072 6f66696c 657392c7 0b010541 6c696365 02656e6a 61c70901 03426f62  | ░░Profiles░░░░░Alice░enja░░░░Bob
   32: 02656e66 72                                                              | ░enfr

decoded: main.ProfileList{Profiles:[]main.Profile{main.Profile{Name:"Alice", Languages:map[string]struct {}{"en":struct {}{}, "ja":struct {}{}}}, main.Profile{Name:"Bob", Languages:map[string]struct {}{"en":struct {}{}, "fr":struct {}{}}}}}

対象の型

今回は以下の Profile 型を msgpack 形式にする想定とする。

type Profile struct {
    Name      string
    Languages map[string]struct{}
}

Name: ユーザ名。アルファベット1 - 255文字。
Languages: そのユーザが使用できる言語をアルファベット2文字で表したもの。en ja など。
- 言語名を key とし、value が空(struct{}{}) の map で表現
- key は0個以上、255個を超えないものとする

例えば以下のような内容が格納される。

    h := &Profile{
        Name:      "Alice",
        Languages: map[string]struct{}{"en": {}, "ja": {}},
    }

Extension type を決める

msgpack/spec.md at master · msgpack/msgpack

Applications can assign 0 to 127 to store application-specific type information.

Extension type は、0 から 127 までの中から、アプリケーション内で一意な番号を割り当てる。今回は 1 とする。

const extCodeProfile = 0x01

エンコード形式を決める

Extension Type なので、データをどう格納するかは自由に決めてよい。

今回は Profile 型を以下のような形式で msgpack に格納する。この部分を データ本体 と呼ぶことにする。

Name
- 文字数 (1byte)
- 文字列本体(255bytes 以内)
Languages
- key 数 (1byte)
- 言語名(2bytes) を、言語の数だけ並べる
  - en ja の2言語であれば、enja のように連結

また今回は、可変長の ext format を使用する。そのため、データの先頭に以下のヘッダが追加される。[仕様]

first byte
- データ本体の長さに応じて、0xc7(255bytes 以下) 0xc8 (65535bytes 以下) 0xc9 (2の32乗-1 bytes 以下) のいずれか
データ本体の長さ
extension type

Encoder の実装

https://github.com/shamaton/msgpack/blob/d00aa7a9bf6594703f4367af3eb259986e83f432/ext/encode.go#L7-L12

type Encoder interface {
    Code() int8
    Type() reflect.Type
    CalcByteSize(value reflect.Value) (int, error)
    WriteToBytes(value reflect.Value, offset int, bytes *[]byte) int
}

Encoder はこの interface を実装する必要がある。

type ProfileEncoder struct {
    ext.EncoderCommon
}

var _ ext.Encoder = (*ProfileEncoder)(nil)

github.com/shamaton/msgpack/v2/ext.EncoderCommon を embed することは必須ではないが、バイト列を作成するのに便利なヘルパーメソッドが提供されているので活用すると良い。

`Code`

上で決めた Extension Type をそのまま返す。

func (e *ProfileEncoder) Code() int8 {
    return extCodeProfile
}

`Type`

この Encoder が扱う対象の型を返す。

var typeProfile = reflect.TypeOf(Profile{})

func (e *ProfileEncoder) Type() reflect.Type {
    return typeProfile
}

`CalcByteSize`

エンコードされたときの byte 数を返す。といっても ext format の最初の 1byte は計算に入れないようなので、実際にエンコードされたときの byte 数 - 1 を返すものとなる。

エンコード後のサイズは固定長とは限らず、実際にデータを受け取ってみないと分からないケースも多いと思う。例えば今回の Profile の例だと、Name の文字数や Languages の数によってサイズは可変となる。
そこで、具体的な値を引数 value で受け取ったという前提で、そのサイズを計算する方法を実装することになる。

func (e *ProfileEncoder) CalcByteSize(value reflect.Value) (int, error) {
    p := value.Interface().(Profile)

    size := e.calcDataSize(p)

    // data length
    if size < (1 << 8) {
        size++
    } else if size < (1 << 16) {
        size += 2
    } else {
        size += 4
    }

    size++ // ext code

    return size, nil
}

// データ本体のサイズを計算
func (e *ProfileEncoder) calcDataSize(p Profile) int {
    size := len(p.Name) + 1
    size++                       // length of language
    size += len(p.Languages) * 2 // 2 bytes for each language

    return size
}

なお、データ本体のサイズ計算は、このあとの WriteToBytes でも使うので、別メソッド(ここでは calcDataSize) に切り分けておくと便利。

`WriteToBytes`

実際にバイト列を書き込む処理の実装。ext.EncoderCommon が提供する SetByte1Int などを活用している。

バイト列は、引数で受け取った bytes の中の、先頭から offset 進んだ位置から書き込まれる。
戻り値は、offset をこのメソッドで書き込んだ byte 数だけ進めたものとなる。

len(bytes) より offset が先に進んでしまうと、index out of range で panic が発生してしまうことに注意。
CalcByteSize で計算されたバイト数と、書き込むバイト数が一致してない場合に起こりうる。

func (e *ProfileEncoder) WriteToBytes(value reflect.Value, offset int, bytes *[]byte) int {
    p := value.Interface().(Profile)

    dataLen := e.calcDataSize(p)
    if dataLen < (1 << 8) {
        offset = e.SetByte1Int(0xc7, offset, bytes)
        offset = e.SetByte1Int(dataLen, offset, bytes)
    } else if dataLen < (1 << 16) {
        offset = e.SetByte1Int(0xc8, offset, bytes)
        offset = e.SetByte2Int(dataLen, offset, bytes)
    } else {
        offset = e.SetByte1Int(0xc9, offset, bytes)
        offset = e.SetByte4Int(dataLen, offset, bytes)
    }
    offset = e.SetByte1Int(extCodeProfile, offset, bytes)

    // Name
    offset = e.SetByte1Int(len(p.Name), offset, bytes)
    offset = e.SetBytes([]byte(p.Name), offset, bytes)

    // Languages
    offset = e.SetByte1Int(len(p.Languages), offset, bytes)
    for l := range p.Languages {
        offset = e.SetBytes([]byte(l[:2]), offset, bytes)
    }

    return offset
}

Decoder の実装

https://github.com/shamaton/msgpack/blob/d00aa7a9bf6594703f4367af3eb259986e83f432/ext/decode.go#L9-L13

type Decoder interface {
    Code() int8
    IsType(offset int, d *[]byte) bool
    AsValue(offset int, k reflect.Kind, d *[]byte) (interface{}, int, error)
}

以上を実装する。これも ext.DecoderCommon を embed しておくと便利。

type ProfileDecoder struct {
    ext.DecoderCommon
}

var _ ext.Decoder = (*ProfileDecoder)(nil)

`Code`

Encoder 同様、Extension Type をそのまま返す。

func (d *ProfileDecoder) Code() int8 {
    return extCodeProfile
}

`IsType`

バイト列(bytes) の、位置 offset から始まる部分バイト列が、この Decoder の処理対象かどうかを判断するのに使う。

今回の場合、以下の条件を満たしたときに処理対象と判断できる。

0xc7 0xc8 0xc9 のいずれかが先頭にある
データ長を読み飛ばした次のバイトが 0x01 (今回の Extension Type)

func (d *ProfileDecoder) IsType(offset int, bytes *[]byte) bool {
    code, _ := d.ReadSize1(offset, bytes)
    ext := byte(extCodeProfile)

    switch code {
    case 0xc7:
        return offset+2 < len(*bytes) && (*bytes)[offset+2] == ext
    case 0xc8:
        return offset+3 < len(*bytes) && (*bytes)[offset+3] == ext
    case 0xc9:
        return offset+5 < len(*bytes) && (*bytes)[offset+5] == ext
    }
    return false
}

`AsValue`

バイト列を内部データに戻す処理を実装する。 DecoderCommon に定義されている ReadSize1 などを活用している。

2番目の戻り値で、後続データの先頭 offset = 今回読み込んだデータの次の offset を返す。

func (d *ProfileDecoder) AsValue(offset int, k reflect.Kind, bytes *[]byte) (interface{}, int, error) {
    p := Profile{}

    // Data より前の部分は今回は不要なのでスキップ
    code, o := d.ReadSize1(offset, bytes)
    offset = o
    switch code {
    case 0xc7:
        _, offset = d.ReadSize1(offset, bytes) // skip data length
    case 0xc8:
        _, offset = d.ReadSize2(offset, bytes) // skip data length
    case 0xc9:
        _, offset = d.ReadSize4(offset, bytes) // skip data length
    default:
        return nil, offset, fmt.Errorf("invalid code: %x", code)
    }
    _, offset = d.ReadSize1(offset, bytes) // skip ext code

    // ここからデータ本体

    // Name
    nameLen, o := d.ReadSize1(offset, bytes)
    offset = o

    name, o := d.ReadSizeN(offset, int(nameLen), bytes)
    offset = o
    p.Name = string(name)

    // Languages
    langLen, o := d.ReadSize1(offset, bytes)
    offset = o
    p.Languages = make(map[string]struct{}, int(langLen))

    for range int(langLen) {
        lng, o := d.ReadSize2(offset, bytes)
        offset = o
        p.Languages[string(lng)] = struct{}{}
    }

    return p, offset, nil
}

Encoder/Decoderを有効にする

以上で作成した Encoder/Decoder を有効にするために AddExtCoder を実行する。

	err := msgpack.AddExtCoder(&ProfileEncoder{}, &ProfileDecoder{})
	if err != nil {
		log.Fatal(err)
	}
	defer msgpack.RemoveExtCoder(&ProfileEncoder{}, &ProfileDecoder{})

Encoder と Decoder は同じ Extension Type を持っている必要がある。
たとえアプリケーション内で片方しか使用しないとしても、(現在のバージョンでは) 両方を指定しなければならない。

もし本当に片方しか必要ないのであれば、もう片方は Codeメソッドの戻り値のみ合わせたダミー実装でも良いかもしれない。

RemoveExtCoder で Encoder/Decoder の登録を解除できる。
アプリケーション実行時は必要なさそうだが、テスト実行時は意図しない影響を避けるために入れておいたほうがいいかも。