Zig Msgpack

https://github.com/zigcc/zig-msgpack
Admin
Zig Msgpack is a MessagePack implementation for the Zig programming language that provides efficient...
Tokens:9,618
Snippets:55
Trust Score:9.5
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install zig-msgpack dependency

Source: https://github.com/zigcc/zig-msgpack/blob/main/README.md

Use the Zig package manager to fetch and save the library as a dependency in your project's build configuration.

```shell
zig fetch --save https://github.com/zigcc/zig-msgpack/archive/{COMMIT_OR_BRANCH}.tar.gz
```

--------------------------------

### Construct MessagePack Data Types

Source: https://github.com/zigcc/zig-msgpack/blob/main/README.md

Provides examples of creating various MessagePack types including primitives, strings, binary data, arrays, extension types, and maps with both string and generic keys.

```zig
const nil_val = msgpack.Payload.nilToPayload();
const bool_val = msgpack.Payload.boolToPayload(true);
const int_val = msgpack.Payload.intToPayload(-42);
const uint_val = msgpack.Payload.uintToPayload(42);
const float_val = msgpack.Payload.floatToPayload(3.14);

const str_val = try msgpack.Payload.strToPayload("hello", allocator);
const bin_val = try msgpack.Payload.binToPayload(&[_]u8{1, 2, 3}, allocator);

var arr = try msgpack.Payload.arrPayload(2, allocator);
try arr.setArrElement(0, msgpack.Payload.intToPayload(1));
try arr.setArrElement(1, msgpack.Payload.intToPayload(2));

const ext_val = try msgpack.Payload.extToPayload(5, &[_]u8{0xaa, 0xbb}, allocator);

var map = msgpack.Payload.mapPayload(allocator);
try map.mapPut("key1", msgpack.Payload.intToPayload(42));

var generic_map = msgpack.Payload.mapPayload(allocator);
try generic_map.mapPutGeneric(msgpack.Payload.intToPayload(1), msgpack.Payload.strToPayload("value1", allocator));
try generic_map.mapPutGeneric(msgpack.Payload.boolToPayload(true), msgpack.Payload.strToPayload("true_value", allocator));
```

--------------------------------

### Batch Integer Conversion for Performance in Zig

Source: https://context7.com/zigcc/zig-msgpack/llms.txt

Optimizes high-throughput scenarios by using batch conversion functions for integer arrays. This example shows how to efficiently convert arrays of u32 and u64 to MessagePack's big-endian format.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
    // Batch convert u32 array to big-endian (MessagePack format)
    const values_u32 = [_]u32{ 1, 2, 3, 4, 5, 6, 7, 8 };
    var output_u32: [32]u8 = undefined;
    const bytes_written_u32 = msgpack.batchU32ToBigEndian(&values_u32, &output_u32);
    std.debug.print("Converted {} u32 values ({} bytes)\n", .{ values_u32.len, bytes_written_u32 });

    // Batch convert u64 array to big-endian
    const values_u64 = [_]u64{ 100, 200, 300, 400 };
    var output_u64: [32]u8 = undefined;
    const bytes_written_u64 = msgpack.batchU64ToBigEndian(&values_u64, &output_u64);
    std.debug.print("Converted {} u64 values ({} bytes)\n", .{ values_u64.len, bytes_written_u64 });
}

```

--------------------------------

### Convert and Validate MessagePack Payload Types

Source: https://context7.com/zigcc/zig-msgpack/llms.txt

Explains the difference between lenient and strict type conversion in the Payload API. Includes examples of type checking helpers to verify data structure contents.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
    const uint_payload = msgpack.Payload.uintToPayload(100);
    const as_i64 = try uint_payload.getInt();
    std.debug.print("Lenient i64: {}\n", .{as_i64});

    const int_payload = msgpack.Payload.intToPayload(50);
    const as_u64 = try int_payload.getUint();
    std.debug.print("Lenient u64: {}\n", .{as_u64});

    const strict_uint = uint_payload.asUint() catch |err| {
        std.debug.print("Strict error: {}\n", .{err});
        return;
    };
    std.debug.print("Strict u64: {}\n", .{strict_uint});

    _ = uint_payload.asInt() catch |_| {
        std.debug.print("asInt() failed for uint type (expected)\n", .{});
    };

    const float_val = msgpack.Payload.floatToPayload(3.14);
    const nil_val = msgpack.Payload.nilToPayload();

    std.debug.print("Is nil: {}\n", .{nil_val.isNil()});
    std.debug.print("Is number: {}\n", .{float_val.isNumber()});
    std.debug.print("Is integer: {}\n", .{uint_payload.isInteger()});
}
```

