zzq 0.1.1 → 0.2.0

data/ext/zzq_native/src/rb.rs

@@ -0,0 +1,424 @@
+//! Calls into the Ruby C API. Every call that may raise runs under
+//! `rb_protect`, so a Ruby exception never unwinds through Rust frames.
+
+use std::ffi::{CStr, CString, c_char, c_long, c_void};
+use std::panic::{AssertUnwindSafe, catch_unwind};
+use std::ptr;
+
+use rb_sys::{VALUE, rb_data_type_struct__bindgen_ty_1, rb_data_type_t, size_t};
+
+pub type RbResult<T = VALUE> = Result<T, RubyErr>;
+
+#[derive(Debug)]
+pub enum RubyErr {
+    /// An exception object to raise.
+    Exception(VALUE),
+    /// An exception to build from a class and a message.
+    Error { class: VALUE, message: String },
+}
+
+impl RubyErr {
+    pub fn new(class: VALUE, message: impl Into<String>) -> Self {
+        Self::Error {
+            class,
+            message: message.into(),
+        }
+    }
+
+    pub fn arg(message: impl Into<String>) -> Self {
+        Self::new(unsafe { rb_sys::rb_eArgError }, message)
+    }
+
+    pub fn runtime(message: impl Into<String>) -> Self {
+        Self::new(unsafe { rb_sys::rb_eRuntimeError }, message)
+    }
+
+    pub fn type_error(message: impl Into<String>) -> Self {
+        Self::new(unsafe { rb_sys::rb_eTypeError }, message)
+    }
+
+    fn current_exception() -> Self {
+        let err = unsafe { rb_sys::rb_errinfo() };
+        unsafe { rb_sys::rb_set_errinfo(qnil()) };
+        if err == qnil() {
+            Self::runtime("Ruby exception")
+        } else {
+            Self::Exception(err)
+        }
+    }
+}
+
+/// Runs a method body: raises its error, and turns a panic into an error.
+pub fn wrap<F>(f: F) -> VALUE
+where
+    F: FnOnce() -> RbResult<VALUE>,
+{
+    match catch_unwind(AssertUnwindSafe(f)) {
+        Ok(Ok(value)) => value,
+        Ok(Err(err)) => raise(err),
+        Err(_) => raise(RubyErr::runtime("native Rust panic")),
+    }
+}
+
+pub fn raise(err: RubyErr) -> ! {
+    match err {
+        RubyErr::Exception(exc) => unsafe { rb_sys::rb_exc_raise(exc) },
+        RubyErr::Error { class, message } => {
+            let message = CString::new(message.replace('\0', "\\0")).unwrap_or_default();
+            let exc = unsafe { rb_sys::rb_exc_new_cstr(class, message.as_ptr()) };
+            unsafe { rb_sys::rb_exc_raise(exc) }
+        }
+    }
+}
+
+struct ProtectData<F> {
+    func: Option<F>,
+    panicked: bool,
+}
+
+/// Runs `func`, which calls into Ruby, catching a Ruby exception.
+pub fn protect<F>(func: F) -> RbResult<VALUE>
+where
+    F: FnOnce() -> VALUE,
+{
+    unsafe extern "C" fn call<F>(arg: VALUE) -> VALUE
+    where
+        F: FnOnce() -> VALUE,
+    {
+        let data = unsafe { &mut *(arg as *mut ProtectData<F>) };
+        let Some(func) = data.func.take() else {
+            data.panicked = true;
+            return qnil();
+        };
+        if let Ok(value) = catch_unwind(AssertUnwindSafe(func)) {
+            value
+        } else {
+            data.panicked = true;
+            qnil()
+        }
+    }
+
+    let mut data = ProtectData {
+        func: Some(func),
+        panicked: false,
+    };
+    let mut state = 0;
+    let value = unsafe {
+        rb_sys::rb_protect(
+            Some(call::<F>),
+            (&raw mut data).cast::<ProtectData<F>>() as VALUE,
+            &raw mut state,
+        )
+    };
+    if state != 0 {
+        Err(RubyErr::current_exception())
+    } else if data.panicked {
+        Err(RubyErr::runtime("native Rust panic"))
+    } else {
+        Ok(value)
+    }
+}
+
+pub const fn qnil() -> VALUE {
+    rb_sys::ruby_special_consts::RUBY_Qnil as VALUE
+}
+
+pub const fn qtrue() -> VALUE {
+    rb_sys::ruby_special_consts::RUBY_Qtrue as VALUE
+}
+
+pub const fn qfalse() -> VALUE {
+    rb_sys::ruby_special_consts::RUBY_Qfalse as VALUE
+}
+
+const fn qundef() -> VALUE {
+    rb_sys::ruby_special_consts::RUBY_Qundef as VALUE
+}
+
+pub fn bool_value(value: bool) -> VALUE {
+    if value { qtrue() } else { qfalse() }
+}
+
+fn is_kind_of(value: VALUE, class: VALUE) -> bool {
+    unsafe { rb_sys::rb_obj_is_kind_of(value, class) == qtrue() }
+}
+
+/// The value under a String key, `None` if the key is missing.
+pub fn hash_get(hash: VALUE, key: &str) -> RbResult<Option<VALUE>> {
+    if !is_kind_of(hash, unsafe { rb_sys::rb_cHash }) {
+        return Err(RubyErr::type_error("expected a Hash"));
+    }
+    let key = new_utf8_string(key)?;
+    let value = protect(|| unsafe { rb_sys::rb_hash_lookup2(hash, key, qundef()) })?;
+    Ok((value != qundef()).then_some(value))
+}
+
+pub fn hash_new() -> RbResult<VALUE> {
+    protect(|| unsafe { rb_sys::rb_hash_new() })
+}
+
+pub fn hash_aset(hash: VALUE, key: VALUE, value: VALUE) -> RbResult<()> {
+    protect(|| unsafe { rb_sys::rb_hash_aset(hash, key, value) })?;
+    Ok(())
+}
+
+pub fn array_new_capa(capacity: usize) -> RbResult<VALUE> {
+    let capacity = c_long_len(capacity)?;
+    protect(|| unsafe { rb_sys::rb_ary_new_capa(capacity) })
+}
+
+pub fn array_entries(array: VALUE) -> RbResult<Vec<VALUE>> {
+    if !is_kind_of(array, unsafe { rb_sys::rb_cArray }) {
+        return Err(RubyErr::type_error("expected an Array"));
+    }
+    let len = unsafe { rb_sys::RARRAY_LEN(array) };
+    (0..len)
+        .map(|i| protect(|| unsafe { rb_sys::rb_ary_entry(array, i) }))
+        .collect()
+}
+
+pub fn array_push(array: VALUE, value: VALUE) -> RbResult<()> {
+    protect(|| unsafe { rb_sys::rb_ary_push(array, value) })?;
+    Ok(())
+}
+
+pub fn freeze(value: VALUE) -> VALUE {
+    unsafe { rb_sys::rb_obj_freeze(value) }
+}
+
+pub fn symbol(name: &str) -> RbResult<VALUE> {
+    let len = c_long_len(name.len())?;
+    protect(|| unsafe { rb_sys::rb_id2sym(rb_sys::rb_intern2(name.as_ptr().cast(), len)) })
+}
+
+/// A frozen binary String.
+pub fn new_binary_string(bytes: &[u8]) -> RbResult<VALUE> {
+    let len = c_long_len(bytes.len())?;
+    let ptr = if bytes.is_empty() {
+        ptr::null()
+    } else {
+        bytes.as_ptr().cast::<c_char>()
+    };
+    let value = protect(|| unsafe { rb_sys::rb_str_new(ptr, len) })?;
+    Ok(freeze(value))
+}
+
+pub fn new_utf8_string(text: &str) -> RbResult<VALUE> {
+    let len = c_long_len(text.len())?;
+    protect(|| unsafe { rb_sys::rb_utf8_str_new(text.as_ptr().cast::<c_char>(), len) })
+}
+
+/// A frozen, deduplicated UTF-8 String, for values that repeat, such as
+/// topics.
+pub fn interned_utf8_string(text: &str) -> RbResult<VALUE> {
+    let len = c_long_len(text.len())?;
+    protect(|| unsafe {
+        rb_sys::rb_enc_interned_str(
+            text.as_ptr().cast::<c_char>(),
+            len,
+            rb_sys::rb_utf8_encoding(),
+        )
+    })
+}
+
+/// `value` as a String, calling `to_str` if needed.
+pub fn string_value(value: VALUE) -> RbResult<VALUE> {
+    protect(|| unsafe { rb_sys::rb_str_to_str(value) })
+}
+
+/// The bytes of a String from [`string_value`].
+///
+/// # Safety
+///
+/// The slice points into the Ruby string. Use it before the next call
+/// into Ruby, which may run GC or change the string.
+pub unsafe fn string_bytes<'a>(string: VALUE) -> &'a [u8] {
+    let len = unsafe { rb_sys::RSTRING_LEN(string) };
+    let ptr = unsafe { rb_sys::RSTRING_PTR(string) };
+    if len <= 0 || ptr.is_null() {
+        return &[];
+    }
+    unsafe { std::slice::from_raw_parts(ptr.cast::<u8>(), len as usize) }
+}
+
+pub fn value_to_bytes(value: VALUE) -> RbResult<Vec<u8>> {
+    let string = string_value(value)?;
+    Ok(unsafe { string_bytes(string) }.to_vec())
+}
+
+pub fn value_to_string(value: VALUE) -> RbResult<String> {
+    String::from_utf8(value_to_bytes(value)?).map_err(|_| RubyErr::arg("expected a UTF-8 String"))
+}
+
+pub fn value_to_i64(value: VALUE) -> RbResult<i64> {
+    let mut out = 0i64;
+    protect(|| {
+        out = unsafe { rb_sys::rb_num2ll(value) };
+        qnil()
+    })?;
+    Ok(out)
+}
+
+pub fn value_to_f64(value: VALUE) -> RbResult<f64> {
+    let mut out = 0.0f64;
+    protect(|| {
+        out = unsafe { rb_sys::rb_num2dbl(value) };
+        qnil()
+    })?;
+    Ok(out)
+}
+
+pub fn value_to_bool(value: VALUE) -> RbResult<bool> {
+    if value == qtrue() {
+        Ok(true)
+    } else if value == qfalse() || value == qnil() {
+        Ok(false)
+    } else {
+        Err(RubyErr::type_error("expected true or false"))
+    }
+}
+
+pub fn u64_value(value: u64) -> VALUE {
+    unsafe { rb_sys::rb_ull2inum(value) }
+}
+
+/// Calls `receiver.name(*args)`.
+pub fn call(receiver: VALUE, name: &CStr, args: &[VALUE]) -> RbResult<VALUE> {
+    let count = std::os::raw::c_int::try_from(args.len())
+        .map_err(|_| RubyErr::arg("too many arguments"))?;
+    protect(|| unsafe {
+        rb_sys::rb_funcallv(
+            receiver,
+            rb_sys::rb_intern(name.as_ptr()),
+            count,
+            args.as_ptr(),
+        )
+    })
+}
+
+pub fn const_get(module: VALUE, name: &CStr) -> RbResult<VALUE> {
+    protect(|| unsafe { rb_sys::rb_const_get(module, rb_sys::rb_intern(name.as_ptr())) })
+}
+
+/// A Ruby type for a boxed `T`, which GC frees with the object.
+pub struct DataType(rb_data_type_t);
+
+unsafe impl Send for DataType {}
+unsafe impl Sync for DataType {}
+
+impl DataType {
+    pub const fn new<T>(name: &'static CStr) -> Self {
+        DataType(rb_data_type_t {
+            wrap_struct_name: name.as_ptr(),
+            function: rb_data_type_struct__bindgen_ty_1 {
+                dmark: None,
+                dfree: Some(free_box::<T>),
+                dsize: Some(size_box::<T>),
+                dcompact: None,
+                reserved: [ptr::null_mut(); 1],
+            },
+            parent: ptr::null(),
+            data: ptr::null_mut(),
+            // RUBY_TYPED_FREE_IMMEDIATELY: dropping never blocks or calls Ruby.
+            flags: 1,
+        })
+    }
+
+    const fn ptr(&'static self) -> *const rb_data_type_t {
+        &raw const self.0
+    }
+
+    /// Wraps `value` in a new object of `class`.
+    pub fn wrap<T>(&'static self, class: VALUE, value: T) -> RbResult<VALUE> {
+        let raw = Box::into_raw(Box::new(value));
+        protect(|| unsafe { rb_sys::rb_data_typed_object_wrap(class, raw.cast(), self.ptr()) })
+            .inspect_err(|_| drop(unsafe { Box::from_raw(raw) }))
+    }
+
+    /// The `T` inside `value`.
+    ///
+    /// # Safety
+    ///
+    /// `T` must be the type this data type was made for.
+    pub unsafe fn get<T>(&'static self, value: VALUE) -> RbResult<&'static T> {
+        let mut ptr = ptr::null_mut();
+        protect(|| unsafe {
+            ptr = rb_sys::rb_check_typeddata(value, self.ptr());
+            qnil()
+        })?;
+        if ptr.is_null() {
+            return Err(RubyErr::runtime("native object is empty"));
+        }
+        Ok(unsafe { &*ptr.cast::<T>() })
+    }
+}
+
+unsafe extern "C" fn free_box<T>(ptr: *mut c_void) {
+    if !ptr.is_null() {
+        let _ = catch_unwind(AssertUnwindSafe(|| {
+            drop(unsafe { Box::from_raw(ptr.cast::<T>()) });
+        }));
+    }
+}
+
+unsafe extern "C" fn size_box<T>(_ptr: *const c_void) -> size_t {
+    std::mem::size_of::<T>() as size_t
+}
+
+pub fn define_module(name: &CStr) -> RbResult<VALUE> {
+    protect(|| unsafe { rb_sys::rb_define_module(name.as_ptr()) })
+}
+
+pub fn define_module_under(outer: VALUE, name: &CStr) -> RbResult<VALUE> {
+    protect(|| unsafe { rb_sys::rb_define_module_under(outer, name.as_ptr()) })
+}
+
+/// A class whose objects only native code creates.
+pub fn define_class_under(outer: VALUE, name: &CStr) -> RbResult<VALUE> {
+    let class = protect(|| unsafe {
+        rb_sys::rb_define_class_under(outer, name.as_ptr(), rb_sys::rb_cObject)
+    })?;
+    protect(|| unsafe {
+        rb_sys::rb_undef_alloc_func(class);
+        qnil()
+    })?;
+    Ok(class)
+}
+
+pub fn define_const(module: VALUE, name: &CStr, value: VALUE) -> RbResult<()> {
+    protect(|| unsafe {
+        rb_sys::rb_define_const(module, name.as_ptr(), value);
+        qnil()
+    })?;
+    Ok(())
+}
+
+/// A method with `arity` arguments. `func` takes `self` and then each
+/// argument as a `VALUE`.
+pub fn define_method(class: VALUE, name: &CStr, func: *const (), arity: i32) -> RbResult<()> {
+    let func = unsafe { std::mem::transmute::<*const (), unsafe extern "C" fn() -> VALUE>(func) };
+    protect(|| unsafe {
+        rb_sys::rb_define_method(class, name.as_ptr(), Some(func), arity);
+        qnil()
+    })?;
+    Ok(())
+}
+
+/// A singleton method, as [`define_method`].
+pub fn define_singleton_method(
+    object: VALUE,
+    name: &CStr,
+    func: *const (),
+    arity: i32,
+) -> RbResult<()> {
+    let func = unsafe { std::mem::transmute::<*const (), unsafe extern "C" fn() -> VALUE>(func) };
+    protect(|| unsafe {
+        rb_sys::rb_define_singleton_method(object, name.as_ptr(), Some(func), arity);
+        qnil()
+    })?;
+    Ok(())
+}
+
+fn c_long_len(len: usize) -> RbResult<c_long> {
+    c_long::try_from(len).map_err(|_| RubyErr::arg("length too large"))
+}

data/ext/zzq_native/src/wake.rs

@@ -0,0 +1,155 @@
+//! `ZZQ::Native::Wake`: how a Ruby fiber waits for a Rust future.
+//!
+//! A native call polls the future with a waker that writes one byte to a
+//! pipe. If the future is pending, Ruby waits for the pipe to turn
+//! readable, which suspends only the fiber under a fiber scheduler and
+//! releases the GVL otherwise, then polls again.
+
+use std::future::Future;
+use std::os::fd::RawFd;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::task::{Context, Poll, Waker};
+
+use rb_sys::VALUE;
+
+use crate::rb::{self, DataType, RbResult, RubyErr};
+
+static TYPE: DataType = DataType::new::<Wake>(c"ZZQ::Native::Wake");
+static CLASS: std::sync::OnceLock<usize> = std::sync::OnceLock::new();
+
+/// A pipe one fiber waits on.
+#[derive(Debug)]
+pub struct Wake {
+    pipe: Arc<Pipe>,
+    waker: Waker,
+}
+
+#[derive(Debug)]
+struct Pipe {
+    read_fd: RawFd,
+    write_fd: RawFd,
+    /// The fiber is about to wait, so a wake must write.
+    armed: AtomicBool,
+}
+
+impl std::task::Wake for Pipe {
+    fn wake(self: Arc<Self>) {
+        self.wake_by_ref();
+    }
+
+    fn wake_by_ref(self: &Arc<Self>) {
+        if self.armed.swap(false, Ordering::AcqRel) {
+            let byte = 1u8;
+            loop {
+                let n = unsafe { libc::write(self.write_fd, (&raw const byte).cast(), 1) };
+                // A full pipe holds a wake already.
+                if n >= 0 || std::io::Error::last_os_error().raw_os_error() != Some(libc::EINTR) {
+                    break;
+                }
+            }
+        }
+    }
+}
+
+impl Drop for Pipe {
+    fn drop(&mut self) {
+        unsafe {
+            libc::close(self.read_fd);
+            libc::close(self.write_fd);
+        }
+    }
+}
+
+impl Wake {
+    fn new() -> std::io::Result<Wake> {
+        let mut fds = [0; 2];
+        if unsafe { pipe(&mut fds) } != 0 {
+            return Err(std::io::Error::last_os_error());
+        }
+        let pipe = Arc::new(Pipe {
+            read_fd: fds[0],
+            write_fd: fds[1],
+            armed: AtomicBool::new(false),
+        });
+        let waker = Waker::from(pipe.clone());
+        Ok(Wake { pipe, waker })
+    }
+
+    /// Polls `fut`. While it is pending, a wake writes to the pipe.
+    pub fn poll<F: Future + ?Sized>(&self, fut: Pin<&mut F>) -> Poll<F::Output> {
+        self.pipe.armed.store(true, Ordering::Release);
+        let out = fut.poll(&mut Context::from_waker(&self.waker));
+        if out.is_ready() {
+            self.pipe.armed.store(false, Ordering::Release);
+        }
+        out
+    }
+
+    /// Reads the wakes written so far.
+    fn clear(&self) {
+        let mut buf = [0u8; 64];
+        loop {
+            let n = unsafe { libc::read(self.pipe.read_fd, buf.as_mut_ptr().cast(), buf.len()) };
+            if n > 0 {
+                continue;
+            }
+            if n < 0 && std::io::Error::last_os_error().raw_os_error() == Some(libc::EINTR) {
+                continue;
+            }
+            break;
+        }
+    }
+}
+
+#[cfg(any(target_os = "linux", target_os = "android"))]
+unsafe fn pipe(fds: &mut [RawFd; 2]) -> i32 {
+    unsafe { libc::pipe2(fds.as_mut_ptr(), libc::O_NONBLOCK | libc::O_CLOEXEC) }
+}
+
+#[cfg(all(unix, not(any(target_os = "linux", target_os = "android"))))]
+unsafe fn pipe(fds: &mut [RawFd; 2]) -> i32 {
+    let ret = unsafe { libc::pipe(fds.as_mut_ptr()) };
+    if ret == 0 {
+        for fd in *fds {
+            unsafe {
+                libc::fcntl(fd, libc::F_SETFL, libc::O_NONBLOCK);
+                libc::fcntl(fd, libc::F_SETFD, libc::FD_CLOEXEC);
+            }
+        }
+    }
+    ret
+}
+
+/// The `Wake` inside `value`.
+pub fn get(value: VALUE) -> RbResult<&'static Wake> {
+    unsafe { TYPE.get(value) }
+}
+
+unsafe extern "C" fn wake_new(_class: VALUE) -> VALUE {
+    rb::wrap(|| {
+        let wake = Wake::new().map_err(|e| RubyErr::runtime(format!("pipe failed: {e}")))?;
+        TYPE.wrap(*CLASS.get().expect("registered") as VALUE, wake)
+    })
+}
+
+unsafe extern "C" fn wake_fd(this: VALUE) -> VALUE {
+    rb::wrap(|| Ok(rb::u64_value(get(this)?.pipe.read_fd as u64)))
+}
+
+unsafe extern "C" fn wake_clear(this: VALUE) -> VALUE {
+    rb::wrap(|| {
+        get(this)?.clear();
+        Ok(rb::qnil())
+    })
+}
+
+pub fn register(native: VALUE) -> RbResult<()> {
+    let class = rb::define_class_under(native, c"Wake")?;
+    let _ = CLASS.set(class as usize);
+    rb::define_singleton_method(class, c"new", wake_new as *const (), 0)?;
+    rb::define_method(class, c"fd", wake_fd as *const (), 0)?;
+    rb::define_method(class, c"clear", wake_clear as *const (), 0)?;
+    Ok(())
+}

