omq 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f11ba4b6d749acef6ad97b6f328aec61aba341ba5759660e23c896af2d96054d
+  data.tar.gz: cf91d6bc140f04d000b5add87322ba9f39ea3b5790f75e4b22144b429284b4c7
+SHA512:
+  metadata.gz: 4ecc0a3992c75679ea9cebd9872bdb7a7c9d3f3e86eaccd82dccc7717a84591c5d8493ab0629b14dfdaea35e30b0bae27c6c142841e2f1c61a04a4ef09805b54
+  data.tar.gz: 7789734d032134883b3ae71ba0af36a7f89d67625d4e879e03f1be81d3ae83b3f1afcda0610bb203ff25a62ecdfac90a4f56b08b5a8127cbab94b1e305261278

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 0.1.0 — 2026-03-25
+
+Initial release. Pure Ruby implementation of ZMTP 3.1 (ZeroMQ) using Async.
+
+### Socket types
+
+- REQ, REP, DEALER, ROUTER
+- PUB, SUB, XPUB, XSUB
+- PUSH, PULL
+- PAIR
+
+### Transports
+
+- TCP (with ephemeral port support and IPv6)
+- IPC (Unix domain sockets, including Linux abstract namespace)
+- inproc (in-process, lock-free direct pipes)
+
+### Features
+
+- Buffered I/O via io-stream (read-ahead buffering, automatic TCP_NODELAY)
+- Heartbeat (PING/PONG) with configurable interval and timeout
+- Automatic reconnection with exponential backoff
+- Per-socket send/receive HWM (high-water mark)
+- Linger on close (drain send queue before closing)
+- `max_message_size` enforcement
+- `connect_timeout` for TCP
+- Works inside Async reactors or standalone (shared IO thread)
+- Optional CURVE encryption via the `omq-curve` gem

