zzq 0.1.1 → 0.2.0

data/lib/zzq/client.rb

@@ -1,51 +1,218 @@
 # frozen_string_literal: true
 
-require_relative "socket"
-
 module ZZQ
-  # MQTT client. Owns exactly one MQTT session at a time (possibly
-  # persisted across reconnects), subscriptions, and a QoS tracker for
-  # inflight PUB flows.
+  # An MQTT 3.1.1 or 5.0 client. Calls wait without blocking other fibers
+  # under a fiber scheduler such as Async, and release the GVL in threads.
+  #
+  # Publishing and subscribing work from any fiber or thread. One fiber at
+  # a time receives.
   #
-  # M3 stub: only the constructor and {#build_routing} stand. The
-  # CONNECT/CONNACK handshake and publish/subscribe plumbing come in
-  # M4 / M5.
-  class Client < Socket
-    def build_routing(engine)
-      Routing::Client.new(engine)
+  # @example
+  #   ZZQ::Client.connect("mqtt://localhost", client_id: "reader") do |client|
+  #     client.subscribe("sensors/#", qos: 1)
+  #     client.each { |message| puts "#{message.topic}: #{message.payload}" }
+  #   end
+  class Client
+    OPTIONS = %i[
+      client_id version clean_start keep_alive session_expiry username password will inbox
+      reconnect connect_timeout tls
+    ].freeze
+
+    # Messages a receive takes from the native inbox at once.
+    BATCH = 64
+
+    # Connects a new client. With a block, yields it and closes it after.
+    #
+    # @param endpoint [String] see {#connect}
+    # @param options [Hash] see {#initialize}
+    # @return [Client, Object] the client, or the block's result
+    def self.connect(endpoint, **options, &block)
+      new(**options).connect(endpoint, &block)
     end
 
+    # @param client_id [String] empty lets a v5 broker assign one
+    # @param version [Integer] 5 (default) or 3 for MQTT 3.1.1
+    # @param clean_start [Boolean] start a new session (default true)
+    # @param keep_alive [Integer] seconds, 60 by default
+    # @param session_expiry [Integer] v5 seconds the broker keeps the session
+    # @param username [String, nil]
+    # @param password [String, nil]
+    # @param will [Hash, nil] +topic:+, +payload:+, +qos:+, +retain:+, +delay:+
+    # @param inbox [Integer] messages the client buffers before it stops
+    #   reading, 4096 by default
+    # @param reconnect [Boolean, Hash] reconnect after a loss, optionally
+    #   with +min:+ and +max:+ seconds between attempts
+    # @param connect_timeout [Numeric] seconds, 10 by default
+    # @param tls [Hash, nil] +ca:+, +cert:+, +key:+ (PEM strings),
+    #   +server_name:+, +insecure:+
+    def initialize(**options)
+      @options = Options.check(options, OPTIONS)
+      @native = nil
+      @inbox = []
+      @receiving = false
+      @closed = false
+    end
 
-    # Most recent CONNACK received from the broker, or nil before the
-    # first successful connect.
-    def last_connack     = @engine.routing.last_connack
-    def session_present? = @engine.routing.session_present?
+    # Connects and waits for CONNACK. With a block, yields the client and
+    # closes it after.
+    #
+    # @param endpoint [String] +mqtt://host[:port]+, +mqtts://+, +tcp://+,
+    #   +tls://+, +ws://+, +wss://+, +quic://+, +ipc://+ or +inproc://+
+    # @return [self, Object] the client, or the block's result
+    # @raise [ConnectionRefused] if the broker refuses the connection
+    # @raise [TransportError] if the connection fails
+    def connect(endpoint)
+      raise Error, "already connected" if @native
 
+      @native = Waiting.await(Native::Client.connect(Options.endpoint(endpoint), @options))
+      return self unless block_given?
+
+      begin
+        yield self
+      ensure
+        close
+      end
+    end
+
+    # @return [Boolean] whether the broker resumed a session
+    def session_present?
+      native.session_present?
+    end
 
-    # Publish a message. For QoS 0 returns once the packet is
-    # written. For QoS 1 blocks until PUBACK; for QoS 2 blocks until
-    # PUBCOMP.
-    def publish(topic, payload, qos: 0, retain: false, properties: {})
-      raise NotInAsyncContext unless Async::Task.current?
-      @engine.routing.publish(
-        topic: topic, payload: coerce_binary(payload),
-        qos: qos, retain: retain, properties: properties,
-      )
+    # @return [String, nil] the client ID a v5 broker assigned
+    def assigned_client_id
+      native.assigned_client_id
     end
 
