zzq 0.1.0

data/lib/zzq/routing/broker.rb

@@ -0,0 +1,380 @@
+# frozen_string_literal: true
+
+require "async"
+require "securerandom"
+require "protocol/mqtt"
+require_relative "../engine/keepalive"
+require_relative "../message"
+require_relative "packet_id_allocator"
+require_relative "qos_tracker"
+require_relative "retained_store"
+require_relative "topic_match"
+require_relative "topic_trie"
+
+module ZZQ
+  module Routing
+    # Broker-side routing.
+    #
+    # Current scope:
+    #   * Read CONNECT, send CONNACK.
+    #   * Per-connection read loop: PINGREQ/PINGRESP, DISCONNECT,
+    #     PUBLISH fan-out to matching sessions (QoS 0/1/2), SUBSCRIBE /
+    #     UNSUBSCRIBE with SUBACK / UNSUBACK, and PUBACK/PUBREC/PUBREL/
+    #     PUBCOMP to drive outbound QoS state per session.
+    #   * Simple linear session map; proper topic trie + retained store
+    #     come in M7.
+    class Broker
+      CONNECT_TIMEOUT = 10  # seconds to wait for the initial CONNECT
+
+
+      Session = Struct.new(
+        :client_id, :conn, :subscriptions, :packet_ids, :qos_tracker,
+        :will, :keepalive, :clean_disconnect,
+        keyword_init: true,
+      )
+
+
+      def initialize(engine)
+        @engine     = engine
+        @sessions   = {}  # client_id  => Session
+        @by_conn    = {}  # Connection => Session
+        @trie       = TopicTrie.new
+        @retained   = RetainedStore.new(persistence: engine.options.persistence)
+      end
+
+
+      def handle_accepted(mqtt, lifecycle)
+        connect = nil
+        Async::Task.current.with_timeout(CONNECT_TIMEOUT) do
+          connect = mqtt.read_connect_packet
+          raise ConnectionRejected, "no CONNECT received" if connect.nil?
+
+          client_id = connect.client_id
+          if client_id.empty? && mqtt.version == 3 && !connect.clean_start
+            write_connack(mqtt, reason: Protocol::MQTT::ReasonCodes::V3Connack::IDENTIFIER_REJECTED)
+            raise ConnectionRejected, "empty ClientId with clean_session=false is illegal in v3"
+          end
+          assigned = client_id.empty?
+          client_id = generate_client_id if assigned
+
+          # v5 Receive Maximum: client advertises the max number of
+          # outstanding QoS > 0 publishes it is willing to accept. Sized
+          # on the packet-id allocator used for fan-out to this session.
+          client_rcv_max = connect.properties[:receive_maximum] || 65_535
+          session = build_session(client_id, mqtt, will: connect.will,
+                                   receive_maximum: client_rcv_max)
+          @sessions[client_id] = session
+          @by_conn[mqtt] = session
+
+          write_connack(mqtt, reason: 0, assigned_client_id: assigned ? client_id : nil)
+        end
+
+        lifecycle.handshake_succeeded!
+        start_read_loop(mqtt, lifecycle)
+        start_keepalive(mqtt, lifecycle, connect.keep_alive)
+      end
+
+
+      def connection_added(_conn); end
+
+
+      def connection_removed(conn)
+        session = @by_conn.delete(conn)
+        return unless session
+        publish_will(session) unless session.clean_disconnect
+        @sessions.delete(session.client_id)
+        @trie.remove_session(session)
+      end
+
+
+      # Publish the client's Last Will and Testament via the normal
+      # dispatch path. Called when the session is torn down without
+      # having seen a clean DISCONNECT.
+      def publish_will(session)
+        will = session.will
+        return unless will
+        msg = Message.new(
+          topic:      will.fetch(:topic),
+          payload:    will.fetch(:payload),
+          qos:        will.fetch(:qos, 0),
+          retain:     will.fetch(:retain, false),
+          properties: will.fetch(:properties, {}) || {},
+        )
+        # Also honor RETAIN on wills.
+        apply_retain(msg) if msg.retain
+        dispatch_message(msg)
+      end
+
+
+      def close; end
+
+
+      # Used by tests.
+      def session_count = @sessions.size
+
+
+      # Fan out a Message to every session subscribed to a matching
+      # filter. Used by both inbound PUBLISH handling and
+      # {Broker#ingest} from a non-MQTT source.
+      def dispatch_message(message, origin: nil)
+        delivered = {}  # session.object_id => true  (one copy per session)
+        @trie.match(message.topic).each do |hit|
+          # v5 No Local (MQTT-3.8.3-3): when set on the subscription,
+          # don't echo a publish back to the publishing client.
+          next if hit.entry[:no_local] && origin && hit.session.conn.equal?(origin)
+          next if delivered[hit.session.object_id]
+          delivered[hit.session.object_id] = true
+          forward_publish(hit.session, message, hit.entry)
+        end
+      end
+
+
+      private
+
+
+      def build_session(client_id, mqtt, will: nil, receive_maximum: 65_535)
+        Session.new(
+          client_id:        client_id,
+          conn:             mqtt,
+          subscriptions:    [],
+          packet_ids:       PacketIdAllocator.new(receive_maximum: receive_maximum),
+          qos_tracker:      QosTracker.new,
+          will:             will,
+          keepalive:        nil,
+          clean_disconnect: false,
+        )
+      end
+
+
+      def start_keepalive(mqtt, lifecycle, keep_alive)
+        return if keep_alive.nil? || keep_alive.zero?
+        session = @by_conn[mqtt] or return
+        session.keepalive = Engine::Keepalive.new(
+          mqtt, keep_alive: keep_alive, role: :watcher,
+          on_timeout: -> { lifecycle.lost! },
+        )
+        lifecycle.barrier.async(annotation: "zzq broker keepalive #{lifecycle.endpoint}") do
+          session.keepalive.run
+        end
+      end
+
+
+      def write_connack(mqtt, reason:, assigned_client_id: nil, session_present: false)
+        props = {}
+        props[:assigned_client_identifier] = assigned_client_id if assigned_client_id && mqtt.version == 5
+        mqtt.write_packet(
+          Protocol::MQTT::Packet::Connack.new(
+            session_present: session_present,
+            reason_code: reason,
+            properties: props,
+          ),
+        )
+      end
+
+
+      def generate_client_id
+        "zzq-#{SecureRandom.hex(6)}"
+      end
+
+
+      def start_read_loop(mqtt, lifecycle)
+        lifecycle.barrier.async(annotation: "zzq broker read #{lifecycle.endpoint}") do
+          loop do
+            pkt = mqtt.read_packet
+            break if pkt.nil?
+            @by_conn[mqtt]&.keepalive&.note_received
+            dispatch(pkt, mqtt)
+          rescue *CONNECTION_LOST, Protocol::MQTT::MalformedPacket
+            break
+          end
+        ensure
+          lifecycle.lost! unless lifecycle.state == :closed
+        end
+      end
+
+
+      def dispatch(pkt, mqtt)
+        case pkt
+        when Protocol::MQTT::Packet::Pingreq
+          mqtt.write_packet(Protocol::MQTT::Packet::Pingresp.new)
+        when Protocol::MQTT::Packet::Disconnect
+          # Clean DISCONNECT: v3 = any disconnect; v5 = reason 0x00
+          # (NORMAL_DISCONNECTION). v5 reason 0x04 explicitly requests
+          # that the will still be published. Others suppress (spec).
+          session = @by_conn[mqtt]
+          if session
+            reason = mqtt.version == 5 ? pkt.reason_code : 0
+            session.clean_disconnect = (reason != 0x04)
+          end
+          raise EOFError  # cleanly unwind the read loop
+        when Protocol::MQTT::Packet::Publish
+          handle_publish(pkt, mqtt)
+        when Protocol::MQTT::Packet::Subscribe
+          handle_subscribe(pkt, mqtt)
+        when Protocol::MQTT::Packet::Unsubscribe
+          handle_unsubscribe(pkt, mqtt)
+        when Protocol::MQTT::Packet::Puback
+          handle_puback(pkt, mqtt)
+        when Protocol::MQTT::Packet::Pubrec
+          handle_pubrec(pkt, mqtt)
+        when Protocol::MQTT::Packet::Pubrel
+          handle_pubrel(pkt, mqtt)
+        when Protocol::MQTT::Packet::Pubcomp
+          handle_pubcomp(pkt, mqtt)
+        end
+      end
+
+
+      def handle_publish(pkt, mqtt)
+        session = @by_conn[mqtt] or return
+        message = Message.from_publish(pkt)
+        case pkt.qos
+        when 0
+          apply_retain(message) if pkt.retain
+          dispatch_message(message, origin: mqtt)
+        when 1
+          apply_retain(message) if pkt.retain
+          dispatch_message(message, origin: mqtt)
+          mqtt.write_packet(Protocol::MQTT::Packet::Puback.new(packet_id: pkt.packet_id))
+        when 2
+          # Fan out only on first receipt; duplicates are still PUBRECed.
+          if session.qos_tracker.on_qos2_publish(pkt.packet_id)
+            apply_retain(message) if pkt.retain
+            dispatch_message(message, origin: mqtt)
+          end
+          mqtt.write_packet(Protocol::MQTT::Packet::Pubrec.new(packet_id: pkt.packet_id))
+        end
+      end
+
+
+      def apply_retain(message)
+        @retained.store(message)
+      end
+
+
+      def handle_subscribe(pkt, mqtt)
+        session = @by_conn[mqtt] or return
+        added = []
+        reasons = pkt.filters.map do |entry|
+          sub_entry = {
+            filter: entry.fetch(:filter),
+            qos: entry.fetch(:qos, 0),
+            no_local: entry.fetch(:no_local, false),
+            retain_as_published: entry.fetch(:retain_as_published, false),
+            retain_handling: entry.fetch(:retain_handling, 0),
+          }
+          session.subscriptions << sub_entry
+          @trie.add(sub_entry[:filter], session, sub_entry)
+          added << sub_entry
+          sub_entry[:qos]  # granted QoS == requested (MVP)
+        end
+        mqtt.write_packet(Protocol::MQTT::Packet::Suback.new(
+          packet_id: pkt.packet_id, reason_codes: reasons,
+        ))
+        # Replay retained messages for each newly-added filter.
+        added.each { |sub_entry| replay_retained(session, sub_entry) }
+      end
+
+
+      def handle_unsubscribe(pkt, mqtt)
+        session = @by_conn[mqtt]
+        reasons = pkt.filters.map do |filter|
+          matched = session&.subscriptions&.reject! { |s| s[:filter] == filter }
+          @trie.remove(filter, session) if matched && session
+          matched && !matched.empty? ? 0x00 : 0x11  # 0x11 = No subscription existed
+        end
+        mqtt.write_packet(Protocol::MQTT::Packet::Unsuback.new(
+          packet_id: pkt.packet_id, reason_codes: reasons,
+        ))
+      end
+
+
+      # For each retained message matching the new filter, deliver a
+      # PUBLISH copy with RETAIN=1 (MQTT-3.3.1-8). Retain handling per
+      # v5: 0 = send retained on every SUBSCRIBE; 1 = only if the sub
+      # didn't exist; 2 = never. MVP honours 0/2; 1 is a future polish.
+      def replay_retained(session, sub_entry)
+        return if sub_entry[:retain_handling] == 2
+        @retained.each_matching(sub_entry[:filter]) do |msg|
+          forward_publish(session, msg, sub_entry, retain: true)
+        end
+      end
+
+
+      # --- outbound-QoS ack handlers -------------------------------------
+
+      def handle_puback(pkt, mqtt)
+        session = @by_conn[mqtt] or return
+        pending = session.qos_tracker.on_puback(pkt.packet_id)
+        session.packet_ids.release(pkt.packet_id) if pending
+      end
+
+
+      def handle_pubrec(pkt, mqtt)
+        session = @by_conn[mqtt] or return
+        entry = session.qos_tracker.on_pubrec(pkt.packet_id)
+        return unless entry
+        mqtt.write_packet(Protocol::MQTT::Packet::Pubrel.new(packet_id: pkt.packet_id))
+      end
+
+
+      # Inbound PUBREL: the client is telling us to release its own
+      # inbound QoS 2 dedup entry (it published at QoS 2; we PUBRECed;
+      # now it's clearing). Respond with PUBCOMP.
+      def handle_pubrel(pkt, mqtt)
+        session = @by_conn[mqtt] or return
+        session.qos_tracker.on_pubrel(pkt.packet_id)
+        mqtt.write_packet(Protocol::MQTT::Packet::Pubcomp.new(packet_id: pkt.packet_id))
+      end
+
+
+      def handle_pubcomp(pkt, mqtt)
+        session = @by_conn[mqtt] or return
+        pending = session.qos_tracker.on_pubcomp(pkt.packet_id)
+        session.packet_ids.release(pkt.packet_id) if pending
+      end
+
+
+      def forward_publish(session, message, entry, retain: false)
+        granted_qos = [message.qos, entry[:qos]].min
+        # retain_as_published (v5): when true, preserve publisher's
+        # RETAIN flag; otherwise spec forces RETAIN=0 on fan-out (and
+        # =1 only on retained-replay, tracked via the +retain+ arg).
+        out_retain =
+          if retain
+            true
+          elsif entry[:retain_as_published]
+            message.retain
+          else
+            false
+          end
+
+        if granted_qos.zero?
+          out = Protocol::MQTT::Packet::Publish.new(
+            topic: message.topic, payload: message.payload,
+            qos: 0, retain: out_retain, dup: false, packet_id: nil,
+            properties: message.properties,
+          )
+          session.conn.write_packet(out)
+          return
+        end
+
+        packet_id = session.packet_ids.acquire
+        out = Protocol::MQTT::Packet::Publish.new(
+          topic: message.topic, payload: message.payload,
+          qos: granted_qos, retain: out_retain, dup: false,
+          packet_id: packet_id, properties: message.properties,
+        )
+        if granted_qos == 1
+          session.qos_tracker.track_qos1(packet_id, out)
+        else
+          session.qos_tracker.track_qos2(packet_id, out)
+        end
+        session.conn.write_packet(out)
+      rescue *CONNECTION_LOST, ClosedError
+        # recipient is gone; tear-down handled by their read loop.
+        session.packet_ids.release(packet_id) if packet_id
+      end
+    end
+  end
+end

