messagepack 1.0.0

data/docs/_tutorials/getting-started.adoc

@@ -0,0 +1,165 @@
+---
+title: Getting started
+nav_order: 1
+---
+
+== Purpose
+
+This tutorial introduces the basics of using MessagePack Ruby to serialize and
+deserialize Ruby objects.
+
+== References
+
+* link:../pages/serialization[Serialization] - Core serialization concepts
+* link:../references/api[API reference] - Complete API documentation
+
+== Prerequisites
+
+* Basic knowledge of Ruby
+* Ruby 2.7 or higher
+
+== Installing the gem
+
+Add to your Gemfile:
+
+[source,ruby]
+----
+gem 'messagepack'
+----
+
+Or install directly:
+
+[source,shell]
+----
+gem install messagepack
+----
+
+== Your first serialization
+
+=== Basic pack and unpack
+
+[source,ruby]
+----
+require 'messagepack'
+
+# Pack some data
+data = { message: "Hello, MessagePack!" }
+binary = Messagepack.pack(data)
+
+# Inspect the binary (non-printable characters escaped)
+puts binary.inspect
+# => "\\x81\\xA7message\\xB4Hello, MessagePack!"
+
+# Unpack the data
+result = Messagepack.unpack(binary)
+puts result.inspect
+# => {"message"=>"Hello, MessagePack!"}
+----
+
+=== Working with different types
+
+[source,ruby]
+----
+# Numbers
+Messagepack.pack(42)          # Integer
+Messagepack.pack(3.14)        # Float
+Messagepack.pack(-100)        # Negative integer
+
+# Strings and symbols
+Messagepack.pack("hello")     # String
+Messagepack.pack(:world)      # Symbol (serialized as string)
+
+# Collections
+Messagepack.pack([1, 2, 3])   # Array
+Messagepack.pack({a: 1})      # Hash
+
+# Special values
+Messagepack.pack(nil)         # Nil
+Messagepack.pack(true)        # Boolean true
+Messagepack.pack(false)       # Boolean false
+----
+
+== Working with IO
+
+=== Writing to a file
+
+[source,ruby]
+----
+data = { name: "Alice", age: 30, skills: ["Ruby", "Python"] }
+
+# Write to file
+File.open("data.msgpack", "wb") do |file|
+  file.write(Messagepack.pack(data))
+end
+----
+
+=== Reading from a file
+
+[source,ruby]
+----
+# Read from file
+data = File.read("data.msgpack", encoding: Encoding::BINARY)
+result = Messagepack.unpack(data)
+# => {"name"=>"Alice", "age"=>30, "skills"=>["Ruby", "Python"]}
+----
+
+=== Using IO directly
+
+[source,ruby]
+----
+# Unpack can read from IO directly
+File.open("data.msgpack", "rb") do |file|
+  result = Messagepack.unpack(file)
+end
+----
+
+== Practical example: Configuration file
+
+Create a simple configuration system using MessagePack:
+
+[source,ruby]
+----
+require 'messagepack'
+
+class Config
+  def initialize(path)
+    @path = path
+    @data = load
+  end
+
+  def [](key)
+    @data[key]
+  end
+
+  def []=(key, value)
+    @data[key] = value
+    save
+  end
+
+  private
+
+  def load
+    if File.exist?(@path)
+      Messagepack.unpack(File.read(@path, encoding: Encoding::BINARY))
+    else
+      {}
+    end
+  end
+
+  def save
+    File.write(@path, Messagepack.pack(@data))
+  end
+end
+
+# Usage
+config = Config.new("config.msgpack")
+config[:database] = { host: "localhost", port: 5432 }
+config[:debug] = true
+
+puts config[:database][:host]  # => "localhost"
+----
+
+== Next steps
+
+* link:../tutorials/extension-types[Custom extension types] - Learn to serialize custom classes
+* link:../guides/performance[Performance guide] - Optimize your serialization code

data/docs/_tutorials/index.adoc

@@ -0,0 +1,14 @@
+---
+title: Tutorials
+nav_order: 1
+---
+
+== Purpose
+
+Tutorials provide step-by-step learning paths for mastering MessagePack Ruby.
+
+== Tutorials
+
+* link:../tutorials/getting-started[Getting started] - Introduction to basic serialization
+* link:../tutorials/extension-types[Custom extension types] - Creating custom type mappings
+* link:../tutorials/thread-safety[Thread-safe usage] - Using factories in multi-threaded applications

data/docs/_tutorials/thread-safety.adoc

