rustzmq2 0.1.0

#![recursion_limit = "1024"]

//! Native async Rust implementation of [ZeroMQ](https://zeromq.org/).
//!
//! The [ZeroMQ guide](https://zguide.zeromq.org/) is the canonical
//! reference for the messaging patterns below; this crate's API
//! mirrors libzmq's so chapters of the guide apply directly.
//!
//! Wire protocol: [ZMTP 3.1](https://rfc.zeromq.org/spec/23/).
//!
//! # Quick start
//!
//! ```toml
//! [dependencies]
//! rustzmq2 = "0.1"
//! tokio = { version = "1", features = ["full"] }
//! ```
//!
//! ```rust,no_run
//! use rustzmq2::prelude::*;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let mut rep = rustzmq2::RepSocket::new();
//!     rep.bind("tcp://127.0.0.1:5555").await?;
//!     let msg: String = rep.recv().await?.try_into()?;
//!     rep.send(format!("{msg} world")).await?;
//!     Ok(())
//! }
//! ```
//!
//! # Socket types
//!
//! | Pattern | Types |
//! |---|---|
//! | Request / Reply | [`ReqSocket`], [`RepSocket`], [`DealerSocket`], [`RouterSocket`] |
//! | Publish / Subscribe | [`PubSocket`], [`SubSocket`], [`XPubSocket`], [`XSubSocket`] |
//! | Pipeline | [`PushSocket`], [`PullSocket`] |
//! | Peer-to-peer | [`PairSocket`] |
//! | Scatter / Gather | [`ScatterSocket`], [`GatherSocket`] |
//! | Channel | [`ChannelSocket`] |
//!
//! All socket types implement [`Socket`] (for `bind` / `connect`) and either
//! [`SocketSend`], [`SocketRecv`], or both. Import them via [`prelude`]:
//!
//! ```rust,no_run
//! use rustzmq2::prelude::*;
//! ```
//!
//! # Configuration
//!
//! Use [`SocketBuilder`] (via `SocketType::builder()`) to configure security,
//! heartbeats, and peer identity before creating a socket:
//!
//! ```rust,no_run
//! use rustzmq2::{RepSocket, Socket};
//!
//! let mut rep = RepSocket::builder()
//!     .plain_server()
//!     .zap_domain("myapp")
//!     .build();
//! ```
//!
//! # Security
//!
//! The full ZMTP security stack is supported: NULL (default), PLAIN, CURVE,
//! and ZAP. See [`SocketBuilder`] for configuration methods and
//! [`set_zap_handler`] / [`clear_zap_handler`] for ZAP.

#[cfg(not(any(feature = "tokio", feature = "smol")))]
compile_error!("at least one runtime feature must be enabled: `tokio` or `smol`");

mod async_rt;
mod bench_harness;
mod codec;
mod endpoint;
mod engine;
mod error;
mod io_compat;
mod mechanism;
mod message;
mod peer_identity;
mod proxy;
mod reconnect;
mod socket;
mod task_handle;
mod transport;
mod wake_counter;
mod zap;

#[doc(hidden)]
pub mod __async_rt {
    //! DO NOT USE! PRIVATE IMPLEMENTATION, EXPOSED ONLY FOR INTEGRATION TESTS.
    pub use super::async_rt::*;
}

#[doc(hidden)]
pub mod __bench {
    //! DO NOT USE! PRIVATE IMPLEMENTATION, EXPOSED ONLY FOR MICROBENCHMARKS.
    //!
    //! Stability: none. Anything here may be removed without notice.
    pub use super::bench_harness::*;
    pub use super::wake_counter::dump_and_reset as wake_dump_and_reset;
}

pub use crate::endpoint::{Endpoint, Host, Transport};
pub use crate::error::{
    CodecError, EndpointError, JoinError, TaskError, ZmqEmptyMessageError, ZmqError, ZmqResult,
};
pub use crate::message::*;
pub use crate::peer_identity::PeerIdentity;
pub use crate::proxy::{proxy, proxy_with_capture};
/// Sealed role-marker traits that gate kind-specific builder methods.
/// Used only in trait bounds; you should never need to name these directly.
pub use crate::socket::family;
pub use crate::socket::kind::channel::*;
pub use crate::socket::kind::dealer::*;
pub use crate::socket::kind::gather::*;
pub use crate::socket::kind::pair::*;
pub use crate::socket::kind::pull::*;
pub use crate::socket::kind::push::*;
pub use crate::socket::kind::r#pub::*;
pub use crate::socket::kind::rep::*;
pub use crate::socket::kind::req::*;
pub use crate::socket::kind::router::*;
pub use crate::socket::kind::scatter::*;
pub use crate::socket::kind::sub::*;
pub use crate::socket::kind::xpub::*;
pub use crate::socket::kind::xsub::*;
pub use crate::socket::{
    CaptureSocket, MultiPeerBackend, ReconnectStop, Socket, SocketBackend, SocketBuilder,
    SocketEvent, SocketOptions, SocketRecv, SocketSend, SocketType,
};
pub use crate::zap::{clear_zap_handler, set_zap_handler, ZapRequest, ZapResponse};

pub mod prelude {
    //! Convenience re-exports. `use rustzmq2::prelude::*;` brings in the
    //! traits and types needed for nearly every program.
    //!
    //! What you get:
    //! - Core traits: [`Socket`], [`SocketSend`], [`SocketRecv`]
    //! - Endpoint type: [`Endpoint`] (use stdlib `TryFrom`/`TryInto` for
    //!   string-to-endpoint parsing — `bind`/`connect` accept anything that
    //!   converts into an `Endpoint`)
    //! - Message type: [`ZmqMessage`]
    //! - Error types: [`ZmqError`], [`ZmqResult`]
    //! - Routing: [`PeerIdentity`] (used by ROUTER/DEALER and monitor events),
    //!   [`RouterEnvelope`] (returned by ROUTER `recv_envelope`),
    //!   [`XPubEvent`] (returned by XPUB `recv_event`)
    //! - Monitor: [`SocketEvent`] (yielded by [`Socket::monitor`])
    //! - Reconnect tuning: [`ReconnectStop`] flag set
    //!
    //! Socket types (`ReqSocket`, `PubSocket`, …) are **not** re-exported here
    //! — reach for them as `rustzmq2::ReqSocket` to keep the prelude import
    //! minimal.
    //!
    //! [`Socket`]: crate::Socket
    //! [`SocketSend`]: crate::SocketSend
    //! [`SocketRecv`]: crate::SocketRecv
    //! [`Socket::monitor`]: crate::Socket::monitor
    //! [`Endpoint`]: crate::Endpoint
    //! [`ZmqMessage`]: crate::ZmqMessage
    //! [`ZmqError`]: crate::ZmqError
    //! [`ZmqResult`]: crate::ZmqResult
    //! [`PeerIdentity`]: crate::PeerIdentity
    //! [`RouterEnvelope`]: crate::RouterEnvelope
    //! [`SocketEvent`]: crate::SocketEvent
    //! [`ReconnectStop`]: crate::ReconnectStop
    //! [`XPubEvent`]: crate::XPubEvent
    pub use crate::{
        Endpoint, PeerIdentity, ReconnectStop, RouterEnvelope, Socket, SocketEvent, SocketRecv,
        SocketSend, XPubEvent, ZmqError, ZmqMessage, ZmqResult,
    };
}