msgpack

Documentation

Overview

Package msgpack provides MessagePack binding support for the binding package.

This package extends rivaas.dev/binding with MessagePack serialization support, using github.com/vmihailenco/msgpack/v5 for parsing.

Example:

type Message struct {
    ID      int64  `msgpack:"id"`
    Content string `msgpack:"content"`
}

msg, err := msgpack.MsgPack[Message](body)
if err != nil {
    // handle error
}

Index

• func FromMsgPack(body []byte, opts ...Option) binding.Option
• func FromMsgPackReader(r io.Reader, opts ...Option) binding.Option
• func MsgPack[T any](body []byte, opts ...Option) (T, error)
• func MsgPackReader[T any](r io.Reader, opts ...Option) (T, error)
• func MsgPackReaderTo(r io.Reader, out any, opts ...Option) error
• func MsgPackTo(body []byte, out any, opts ...Option) error
• type Option
  • func WithDisallowUnknown() Option
  • func WithJSONTag() Option

Examples

• MsgPack
• MsgPack (Arrays)
• MsgPack (Maps)
• MsgPack (NestedStructs)
• MsgPack (WithDisallowUnknown)
• MsgPack (WithJSONTag)
• MsgPackReader
• MsgPackTo

Functions

func FromMsgPack

func FromMsgPack(body []byte, opts ...Option) binding.Option

FromMsgPack returns a binding.Option that specifies MessagePack body as a binding source. This can be used with binding.Bind for multi-source binding.

Example:

req, err := binding.Bind[Request](
    binding.FromQuery(r.URL.Query()),
    msgpack.FromMsgPack(body),
)

func FromMsgPackReader

func FromMsgPackReader(r io.Reader, opts ...Option) binding.Option

FromMsgPackReader returns a binding.Option that specifies MessagePack from io.Reader as a binding source.

Example:

req, err := binding.Bind[Request](
    msgpack.FromMsgPackReader(r.Body),
)

func MsgPack

func MsgPack[T any](body []byte, opts ...Option) (T, error)

MsgPack binds MessagePack bytes to type T.

Example:

msg, err := msgpack.MsgPack[Message](body)

// With options
msg, err := msgpack.MsgPack[Message](body, msgpack.WithJSONTag())

Example

ExampleMsgPack demonstrates basic MessagePack binding.

package main

import (
	"fmt"
	"log"

	"rivaas.dev/binding/msgpack"

	mp "github.com/vmihailenco/msgpack/v5"
)

func main() {
	type Config struct {
		Name  string `msgpack:"name"`
		Port  int    `msgpack:"port"`
		Debug bool   `msgpack:"debug"`
	}

	// Create MessagePack data
	original := Config{
		Name:  "myapp",
		Port:  8080,
		Debug: true,
	}
	body, err := mp.Marshal(&original)
	if err != nil {
		log.Fatal(err)
	}

	config, err := msgpack.MsgPack[Config](body)
	if err != nil {
		_, _ = fmt.Printf("Error: %v\n", err)
		return
	}

	_, _ = fmt.Printf("Name: %s, Port: %d, Debug: %v\n", config.Name, config.Port, config.Debug)
}

Output:

Name: myapp, Port: 8080, Debug: true

Example (Arrays)

ExampleMsgPack_arrays demonstrates binding MessagePack arrays.

package main

import (
	"fmt"
	"log"

	"rivaas.dev/binding/msgpack"

	mp "github.com/vmihailenco/msgpack/v5"
)

func main() {
	type Config struct {
		Hosts []string `msgpack:"hosts"`
		Ports []int    `msgpack:"ports"`
	}

	original := Config{
		Hosts: []string{"host1.example.com", "host2.example.com"},
		Ports: []int{8080, 8081},
	}
	body, err := mp.Marshal(&original)
	if err != nil {
		log.Fatal(err)
	}

	config, err := msgpack.MsgPack[Config](body)
	if err != nil {
		_, _ = fmt.Printf("Error: %v\n", err)
		return
	}

	_, _ = fmt.Printf("Hosts: %d, Ports: %d\n", len(config.Hosts), len(config.Ports))
}

Output:

Hosts: 2, Ports: 2

Example (Maps)

ExampleMsgPack_maps demonstrates binding MessagePack maps.

package main

import (
	"fmt"
	"log"

	"rivaas.dev/binding/msgpack"

	mp "github.com/vmihailenco/msgpack/v5"
)

func main() {
	type Config struct {
		Settings map[string]string `msgpack:"settings"`
	}

	original := Config{
		Settings: map[string]string{
			"log_level":   "debug",
			"environment": "production",
		},
	}
	body, err := mp.Marshal(&original)
	if err != nil {
		log.Fatal(err)
	}

	config, err := msgpack.MsgPack[Config](body)
	if err != nil {
		_, _ = fmt.Printf("Error: %v\n", err)
		return
	}

	_, _ = fmt.Printf("Log Level: %s\n", config.Settings["log_level"])
}

Output:

Log Level: debug

Example (NestedStructs)

ExampleMsgPack_nestedStructs demonstrates binding nested MessagePack structures.

package main

import (
	"fmt"
	"log"

	"rivaas.dev/binding/msgpack"

	mp "github.com/vmihailenco/msgpack/v5"
)