--------------------------------

### Creating and Managing Array Payloads in Zig

Source: https://context7.com/zigcc/zig-msgpack/llms.txt

Shows how to initialize an array payload of a specific size and populate it with heterogeneous MessagePack types. Includes methods for setting elements and retrieving array length.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
    const allocator = std.heap.page_allocator;

    // Create array with 4 elements
    var arr = try msgpack.Payload.arrPayload(4, allocator);
    defer arr.free(allocator);

    // Set elements of different types
    try arr.setArrElement(0, msgpack.Payload.intToPayload(42));
    try arr.setArrElement(1, msgpack.Payload.boolToPayload(true));
    try arr.setArrElement(2, try msgpack.Payload.strToPayload("nested string", allocator));
    try arr.setArrElement(3, msgpack.Payload.floatToPayload(2.718));

    // Access array elements
    const first = try arr.getArrElement(0);
    const len = try arr.getArrLen();

    std.debug.print("Array has {} elements, first is {}\n", .{ len, first.int });
}
```

--------------------------------

### Create and Read Timestamps in Zig

Source: https://github.com/zigcc/zig-msgpack/blob/main/README.md

Demonstrates how to create timestamp payloads from seconds and nanoseconds, write them to a packer, and then read them back. It also shows how to access the seconds and nanoseconds components and convert the timestamp to a float.

```zig
// Create timestamps
const ts1 = msgpack.Payload.timestampFromSeconds(1234567890);
const ts2 = msgpack.Payload.timestampToPayload(1234567890, 123456789);

// Write and read timestamp
try packer.write(ts2);
read_buffer.pos = 0;
const decoded_ts = try packer.read(allocator);
defer decoded_ts.free(allocator);

std.debug.print("Timestamp: {}s + {}ns\n",
    .{ decoded_ts.timestamp.seconds, decoded_ts.timestamp.nanoseconds });
std.debug.print("As float: {d}\n", .{ decoded_ts.timestamp.toFloat() });
```

--------------------------------

### Creating and Managing Map Payloads in Zig

Source: https://context7.com/zigcc/zig-msgpack/llms.txt

Illustrates the creation of maps using both string-based keys and generic Payload-based keys. Demonstrates insertion and retrieval operations within the MessagePack map structure.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
    const allocator = std.heap.page_allocator;

    // Create map with string keys
    var map = msgpack.Payload.mapPayload(allocator);
    defer map.free(allocator);

    // Add entries with string keys
    try map.mapPut("name", try msgpack.Payload.strToPayload("Alice", allocator));
    try map.mapPut("age", msgpack.Payload.uintToPayload(30));
    try map.mapPut("active", msgpack.Payload.boolToPayload(true));
    try map.mapPut("score", msgpack.Payload.floatToPayload(95.5));

    // Access values by string key
    if (try map.mapGet("name")) |name| {
        std.debug.print("Name: {s}\n", .{name.str.value()});
    }

    // Generic keys: use any Payload type as key
    var generic_map = msgpack.Payload.mapPayload(allocator);
    defer generic_map.free(allocator);

    try generic_map.mapPutGeneric(
        msgpack.Payload.intToPayload(1),
        try msgpack.Payload.strToPayload("value for key 1", allocator)
    );
    try generic_map.mapPutGeneric(
        msgpack.Payload.boolToPayload(true),
        try msgpack.Payload.strToPayload("value for true", allocator)
    );

    // Lookup with generic key
    if (try generic_map.mapGetGeneric(msgpack.Payload.intToPayload(1))) |val| {
        std.debug.print("Found: {s}\n", .{val.str.value()});
    }
}
```

--------------------------------

### Perform Buffered File I/O with MessagePack in Zig

Source: https://context7.com/zigcc/zig-msgpack/llms.txt

