omq 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a81ea3e22e2133f508016129454fca72393068b259400e3d47aaf92d0948136
-  data.tar.gz: 71839df55e8ae9edb9db9710b77c5449853cde909c60867958a46e8350f27ead
+  metadata.gz: d5ea3ce51d24a9181cfe7a4c1f2680ed57c5dbba078010a54de5b1c13d27d484
+  data.tar.gz: 97f7e7fcb27a250e71af4732ff06298e7311af052a9d9a6b3868d73059373174
 SHA512:
-  metadata.gz: 9e9d603fb6f44b53626e37d88da5dea1297f932bfbc7b3af0b32e5ab4ebdc6c2151f4b7482bca70d5060d31ffc49ba3c771603b6ed1b4dd17ed51733339de67d
-  data.tar.gz: b40525791795b8e040a4a275a628c1cdca42eab43fcabfab76407de97f669ff9c1b21d05490509c0e0f5cd0b53505c7f85281343b2c312bdb89fd3eee7d4af75
+  metadata.gz: 9f60b7d45d1b3783b2bde482a6f826ec3b89bfff6a9532836dbd2a8a22622709e7c298cc7c2abae6e596641973636b8972efa92de7258bd1e4164ff62d782237
+  data.tar.gz: 7024b97bb46c9005b73bc7959cc4138bd5498a514af26253441613aa05206d357d1fbd002afff5820c9a3baff0c4351d66bcf1aa738955783272a2c2b459a697

data/CHANGELOG.md

@@ -2,6 +2,163 @@
 
 ## Unreleased
 
