omq 0.24.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed87cc3a3243100b7977fd58f102b87918de8568cf8739642afc6377bb3f76e5
-  data.tar.gz: f01b30844ae48ffe26ec3934fef780521937a7611e1d00c87b333136fa5641ac
+  metadata.gz: 304adcf07ab3967251a821578bb96376b7c080e2a4d0d16430768ba6855b3557
+  data.tar.gz: 26babe478d3f2f07f8d011b2484083bc1c327a9938eaae0ab199bcdc560eaf55
 SHA512:
-  metadata.gz: 853d3171298de868ad3de28fe284c7970ddf196203bbb217fc91fa62cebb9d39c1d278b53d4259d0dc505b09457624ea68f4a9a8a0e654850c9266139a1fa05e
-  data.tar.gz: ad8a2cec518ceebac32055aeab7fd159d982421e9983670ec28182094f4fe2338f89cd7a1609d02cd8720f01c121159fec7e2489b8c816f9f16adf9d950c34c4
+  metadata.gz: 873f2817de7d8fb063da6b425982493012b4eff08b3035cf86fbce948e3398de34ca319713dc4b1f56e4556250a82b23510a304e5f3a503aa01b367c5e6c6379
+  data.tar.gz: 18df1029acefe76806a1e188e077aad0023ec52a5ae63b31aac09fbe450aec68c4c4688b88b8ae77c19669a30f53c418b65f9a728eb377562a5c74da34e1a8fd

data/CHANGELOG.md

@@ -1,5 +1,111 @@
 # Changelog
 
