zzq 0.1.0

data/lib/zzq/subscription.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "async/queue"
+require "async/limited_queue"
+
+module ZZQ
+  # Handle returned by {Client#subscribe} and {Broker#subscribe}. A
+  # thin wrapper around an +Async::LimitedQueue+ that also owns the
+  # UNSUBSCRIBE lifecycle.
+  #
+  # Callers consume with {#pop} or {#each}; {#close} sends UNSUBSCRIBE
+  # and wakes any blocked consumer with +nil+.
+  #
+  # Created internally — users should never call +.new+ directly.
+  class Subscription
+    # @return [Array<String>] topic filters this subscription matches.
+    attr_reader :filters
+
+    # @return [Integer] subscription identifier (v5) or nil (v3).
+    attr_reader :subscription_id
+
+
+    def initialize(filters:, hwm:, subscription_id: nil, on_close: nil)
+      @filters         = Array(filters).freeze
+      @subscription_id = subscription_id
+      @queue           = Async::LimitedQueue.new(hwm)
+      @on_close        = on_close
+      @closed          = false
+    end
+
+
+    # Blocks the fiber until a message arrives. Returns +nil+ when
+    # the subscription is closed.
+    def pop
+      return nil if @closed && @queue.empty?
+      @queue.dequeue
+    end
+
+
+    # Yields each message until the subscription is closed.
+    def each
+      return enum_for(:each) unless block_given?
+      while (msg = pop)
+        yield msg
+      end
+    end
+
+
+    # Sends UNSUBSCRIBE and wakes the consumer. Idempotent.
+    def close
+      return if @closed
+      @closed = true
+      @on_close&.call(self)
+      @queue.enqueue(nil)
+    end
+
+
+    def closed?
+      @closed
+    end
+
+
+    # Internal: deliver a message to the subscriber's queue. Blocks
+    # the caller if the queue is at high-water-mark.
+    def deliver(message)
+      return if @closed
+      @queue.enqueue(message)
+    end
+  end
+end

