msgpack

KO | EN

gitlite — search

#python #docker #golang #aws #react #python3 #ios #hacktoberfest #go #postgresql #flutter #javascript

★ 179 Open GitHub ↗

easier, faster, but extendable MessagePack Serializer for Golang. / msgpack.org[Go]

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MessagePack for Golang

[![Go Reference](https://pkg.go.dev/badge/github.com/shamaton/msgpack.svg)](https://pkg.go.dev/github.com/shamaton/msgpack)
![test](https://github.com/shamaton/msgpack/workflows/test/badge.svg)
[![Go Report Card](https://goreportcard.com/badge/github.com/shamaton/msgpack)](https://goreportcard.com/report/github.com/shamaton/msgpack)
[![codecov](https://codecov.io/gh/shamaton/msgpack/branch/master/graph/badge.svg?token=9PD2JUK5V3)](https://codecov.io/gh/shamaton/msgpack)
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fshamaton%2Fmsgpack.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fshamaton%2Fmsgpack?ref=badge_shield)

## 📣 Announcement: `time.Time` decoding defaults to **UTC** in v3

Starting with **v3.0.0**, when decoding MessagePack **Timestamp** into Go’s `time.Time`,
the default `Location` will be **UTC** (previously `Local`). The instant is unchanged.
To keep the old behavior, use `SetDecodedTimeAsLocal()`.

## Features

- Supported types : primitive / array / slice / struct / map / interface{} and time.Time
- Renaming fields via `msgpack:"field_name"`
- Omitting fields via `msgpack:"-"`
- Omitting empty fields via `msgpack:"field_name,omitempty"`
- Supports extend encoder / decoder [(example)](./msgpack_example_test.go)
- Can also Encoding / Decoding struct as array

## Installation

Current version is **msgpack/v3**.

```sh
go get -u github.com/shamaton/msgpack/v3
```

### Upgrading from v2

If you are upgrading from v2, please note the `time.Time` decoding change mentioned in the announcement above.
To keep the v2 behavior, use `msgpack.SetDecodedTimeAsLocal()` after upgrading.

## Quick Start

```go
package main

import (
  "github.com/shamaton/msgpack/v3"
  "net/http"
)

type Struct struct {
  String string
}

// simple
func main() {
  v := Struct{String: "msgpack"}

d, err := msgpack.Marshal(v)
  if err != nil {
    panic(err)
  }
  r := Struct{}
  if err = msgpack.Unmarshal(d, &r); err != nil {
    panic(err)
  }
}

// streaming
func handle(w http.ResponseWriter, r *http.Request) {
  var body Struct
  if err := msgpack.UnmarshalRead(r, &body); err != nil {
    panic(err)
  }
  if err := msgpack.MarshalWrite(w, body); err != nil {
    panic(err)
  }
}
```

## v3: `time.Time` decoding defaults to **UTC**

**TL;DR:** Starting with **v3.0.0**, when decoding MessagePack **Timestamp** into Go’s `time.Time`, the default `Location` will be **UTC** (previously `Local`). The **instant** is unchanged—only the display/location changes. This avoids host-dependent differences and aligns with common distributed systems practice.

### What is changing?

- **Before (v2.x):** Decoded `time.Time` defaults to `Local`.
- **After (v3.0.0):** Decoded `time.Time` defaults to **UTC**.

MessagePack’s Timestamp encodes an **instant** (epoch seconds + nanoseconds) and does **not** carry timezone info. Your data’s point in time is the same; only `time.Time.Location()` differs.

### Why?

- Eliminate environment-dependent behavior, such as different hosts showing different local zones.
- Make “UTC by default” the safe, predictable baseline for logs, APIs, and distributed apps.

### Who is affected?

- Apps that **display local time** without explicitly converting from UTC.
- If your code already normalizes to UTC or explicitly sets a location, you’re likely unaffected.

### Keep the old behavior (Local)

If you want the v2 behavior on v3:

```go
msgpack.SetDecodedTimeAsLocal()
```

Or convert after the fact:

```go
var t time.Time
_ = msgpack.Unmarshal(data, &t)
t = t.In(time.Local)
```

### Preview the new behavior on v2 (optional)

You can opt into UTC today on v2.x:

```go
msgpack.SetDecodedTimeAsUTC()
```

## Benchmarks

These results are recorded by [msgpack_bench](https://github.com/shamaton/msgpack_bench).
Our package results show in `Shamaton`. Prefix `ShamatonGen` shows another our messagepack serialization library. See also: [msgpackgen](https://github.com/shamaton/msgpackgen).

![Benchmark Encode](https://raw.githubusercontent.com/shamaton/msgpack_bench/refs/heads/main/docs/benchmarks/compare-encode.svg)

![Benchmark Decode](https://raw.githubusercontent.com/shamaton/msgpack_bench/refs/heads/main/docs/benchmarks/compare-decode.svg)

## License

This library is under the MIT License. See the [LICENSE](./LICENSE) file for details.

msgpack

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README