> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MessagePack

> MessagePack content handling middleware for binary serialization.

## Overview

The `msgpack` middleware provides MessagePack content negotiation and serialization for efficient binary data transfer.

Use it when you need:

* Binary serialization
* Reduced payload size
* Faster parsing

## Installation

```go theme={null}
import "github.com/go-mizu/mizu/middlewares/msgpack"
```

## Quick Start

```go theme={null}
app := mizu.New()

app.Use(msgpack.New())

app.Get("/data", func(c *mizu.Ctx) error {
    // Auto-negotiates based on Accept header
    return c.Negotiate(200, data)
})
```

## Examples

### Enable MessagePack

```go theme={null}
app.Use(msgpack.New())
```

### Explicit MessagePack Response

```go theme={null}
app.Get("/data", func(c *mizu.Ctx) error {
    return msgpack.Send(c, 200, data)
})
```

### Parse MessagePack Request

```go theme={null}
app.Post("/data", func(c *mizu.Ctx) error {
    var data MyStruct
    if err := msgpack.Bind(c, &data); err != nil {
        return err
    }
    return c.JSON(200, data)
})
```

### Content Negotiation

```go theme={null}
app.Use(msgpack.New())

app.Get("/data", func(c *mizu.Ctx) error {
    // Returns MessagePack if Accept: application/msgpack
    // Returns JSON if Accept: application/json
    return c.Negotiate(200, data)
})
```

## API Reference

### Functions

```go theme={null}
// New creates MessagePack middleware
func New() mizu.Middleware

// Send sends MessagePack response
func Send(c *mizu.Ctx, status int, data any) error

// Bind parses MessagePack request body
func Bind(c *mizu.Ctx, v any) error
```

## Content Types

| Type                    | Description          |
| ----------------------- | -------------------- |
| `application/msgpack`   | Standard MessagePack |
| `application/x-msgpack` | Alternative          |

## Technical Details

### Architecture

The msgpack middleware implements a lightweight MessagePack encoder/decoder without external dependencies. It consists of three main components:

#### Middleware Handler

* Intercepts requests with MessagePack content types
* Stores raw request body in context for later parsing
* Supports configurable content types (default: `application/msgpack`, `application/x-msgpack`)

#### Encoder

* Implements MessagePack binary format specification
* Uses fixed-size optimizations for common value ranges
* Supports fixint, int8/16/32/64, uint8/16/32/64 encoding
* Handles fixstr, str8/16/32 for strings with automatic size selection
* Encodes binary data with bin8/16/32 formats
* Supports fixarray, array16/32 and fixmap, map16/32 structures

#### Decoder

* Parses MessagePack binary format to Go values
* Returns generic `any` types (string, int64, uint64, float32/64, \[]any, map\[string]any)
* Validates buffer boundaries to prevent out-of-bounds access
* Handles all MessagePack type codes including fixint, negative fixint, and type-specific codes

### Type Mappings

| Go Type         | MessagePack Format   | Notes                    |
| --------------- | -------------------- | ------------------------ |
| nil             | 0xc0                 | Null value               |
| bool            | 0xc2, 0xc3           | false, true              |
| int, int8-64    | fixint, int8-64      | Optimized by value range |
| uint, uint8-64  | fixint, uint8-64     | Optimized by value range |
| float32         | float 32 (0xca)      | 4-byte IEEE 754          |
| float64         | float 64 (0xcb)      | 8-byte IEEE 754          |
| string          | fixstr, str8-32      | Length-prefixed          |
| \[]byte         | bin8-32              | Binary data              |
| \[]any          | fixarray, array16-32 | Recursive encoding       |
| map\[string]any | fixmap, map16-32     | Key-value pairs          |

### Error Handling

The middleware defines three error types:

* `ErrUnsupportedType`: Returned when attempting to encode unsupported Go types
* `ErrInvalidFormat`: Returned when decoding encounters invalid MessagePack data
* `ErrBufferTooSmall`: Returned when the input buffer is insufficient for the declared data

### Context Storage

The middleware stores the raw MessagePack request body in the request context using a private context key. This allows:

* Multiple reads of the request body
* Access via the `Body()` helper function
* Preservation of the original request body for middleware chain

## Best Practices