+    # Publishes a message. QoS 0 returns once queued, QoS 1 and 2 once the
+    # broker acked it.
+    #
+    # @param topic [String]
+    # @param payload [String]
+    # @param qos [Integer] 0, 1 or 2
+    # @param retain [Boolean] the broker keeps it for later subscribers;
+    #   an empty payload clears the topic
+    # @return [nil]
+    def publish(topic, payload, qos: 0, retain: false)
+      payload = payload.to_s unless payload.is_a?(String)
+      op = native.publish(topic, payload, qos, retain)
+      Waiting.await(op) if op
+      nil
+    end
 
-    # Subscribe to a topic filter. Returns a {ZZQ::Subscription} whose
-    # queue receives matching messages until it is closed.
+    # Subscribes to a topic filter.
+    #
+    # @param filter [String]
+    # @param qos [Integer] maximum QoS
+    # @param no_local [Boolean] v5: skip this client's own publishes
+    # @param retain_as_published [Boolean] v5: keep the publisher's retain
+    #   flag
+    # @param retain_handling [Integer] v5: 0 send retained messages, 1 only
+    #   for a new subscription, 2 never
+    # @param subscription_id [Integer] v5 Subscription Identifier, 0 for
+    #   none
+    # @return [Integer] the granted QoS
+    # @raise [Rejected] if the broker refuses the filter
     def subscribe(filter, qos: 0, no_local: false, retain_as_published: false,
-                  retain_handling: 0)
-      raise NotInAsyncContext unless Async::Task.current?
-      @engine.routing.subscribe(
-        filter, qos: qos, no_local: no_local,
-        retain_as_published: retain_as_published,
-        retain_handling: retain_handling,
-      )
+                  retain_handling: 0, subscription_id: 0)
+      spec = [filter, qos, no_local, retain_as_published, retain_handling]
+      code = Waiting.await(native.subscribe([spec], subscription_id)).first
+      raise Rejected.new("subscribe to #{filter.inspect} refused", code) if code >= 0x80
+
+      code
+    end
+
+    # Unsubscribes from topic filters.
+    #
+    # @param filters [Array<String>]
+    # @return [nil]
+    # @raise [Rejected] if a v5 broker refuses one
+    def unsubscribe(*filters)
+      codes = Waiting.await(native.unsubscribe(filters.flatten))
+      refused = codes.find { |code| code >= 0x80 }
+      raise Rejected.new("unsubscribe refused", refused) if refused
+
+      nil
+    end
+
+    # Takes the next message, waiting for one.
+    #
+    # @param timeout [Numeric, nil] seconds
+    # @return [Message, nil] nil once the client is closed
+    # @raise [IO::TimeoutError] if no message came within +timeout+
+    def receive(timeout: nil)
+      return @inbox.shift unless @inbox.empty?
+      return nil unless @native
+      raise Error, "another fiber is receiving" if @receiving
+
+      @receiving = true
+      begin
+        next_batch(timeout)
+      ensure
+        @receiving = false
+      end
+    end
+
+    # Yields each message until the client is closed.
+    #
+    # @yieldparam message [Message]
+    # @return [Enumerator, nil] an Enumerator without a block
+    def each
+      return enum_for(:each) unless block_given?
+
+      while (message = receive)
+        yield message
+      end
+    end
+
+    # Sends DISCONNECT and closes. A fiber waiting in {#receive} gets nil.
+    #
+    # @param reason [Integer] v5 reason code; 0x04 asks for the will
+    # @return [nil]
+    def disconnect(reason: 0)
+      return if @closed || @native.nil?
+
+      @closed = true
+      Waiting.await(@native.disconnect(reason))
+      nil
+    end
+
+    # Closes with a normal DISCONNECT.
+    #
+    # @return [nil]
+    def close
+      disconnect
+    end
+
+    # @return [Boolean]
+    def closed?
+      @closed
+    end
+
+    private
+
+    # Waits for messages, keeps them in the inbox and returns the first.
+    def next_batch(timeout)
+      Waiting.with_wake do |wake|
+        limit = Waiting.deadline(timeout)
+        loop do
+          batch = @native.receive(wake, BATCH)
+          return nil if batch.nil?
+
+          if batch.is_a?(Array)
+            @inbox = batch
+            return @inbox.shift
+          end
+          wake.wait(limit)
+        end
+      end
+    end
+
+    def native
+      raise ClosedError, "client closed" if @closed
+      raise ClosedError, "client not connected" unless @native
+
+      @native
     end
   end
 end
-
-require_relative "routing/client"

