messagepack 1.0.0

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/docs/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 3.10"
+gem "just-the-docs", "~> 0.7.0"
+gem "jekyll-asciidoc", "~> 3.0"
+gem "jekyll-seo-tag", "~> 2.8"
+gem "jekyll-sitemap", "~> 2.4"

data/docs/README.md

@@ -0,0 +1,85 @@
+# MessagePack Documentation
+
+This directory contains the documentation site for the MessagePack Ruby gem, built with Jekyll and the just-the-docs theme.
+
+## Building locally
+
+### Prerequisites
+
+- Ruby 3.3 or higher
+- Bundler
+
+### Install dependencies
+
+```bash
+cd docs
+bundle install
+```
+
+### Build the site
+
+```bash
+bundle exec jekyll build
+```
+
+The built site will be in `_site/`.
+
+### Serve locally
+
+```bash
+bundle exec jekyll serve
+```
+
+Visit `http://localhost:4000/messagepack/` to view the site.
+
+## Running link checker
+
+Install lychee:
+
+```bash
+# macOS
+brew install lychee
+
+# Or with cargo
+cargo install lychee
+
+# Or use Docker
+docker run -v $(pwd):/work lycheeverse/lychee ./docs
+```
+
+Run link checker:
+
+```bash
+# Build the site first
+bundle exec jekyll build
+
+# Check links
+lychee --config lychee.toml _site/**/*.html
+```
+
+## Documentation structure
+
+- `index.adoc` - Main entry point
+- `_pages/` - Core topics (fundamental concepts)
+- `_tutorials/` - Step-by-step learning guides
+- `_guides/` - Task-oriented documentation
+- `_references/` - Technical specifications and API docs
+
+## Adding new documentation
+
+1. Create new `.adoc` file in the appropriate collection directory
+2. Add YAML front matter with `title`, `parent`, and `nav_order`
+3. Follow the template structure:
+   - Purpose section
+   - References section
+   - Concepts section
+   - Examples section
+4. Update the collection's index.adoc to include the new page
+
+## CI/CD
+
+Documentation is automatically built and deployed to GitHub Pages:
+- On push to `main` branch
+- When files in `docs/` change
+
+Links are automatically checked with lychee on every push and PR.

data/docs/_config.yml

@@ -0,0 +1,137 @@
+# Site settings
+title: MessagePack Ruby
+description: >-
+  Pure Ruby implementation of the MessagePack binary serialization format
+baseurl: "/messagepack"
+url: "https://lutaml.github.io"
+
+# Theme
+theme: just-the-docs
+remote_theme: just-the-docs/just-the-docs@v0.7.0
+
+# Color scheme
+color_scheme: light
+
+# Search
+search_enabled: true
+search:
+  heading_level: 2
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: false
+
+# Heading anchors
+heading_anchors: true
+
+# Aux links for the upper right navigation
+aux_links:
+  "GitHub":
+    - "https://github.com/lutaml/messagepack"
+  "RubyGems":
+    - "https://rubygems.org/gems/messagepack"
+
+# Makes Aux links open in a new tab
+aux_links_new_tab: true
+
+# Back to top link
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# Footer content
+footer_content: >-
+  Copyright © 2025 Ribose. Distributed by an
+  <a href="https://github.com/lutaml/messagepack/blob/main/LICENSE">MIT license</a>.
+
+# Footer last edit timestamp
+last_edit_timestamp: true
+last_edit_time_format: "%b %e %Y at %I:%M %p"
+
+# Navigation structure
+nav_sort: order
+
+# Collections for organizing content
+collections:
+  pages:
+    permalink: "/:path/"
+    output: true
+  tutorials:
+    permalink: "/:collection/:path/"
+    output: true
+  guides:
+    permalink: "/:collection/:path/"
+    output: true
+  references:
+    permalink: "/:collection/:path/"
+    output: true
+
+# Just the Docs collection configuration
+just_the_docs:
+  collections:
+    pages:
+      name: Core topics
+      nav_fold: false
+    tutorials:
+      name: Tutorials
+      nav_fold: true
+    guides:
+      name: Guides
+      nav_fold: true
+    references:
+      name: References
+      nav_fold: true
+
+# Plugins
+plugins:
+  - jekyll-asciidoc
+  - jekyll-seo-tag
+  - jekyll-sitemap
+
+# AsciiDoc configuration
+asciidoc: {}
+asciidoctor:
+  attributes:
+    - source-highlighter=rouge
+    - rouge-style=github
+    - icons=font
+    - sectanchors=true
+    - idprefix=
+    - idseparator=-
+    - experimental=true
+
+include:
+  - '*.adoc'
+
+# Exclude from processing
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - _site
+  - node_modules
+  - vendor/bundle/
+  - vendor/cache/
+  - vendor/gems/
+  - vendor/ruby/
+
+# Enable code copy button
+enable_copy_code_button: true
+
+# Callouts
+callouts_level: quiet
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red

data/docs/_guides/index.adoc

