omq 0.22.1 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f58b9e0c8c49bcdfb8dd80ec5eda6a6b6e5b09f04a2a7851001449449ba448fd
-  data.tar.gz: 0f6cbd451adc8b1d1cde0771d6535c5959f09e4b3f0442164b0544964755795e
+  metadata.gz: ed87cc3a3243100b7977fd58f102b87918de8568cf8739642afc6377bb3f76e5
+  data.tar.gz: f01b30844ae48ffe26ec3934fef780521937a7611e1d00c87b333136fa5641ac
 SHA512:
-  metadata.gz: d7d13f97eeacf998f1e0137bdbc5dd4a471195ff628fd7da97720a019e30c2a9c200fab761c38943bbbada056bf81880e6ca2dd87d3936f150f0fa22566cebe5
-  data.tar.gz: f97931ecb4893ecd0155c37ea18793c9414bd57de6918496ef7af18bad714720aa2e146531788956265d6f85bc3e18f6dd403f71df8683913d322c94a6dd1bdb
+  metadata.gz: 853d3171298de868ad3de28fe284c7970ddf196203bbb217fc91fa62cebb9d39c1d278b53d4259d0dc505b09457624ea68f4a9a8a0e654850c9266139a1fa05e
+  data.tar.gz: ad8a2cec518ceebac32055aeab7fd159d982421e9983670ec28182094f4fe2338f89cd7a1609d02cd8720f01c121159fec7e2489b8c816f9f16adf9d950c34c4

data/CHANGELOG.md

@@ -1,5 +1,167 @@
 # Changelog
 