Demonstrates how to read and write MessagePack payloads to files using buffered I/O. It covers initializing a packer with file streams, serializing map data, and deserializing it back into the application.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var file = try std.fs.cwd().createFile("data.msgpack", .{ .read = true });
    defer file.close();

    var reader_buf: [4096]u8 = undefined;
    var reader = file.reader(&reader_buf);
    var writer_buf: [4096]u8 = undefined;
    var writer = file.writer(&writer_buf);

    var packer = msgpack.PackerIO.init(&reader, &writer);

    var payload = msgpack.Payload.mapPayload(allocator);
    defer payload.free(allocator);
    try payload.mapPut("message", try msgpack.Payload.strToPayload("Hello, MessagePack!", allocator));
    try payload.mapPut("timestamp", msgpack.Payload.timestampFromSeconds(1234567890));
    try packer.write(payload);

    try writer.flush();
    try file.seekTo(0);
    reader.seek = 0;
    reader.end = 0;

    const decoded = try packer.read(allocator);
    defer decoded.free(allocator);

    const message = (try decoded.mapGet("message")).?.str.value();
    std.debug.print("Read from file: {s}\n", .{message});
}
```

--------------------------------

### Creating Basic Payload Types in Zig

Source: https://context7.com/zigcc/zig-msgpack/llms.txt

Demonstrates how to instantiate various MessagePack types using static factory methods. Includes handling of nil, booleans, integers, floats, strings, binary data, and timestamps.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
    const allocator = std.heap.page_allocator;

    // Nil and boolean
    const nil_val = msgpack.Payload.nilToPayload();
    const bool_val = msgpack.Payload.boolToPayload(true);

    // Integer types (auto-selects optimal encoding)
    const int_val = msgpack.Payload.intToPayload(-42);
    const uint_val = msgpack.Payload.uintToPayload(12345);

    // Float (auto-selects f32 or f64 based on value range)
    const float_val = msgpack.Payload.floatToPayload(3.14159);

    // String (allocates memory, must be freed)
    const str_val = try msgpack.Payload.strToPayload("Hello, MessagePack!", allocator);
    defer str_val.free(allocator);

    // Binary data (allocates memory, must be freed)
    const bin_val = try msgpack.Payload.binToPayload(&[_]u8{ 0xDE, 0xAD, 0xBE, 0xEF }, allocator);
    defer bin_val.free(allocator);

    // Timestamp with nanosecond precision
    const ts_val = msgpack.Payload.timestampToPayload(1234567890, 123456789);
    const ts_from_secs = msgpack.Payload.timestampFromSeconds(1234567890);

    std.debug.print("Created payloads successfully\n", .{});
}
```

--------------------------------

### Implement Cross-Version Compatibility with Pack API

Source: https://github.com/zigcc/zig-msgpack/blob/main/README.md

Shows how to use the generic Pack API for maximum compatibility across different Zig versions. This approach uses a fixed buffer stream and explicit type definitions for reading and writing.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
	const allocator = std.heap.page_allocator;
	var buffer: [1024]u8 = undefined;

	const compat = msgpack.compat;
	var write_buffer = compat.fixedBufferStream(&buffer);
	var read_buffer = compat.fixedBufferStream(&buffer);

	const BufferType = compat.BufferStream;
	var packer = msgpack.Pack(
		*BufferType, *BufferType,
		BufferType.WriteError, BufferType.ReadError,
		BufferType.write, BufferType.read,
	).init(&write_buffer, &read_buffer);

	var map = msgpack.Payload.mapPayload(allocator);
	defer map.free(allocator);
	try map.mapPut("name", try msgpack.Payload.strToPayload("Alice", allocator));
	try map.mapPut("age", msgpack.Payload.uintToPayload(30));
	try packer.write(map);

	read_buffer.pos = 0;
	const decoded = try packer.read(allocator);
	defer decoded.free(allocator);

	const name = (try decoded.mapGet("name")).?.str.value();
	const age = (try decoded.mapGet("age")).?.uint;
	std.debug.print("Name: {s}, Age: {d}\n", .{ name, age });
}
```

--------------------------------

### Access Library Constants

Source: https://github.com/zigcc/zig-msgpack/blob/main/README.md

Demonstrates how to use semantic constant structures provided by the library to handle MessagePack format limits, integer bounds, extension lengths, and marker base values.

```zig
const max_fixstr = msgpack.FixLimits.STR_LEN_MAX;
const max_fixarray = msgpack.FixLimits.ARRAY_LEN_MAX;

const uint8_max = msgpack.IntBounds.UINT8_MAX;
const int8_min = msgpack.IntBounds.INT8_MIN;