@@ -0,0 +1,14 @@
+---
+title: Guides
+nav_order: 1
+---
+
+== Purpose
+
+Guides provide task-oriented documentation for specific use cases.
+
+== Guides
+
+* link:../guides/performance[Performance optimization] - Techniques for maximizing performance
+* link:../guides/io-streaming[IO streaming] - Working with files and network streams
+* link:../guides/migration[Migration guide] - Migrating from other MessagePack implementations

data/docs/_guides/io-streaming.adoc

@@ -0,0 +1,226 @@
+---
+title: IO streaming
+nav_order: 2
+---
+
+== Purpose
+
+This guide explains how to work with IO objects and network streams using
+MessagePack.
+
+== References
+
+* link:../pages/streaming[Streaming] - Streaming unpacker concepts
+* link:../pages/buffer[Buffer management] - Buffer IO integration
+
+== Concepts
+
+=== IO-based unpacking
+
+The unpacker can work directly with IO objects:
+
+* Automatically reads data as needed
+* Efficient chunked buffering
+* Suitable for files and network sockets
+
+=== Streaming unpacker
+
+Feed data incrementally:
+
+* Parse incomplete data
+* Handle chunked responses
+* Process multiple objects from stream
+
+== Working with files
+
+=== Writing to files
+
+[source,ruby]
+----
+data = { name: "Alice", items: [1, 2, 3] }
+
+# Pack and write
+File.open("output.msgpack", "wb") do |file|
+  packed = Messagepack.pack(data)
+  file.write(packed)
+end
+
+# Or use pack with IO directly
+File.open("output.msgpack", "wb") do |file|
+  Messagepack.pack(data, file)
+end
+----
+
+=== Reading from files
+
+[source,ruby]
+----
+# Read and unpack
+data = File.read("output.msgpack", encoding: Encoding::BINARY)
+result = Messagepack.unpack(data)
+
+# Or use unpack with IO directly
+File.open("output.msgpack", "rb") do |file|
+  result = Messagepack.unpack(file)
+end
+----
+
+=== Processing large files
+
+[source,ruby]
+----
+# For files with multiple objects, use streaming
+unpacker = Messagepack::Unpacker.new(File.open("large.msgpack", "rb"))
+
+while obj = unpacker.read
+  process(obj)
+end
+----
+
+== Network streaming
+
+=== TCP server example
+
+[source,ruby]
+----
+require 'socket'
+require 'messagepack'
+
+server = TCPServer.new(2000)
+
+loop do
+  client = server.accept
+  unpacker = Messagepack::Unpacker.new(client)
+
+  while obj = unpacker.read
+    # Process each message
+    response = handle_message(obj)
+
+    # Send response
+    packed = Messagepack.pack(response)
+    client.write(packed)
+  end
+
+  client.close
+end
+----
+
+=== TCP client example
+
+[source,ruby]
+----
+require 'socket'
+require 'messagepack'
+
+socket = TCPSocket.new('localhost', 2000)
+
+# Send request
+request = { action: "ping", data: "hello" }
+socket.write(Messagepack.pack(request))
+
+# Read response
+unpacker = Messagepack::Unpacker.new(socket)
+response = unpacker.read
+
+puts response.inspect
+socket.close
+----
+
+=== HTTP streaming
+
+[source,ruby]
+----
+require 'net/http'
+require 'messagepack'
+
+uri = URI('http://example.com/stream')
+http = Net::HTTP.new(uri.host, uri.port)
+
+request = Net::HTTP::Get.new(uri.request_uri)
+http.request(request) do |response|
+  unpacker = Messagepack::Unpacker.new
+
+  response.read_body do |chunk|
+    unpacker.feed(chunk)
+
+    while obj = unpacker.read
+      process(obj)
+    end
+  end
+end
+----
+
+== WebSocket streaming
+
+[source,ruby]
+----
+# Using websocket-client-simple gem
+require 'websocket-client-simple'
+require 'messagepack'
+
+ws = WebSocket::Client::Simple.connect('ws://example.com/stream')
+
+unpacker = Messagepack::Unpacker.new
+
+ws.on :message do |msg|
+  unpacker.feed(msg.data)
+
+  while obj = unpacker.read
+    puts "Received: #{obj.inspect}"
+  end
+end
+
+ws.on :open do
+  # Send MessagePack data
+  ws.send(Messagepack.pack({type: "subscribe", channel: "updates"}))
+end
+----
+
+== Error handling
+
+=== Handling incomplete data
+
+[source,ruby]
+----
+unpacker = Messagepack::Unpacker.new
+
+unpacker.feed(partial_data)
+obj = unpacker.read
+
+if obj
+  puts "Got object: #{obj.inspect}"
+else
+  puts "Need more data"
+end
+----
+
+=== Handling malformed data
+
+[source,ruby]
+----
+begin
+  result = Messagepack.unpack(invalid_data)
+rescue Messagepack::MalformedFormatError => e
+  puts "Invalid MessagePack: #{e.message}"
+rescue Messagepack::UnpackError => e
+  puts "Unpack error: #{e.message}"
+end
+----
+
+=== Handling IO errors
+
+[source,ruby]
+----
+begin
+  File.open("data.msgpack", "rb") do |file|
+    unpacker = Messagepack::Unpacker.new(file)
+    while obj = unpacker.read
+      process(obj)
+    end
+  end
+rescue Errno::ENOENT
+  puts "File not found"
+rescue IOError => e
+  puts "IO error: #{e.message}"
+end
+----