data/lib/zzq/errors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ZZQ
+  # Base class of zzq errors.
+  class Error < StandardError; end
+
+  # The client or broker is closed, or the connection is gone.
+  class ClosedError < Error; end
+
+  # The endpoint, the connection or TLS failed.
+  class TransportError < Error; end
+
+  # The peer broke the MQTT protocol.
+  class ProtocolError < Error; end
+
+  # A topic name or filter is not valid.
+  class InvalidTopic < Error; end
+
+  # A message or field is larger than MQTT can carry.
+  class TooLarge < Error; end
+
+  # The broker rejected a request, such as a subscription.
+  class Rejected < Error
+    # @return [Integer, nil] MQTT reason code
+    attr_reader :reason_code
+
+    # @param message [String, nil]
+    # @param reason_code [Integer, nil]
+    def initialize(message = nil, reason_code = nil)
+      super(message)
+      @reason_code = reason_code
+    end
+  end
+
+  # The broker refused the connection.
+  class ConnectionRefused < Rejected; end
+end

data/lib/zzq/message.rb

@@ -1,113 +1,22 @@
 # frozen_string_literal: true
 
-require "protocol/mqtt"
-
 module ZZQ
-  # One MQTT application message as delivered to a subscriber or
-  # accepted by {Client#publish} / {Broker#ingest}.
-  #
-  # `Message` is independent of any particular connection: it carries
-  # every wire-level field that a PUBLISH packet does, so it can be
-  # shipped across non-MQTT transports (OMQ, NNQ, a file, a queue) via
-  # {#to_wire} / {.from_wire} and re-injected at the other end.
+  # A received message. The topic is a frozen UTF-8 String and the payload
+  # a frozen binary String.
   #
-  # `#ack!` is only meaningful for QoS 1/2 messages received with
-  # `auto_ack: false` — it sends the appropriate PUBACK/PUBCOMP.
-  class Message
-    attr_reader :topic, :payload, :qos, :retain, :dup, :packet_id, :properties
-
-
-    def initialize(topic:, payload:, qos: 0, retain: false, dup: false,
-                   packet_id: nil, properties: {}, on_ack: nil)
-      @topic      = topic
-      @payload    = payload.b.freeze
-      @qos        = qos
-      @retain     = retain
-      @dup        = dup
-      @packet_id  = packet_id
-      @properties = properties
-      @on_ack     = on_ack
-      @acked      = false
-    end
-
-
-    def ack!
-      return if @qos.zero? || @acked
-      @acked = true
-      @on_ack&.call(self)
-    end
-
-
-    def acked?
-      @acked
-    end
-
-
-    # Encode this message as a self-describing byte string using the
-    # PUBLISH packet codec. The output can be cross-shipped over a
-    # non-MQTT transport and reconstructed via {.from_wire}. v5 wire
-    # format is used so the full property block round-trips.
-    def to_wire
-      packet = to_publish
-      packet.encode(version: 5)
-    end
-
-
-    # Inverse of {#to_wire}. Raises +Protocol::MQTT::MalformedPacket+
-    # if the bytes don't decode as a PUBLISH packet.
-    def self.from_wire(bytes)
-      pkt, consumed = Protocol::MQTT::Packet.decode(bytes, version: 5)
-      raise Protocol::MQTT::MalformedPacket, "expected PUBLISH, got #{pkt.class}" unless pkt.is_a?(Protocol::MQTT::Packet::Publish)
-      raise Protocol::MQTT::MalformedPacket, "trailing bytes after PUBLISH" if consumed != bytes.bytesize
-      from_publish(pkt)
-    end
-
-
-    # Build a PUBLISH packet that represents this message. Used both
-    # internally (for over-the-wire transmission) and by {#to_wire}.
-    def to_publish
-      Protocol::MQTT::Packet::Publish.new(
-        topic:      @topic,
-        payload:    @payload,
-        qos:        @qos,
-        retain:     @retain,
-        dup:        @dup,
-        packet_id:  @packet_id,
-        properties: @properties,
-      )
-    end
-
-
-    # Build a Message from a decoded PUBLISH packet.
-    def self.from_publish(pkt, on_ack: nil)
-      new(
-        topic:      pkt.topic,
-        payload:    pkt.payload,
-        qos:        pkt.qos,
-        retain:     pkt.retain,
-        dup:        pkt.dup,
-        packet_id:  pkt.packet_id,
-        properties: pkt.properties,
-        on_ack:     on_ack,
-      )
-    end
-
-
-    def ==(other)
-      other.is_a?(Message) &&
-        other.topic == @topic &&
-        other.payload == @payload &&
-        other.qos == @qos &&
-        other.retain == @retain &&
-        other.dup == @dup &&
-        other.packet_id == @packet_id &&
-        other.properties == @properties
-    end
-    alias eql? ==
-
-
-    def hash
-      [self.class, @topic, @payload, @qos, @retain, @dup, @packet_id, @properties].hash
-    end
+  # @!attribute [r] topic
+  #   @return [String]
+  # @!attribute [r] payload
+  #   @return [String]
+  # @!attribute [r] qos
+  #   @return [Integer] delivery QoS, 0 to 2
+  # @!attribute [r] retain
+  #   @return [Boolean] a retained message, or the publisher's flag under
+  #     Retain As Published
+  # @!attribute [r] subscription_ids
+  #   @return [Array<Integer>] v5 Subscription Identifiers of the matching
+  #     subscriptions
+  Message = Data.define(:topic, :payload, :qos, :retain, :subscription_ids) do
+    alias_method :retain?, :retain
   end
 end