@@ -0,0 +1,157 @@
+---
+title: Thread-safe usage
+nav_order: 3
+---
+
+== Purpose
+
+This tutorial explains how to use MessagePack factories safely in multi-threaded
+applications.
+
+== References
+
+* link:../pages/factory-pattern[Factory pattern] - Factory concepts
+* link:../guides/performance[Performance guide] - Performance optimization
+
+== Prerequisites
+
+* Completed link:../tutorials/getting-started[Getting started] tutorial
+* Basic understanding of Ruby threads
+
+== Understanding thread safety
+
+The `Messagepack::Factory` class provides two approaches for thread-safe usage:
+
+* **Frozen factory** - Safe for concurrent reads
+* **Factory pool** - Safe for concurrent reads and writes
+
+== Using frozen factories
+
+For concurrent serialization with custom types:
+
+[source,ruby]
+----
+# Create and configure factory
+factory = Messagepack::Factory.new
+factory.register_type(0x01, MyClass, packer: ..., unpacker: ...)
+
+# Freeze to make thread-safe
+factory.freeze
+
+# Now safe to use from multiple threads
+threads = 10.times.map do
+  Thread.new { factory.pack(my_object) }
+end
+results = threads.map(&:value)
+----
+
+NOTE: Frozen factories are safe for concurrent packing but not for unpacking
+from a shared unpacker. Use pools for full thread safety.
+
+== Using factory pools
+
+Pools provide the highest level of thread safety:
+
+[source,ruby]
+----
+# Create pool with 5 instances
+pool = factory.pool(5)
+
+# Use from multiple threads
+threads = 20.times.map do |i|
+  Thread.new do
+    # Each thread gets its own packer/unpacker from the pool
+    data = { id: i, value: "thread-#{i}" }
+    binary = pool.pack(data)
+    pool.unpack(binary)
+  end
+end
+
+results = threads.map(&:value)
+----
+
+=== Pool size guidelines
+
+Choose pool size based on your concurrency needs:
+
+[source,ruby]
+----
+# For thread pool of 10 workers
+pool = factory.pool(10)
+
+# For unlimited concurrency, use number of CPU cores
+pool = factory.pool(Erl::Concurrency.available_processors)
+
+# Default: 4 instances
+pool = factory.pool(4)
+----
+
+== Practical example: Web server
+
+[source,ruby]
+----
+require 'messagepack'
+
+class Cache
+  def initialize
+    @factory = Messagepack::Factory.new
+    @factory.register_type(0x01, CachedObject, ...)
+    @pool = @factory.pool(10)
+  end
+
+  def put(key, value)
+    binary = @pool.pack(value)
+    redis.set("cache:#{key}", binary)
+  end
+
+  def get(key)
+    data = redis.get("cache:#{key}")
+    return nil unless data
+    @pool.unpack(data)
+  end
+end
+
+# Thread-safe for web server
+cache = Cache.new
+
+# In web requests (concurrent)
+Thread.new do
+  cache.put("user:123", user_data)
+end
+
+Thread.new do
+  user = cache.get("user:123")
+end
+----
+
+== Performance considerations
+
+[source,ruby]
+----
+# Benchmark different approaches
+require 'benchmark'
+
+n = 10000
+
+Benchmark.bm do |x|
+  x.report("pack:") do
+    factory = Messagepack::Factory.new
+    n.times { factory.pack(data) }
+  end
+
+  x.report("pool(2):") do
+    pool = factory.pool(2)
+    n.times { pool.pack(data) }
+  end
+
+  x.report("pool(10):") do
+    pool = factory.pool(10)
+    n.times { pool.pack(data) }
+  end
+end
+----
+
+== Next steps
+
+* link:../guides/performance[Performance guide] - Optimize for performance
+* link:../references/api[API reference] - Complete API documentation

data/docs/index.adoc

@@ -0,0 +1,77 @@
+---
+title: MessagePack Ruby
+nav_order: 1
+---
+
+== Purpose
+
+MessagePack Ruby is a pure Ruby implementation of the https://msgpack.org/[MessagePack] binary serialization format. MessagePack is an efficient binary serialization format that enables exchange of data among multiple languages like JSON, but is faster and smaller.
+
+This implementation provides:
+
+* Pure Ruby implementation (no C extension required)
+* Full compatibility with the MessagePack specification
+* Support for custom extension types
+* Thread-safe factory pattern for packer/unpacker reuse
+* Streaming unpacker for incremental parsing
+* Comprehensive timestamp support with nanosecond precision
+
+== Getting started
+
+=== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'messagepack'
+----
+
+And then execute:
+
+[source,shell]
+----
+bundle install
+----
+
+Or install it yourself as:
+
+[source,shell]
+----
+gem install messagepack
+----
+
+=== Quick start
+
+[source,ruby]
+----
+require 'messagepack'
+
+# Serialize data
+data = { hello: "world", count: 42 }
+binary = Messagepack.pack(data)
+
+# Deserialize data
+result = Messagepack.unpack(binary)
+# => {"hello"=>"world", "count"=>42}
+----
+
+== Core concepts
+
+* link:pages/serialization[Serialization] - Converting Ruby objects to binary format and back
+* link:pages/factory-pattern[Factory pattern] - Thread-safe packer/unpacker management
+* link:pages/extension-types[Extension types] - Custom type registration system
+* link:pages/buffer[Buffer management] - Efficient chunked binary data storage
+* link:pages/streaming[Streaming] - Incremental data parsing
+
+== Learn more
+
+* link:tutorials/getting-started[Getting started tutorial] - Step-by-step introduction
+* link:guides/performance[Performance guide] - Optimization techniques and best practices
+* link:references/api[API reference] - Complete API documentation
+
+== External resources
+
+* https://msgpack.org/[MessagePack specification] - Official format specification
+* https://github.com/msgpack/msgpack/blob/master/spec.md[MessagePack spec] - Detailed format documentation
+* https://github.com/lutaml/messagepack[GitHub repository] - Source code and issues

