zzq 0.1.0 → 0.2.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zzq
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Patrik Wenger
@@ -10,104 +10,60 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: async
+  name: rb_sys
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.38'
+        version: '0.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.38'
-- !ruby/object:Gem::Dependency
-  name: io-stream
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.11'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.11'
-- !ruby/object:Gem::Dependency
-  name: protocol-mqtt
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.1.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.1.0
-- !ruby/object:Gem::Dependency
-  name: pstore
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
-description: Pure Ruby implementation of MQTT — client and broker in one gem — built
-  on async, io-stream, and protocol-mqtt. Fiber-first, pluggable transports (tcp,
-  tls, ws, ipc), pluggable persistence (in-memory, PStore).
+        version: '0.9'
+description: 'Ruby binding for zzq: an MQTT 3.1.1 and 5.0 client and broker with an
+  MQTT-SN gateway, running on Rust IO threads. Works in threads and under fiber schedulers
+  such as Async.'
 email:
 - paddor@gmail.com
 executables: []
-extensions: []
+extensions:
+- ext/zzq_native/extconf.rb
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- LICENSE
+- LICENSE-APACHE
+- LICENSE-ISC
 - README.md
+- ext/zzq_native/Cargo.toml
+- ext/zzq_native/extconf.rb
+- ext/zzq_native/src/broker.rs
+- ext/zzq_native/src/client.rs
+- ext/zzq_native/src/context.rs
+- ext/zzq_native/src/error.rs
+- ext/zzq_native/src/lib.rs
+- ext/zzq_native/src/op.rs
+- ext/zzq_native/src/options.rs
+- ext/zzq_native/src/rb.rs
+- ext/zzq_native/src/wake.rs
 - lib/zzq.rb
 - lib/zzq/broker.rb
 - lib/zzq/client.rb
-- lib/zzq/engine.rb
-- lib/zzq/engine/connection_lifecycle.rb
-- lib/zzq/engine/keepalive.rb
-- lib/zzq/engine/socket_lifecycle.rb
-- lib/zzq/error.rb
+- lib/zzq/errors.rb
 - lib/zzq/message.rb
-- lib/zzq/monitor_event.rb
 - lib/zzq/options.rb
-- lib/zzq/persistence/interface.rb
-- lib/zzq/persistence/memory.rb
-- lib/zzq/persistence/pstore.rb
-- lib/zzq/routing/broker.rb
-- lib/zzq/routing/client.rb
-- lib/zzq/routing/packet_id_allocator.rb
-- lib/zzq/routing/qos_tracker.rb
-- lib/zzq/routing/retained_store.rb
-- lib/zzq/routing/topic_match.rb
-- lib/zzq/routing/topic_trie.rb
-- lib/zzq/socket.rb
-- lib/zzq/subscription.rb
-- lib/zzq/transport/ipc.rb
-- lib/zzq/transport/mqtt.rb
-- lib/zzq/transport/mqtts.rb
 - lib/zzq/version.rb
-homepage: https://github.com/paddor/zzq
+- lib/zzq/waiting.rb
+homepage: https://github.com/paddor/zzq/tree/main/bindings/ruby
 licenses:
 - ISC
-metadata: {}
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/paddor/zzq/tree/main/bindings/ruby
+  changelog_uri: https://github.com/paddor/zzq/tree/main/bindings/ruby/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -115,14 +71,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '4.0'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Pure Ruby MQTT 3.1.1 + 5.0 client and broker on Async
+summary: MQTT 3.1.1 and 5.0 client and broker for Ruby, backed by Rust
 test_files: []

data/LICENSE

@@ -1,13 +0,0 @@
-Copyright (c) 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/lib/zzq/engine/connection_lifecycle.rb

