omq 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa0683eef1c05982186c434cfbb21112518ec220e843207fa772a3cc3cd69ee9
-  data.tar.gz: 95b92509cac850c9b45380675fec60ed3db22cc21674ffde09901742b024f43a
+  metadata.gz: 2a0e72756aae2179b8c790d5b65c54a82b516a17d11f760187a6fefecf6bf2c1
+  data.tar.gz: d6ce860b558977939b28c3d1f23d7bfc0740cf602fb63a519107a59cdca3c8c3
 SHA512:
-  metadata.gz: 51b018f6e6d0fe83181e14fefc9f7cda13661cc3e071e2b83f2ed517e98e550eb22f9c7b7092696261ce4bd458a7355ccfe51cb44235c38df9004f6c72d7c31b
-  data.tar.gz: 7e4581c1f0e18714a30af54833d6cabef1001936d5f4126bde2fa6144dfe3b153b825dff82576a7abca0d61dc9f87b01f0a962f950c56c2d0a5803705addf1ca
+  metadata.gz: fa8a7c98147aa4f0fea5fad3004e8a964105a2005ed645d03b0fd1f0fba67bfc4952a3f4d14926fbaf4293efdcada93235b2ba59956737ef0ced5c1b97d35ea2
+  data.tar.gz: b5878650300c7135e04ec8fffcadef6d5101f77c8f2a7e3e6c1407faebe57714b613398c3fecf71b561cb8bdb6c25a70646d812c395db46f78827e97f796c8e7

data/CHANGELOG.md

@@ -1,5 +1,144 @@
 # Changelog
 
+## 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
+
+- **Reuse batch arrays in send pumps.** All send pumps (RoundRobin,
+  Pair, ConnSendPump, FanOut, FanOut-conflate) now pre-allocate a
+  single batch array and clear it between cycles instead of
+  allocating a fresh `[msg]` per dequeue.
+
+- **`Routing.dequeue_batch`** consolidates the blocking-dequeue +
+  non-blocking-sweep pattern that was duplicated across four call
+  sites into one method. `dequeue_batch_capped` does the same for
+  the byte/message-capped RoundRobin variant.
+
+- **REP envelope stored as `[conn, envelope]`** instead of a Hash,
+  and reply assembly uses `<<` + `concat` instead of double splat.
+
+- **Heartbeat drops redundant `context: "".b`** — the default is
+  now `EMPTY_BINARY` in protocol-zmtp.
+
+- **Bench harness accepts `OMQ_BENCH_SIZES`, `OMQ_BENCH_TRANSPORTS`,
+  and `OMQ_BENCH_PEERS`** env vars to scope runs without editing
+  code.
+
 ## 0.22.0 — 2026-04-15
 
 ### Fixed

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.b.freeze, message.b.freeze]
+      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

@@ -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
@@ -161,7 +161,15 @@ module OMQ
 
 
       def ready!(conn)
-        conn  = @engine.connection_wrapper.call(conn) if @engine.connection_wrapper
+        conn = @engine.connection_wrapper.call(conn) if @engine.connection_wrapper
+
+        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)
@@ -212,7 +220,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

data/lib/omq/engine/heartbeat.rb

@@ -11,9 +11,8 @@ module OMQ
       # @param parent [Async::Task, Async::Barrier] parent to spawn under
       # @param conn [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,10 +20,10 @@ 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, context: "".b))
+            conn.send_command(Protocol::ZMTP::Codec::Command.ping(ttl: ttl))
             if conn.heartbeat_expired?(timeout)
               conn.close
               break

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

data/lib/omq/engine/recv_pump.rb

@@ -61,8 +61,7 @@ module OMQ
       #
       def start(parent_task, transform)
         if @conn.is_a?(Transport::Inproc::DirectPipe) && @conn.peer
-          @conn.peer.direct_recv_queue     = @recv_queue
-          @conn.peer.direct_recv_transform = transform
+          @conn.peer.wire_direct_recv(@recv_queue, transform)
           return nil
         end
 
@@ -125,7 +124,7 @@ module OMQ
         rescue Protocol::ZMTP::Error, *CONNECTION_LOST => error
           # expected disconnect — stash reason for the :disconnected
           # monitor event, let the lifecycle reconnect as usual
-          engine.connections[conn]&.record_disconnect_reason(error)
+          engine.record_disconnect_reason(conn, error)
         rescue => error
           engine.signal_fatal_error(error)
         end
@@ -172,7 +171,7 @@ module OMQ
         rescue Protocol::ZMTP::Error, *CONNECTION_LOST => error
           # expected disconnect — stash reason for the :disconnected
           # monitor event, let the lifecycle reconnect as usual
-          engine.connections[conn]&.record_disconnect_reason(error)
+          engine.record_disconnect_reason(conn, error)
         rescue => error
           engine.signal_fatal_error(error)
         end

data/lib/omq/engine/socket_lifecycle.rb

@@ -28,11 +28,11 @@ module OMQ
 
 
       TRANSITIONS = {
-        new:     %i[open closed].freeze,
-        open:    %i[closing closed].freeze,
-        closing: %i[closed].freeze,
-        closed:  [].freeze,
-      }.freeze
+        new:     %i[open closed],
+        open:    %i[closing closed],
+        closing: %i[closed],
+        closed:  [],
+      }.transform_values(&:freeze).freeze
 
 
       # @return [Symbol]
@@ -74,8 +74,8 @@ module OMQ
         @peer_connected    = Async::Promise.new
         @all_peers_gone    = Async::Promise.new
         @reconnect_enabled = true
-        @parent_task       = nil
         @on_io_thread      = false
+        @parent_task       = nil
         @barrier           = nil
       end
 
@@ -106,6 +106,7 @@ module OMQ
       #
       def capture_parent_task(parent: nil, linger:)
         return false if @parent_task
+
         if parent
           @parent_task  = parent
         elsif Async::Task.current?
@@ -115,6 +116,7 @@ module OMQ
           @on_io_thread = true
           Reactor.track_linger(linger)
         end
+
         @barrier = Async::Barrier.new(parent: @parent_task)
         transition!(:open)
         true
@@ -134,10 +136,23 @@ module OMQ
       end
 
 
-      # Resolves `all_peers_gone` if we had peers and now have none.
+      # Hard close from any alive state — used by {Engine#stop}'s crash
+      # path, which skips the linger drain. Goes `:open → :closed`
+      # directly when needed.
+      def force_close!
+        transition!(:closed)
+      end
+
+
+      # Resolves `all_peers_gone` once we had peers and the connection map
+      # is empty. Called by {Engine#maybe_resolve_all_peers_gone} after a
+      # teardown removes a peer.
+      #
       # @param connections [Hash] current connection map
-      def resolve_all_peers_gone_if_empty(connections)
-        return unless @peer_connected.resolved? && connections.empty?
+      def maybe_resolve_all_peers_gone(connections)
+        return unless @peer_connected.resolved?
+        return unless connections.empty?
+
         @all_peers_gone.resolve(true)
       end
 
@@ -147,9 +162,11 @@ module OMQ
 
       def transition!(new_state)
         allowed = TRANSITIONS[@state]
+
         unless allowed&.include?(new_state)
           raise InvalidTransition, "#{@state} → #{new_state}"
         end
+
         @state = new_state
       end