data/docs/lychee.toml

@@ -0,0 +1,42 @@
+# Lychee link checker configuration
+
+# Exclude specific URLs
+exclude = [
+  # Exclude localhost links
+  "http://localhost",
+  "https://localhost",
+
+  # Exclude example domains that may not resolve
+  "http://example.com",
+  "https://example.com",
+
+  # Exclude links that require authentication
+  "https://github.com/lutaml/*",
+]
+
+# Only check http and https links
+schemes = ["http", "https"]
+
+# Maximum number of concurrent requests
+max_concurrency = 8
+
+# Maximum number of redirects to follow
+max_redirects = 10
+
+# Request timeout in seconds
+timeout = 20
+
+# User agent for requests
+user_agent = "lychee/0.14.0"
+
+# Accept 200, 204, 301, 302, 304, 307, 308 status codes
+accept = [200, 204, 301, 302, 304, 307, 308]
+
+# Method to use for requests (GET or HEAD)
+method = "get"
+
+# Verbose output
+verbose = false
+
+# Do not show progress
+no_progress = true

data/lib/messagepack/bigint.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative 'extensions/value'
+
+module Messagepack
+  # Bigint extension type for arbitrary precision integers.
+  #
+  # This class handles integers that are too large for 64-bit representation.
+  # Uses the same format as msgpack-ruby: 32-bit big-endian chunks.
+  #
+  class Bigint
+    # Bigint extension type ID
+    TYPE = 0
+
+    # Number of bits per chunk
+    CHUNK_BITLENGTH = 32
+
+    # Ruby pack format: sign byte + 32-bit big-endian chunks
+    FORMAT = 'CL>*'
+
+    attr_reader :data
+
+    def initialize(data)
+      @data = data
+    end
+
+    # Serialize an integer to MessagePack bigint extension format.
+    #
+    # @param int [Integer] The integer to serialize
+    # @return [String] Binary payload
+    #
+    def self.to_msgpack_ext(int)
+      # Format: [sign(1 byte)][32-bit big-endian chunks...]
+      # sign: 0 for positive, 1 for negative
+      # chunks: absolute value split into 32-bit pieces, LSB first, each in big-endian byte order
+
+      if int == 0
+        return "\x00".b
+      end
+
+      members = []
+
+      # Sign byte
+      if int < 0
+        int = -int
+        members << 1
+      else
+        members << 0
+      end
+
+      # Split into 32-bit chunks (least significant chunk first)
+      base = (2 ** CHUNK_BITLENGTH) - 1
+      while int > 0
+        members << (int & base)
+        int >>= CHUNK_BITLENGTH
+      end
+
+      # Pack as sign byte + 32-bit big-endian chunks
+      members.pack(FORMAT)
+    end
+
+    # Deserialize from binary payload.
+    #
+    # @param data [String] Binary payload
+    # @return [Integer] The deserialized integer
+    #
+    def self.from_msgpack_ext(data)
+      return 0 if data.nil? || data.empty?
+
+      # Unpack as sign byte + 32-bit big-endian chunks
+      parts = data.unpack(FORMAT)
+
+      return 0 if parts.empty?
+
+      sign = parts.shift
+
+      return 0 if parts.empty?
+
+      # Reconstruct integer from chunks (LSB first)
+      sum = parts.pop.to_i
+      parts.reverse_each do |part|
+        sum = (sum << CHUNK_BITLENGTH) | part.to_i
+      end
+
+      sign == 0 ? sum : -sum
+    end
+
+    # Create a Bigint from an integer.
+    #
+    # @param int [Integer] The integer
+    # @return [Bigint] A new Bigint instance
+    #
+    def self.from_int(int)
+      new(to_msgpack_ext(int))
+    end
+
+    # Convert to integer.
+    #
+    # @return [Integer] The integer value
+    #
+    def to_int
+      self.class.from_msgpack_ext(@data)
+    end
+
+    # Equality comparison.
+    #
+    # @param other [Object] Another object
+    # @return [Boolean]
+    #
+    def ==(other)
+      return false unless other.is_a?(Bigint)
+      to_int == other.to_int
+    end
+
+    alias eql? ==
+
+    def hash
+      to_int.hash
+    end
+
+    # String representation.
+    #
+    # @return [String]
+    #
+    def to_s
+      "Bigint(#{@data.bytes.map { |b| '0x%02x' % b }.join(' ')})"
+    end
+
+    alias inspect to_s
+  end
+end