data/lib/zzq/transport/ipc.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "socket"
+require "io/stream"
+require_relative "../engine"
+
+module ZZQ
+  module Transport
+    # IPC transport using Unix domain sockets.
+    #
+    # Endpoint forms:
+    #   * `ipc:///var/run/zzq.sock` — filesystem path (portable).
+    #   * `ipc://@zzq-local`        — Linux abstract namespace (the
+    #     leading `@` becomes a NUL byte in sockaddr.sun_path).
+    module IPC
+      Engine.transports["ipc"] = self
+
+
+      class << self
+        def bind(endpoint, engine, **)
+          path      = parse_path(endpoint)
+          sock_path = to_socket_path(path)
+
+          File.delete(sock_path) if !abstract?(path) && File.exist?(sock_path)
+
+          server = UNIXServer.new(sock_path)
+          Listener.new(endpoint, server, path, engine)
+        end
+
+
+        def connect(endpoint, engine, **)
+          path      = parse_path(endpoint)
+          sock_path = to_socket_path(path)
+          sock      = UNIXSocket.new(sock_path)
+          engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: endpoint)
+        end
+
+
+        def parse_path(endpoint)
+          endpoint.sub(%r{\Aipc://}, "")
+        end
+
+
+        # Linux abstract-namespace Unix sockets: leading `@` becomes a
+        # NUL byte in sun_path. Only supported on Linux.
+        def to_socket_path(path)
+          abstract?(path) ? "\0#{path[1..]}" : path
+        end
+
+
+        def abstract?(path)
+          path.start_with?("@")
+        end
+      end
+
+
+      class Listener
+        attr_reader :endpoint
+
+
+        def initialize(endpoint, server, path, engine)
+          @endpoint = endpoint
+          @server   = server
+          @path     = path
+          @engine   = engine
+          @task     = nil
+        end
+
+
+        def start_accept_loop(parent_task, &on_accepted)
+          @task = parent_task.async(annotation: "zzq ipc accept #{@endpoint}") do
+            loop do
+              client = @server.accept
+              on_accepted.call(IO::Stream::Buffered.wrap(client))
+            rescue Async::Stop, IOError
+              break
+            end
+          ensure
+            @server.close rescue nil
+          end
+        end
+
+
+        def stop
+          @task&.stop
+          @server.close rescue nil
+          File.delete(@path) rescue nil unless IPC.abstract?(@path)
+        end
+      end
+    end
+  end
+end

data/lib/zzq/transport/mqtt.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "socket"
+require "uri"
+require "io/stream"
+require_relative "../engine"
+
+module ZZQ
+  module Transport
+    # Plain MQTT-over-TCP transport. Endpoint scheme: `mqtt://host:port`
+    # (default port 1883). One server per bind, blocking accept inside
+    # an Async fiber.
+    module MQTT
+      Engine.transports["mqtt"] = self
+
+
+      class << self
+        def bind(endpoint, engine, **)
+          host, port = parse_endpoint(endpoint)
+          host       = "0.0.0.0" if host == "*"
+          server     = TCPServer.new(host, port)
+          actual     = server.local_address.ip_port
+          host_part  = host.include?(":") ? "[#{host}]" : host
+          Listener.new("mqtt://#{host_part}:#{actual}", server, actual, engine)
+        end
+
+
+        def connect(endpoint, engine, **)
+          host, port = parse_endpoint(endpoint)
+          sock = ::Socket.tcp(host, port, connect_timeout: connect_timeout(engine.options))
+          engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: endpoint)
+        end
+
+
+        def connect_timeout(options)
+          ri = options.reconnect_interval
+          ri = ri.end if ri.is_a?(Range)
+          [ri, 0.5].max
+        end
+
+
+        def parse_endpoint(endpoint)
+          uri = URI.parse(endpoint.sub("mqtt://", "tcp://"))
+          [uri.hostname, uri.port]
+        end
+      end
+
+
+      class Listener
+        attr_reader :endpoint, :port
+
+
+        def initialize(endpoint, server, port, engine)
+          @endpoint = endpoint
+          @server   = server
+          @port     = port
+          @engine   = engine
+          @task     = nil
+        end
+
+
+        def start_accept_loop(parent_task, &on_accepted)
+          @task = parent_task.async(annotation: "zzq mqtt accept #{@endpoint}") do
+            loop do
+              client = @server.accept
+              on_accepted.call(IO::Stream::Buffered.wrap(client))
+            rescue Async::Stop, IOError
+              break
+            end
+          ensure
+            @server.close rescue nil
+          end
+        end
+
+
+        def stop
+          @task&.stop
+          @server.close rescue nil
+        end
+      end
+    end
+  end
+end

data/lib/zzq/transport/mqtts.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "socket"
+require "openssl"
+require "uri"
+require "io/stream"
+require_relative "../engine"
+
+module ZZQ
+  module Transport
+    # MQTT-over-TLS transport — endpoint scheme `mqtts://host:port`
+    # (default port 8883).
+    #
+    # Both bind and connect accept a `tls_context:` option — any
+    # +OpenSSL::SSL::SSLContext+. On bind the context must carry a
+    # cert + key; on connect a default client context is used if
+    # none is given. The transport does not constrain the context;
+    # see the README for a recommended TLS 1.3 +
+    # `TLS_CHACHA20_POLY1305_SHA256` configuration.
+    #
+    # Per-connection application data is capped at
+    # {DATA_LIMIT} bytes, after which the socket is torn down and
+    # the peer must reconnect. This keeps AEAD nonce counters well
+    # below their unsafe bound (e.g. ChaCha20-Poly1305's ~256 GiB
+    # per-key integrity bound) without relying on a specific cipher
+    # choice.
+    module MQTTS
+      Engine.transports["mqtts"] = self
+
+      # 128 GiB — conservative for every AEAD in TLS 1.3 (ChaCha20-
+      # Poly1305 at ~256 GiB, AES-GCM limits are higher under TLS 1.3
+      # record sizes). Reconnection negotiates fresh keys, so this
+      # caps nonce reuse exposure regardless of cipher choice.
+      DATA_LIMIT = 128 * 1024 * 1024 * 1024
+
+
+      class << self
+        def bind(endpoint, engine, tls_context: nil, **)
+          raise Error, "mqtts:// bind requires tls_context:" unless tls_context
+
+          host, port = parse_endpoint(endpoint)
+          host       = "0.0.0.0" if host == "*"
+          server     = TCPServer.new(host, port)
+          actual     = server.local_address.ip_port
+          host_part  = host.include?(":") ? "[#{host}]" : host
+          Listener.new("mqtts://#{host_part}:#{actual}", server, tls_context, engine)
+        end
+
+
+        def connect(endpoint, engine, tls_context: nil, **)
+          host, port = parse_endpoint(endpoint)
+          ctx = tls_context || OpenSSL::SSL::SSLContext.new
+          tcp = ::Socket.tcp(host, port, connect_timeout: connect_timeout(engine.options))
+          ssl = OpenSSL::SSL::SSLSocket.new(tcp, ctx)
+          ssl.hostname = host  # SNI
+          ssl.sync_close = true
+          ssl.connect
+          engine.handle_connected(LimitedStream.wrap(ssl), endpoint: endpoint)
+        end
+
+
+        def connect_timeout(options)
+          ri = options.reconnect_interval
+          ri = ri.end if ri.is_a?(Range)
+          [ri, 0.5].max
+        end
+
+
+        def parse_endpoint(endpoint)
+          uri = URI.parse(endpoint.sub("mqtts://", "tcp://"))
+          [uri.hostname, uri.port]
+        end
+      end
+
+
+      class Listener
+        attr_reader :endpoint
+
+
+        def initialize(endpoint, server, tls_context, engine)
+          @endpoint = endpoint
+          @server   = server
+          @ctx      = tls_context
+          @engine   = engine
+          @task     = nil
+        end
+
+
+        def start_accept_loop(parent_task, &on_accepted)
+          @task = parent_task.async(annotation: "zzq mqtts accept #{@endpoint}") do |task|
+            loop do
+              client = @server.accept
+              # TLS handshake per-connection, off the accept loop, so
+              # one slow handshake can't block the next client.
+              task.async(annotation: "zzq mqtts handshake") do
+                ssl = OpenSSL::SSL::SSLSocket.new(client, @ctx)
+                ssl.sync_close = true
+                ssl.accept
+                on_accepted.call(LimitedStream.wrap(ssl))
+              rescue Async::Stop, IOError, OpenSSL::SSL::SSLError
+                ssl&.close rescue nil
+                client.close rescue nil
+              end
+            rescue Async::Stop, IOError
+              break
+            end
+          ensure
+            @server.close rescue nil
+          end
+        end
+
+
+        def stop
+          @task&.stop
+          @server.close rescue nil
+        end
+      end
+
+
+      # Buffered stream with a per-connection byte cap. When the cap
+      # is reached on either direction the underlying socket is
+      # closed and the next I/O raises — forcing the peer to
+      # reconnect and negotiate fresh keys before ChaCha20-Poly1305's
+      # nonce counter approaches its unsafe range.
+      class LimitedStream < IO::Stream::Buffered
+        def self.wrap(io, limit: DATA_LIMIT)
+          if io.respond_to?(:buffered=)
+            io.buffered = false
+          elsif io.respond_to?(:sync=)
+            io.sync = true
+          end
+          new(io, limit)
+        end
+
+
+        def initialize(io, limit = DATA_LIMIT)
+          super(io)
+          @limit = limit
+          @bytes = 0
+        end
+
+
+        protected
+
+
+        def syswrite(buffer)
+          enforce!(buffer.bytesize)
+          super
+        end
+
+
+        def sysread(size, buffer)
+          result = super
+          enforce!(result.bytesize) if result.is_a?(String)
+          result
+        end
+
+
+        private
+
+
+        def enforce!(n)
+          @bytes += n
+          return if @bytes < @limit
+
+          close rescue nil
+          raise ZZQ::Error,
+            "mqtts:// data limit reached (#{@limit} B): dropping connection to force fresh keys"
+        end
+      end
+    end
+  end
+end

data/lib/zzq/version.rb

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

data/lib/zzq.rb

@@ -0,0 +1,26 @@
+# 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_relative "zzq/version"
+require_relative "zzq/error"
+require_relative "zzq/monitor_event"
+require_relative "zzq/options"
+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/client"
+require_relative "zzq/broker"

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: zzq
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Patrik Wenger
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.38'
+  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).
+email:
+- paddor@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- 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/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
+licenses:
+- ISC
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Pure Ruby MQTT 3.1.1 + 5.0 client and broker on Async
+test_files: []