data/docs/_guides/migration.adoc

@@ -0,0 +1,218 @@
+---
+title: Migration guide
+nav_order: 3
+---
+
+== Purpose
+
+This guide helps you migrate from other MessagePack implementations to the
+pure Ruby MessagePack library.
+
+== References
+
+* link:../pages/serialization[Serialization] - Core API
+* link:../references/api[API reference] - Complete API documentation
+
+== From msgpack-ruby (C extension)
+
+The pure Ruby implementation aims for API compatibility with msgpack-ruby.
+
+=== Module name
+
+[source,ruby]
+----
+# msgpack-ruby
+MessagePack.pack(data)
+
+# messagepack (pure Ruby)
+Messagepack.pack(data)
+----
+
+The pure Ruby version uses `Messagepack` (single word) instead of `MessagePack`.
+
+=== Compatible APIs
+
+Most core APIs are compatible:
+
+[source,ruby]
+----
+# These work the same in both
+Messagepack.pack(data)
+Messagepack.unpack(data)
+Messagepack.load(data)
+Messagepack.dump(data)
+----
+
+=== Extension types
+
+Extension type registration is similar:
+
+[source,ruby]
+----
+# msgpack-ruby
+factory = MessagePack::Factory.new
+factory.register_type(0x01, MyClass, ...)
+
+# messagepack (pure Ruby)
+factory = Messagepack::Factory.new
+factory.register_type(0x01, MyClass, ...)
+----
+
+=== Differences
+
+* **Performance**: C extension is faster for most operations
+* **Dependencies**: Pure Ruby has no C dependencies
+* **Portability**: Pure Ruby works on any Ruby implementation
+
+=== Migration steps
+
+1. Update Gemfile:
+
+[source,ruby]
+----
+# Remove
+gem 'msgpack'
+
+# Add
+gem 'messagepack'
+----
+
+2. Update require statements:
+
+[source,ruby]
+----
+# Change
+require 'msgpack'
+
+# To
+require 'messagepack'
+----
+
+3. Update constant references:
+
+[source,ruby]
+----
+# Change
+MessagePack::Factory
+MessagePack::Unpacker
+
+# To
+Messagepack::Factory
+Messagepack::Unpacker
+----
+
+== From JSON serialization
+
+MessagePack is a binary alternative to JSON.
+
+=== Encoding data
+
+[source,ruby]
+----
+# JSON
+require 'json'
+JSON.generate({name: "Alice"})
+
+# MessagePack
+require 'messagepack'
+Messagepack.pack({name: "Alice"})
+----
+
+=== Decoding data
+
+[source,ruby]
+----
+# JSON
+JSON.parse('{"name":"Alice"}')
+
+# MessagePack
+Messagepack.unpack(binary_string)
+----
+
+=== Type differences
+
+[source,ruby]
+----
+# JSON only supports these types
+null, true, false, number, string, array, object
+
+# MessagePack supports additional types
+nil, boolean, integer, float, string, binary, array, map,
+timestamp, extension types
+----
+
+=== Migration pattern
+
+[source,ruby]
+----
+# Before (JSON)
+class Cache
+  def save(key, value)
+    File.write("cache/#{key}", JSON.generate(value))
+  end
+
+  def load(key)
+    JSON.parse(File.read("cache/#{key}"))
+  end
+end
+
+# After (MessagePack)
+class Cache
+  def save(key, value)
+    File.write("cache/#{key}", Messagepack.pack(value), mode: 'wb')
+  end
+
+  def load(key)
+    Messagepack.unpack(File.read("cache/#{key}", encoding: Encoding::BINARY))
+  end
+end
+----
+
+== Compatibility mode
+
+For compatibility with older MessagePack implementations:
+
+[source,ruby]
+----
+# Use compatibility mode to avoid bin/str8 types
+binary = Messagepack.pack(data, compatibility_mode: true)
+----
+
+This ensures:
+* Binary data uses str16/str32 instead of bin8/bin16/bin32
+* Strings use str16/str32 instead of str8
+
+== Testing your migration
+
+=== Verify serialization
+
+[source,ruby]
+----
+# Test that data round-trips correctly
+def test_serialization(data)
+  binary = Messagepack.pack(data)
+  result = Messagepack.unpack(binary)
+  result == data
+end
+
+# Test various types
+test_serialization(nil)
+test_serialization(true)
+test_serialization(42)
+test_serialization(3.14)
+test_serialization("hello")
+test_serialization([1, 2, 3])
+test_serialization({a: 1, b: 2})
+----
+
+=== Compare with old implementation
+
+[source,ruby]
+----
+# Verify compatibility by comparing outputs
+old_binary = OldImpl.pack(data)
+new_binary = Messagepack.pack(data)
+
+# Results should be identical for standard types
+# (extension types may differ)
+----