@@ -1,139 +0,0 @@
-# frozen_string_literal: true
-
-require "async/barrier"
-require "protocol/mqtt"
-
-module ZZQ
-  class Engine
-    # Owns the full arc of one connection: new → handshaking → ready →
-    # closed. Centralises side-effect ordering so routing doesn't have
-    # to.
-    #
-    # The MQTT CONNECT/CONNACK exchange itself is NOT performed here —
-    # it's role-asymmetric (client writes CONNECT first, broker reads
-    # it first) and so lives in the role's routing layer, which calls
-    # +handshake_succeeded!+ once the exchange is done.
-    #
-    #   new → handshaking → ready → closed
-    #
-    # #lost! / #close! are idempotent.
-    class ConnectionLifecycle
-      class InvalidTransition < RuntimeError; end
-
-      STATES = %i[new handshaking ready closed].freeze
-
-      TRANSITIONS = {
-        new:         %i[handshaking ready closed].freeze,
-        handshaking: %i[ready closed].freeze,
-        ready:       %i[closed].freeze,
-        closed:      [].freeze,
-      }.freeze
-
-
-      attr_reader :conn       # Protocol::MQTT::Connection
-      attr_reader :endpoint
-      attr_reader :state
-      attr_reader :barrier
-
-
-      def initialize(engine, endpoint:)
-        @engine   = engine
-        @endpoint = endpoint
-        @state    = :new
-        @conn     = nil
-        @barrier  = Async::Barrier.new(parent: engine.barrier)
-      end
-
-
-      # Wraps the accepted/connected IO in a Protocol::MQTT::Connection
-      # and returns it. The handshake itself (CONNECT/CONNACK exchange)
-      # is driven by the routing layer — this is "transport ready,
-      # MQTT handshake pending".
-      def begin_handshake!(io)
-        transition!(:handshaking)
-        mqtt = Protocol::MQTT::Connection.new(
-          io,
-          version: @engine.options.version,
-          max_packet_size: @engine.options.max_packet_size,
-        )
-        @conn = mqtt
-        mqtt
-      end
-
-
-      # Called by the routing layer after CONNECT/CONNACK succeeds.
-      def handshake_succeeded!
-        @engine.connections[@conn] = self
-        transition!(:ready)
-        begin
-          @engine.routing.connection_added(@conn) if @engine.routing.respond_to?(:connection_added)
-        rescue ConnectionRejected
-          @engine.emit_monitor_event(:connection_rejected, endpoint: @endpoint)
-          tear_down!(reconnect: false)
-          raise
-        end
-        @engine.lifecycle.peer_connected.resolve(@conn) unless @engine.lifecycle.peer_connected.resolved?
-        @engine.emit_monitor_event(:connected, endpoint: @endpoint)
-      end
-
-
-      # Called on handshake failure — e.g. refused CONNACK, RST mid-
-      # CONNECT. Tears down and requests a reconnect if eligible.
-      def handshake_failed!(error:)
-        @engine.emit_monitor_event(:handshake_failed, endpoint: @endpoint, detail: { error: error })
-        @conn&.close rescue nil
-        tear_down!(reconnect: true)
-      end
-
-
-      # Unexpected loss of an established connection.
-      def lost!
-        tear_down!(reconnect: true)
-      end
-
-
-      # Deliberate close (engine shutdown, kicked by broker, …).
-      def close!
-        tear_down!(reconnect: false)
-      end
-
-
-      # Starts a supervisor task that tears down when any pump exits.
-      def start_supervisor!
-        return if @barrier.empty?
-        @engine.barrier.async(transient: true, annotation: "zzq conn supervisor") do
-          @barrier.wait { |task| task.wait; break }
-        rescue Async::Stop, Async::Cancel
-        rescue *CONNECTION_LOST
-        ensure
-          lost!
-        end
-      end
-
-
-      private def tear_down!(reconnect: false)
-        return if @state == :closed
-        transition!(:closed)
-        if @conn
-          @engine.connections.delete(@conn)
-          @engine.routing.connection_removed(@conn) if @engine.routing.respond_to?(:connection_removed)
-          @conn.close rescue nil
-          @engine.emit_monitor_event(:disconnected, endpoint: @endpoint)
-          @engine.resolve_all_peers_gone_if_empty
-        end
-        @engine.maybe_reconnect(@endpoint) if reconnect
-        # Stop after cleanup: when tear_down! is called from a task on
-        # this barrier (e.g. the read-loop's ensure), stopping earlier
-        # would cancel the current fiber mid-cleanup.
-        @barrier.stop
-      end
-
-
-      private def transition!(new_state)
-        allowed = TRANSITIONS[@state]
-        raise InvalidTransition, "#{@state} → #{new_state}" unless allowed&.include?(new_state)
-        @state = new_state
-      end
-    end
-  end
-end