data/lib/zzq/broker.rb

@@ -1,34 +1,103 @@
 # frozen_string_literal: true
 
-require_relative "socket"
-
 module ZZQ
-  # MQTT broker. Owns the session map (by client id), retained-message
-  # store, topic trie, and shared-subscription groups.
+  # An MQTT 3.1.1 and 5.0 broker with an MQTT-SN gateway on +udp://+. It
+  # runs on the process's IO lanes; see {ZZQ.io_threads=}.
   #
-  # M3 stub: constructor + {#build_routing}. CONNECT handling,
-  # subscription matching, and retained store come in M7.
-  class Broker < Socket
-    def build_routing(engine)
-      Routing::Broker.new(engine)
+  # @example
+  #   broker = ZZQ::Broker.new
+  #   broker.bind("mqtt://0.0.0.0:1883")
+  class Broker
+    OPTIONS = %i[
+      max_packet_size max_inflight max_queued receive_maximum max_subscriptions max_retained
+      max_topic_levels topic_alias_maximum max_session_expiry max_connections max_keep_alive
+      connect_timeout sys_interval persistence tls
+    ].freeze
+
+    # Starts a broker and binds it. With a block, yields it and closes it
+    # after.
+    #
+    # @param endpoint [String] see {#bind}
+    # @param options [Hash] see {#initialize}
+    # @return [Broker, Object] the broker, or the block's result
+    def self.bind(endpoint, **options)
+      broker = new(**options)
+      broker.bind(endpoint)
+      return broker unless block_given?
+
+      begin
+        yield broker
+      ensure
+        broker.close
+      end
     end
 
