unison-client 0.1.0

data/Cargo.toml

@@ -0,0 +1,11 @@
+# Ruby client gem の native 拡張 workspace。
+#
+# gem root に置くのは rb_sys（rake-compiler）の要請: `cargo metadata` を
+# gem root から実行するため、ここに manifest が無いと cargo が親へ遡り
+# club-unison の workspace を誤って拾う。
+#
+# 親 (club-unison) の Cargo workspace は `crates/*` のみを member とするため
+# この workspace とは独立。両者が干渉することはない。
+[workspace]
+members = ["ext/unison_client"]
+resolver = "3"

data/README.md

@@ -0,0 +1,110 @@
+# unison-client (Ruby)
+
+[Unison protocol](https://github.com/chronista-club/club-unison) の Ruby client。
+
+## アーキテクチャ
+
+これは **言語バインディング**であって protocol の再実装ではない。
+QUIC トランスポート・channel 多重化・wire framing は Rust の `club-unison`
+crate が実装しており、この gem はそれを **Magnus**（Rust 製 Ruby native
+extension）経由で薄く包む。
+
+```
+Ruby (require "unison")
+  └─ native ext  (Magnus, ext/unison_client/)
+       └─ club-unison crate  (ProtocolClient — QUIC / channel / wire)
+```
+
+理由: Ruby に成熟した native QUIC スタックが無いため、protocol を Ruby で
+再実装するより Rust core を FFI で binding する方が経済的。TS SDK は browser
+の WebTransport に乗れたので完全再実装したが、Ruby にはその前提が無い。
+
+## 状態
+
+接続ライフサイクルと channel 層を実装済み。
+
+```ruby
+require "unison"
+
+client = Unison::Client.new
+client.connect("quic://[::1]:7878")
+
+ch = client.open_channel("greeter")
+ch.request("Hello", { "name" => "Mako" })   #=> レスポンス Hash
+ch.send_event("Ping", { "seq" => 1 })        # 応答不要
+ch.recv                                      # 次の event を待つ（Hash）
+ch.close
+
+client.disconnect
+```
+
+> **注意**: `Unison::Client.new` は証明書検証を行わない insecure な client を
+> 構築する（loopback / 開発用途）。trust anchor を明示する secure constructor は
+> 今後のフェーズ。
+
+channel payload は native な Ruby 値（`Hash` / `Array` / scalar）で渡せる。
+Rust 側で `serde_magnus` が `serde_json::Value` へ双方向変換し、channel の
+JSON codec が処理する。
+
+async は extension 内に埋めた tokio runtime で `block_on` する。ブロッキング
+呼び出しは `rb_thread_call_without_gvl` で **GVL を解放**するため、待機中も他の
+Ruby スレッドは動き続ける（呼び出し自体の中断・タイムアウトは未対応 — 今後の
+refinement）。
+
+失敗はすべて `Unison::Error`（`< StandardError`）として raise される。
+
+次フェーズ: GVL 解放中の呼び出しの中断（unblock function）、`recv` の timeout 版。
+
+## ビルド・テスト
+
+```
+bundle install
+bundle exec rake compile    # native 拡張をビルド
+bundle exec rake test       # compile → 単体テスト（ネットワーク不要）
+bundle exec rake test:e2e   # compile → E2E（`unison mock` を subprocess 起動）
+```
+
+`rake test:e2e` は `unison` バイナリ（`cargo build -p unison-cli` で生成、または
+`UNISON_MOCK_BIN` で指定）を要する。見つからない場合は skip される。
+
+**Ruby 3.4 以上が必須。** Ruby 3.4 系と 4.0 系の両方で動作する。開発環境の
+version は `.mise.toml` に固定（既定 3.4.9、 4.0.5 も同居）。
+
+## ベンチマーク
+
+```
+ruby bench/bench.rb > bench/runs/<date>-<tag>.kdl
+```
+
+`unison mock` を subprocess 起動し、(1) `Channel#request` の RTT / throughput と
+(2) GVL 解放の効果（ブロッキング呼び出し中に背景スレッドが進む割合）を計測し、
+structured-log KDL を出力する。run は `bench/runs/` に immutable に蓄積し、
+`bench/index.kdl` が append-only インデックスとして参照する。
+
+## 対応 protocol 世代
+
+`1.0.0` GA — npm [`@chronista-club/unison-client@1.0.0`](https://www.npmjs.com/package/@chronista-club/unison-client) /
+crates.io [`club-unison@1.0.0`](https://crates.io/crates/club-unison) と同世代。
+gem 側の API は scaffold stage を抜けるまで gem 単独で stabilize する方針
+（gem version は `0.x` 系）。
+
+## インストール
+
+```ruby
+# Gemfile
+gem "unison-client"
+```
+
+```bash
+bundle install
+# または
+gem install unison-client
+```
+
+source-only gem（gem ファイルに Rust source を bundle）なので、 install 時に
+**Rust toolchain (`rustc` / `cargo`、 1.85 以上推奨)** が要求される。 toolchain が
+無い環境では rustup の `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+等で先に入れる。
+
+> 将来的に platform-specific な prebuilt binary gem へ移行予定（nokogiri / grpc
+> 等と同じ rake-compiler-dock + GitHub Actions matrix）。 0.1.0 では source-only。

data/ext/unison_client/Cargo.toml

@@ -0,0 +1,32 @@
+# crate 名は拡張ターゲット名（unison_client）と一致させる。gem 名はハイフン
+# 区切りの `unison-client`（gem 慣習）で、両者が別表記なのは想定どおり。
+[package]
+name = "unison_client"
+version = "0.1.0"
+edition = "2024"
+publish = false
+license = "MIT"
+description = "Native extension for the unison-client Ruby gem — Magnus binding over club-unison."
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = "0.8"
+# club-unison 本体（QUIC / channel / wire）。crate の package 名は club-unison、
+# lib 名は unison なので Rust 側は `use unison::...`。
+club-unison = "1.0.0"
+# block_on で async API を Ruby の同期呼び出しへ橋渡しするための runtime。
+tokio = { version = "1", features = ["rt-multi-thread"] }
+# channel payload の Ruby 値 ⇄ serde_json::Value 変換。serde_magnus は magnus
+# エコシステム標準で、magnus version を一致させる必要がある（0.11 → magnus 0.8）。
+serde_json = "1"
+serde_magnus = "0.11"
+# GVL 解放（rb_thread_call_without_gvl）の raw FFI。magnus 0.8 はこの C API を
+# 安全ラッパとして公開していないため rb-sys を直接使う。magnus が間接依存する
+# のと同じ crate（version 一致で unify）。
+rb-sys = "0.9"
+
+# cargo 単体（clippy / check）は rb-sys が Ruby ABI を要求するため通らない。
+# ビルド・lint は `bundle exec rake compile` 経由で行う（rb_sys が Ruby env を
+# 注入する）。

data/ext/unison_client/extconf.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Generates a Makefile that builds the Rust crate in this directory into the
+# gem's native extension, via rb-sys.
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("unison_client/unison_client")

data/ext/unison_client/src/lib.rs

@@ -0,0 +1,255 @@
+//! Native extension for the `unison-client` Ruby gem.
+//!
+//! Wraps the Rust `club-unison` crate as Ruby objects. The protocol itself
+//! (QUIC transport, channel multiplexing, wire framing) lives in Rust; this
+//! layer only bridges Ruby ⇄ Rust values and Ruby's blocking calls ⇄ the
+//! async runtime.
+//!
+//! - `Unison::Client`  — connection lifecycle, wraps `ProtocolClient`
+//! - `Unison::Channel` — request/response + event push, wraps `UnisonChannel`
+//! - `Unison::Error`   — base class for every failure this binding raises
+//!
+//! Channel payloads cross the boundary as native Ruby values: `serde_magnus`
+//! converts Ruby `Hash`/`Array`/… ⇄ `serde_json::Value`, which the channel's
+//! JSON codec consumes.
+//!
+//! Blocking calls release the GVL while parked on the network (see
+//! [`without_gvl`]), so other Ruby threads keep running.
+
+use std::ffi::c_void;
+use std::sync::OnceLock;
+
+use magnus::{Error, ExceptionClass, Ruby, Value, function, method, prelude::*};
+use serde_json::Value as JsonValue;
+use tokio::runtime::Runtime;
+use unison::{NetworkError, ProtocolClient, UnisonChannel};
+
+/// Process-wide multi-thread tokio runtime backing every blocking bridge.
+///
+/// One long-lived runtime: the QUIC reactor should outlive individual calls,
+/// and building a runtime per call would be wasteful. Created lazily on first
+/// use.
+fn runtime() -> &'static Runtime {
+    static RT: OnceLock<Runtime> = OnceLock::new();
+    RT.get_or_init(|| Runtime::new().expect("failed to build the Unison tokio runtime"))
+}
+
+/// Runs `f` with Ruby's GVL released, letting other Ruby threads proceed.
+///
+/// `f` MUST NOT touch any Ruby value or Ruby C API — it executes without the
+/// GVL. It runs on the *calling* thread (`rb_thread_call_without_gvl` does not
+/// move work elsewhere), so non-`Send` captures are fine.
+///
+/// Limitations, both future refinements:
+/// - No unblock function is registered, so a blocked call cannot be
+///   interrupted by Ruby (e.g. `Thread#kill`).
+/// - A panic inside `f` crosses an `extern "C"` boundary and aborts the
+///   process. The closures here (`block_on` of QUIC ops) are not expected to
+///   panic.
+fn without_gvl<F, R>(f: F) -> R
+where
+    F: FnOnce() -> R,
+{
+    /// Carries the closure in and its result out across the C boundary.
+    struct Payload<F, R> {
+        func: Option<F>,
+        result: Option<R>,
+    }
+
+    unsafe extern "C" fn trampoline<F, R>(arg: *mut c_void) -> *mut c_void
+    where
+        F: FnOnce() -> R,
+    {
+        // SAFETY: `arg` is the `&mut Payload` passed below; Ruby invokes this
+        // exactly once, on this thread, before `rb_thread_call_without_gvl`
+        // returns.
+        let payload = unsafe { &mut *(arg as *mut Payload<F, R>) };
+        let func = payload.func.take().expect("without_gvl closure already ran");
+        payload.result = Some(func());
+        std::ptr::null_mut()
+    }
+
+    let mut payload = Payload::<F, R> {
+        func: Some(f),
+        result: None,
+    };
+    // SAFETY: `trampoline::<F, R>` interprets the data pointer as
+    // `&mut Payload<F, R>`, which is exactly what we hand it; no unblock
+    // function is used.
+    unsafe {
+        rb_sys::rb_thread_call_without_gvl(
+            Some(trampoline::<F, R>),
+            (&raw mut payload).cast(),
+            None,
+            std::ptr::null_mut(),
+        );
+    }
+    payload.result.expect("without_gvl closure did not run")
+}
+
+/// Current `Ruby` handle.
+///
+/// Safe inside any function bound into Ruby: such code only runs while a Ruby
+/// method is on the stack, so the handle is always available.
+fn ruby() -> Ruby {
+    Ruby::get().expect("Unison binding used outside a Ruby thread")
+}
+
+/// Builds a `Unison::Error` exception carrying `msg`.
+///
+/// `Unison::Error` is defined once in `init`; this re-fetches it via the
+/// (idempotent) module handle rather than caching — error construction is
+/// never a hot path.
+fn unison_error(msg: impl Into<String>) -> Error {
+    let class: ExceptionClass = ruby()
+        .define_module("Unison")
+        .and_then(|m| m.const_get("Error"))
+        .expect("Unison::Error class is not defined");
+    Error::new(class, msg.into())
+}
+
+/// Turns a `NetworkError` into a `Unison::Error`.
+fn net_err(e: NetworkError) -> Error {
+    unison_error(e.to_string())
+}
+
+/// The Unison protocol generation this client is built against.
+fn protocol_target() -> &'static str {
+    "1.0.0-rc.1"
+}
+
+/// `Unison::Client` — a QUIC-backed Unison protocol client.
+///
+/// `ProtocolClient`'s methods all take `&self`, so no interior mutability is
+/// needed: the wrapped value is shared read-only and the QUIC state is
+/// managed internally by the Rust crate.
+#[magnus::wrap(class = "Unison::Client", free_immediately, size)]
+struct Client {
+    inner: ProtocolClient,
+}
+
+impl Client {
+    /// `Unison::Client.new` — builds a default QUIC-backed client.
+    ///
+    /// Does not open a connection; call `#connect` for that.
+    ///
+    /// **Warning**: backed by `ProtocolClient::new_default()`, which builds an
+    /// **insecure** client — TLS certificate verification is skipped (intended
+    /// for loopback / development). A secure constructor taking explicit trust
+    /// anchors is future work.
+    fn new() -> Result<Self, Error> {
+        let inner = ProtocolClient::new_default()
+            .map_err(|e| unison_error(format!("Unison::Client.new failed: {e}")))?;
+        Ok(Self { inner })
+    }
+
+    /// `client.connect(url)` — opens the QUIC connection to `url`.
+    ///
+    /// Blocks the calling thread until the handshake completes (the GVL is
+    /// released, so other Ruby threads keep running). Raises `Unison::Error`
+    /// on failure.
+    fn connect(&self, url: String) -> Result<(), Error> {
+        without_gvl(|| runtime().block_on(self.inner.connect(&url))).map_err(net_err)
+    }
+
+    /// `client.connected?` — whether the QUIC connection is currently open.
+    fn connected(&self) -> bool {
+        without_gvl(|| runtime().block_on(self.inner.is_connected()))
+    }
+
+    /// `client.disconnect` — closes the QUIC connection.
+    ///
+    /// Raises `Unison::Error` only if the close itself errors.
+    fn disconnect(&self) -> Result<(), Error> {
+        without_gvl(|| runtime().block_on(self.inner.disconnect())).map_err(net_err)
+    }
+
+    /// `client.open_channel(name)` — opens a named channel, returning a
+    /// `Unison::Channel`. Raises `Unison::Error` on failure.
+    fn open_channel(&self, name: String) -> Result<Channel, Error> {
+        let inner = without_gvl(|| runtime().block_on(self.inner.open_channel(&name)))
+            .map_err(net_err)?;
+        Ok(Channel { inner })
+    }
+}
+
+/// `Unison::Channel` — a request/response + event-push channel.
+///
+/// Constructed only via `Unison::Client#open_channel`; it has no public
+/// allocator. Payloads are native Ruby values (`Hash`/`Array`/scalars),
+/// carried over the channel's JSON codec.
+#[magnus::wrap(class = "Unison::Channel", free_immediately, size)]
+struct Channel {
+    inner: UnisonChannel,
+}
+
+impl Channel {
+    /// `channel.request(method, payload)` — sends a request and blocks until
+    /// the matching response arrives. Returns the response payload as a Ruby
+    /// value. Raises `Unison::Error` on a protocol error or timeout.
+    fn request(&self, method: String, payload: Value) -> Result<Value, Error> {
+        let ruby = ruby();
+        // Ruby → Rust conversion needs the GVL; do it before releasing it.
+        let req: JsonValue = serde_magnus::deserialize(&ruby, payload)?;
+        let resp: JsonValue = without_gvl(|| {
+            runtime().block_on(self.inner.request::<JsonValue, JsonValue>(&method, &req))
+        })
+        .map_err(net_err)?;
+        serde_magnus::serialize(&ruby, &resp)
+    }
+
+    /// `channel.send_event(method, payload)` — sends a fire-and-forget event
+    /// (no response is awaited).
+    fn send_event(&self, method: String, payload: Value) -> Result<(), Error> {
+        let event: JsonValue = serde_magnus::deserialize(&ruby(), payload)?;
+        without_gvl(|| runtime().block_on(self.inner.send_event(&method, &event)))
+            .map_err(net_err)
+    }
+
+    /// `channel.recv` — blocks until the next inbound event (server push or
+    /// other non-response message), returned as a Ruby `Hash` with keys
+    /// `"id"`, `"type"`, `"method"`, `"payload"`.
+    ///
+    /// The GVL is released while waiting, so other Ruby threads run; the call
+    /// itself is not interruptible and has no timeout (future refinements).
+    fn recv(&self) -> Result<Value, Error> {
+        let msg = without_gvl(|| runtime().block_on(self.inner.recv())).map_err(net_err)?;
+        let payload = msg.payload_as_value().map_err(net_err)?;
+        let out = serde_json::json!({
+            "id": msg.id,
+            "type": msg.msg_type,
+            "method": msg.method,
+            "payload": payload,
+        });
+        serde_magnus::serialize(&ruby(), &out)
+    }
+
+    /// `channel.close` — closes the channel and stops its receive loop.
+    fn close(&self) -> Result<(), Error> {
+        without_gvl(|| runtime().block_on(self.inner.close())).map_err(net_err)
+    }
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("Unison")?;
+    module.define_module_function("protocol_target", function!(protocol_target, 0))?;
+
+    // `Unison::Error` — base class for every failure raised by this binding.
+    module.define_error("Error", ruby.exception_standard_error())?;
+
+    let client = module.define_class("Client", ruby.class_object())?;
+    client.define_singleton_method("new", function!(Client::new, 0))?;
+    client.define_method("connect", method!(Client::connect, 1))?;
+    client.define_method("connected?", method!(Client::connected, 0))?;
+    client.define_method("disconnect", method!(Client::disconnect, 0))?;
+    client.define_method("open_channel", method!(Client::open_channel, 1))?;
+
+    let channel = module.define_class("Channel", ruby.class_object())?;
+    channel.define_method("request", method!(Channel::request, 2))?;
+    channel.define_method("send_event", method!(Channel::send_event, 2))?;
+    channel.define_method("recv", method!(Channel::recv, 0))?;
+    channel.define_method("close", method!(Channel::close, 0))?;
+
+    Ok(())
+}

data/lib/unison/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Unison
+  # Gem version. The gem is in scaffold stage; the Unison protocol generation
+  # it targets is reported by the native extension (`Unison.protocol_target`).
+  VERSION = "0.1.0"
+end

data/lib/unison.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "unison/version"
+
+# Load the Rust native extension (built by `rake compile` into
+# `lib/unison_client/`). It defines the Rust-backed `Unison` module functions.
+require "unison_client/unison_client"
+
+# Unison — a Ruby client for the Unison protocol.
+#
+# This gem is a thin **language binding**, not a re-implementation: the
+# protocol itself (QUIC transport, channel multiplexing, wire framing) lives
+# in the Rust `club-unison` crate. The native extension (Magnus) wraps that
+# crate's `ProtocolClient`.
+#
+# `Unison::Client` wraps the crate's `ProtocolClient` (connection lifecycle:
+# `new` / `connect` / `connected?` / `disconnect` / `open_channel`), and
+# `Unison::Channel` wraps `UnisonChannel` (`request` / `send_event` / `recv` /
+# `close`). Channel payloads are native Ruby values.
+module Unison
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: unison-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mako
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A thin Ruby binding over the Rust `club-unison` crate's ProtocolClient,
+  via a Magnus native extension. The protocol — QUIC transport, channel multiplexing,
+  wire framing — is implemented in Rust; this gem is the language binding.
+email:
+- mito@chronista.club
+executables: []
+extensions:
+- ext/unison_client/extconf.rb
+extra_rdoc_files: []
+files:
+- Cargo.lock
+- Cargo.toml
+- README.md
+- ext/unison_client/Cargo.toml
+- ext/unison_client/extconf.rb
+- ext/unison_client/src/lib.rs
+- lib/unison.rb
+- lib/unison/version.rb
+homepage: https://github.com/chronista-club/club-unison
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the Unison protocol.
+test_files: []