data/lib/zzq/engine/keepalive.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-require "async"
-require "async/clock"
-require "protocol/mqtt"
-
-module ZZQ
-  class Engine
-    # Keepalive driver for a single connection.
-    #
-    # +role+:
-    #   * +:sender+ (client default) — sends PINGREQ if locally idle
-    #     for keep_alive/2; closes if nothing received for 1.5 × keep_alive.
-    #   * +:watcher+ (broker default) — does not send; just closes if
-    #     nothing received for 1.5 × keep_alive. MQTT-3.1.2-22 is
-    #     enforced by the broker.
-    #
-    # One fiber per connection, attached to the connection's barrier
-    # so it tears down with the connection.
-    class Keepalive
-      attr_accessor :last_sent_at, :last_received_at
-
-
-      def initialize(conn, keep_alive:, on_timeout:, role: :sender)
-        @conn = conn
-        @keep_alive = keep_alive
-        @on_timeout = on_timeout
-        @role = role
-        now = Async::Clock.now
-        @last_sent_at = now
-        @last_received_at = now
-      end
-
-
-      # Call this every time a packet is written, to reset the send-idle
-      # timer.
-      def note_sent
-        @last_sent_at = Async::Clock.now
-      end
-
-
-      # Call this every time a packet is read, to reset the recv-idle
-      # timer.
-      def note_received
-        @last_received_at = Async::Clock.now
-      end
-
-
-      def run
-        return if @keep_alive.zero?  # 0 disables keepalive
-        loop do
-          sleep(@keep_alive / 2.0)
-          now = Async::Clock.now
-
-          if (now - @last_received_at) > (@keep_alive * 1.5)
-            @on_timeout.call
-            break
-          end
-
-          next unless @role == :sender
-
-          if (now - @last_sent_at) >= (@keep_alive / 2.0)
-            begin
-              @conn.write_packet(Protocol::MQTT::Packet::Pingreq.new)
-              note_sent
-            rescue IOError, Errno::EPIPE, Errno::ECONNRESET
-              break
-            end
-          end
-        end
-      rescue Async::Stop
-      end
-    end
-  end
-end

data/lib/zzq/engine/socket_lifecycle.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-require "async/barrier"
-require "async/promise"
-
-module ZZQ
-  class Engine
-    # Owns the socket-level state: `:new → :open → :closing → :closed`.
-    #
-    # Adapted from NNQ::Engine::SocketLifecycle, minus the shared-IO-
-    # thread fallback (ZZQ is pure-Async).
-    class SocketLifecycle
-      class InvalidTransition < RuntimeError; end
-
-      STATES = %i[new open closing closed].freeze
-
-      TRANSITIONS = {
-        new:     %i[open closed].freeze,
-        open:    %i[closing closed].freeze,
-        closing: %i[closed].freeze,
-        closed:  [].freeze,
-      }.freeze
-
-
-      attr_reader :state
-      attr_reader :parent_task
-      attr_reader :peer_connected
-      attr_reader :all_peers_gone
-      attr_reader :barrier
-      attr_accessor :reconnect_enabled
-
-
-      def initialize
-        @state             = :new
-        @parent_task       = nil
-        @peer_connected    = Async::Promise.new
-        @all_peers_gone    = Async::Promise.new
-        @reconnect_enabled = true
-        @barrier           = nil
-      end
-
-
-      def open?    = @state == :open
-      def closing? = @state == :closing
-      def closed?  = @state == :closed
-      def alive?   = @state == :new || @state == :open
-
-
-      # Must be called from within an Async::Task. Raises
-      # NotInAsyncContext otherwise.
-      def capture_parent_task
-        return false if @parent_task
-        task = Async::Task.current? or raise NotInAsyncContext
-        @parent_task = task
-        @barrier = Async::Barrier.new(parent: @parent_task)
-        transition!(:open)
-        true
-      end
-
-
-      def start_closing!  = transition!(:closing)
-      def finish_closing! = transition!(:closed)
-
-
-      def resolve_all_peers_gone_if_empty(connections)
-        return unless @peer_connected.resolved? && connections.empty?
-        return if @all_peers_gone.resolved?
-        @all_peers_gone.resolve(true)
-      end
-
-
-      private def transition!(new_state)
-        allowed = TRANSITIONS[@state]
-        raise InvalidTransition, "#{@state} → #{new_state}" unless allowed&.include?(new_state)
-        @state = new_state
-      end
-    end
-  end
-end