+## 0.24.0 — 2026-04-18
+
+### Changed
+
+- **Caller owns message parts.** `Writable#send` no longer deep-freezes or
+  binary-coerces the caller's input. The contract is now libzmq-style:
+  don't mutate parts after sending. `#receive` likewise returns mutable
+  arrays of mutable strings. This removes a full-payload allocation per
+  message (`.b.freeze`) on the send path and a per-frame freeze on the
+  receive path.
+
+- **No more implicit `#to_s` / nil coercion.** Passing a non-string part
+  (e.g. Integer, Symbol, nil) will raise `NoMethodError` at the wire layer
+  instead of being silently converted. The `EMPTY_PART` constant is gone.
+
+- **Reactor fast path for `#send` / `#receive`.** When the socket was
+  bound/connected from an Async fiber, hot-path I/O skips `Reactor.run`
+  entirely and calls the engine directly (with an `Async::Task#with_timeout`
+  wrapper only when a timeout is configured). The shared IO thread is used
+  only when the socket was created from a non-Async thread.
+
+### Performance
+
+Combined effect of caller-owns-data + Reactor fast path on inproc:
+
+- PUSH/PULL inproc 1-peer: **+105% to +128%** msg/s across payload sizes
+- PUSH/PULL inproc 3-peer: **+63% to +111%** msg/s
+- PUSH/PULL ipc: +5% to +17%
+- TCP numbers unchanged (OS/syscall-dominated)
+
+### Removed
+
+- `Writable#freeze_message` and `#frozen_binary` private helpers.
+- `Writable::EMPTY_PART` constant.
+
+
+## 0.23.1 — 2026-04-18
+
+### Fixed
+
+- **SCATTER double-tracked each peer.** `Routing::Scatter#connection_added`
+  appended to `@connections` and then called `add_round_robin_send_connection`,
+  which appends again — so every connected peer had two entries in the list.
+  `#connection_removed` deleted only one on disconnect, leaving a stale entry
+  behind. Fixed by dropping the duplicate append.
+
+
+## 0.23.0 — 2026-04-17
+
+### Added
+
+- **Draft socket types now ship with `omq` itself.** `OMQ::CLIENT`/`SERVER`,
+  `OMQ::RADIO`/`DISH`, `OMQ::SCATTER`/`GATHER`, `OMQ::CHANNEL`, and
+  `OMQ::PEER` are back in OMQ. They were previously distributed as separate
+  `omq-rfc-*` gems, which was a PITA to maintain. Their source is now part of
+  `omq`. They are **not** loaded by `require "omq"` — opt in with one of:
+
+  ```ruby
+  require "omq/client_server"
+  require "omq/radio_dish"      # also registers the udp:// transport
+  require "omq/scatter_gather"
+  require "omq/channel"
+  require "omq/peer"
+  ```
+
+  These requires must run at process startup (before any socket is bound
+  or connected), since the underlying registries (`Routing`,
+  `Engine.transports`) freeze on first use. The five `omq-rfc-*` gems are
+  superseded and will not receive further releases. Per-pattern docs live
+  under [`doc/socket-types/`](doc/socket-types/).
+
+
+### Changed
+
+- **`Socket#bind` / `#connect` now return a `URI`** (the resolved endpoint).
+  `#bind` returns the listener's resolved URI — for `tcp://host:0` this
+  carries the auto-selected port via `uri.port`. `#connect` returns the
+  parsed input URI. The `last_tcp_port` and `last_endpoint` accessors are
+  removed; callers should capture the URI from `#bind` instead. Note: stdlib
+  `URI.parse` is lossy on abstract IPC endpoints (`ipc://@name`) — the `@`
+  is parsed as userinfo and dropped on `to_s`. For abstract IPC, use the
+  input string for connect rather than re-serializing the URI.
+  `Socket#inspect` now shows `bound=[...]` (the listener endpoints) instead
+  of `last_endpoint=...`.
+
+- **Transport interface: `.bind`/`.connect` replaced by `.listener`/`.dialer`
+  factory methods** returning stateful `Listener`/`Dialer` objects. The
+  engine now stores a per-endpoint `@dialers` map (was a `@dialed` Set)
+  and a `@listeners` hash keyed by endpoint (was an Array). Reconnect
+  calls `dialer.connect` directly — no transport lookup or option replay
+  on every retry. `Transport::Inproc` keeps its synchronous `.connect`
+  fast-path; only TCP/IPC gain `Dialer` classes.
+
+- **`Engine#bind` / `#connect` accept transport-specific kwargs** via
+  `**opts`, forwarded to the transport's `.listener` / `.dialer`. Socket
+  `#bind` / `#connect` pass them through. Enables per-connection
+  transport configuration (e.g., TLS context) without polluting
+  `Options`.
+
+- **`ConnectionLifecycle#ready!` calls `transport_obj.wrap_connection(conn)`
+  if defined** — hook for transports that need to wrap the buffered
+  stream after handshake (e.g., TLS).
+
+- **Transports self-register in `Engine.transports`.** Each transport
+  file (`tcp`, `ipc`, `inproc`) now adds its own scheme entry at load
+  time. `lib/omq.rb` requires transports after `engine.rb` so the
+  `Engine` constant is available. External transport plugins follow
+  the same pattern.
+
+- **`Engine` gains delegate methods that hide internal layout** from
+  callers: `#subscribe`, `#unsubscribe`, `#subscriber_joined` forward
+  to the routing strategy; `#record_disconnect_reason(conn, error)`
+  wraps the `@connections` lookup; `Inproc::DirectPipe#wire_direct_recv`
+  replaces two separate attribute setters previously poked from the
+  recv pump. Callers no longer chain through `engine.routing.*` or
+  `engine.connections[conn]`.
+
+- **`SocketLifecycle#resolve_all_peers_gone_if_empty` renamed to
+  `#maybe_resolve_all_peers_gone`.** The composite `unless` was split
+  into two early-returns for readability. A new `#force_close!` handles
+  `Engine#stop`'s crash path, collapsing two `@lifecycle.*` calls into
+  one.
+
+- **Module-level constants consolidated into `lib/omq/constants.rb`.**
+  `MonitorEvent`, `DEBUG`, `SocketDeadError`, `CONNECTION_LOST`,
+  `CONNECTION_FAILED`, and `OMQ.freeze_for_ractors!` now live in one
+  file. `lib/omq/monitor_event.rb` is deleted; `lib/omq.rb` just
+  requires `omq/constants`.
+
+### Removed
+
+- **`Engine#tasks` array** (and every `@tasks << ...` append site)
+  deleted. `Async::Barrier` already tracks every spawned task and
+  exposes `#size`, `#empty?`, and `#stop`. `Heartbeat.start`,
+  `Maintenance.start`, and `Reconnect#run` drop their `tasks`
+  parameter. Teardown collapses to `@lifecycle.barrier&.stop`.
+
+- **Routing strategies and TCP listener drop their `@tasks` arrays
+  too.** Same `Async::Barrier` rollout applied to every routing
+  strategy and `Transport::TCP::Listener`. Per-connection pumps
+  (send/recv/reaper/group/subscription listener) ride the
+  per-connection lifecycle barrier; Radio's socket-level send pump
+  rides `engine.barrier` via a new `parent:` kwarg on
+  `Engine#spawn_pump_task`. The redundant `@conn_send_tasks` hashes
+  in RoundRobin, FanOut, Rep, Router, Peer, and Server are gone, as
+  are all routing-strategy `#stop` methods and the matching
+  `routing.stop rescue nil` calls in `Engine#close`/`#stop`.
+  `ConnSendPump.start` drops its `tasks` parameter. Channel's send
+  pump moves from loose `spawn_pump_task` to `spawn_conn_pump_task`,
+  so its disconnect rescue is now centralized in `Engine`. Net: 24
+  files, −340/+121.
+
+### Fixed
+
+- **`bench/report.rb` preserves chronological run order.** Named run IDs
+  (e.g. `baseline-append`) previously sorted alphabetically after ISO
+  timestamps, hiding the most recent run. Now uses insertion order.
+
+- **`zmtp_30_compat_test` waits for XSUB connection** before sending
+  `SUBSCRIBE`, removing a race where the subscribe arrived before the
+  handshake completed.
+
 ## 0.22.1 — 2026-04-16
 
 ### Changed

