Module: Turbocable::Codecs::MsgPack

Defined in:
lib/turbocable/codecs/msgpack.rb

Overview

MessagePack codec.

Encodes payloads using MessagePack with registered ext types for Time and Symbol. The ext type IDs are coordinated with the TurboCable JS client — the server uses plain rmp_serde and does not interpret ext types (it forwards raw bytes downstream once it confirms the payload is valid MessagePack).

Ext type registry (coordinated with JS client)

EXT_TYPE_SYMBOL = 0   # Symbol encoded as UTF-8 string bytes
EXT_TYPE_TIME   = 1   # Time encoded as int64 (seconds) + int32 (nsec), big-endian

Optional dependency

This codec requires the msgpack gem (~> 1.7), which is not a hard dependency of turbocable_nats. Add it to your Gemfile:

gem "msgpack", "~> 1.7"

A LoadError with install instructions is raised on first use if the gem is unavailable.

MRI only

The msgpack gem’s native extension is MRI-only. JRuby and TruffleRuby are not supported for this codec.

Constant Summary collapse

EXT_TYPE_SYMBOL =

Ext type ID for Symbol, encoded as its UTF-8 string representation. Coordinated with the TurboCable JS client decoder — do not change without a matching update there.

0
EXT_TYPE_TIME =

Ext type ID for Time, encoded as 12 bytes: big-endian int64 (seconds since Unix epoch) + big-endian int32 (nanoseconds). Coordinated with the TurboCable JS client decoder — do not change without a matching update there.

1

Class Method Summary collapse

Class Method Details

.content_type ⇒ String

Returns the WebSocket sub-protocol name for this codec.

Returns:

  • (String) —

    the WebSocket sub-protocol name for this codec



48
49
50
 
# File 'lib/turbocable/codecs/msgpack.rb', line 48

def self.content_type
  "turbocable-v1-msgpack"
end

.decode(bytes) ⇒ Object

Deserializes MessagePack bytes back to a Ruby value. Intended for testing and round-trip specs; production subscribers are WebSocket clients, not this gem.

Parameters:

  • bytes (String) —

    MessagePack-encoded bytes

Returns:

  • (Object)

Raises:

  • (LoadError) —

    if the msgpack gem is not installed



76
77
78
79
 
# File 'lib/turbocable/codecs/msgpack.rb', line 76

def self.decode(bytes)
  require_msgpack!
  factory.unpack(bytes)
end

.encode(payload) ⇒ String

Serializes payload to MessagePack bytes.

Parameters:

  • payload (Object) —

    any MessagePack-serializable value

Returns:

  • (String) —

    binary MessagePack bytes (ASCII-8BIT encoding)

Raises:



58
59
60
61
62
63
64
65
66
67
 
# File 'lib/turbocable/codecs/msgpack.rb', line 58

def self.encode(payload)
  require_msgpack!
  factory.pack(payload)
rescue ::TypeError, ::NoMethodError => e
  raise Turbocable::SerializationError.new(
    "MsgPack codec failed to encode #{payload.class}: #{e.message}",
    codec_name: :msgpack,
    payload_class: payload.class
  )
end

.factory ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the shared factory instance, building it on first call.



83
84
85
86
87
 
# File 'lib/turbocable/codecs/msgpack.rb', line 83

def self.factory
  return @factory if @factory

  FACTORY_MUTEX.synchronize { @factory ||= build_factory }
end

.reset_factory! ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Resets the cached factory. Used in tests that need a fresh state.



91
92
93
 
# File 'lib/turbocable/codecs/msgpack.rb', line 91

def self.reset_factory!
  FACTORY_MUTEX.synchronize { @factory = nil }
end