Ruby binding

​

Install

gem install offline_protocol -v 0.31.0

gem "offline_protocol", "0.31.0"

# Linux
LD_LIBRARY_PATH=/path/to/dir ruby your_script.rb
# macOS
DYLD_LIBRARY_PATH=/path/to/dir ruby your_script.rb
# Windows (RubyInstaller reads RUBY_DLL_PATH, not PATH)
$env:RUBY_DLL_PATH = "C:\path\to\dir"; ruby your_script.rb

​

Quick start

require "offline_protocol"

Sdk = OfflineProtocol

# An instance-less function needs no engine.
puts Sdk.derive_address([0] * 32)

# Name the fields the definition leaves without a default; the rest take it.
config = Sdk::ProtocolConfig.new(
  app_id: "com.example.ruby", profile: "ruby-example",
  ble_enabled: false, wifi_direct_enabled: false, internet_enabled: true,
  reticulum_enabled: false, nostr_enabled: false, prefer_online: false,
  initial_ttl: 8, encryption_enabled: true, auto_key_exchange: true,
  # The pending queue: per peer, global, the SDK's 24 h lifetime, overflow.
  store_pending: true, max_pending_per_peer: 64, max_pending_global: 4096,
  pending_ttl_ms: 86_400_000, overflow_policy: Sdk::OverflowPolicy::DROP_OLDEST
)

engine = Sdk::OfflineProtocol.new(config)

# Any object that responds to on_event. It runs inside the engine call.
listener = Object.new
def listener.on_event(json) = puts(json)
engine.set_event_callback(listener)

engine.emit_test_event

​

Storage

engine.initialize_mls_with_file_stores(mls_dir, state_dir, store_key_32_bytes)

​

Bytes and threads

• Mask bytes before they go back in. A byte array the engine returns arrives signed, from -128 to 127, and is refused on the way back in. Mask it with map { |b| b & 0xFF } before passing it on, for example a key package from mls_get_or_create_key_package given to send_connection_request. Byte arrays inside event JSON are already 0 to 255.
• Callbacks run inside the engine. A callback must be safe from any thread, must not call back into the engine, and must raise nothing but the interface’s own error. Copy the event, queue it, return. poll_event takes events without a callback.
• Engine calls hold the VM lock. A slow call (start, initialize_mls, flush_telemetry_blocking) stops every Ruby thread until it returns. A server keeps such calls off its request threads.

​

What your host provides

• Transports. The radios and sockets, through the transport callbacks and the ble*, wifi_direct*, internet*, reticulum* and nostr* methods.
• Storage. The built-in file stores or two providers, as above.
• Telemetry platform. If you enable telemetry, pass TelemetryConfig os and os_major as the platform the process actually runs on (TelemetryOs::LINUX, MACOS or WINDOWS), read from the host.
• Lifecycle. start, stop and process on a timer, and one engine kept for the life of the process.

​

Reference

• Ruby binding README: building, testing and regenerating the binding.
• Ruby binding contract: library loading, defaults, callbacks, storage, signed bytes and the gem.
• offline_protocol on RubyGems.