+### Added
+
+- **QoS infrastructure** — `Options#qos` attribute (default 0) and inproc
+  command queue support for QoS-enabled connections. The
+  [omq-qos](https://github.com/paddor/omq-qos) gem activates delivery
+  guarantees via prepends.
+- **REQ send/recv ordering** — REQ sockets now enforce strict
+  send/recv/send/recv alternation. Calling `#send` twice without a
+  `#receive` in between raises `SocketError`.
+- **DirectPipe command frame support** — `DirectPipe#receive_message`
+  accepts a block for command frames, matching the `Protocol::ZMTP::Connection`
+  interface. Enables inproc transports to handle ACK/NACK and other
+  command-level protocols.
+
+### Fixed
+
+- **`send_pump_idle?` visibility** — moved above `private` in `RoundRobin`
+  and `FanOut` so `Engine#drain_send_queues` can call it during socket close.
+
+- **`Socket#monitor`** — observe connection lifecycle events via a
+  block-based API. Returns an `Async::Task` that yields `MonitorEvent`
+  (Data.define) instances for `:listening`, `:accepted`, `:connected`,
+  `:connect_delayed`, `:connect_retried`, `:handshake_succeeded`,
+  `:handshake_failed`, `:accept_failed`, `:bind_failed`, `:disconnected`,
+  `:closed`, and `:monitor_stopped`. Event types align with libzmq's
+  `zmq_socket_monitor` where applicable. Pattern-matchable, zero overhead
+  when no monitor is attached.
+- **Pluggable transport registry** — `Engine.transports` is a scheme →
+  module hash. Built-in transports (`tcp`, `ipc`, `inproc`) are registered
+  at load time. External gems register via
+  `OMQ::Engine.transports["scheme"] = MyTransport`. Each transport
+  implements `.bind(endpoint, engine)` → Listener, `.connect(endpoint,
+  engine)`, and optionally `.validate_endpoint!(endpoint)`. Listeners
+  implement `#start_accept_loops(parent_task, &on_accepted)`, `#stop`,
+  `#endpoint`, and optionally `#port`.
+- **Mutable error lists** — `CONNECTION_LOST` and `CONNECTION_FAILED` are
+  no longer frozen at load time. Transport plugins can append error classes
+  (e.g. `OpenSSL::SSL::SSLError`) before the first `#bind`/`#connect`,
+  which freezes both arrays.
+
+- **`on_mute` option** — controls behavior when a socket enters the mute state
+  (HWM full). PUB, XPUB, and RADIO default to `on_mute: :drop_newest` — slow
+  subscribers are skipped in the fan-out rather than blocking the publisher.
+  SUB, XSUB, and DISH accept `on_mute: :drop_newest` or `:drop_oldest` to
+  drop messages on the receive side instead of applying backpressure. All other
+  socket types default to `:block` (existing behavior).
+- **`DropQueue`** — bounded queue with `:drop_newest` (tail drop) and
+  `:drop_oldest` (head drop) strategies. Used by recv queues when `on_mute`
+  is a drop strategy.
+- **`Routing.build_queue`** — factory method for building send/recv queues
+  based on HWM and mute strategy. Supports HWM of `0` or `nil` for unbounded
+  queues.
+
+### Changed
+
+- **`max_message_size` defaults to 1 MiB** — frames exceeding this limit cause
+  the connection to be dropped before the body is read from the wire, preventing
+  a malicious peer from causing arbitrary memory allocation. Set `socket.max_message_size = nil`
+  to restore the previous unlimited behavior.
+- **Accept loops moved into Listeners** — `TCP::Listener` and
+  `IPC::Listener` now own their accept loop logic via
+  `#start_accept_loops(parent_task, &on_accepted)`. Engine delegates
+  via duck-type check. This enables external transports to define
+  custom accept behavior without modifying Engine.
+- `Engine#transport_for` uses registry lookup instead of `case/when`.
+- `Engine#validate_endpoint!` delegates to transport module.
+- `Engine#bind` reads `listener.port` instead of parsing the endpoint
+  string.
+
+### Removed
+
+- **Draft socket types extracted** — `RADIO`, `DISH`, `CLIENT`, `SERVER`,
+  `SCATTER`, `GATHER`, `CHANNEL`, and `PEER` are no longer bundled with `omq`.
+  Use the [omq-draft](https://github.com/paddor/omq-draft) gem and require
+  the relevant entry point (`omq/draft/radiodish`, `omq/draft/clientserver`,
+  etc.).
+- **UDP transport extracted** — `udp://` endpoints are provided by
+  `omq-draft` (via `require "omq/draft/radiodish"`). No longer registered by
+  default.
+- **`Routing.for` plugin registry** — draft socket type removal added
+  `Routing.register(socket_type, strategy_class)` for external gems to
+  register routing strategies. Unknown types fall through the built-in
+  `case` to this registry before raising `ArgumentError`.
+
+- **TLS transport** — extracted to the
+  [omq-transport-tls](https://github.com/paddor/omq-transport-tls) gem.
+  (Experimental) `require "omq/transport/tls"` to restore `tls+tcp://` support.
+- `tls_context` / `tls_context=` removed from `Options` and `Socket`
+  (provided by omq-transport-tls).
+- `OpenSSL::SSL::SSLError` removed from `CONNECTION_LOST` (added back
+  by omq-transport-tls).
+- TLS benchmark transport removed from `bench_helper.rb` and `plot.rb`.
+
+## 0.11.0
+
+### 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.
+- **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.
+  SNI set automatically from the endpoint hostname. Bad TLS handshakes are
+  dropped without killing the accept loop. `OpenSSL::SSL::SSLError` added
+  to `CONNECTION_LOST` for automatic reconnection on TLS failures.
+  Accompanied by a draft RFC (`rfc/zmtp-tls.md`) defining the transport
+  mapping for ZMTP 3.1 over TLS.
+- **PUB/RADIO fan-out pre-encoding** — ZMTP frames are encoded once per
+  message and written as raw wire bytes to all non-CURVE subscribers.
+  Eliminates redundant `Frame.new` + `#to_wire` calls during fan-out.
+  CURVE connections (which encrypt at the ZMTP level) still encode
+  per-connection. TLS, NULL, and PLAIN all benefit since TLS encrypts
+  below ZMTP. Requires protocol-zmtp `Frame.encode_message` and
+  `Connection#write_wire`.
+- **CURVE benchmarks** — all per-pattern benchmarks now include CURVE
+  (via rbnacl) alongside inproc, ipc, tcp, and tls transports.
+- **Engine `connection_wrapper` hook** — optional proc on Engine that wraps
+  new connections (both inproc and tcp/ipc) at creation time. Used by the
+  omq-ractor gem for per-connection serialization (Marshal for tcp/ipc,
+  `Ractor.make_shareable` for inproc).
+- **Queue-style interface** — readable sockets gain `#dequeue(timeout:)`,
+  `#pop`, `#wait`, and `#each`; writable sockets gain `#enqueue` and
+  `#push`. Inspired by `Async::Queue`. `#wait` blocks indefinitely
+  (ignores `read_timeout`); `#each` returns gracefully on timeout.
+- **Recv pump fairness** — each connection yields to the fiber scheduler
+  after 64 messages or 1 MB (whichever comes first). Prevents a fast or
+  large-message connection from starving slower peers when the consumer
+  keeps up. Byte counting gracefully handles non-string messages (e.g.
+  deserialized objects from connection wrappers).
+- **Per-pattern benchmark suite** — `bench/{push_pull,req_rep,router_dealer,dealer_dealer,pub_sub,pair}/omq.rb`
+  with shared helpers (`bench_helper.rb`) and UnicodePlot braille line
+  charts (`plot.rb`). Each benchmark measures throughput (msg/s) and
+  bandwidth (MB/s) across transports (inproc, ipc, tcp, tls, curve),
+  message sizes (64 B–64 KB), and peer counts (1, 3). Plots are written to per-directory
+  `README.md` files for easy diffing across versions.
+
+### Changed
+
+- **SUB/XSUB `prefix:` kwarg renamed to `subscribe:`** — aligns with
+  ZeroMQ conventions. `subscribe: nil` (no subscription) remains the
+  default; pass `subscribe: ''` to subscribe to everything, or
+  `subscribe: 'topic.'` for a prefix filter.
+- **Scenario benchmarks moved to `bench/scenarios/`** — broker,
+  draft_types, flush_batching, hwm_backpressure, large_messages,
+  multiframe, pubsub_fanout, ractors_vs_async, ractors_vs_fork,
+  reconnect_storm, and reqrep_throughput moved from `bench/` top level.
+
+### Removed
+
+- **Old flat benchmarks** — `bench/throughput.rb`, `bench/latency.rb`,
+  `bench/pipeline_mbps.rb`, `bench/run_all.sh` replaced by per-pattern
+  benchmarks.
+- **`bench/cli/`** — CLI-specific benchmarks (fib pipeline, latency,
+  throughput shell scripts) moved to the omq-cli repository.
+
 ## 0.10.0 — 2026-04-01
 
 ### Added

data/README.md

@@ -9,9 +9,9 @@
 
 OMQ builds ZeroMQ socket patterns on top of [protocol-zmtp](https://github.com/paddor/protocol-zmtp) (a pure Ruby [ZMTP 3.1](https://rfc.zeromq.org/spec/23/) codec) using [Async](https://github.com/socketry/async) fibers. It speaks native ZeroMQ on the wire and interoperates with libzmq, pyzmq, CZMQ, and everything else in the ZMQ ecosystem.
 
-> **234k msg/s** inproc | **49k msg/s** ipc | **36k msg/s** tcp
+> **980k msg/s** inproc | **38k msg/s** ipc | **31k msg/s** tcp
 >
-> **12 µs** inproc latency | **51 µs** ipc | **62 µs** tcp
+> **10 µs** inproc latency | **71 µs** ipc | **82 µs** tcp
 >
 > Ruby 4.0 + YJIT on a Linux VM — see [`bench/`](bench/) for full results
 
@@ -30,7 +30,7 @@ See [GETTING_STARTED.md](GETTING_STARTED.md) for a ~30 min walkthrough of all ma
 ## Highlights
 
 - **Zero dependencies on C** — no extensions, no FFI, no libzmq. `gem install` just works everywhere
-- **Fast** — YJIT-optimized hot paths, batched sends, 234k msg/s inproc with 12 µs latency
+- **Fast** — YJIT-optimized hot paths, batched sends, recv prefetching, direct-pipe inproc bypass. 980k msg/s inproc, 10 µs latency
 - **[`omq` CLI](https://github.com/paddor/omq-cli)** — `gem install omq-cli` for a command-line tool with Ruby eval, Ractor parallelism, and script handlers
 - **Every socket pattern** — req/rep, pub/sub, push/pull, dealer/router, xpub/xsub, pair, and all draft types
 - **Every transport** — tcp, ipc (Unix domain sockets), inproc (in-process queues)
@@ -125,9 +125,29 @@ pull.close
 
 The IO thread runs all pumps, reconnection, and heartbeating in the background. When you're inside an `Async` block, OMQ uses the existing reactor instead.
 
+### Queue Interface
+
+All sockets expose an `Async::Queue`-inspired interface:
+
+| Async::Queue | OMQ Socket | Notes |
+|---|---|---|
+| `enqueue(item)` / `push(item)` | `enqueue(msg)` / `push(msg)` | Also: `send(msg)`, `<< msg` |
+| `dequeue(timeout:)` / `pop(timeout:)` | `dequeue(timeout:)` / `pop(timeout:)` | Defaults to socket's `read_timeout` |
+| `wait` | `wait` | Blocks indefinitely (ignores `read_timeout`) |
+| `each` | `each` | Yields messages; returns on close or timeout |
+
+```ruby
+pull = OMQ::PULL.bind('inproc://work')
+
+# iterate messages like a queue
+pull.each do |msg|
+  puts msg.first
+end
+```
+
 ## Socket Types
 
-All sockets are thread-safe. Default HWM is 1000 messages per socket. Classes live under `OMQ::` (alias: `ØMQ`).
+All sockets are thread-safe. Default HWM is 1000 messages per socket. Default `max_message_size` is **1 MiB** — frames larger than this cause the connection to be dropped before the body is read from the wire. Set `socket.max_message_size = nil` to disable the limit or raise it as needed. Classes live under `OMQ::` (alias: `ØMQ`).
 
 #### Standard (multipart messages)
 
@@ -142,6 +162,8 @@ All sockets are thread-safe. Default HWM is 1000 messages per socket. Classes li
 
 #### Draft (single-frame only)
 
+These require the `omq-draft` gem.
+
 | Pattern | Send | Receive | When HWM full |
 |---------|------|---------|---------------|
 | **CLIENT** / **SERVER** | Round-robin / routing-ID | Fair-queue | Block |
@@ -163,6 +185,11 @@ echo "hello" | omq req -c tcp://localhost:5555
 
 See the [omq-cli README](https://github.com/paddor/omq-cli) for full documentation.
 
+## 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.
+
 ## Development
 
 ```sh

data/lib/omq/drop_queue.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module OMQ
+  # A bounded queue that drops messages when full instead of blocking.
+  #
+  # Two drop strategies:
+  #   :drop_newest — discard the incoming message (tail drop)
+  #   :drop_oldest — discard the head, then enqueue the new message
+  #
+  # Used by SUB/XSUB/DISH recv queues when on_mute is a drop strategy.
+  #
+  class DropQueue
+    # @param limit [Integer] maximum number of items
+    # @param strategy [Symbol] :drop_newest or :drop_oldest
+    #
+    def initialize(limit, strategy: :drop_newest)
+      @queue    = Thread::SizedQueue.new(limit)
+      @strategy = strategy
+    end
+
+    # Enqueues an item. Drops according to the configured strategy if full.
+    #
+    # @param item [Object]
+    # @return [void]
+    #
+    def enqueue(item)
+      @queue.push(item, true)
+    rescue ThreadError
+      return if @strategy == :drop_newest
+
+      # :drop_oldest — discard head, enqueue new
+      @queue.pop(true) rescue nil
+      retry
+    end
+
+    # Removes and returns the next item, blocking if empty.
+    #
+    # @return [Object]
+    #
+    def dequeue(timeout: nil)
+      if timeout
+        @queue.pop(timeout: timeout)
+      else
+        @queue.pop
+      end
+    end
+
+    # @return [Boolean]
+    #
+    def empty?
+      @queue.empty?
+    end
+  end
+end

data/lib/omq/engine.rb

@@ -9,6 +9,17 @@ module OMQ
   # OMQ::Socket instance. Each socket type creates one Engine.
   #
   class Engine
+    # Scheme → transport module registry.
+    # Plugins add entries via +Engine.transports["scheme"] = MyTransport+.
+    #
+    @transports = {}
+
+    class << self
+      # @return [Hash{String => Module}] registered transports
+      attr_reader :transports
+    end
+
+
     # @return [Symbol] socket type (e.g. :REQ, :PAIR)
     #
     attr_reader :socket_type
@@ -57,12 +68,18 @@ module OMQ
       @on_io_thread         = false
       @connection_promises  = {} # connection => Async::Promise
       @fatal_error          = nil
+      @monitor_queue        = nil
     end
 
 
     attr_reader :peer_connected, :all_peers_gone, :connections, :parent_task
 
-    attr_writer :reconnect_enabled
+    attr_writer :reconnect_enabled, :monitor_queue
+
+    # Optional proc that wraps new connections (e.g. for serialization).
+    # Called with the raw connection; must return the (possibly wrapped) connection.
+    #
+    attr_accessor :connection_wrapper
 
 
     # Spawns an inproc reconnect retry task under @parent_task.
@@ -87,12 +104,17 @@ module OMQ
     # @raise [ArgumentError] on unsupported transport
     #
     def bind(endpoint)
+      freeze_error_lists!
       transport = transport_for(endpoint)
       listener  = transport.bind(endpoint, self)
       start_accept_loops(listener)
       @listeners << listener
       @last_endpoint = listener.endpoint
-      @last_tcp_port = extract_tcp_port(listener.endpoint)
+      @last_tcp_port = listener.respond_to?(:port) ? listener.port : nil
+      emit_monitor_event(:listening, endpoint: listener.endpoint)
+    rescue => error
+      emit_monitor_event(:bind_failed, endpoint: endpoint, detail: { error: error })
+      raise
     end
 
 
@@ -102,6 +124,7 @@ module OMQ
     # @return [void]
     #
     def connect(endpoint)
+      freeze_error_lists!
       validate_endpoint!(endpoint)
       @connected_endpoints << endpoint
       if endpoint.start_with?("inproc://")
@@ -110,6 +133,7 @@ module OMQ
         transport.connect(endpoint, self)
       else
         # TCP/IPC connect in background — never blocks the caller
+        emit_monitor_event(:connect_delayed, endpoint: endpoint)
         schedule_reconnect(endpoint, delay: 0)
       end
     end
@@ -163,6 +187,7 @@ module OMQ
     # @return [void]
     #
     def handle_accepted(io, endpoint: nil)
+      emit_monitor_event(:accepted, endpoint: endpoint)
       spawn_connection(io, as_server: true, endpoint: endpoint)
     end
 
@@ -173,6 +198,7 @@ module OMQ
     # @return [void]
     #
     def handle_connected(io, endpoint: nil)
+      emit_monitor_event(:connected, endpoint: endpoint)
       spawn_connection(io, as_server: false, endpoint: endpoint)
     end
 
@@ -184,10 +210,12 @@ module OMQ
     # @return [void]
     #
     def connection_ready(pipe, endpoint: nil)
+      pipe = @connection_wrapper.call(pipe) if @connection_wrapper
       @connections << pipe
       @connection_endpoints[pipe] = endpoint if endpoint
       @routing.connection_added(pipe)
       @peer_connected.resolve(pipe)
+      emit_monitor_event(:handshake_succeeded, endpoint: endpoint)
     end
 
 
@@ -262,6 +290,13 @@ module OMQ
     # @yield [msg] optional per-message transform
     # @return [#stop, nil] pump task handle, or nil for DirectPipe bypass
     #
+    # Fairness limits for the recv pump. Yield to the scheduler
+    # after reading this many messages or bytes from one connection,
+    # whichever comes first. Prevents a fast or large-message
+    # connection from starving slower peers.
+    RECV_FAIRNESS_MESSAGES = 64
+    RECV_FAIRNESS_BYTES    = 1 << 20 # 1 MB
+
     def start_recv_pump(conn, recv_queue, &transform)
       if conn.is_a?(Transport::Inproc::DirectPipe) && conn.peer
         conn.peer.direct_recv_queue = recv_queue
@@ -270,11 +305,18 @@ module OMQ
       end
 
       if transform
-        @parent_task.async(transient: true, annotation: "recv pump") do
+        @parent_task.async(transient: true, annotation: "recv pump") do |task|
           loop do
-            msg = conn.receive_message
-            msg = transform.call(msg).freeze
-            recv_queue.enqueue(msg)
+            count = 0
+            bytes = 0
+            while count < RECV_FAIRNESS_MESSAGES && bytes < RECV_FAIRNESS_BYTES
+              msg = conn.receive_message
+              msg = transform.call(msg).freeze
+              recv_queue.enqueue(msg)
+              count += 1
+              bytes += msg.is_a?(Array) && msg.first.is_a?(String) ? msg.sum(&:bytesize) : 0
+            end
+            task.yield
           end
         rescue Async::Stop
         rescue Protocol::ZMTP::Error, *CONNECTION_LOST
@@ -283,9 +325,17 @@ module OMQ
           signal_fatal_error(error)
         end
       else
-        @parent_task.async(transient: true, annotation: "recv pump") do
+        @parent_task.async(transient: true, annotation: "recv pump") do |task|
           loop do
-            recv_queue.enqueue(conn.receive_message)
+            count = 0
+            bytes = 0
+            while count < RECV_FAIRNESS_MESSAGES && bytes < RECV_FAIRNESS_BYTES
+              msg = conn.receive_message
+              recv_queue.enqueue(msg)
+              count += 1
+              bytes += msg.is_a?(Array) && msg.first.is_a?(String) ? msg.sum(&:bytesize) : 0
+            end
+            task.yield
           end
         rescue Async::Stop
         rescue Protocol::ZMTP::Error, *CONNECTION_LOST
@@ -307,6 +357,7 @@ module OMQ
       @connections.delete(connection)
       @routing.connection_removed(connection)
       connection.close
+      emit_monitor_event(:disconnected, endpoint: endpoint)
 
       # Signal the connection task to exit.
       done = @connection_promises.delete(connection)
@@ -365,6 +416,8 @@ module OMQ
       @routing.stop rescue nil
       @tasks.each { |t| t.stop rescue nil }
       @tasks.clear
+      emit_monitor_event(:closed)
+      close_monitor_queue
     end
 
 
@@ -485,13 +538,16 @@ module OMQ
       )
       conn.handshake!
       start_heartbeat(conn)
+      conn = @connection_wrapper.call(conn) if @connection_wrapper
       @connections << conn
       @connection_endpoints[conn] = endpoint if endpoint
       @connection_promises[conn]  = done if done
       @routing.connection_added(conn)
       @peer_connected.resolve(conn)
+      emit_monitor_event(:handshake_succeeded, endpoint: endpoint)
       conn
-    rescue Protocol::ZMTP::Error, *CONNECTION_LOST
+    rescue Protocol::ZMTP::Error, *CONNECTION_LOST => error
+      emit_monitor_event(:handshake_failed, endpoint: endpoint, detail: { error: error })
       conn&.close
       raise
     end
@@ -556,6 +612,7 @@ module OMQ
             delay = [delay * 2, max_delay].min if max_delay
             # After first attempt with delay: 0, use the configured interval
             delay = ri.is_a?(Range) ? ri.begin : ri if delay == 0
+            emit_monitor_event(:connect_retried, endpoint: endpoint, detail: { interval: delay })
           end
         end
       rescue Async::Stop
@@ -572,70 +629,55 @@ module OMQ
     # resolution failures during reconnect are retried with backoff.
     #
     def validate_endpoint!(endpoint)
-      return unless endpoint.start_with?("tcp://")
-      host = URI.parse(endpoint.sub("tcp://", "http://")).hostname
-      Addrinfo.getaddrinfo(host, nil, nil, :STREAM) if host
+      transport = transport_for(endpoint)
+      transport.validate_endpoint!(endpoint) if transport.respond_to?(:validate_endpoint!)
     end
 
 
+
     def transport_for(endpoint)
-      case endpoint
-      when /\Atcp:\/\//    then Transport::TCP
-      when /\Aipc:\/\//    then Transport::IPC
-      when /\Ainproc:\/\// then Transport::Inproc
-      else raise ArgumentError, "unsupported transport: #{endpoint}"
+      scheme = endpoint[/\A([^:]+):\/\//, 1]
+      self.class.transports[scheme] or
+        raise ArgumentError, "unsupported transport: #{endpoint}"
+    end
+
+
+    # Delegates accept loop startup to the listener.
+    #
+    # Stream-based listeners (TCP, IPC, TLS, …) implement
+    # +#start_accept_loops+. Inproc listeners do not — connections
+    # are established synchronously during +connect+.
+    #
+    def start_accept_loops(listener)
+      return unless listener.respond_to?(:start_accept_loops)
+      listener.start_accept_loops(@parent_task) do |io|
+        handle_accepted(io, endpoint: listener.endpoint)
       end
     end
 
 
-    def extract_tcp_port(endpoint)
-      return nil unless endpoint&.start_with?("tcp://")
-      port = endpoint.split(":").last.to_i
-      port.positive? ? port : nil
+    def freeze_error_lists!
+      return if OMQ::CONNECTION_LOST.frozen?
+      OMQ::CONNECTION_LOST.freeze
+      OMQ::CONNECTION_FAILED.freeze
     end
 
 
-    # Spawns accept loops for a listener under @parent_task.
-    #
-    # TCP listeners have multiple server sockets (IPv4/IPv6);
-    # IPC listeners have one. Inproc listeners have none.
-    #
-    def start_accept_loops(listener)
-      case listener
-      when Transport::TCP::Listener
-        tasks = listener.servers.map do |server|
-          @parent_task.async(transient: true, annotation: "tcp accept #{listener.endpoint}") do
-            loop do
-              client = server.accept
-              Async::Task.current.defer_stop do
-                handle_accepted(IO::Stream::Buffered.wrap(client), endpoint: listener.endpoint)
-              end
-            end
-          rescue Async::Stop
-          rescue IOError
-            # server closed
-          ensure
-            server.close rescue nil
-          end
-        end
-        listener.accept_tasks = tasks
+    def emit_monitor_event(type, endpoint: nil, detail: nil)
+      return unless @monitor_queue
+      @monitor_queue.push(MonitorEvent.new(type: type, endpoint: endpoint, detail: detail))
+    rescue Async::Stop, ClosedQueueError
+    end
 
-      when Transport::IPC::Listener
-        task = @parent_task.async(transient: true, annotation: "ipc accept #{listener.endpoint}") do
-          loop do
-            client = listener.server.accept
-            Async::Task.current.defer_stop do
-              handle_accepted(IO::Stream::Buffered.wrap(client), endpoint: listener.endpoint)
-            end
-          end
-        rescue Async::Stop
-        rescue IOError
-          # server closed
-        ensure
-          listener.server.close rescue nil
-        end
-        listener.accept_task = task
-      end
+
+    def close_monitor_queue
+      return unless @monitor_queue
+      @monitor_queue.push(nil)
     end
   end
+
+  # Register built-in transports.
+  Engine.transports["tcp"]    = Transport::TCP
+  Engine.transports["ipc"]    = Transport::IPC
+  Engine.transports["inproc"] = Transport::Inproc
 end

data/lib/omq/monitor_event.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module OMQ
+  # Lifecycle event emitted by {Socket#monitor}.
+  #
+  # @!attribute [r] type
+  #   @return [Symbol] event type (:listening, :connected, :disconnected, etc.)
+  # @!attribute [r] endpoint
+  #   @return [String, nil] the endpoint involved
+  # @!attribute [r] detail
+  #   @return [Hash, nil] extra context (e.g. { error: }, { interval: }, etc.)
+  #
+  MonitorEvent = Data.define(:type, :endpoint, :detail) do
+    def initialize(type:, endpoint: nil, detail: nil) = super
+  end
+end

data/lib/omq/options.rb

@@ -23,9 +23,11 @@ module OMQ
       @heartbeat_interval    = nil   # seconds, nil = disabled
       @heartbeat_ttl         = nil   # seconds, nil = use heartbeat_interval
       @heartbeat_timeout     = nil   # seconds, nil = use heartbeat_interval
-      @max_message_size      = nil  # bytes, nil = unlimited
+      @max_message_size      = 1 << 20  # bytes (1 MiB default)
       @conflate              = false
+      @on_mute               = :block   # :block, :drop_newest, :drop_oldest
       @mechanism             = Protocol::ZMTP::Mechanism::Null.new
+      @qos                   = 0       # 0 = fire-and-forget, 1 = at-least-once (see omq-qos gem)
     end
 
     attr_accessor :send_hwm,  :recv_hwm,
@@ -35,7 +37,9 @@ module OMQ
                   :reconnect_interval,
                   :heartbeat_interval,    :heartbeat_ttl,    :heartbeat_timeout,
                   :max_message_size,
-                  :mechanism
+                  :on_mute,
+                  :mechanism,
+                  :qos
 
     alias_method :router_mandatory?, :router_mandatory
     alias_method :recv_timeout,      :read_timeout

data/lib/omq/pair.rb

@@ -5,8 +5,8 @@ module OMQ
     include Readable
     include Writable
 
-    def initialize(endpoints = nil, linger: 0)
-      _init_engine(:PAIR, linger: linger)
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:PAIR, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)
     end
   end