const ext4_len = msgpack.FixExtLen.EXT4;

const ts_type = msgpack.TimestampExt.TYPE_ID;
const ts32_len = msgpack.TimestampExt.FORMAT32_LEN;
const max_nano = msgpack.TimestampExt.NANOSECONDS_MAX;

const fixarray_base = msgpack.MarkerBase.FIXARRAY;
const fixstr_mask = msgpack.MarkerBase.FIXSTR_LEN_MASK;
```

--------------------------------

### Error Handling for Type Conversions in Zig

Source: https://github.com/zigcc/zig-msgpack/blob/main/README.md

Illustrates robust error handling for MessagePack type conversions in Zig. It shows how to safely convert between integer types, manage errors when a conversion is not possible (e.g., negative to unsigned), and perform strict type checking to ensure data integrity.

```zig
// Type conversion with error handling
const int_payload = msgpack.Payload.intToPayload(-42);
const uint_result = int_payload.getUint() catch |err| switch (err) {
    msgpack.MsgPackError.InvalidType => {
        std.debug.print("Cannot convert negative to unsigned\n");
        return;
    },
    else => return err,
};

// Strict type conversion (no auto-conversion)
const strict_int = payload.asInt() catch |err| {
    // Only accepts .int type, rejects .uint even if it fits
    return err;
};

// Type checking
if (payload.isNil()) {
    std.debug.print("Value is nil\n", .{});
}
if (payload.isNumber()) {
    std.debug.print("Value is a number (int/uint/float)\n", .{});
}
if (payload.isInteger()) {
    std.debug.print("Value is an integer (int/uint)\n", .{});
}
```

--------------------------------

### Perform File-based MessagePack Serialization

Source: https://github.com/zigcc/zig-msgpack/blob/main/README.md

Shows how to interface MessagePack with Zig file system operations. It includes creating a file, using buffered readers/writers, and flushing data after serialization.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
	var gpa = std.heap.GeneralPurposeAllocator(.{}){};
	defer _ = gpa.deinit();
	const allocator = gpa.allocator();

	var file = try std.fs.cwd().createFile("data.msgpack", .{ .read = true });
	defer file.close();

	var reader_buf: [4096]u8 = undefined;
	var reader = file.reader(&reader_buf);
	var writer_buf: [4096]u8 = undefined;
	var writer = file.writer(&writer_buf);

	var packer = msgpack.PackerIO.init(&reader, &writer);

	var payload = msgpack.Payload.mapPayload(allocator);
	defer payload.free(allocator);
	try payload.mapPut("message", try msgpack.Payload.strToPayload("Hello, MessagePack!", allocator));
	try packer.write(payload);

	try writer.flush();
	try file.seekTo(0);
	reader.seek = 0;
	reader.end = 0;

	const decoded = try packer.read(allocator);
	defer decoded.free(allocator);

	const message = (try decoded.mapGet("message")).?.str.value();
	std.debug.print("Message: {s}\n", .{message});
}
```

--------------------------------

### Configure Parser Safety Limits

Source: https://context7.com/zigcc/zig-msgpack/llms.txt

Shows how to instantiate a packer with custom constraints to prevent malicious input from exhausting system resources. Defines limits for nesting depth, array/map sizes, and string/binary lengths.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
    const allocator = std.heap.page_allocator;
    var buffer: [4096]u8 = undefined;

    const compat = msgpack.compat;
    var write_buffer = compat.fixedBufferStream(&buffer);
    var read_buffer = compat.fixedBufferStream(&buffer);

    const BufferType = compat.BufferStream;

    const StrictPacker = msgpack.PackWithLimits(
        *BufferType,
        *BufferType,
        BufferType.WriteError,
        BufferType.ReadError,
        BufferType.write,
        BufferType.read,
        .{
            .max_depth = 50,
            .max_array_length = 10_000,
            .max_map_size = 10_000,
            .max_string_length = 1024 * 1024,
            .max_bin_length = 1024 * 1024,
            .max_ext_length = 512 * 1024,
        },
    );

    var packer = StrictPacker.init(&write_buffer, &read_buffer);

    var payload = msgpack.Payload.mapPayload(allocator);
    defer payload.free(allocator);
    try payload.mapPut("data", try msgpack.Payload.strToPayload("safe data", allocator));

    try packer.write(payload);

    read_buffer.pos = 0;
    const decoded = try packer.read(allocator);
    defer decoded.free(allocator);

    std.debug.print("Decoded with strict limits\n", .{});
}
```

--------------------------------

### Configurable Security Limits for MessagePack Parsing in Zig

Source: https://github.com/zigcc/zig-msgpack/blob/main/README.md

Explains how to configure safety limits in the zig-msgpack library to protect against malicious or corrupted MessagePack data. It shows the default recommended limits and how to define custom limits for nesting depth, array/map sizes, and string/binary lengths.

```zig
// Default limits (recommended for most use cases)
const Packer = msgpack.Pack(
    *Writer, *Reader,
    Writer.Error, Reader.Error,
    Writer.write, Reader.read,
);
// Automatically protected against:
// - Deep nesting attacks (max 1000 layers)
// - Large array/map attacks (max 1M elements)
// - Memory exhaustion (max 100MB strings)