data/README.md

@@ -20,7 +20,7 @@ live in the same process, on the same machine, or across the network.
 Reconnects, queuing, and back-pressure are handled for you; you write the
 interesting part.
 
-New to ZeroMQ? Start with [GETTING_STARTED.md](GETTING_STARTED.md) — a ~30 min
+New to ZeroMQ? Start with [GETTING_STARTED.md](doc/GETTING_STARTED.md) — a ~30 min
 walkthrough of every major pattern with working code.
 
 ## Highlights
@@ -45,7 +45,7 @@ walkthrough of every major pattern with working code.
   connect, peers come and go. ZeroMQ reconnects automatically and queued
   messages drain when peers arrive
 
-For architecture internals, see [DESIGN.md](DESIGN.md).
+For architecture internals, see [DESIGN.md](doc/DESIGN.md).
 
 ## Install
 
@@ -176,20 +176,22 @@ wire. Classes live under `OMQ::` (alias: `ØMQ`).
 > **Work-stealing, not round-robin.** Outbound load balancing uses one shared
 > send queue per socket drained by N racing pump fibers, so a slow peer can't
 > stall the pipeline. Under tight bursts on small `n`, distribution isn't
-> strict RR. See [DESIGN.md](DESIGN.md#per-socket-hwm-not-per-connection) and
-> [Libzmq quirks](DESIGN.md#libzmq-quirks-omq-avoids) for the reasoning.
+> strict RR. See [DESIGN.md](doc/DESIGN.md#per-socket-hwm-not-per-connection) and
+> [Libzmq quirks](doc/DESIGN.md#libzmq-quirks-omq-avoids) for the reasoning.
 
 #### Draft (single-frame only)
 
-Each draft pattern lives in its own gem — install only the ones you use.
+Bundled with `omq` but not loaded by `require "omq"` — opt in with the matching
+`require` line. See [`doc/socket-types/`](doc/socket-types/) for per-pattern
+usage.
 
-| Pattern | Send | Receive | When HWM full | Gem |
-|---------|------|---------|---------------|-----|
-| **CLIENT** / **SERVER** | Work-stealing / routing-ID | Fair-queue | Block | [`omq-rfc-clientserver`](https://github.com/paddor/omq-rfc-clientserver) |
-| **RADIO** / **DISH** | Group fan-out | Group filter | Drop | [`omq-rfc-radiodish`](https://github.com/paddor/omq-rfc-radiodish) |
-| **SCATTER** / **GATHER** | Work-stealing | Fair-queue | Block | [`omq-rfc-scattergather`](https://github.com/paddor/omq-rfc-scattergather) |
-| **PEER** | Routing-ID | Fair-queue | Block | [`omq-rfc-p2p`](https://github.com/paddor/omq-rfc-p2p) |
-| **CHANNEL** | Exclusive 1-to-1 | Exclusive 1-to-1 | Block | [`omq-rfc-channel`](https://github.com/paddor/omq-rfc-channel) |
+| Pattern | Send | Receive | When HWM full | Opt-in `require` |
+|---------|------|---------|---------------|------------------|
+| **CLIENT** / **SERVER** | Work-stealing / routing-ID | Fair-queue | Block | `require "omq/client_server"` |
+| **RADIO** / **DISH** | Group fan-out | Group filter | Drop | `require "omq/radio_dish"` (also registers `udp://`) |
+| **SCATTER** / **GATHER** | Work-stealing | Fair-queue | Block | `require "omq/scatter_gather"` |
+| **PEER** | Routing-ID | Fair-queue | Block | `require "omq/peer"` |
+| **CHANNEL** | Exclusive 1-to-1 | Exclusive 1-to-1 | Block | `require "omq/channel"` |
 
 ## CLI
 
@@ -220,7 +222,7 @@ See the [omq-cli README](https://github.com/paddor/omq-cli) for full documentati
 Optional plug-ins that extend the ZMTP wire protocol. Each is a separate gem;
 load the ones you need.
 
-- **[omq-rfc-zstd](https://github.com/paddor/omq-rfc-zstd)** — transparent
+- **[omq-zstd](https://github.com/paddor/omq-zstd)** — transparent
   Zstandard compression on the wire, negotiated per peer via READY properties.
 
 ## Development
@@ -233,7 +235,7 @@ bundle exec rake
 ### Full development setup
 
 Set `OMQ_DEV=1` to tell Bundler to load sibling projects from source
-(protocol-zmtp, nuckle, omq-rfc-\*, etc.) instead of released gems.
+(protocol-zmtp, omq-zstd ,nuckle, etc.) instead of released gems.
 This is required for running benchmarks and for testing changes across
 the stack.
 
@@ -241,13 +243,7 @@ the stack.
 # clone OMQ and its sibling repos into the same parent directory
 git clone https://github.com/paddor/omq.git
 git clone https://github.com/paddor/protocol-zmtp.git
-git clone https://github.com/paddor/omq-rfc-zstd.git
-git clone https://github.com/paddor/omq-rfc-clientserver.git
-git clone https://github.com/paddor/omq-rfc-radiodish.git
-git clone https://github.com/paddor/omq-rfc-scattergather.git
-git clone https://github.com/paddor/omq-rfc-channel.git
-git clone https://github.com/paddor/omq-rfc-p2p.git
-git clone https://github.com/paddor/omq-rfc-qos.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/channel.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# OMQ CHANNEL socket type (ZeroMQ RFC 52).
+#
+# Not loaded by +require "omq"+; opt in with:
+#
+#   require "omq/channel"
+
+require "omq"
+require_relative "routing/channel"
+
+module OMQ
+  # Exclusive 1-to-1 bidirectional socket (ZeroMQ RFC 52).
+  #
+  # Allows exactly one peer connection. Both sides can send and receive.
+  class CHANNEL < Socket
+    include Readable
+    include Writable
+    include SingleFrame
+
+    # Creates a new CHANNEL socket.
+    #
+    # @param endpoints [String, Array<String>, nil] endpoint(s) to connect to
+    # @param linger [Numeric] linger period in seconds (Float::INFINITY = wait forever, 0 = drop)
+    # @param backend [Object, nil] optional transport backend
+    def initialize(endpoints = nil, linger: Float::INFINITY, backend: nil)
+      init_engine(:CHANNEL, backend: backend)
+      @options.linger = linger
+      attach_endpoints(endpoints, default: :connect)
+    end
+  end
+
+
+  Routing.register(:CHANNEL, Routing::Channel)
+end

data/lib/omq/client_server.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# OMQ CLIENT/SERVER socket types (ZeroMQ RFC 41).
+#
+# Not loaded by +require "omq"+; opt in with:
+#
+#   require "omq/client_server"
+
+require "omq"
+require_relative "routing/client"
+require_relative "routing/server"
+
+module OMQ
+  # Asynchronous client socket for the CLIENT/SERVER pattern (ZeroMQ RFC 41).
+  #
+  # Round-robins outgoing messages across connected SERVER peers.
+  class CLIENT < Socket
+    include Readable
+    include Writable
+    include SingleFrame
+
+    # Creates a new CLIENT socket.
+    #
+    # @param endpoints [String, Array<String>, nil] endpoint(s) to connect to
+    # @param linger [Numeric] linger period in seconds (Float::INFINITY = wait forever, 0 = drop)
+    # @param backend [Object, nil] optional transport backend
+    def initialize(endpoints = nil, linger: Float::INFINITY, backend: nil)
+      init_engine(:CLIENT, backend: backend)
+      @options.linger = linger
+      attach_endpoints(endpoints, default: :connect)
+    end
+  end
+
+
+  # Asynchronous server socket for the CLIENT/SERVER pattern (ZeroMQ RFC 41).
+  #
+  # Assigns a 4-byte routing ID to each connected CLIENT and supports
+  # directed replies via #send_to.
+  class SERVER < Socket
+    include Readable
+    include Writable
+    include SingleFrame
+
+    # Creates a new SERVER socket.
+    #
+    # @param endpoints [String, Array<String>, nil] endpoint(s) to bind to
+    # @param linger [Numeric] linger period in seconds (Float::INFINITY = wait forever, 0 = drop)
+    # @param backend [Object, nil] optional transport backend
+    def initialize(endpoints = nil, linger: Float::INFINITY, backend: nil)
+      init_engine(:SERVER, backend: backend)
+      @options.linger = linger
+      attach_endpoints(endpoints, default: :bind)
+    end
+
+
+    # Sends a message to a specific peer by routing ID.
+    #
+    # @param routing_id [String] 4-byte routing ID
+    # @param message [String] message body
+    # @return [self]
+    #
+    def send_to(routing_id, message)
+      parts = [routing_id, message]
+      Reactor.run(timeout: @options.write_timeout) { @engine.enqueue_send(parts) }
+      self
+    end
+  end
+
+
+  Routing.register(:CLIENT, Routing::Client)
+  Routing.register(:SERVER, Routing::Server)
+end

data/lib/omq/constants.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "socket"
+require "io/stream"
+
+module OMQ
+  # When OMQ_DEBUG is set, silent rescue clauses print the exception
+  # to stderr so transport/engine bugs surface immediately.
+  DEBUG = !!ENV["OMQ_DEBUG"]
+
+
+  # Raised when an internal pump task crashes unexpectedly.
+  # The socket is no longer usable; the original error is available via #cause.
+  #
+  class SocketDeadError < RuntimeError
+  end
+
+
+  # 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
+
+
+  # Errors raised when a peer disconnects or resets the connection.
+  # Not frozen at load time — transport plugins append to this before
+  # the first bind/connect, which freezes both arrays.
+  CONNECTION_LOST = [
+    EOFError,
+    IOError,
+    Errno::EPIPE,
+    Errno::ECONNRESET,
+    Errno::ECONNABORTED,
+    Errno::ENOTCONN,
+    IO::Stream::ConnectionResetError,
+  ]
+
+
+  # Errors raised when a peer cannot be reached.
+  CONNECTION_FAILED = [
+    Errno::ECONNREFUSED,
+    Errno::ENOENT,
+    Errno::ETIMEDOUT,
+    Errno::EHOSTUNREACH,
+    Errno::ENETUNREACH,
+    Errno::EPROTOTYPE, # IPC: existing socket file is SOCK_DGRAM, not SOCK_STREAM
+    Socket::ResolutionError,
+  ]
+
+
+  # Freezes module-level state so OMQ sockets can be used inside Ractors.
+  # Call this once before spawning any Ractors that create OMQ sockets.
+  #
+  def self.freeze_for_ractors!
+    CONNECTION_LOST.freeze
+    CONNECTION_FAILED.freeze
+    Engine.transports.freeze
+    Routing.registry.freeze
+  end
+end

data/lib/omq/engine/connection_lifecycle.rb

@@ -5,7 +5,7 @@ module OMQ
     # Owns the full arc of *one* connection: handshake → ready → closed.
     #
     # Scope boundary: ConnectionLifecycle tracks a single peer link
-    # (one ZMTP connection or one inproc DirectPipe). SocketLifecycle
+    # (one ZMTP connection or one inproc Pipe). SocketLifecycle
     # owns the socket-wide state above it — first-peer/last-peer
     # signaling, reconnect enable flag, the parent task tree, and the
     # open → closing → closed transitions that gate close-time drain.
@@ -43,7 +43,7 @@ module OMQ
       }.freeze
 
 
-      # @return [Protocol::ZMTP::Connection, Transport::Inproc::DirectPipe, nil]
+      # @return [Protocol::ZMTP::Connection, Transport::Inproc::Pipe, nil]
       attr_reader :conn
 
 
@@ -101,7 +101,7 @@ module OMQ
           conn.handshake!
         end
 
-        Heartbeat.start(@barrier, conn, @engine.options, @engine.tasks)
+        Heartbeat.start(@barrier, conn, @engine.options)
         ready!(conn)
         @conn
       rescue Protocol::ZMTP::Error, *CONNECTION_LOST, Async::TimeoutError => error
@@ -120,9 +120,9 @@ module OMQ
 
 
       # Registers an already-connected inproc pipe as :ready.
-      # No handshake — inproc DirectPipe bypasses ZMTP entirely.
+      # No handshake — inproc Pipe bypasses ZMTP entirely.
       #
-      # @param pipe [Transport::Inproc::DirectPipe]
+      # @param pipe [Transport::Inproc::Pipe]
       #
       def ready_direct!(pipe)
         ready!(pipe)
@@ -161,7 +161,17 @@ module OMQ
 
 
       def ready!(conn)
-        conn  = @engine.connection_wrapper.call(conn) if @engine.connection_wrapper
+        if @engine.connection_wrapper
+          conn = @engine.connection_wrapper.call(conn)
+        end
+
+        if @endpoint
+          transport_obj = @engine.transport_object_for(@endpoint)
+          if transport_obj.respond_to?(:wrap_connection)
+            conn = transport_obj.wrap_connection(conn)
+          end
+        end
+
         @conn = conn
         @engine.connections[@conn] = self
         @engine.emit_monitor_event(:handshake_succeeded, endpoint: @endpoint)
@@ -169,7 +179,7 @@ module OMQ
         @engine.peer_connected.resolve(@conn)
         transition!(:ready)
 
-        # No supervisor if nothing to supervise: inproc DirectPipes
+        # No supervisor if nothing to supervise: inproc Pipes
         # wire the recv/send paths synchronously (no task-based pumps),
         # and isolated unit tests use a FakeEngine without pumps at all.
         # Waiting on an empty barrier returns immediately and would
@@ -205,6 +215,7 @@ module OMQ
 
       def tear_down!(reconnect:, reason: nil)
         return if @state == :closed
+
         transition!(:closed)
         @engine.connections.delete(@conn)
         @engine.routing.connection_removed(@conn) if @conn
@@ -212,7 +223,7 @@ module OMQ
         detail = reason ? { error: reason, reason: reason.message } : nil
         @engine.emit_monitor_event(:disconnected, endpoint: @endpoint, detail: detail)
         @done&.resolve(true)
-        @engine.resolve_all_peers_gone_if_empty
+        @engine.maybe_resolve_all_peers_gone
         @engine.maybe_reconnect(@endpoint) if reconnect
 
         # Cancel every sibling pump of this connection. The caller is
@@ -236,11 +247,14 @@ module OMQ
 
       def transition!(new_state)
         allowed = TRANSITIONS[@state]
+
         unless allowed&.include?(new_state)
           raise InvalidTransition, "#{@state} → #{new_state}"
         end
+
         @state = new_state
       end
+
     end
   end
 end

data/lib/omq/engine/heartbeat.rb

@@ -9,11 +9,10 @@ module OMQ
     #
     module Heartbeat
       # @param parent [Async::Task, Async::Barrier] parent to spawn under
-      # @param conn [Connection]
+      # @param conn [Protocol::ZMTP::Connection]
       # @param options [Options]
-      # @param tasks [Array]
       #
-      def self.start(parent, conn, options, tasks)
+      def self.start(parent, conn, options)
         interval = options.heartbeat_interval
         return unless interval
 
@@ -21,7 +20,7 @@ module OMQ
         timeout = options.heartbeat_timeout || interval
         conn.touch_heartbeat
 
-        tasks << parent.async(transient: true, annotation: "heartbeat") do
+        parent.async(transient: true, annotation: "heartbeat") do
           loop do
             sleep interval
             conn.send_command(Protocol::ZMTP::Codec::Command.ping(ttl: ttl))

data/lib/omq/engine/maintenance.rb

@@ -12,17 +12,15 @@ module OMQ
     module Maintenance
       # @param parent_task [Async::Task]
       # @param mechanism [#maintenance, nil]
-      # @param tasks [Array<Async::Task>]
       #
-      def self.start(parent_task, mechanism, tasks)
+      def self.start(parent_task, mechanism)
         return unless mechanism.respond_to?(:maintenance)
-        spec = mechanism.maintenance
-        return unless spec
+        spec = mechanism.maintenance or return spec
 
         interval = spec[:interval]
         callable = spec[:task]
 
-        tasks << parent_task.async(transient: true, annotation: "mechanism maintenance") do
+        parent_task.async(transient: true, annotation: "mechanism maintenance") do
           Async::Loop.quantized(interval: interval) do
             callable.call
           end
@@ -30,6 +28,7 @@ module OMQ
           # clean shutdown
         end
       end
+
     end
   end
 end

data/lib/omq/engine/reconnect.rb

@@ -8,25 +8,25 @@ module OMQ
     # or the engine is closed.
     #
     class Reconnect
-      # @param endpoint [String]
+      # @param dialer [Transport::TCP::Dialer, etc.] stateful dialer factory
       # @param options [Options]
       # @param parent_task [Async::Task]
       # @param engine [Engine]
       # @param delay [Numeric, nil] initial delay (defaults to reconnect_interval)
       #
-      def self.schedule(endpoint, options, parent_task, engine, delay: nil)
-        new(engine, endpoint, options).run(parent_task, delay: delay)
+      def self.schedule(dialer, options, parent_task, engine, delay: nil)
+        new(engine, dialer, options).run(parent_task, delay: delay)
       end
 
 
       # @param engine [Engine]
-      # @param endpoint [String]
+      # @param dialer [Transport::TCP::Dialer, etc.] stateful dialer factory
       # @param options [Options]
       #
-      def initialize(engine, endpoint, options)
-        @engine   = engine
-        @endpoint = endpoint
-        @options  = options
+      def initialize(engine, dialer, options)
+        @engine  = engine
+        @dialer  = dialer
+        @options = options
       end
 
 
@@ -37,7 +37,8 @@ module OMQ
       # @return [void]
       #
       def run(parent_task, delay: nil)
-        @engine.tasks << parent_task.async(transient: true, annotation: "reconnect #{@endpoint}") do
+        endpoint = @dialer.endpoint
+        parent_task.async(transient: true, annotation: "reconnect #{endpoint}") do
           retry_loop(delay: delay)
         rescue Async::Stop
         rescue => error
@@ -57,12 +58,12 @@ module OMQ
           sleep quantized_wait(delay) if delay > 0
           break if @engine.closed?
           begin
-            @engine.transport_for(@endpoint).connect(@endpoint, @engine)
+            @dialer.connect
             break
           rescue *CONNECTION_LOST, *CONNECTION_FAILED, Protocol::ZMTP::Error
             delay = next_delay(delay, max_delay)
             @engine.emit_monitor_event :connect_retried,
-                                       endpoint: @endpoint, detail: { interval: delay }
+                                       endpoint: @dialer.endpoint, detail: { interval: delay }
           end
         end
       end