data/lib/zzq/engine.rb

@@ -1,163 +0,0 @@
-# frozen_string_literal: true
-
-require "async"
-require "async/clock"
-require "set"
-require_relative "error"
-require_relative "engine/socket_lifecycle"
-require_relative "engine/connection_lifecycle"
-
-module ZZQ
-  # Per-socket orchestrator. Owns listeners, the connection map, the
-  # transport registry, and the socket-level state machine. Adapted
-  # from NNQ::Engine minus reactor / inproc / SP-handshake concerns.
-  class Engine
-    # Scheme → transport module registry. Populated by each transport
-    # file on require.
-    @transports = {}
-
-
-    class << self
-      attr_reader :transports
-    end
-
-
-    attr_reader :options
-    attr_reader :routing
-    attr_reader :connections  # Hash{Protocol::MQTT::Connection => ConnectionLifecycle}
-    attr_reader :lifecycle
-    attr_reader :last_endpoint
-    attr_reader :dialed
-    attr_accessor :monitor_queue
-
-
-    # @yieldparam engine [Engine] build_routing hook; returns the
-    #   role-specific routing strategy.
-    def initialize(options:)
-      @options       = options
-      @connections   = {}
-      @listeners     = []
-      @lifecycle     = SocketLifecycle.new
-      @last_endpoint = nil
-      @monitor_queue = nil
-      @dialed        = Set.new
-      @dial_opts     = {}
-      @routing       = yield(self)
-    end
-
-
-    def emit_monitor_event(type, endpoint: nil, detail: nil)
-      return unless @monitor_queue
-      @monitor_queue.enqueue(MonitorEvent.new(type: type, endpoint: endpoint, detail: detail))
-    rescue Async::Stop
-    end
-
-
-    def parent_task   = @lifecycle.parent_task
-    def barrier       = @lifecycle.barrier
-    def closed?       = @lifecycle.closed?
-    def peer_connected = @lifecycle.peer_connected
-    def all_peers_gone = @lifecycle.all_peers_gone
-
-
-    def resolve_all_peers_gone_if_empty
-      @lifecycle.resolve_all_peers_gone_if_empty(@connections)
-    end
-
-
-    # Must be called from inside an Async::Task.
-    def capture_parent_task
-      @lifecycle.capture_parent_task
-    end
-
-
-    # Bind (listener) — role-agnostic. The routing layer (on accept)
-    # drives the MQTT handshake.
-    def bind(endpoint, **opts)
-      transport = transport_for(endpoint)
-      listener  = transport.bind(endpoint, self, **opts)
-      listener.start_accept_loop(@lifecycle.barrier) do |io|
-        handle_accepted(io, endpoint: endpoint)
-      end
-      @listeners << listener
-      @last_endpoint = listener.endpoint
-      emit_monitor_event(:listening, endpoint: @last_endpoint)
-    end
-
-
-    # Connect (dialer).
-    def connect(endpoint, **opts)
-      @dialed << endpoint
-      @dial_opts[endpoint] = opts unless opts.empty?
-      @last_endpoint = endpoint
-      transport_for(endpoint).connect(endpoint, self, **opts)
-    end
-
-
-    def dial_opts_for(endpoint)
-      @dial_opts[endpoint] || {}
-    end
-
-
-    def maybe_reconnect(endpoint)
-      # Reconnect loop not wired up yet (M4 job).
-    end
-
-
-    def transport_for(endpoint)
-      scheme = endpoint[/\A([a-z+]+):\/\//i, 1] or raise Error, "no scheme: #{endpoint}"
-      Engine.transports[scheme] or raise Error, "unsupported transport: #{scheme}"
-    end
-
-
-    # Called by transports for each accepted connection. Hands off to
-    # routing so the broker can read CONNECT / write CONNACK.
-    def handle_accepted(io, endpoint:)
-      lifecycle = ConnectionLifecycle.new(self, endpoint: endpoint)
-      mqtt = lifecycle.begin_handshake!(io)
-      @routing.handle_accepted(mqtt, lifecycle) if @routing.respond_to?(:handle_accepted)
-    rescue => e
-      lifecycle.handshake_failed!(error: e)
-      raise unless e.is_a?(ConnectionRejected) || CONNECTION_LOST.any? { |c| e.is_a?(c) }
-    end
-
-
-    # Called by transports for each dialed connection. Hands off to
-    # routing so the client can write CONNECT / read CONNACK.
-    def handle_connected(io, endpoint:)
-      lifecycle = ConnectionLifecycle.new(self, endpoint: endpoint)
-      mqtt = lifecycle.begin_handshake!(io)
-      @routing.handle_connected(mqtt, lifecycle) if @routing.respond_to?(:handle_connected)
-    rescue => e
-      lifecycle.handshake_failed!(error: e)
-      raise unless e.is_a?(ConnectionRejected) || CONNECTION_LOST.any? { |c| e.is_a?(c) }
-    end
-
-
-    def spawn_task(annotation:, parent: @lifecycle.barrier, &block)
-      parent.async(annotation: annotation, &block)
-    end
-
-
-    def close
-      return unless @lifecycle.alive?
-
-      @lifecycle.start_closing!
-      @listeners.each(&:stop)
-      @routing.close if @routing.respond_to?(:close)
-      @connections.values.each(&:close!)
-
-      emit_monitor_event(:closed)
-      @monitor_queue&.enqueue(nil)
-
-      @lifecycle.barrier&.stop
-      @lifecycle.finish_closing!
-      @lifecycle.peer_connected.resolve(nil) unless @lifecycle.peer_connected.resolved?
-    end
-
-
-    def handle_connection_lost(conn)
-      @connections[conn]&.lost!
-    end
-  end
-end

data/lib/zzq/error.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module ZZQ
-  class Error < StandardError; end
-
-  # Raised when sending on or interacting with a closed socket.
-  class ClosedError < Error; end
-
-  # Raised when the routing layer refuses to accept a peer (e.g. a
-  # duplicate client id collision on the broker).
-  class ConnectionRejected < Error; end
-
-  # Raised when a socket method is called outside an Async::Task. ZZQ
-  # is fiber-first: wrap calls in `Async do ... end` or use the block
-  # form of #connect / #bind.
-  class NotInAsyncContext < Error
-    def initialize(msg = "ZZQ socket methods must run inside an Async task. " \
-                         "Wrap in `Async do ... end`, or use the block form " \
-                         "of #connect/#bind.")
-      super
-    end
-  end
-
-  # Server responded with a non-success CONNACK.
-  class ConnectionRefused < Error
-    attr_reader :reason_code
-
-    def initialize(reason_code, message = nil)
-      @reason_code = reason_code
-      super(message || "broker refused connect: reason=0x#{reason_code.to_s(16)}")
-    end
-  end
-
-  # Authentication failed.
-  class AuthFailed < Error; end
-
-  # Network errors that indicate the connection is gone.
-  CONNECTION_LOST = [
-    Errno::ECONNRESET, Errno::EPIPE, Errno::ENOTCONN, Errno::ECONNABORTED,
-    Errno::EBADF, EOFError, IOError
-  ].freeze
-end

data/lib/zzq/monitor_event.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-module ZZQ
-  # A single event emitted by a Socket's #monitor task. Event types
-  # cover both infrastructure lifecycle (:listening, :connected,
-  # :disconnected, :closed) and MQTT semantics (:session_resumed,
-  # :session_expired, :retained_updated, :publish_delivered,
-  # :will_published).
-  MonitorEvent = Data.define(:type, :endpoint, :detail) do
-    def initialize(type:, endpoint: nil, detail: nil)
-      super
-    end
-  end
-end