// Custom limits for specific environments
const StrictPacker = msgpack.PackWithLimits(
    *Writer, *Reader,
    Writer.Error, Reader.Error,
    Writer.write, Reader.read,
    .{
        .max_depth = 50,              // Limit nesting to 50 layers
        .max_array_length = 10_000,   // Max 10K array elements
        .max_map_size = 10_000,       // Max 10K map pairs
        .max_string_length = 1024 * 1024,  // Max 1MB strings
        .max_bin_length = 1024 * 1024,     // Max 1MB binary blobs
        .max_ext_length = 512 * 1024,      // Max 512KB extension data
    },
);
```

--------------------------------

### Serialize and Deserialize with PackerIO in Zig

Source: https://github.com/zigcc/zig-msgpack/blob/main/README.md

Demonstrates using the PackerIO API for reading and writing MessagePack data to fixed buffers. It covers payload creation, map manipulation, and decoding values.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
	var gpa = std.heap.GeneralPurposeAllocator(.{}){};
	defer _ = gpa.deinit();
	const allocator = gpa.allocator();

	var buffer: [1024]u8 = undefined;

	var writer = std.Io.Writer.fixed(&buffer);
	var reader = std.Io.Reader.fixed(&buffer);

	var packer = msgpack.PackerIO.init(&reader, &writer);

	var map = msgpack.Payload.mapPayload(allocator);
	defer map.free(allocator);
	try map.mapPut("name", try msgpack.Payload.strToPayload("Alice", allocator));
	try map.mapPut("age", msgpack.Payload.uintToPayload(30));
	try packer.write(map);

	reader.seek = 0;
	const decoded = try packer.read(allocator);
	defer decoded.free(allocator);

	const name = (try decoded.mapGet("name")).?.str.value();
	const age = (try decoded.mapGet("age")).?.uint;
	std.debug.print("Name: {s}, Age: {d}\n", .{ name, age });
}
```

```zig
var packer = msgpack.packIO(&reader, &writer);
```

--------------------------------

### Perform Timestamp Operations in Zig

Source: https://context7.com/zigcc/zig-msgpack/llms.txt