+    # @return [String, nil] the endpoint bound last
+    attr_reader :last_endpoint
 
-    # Number of currently-connected MQTT sessions.
-    def session_count = @engine.routing.session_count
+    # Starts a broker.
+    #
+    # @param options [Hash] limits as in zzq-broker's +BrokerOptions+, such
+    #   as +max_connections:+ or +max_queued:+; +max_keep_alive:+ and
+    #   +sys_interval:+ (seconds, nil for none); +connect_timeout:+
+    #   (seconds); +persistence:+ (path of a file for retained messages);
+    #   +tls:+ (+cert:+, +key:+, +client_ca:+ as PEM strings)
+    def initialize(**options)
+      opts = Options.check(options, OPTIONS)
+      @native = Waiting.await(Native::Broker.start(opts))
+      @closed = false
+    end
 
+    # Listens on an endpoint.
+    #
+    # @param endpoint [String] +mqtt://host:port+, +mqtts://+, +tcp://+,
+    #   +tls://+, +ws://+, +wss://+, +quic://+, +udp://+ (MQTT-SN),
+    #   +ipc://+ or +inproc://+; port 0 picks a free port
+    # @return [String] the bound endpoint, with the actual port
+    def bind(endpoint)
+      @last_endpoint = Waiting.await(native.bind(Options.endpoint(endpoint)))
+    end
+
+    # Publishes a message as the broker itself.
+    #
+    # @param topic [String]
+    # @param payload [String]
+    # @param qos [Integer]
+    # @param retain [Boolean]
+    # @return [nil]
+    def publish(topic, payload, qos: 0, retain: false)
+      payload = payload.to_s unless payload.is_a?(String)
+      native.publish(topic, payload, qos, retain)
+    end
+
+    # @return [Hash{Symbol => Integer}] counters summed over lanes
+    def stats
+      Waiting.await(native.stats)
+    end
 
-    # Inject a {ZZQ::Message} into the broker's delivery path as if it
-    # had arrived via a PUBLISH packet. Fans out to every matching
-    # subscriber. Use this to bridge non-MQTT inputs (NNQ, OMQ, a
-    # file) into broker topics.
-    def ingest(message)
-      raise NotInAsyncContext unless Async::Task.current?
-      @engine.routing.dispatch_message(message)
+    # Stops the broker and waits until its connections are closed.
+    #
+    # @return [nil]
+    def close
+      return if @closed
+
+      @closed = true
+      op = @native.shutdown
+      Waiting.await(op) if op
       nil
     end
-    alias_method :<<, :ingest
+
+    # @return [Boolean]
+    def closed?
+      @closed
+    end
+
+    private
+
+    def native
+      raise ClosedError, "broker closed" if @closed
+
+      @native
+    end
   end
 end
-
-require_relative "routing/broker"