func main() {
	type Address struct {
		Street string `msgpack:"street"`
		City   string `msgpack:"city"`
	}

	type Person struct {
		Name    string  `msgpack:"name"`
		Address Address `msgpack:"address"`
	}

	original := Person{
		Name: "Jane",
		Address: Address{
			Street: "123 Main St",
			City:   "Boston",
		},
	}
	body, err := mp.Marshal(&original)
	if err != nil {
		log.Fatal(err)
	}

	person, err := msgpack.MsgPack[Person](body)
	if err != nil {
		_, _ = fmt.Printf("Error: %v\n", err)
		return
	}

	_, _ = fmt.Printf("Name: %s, Address: %s, %s\n",
		person.Name, person.Address.Street, person.Address.City)
}

Output:

Name: Jane, Address: 123 Main St, Boston

Example (WithDisallowUnknown)

ExampleMsgPack_withDisallowUnknown demonstrates strict unknown field handling.

package main

import (
	"fmt"
	"log"

	"rivaas.dev/binding/msgpack"

	mp "github.com/vmihailenco/msgpack/v5"
)

func main() {
	type Config struct {
		Name string `msgpack:"name"`
	}

	// Only known fields
	original := Config{Name: "myapp"}
	body, err := mp.Marshal(&original)
	if err != nil {
		log.Fatal(err)
	}

	config, err := msgpack.MsgPack[Config](body, msgpack.WithDisallowUnknown())
	if err != nil {
		_, _ = fmt.Printf("Error: %v\n", err)
		return
	}

	_, _ = fmt.Printf("Name: %s\n", config.Name)
}

Output:

Name: myapp

Example (WithJSONTag)

ExampleMsgPack_withJSONTag demonstrates using JSON tags for MessagePack.

package main

import (
	"bytes"
	"fmt"
	"log"

	"rivaas.dev/binding/msgpack"

	mp "github.com/vmihailenco/msgpack/v5"
)

func main() {
	type User struct {
		Name  string `json:"name"`
		Email string `json:"email"`
	}

	// Encode using JSON tags
	buf := &bytes.Buffer{}
	enc := mp.NewEncoder(buf)
	enc.SetCustomStructTag("json")
	err := enc.Encode(&User{
		Name:  "John",
		Email: "john@example.com",
	})
	if err != nil {
		log.Fatal(err)
	}

	user, err := msgpack.MsgPack[User](buf.Bytes(), msgpack.WithJSONTag())
	if err != nil {
		_, _ = fmt.Printf("Error: %v\n", err)
		return
	}

	_, _ = fmt.Printf("Name: %s, Email: %s\n", user.Name, user.Email)
}

Output:

Name: John, Email: john@example.com

func MsgPackReader

func MsgPackReader[T any](r io.Reader, opts ...Option) (T, error)

MsgPackReader binds MessagePack from an io.Reader to type T.

Example:

msg, err := msgpack.MsgPackReader[Message](r.Body)

Example

ExampleMsgPackReader demonstrates binding from an io.Reader.

package main

import (
	"bytes"
	"fmt"
	"log"

	"rivaas.dev/binding/msgpack"

	mp "github.com/vmihailenco/msgpack/v5"
)

func main() {
	type Database struct {
		Host     string `msgpack:"host"`
		Port     int    `msgpack:"port"`
		Database string `msgpack:"database"`
	}

	original := Database{
		Host:     "db.example.com",
		Port:     5432,
		Database: "mydb",
	}
	data, err := mp.Marshal(&original)
	if err != nil {
		log.Fatal(err)
	}

	db, err := msgpack.MsgPackReader[Database](bytes.NewReader(data))
	if err != nil {
		_, _ = fmt.Printf("Error: %v\n", err)
		return
	}

	_, _ = fmt.Printf("Database: %s@%s:%d\n", db.Database, db.Host, db.Port)
}

Output:

Database: mydb@db.example.com:5432

func MsgPackReaderTo

func MsgPackReaderTo(r io.Reader, out any, opts ...Option) error

MsgPackReaderTo binds MessagePack from an io.Reader to out.

Example:

var msg Message
err := msgpack.MsgPackReaderTo(r.Body, &msg)

func MsgPackTo

func MsgPackTo(body []byte, out any, opts ...Option) error

MsgPackTo binds MessagePack bytes to out.

Example:

var msg Message
err := msgpack.MsgPackTo(body, &msg)

Example

ExampleMsgPackTo demonstrates non-generic MessagePack binding.

package main

import (
	"fmt"
	"log"

	"rivaas.dev/binding/msgpack"

	mp "github.com/vmihailenco/msgpack/v5"
)

func main() {
	type Server struct {
		Host string `msgpack:"host"`
		Port int    `msgpack:"port"`
	}

	original := Server{Host: "localhost", Port: 3000}
	body, err := mp.Marshal(&original)
	if err != nil {
		log.Fatal(err)
	}

	var server Server
	err = msgpack.MsgPackTo(body, &server)
	if err != nil {
		_, _ = fmt.Printf("Error: %v\n", err)
		return
	}

	_, _ = fmt.Printf("Server: %s:%d\n", server.Host, server.Port)
}

Output:

Server: localhost:3000

Types

type Option

type Option func(*config)

Option configures MessagePack binding behavior.

func WithDisallowUnknown

func WithDisallowUnknown() Option

WithDisallowUnknown enables strict mode that returns an error if the MessagePack data contains fields not in the struct.

func WithJSONTag

func WithJSONTag() Option

WithJSONTag enables using JSON struct tags for field names. By default, msgpack struct tags are used.