Shows how to create and manipulate MessagePack timestamps with nanosecond precision. It supports creation from seconds, nanoseconds, or total nanoseconds since the Unix epoch.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
	// Create from seconds and nanoseconds
	const ts1 = msgpack.Payload.timestampToPayload(1234567890, 500_000_000);

	// Create from seconds only
	const ts2 = msgpack.Payload.timestampFromSeconds(1234567890);

	// Create from total nanoseconds since Unix epoch
	const ts3 = msgpack.Payload.timestampFromNanos(1234567890_500_000_000);

	// Access timestamp components
	std.debug.print("Seconds: {}, Nanoseconds: {}\n", .{
		ts1.timestamp.seconds,
		ts1.timestamp.nanoseconds,
	});

	// Convert to float (seconds with fractional nanoseconds)
	std.debug.print("As float: {d}\n", .{ts1.timestamp.toFloat()});
}
```

--------------------------------

### Serialize Data with Generic Pack API

Source: https://context7.com/zigcc/zig-msgpack/llms.txt

Uses the generic Pack API for cross-version compatibility in Zig. This approach requires a compatibility layer for buffer streams and manual configuration of reader/writer interfaces.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
	const allocator = std.heap.page_allocator;
	var buffer: [1024]u8 = undefined;

	// Use compatibility layer for cross-version support
	const compat = msgpack.compat;
	var write_buffer = compat.fixedBufferStream(&buffer);
	var read_buffer = compat.fixedBufferStream(&buffer);

	const BufferType = compat.BufferStream;
	var packer = msgpack.Pack(
		*BufferType,
		*BufferType,
		BufferType.WriteError,
		BufferType.ReadError,
		BufferType.write,
		BufferType.read,
	).init(&write_buffer, &read_buffer);

	// Create a complex payload
	var payload = msgpack.Payload.mapPayload(allocator);
	defer payload.free(allocator);

	try payload.mapPut("name", try msgpack.Payload.strToPayload("Alice", allocator));
	try payload.mapPut("age", msgpack.Payload.uintToPayload(30));
	try payload.mapPut("scores", blk: {
		var arr = try msgpack.Payload.arrPayload(3, allocator);
		try arr.setArrElement(0, msgpack.Payload.intToPayload(95));
		try arr.setArrElement(1, msgpack.Payload.intToPayload(87));
		try arr.setArrElement(2, msgpack.Payload.intToPayload(92));
		break :blk arr;
	});

	// Serialize
	try packer.write(payload);

	// Reset read position for deserialization
	read_buffer.pos = 0;

	// Deserialize
	const decoded = try packer.read(allocator);
	defer decoded.free(allocator);

	// Access decoded data
	const name = (try decoded.mapGet("name")).?.str.value();
	const age = (try decoded.mapGet("age")).?.uint;
	std.debug.print("Decoded: {s}, age {}\n", .{ name, age });
}
```

--------------------------------

### Serialize Data with PackerIO API (Zig 0.15+)

Source: https://context7.com/zigcc/zig-msgpack/llms.txt

Utilizes the PackerIO wrapper for simplified serialization in Zig 0.15 and later. This API integrates directly with standard I/O reader and writer interfaces.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
	var gpa = std.heap.GeneralPurposeAllocator(.{}){};
	defer _ = gpa.deinit();
	const allocator = gpa.allocator();

	var buffer: [1024]u8 = undefined;

	// Create Reader and Writer from fixed buffer
	var writer = std.Io.Writer.fixed(&buffer);
	var reader = std.Io.Reader.fixed(&buffer);

	// Create packer using PackerIO
	var packer = msgpack.PackerIO.init(&reader, &writer);

	// Create payload
	var map = msgpack.Payload.mapPayload(allocator);
	defer map.free(allocator);
	try map.mapPut("message", try msgpack.Payload.strToPayload("Hello!", allocator));
	try map.mapPut("count", msgpack.Payload.uintToPayload(42));

	// Serialize
	try packer.write(map);

	// Reset reader position
	reader.seek = 0;

	// Deserialize
	const decoded = try packer.read(allocator);
	defer decoded.free(allocator);

	const msg = (try decoded.mapGet("message")).?.str.value();
	std.debug.print("Message: {s}\n", .{msg});
}
```

--------------------------------

### Configure build.zig for MessagePack Dependency

Source: https://github.com/zigcc/zig-msgpack/blob/main/README.md

Configures the Zig build system to include the msgpack dependency as a module in an executable project.

```zig
const std = @import("std");

pub fn build(b: *std.Build) void {
	const target = b.standardTargetOptions(.{});
	const optimize = b.standardOptimizeOption(.{});

	const exe = b.addExecutable(.{
		.name = "my-app",
		.root_source_file = .{ .path = "src/main.zig" },
		.target = target,
		.optimize = optimize,
	});

	const msgpack_dep = b.dependency("zig_msgpack", .{
		.target = target,
		.optimize = optimize,
	});

	exe.root_module.addImport("msgpack", msgpack_dep.module("msgpack"));

	b.installArtifact(exe);
}
```

--------------------------------

### Handle Custom Extension Types in Zig

Source: https://context7.com/zigcc/zig-msgpack/llms.txt

Demonstrates how to create and access custom application-specific data using MessagePack extension types. It requires an allocator to manage the payload memory and a type identifier between -128 and 127.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
	const allocator = std.heap.page_allocator;

	// Create extension with custom type ID (e.g., 5 for application-specific type)
	const custom_data = [_]u8{ 0xCA, 0xFE, 0xBA, 0xBE };
	const ext_val = try msgpack.Payload.extToPayload(5, &custom_data, allocator);
	defer ext_val.free(allocator);

	// Access extension data
	std.debug.print("Extension type: {}, data length: {}\n", .{
		ext_val.ext.type,
		ext_val.ext.data.len,
	});
}
```