data/lib/zzq/options.rb

@@ -1,94 +1,35 @@
 # frozen_string_literal: true
 
 module ZZQ
-  # Per-socket configuration. Holds both infrastructure options (linger,
-  # HWMs, reconnect) lifted from NNQ::Options, and MQTT-specific ones
-  # (keepalive, session_expiry, receive_maximum, etc.) that shape the
-  # wire behaviour.
-  #
-  # Clients and brokers share this class; role-irrelevant fields are
-  # simply ignored by the other side.
-  class Options
-    DEFAULT_HWM = 1000
-
-    # --- infrastructure -------------------------------------------------
-    attr_accessor :linger
-    attr_accessor :read_timeout
-    attr_accessor :write_timeout
-    attr_accessor :reconnect_interval
-    attr_accessor :send_hwm
-    attr_accessor :recv_hwm
-
-    # --- MQTT wire ------------------------------------------------------
-    # 3 = MQTT v3.1.1, 5 = MQTT v5.0
-    attr_accessor :version
-
-    # Client identifier. Client-only; required unless empty-id + v5 is
-    # used (server assigns it).
-    attr_accessor :client_id
-
-    # Clean Start (v5) / Clean Session (v3.1.1). When true, any prior
-    # session state for this client id is discarded on CONNECT.
-    attr_accessor :clean_start
-
-    # Keep-alive interval in seconds. The broker will close the
-    # connection after 1.5× this period with no traffic. 0 disables.
-    attr_accessor :keep_alive
-
-    # Session expiry interval (v5 only), in seconds. Only meaningful
-    # when clean_start is false.
-    attr_accessor :session_expiry_interval
-
-    # Maximum outstanding unacknowledged QoS 1/2 messages (v5).
-    attr_accessor :receive_maximum
-
-    # Maximum packet size this peer is willing to accept (v5). nil =
-    # unlimited.
-    attr_accessor :max_packet_size
-
-    # Topic Alias Maximum we advertise (v5).
-    attr_accessor :topic_alias_maximum
-
-    # MQTT username / password (both optional).
-    attr_accessor :username
-    attr_accessor :password
-
-    # Last Will and Testament, client-side. Nil or a Hash of
-    # { topic:, payload:, qos:, retain:, properties: }.
-    attr_accessor :will
-
-    # Broker-side persistence backend. Nil = ephemeral (no durability).
-    # Pass an instance of a {ZZQ::Persistence::Interface} subclass
-    # (e.g. {ZZQ::Persistence::PStore}) to survive process restarts.
-    attr_accessor :persistence
+  # @api private
+  module Options
+    module_function
+
+    # +given+ with String keys, after checking every key is +allowed+.
+    def check(given, allowed)
+      unknown = given.keys - allowed
+      unless unknown.empty?
+        raise ArgumentError, "unknown option#{"s" if unknown.size > 1}: #{unknown.join(", ")}"
+      end
+
+      stringify(given)
+    end
 
+    def stringify(hash)
+      hash.to_h { |key, value| [key.to_s, value.is_a?(Hash) ? stringify(value) : value] }
+    end
 