+## 0.27.0 — 2026-04-20
+
+### Added
+
+- **Transport-supplied ZMTP Connection class.** Transport modules may
+  now define `.connection_class` to substitute their own
+  `Protocol::ZMTP::Connection`-shaped class. `ConnectionLifecycle`
+  reads it (with a `respond_to?` fallback to
+  `Protocol::ZMTP::Connection`) so existing transports — built-in or
+  third-party — keep working unchanged. Enables plugin transports
+  whose wire shape differs from ZMTP/3.1 (e.g. ZeroMQ-over-WebSocket
+  per RFC 45) to plug in without forking the engine.
+
+## 0.26.2 — 2026-04-20
+
+### Fixed
+
+- **Ruby 3.3 compatibility.** Replaced bare `it` block references
+  with explicit block parameters in `engine/recv_pump.rb` and
+  `writable.rb`. Ruby 3.3 warned that `it` would change meaning in
+  3.4; the explicit params work on both.
+
+## 0.26.1 — 2026-04-20
+
+### Fixed
+
+- **Inproc Pipe: tolerate non-String parts.** The BINARY-encoding
+  upgrade introduced in 0.25 called `.encoding` on every frame,
+  crashing when plugins (e.g. omq-ractor's `ShareableConnection`)
+  carried arbitrary Ruby objects through inproc. Non-String parts
+  now pass through untouched; String parts still get the
+  frozen-string-literal → BINARY upgrade.
+
+## 0.26.0 — 2026-04-20
+
+### Added
+
+- **FFI backend absorbed in-tree.** The libzmq-backed `OMQ::FFI::Engine`
+  (previously shipped as the separate `omq-ffi` gem) now lives in
+  `lib/omq/ffi/`. Load with `require "omq/ffi"` and select per socket
+  via `OMQ::PUSH.new(backend: :ffi)`. `lib/omq/socket.rb` also
+  lazy-requires `omq/ffi` on first `:ffi` use, so the explicit require
+  is optional.
+- **Auto-running FFI interop tests.** `test/omq/ffi_test.rb` (FFI
+  backend) and `test/omq/interop_test.rb` (FFI ↔ pure Ruby wire
+  compatibility) now run as part of `rake test` whenever the `ffi` gem
+  and system libzmq are both available. They self-skip otherwise —
+  detection runs once in `test/test_helper.rb` as `OMQ_FFI_AVAILABLE`.
+
+### Notes
+
+- `ffi` remains optional and is NOT a runtime dependency of `omq`.
+  Install it explicitly (`gem install ffi` + system libzmq 4.x) to use
+  the `:ffi` backend. The omq-ffi gem is superseded; existing pins to
+  `omq-ffi ~> 0.3` keep working via its own dependency on `omq ~> 0.23`.
+
+## 0.25.0 — 2026-04-20
+
+### Added
+
+- **Recv-pump transforms can drop messages.** A `transform` block passed
+  to `Engine#start_recv_pump` may now return `nil` to discard the
+  message instead of enqueueing it to the application's recv queue.
+  The pump still counts the dropped message toward its per-connection
+  fairness caps (64 msgs / 1 MiB), so a duplicate flood can't starve
+  siblings. omq-qos 0.3.0 uses this at QoS >= 2 for dedup-set hits:
+  the transform ACKs the sender and returns `nil`.
+
+### Changed
+
+- **Uniform frozen + BINARY contract on both sides of the wire —
+  restoring pre-0.24 behavior.** 0.24 dropped freezing from the
+  send/receive paths to chase throughput numbers, which left inproc
+  with an unsafe shared-reference contract (sender and receiver share
+  the same array and strings) and made the contract differ by
+  transport. Safety is back, minus the `.b` copy that was the
+  actually-expensive part of the old path. Invariants:
+
+  - `Writable#send` freezes every part (and the parts array, if one
+    was passed). Unfrozen non-BINARY parts are re-tagged to
+    `Encoding::BINARY` in place — a flag flip, no allocation.
+  - Receivers always get frozen `BINARY`-tagged parts. TCP/IPC get
+    this via byteslice on the wire + recv-pump freeze. Inproc gets
+    it via `Pipe#send_message`, which only allocates (one `.b` copy
+    per part) in the pathological case of a frozen non-BINARY part
+    — the typical `# frozen_string_literal: true` UTF-8 literal.
+
+  Mutation bugs surface as `FrozenError` instead of silently
+  corrupting a shared reference on inproc. Cost on inproc is ~20-30%
+  throughput; TCP/IPC unaffected.
+
+- **String-like part coercion via `#to_str`.** Non-String parts are
+  coerced via `#to_str` (not `#to_s`) — an object must be explicitly
+  string-like to serialize. Passing `42`, `:foo`, or `nil` raises
+  `NoMethodError` instead of silently accepting a `#to_s`
+  representation or producing a zero-byte frame from a `nil`. Use
+  `""` to send an empty frame.
+
+- **Inproc `needs_commands?` accepts nilable `options.qos`.** Core
+  `Options#qos` is still an Integer (default `0`), but omq-qos 0.3
+  stores either `nil` (QoS 0) or an `OMQ::QoS` instance (levels 1–3)
+  in that slot. The inproc transport's command-queue decision now
+  treats both Integer `0` and `nil` as disabled; any non-zero
+  Integer or non-nil object forces the command-queue path.
+
+
 ## 0.24.0 — 2026-04-18
 
 ### Changed
@@ -1044,9 +1150,10 @@ Combined effect of caller-owns-data + Reactor fast path on inproc:
 ### Added
 
 - **`backend:` kwarg** — all socket types accept `backend: :ffi` to use
-  the libzmq FFI backend (via the [omq-ffi](https://github.com/paddor/omq-ffi)
-  gem). Default is `:ruby` (pure Ruby ZMTP). Enables interop testing and
-  access to libzmq-specific features without changing the socket API.
+  the libzmq FFI backend (then shipped separately as the `omq-ffi` gem;
+  absorbed in-tree in 0.26.0). Default is `:ruby` (pure Ruby ZMTP).
+  Enables interop testing and access to libzmq-specific features without
+  changing the socket API.
 - **TLS transport (`tls+tcp://`)** — TLS v1.3 on top of TCP using Ruby's
   stdlib `openssl`. Set `socket.tls_context` to an `OpenSSL::SSL::SSLContext`
   before bind/connect. Per-socket (not per-endpoint), frozen on first use.

data/README.md

@@ -5,9 +5,9 @@
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
 [![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.3-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
 
-> **1.23M msg/s** inproc | **361k msg/s** ipc | **358k msg/s** tcp
+> **1.64M msg/s** inproc | **294k msg/s** ipc | **308k msg/s** tcp
 >
-> **9.1 µs** inproc latency | **49 µs** ipc | **64 µs** tcp
+> **8.7 µs** inproc latency | **51 µs** ipc | **64 µs** tcp
 >
 > Ruby 4.0 + YJIT on a Linux VM — see [`bench/`](bench/) for full results
 
@@ -162,6 +162,12 @@ All sockets are thread-safe. Default HWM is 1000 messages per socket.
 frames cause the connection to be dropped before the body is read from the
 wire. Classes live under `OMQ::` (alias: `ØMQ`).
 
+**Received messages are frozen** across all transports (inproc, ipc, tcp).
+The array returned by `#receive` and every part inside it is frozen —
+mutating a received part raises `FrozenError` rather than silently
+corrupting a shared reference on the inproc fast path. `dup` a part if
+you need to mutate it.
+
 #### Standard (multipart messages)
 
 | Pattern | Send | Receive | When HWM full |
@@ -207,12 +213,23 @@ echo "hello" | omq req -c tcp://localhost:5555
 
 See the [omq-cli README](https://github.com/paddor/omq-cli) for full documentation.
 
+## Optional libzmq backend
+
+OMQ ships with an optional libzmq FFI backend. Same socket API, but
+backed by libzmq instead of the pure Ruby ZMTP stack. Useful when you
+need libzmq-specific features or for verifying wire compatibility.
+
+```ruby
+require "omq/ffi"
+push = OMQ::PUSH.new(backend: :ffi)
+```
+
+Requires the `ffi` gem and a system libzmq 4.x. `ffi` is not a runtime
+dependency of `omq` — install it explicitly (`gem install ffi`) if you
+want the `:ffi` backend.
+
 ## Companion Gems
 
-- **[omq-ffi](https://github.com/paddor/omq-ffi)** — libzmq FFI backend. Same
-  OMQ socket API, but backed by libzmq instead of the pure Ruby ZMTP stack.
-  Useful for interop testing and when you need libzmq-specific features.
-  Requires libzmq installed.
 - **[omq-ractor](https://github.com/paddor/omq-ractor)** — bridge OMQ sockets
   into Ruby Ractors for true parallel processing across cores. I/O stays on the
   main Ractor, worker Ractors do pure computation.
@@ -244,7 +261,6 @@ the stack.
 git clone https://github.com/paddor/omq.git
 git clone https://github.com/paddor/protocol-zmtp.git
 git clone https://github.com/paddor/omq-zstd.git
-git clone https://github.com/paddor/omq-ffi.git
 git clone https://github.com/paddor/omq-ractor.git
 git clone https://github.com/paddor/nuckle.git
 

data/lib/omq/engine/connection_lifecycle.rb

@@ -66,13 +66,19 @@ module OMQ
       # @param engine [Engine]
       # @param endpoint [String, nil]
       # @param done [Async::Promise, nil] resolved when connection is lost
+      # @param transport [Module, nil] transport module that produced +io+;
+      #   queried for {.connection_class} so plugins (e.g. WebSocket) can
+      #   substitute their own ZMTP-shaped connection class. Falls back to
+      #   {Protocol::ZMTP::Connection} when nil or when the transport
+      #   doesn't define +connection_class+.
       #
-      def initialize(engine, endpoint: nil, done: nil)
-        @engine   = engine
-        @endpoint = endpoint
-        @done     = done
-        @state    = :new
-        @conn     = nil
+      def initialize(engine, endpoint: nil, done: nil, transport: nil)
+        @engine    = engine
+        @endpoint  = endpoint
+        @done      = done
+        @transport = transport
+        @state     = :new
+        @conn      = nil
 
         # Nest the per-connection barrier under the socket-level barrier
         # so every pump spawned via +@barrier.async+ is also tracked by
@@ -90,7 +96,8 @@ module OMQ
       #
       def handshake!(io, as_server:)
         transition!(:handshaking)
-        conn = Protocol::ZMTP::Connection.new io,
+        conn_class = @transport.respond_to?(:connection_class) ? @transport.connection_class : Protocol::ZMTP::Connection
+        conn = conn_class.new io,
           socket_type:      @engine.socket_type.to_s,
           identity:         @engine.options.identity,
           as_server:        as_server,

data/lib/omq/engine/recv_pump.rb

@@ -80,6 +80,12 @@ module OMQ
       # cross-Ractor transport). Kept separate from {#start_direct} so
       # YJIT sees a monomorphic transform.call site.
       #
+      # A transform that returns +nil+ drops the message — the recv pump
+      # still counts it toward fairness (so dup-floods can't starve
+      # siblings) but it is neither emitted nor enqueued to the
+      # application. omq-qos uses this at QoS >= 2 for dedup-set hits:
+      # the transform ACKs the sender and returns nil.
+      #
       # @param parent [Async::Task, Async::Barrier]
       # @param transform [Proc]
       # @return [Async::Task]
@@ -94,18 +100,11 @@ module OMQ
 
             while count < FAIRNESS_MESSAGES && bytes < FAIRNESS_BYTES
               msg = conn.receive_message
-              msg = transform.call(msg)
-
-              # Emit the verbose trace BEFORE enqueueing so the monitor
-              # fiber is woken before the application fiber -- the
-              # async scheduler is FIFO on the ready list, so this
-              # preserves log-before-stdout ordering for -vvv traces.
-              engine.emit_verbose_msg_received(conn, msg)
-              recv_queue.enqueue(msg)
-
-              count += 1
+              msg.each { |part| part.freeze }
+              msg.freeze
 
-              # hot path
+              # hot path bytes — count before transform so dropped
+              # messages still contribute to the fairness cap.
               if count_bytes
                 if msg.size == 1
                   bytes += msg.first.bytesize
@@ -117,6 +116,17 @@ module OMQ
                   end
                 end
               end
+
+              count += 1
+              transformed = transform.call(msg)
+              next unless transformed
+
+              # Emit the verbose trace BEFORE enqueueing so the monitor
+              # fiber is woken before the application fiber -- the
+              # async scheduler is FIFO on the ready list, so this
+              # preserves log-before-stdout ordering for -vvv traces.
+              engine.emit_verbose_msg_received(conn, transformed)
+              recv_queue.enqueue(transformed)
             end
 
             task.yield
@@ -147,6 +157,8 @@ module OMQ
 
             while count < FAIRNESS_MESSAGES && bytes < FAIRNESS_BYTES
               msg = conn.receive_message
+              msg.each { |part| part.freeze }
+              msg.freeze
               engine.emit_verbose_msg_received(conn, msg)
               recv_queue.enqueue(msg)
 

data/lib/omq/engine.rb

@@ -635,7 +635,8 @@ module OMQ
     def spawn_connection(io, as_server:, endpoint: nil)
       @lifecycle.barrier&.async(transient: true, annotation: "conn #{endpoint}") do
         done      = Async::Promise.new
-        lifecycle = ConnectionLifecycle.new(self, endpoint: endpoint, done: done)
+        transport = endpoint ? transport_for(endpoint) : nil
+        lifecycle = ConnectionLifecycle.new(self, endpoint: endpoint, done: done, transport: transport)
         lifecycle.handshake!(io, as_server: as_server)
         done.wait
       rescue Async::Stop, Async::Cancel

data/lib/omq/ffi/engine.rb

@@ -0,0 +1,646 @@
+# frozen_string_literal: true
+
+require "async"
+require "uri"
+
+module OMQ
+  module FFI
+    # FFI Engine — wraps a libzmq socket to implement the OMQ Engine contract.
+    #
+    # A dedicated I/O thread owns the zmq_socket exclusively (libzmq sockets
+    # are not thread-safe). Send and recv flow through queues, with an IO pipe
+    # to wake the Async fiber scheduler.
+    #
+    class Engine
+      L = Libzmq
+
+
+      # @return [Options] socket options
+      attr_reader :options
+      # @return [Array] active connections
+      attr_reader :connections
+      # @return [RoutingStub] subscription/group routing interface
+      attr_reader :routing
+      # @return [Async::Promise] resolved when the first peer connects
+      attr_reader :peer_connected
+      # @return [Async::Promise] resolved when all peers have disconnected
+      attr_reader :all_peers_gone
+      # @return [Async::Task, nil] root of the engine's task tree
+      attr_reader :parent_task
+      # @return [Boolean] true when the engine's parent task lives on the
+      #   shared {OMQ::Reactor} IO thread (i.e. not created under an
+      #   Async task). Writable/Readable check this to pick the fast path.
+      attr_reader :on_io_thread
+      alias on_io_thread? on_io_thread
+      # @param value [Boolean] enables or disables automatic reconnection
+      attr_writer :reconnect_enabled
+      # @note Monitor events are not yet emitted by the FFI backend; these
+      #   writers exist so Socket#monitor can attach without raising. Wiring
+      #   libzmq's zmq_socket_monitor is a TODO.
+      attr_writer :monitor_queue, :verbose_monitor
+
+      # Routing stub that delegates subscribe/unsubscribe/join/leave to
+      # libzmq socket options via the I/O thread.
+      #
+      class RoutingStub
+        # @return [Async::Promise] resolved when a subscriber joins
+        attr_reader :subscriber_joined
+
+        # @param engine [Engine] the parent engine instance
+        def initialize(engine)
+          @engine            = engine
+          @subscriber_joined = Async::Promise.new
+        end
+
+
+        # Subscribes to messages matching the given prefix.
+        #
+        # @param prefix [String] subscription prefix
+        # @return [void]
+        def subscribe(prefix)
+          @engine.send_cmd(:subscribe, prefix.b)
+        end
+
+
+        # Removes a subscription for the given prefix.
+        #
+        # @param prefix [String] subscription prefix to remove
+        # @return [void]
+        def unsubscribe(prefix)
+          @engine.send_cmd(:unsubscribe, prefix.b)
+        end
+
+
+        # Joins a DISH group for receiving RADIO messages.
+        #
+        # @param group [String] group name
+        # @return [void]
+        def join(group)
+          @engine.send_cmd(:join, group)
+        end
+
+
+        # Leaves a DISH group.
+        #
+        # @param group [String] group name
+        # @return [void]
+        def leave(group)
+          @engine.send_cmd(:leave, group)
+        end
+      end
+
+
+      # Maps an OMQ +linger+ value (seconds, or +nil+/+Float::INFINITY+
+      # for "wait forever") to libzmq's ZMQ_LINGER int milliseconds
+      # (-1 = infinite, 0 = drop, N = N ms).
+      #
+      # @param linger [Numeric, nil]
+      # @return [Integer]
+      #
+      def self.linger_to_zmq_ms(linger)
+        return -1 if linger.nil? || linger == Float::INFINITY
+        (linger * 1000).to_i
+      end
+
+
+      # @param socket_type [Symbol] e.g. :REQ, :PAIR
+      # @param options [Options]
+      #
+      def initialize(socket_type, options)
+        @socket_type    = socket_type
+        @options        = options
+        @peer_connected = Async::Promise.new
+        @all_peers_gone = Async::Promise.new
+        @connections    = []
+        @closed         = false
+        @parent_task    = nil
+        @on_io_thread   = false
+
+        @zmq_socket = L.zmq_socket(OMQ::FFI.context, L::SOCKET_TYPES.fetch(@socket_type))
+        raise "zmq_socket failed: #{L.zmq_strerror(L.zmq_errno)}" if @zmq_socket.null?
+
+        apply_options
+
+        @routing = RoutingStub.new(self)
+
+        # Queues for cross-thread communication
+        @send_queue = Thread::Queue.new   # main → io thread
+        @recv_queue = Thread::Queue.new   # io thread → main
+        @cmd_queue  = Thread::Queue.new   # control commands → io thread
+
+        # Signal pipe: io thread → Async fiber (message received)
+        @recv_signal_r, @recv_signal_w = IO.pipe
+        # Wake pipe: main thread → io thread (send/cmd enqueued)
+        @wake_r, @wake_w = IO.pipe
+
+        @io_thread = nil
+      end
+
+
+      # --- Socket lifecycle ---
+
+      # Binds the socket to the given endpoint.
+      #
+      # @param endpoint [String] ZMQ endpoint URL (e.g. "tcp://*:5555")
+      # @return [URI::Generic] resolved endpoint URI (with auto-selected port for "tcp://host:0")
+      def bind(endpoint)
+        sync_identity
+        send_cmd(:bind, endpoint)
+        resolved = get_string_option(L::ZMQ_LAST_ENDPOINT)
+        @connections << :ffi
+        @peer_connected.resolve(:ffi) unless @peer_connected.resolved?
+        URI.parse(resolved)
+      end
+
+
+      # Connects the socket to the given endpoint.
+      #
+      # @param endpoint [String] ZMQ endpoint URL
+      # @return [URI::Generic] parsed endpoint URI
+      def connect(endpoint)
+        sync_identity
+        send_cmd(:connect, endpoint)
+        @connections << :ffi
+        @peer_connected.resolve(:ffi) unless @peer_connected.resolved?
+        URI.parse(endpoint)
+      end
+
+
+      # Disconnects from the given endpoint.
+      #
+      # @param endpoint [String] ZMQ endpoint URL
+      # @return [void]
+      def disconnect(endpoint)
+        send_cmd(:disconnect, endpoint)
+      end
+
+
+      # Unbinds from the given endpoint.
+      #
+      # @param endpoint [String] ZMQ endpoint URL
+      # @return [void]
+      def unbind(endpoint)
+        send_cmd(:unbind, endpoint)
+      end
+
+
+      # Subscribes to a topic prefix (SUB/XSUB). Delegates to the routing
+      # stub for API parity with the pure-Ruby Engine.
+      #
+      # @param prefix [String]
+      # @return [void]
+      def subscribe(prefix)
+        @routing.subscribe(prefix)
+      end
+
+
+      # Unsubscribes from a topic prefix (SUB/XSUB).
+      #
+      # @param prefix [String]
+      # @return [void]
+      def unsubscribe(prefix)
+        @routing.unsubscribe(prefix)
+      end
+
+
+      # @return [Async::Promise] resolved when a subscriber joins (PUB/XPUB).
+      def subscriber_joined
+        @routing.subscriber_joined
+      end
+
+
+      # Closes the socket and shuts down the I/O thread.
+      #
+      # Honors `options.linger`:
+      #   nil → wait forever for Ruby-side queue to drain into libzmq
+      #         and for libzmq's own LINGER to flush to the network
+      #   0   → drop anything not yet in libzmq's kernel buffers, close fast
+      #   N   → up to N seconds for drain + N + 1s grace for join
+      #
+      # @return [void]
+      def close
+        return if @closed
+        @closed = true
+        if @io_thread
+          @cmd_queue.push([:stop])
+          wake_io_thread
+          linger = @options.linger
+          if linger.nil?
+            @io_thread.join
+          elsif linger.zero?
+            @io_thread.join(0.5) # fast path: zmq_close is non-blocking with LINGER=0
+          else
+            @io_thread.join(linger + 1.0)
+          end
+          @io_thread.kill if @io_thread.alive? # hard stop if deadline exceeded
+        else
+          # IO thread never started — close socket directly
+          L.zmq_close(@zmq_socket)
+        end
+        @recv_signal_r&.close rescue nil
+        @recv_signal_w&.close rescue nil
+        @wake_r&.close rescue nil
+        @wake_w&.close rescue nil
+      end
+
+
+      # Captures the current Async task as the parent for I/O scheduling.
+      # +parent:+ is accepted for API compatibility with the pure-Ruby
+      # engine but has no effect: the FFI backend runs its own I/O
+      # thread and doesn't participate in the Async barrier tree.
+      #
+      # @return [void]
+      def capture_parent_task(parent: nil)
+        return if @parent_task
+        if parent
+          @parent_task = parent
+        elsif Async::Task.current?
+          @parent_task = Async::Task.current
+        else
+          @parent_task  = Reactor.root_task
+          @on_io_thread = true
+          Reactor.track_linger(@options.linger)
+        end
+      end
+
+
+      # --- Send ---
+
+      # Enqueues a multipart message for sending via the I/O thread.
+      #
+      # @param parts [Array<String>] message frames
+      # @return [void]
+      def enqueue_send(parts)
+        ensure_io_thread
+        @send_queue.push(parts)
+        wake_io_thread
+      end
+
+
+      # --- Recv ---
+
+      # Dequeues the next received message, blocking until one is available.
+      #
+      # @return [Array<String>] multipart message
+      def dequeue_recv
+        ensure_io_thread
+        wait_for_message
+      end
+
+
+      # Pushes a nil sentinel into the recv queue to unblock a waiting consumer.
+      #
+      # @return [void]
+      def dequeue_recv_sentinel
+        @recv_queue.push(nil)
+        @recv_signal_w.write_nonblock(".", exception: false) rescue nil
+      end
+
+
+      # Send a control command to the I/O thread.
+      # @api private
+      #
+      def send_cmd(cmd, *args)
+        ensure_io_thread
+        result = Thread::Queue.new
+        @cmd_queue.push([cmd, args, result])
+        wake_io_thread
+        r = result.pop
+        raise r if r.is_a?(Exception)
+        r
+      end
+
+
+      # Wakes the I/O thread via the internal pipe.
+      #
+      # @return [void]
+      def wake_io_thread
+        @wake_w.write_nonblock(".", exception: false)
+      end
+
+      private
+
+      # Waits for a message from the I/O thread's recv queue.
+      # Uses the signal pipe so Async can yield the fiber.
+      #
+      def wait_for_message
+        loop do
+          begin
+            return @recv_queue.pop(true)
+          rescue ThreadError
+            # empty
+          end
+          @recv_signal_r.wait_readable
+          @recv_signal_r.read_nonblock(256, exception: false)
+        end
+      end
+
+
+      def ensure_io_thread
+        return if @io_thread
+        @io_thread = Thread.new { io_loop }
+      end
+
+
+      # The I/O loop runs on a dedicated thread. It owns the zmq_socket
+      # exclusively and processes commands, sends, and recvs.
+      #
+      def io_loop
+        zmq_fd_io = IO.for_fd(get_zmq_fd, autoclose: false)
+
+        loop do
+          drain_cmds or break
+          drain_sends
+          try_recv
+
+          # Block until ZMQ or wake pipe has activity.
+          IO.select([zmq_fd_io, @wake_r], nil, nil, 0.1)
+          @wake_r.read_nonblock(4096, exception: false)
+        end
+      rescue
+        # Thread exit
+      ensure
+        # Drain Ruby-side send queue into libzmq, bounded by linger deadline.
+        # Then re-apply current linger to libzmq (user may have changed it
+        # after apply_options ran in initialize) and zmq_close uses it to
+        # flush libzmq's own queue to TCP.
+        drain_sends_with_deadline(zmq_fd_io, shutdown_deadline) rescue nil
+        set_int_option(L::ZMQ_LINGER, Engine.linger_to_zmq_ms(@options.linger)) rescue nil
+        zmq_fd_io&.close rescue nil
+        L.zmq_close(@zmq_socket)
+      end
+
+
+      # Returns a monotonic deadline for the Ruby-side drain phase, or nil
+      # for infinite, or the current clock for "drop immediately".
+      #
+      def shutdown_deadline
+        linger = @options.linger
+        return nil if linger.nil?
+        now = Async::Clock.now
+        return now if linger.zero?
+        now + linger
+      end
+
+
+      # Retries drain_sends with IO.select until either the Ruby-side queue
+      # is empty or the deadline is hit. nil deadline = wait forever.
+      #
+      def drain_sends_with_deadline(zmq_fd_io, deadline)
+        loop do
+          drain_sends
+          break if @pending_send.nil? && @send_queue.empty?
+          if deadline
+            remaining = deadline - Async::Clock.now
+            break if remaining <= 0
+            IO.select([zmq_fd_io], nil, nil, [remaining, 0.1].min)
+          else
+            IO.select([zmq_fd_io], nil, nil, 0.1)
+          end
+        end
+      end
+
+
+      def zmq_has_events?
+        @events_buf ||= ::FFI::MemoryPointer.new(:int)
+        @events_len ||= ::FFI::MemoryPointer.new(:size_t).tap { |p| p.write(:size_t, ::FFI.type_size(:int)) }
+        L.zmq_getsockopt(@zmq_socket, L::ZMQ_EVENTS, @events_buf, @events_len)
+        @events_buf.read_int != 0
+      end
+
+
+      def drain_cmds
+        loop do
+          begin
+            cmd = @cmd_queue.pop(true)
+          rescue ThreadError
+            return true  # queue empty, continue
+          end
+          return false unless process_cmd(cmd)
+        end
+      end
+
+
+      def process_cmd(cmd)
+        name, args, result = cmd
+        case name
+        when :stop
+          result&.push(nil)
+          return false
+        when :bind
+          rc = L.zmq_bind(@zmq_socket, args[0])
+          result&.push(rc >= 0 ? nil : syscall_error)
+        when :connect
+          rc = L.zmq_connect(@zmq_socket, args[0])
+          result&.push(rc >= 0 ? nil : syscall_error)
+        when :disconnect
+          rc = L.zmq_disconnect(@zmq_socket, args[0])
+          result&.push(rc >= 0 ? nil : syscall_error)
+        when :unbind
+          rc = L.zmq_unbind(@zmq_socket, args[0])
+          result&.push(rc >= 0 ? nil : syscall_error)
+        when :set_identity
+          set_bytes_option(L::ZMQ_IDENTITY, args[0])
+          result&.push(nil)
+        when :subscribe
+          set_bytes_option(L::ZMQ_SUBSCRIBE, args[0])
+          result&.push(nil)
+        when :unsubscribe
+          set_bytes_option(L::ZMQ_UNSUBSCRIBE, args[0])
+          result&.push(nil)
+        when :join
+          rc = L.respond_to?(:zmq_join) ? L.zmq_join(@zmq_socket, args[0]) : -1
+          result&.push(rc >= 0 ? nil : RuntimeError.new("zmq_join not available"))
+        when :leave
+          rc = L.respond_to?(:zmq_leave) ? L.zmq_leave(@zmq_socket, args[0]) : -1
+          result&.push(rc >= 0 ? nil : RuntimeError.new("zmq_leave not available"))
+        when :drain_send
+          # handled in drain_sends
+          result&.push(nil)
+        end
+        true
+      end
+
+
+      def try_recv
+        loop do
+          parts = recv_multipart_nonblock
+          break unless parts
+          @recv_queue.push(parts.freeze)
+          @recv_signal_w.write_nonblock(".", exception: false)
+        end
+      end
+
+
+      def drain_sends
+        @pending_send ||= nil
+        loop do
+          parts = @pending_send || begin
+            @send_queue.pop(true)
+          rescue ThreadError
+            break
+          end
+          if send_multipart_nonblock(parts)
+            @pending_send = nil
+          else
+            @pending_send = parts  # retry next cycle (HWM reached)
+            break
+          end
+        end
+      end
+
+
+      # Returns true if fully sent, false if would block (HWM).
+      #
+      def send_multipart_nonblock(parts)
+        parts.each_with_index do |part, i|
+          flags = L::ZMQ_DONTWAIT
+          flags |= L::ZMQ_SNDMORE if i < parts.size - 1
+          msg = L.alloc_msg
+          L.zmq_msg_init_size(msg, part.bytesize)
+          L.zmq_msg_data(msg).write_bytes(part)
+          rc = L.zmq_msg_send(msg, @zmq_socket, flags)
+          if rc < 0
+            L.zmq_msg_close(msg)
+            return false  # EAGAIN — would block
+          end
+        end
+        true
+      end
+
+
+      def recv_multipart_nonblock
+        parts = []
+        loop do
+          msg = L.alloc_msg
+          L.zmq_msg_init(msg)
+          rc = L.zmq_msg_recv(msg, @zmq_socket, L::ZMQ_DONTWAIT)
+          if rc < 0
+            L.zmq_msg_close(msg)
+            return parts.empty? ? nil : parts  # EAGAIN = no more data
+          end
+
+          size = L.zmq_msg_size(msg)
+          data = L.zmq_msg_data(msg).read_bytes(size)
+          L.zmq_msg_close(msg)
+          parts << data.freeze
+
+          break unless rcvmore?
+        end
+        parts.empty? ? nil : parts
+      end
+
+
+      def rcvmore?
+        buf = ::FFI::MemoryPointer.new(:int)
+        len = ::FFI::MemoryPointer.new(:size_t)
+        len.write(:size_t, ::FFI.type_size(:int))
+        L.zmq_getsockopt(@zmq_socket, L::ZMQ_RCVMORE, buf, len)
+        buf.read_int != 0
+      end
+
+
+      def get_zmq_fd
+        buf = ::FFI::MemoryPointer.new(:int)
+        len = ::FFI::MemoryPointer.new(:size_t)
+        len.write(:size_t, ::FFI.type_size(:int))
+        L.zmq_getsockopt(@zmq_socket, L::ZMQ_FD, buf, len)
+        buf.read_int
+      end
+
+
+      # Re-syncs identity to libzmq (user may set it after construction).
+      #
+      def sync_identity
+        id = @options.identity
+        if id && !id.empty?
+          send_cmd(:set_identity, id)
+        end
+      end
+
+
+      def apply_options
+        set_int_option(L::ZMQ_SNDHWM, @options.send_hwm)
+        set_int_option(L::ZMQ_RCVHWM, @options.recv_hwm)
+        set_int_option(L::ZMQ_LINGER, Engine.linger_to_zmq_ms(@options.linger))
+        set_int_option(L::ZMQ_CONFLATE, @options.conflate ? 1 : 0)
+
+        if @options.identity && !@options.identity.empty?
+          set_bytes_option(L::ZMQ_IDENTITY, @options.identity)
+        end
+
+        if @options.max_message_size
+          set_int64_option(L::ZMQ_MAXMSGSIZE, @options.max_message_size)
+        end
+
+        if @options.reconnect_interval
+          ivl = @options.reconnect_interval
+          if ivl.is_a?(Range)
+            set_int_option(L::ZMQ_RECONNECT_IVL, (ivl.begin * 1000).to_i)
+            set_int_option(L::ZMQ_RECONNECT_IVL_MAX, (ivl.end * 1000).to_i)
+          else
+            set_int_option(L::ZMQ_RECONNECT_IVL, (ivl * 1000).to_i)
+          end
+        end
+
+        set_int_option(L::ZMQ_ROUTER_MANDATORY, 1) if @options.router_mandatory
+      end
+
+
+      def set_int_option(opt, value)
+        buf = ::FFI::MemoryPointer.new(:int)
+        buf.write_int(value)
+        L.zmq_setsockopt(@zmq_socket, opt, buf, ::FFI.type_size(:int))
+      end
+
+
+      def set_int64_option(opt, value)
+        buf = ::FFI::MemoryPointer.new(:int64)
+        buf.write_int64(value)
+        L.zmq_setsockopt(@zmq_socket, opt, buf, ::FFI.type_size(:int64))
+      end
+
+
+      def set_bytes_option(opt, value)
+        buf = ::FFI::MemoryPointer.from_string(value)
+        L.zmq_setsockopt(@zmq_socket, opt, buf, value.bytesize)
+      end
+
+
+      def get_string_option(opt)
+        buf = ::FFI::MemoryPointer.new(:char, 256)
+        len = ::FFI::MemoryPointer.new(:size_t)
+        len.write(:size_t, 256)
+        L.check!(L.zmq_getsockopt(@zmq_socket, opt, buf, len), "zmq_getsockopt")
+        buf.read_string(len.read(:size_t) - 1)
+      end
+
+
+      # Builds an Errno::XXX exception from the current zmq_errno so callers
+      # can rescue the same classes they would from the pure-Ruby backend
+      # (e.g. `Errno::EADDRINUSE`, `Errno::ECONNREFUSED`). Falls back to a
+      # plain SystemCallError when the errno is libzmq-specific.
+      #
+      def syscall_error
+        errno = L.zmq_errno
+        SystemCallError.new(L.zmq_strerror(errno), errno)
+      end
+
+
+    end
+
+
+    # Returns the shared ZMQ context (one per process, lazily initialized).
+    #
+    # @return [FFI::Pointer] zmq context pointer
+    def self.context
+      @context ||= Libzmq.zmq_ctx_new.tap do |ctx|
+        raise "zmq_ctx_new failed" if ctx.null?
+        at_exit do
+          Libzmq.zmq_ctx_shutdown(ctx) rescue nil
+          Libzmq.zmq_ctx_term(ctx) rescue nil
+        end
+      end
+    end
+  end
+end

data/lib/omq/ffi/libzmq.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module OMQ
+  module FFI
+    # Minimal libzmq FFI bindings — only what OMQ needs.
+    #
+    module Libzmq
+      extend ::FFI::Library
+      ffi_lib ["libzmq.so.5", "libzmq.5.dylib", "libzmq"]
+
+      # Context
+      attach_function :zmq_ctx_new,  [], :pointer
+      attach_function :zmq_ctx_term,     [:pointer], :int
+      attach_function :zmq_ctx_shutdown, [:pointer], :int
+
+      # Socket
+      attach_function :zmq_socket,     [:pointer, :int], :pointer
+      attach_function :zmq_close,      [:pointer], :int
+      attach_function :zmq_bind,       [:pointer, :string], :int
+      attach_function :zmq_connect,    [:pointer, :string], :int
+      attach_function :zmq_disconnect, [:pointer, :string], :int
+      attach_function :zmq_unbind,     [:pointer, :string], :int
+
+      # Message
+      attach_function :zmq_msg_init,      [:pointer], :int
+      attach_function :zmq_msg_init_size, [:pointer, :size_t], :int
+      attach_function :zmq_msg_data,      [:pointer], :pointer
+      attach_function :zmq_msg_size,      [:pointer], :size_t
+      attach_function :zmq_msg_close,     [:pointer], :int
+      attach_function :zmq_msg_send,      [:pointer, :pointer, :int], :int
+      attach_function :zmq_msg_recv,      [:pointer, :pointer, :int], :int
+
+      # Socket options
+      attach_function :zmq_setsockopt, [:pointer, :int, :pointer, :size_t], :int
+      attach_function :zmq_getsockopt, [:pointer, :int, :pointer, :pointer], :int
+
+      # Group membership (RADIO/DISH) — draft API, may not be available
+      begin
+        attach_function :zmq_join,  [:pointer, :string], :int
+        attach_function :zmq_leave, [:pointer, :string], :int
+      rescue ::FFI::NotFoundError
+        # libzmq built without ZMQ_BUILD_DRAFT_API
+      end
+
+
+      # Error
+      attach_function :zmq_errno,    [], :int
+      attach_function :zmq_strerror, [:int], :string
+
+      # Socket types
+      ZMQ_PAIR    = 0
+      ZMQ_PUB     = 1
+      ZMQ_SUB     = 2
+      ZMQ_REQ     = 3
+      ZMQ_REP     = 4
+      ZMQ_DEALER  = 5
+      ZMQ_ROUTER  = 6
+      ZMQ_PULL    = 7
+      ZMQ_PUSH    = 8
+      ZMQ_XPUB    = 9
+      ZMQ_XSUB    = 10
+      ZMQ_SERVER  = 12
+      ZMQ_CLIENT  = 13
+      ZMQ_RADIO   = 14
+      ZMQ_DISH    = 15
+      ZMQ_GATHER  = 16
+      ZMQ_SCATTER = 17
+      ZMQ_PEER    = 19
+      ZMQ_CHANNEL = 20
+
+
+      # Socket type name → constant
+      SOCKET_TYPES = {
+        PAIR: ZMQ_PAIR, PUB: ZMQ_PUB, SUB: ZMQ_SUB,
+        REQ: ZMQ_REQ, REP: ZMQ_REP,
+        DEALER: ZMQ_DEALER, ROUTER: ZMQ_ROUTER,
+        PULL: ZMQ_PULL, PUSH: ZMQ_PUSH,
+        XPUB: ZMQ_XPUB, XSUB: ZMQ_XSUB,
+        SERVER: ZMQ_SERVER, CLIENT: ZMQ_CLIENT,
+        RADIO: ZMQ_RADIO, DISH: ZMQ_DISH,
+        GATHER: ZMQ_GATHER, SCATTER: ZMQ_SCATTER,
+        PEER: ZMQ_PEER, CHANNEL: ZMQ_CHANNEL,
+      }.freeze
+
+      # Send/recv flags
+      ZMQ_DONTWAIT = 1
+      ZMQ_SNDMORE  = 2
+
+
+      # Socket options
+      ZMQ_IDENTITY     = 5
+      ZMQ_SUBSCRIBE    = 6
+      ZMQ_UNSUBSCRIBE  = 7
+      ZMQ_RCVMORE      = 13
+      ZMQ_FD           = 14
+      ZMQ_EVENTS       = 15
+      ZMQ_LINGER       = 17
+      ZMQ_SNDHWM       = 23
+      ZMQ_RCVHWM       = 24
+      ZMQ_RCVTIMEO     = 27
+      ZMQ_SNDTIMEO     = 28
+      ZMQ_MAXMSGSIZE   = 22
+      ZMQ_LAST_ENDPOINT = 32
+      ZMQ_ROUTER_MANDATORY = 33
+      ZMQ_RECONNECT_IVL     = 18
+      ZMQ_RECONNECT_IVL_MAX = 21
+      ZMQ_CONFLATE     = 54
+
+
+      # zmq_msg_t is 64 bytes on all platforms
+      MSG_T_SIZE = 64
+
+
+      # Allocates a zmq_msg_t on the heap.
+      #
+      # @return [FFI::MemoryPointer]
+      #
+      def self.alloc_msg
+        ::FFI::MemoryPointer.new(MSG_T_SIZE)
+      end
+
+
+      # Raises an error with the current zmq_errno message.
+      #
+      def self.check!(rc, label = "zmq")
+        return rc if rc >= 0
+        errno = zmq_errno
+        raise "#{label}: #{zmq_strerror(errno)} (errno #{errno})"
+      end
+    end
+  end
+end

data/lib/omq/ffi.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Load the FFI backend for OMQ.
+#
+# Usage:
+#   require "omq/ffi"
+#   push = OMQ::PUSH.new(backend: :ffi)
+#
+# Raises LoadError if libzmq is not installed.
+
+require_relative "ffi/libzmq"
+require_relative "ffi/engine"

data/lib/omq/socket.rb

@@ -36,7 +36,7 @@ module OMQ
 
 
     # @return [Engine] the socket's engine. Exposed for peer tooling
-    #   (omq-cli, omq-ffi, omq-ractor) that needs to reach into the
+    #   (omq-cli, omq-ractor) that needs to reach into the
     #   socket's internals — not part of the stable user API.
     #
     attr_reader :engine
@@ -318,6 +318,7 @@ module OMQ
       when nil, :ruby
         Engine.new(socket_type, @options)
       when :ffi
+        require "omq/ffi" unless defined?(FFI::Engine)
         FFI::Engine.new(socket_type, @options)
       else
         raise ArgumentError, "unknown backend: #{backend}"

data/lib/omq/transport/inproc/pipe.rb

@@ -101,6 +101,19 @@ module OMQ
         def send_message(parts)
           raise IOError, "closed" if @closed
 
+          # Writable#send guarantees frozen parts, but a frozen non-BINARY
+          # part (e.g. a `# frozen_string_literal: true` literal) can't be
+          # re-tagged in place. Inproc receivers see the parts directly, so
+          # upgrade that one case to fresh BINARY copies to keep the
+          # receive contract uniform with TCP/IPC.
+          #
+          # Non-String parts pass through untouched — plugins like
+          # omq-ractor's ShareableConnection carry arbitrary Ruby objects
+          # over inproc.
+          if parts.any? { |p| p.is_a?(String) && p.encoding != Encoding::BINARY }
+            parts = parts.map { |p| !p.is_a?(String) || p.encoding == Encoding::BINARY ? p : p.b.freeze }.freeze
+          end
+
           if @direct_recv_queue
             @direct_recv_queue.enqueue(apply_transform(parts))
           elsif @send_queue

data/lib/omq/transport/inproc.rb

@@ -11,8 +11,8 @@ module OMQ
     # Both peers are Ruby backend sockets in the same process (native
     # ZMQ's inproc registry is separate and unreachable). Messages are
     # transferred as Ruby arrays — no ZMTP framing, no byte
-    # serialization. String parts are frozen by Writable#send to
-    # prevent shared mutable state without copying.
+    # serialization. Parts are already frozen by Writable#send, so the
+    # receiver sees the same immutable contract as ZMTP transports.
     #
     module Inproc
       Engine.transports["inproc"] = self
@@ -132,11 +132,23 @@ module OMQ
         #
         def needs_commands?(ce, se, ct, st)
           return true if COMMAND_TYPES.include?(ct) || COMMAND_TYPES.include?(st)
-          return true if ce.options.qos >= 1 || se.options.qos >= 1
+          return true if qos_enabled?(ce.options) || qos_enabled?(se.options)
           false
         end
 
 
+        # QoS integration: core +Options#qos+ defaults to Integer +0+.
+        # When the omq-qos extension is loaded, +#qos+ holds either
+        # +nil+ (QoS 0) or an +OMQ::QoS+ instance (levels 1–3). Treat
+        # both Integer 0 and nil as disabled.
+        def qos_enabled?(options)
+          q = options.qos
+          return false if q.nil?
+          return q != 0 if q.is_a?(Integer)
+          true
+        end
+
+
         # Builds a bidirectional {Pipe} pair for client + server.
         # When +needs_cmds+ is false the pipes have no command queues
         # (fast path — all traffic bypasses Async::Queue entirely).

data/lib/omq/transport/ipc.rb

@@ -15,6 +15,15 @@ module OMQ
 
 
       class << self
+        # ZMTP connection class used for IPC-accepted/dialed peers.
+        #
+        # @return [Class]
+        #
+        def connection_class
+          Protocol::ZMTP::Connection
+        end
+
+
         # Creates a bound IPC listener.
         #
         # @param endpoint [String] e.g. "ipc:///tmp/my.sock" or "ipc://@abstract"

data/lib/omq/transport/tcp.rb

@@ -13,6 +13,15 @@ module OMQ
 
 
       class << self
+        # ZMTP connection class used for TCP-accepted/dialed peers.
+        #
+        # @return [Class]
+        #
+        def connection_class
+          Protocol::ZMTP::Connection
+        end
+
+
         # Creates a bound TCP listener.
         #
         # @param endpoint [String] e.g. "tcp://127.0.0.1:5555" or "tcp://*:0"

data/lib/omq/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OMQ
-  VERSION = "0.24.0"
+  VERSION = "0.27.0"
 end

data/lib/omq/writable.rb

@@ -11,18 +11,38 @@ module OMQ
 
     # Sends a message.
     #
-    # Caller owns the message parts. Don't mutate them after sending — especially
-    # with inproc transport or PUB fan-out, where a single reference can be shared
-    # across peers and read later by the send pump.
+    # Parts must be String-like (respond to `#to_str`). Use an empty
+    # string to send an empty frame — `nil` raises `NoMethodError` so
+    # accidental nils surface instead of silently producing a zero-byte
+    # frame. Invariants after `#send` returns:
     #
-    # @param message [String, Array<String>] message parts
+    # * every part is a frozen String
+    # * unfrozen String parts are re-tagged to `Encoding::BINARY` in
+    #   place (a flag flip, no copy)
+    # * the parts array (if the caller passed one) is frozen
+    #
+    # The receiver always gets frozen `BINARY`-tagged parts — on TCP/IPC
+    # via byteslice on the wire, on inproc via {Pipe#send_message} which
+    # duplicates the one pathological case (frozen non-BINARY parts) so
+    # the receiver sees BINARY like every other transport.
+    #
+    # @param message [String, #to_str, Array<String, #to_str>]
     # @return [self]
     # @raise [IO::TimeoutError] if write_timeout exceeded
+    # @raise [NoMethodError] if a part is not String-like
     #
     def send(message)
       parts = message.is_a?(Array) ? message : [message]
       raise ArgumentError, "message has no parts" if parts.empty?
 
+      parts = parts.map { |p| p.to_str } if parts.any? { |p| !p.is_a?(String) }
+
+      parts.each do |part|
+        part.force_encoding(Encoding::BINARY) unless part.frozen? || part.encoding == Encoding::BINARY
+        part.freeze
+      end
+      parts.freeze
+
       if @engine.on_io_thread?
         Reactor.run(timeout: @options.write_timeout) { @engine.enqueue_send(parts) }
       elsif (timeout = @options.write_timeout)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omq
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Patrik Wenger
@@ -76,6 +76,9 @@ files:
 - lib/omq/engine/reconnect.rb
 - lib/omq/engine/recv_pump.rb
 - lib/omq/engine/socket_lifecycle.rb
+- lib/omq/ffi.rb
+- lib/omq/ffi/engine.rb
+- lib/omq/ffi/libzmq.rb
 - lib/omq/options.rb
 - lib/omq/pair.rb
 - lib/omq/peer.rb