--------------------------------

### Handle MessagePack Errors in Zig

Source: https://context7.com/zigcc/zig-msgpack/llms.txt

Demonstrates how to handle MessagePack-specific errors in Zig, such as type mismatches, invalid map/array access, and security limit violations. This ensures robust application behavior when processing MessagePack data.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
    const allocator = std.heap.page_allocator;

    // Type mismatch error handling
    const int_payload = msgpack.Payload.intToPayload(-42);

    // Trying to get unsigned from negative value
    const uint_result = int_payload.getUint() catch |err| {
        switch (err) {
            msgpack.MsgPackError.InvalidType => {
                std.debug.print("Cannot convert negative to unsigned\n", .{});
                return;
            },
            else => return err,
        }
    };
    _ = uint_result;

    // Map/Array type errors
    const not_a_map = msgpack.Payload.intToPayload(42);
    _ = not_a_map.mapGet("key") catch |err| {
        switch (err) {
            error.NotMap => std.debug.print("Payload is not a map\n", .{}),
            else => return err,
        }
    };

    const not_an_array = msgpack.Payload.intToPayload(42);
    _ = not_an_array.getArrElement(0) catch |err| {
        switch (err) {
            error.NotArray => std.debug.print("Payload is not an array\n", .{}),
            else => return err,
        }
    };

    // Security limit errors (when using custom limits)
    // MsgPackError.MaxDepthExceeded - nesting too deep
    // MsgPackError.ArrayTooLarge - array exceeds limit
    // MsgPackError.MapTooLarge - map exceeds limit
    // MsgPackError.StringTooLong - string exceeds limit
    // MsgPackError.BinDataLengthTooLong - binary data exceeds limit
    // MsgPackError.ExtDataTooLarge - extension data exceeds limit
}

```

--------------------------------

### Use Semantic Constants for MessagePack Limits in Zig

Source: https://context7.com/zigcc/zig-msgpack/llms.txt

Employs semantic constant structures for clearer code when defining MessagePack format limits. This includes constants for string lengths, array/map sizes, integer bounds, and extension data lengths.

```zig
const std = @import("std");
const msgpack = @import("msgpack");

pub fn main() !void {
    // Fix type limits
    const max_fixstr = msgpack.FixLimits.STR_LEN_MAX;     // 31
    const max_fixarray = msgpack.FixLimits.ARRAY_LEN_MAX; // 15
    const max_fixmap = msgpack.FixLimits.MAP_LEN_MAX;     // 15

    // Integer bounds
    const uint8_max = msgpack.IntBounds.UINT8_MAX;   // 0xff
    const int8_min = msgpack.IntBounds.INT8_MIN;    // -128

    // Fixed extension lengths
    const ext4_len = msgpack.FixExtLen.EXT4;  // 4
    const ext8_len = msgpack.FixExtLen.EXT8;  // 8

    // Timestamp extension constants
    const ts_type = msgpack.TimestampExt.TYPE_ID;           // -1
    const ts32_len = msgpack.TimestampExt.FORMAT32_LEN;     // 4
    const max_nano = msgpack.TimestampExt.NANOSECONDS_MAX;  // 999_999_999

    std.debug.print("Max fixstr length: {}\n", .{max_fixstr});
    std.debug.print("Timestamp type ID: {}\n", .{ts_type});
    std.debug.print("Max nanoseconds: {}\n", .{max_nano});
}

```

--------------------------------

### MessagePack Security Error Types in Zig

Source: https://github.com/zigcc/zig-msgpack/blob/main/README.md

Lists the specific error types that can be raised by the zig-msgpack library when security limits are exceeded during parsing. These errors help identify and handle potential security vulnerabilities or data corruption issues.

```zig
msgpack.MsgPackError.MaxDepthExceeded    // Nesting too deep
msgpack.MsgPackError.ArrayTooLarge       // Array claims too many elements
msgpack.MsgPackError.MapTooLarge         // Map claims too many pairs
msgpack.MsgPackError.StringTooLong       // String data too large
msgpack.MsgPackError.BinDataLengthTooLong // Binary blob too large
msgpack.MsgPackError.ExtDataTooLarge     // Extension payload too large
```
Tokens:
Raw