-    def initialize(
-      linger: Float::INFINITY, send_hwm: DEFAULT_HWM, recv_hwm: DEFAULT_HWM,
-      version: 5, client_id: nil, clean_start: true, keep_alive: 60,
-      session_expiry_interval: 0, receive_maximum: 65_535,
-      max_packet_size: nil, topic_alias_maximum: 0,
-      username: nil, password: nil, will: nil,
-      persistence: nil
-    )
-      @linger                  = linger
-      @read_timeout            = nil
-      @write_timeout           = nil
-      @reconnect_interval      = 0.1
-      @send_hwm                = send_hwm
-      @recv_hwm                = recv_hwm
-      @version                 = version
-      @client_id               = client_id
-      @clean_start             = clean_start
-      @keep_alive              = keep_alive
-      @session_expiry_interval = session_expiry_interval
-      @receive_maximum         = receive_maximum
-      @max_packet_size         = max_packet_size
-      @topic_alias_maximum     = topic_alias_maximum
-      @username                = username
-      @password                = password
-      @will                    = will
-      @persistence             = persistence
+    # +mqtt://+ and +mqtts://+ as the +tcp://+ and +tls://+ endpoints they
+    # name. Other schemes pass through.
+    def endpoint(uri)
+      uri = uri.to_s
+      if uri.start_with?("mqtt://")
+        "tcp://#{uri.delete_prefix("mqtt://")}"
+      elsif uri.start_with?("mqtts://")
+        "tls://#{uri.delete_prefix("mqtts://")}"
+      else
+        uri
+      end
     end
   end
 end

data/lib/zzq/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module ZZQ
-  VERSION = "0.1.1"
+  # Gem version.
+  VERSION = "0.2.0"
 end

data/lib/zzq/waiting.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ZZQ
+  module Native
+    # A pipe a fiber waits on while a Rust future is pending.
+    class Wake
+      # Waits for a wake, raising IO::TimeoutError past +deadline+.
+      #
+      # @param deadline [Float, nil] monotonic clock time
+      def wait(deadline)
+        timeout = deadline && [deadline - Waiting.now, 0].max
+        @io ||= IO.for_fd(fd, autoclose: false)
+        raise IO::TimeoutError, "timed out" unless @io.wait_readable(timeout)
+
+        clear
+      end
+    end
+  end
+
+  # Waits for native ops without blocking other fibers: under a fiber
+  # scheduler only the calling fiber waits, otherwise the thread waits
+  # without holding the GVL.
+  #
+  # @api private
+  module Waiting
+    # Wakes kept for reuse. More are made while more fibers wait at once.
+    WAKES = []
+    KEEP = 64
+
+    module_function
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def deadline(timeout)
+      timeout && now + timeout
+    end
+
+    # Yields a wake for this call's waits.
+    def with_wake
+      wake = WAKES.pop || Native::Wake.new
+      yield wake
+    ensure
+      WAKES.push(wake) if wake && WAKES.size < KEEP
+    end
+
+    # Polls +op+ until it is done and returns its result. An interrupted
+    # wait cancels it.
+    def await(op, timeout = nil)
+      with_wake do |wake|
+        limit = deadline(timeout)
+        loop do
+          result = op.poll(wake)
+          return result unless Native::PENDING.equal?(result)
+
+          wake.wait(limit)
+        end
+      end
+    rescue Exception # rubocop:disable Lint/RescueException
+      op.cancel
+      raise
+    end
+  end
+end

data/lib/zzq.rb

@@ -1,26 +1,29 @@
 # frozen_string_literal: true
 
-# ZZQ — async-native MQTT client and broker for Ruby.
-#
-# Built on `async`, `io-stream`, and `protocol-mqtt`. Applies the
-# omq/nnq architecture (Socket base, Engine, pluggable transports,
-# barrier-scoped lifecycle) to MQTT 3.1.1 and 5.0.
-module ZZQ
-end
+require "io/wait"
 
 require_relative "zzq/version"
-require_relative "zzq/error"
-require_relative "zzq/monitor_event"
-require_relative "zzq/options"
+require_relative "zzq/errors"
 require_relative "zzq/message"
-require_relative "zzq/subscription"
-require_relative "zzq/engine"
-require_relative "zzq/socket"
-require_relative "zzq/transport/mqtt"
-require_relative "zzq/transport/ipc"
-require_relative "zzq/transport/mqtts"
-require_relative "zzq/persistence/interface"
-require_relative "zzq/persistence/memory"
-require_relative "zzq/persistence/pstore"
+require_relative "zzq/zzq_native"
+require_relative "zzq/options"
+require_relative "zzq/waiting"
 require_relative "zzq/client"
 require_relative "zzq/broker"
+
+# MQTT 3.1.1 and 5.0 client and broker, backed by the zzq Rust crates.
+module ZZQ
+  class << self
+    # @return [Integer] IO lanes: threads that run connections
+    def io_threads
+      Native.io_threads
+    end
+
+    # Sets the number of IO lanes, before the first client or broker.
+    #
+    # @param count [Integer]
+    def io_threads=(count)
+      Native.io_threads = count
+    end
+  end
+end