data/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-2026, Patrik Wenger
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,145 @@
+# OMQ! Where did the C dependency go?!
+
+[![CI](https://github.com/paddor/omq/actions/workflows/ci.yml/badge.svg)](https://github.com/paddor/omq/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/omq?color=e9573f)](https://rubygems.org/gems/omq)
+[![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)
+
+Pure Ruby implementation of the [ZMTP 3.1](https://rfc.zeromq.org/spec/23/) wire protocol ([ZeroMQ](https://zeromq.org/)) using the [Async](https://github.com/socketry/async) gem. No native libraries required.
+
+> **186k msg/s** inproc throughput | **12 µs** req/rep roundtrip latency | pure Ruby + YJIT
+
+---
+
+## Highlights
+
+- **Pure Ruby** — no C extensions, no FFI, no libzmq/libczmq dependency
+- **All socket types** — req/rep, pub/sub, push/pull, dealer/router, xpub/xsub, pair
+- **Async-native** — built on [Async](https://github.com/socketry/async) fibers, also works with plain threads
+- **Ruby-idiomatic API** — messages as `Array<String>`, errors as exceptions, timeouts as `IO::TimeoutError`
+- **All transports** — tcp, ipc, inproc
+
+## Why pure Ruby?
+
+Modern Ruby has closed the gap:
+
+- **YJIT** — JIT-compiled hot paths close the throughput gap with C extensions
+- **Fiber Scheduler** — non-blocking I/O without callbacks or threads (`Async` builds on this)
+- **`IO::Buffer`** — zero-copy binary reads/writes, no manual `String#b` packing
+
+When [CZTop](https://github.com/paddor/cztop) was written, none of this existed. Today, a pure Ruby ZMTP implementation is fast enough for production use — and you get `gem install` with no compiler toolchain, no system packages, and no segfaults.
+
+## Install
+
+No system libraries needed — just Ruby:
+
+```sh
+gem install omq
+# or in Gemfile
+gem 'omq'
+```
+
+## Learning ZeroMQ
+
+New to ZeroMQ? See [ZGUIDE_SUMMARY.md](ZGUIDE_SUMMARY.md) — a ~30 min read covering all major patterns with working OMQ code examples.
+
+## Quick Start
+
+### Request / Reply
+
+```ruby
+require 'omq'
+require 'async'
+
+Async do |task|
+  rep = OMQ::REP.bind('inproc://example')
+  req = OMQ::REQ.connect('inproc://example')
+
+  task.async do
+    msg = rep.receive
+    rep << msg.map(&:upcase)
+  end
+
+  req << 'hello'
+  puts req.receive.inspect  # => ["HELLO"]
+ensure
+  req&.close
+  rep&.close
+end
+```
+
+### Pub / Sub
+
+```ruby
+Async do |task|
+  pub = OMQ::PUB.bind('inproc://pubsub')
+  sub = OMQ::SUB.connect('inproc://pubsub')
+  sub.subscribe('')  # subscribe to all
+
+  task.async { pub << 'news flash' }
+  puts sub.receive.inspect  # => ["news flash"]
+ensure
+  pub&.close
+  sub&.close
+end
+```
+
+### Push / Pull (Pipeline)
+
+```ruby
+Async do
+  push = OMQ::PUSH.connect('inproc://pipeline')
+  pull = OMQ::PULL.bind('inproc://pipeline')
+
+  push << 'work item'
+  puts pull.receive.inspect  # => ["work item"]
+ensure
+  push&.close
+  pull&.close
+end
+```
+
+## Socket Types
+
+| Pattern | Classes | Direction |
+|---------|---------|-----------|
+| Request/Reply | `REQ`, `REP` | bidirectional |
+| Publish/Subscribe | `PUB`, `SUB`, `XPUB`, `XSUB` | unidirectional |
+| Pipeline | `PUSH`, `PULL` | unidirectional |
+| Routing | `DEALER`, `ROUTER` | bidirectional |
+| Exclusive pair | `PAIR` | bidirectional |
+
+All classes live under `OMQ::`.
+
+## Performance
+
+Benchmarked with benchmark-ips on Linux x86_64 (Ruby 4.0.1 +YJIT):
+
+#### Throughput (push/pull, 64 B messages)
+
+| inproc | ipc | tcp |
+|--------|-----|-----|
+| 184k/s | 35k/s | 18k/s |
+
+#### Latency (req/rep roundtrip)
+
+| inproc | ipc | tcp |
+|--------|-----|-----|
+| 13 µs | 70 µs | 97 µs |
+
+See [`bench/`](bench/) for full results and scripts.
+
+## Interop with native ZMQ
+
+OMQ speaks ZMTP 3.1 on the wire and interoperates with libzmq, CZMQ, pyzmq, etc. over **tcp** and **ipc**. The `inproc://` transport is OMQ-internal (in-process Ruby queues) and is not visible to native ZMQ running in the same process — use `ipc://` to talk across library boundaries.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+```
+
+## License
+
+[ISC](LICENSE)

data/lib/omq/pair.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module OMQ
+  class PAIR < Socket
+    include ZMTP::Readable
+    include ZMTP::Writable
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:PAIR, linger: linger)
+      _attach(endpoints, default: :connect)
+    end
+  end
+end

data/lib/omq/pub_sub.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module OMQ
+  class PUB < Socket
+    include ZMTP::Writable
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:PUB, linger: linger)
+      _attach(endpoints, default: :bind)
+    end
+  end
+
+  # SUB socket.
+  #
+  class SUB < Socket
+    include ZMTP::Readable
+
+    # @return [String] subscription prefix to subscribe to everything
+    #
+    EVERYTHING = ''
+
+    # @param endpoints [String, nil]
+    # @param linger [Integer]
+    # @param prefix [String, nil] subscription prefix; +nil+ (default)
+    #   means no subscription — call {#subscribe} explicitly.
+    #
+    def initialize(endpoints = nil, linger: 0, prefix: nil)
+      _init_engine(:SUB, linger: linger)
+      _attach(endpoints, default: :connect)
+      subscribe(prefix) unless prefix.nil?
+    end
+
+    # Subscribes to a topic prefix.
+    #
+    # @param prefix [String]
+    # @return [void]
+    #
+    def subscribe(prefix = EVERYTHING)
+      @engine.routing.subscribe(prefix)
+    end
+
+    # Unsubscribes from a topic prefix.
+    #
+    # @param prefix [String]
+    # @return [void]
+    #
+    def unsubscribe(prefix)
+      @engine.routing.unsubscribe(prefix)
+    end
+  end
+
+  class XPUB < Socket
+    include ZMTP::Readable
+    include ZMTP::Writable
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:XPUB, linger: linger)
+      _attach(endpoints, default: :bind)
+    end
+  end
+
+  class XSUB < Socket
+    include ZMTP::Readable
+    include ZMTP::Writable
+
+    # @param endpoints [String, nil]
+    # @param linger [Integer]
+    # @param prefix [String, nil] subscription prefix; +nil+ (default)
+    #   means no subscription — send a subscribe frame explicitly.
+    #
+    def initialize(endpoints = nil, linger: 0, prefix: nil)
+      _init_engine(:XSUB, linger: linger)
+      _attach(endpoints, default: :connect)
+      send("\x01#{prefix}".b) unless prefix.nil?
+    end
+  end
+end

data/lib/omq/push_pull.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module OMQ
+  class PUSH < Socket
+    include ZMTP::Writable
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:PUSH, linger: linger)
+      _attach(endpoints, default: :connect)
+    end
+  end
+
+  class PULL < Socket
+    include ZMTP::Readable
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:PULL, linger: linger)
+      _attach(endpoints, default: :bind)
+    end
+  end
+end

data/lib/omq/req_rep.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OMQ
+  class REQ < Socket
+    include ZMTP::Readable
+    include ZMTP::Writable
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:REQ, linger: linger)
+      _attach(endpoints, default: :connect)
+    end
+  end
+
+  class REP < Socket
+    include ZMTP::Readable
+    include ZMTP::Writable
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:REP, linger: linger)
+      _attach(endpoints, default: :bind)
+    end
+  end
+end

data/lib/omq/router_dealer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module OMQ
+  class DEALER < Socket
+    include ZMTP::Readable
+    include ZMTP::Writable
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:DEALER, linger: linger)
+      _attach(endpoints, default: :connect)
+    end
+  end
+
+  # ROUTER socket.
+  #
+  class ROUTER < Socket
+    include ZMTP::Readable
+    include ZMTP::Writable
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:ROUTER, linger: linger)
+      _attach(endpoints, default: :bind)
+    end
+
+    # Sends a message to a specific peer by identity.
+    #
+    # @param receiver [String] peer identity
+    # @param message [String, Array<String>]
+    # @return [self]
+    #
+    def send_to(receiver, message)
+      parts = message.is_a?(Array) ? message : [message]
+      send([receiver, '', *parts])
+    end
+  end
+end

data/lib/omq/socket.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module OMQ
+  # Socket base class.
+  #
+  class Socket
+    # @return [ZMTP::Options]
+    #
+    attr_reader :options
+
+    # @return [Integer, nil] last auto-selected TCP port
+    #
+    attr_reader :last_tcp_port
+
+    # Delegate socket option accessors to @options.
+    #
+    %i[
+      send_hwm                send_hwm=
+      recv_hwm                recv_hwm=
+      linger                  linger=
+      identity                identity=
+      recv_timeout            recv_timeout=
+      send_timeout            send_timeout=
+      read_timeout            read_timeout=
+      write_timeout           write_timeout=
+      router_mandatory        router_mandatory=
+      router_mandatory?
+      reconnect_interval      reconnect_interval=
+      heartbeat_interval      heartbeat_interval=
+      heartbeat_ttl           heartbeat_ttl=
+      heartbeat_timeout       heartbeat_timeout=
+      max_message_size        max_message_size=
+      connect_timeout         connect_timeout=
+      mechanism               mechanism=
+      curve_server            curve_server=
+      curve_server_key        curve_server_key=
+      curve_public_key        curve_public_key=
+      curve_secret_key        curve_secret_key=
+      curve_authenticator     curve_authenticator=
+    ].each do |method|
+      define_method(method) { |*args| @options.public_send(method, *args) }
+    end
+
+    # Creates a new socket and binds it to the given endpoint.
+    #
+    # @param endpoint [String]
+    # @param opts [Hash] keyword arguments forwarded to {#initialize}
+    # @return [Socket]
+    #
+    def self.bind(endpoint, **opts)
+      new(nil, **opts).tap { |s| s.bind(endpoint) }
+    end
+
+    # Creates a new socket and connects it to the given endpoint.
+    #
+    # @param endpoint [String]
+    # @param opts [Hash] keyword arguments forwarded to {#initialize}
+    # @return [Socket]
+    #
+    def self.connect(endpoint, **opts)
+      new(nil, **opts).tap { |s| s.connect(endpoint) }
+    end
+
+    def initialize(endpoints = nil, linger: 0); end
+
+    # Binds to an endpoint.
+    #
+    # @param endpoint [String]
+    # @return [void]
+    #
+    def bind(endpoint)
+      @engine.bind(endpoint)
+      @last_tcp_port = @engine.last_tcp_port
+    end
+
+    # Connects to an endpoint.
+    #
+    # @param endpoint [String]
+    # @return [void]
+    #
+    def connect(endpoint)
+      @engine.connect(endpoint)
+    end
+
+    # Disconnects from an endpoint.
+    #
+    # @param endpoint [String]
+    # @return [void]
+    #
+    def disconnect(endpoint)
+      @engine.disconnect(endpoint)
+    end
+
+    # Unbinds from an endpoint.
+    #
+    # @param endpoint [String]
+    # @return [void]
+    #
+    def unbind(endpoint)
+      @engine.unbind(endpoint)
+    end
+
+    # @return [String, nil] last bound endpoint
+    #
+    def last_endpoint
+      @engine.last_endpoint
+    end
+
+    # Closes the socket.
+    #
+    # @return [void]
+    #
+    def close
+      @engine.close
+      nil
+    end
+
+    # Set socket to use unbounded pipes (HWM=0).
+    #
+    def set_unbounded
+      @options.send_hwm = 0
+      @options.recv_hwm = 0
+      nil
+    end
+
+    # @return [String]
+    #
+    def inspect
+      format("#<%s last_endpoint=%p>", self.class, last_endpoint)
+    end
+
+    private
+
+    # Runs a block with a timeout. Uses Async's with_timeout if inside
+    # a reactor, otherwise falls back to Timeout.timeout.
+    #
+    # @param seconds [Numeric]
+    # @raise [IO::TimeoutError]
+    #
+    def with_timeout(seconds, &block)
+      return yield if seconds.nil?
+      if Async::Task.current?
+        Async::Task.current.with_timeout(seconds, &block)
+      else
+        Timeout.timeout(seconds, &block)
+      end
+    rescue Async::TimeoutError, Timeout::Error
+      raise IO::TimeoutError, "timed out"
+    end
+
+    # Connects or binds based on endpoint prefix convention.
+    #
+    # @param endpoints [String, nil]
+    # @param default [Symbol] :connect or :bind
+    #
+    def _attach(endpoints, default:)
+      return unless endpoints
+      case endpoints
+      when /\A@(.+)\z/
+        bind($1)
+      when /\A>(.+)\z/
+        connect($1)
+      else
+        __send__(default, endpoints)
+      end
+    end
+
+    # Initializes engine and options for a socket type.
+    #
+    # @param socket_type [Symbol]
+    # @param linger [Integer]
+    #
+    def _init_engine(socket_type, linger:)
+      @options = ZMTP::Options.new(linger: linger)
+      @engine  = ZMTP::Engine.new(socket_type, @options)
+    end
+  end
+end

data/lib/omq/version.rb

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