open-net 0.3.5

A cross-platform async networking library for Rust with HTTP and WebSocket clients, network status monitoring, configurable retries, WebSocket reconnection and heartbeats, and managed client lifecycles. Reuse common networking infrastructure across applications to avoid repeated implementation and debugging, helping save development time and AI coding tokens.
Documentation
//! macOS native network-change hints, independent of a Swift toolchain.
//!
//! The callback deliberately ignores the path. Its only responsibility is a
//! non-blocking hint to resample the authoritative `netwatch::State`.

use std::ffi::{c_int, c_void};
use std::io::{self, Write};
use std::panic::{catch_unwind, AssertUnwindSafe};
use std::ptr::{self, NonNull};

use super::super::refresh_trigger::RefreshTrigger;

#[cfg(test)]
#[path = "macos_tests.rs"]
mod tests;

// 原生队列使用的 C ABI 回调;参数借用 Rust 保持存活的刷新触发器。
type NativeCallback = unsafe extern "C" fn(*mut c_void);

unsafe extern "C" {
    // 启动原生监听;context 须存活至 stop 返回,output 接收唯一句柄,返回原生状态码。
    fn open_net_path_monitor_start(
        notify: Option<NativeCallback>,
        context: *mut c_void,
        output: *mut *mut c_void,
    ) -> c_int;
    // 在私有回调队列之外同步停止并释放句柄,等待所有回调结束后才归还 context。
    fn open_net_path_monitor_stop(monitor: *mut c_void);
}

/// Private ABI boundary, also injectable by the lifecycle tests.
///
/// Start may borrow context until stop returns. A null output must never retain
/// context; each non-null output must accept exactly one synchronous stop.
/// Stop must finish every callback before returning and may run on any thread
/// except the private callback queue. These requirements also apply to tests.
// 可注入的原生 ABI 函数表;生产实现和测试替身必须满足相同的所有权与停止约定。
#[derive(Clone, Copy, Debug)]
struct NativeApi {
    // 初始化入口;非空输出句柄交给 Rust 唯一持有,空输出不得继续借用 context。
    start: unsafe extern "C" fn(Option<NativeCallback>, *mut c_void, *mut *mut c_void) -> c_int,
    // 与 start 配对的回收入口;每个非空句柄仅调用一次,返回前完成所有回调。
    stop: unsafe extern "C" fn(*mut c_void),
}

// 原生监听句柄的唯一 Rust 所有者,将回调上下文的生存期绑定到同步停止之后。
#[derive(Debug)]
pub(crate) struct NativeNetworkMonitor {
    // 成功启动获得的非空原生句柄;仅由当前所有者在 Drop 中回收。
    handle: NonNull<c_void>,
    // 创建该句柄时使用的函数表,确保释放使用匹配的实现。
    api: NativeApi,
    // 保持回调上下文地址稳定;Drop 先停止原生来源,再由 Rust 释放此字段。
    // The allocation stays stable across moves. Drop stops the native source
    // before Rust drops this field, including an update racing cancellation.
    _trigger: Box<RefreshTrigger>,
}

// SAFETY: The handle has one owner, and Network.framework delivers callbacks
// on a private serial queue. Stop synchronizes with that queue on any owning
// thread. The callback only borrows the Send + Sync RefreshTrigger.
// 允许转移所有权到其他线程;安全性依赖唯一句柄和 stop 对私有队列的同步。
unsafe impl Send for NativeNetworkMonitor {}
// SAFETY: Shared references cannot access or mutate the native handle. Stop
// requires exclusive ownership through Drop; the trigger itself is Sync.
// 共享引用不操作原生句柄;回调只借用线程安全的 RefreshTrigger。
unsafe impl Sync for NativeNetworkMonitor {}

impl NativeNetworkMonitor {
    // 使用真实 C 适配层启动网络路径监听,只发送重采样提示而不判断网络在线状态。
    pub(crate) fn start(trigger: RefreshTrigger) -> io::Result<Self> {
        Self::start_with(
            trigger,
            NativeApi {
                start: open_net_path_monitor_start,
                stop: open_net_path_monitor_stop,
            },
        )
    }

    // 固定触发器地址后调用可注入的启动入口;失败时先回收部分句柄,再释放上下文。
    fn start_with(trigger: RefreshTrigger, api: NativeApi) -> io::Result<Self> {
        let trigger = Box::new(trigger);
        let context = ptr::from_ref(trigger.as_ref()).cast_mut().cast();
        let mut handle = ptr::null_mut();
        // SAFETY: The output is writable and context points to a stable, live
        // allocation owned here. NativeApi follows the private ABI contract.
        let status = unsafe { (api.start)(Some(notify), context, &mut handle) };
        if status != 0 {
            if !handle.is_null() {
                // SAFETY: Defensively reclaim a partial native handle while
                // context is still alive, using its matching stop function.
                unsafe { (api.stop)(handle) };
            }
            return Err(io::Error::other(format!(
                "macOS network-change monitor initialization failed (native status {status})"
            )));
        }
        let handle = NonNull::new(handle).ok_or_else(|| {
            io::Error::other("macOS network-change monitor returned a null handle")
        })?;
        Ok(Self {
            handle,
            api,
            _trigger: trigger,
        })
    }
}

impl Drop for NativeNetworkMonitor {
    // 同步停止原生源,确保已排队或正执行的回调不再访问随后释放的触发器。
    // 此释放过程可能等待取消完成,不能在私有原生回调队列上执行。
    fn drop(&mut self) {
        // SAFETY: This is the unique handle owner. The callback only notifies
        // a channel and cannot drop this owner on its private native queue.
        // Stop waits for cancellation completion and drains that queue before
        // returning, so no callback can access _trigger after it is dropped.
        unsafe { (self.api.stop)(self.handle.as_ptr()) };
    }
}

// 将原生通知转为不等待容量的合并提示;空上下文直接返回,隔离可展开的 panic。
// 非空 context 必须指向仍存活的 RefreshTrigger,不能在此回调中停止其原生所有者。
unsafe extern "C" fn notify(context: *mut c_void) {
    if context.is_null() {
        return;
    }
    // Contain unwinding at the ABI boundary. No application callback runs here.
    let result = catch_unwind(AssertUnwindSafe(|| {
        // SAFETY: The native source borrows this allocation only between start
        // and synchronous stop. It never changes the pointer or its contents.
        let trigger = unsafe { &*context.cast::<RefreshTrigger>() };
        let _ = trigger.notify();
    }));
    if result.is_err() {
        // Fallible I/O avoids a second unwind while diagnosing an ABI failure.
        let _ = io::stderr()
            .lock()
            .write_all(b"open-net: macOS network-change callback failed\n");
    }
}