data/lib/zzq/routing/client.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/promise"
+require "protocol/mqtt"
+require_relative "../engine/keepalive"
+require_relative "../message"
+require_relative "../subscription"
+require_relative "packet_id_allocator"
+require_relative "qos_tracker"
+require_relative "topic_match"
+
+module ZZQ
+  module Routing
+    # Client-side routing.
+    #
+    # Responsibilities:
+    #   * CONNECT / CONNACK handshake on +handle_connected+.
+    #   * Per-connection read loop dispatching PINGRESP, DISCONNECT,
+    #     PUBLISH (fan-out to matching subscriptions), SUBACK/UNSUBACK
+    #     (resolve pending acks), and PUBACK/PUBREC/PUBREL/PUBCOMP
+    #     (drive outbound QoS 1/2 state machines).
+    #   * Keepalive fiber.
+    #   * QoS 0/1/2 publish and subscribe.
+    class Client
+      HANDSHAKE_TIMEOUT = 10  # seconds to wait for CONNACK
+      SUBSCRIBE_TIMEOUT = 30  # seconds to wait for SUBACK / UNSUBACK
+      PUBLISH_TIMEOUT   = 30  # seconds to wait for terminal ack on qos>0
+
+
+      # @return [Protocol::MQTT::Packet::Connack, nil] the most recent
+      #   CONNACK received, or nil before the first connect.
+      attr_reader :last_connack
+
+
+      def initialize(engine)
+        @engine        = engine
+        @conn          = nil
+        @keepalive     = nil
+        @last_connack  = nil
+        @subscriptions = []   # ZZQ::Subscription
+        @packet_ids    = PacketIdAllocator.new(
+          receive_maximum: @engine.options.receive_maximum,
+        )
+        @qos_tracker   = QosTracker.new
+        @pending_ctl   = {}   # packet_id => Async::Promise (SUBACK / UNSUBACK)
+        @inbound_qos2  = {}   # packet_id => Message awaiting PUBREL (manual-ack path; M9)
+      end
+
+
+      def session_present?
+        @last_connack&.session_present || false
+      end
+
+
+      # Called by Engine#handle_connected. Runs inside the caller's
+      # Async task (Socket#connect → Engine.connect → Transport.connect
+      # → Engine.handle_connected), so we can synchronously drive the
+      # CONNECT/CONNACK exchange and raise to the caller on refusal.
+      def handle_connected(mqtt, lifecycle)
+        opts = @engine.options
+        mqtt.version = opts.version
+
+        connect_packet = build_connect(opts)
+
+        Async::Task.current.with_timeout(HANDSHAKE_TIMEOUT) do
+          mqtt.write_packet(connect_packet)
+          reply = mqtt.read_packet
+          raise ConnectionRefused.new(0, "no CONNACK from broker") if reply.nil?
+          raise ConnectionRefused.new(0, "expected CONNACK, got #{reply.class.name}") unless reply.is_a?(Protocol::MQTT::Packet::Connack)
+          unless success_connack?(reply)
+            raise ConnectionRefused.new(reply.reason_code)
+          end
+          @last_connack = reply
+        end
+
+        @conn = mqtt
+        lifecycle.handshake_succeeded!
+
+        start_read_loop(mqtt, lifecycle)
+        start_keepalive(mqtt, lifecycle)
+      end
+
+
+      def connection_added(_conn); end
+
+
+      def connection_removed(conn)
+        return unless @conn.equal?(conn)
+        @conn = nil
+        @subscriptions.each(&:close)
+        @subscriptions.clear
+        @pending_ctl.each_value { |p| p.resolve(nil) unless p.resolved? }
+        @pending_ctl.clear
+        # Wake any fiber blocked on a publish ack. Don't clear the
+        # tracker yet — M6 retransmit-on-reconnect will want to inspect
+        # +inflight_outbound+. For now, just unblock with nil.
+        @qos_tracker.inflight_outbound.each do |pending|
+          pending.promise.resolve(nil) unless pending.promise.resolved?
+        end
+      end
+
+
+      def close
+        return unless @conn
+        begin
+          @conn.write_packet(Protocol::MQTT::Packet::Disconnect.new)
+        rescue IOError, Errno::EPIPE, Errno::ECONNRESET, ClosedError
+          # peer already gone; fine
+        end
+        @conn = nil
+      end
+
+
+      # Send a PUBLISH. For QoS 0 returns immediately after write. For
+      # QoS 1 blocks the fiber until PUBACK. For QoS 2 blocks until
+      # PUBCOMP.
+      def publish(topic:, payload:, qos: 0, retain: false, properties: {})
+        raise ClosedError, "client not connected" unless @conn
+        if qos.zero?
+          pkt = Protocol::MQTT::Packet::Publish.new(
+            topic: topic, payload: payload, qos: 0, retain: retain,
+            properties: properties,
+          )
+          @conn.write_packet(pkt)
+          @keepalive&.note_sent
+          return nil
+        end
+
+        packet_id = @packet_ids.acquire
+        pkt = Protocol::MQTT::Packet::Publish.new(
+          topic: topic, payload: payload, qos: qos, retain: retain,
+          packet_id: packet_id, properties: properties,
+        )
+        pending = qos == 1 \
+          ? @qos_tracker.track_qos1(packet_id, pkt) \
+          : @qos_tracker.track_qos2(packet_id, pkt)
+        begin
+          @conn.write_packet(pkt)
+          @keepalive&.note_sent
+          result = Async::Task.current.with_timeout(PUBLISH_TIMEOUT) { pending.promise.wait }
+          raise ClosedError, "connection lost before publish ack" if result.nil?
+        ensure
+          @packet_ids.release(packet_id)
+        end
+        nil
+      end
+
+
+      # Send a SUBSCRIBE, wait for SUBACK, return a Subscription.
+      def subscribe(filter, qos: 0, no_local: false, retain_as_published: false,
+                    retain_handling: 0)
+        raise ClosedError, "client not connected" unless @conn
+        packet_id = @packet_ids.acquire
+        filter_entry = {
+          filter: filter, qos: qos, no_local: no_local,
+          retain_as_published: retain_as_published,
+          retain_handling: retain_handling,
+        }
+        subscription = Subscription.new(
+          filters: [filter],
+          hwm: @engine.options.recv_hwm,
+          on_close: ->(sub) { send_unsubscribe(sub) },
+        )
+        @subscriptions << subscription
+
+        promise = Async::Promise.new
+        @pending_ctl[packet_id] = promise
+        begin
+          @conn.write_packet(Protocol::MQTT::Packet::Subscribe.new(
+            packet_id: packet_id, filters: [filter_entry],
+          ))
+          @keepalive&.note_sent
+
+          suback = Async::Task.current.with_timeout(SUBSCRIBE_TIMEOUT) { promise.wait }
+          raise ClosedError, "connection lost before SUBACK" if suback.nil?
+          reason = suback.reason_codes.first
+          if reason >= 0x80
+            @subscriptions.delete(subscription)
+            raise Error, "SUBSCRIBE refused: reason=0x#{reason.to_s(16)}"
+          end
+        ensure
+          @packet_ids.release(packet_id)
+        end
+        subscription
+      end
+
+
+      private
+
+
+      def build_connect(opts)
+        Protocol::MQTT::Packet::Connect.new(
+          client_id: opts.client_id.to_s,
+          clean_start: opts.clean_start,
+          keep_alive: opts.keep_alive,
+          username: opts.username,
+          password: opts.password,
+          will: opts.will,
+          properties: build_connect_properties(opts),
+        )
+      end
+
+
+      def build_connect_properties(opts)
+        return {} unless opts.version == 5
+        props = {}
+        props[:session_expiry_interval] = opts.session_expiry_interval if opts.session_expiry_interval > 0
+        props[:receive_maximum]         = opts.receive_maximum         if opts.receive_maximum != 65_535
+        props[:maximum_packet_size]     = opts.max_packet_size         if opts.max_packet_size
+        props[:topic_alias_maximum]     = opts.topic_alias_maximum     if opts.topic_alias_maximum > 0
+        props
+      end
+
+
+      def success_connack?(ack)
+        # v3 accepted = 0x00; v5 success = 0x00. Both map to 0.
+        ack.reason_code.zero?
+      end
+
+
+      def send_unsubscribe(subscription)
+        return unless @conn
+        packet_id = @packet_ids.acquire
+        promise = Async::Promise.new
+        @pending_ctl[packet_id] = promise
+        begin
+          @conn.write_packet(Protocol::MQTT::Packet::Unsubscribe.new(
+            packet_id: packet_id, filters: subscription.filters.dup,
+          ))
+          @keepalive&.note_sent
+        rescue *CONNECTION_LOST, ClosedError
+          @pending_ctl.delete(packet_id)
+        ensure
+          @packet_ids.release(packet_id)
+        end
+        @subscriptions.delete(subscription)
+      end
+
+
+      def start_read_loop(mqtt, lifecycle)
+        lifecycle.barrier.async(annotation: "zzq client read #{lifecycle.endpoint}") do
+          loop do
+            pkt = mqtt.read_packet
+            break if pkt.nil?  # clean EOF
+            @keepalive&.note_received
+            dispatch(pkt, mqtt)
+          rescue *CONNECTION_LOST, Protocol::MQTT::MalformedPacket
+            break
+          end
+        ensure
+          lifecycle.lost! unless lifecycle.state == :closed
+        end
+      end
+
+
+      def start_keepalive(mqtt, lifecycle)
+        ka = @engine.options.keep_alive
+        return if ka.zero?
+        @keepalive = Engine::Keepalive.new(
+          mqtt, keep_alive: ka,
+          on_timeout: -> { lifecycle.lost! },
+        )
+        lifecycle.barrier.async(annotation: "zzq client keepalive") do
+          @keepalive.run
+        end
+      end
+
+
+      def dispatch(pkt, mqtt)
+        case pkt
+        when Protocol::MQTT::Packet::Pingresp
+          # liveness refreshed via @keepalive.note_received above
+        when Protocol::MQTT::Packet::Disconnect
+          raise EOFError  # cleanly unwind the read loop
+        when Protocol::MQTT::Packet::Publish
+          handle_inbound_publish(pkt, mqtt)
+        when Protocol::MQTT::Packet::Suback, Protocol::MQTT::Packet::Unsuback
+          promise = @pending_ctl.delete(pkt.packet_id)
+          promise&.resolve(pkt)
+        when Protocol::MQTT::Packet::Puback
+          @qos_tracker.on_puback(pkt.packet_id)
+        when Protocol::MQTT::Packet::Pubrec
+          entry = @qos_tracker.on_pubrec(pkt.packet_id)
+          if entry
+            mqtt.write_packet(Protocol::MQTT::Packet::Pubrel.new(packet_id: pkt.packet_id))
+            @keepalive&.note_sent
+          end
+        when Protocol::MQTT::Packet::Pubrel
+          # Inbound half of QoS 2 (broker → client). Release the held
+          # dedup entry and acknowledge with PUBCOMP.
+          @qos_tracker.on_pubrel(pkt.packet_id)
+          mqtt.write_packet(Protocol::MQTT::Packet::Pubcomp.new(packet_id: pkt.packet_id))
+          @keepalive&.note_sent
+        when Protocol::MQTT::Packet::Pubcomp
+          @qos_tracker.on_pubcomp(pkt.packet_id)
+        end
+      end
+
+
+      def handle_inbound_publish(pkt, mqtt)
+        case pkt.qos
+        when 0
+          fan_out_publish(pkt)
+        when 1
+          fan_out_publish(pkt)
+          mqtt.write_packet(Protocol::MQTT::Packet::Puback.new(packet_id: pkt.packet_id))
+          @keepalive&.note_sent
+        when 2
+          # Only fan out the first receipt; duplicates (same packet id
+          # before PUBREL) are dropped but still PUBRECed.
+          fan_out_publish(pkt) if @qos_tracker.on_qos2_publish(pkt.packet_id)
+          mqtt.write_packet(Protocol::MQTT::Packet::Pubrec.new(packet_id: pkt.packet_id))
+          @keepalive&.note_sent
+        end
+      end
+
+
+      def fan_out_publish(pkt)
+        msg = Message.from_publish(pkt)
+        @subscriptions.each do |sub|
+          sub.deliver(msg) if sub.filters.any? { |f| TopicMatch.match?(f, pkt.topic) }
+        end
+      end
+    end
+  end
+end