* Use for internal APIs
* Fall back to JSON for browsers
* Consider client library support
* Benchmark for your use case

## Testing

### Test Coverage

The msgpack middleware includes comprehensive test coverage for all functionality:

| Test Case                             | Description                 | Expected Behavior                                               |
| ------------------------------------- | --------------------------- | --------------------------------------------------------------- |
| TestNew                               | Middleware initialization   | Middleware successfully initializes and passes requests through |
| TestMarshalUnmarshal - nil            | Nil value encoding/decoding | Correctly encodes and decodes nil values                        |
| TestMarshalUnmarshal - true/false     | Boolean encoding/decoding   | Correctly encodes and decodes true/false values                 |
| TestMarshalUnmarshal - positive int   | Positive integer encoding   | Correctly encodes and decodes positive integers                 |
| TestMarshalUnmarshal - negative int   | Negative integer encoding   | Correctly encodes and decodes negative integers                 |
| TestMarshalUnmarshal - zero           | Zero value encoding         | Correctly encodes and decodes zero                              |
| TestMarshalUnmarshal - large int      | Large integer encoding      | Correctly encodes and decodes large integers (1000000)          |
| TestMarshalUnmarshal - uint           | Unsigned integer encoding   | Correctly encodes and decodes unsigned integers                 |
| TestMarshalUnmarshal - float64        | Float64 encoding            | Correctly encodes and decodes float64 values                    |
| TestMarshalUnmarshal - string         | String encoding             | Correctly encodes and decodes strings                           |
| TestMarshalUnmarshal - empty string   | Empty string encoding       | Correctly encodes and decodes empty strings                     |
| TestMarshalUnmarshal - long string    | Long string encoding        | Correctly encodes and decodes strings exceeding 31 bytes        |
| TestMarshalArray                      | Array encoding/decoding     | Correctly encodes and decodes arrays with multiple elements     |
| TestMarshalMap                        | Map encoding/decoding       | Correctly encodes and decodes maps with string keys             |
| TestMarshalBinary                     | Binary data encoding        | Correctly encodes and decodes raw byte slices                   |
| TestResponse                          | HTTP response generation    | Sets correct Content-Type header and encodes response data      |
| TestBind                              | Request body parsing        | Correctly parses MessagePack request bodies                     |
| TestBody                              | Raw body retrieval          | Retrieves raw MessagePack body from context                     |
| TestEncoderIntegers - zero            | Zero integer                | Encodes/decodes zero correctly                                  |
| TestEncoderIntegers - positive fixint | Positive fixint (100)       | Uses optimized fixint encoding                                  |
| TestEncoderIntegers - negative fixint | Negative fixint (-20)       | Uses optimized negative fixint encoding                         |
| TestEncoderIntegers - int8 positive   | int8 range (127)            | Uses int8 encoding                                              |
| TestEncoderIntegers - int8 negative   | int8 range (-128)           | Uses int8 encoding                                              |
| TestEncoderIntegers - int16 positive  | int16 range (1000)          | Uses int16 encoding                                             |
| TestEncoderIntegers - int16 negative  | int16 range (-1000)         | Uses int16 encoding                                             |
| TestEncoderIntegers - int32 positive  | int32 range (100000)        | Uses int32 encoding                                             |
| TestEncoderIntegers - int32 negative  | int32 range (-100000)       | Uses int32 encoding                                             |
| TestEncoderIntegers - int64 positive  | int64 range (5000000000)    | Uses int64 encoding                                             |
| TestEncoderIntegers - int64 negative  | int64 range (-5000000000)   | Uses int64 encoding                                             |
| TestEncoderFloats - float32           | float32 encoding            | Encodes/decodes float32 with correct precision                  |
| TestEncoderFloats - float64           | float64 encoding            | Encodes/decodes float64 with correct precision                  |
| TestUnsupportedType                   | Unsupported type error      | Returns ErrUnsupportedType for custom structs                   |
| TestEmptyBuffer                       | Empty buffer error          | Returns error when unmarshaling empty buffer                    |

## Related Middlewares

* [contenttype](/middlewares/contenttype) - Content-Type validation
* [compress](/middlewares/compress) - Response compression
* [xml](/middlewares/xml) - XML handling