zus_rs/

lib.rs

//! # ZUS-RS: ZUS RPC Framework for Rust
//!
//! `zus-rs` is a high-performance RPC framework with cross-language compatibility
//! (Rust, Java, C++). It provides service discovery via ZooServer and supports
//! QuickLZ/Snappy compression.
//!
//! ## Features
//!
//! - **Cross-language RPC**: Compatible with Java and C++ implementations
//! - **Protocol Buffer serialization**: Efficient binary protocol
//! - **Compression**: QuickLZ (default) and Snappy support
//! - **Service Discovery**: Integration with ZooServer
//! - **Async I/O**: Built on Tokio runtime
//! - **Type-safe**: Full Rust type safety with protobuf definitions
//!
//! ## Quick Start
//!
//! ### Client Example
//!
//! ```toml
//! [dependencies]
//! zus-rs = { version = "1.1.4", features = ["client"] }
//! tokio = { version = "1.35", features = ["full"] }
//! ```
//!
//! ```rust,no_run
//! # // Note: This is a documentation example showing the conceptual API
//! # // The actual types may differ - check the API docs for details
//! use zus_rs::prelude::*;
//!
//! # #[tokio::main]
//! # async fn main() -> anyhow::Result<()> {
//! #     // This is a conceptual example
//! #     // See zus-examples/ for working code
//! #     Ok(())
//! # }
//! ```
//!
//! ### Server Example
//!
//! ```toml
//! [dependencies]
//! zus-rs = { version = "1.1.4", features = ["server"] }
//! tokio = { version = "1.35", features = ["full"] }
//! ```
//!
//! ```rust,no_run
//! # // Note: This is a documentation example showing the conceptual API
//! # // See zus-examples/ for working server implementations
//! use zus_rs::prelude::*;
//!
//! # #[tokio::main]
//! # async fn main() -> anyhow::Result<()> {
//! #     // This is a conceptual example
//! #     // See zus-rpc-server documentation for actual API
//! #     Ok(())
//! # }
//! ```
//!
//! ### Protocol Only (No RPC Runtime)
//!
//! ```toml
//! [dependencies]
//! zus-rs = { version = "1.1.4", features = ["protocol"] }
//! ```
//!
//! ```rust
//! use zus_rs::prelude::*;
//!
//! // Create protocol message
//! let request = ZooRegisterClientRequest {};
//!
//! // Use compression types
//! let _compressor = Compressor::default();
//! let _comp_type = CompressionType::QuickLZ;
//! ```
//!
//! ## Feature Flags
//!
//! Choose the features you need:
//!
//! | Feature | Description | Includes |
//! |---------|-------------|----------|
//! | `default` | Client + Server + Protocol | Everything except runtime |
//! | `minimal` | Protocol definitions only | Just `zus-proto` |
//! | `protocol` | Protocol + Codec + Compression | `zus-proto`, `zus-common` |
//! | `client` | RPC client functionality | `protocol`, `zus-rpc-client`, `zus-discovery` |
//! | `server` | RPC server functionality | `protocol`, `zus-rpc-server`, `zus-discovery`, `zus-macros` |
//! | `full` | Everything | `client` + `server` |
//!
//! ## Examples
//!
//! ```toml
//! # Just client
//! [dependencies]
//! zus-rs = { version = "1.1.4", features = ["client"] }
//!
//! # Just server
//! [dependencies]
//! zus-rs = { version = "1.1.4", features = ["server"] }
//!
//! # Protocol only (no RPC runtime)
//! [dependencies]
//! zus-rs = { version = "1.1.4", features = ["protocol"] }
//!
//! # Minimal (just message definitions)
//! [dependencies]
//! zus-rs = { version = "1.1.4", features = ["minimal"] }
//!
//! # Everything (default)
//! [dependencies]
//! zus-rs = "1.1.4"
//! ```
//!
//! ## Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────┐
//! │           zus-rs (convenience)          │
//! └─────────────────────────────────────────┘
//!                    │
//!        ┌───────────┼───────────┐
//!        │           │           │
//!        ↓           ↓           ↓
//!   ┌────────┐  ┌────────┐  ┌────────┐
//!   │ client │  │ server │  │protocol│
//!   └────────┘  └────────┘  └────────┘
//!        │           │           │
//!        ↓           ↓           ↓
//!   ┌─────────────────────────────────┐
//!   │  zus-rpc-{client,server}        │
//!   │  zus-discovery                  │
//!   │  zus-common (codec/compression) │
//!   │  zus-proto (protobuf messages)  │
//!   └─────────────────────────────────┘
//! ```
//!
//! ## Cross-Language Compatibility
//!
//! ZUS-RS is wire-compatible with:
//! - **Java**: ZUS Java client/server (tested with integration tests)
//! - **C++**: ZUS C++ client/server (production-tested)
//!
//! All implementations share:
//! - Same 40-byte RPC header format
//! - Same Protocol Buffer definitions
//! - Same compression algorithms (QuickLZ, Snappy)
//! - Same CRC validation (CRC16 header, CRC32 data)
//!
//! See `tests/cross-language/` for comprehensive cross-language test suite.
//!
//! ## Documentation
//!
//! - [Getting Started Guide](../docs/GETTING_STARTED.md)
//! - [Protocol Specification](../docs/protocol&wireformat.md)
//! - [ZooServer Architecture](../docs/ZOOSERVER_ARCHITECTURE.md)
//! - [Cross-Language Tests](../tests/cross-language/README.md)

#![cfg_attr(docsrs, feature(doc_cfg))]

// Re-export core protocol definitions (always available)
pub use zus_proto as proto;

// Re-export common codec and compression (available with protocol, client, or server features)
#[cfg(feature = "protocol")]
#[cfg_attr(docsrs, doc(cfg(feature = "protocol")))]
pub use zus_common as common;

// Re-export service discovery (available with client or server features)
#[cfg(any(feature = "client", feature = "server"))]
#[cfg_attr(docsrs, doc(cfg(any(feature = "client", feature = "server"))))]
pub use zus_discovery as discovery;

// Re-export RPC client (available with client feature)
#[cfg(feature = "client")]
#[cfg_attr(docsrs, doc(cfg(feature = "client")))]
pub use zus_rpc_client as client;

// Re-export RPC server (available with server feature)
#[cfg(feature = "server")]
#[cfg_attr(docsrs, doc(cfg(feature = "server")))]
pub use zus_rpc_server as server;

// Re-export proc macros (available with server feature)
#[cfg(feature = "server")]
#[cfg_attr(docsrs, doc(cfg(feature = "server")))]
pub use zus_macros;

// Re-export commonly used types for convenience
#[cfg(any(feature = "client", feature = "server"))]
#[cfg_attr(docsrs, doc(cfg(any(feature = "client", feature = "server"))))]
pub use async_trait::async_trait;

// Type aliases for more intuitive API
/// Convenient type alias for `BaseRpcClient`
///
/// This is the main RPC client type for making service calls.
///
/// # Example
/// ```no_run
/// use zus_rs::RpcClient;
///
/// # #[tokio::main]
/// # async fn main() -> anyhow::Result<()> {
/// // Connect via TCP
/// let client = RpcClient::new("tcp://localhost:9527").await?;
///
/// // Or via ZooServer discovery
/// let client = RpcClient::new("zns://localhost:9528/zus/services/myservice/").await?;
/// # Ok(())
/// # }
/// ```
#[cfg(feature = "client")]
#[cfg_attr(docsrs, doc(cfg(feature = "client")))]
pub use zus_rpc_client::BaseRpcClient as RpcClient;

/// Convenient type alias for `ZusServerManager`
///
/// This is the main RPC server type for hosting services.
///
/// # Example
/// ```no_run
/// use zus_rs::{RpcServer, prelude::*};
/// use bytes::Bytes;
/// use std::sync::Arc;
///
/// struct MyService;
///
/// #[async_trait]
/// impl Service for MyService {
///     fn service_name(&self) -> &str { "MyService" }
///
///     async fn do_work(
///         &self,
///         method: &str,
///         params: Bytes,
///         _ctx: zus_rpc_server::RequestContext,
///     ) -> zus_common::Result<Bytes> {
///         Ok(params)
///     }
/// }
///
/// # #[tokio::main]
/// # async fn main() -> anyhow::Result<()> {
/// let mut server = RpcServer::new("0.0.0.0".to_string(), 9527);
/// server.register_service(Arc::new(MyService));
/// server.start().await?;
/// # Ok(())
/// # }
/// ```
#[cfg(feature = "server")]
#[cfg_attr(docsrs, doc(cfg(feature = "server")))]
pub use zus_rpc_server::ZusServerManager as RpcServer;

// Mobile protocol type aliases
/// Mobile RPC Client (16-byte header protocol)
///
/// Use this for connecting to mobile-optimized servers.
#[cfg(feature = "client")]
#[cfg_attr(docsrs, doc(cfg(feature = "client")))]
pub use zus_rpc_client::MobileRpcClient;

/// Mobile RPC Server (16-byte header protocol)
///
/// Use this for mobile clients with bandwidth constraints.
#[cfg(feature = "server")]
#[cfg_attr(docsrs, doc(cfg(feature = "server")))]
pub use zus_rpc_server::MobileRpcServer;

// Prelude module with commonly used imports
pub mod prelude {
  //! Commonly used types and traits
  //!
  //! ```rust
  //! use zus_rs::prelude::*;
  //! ```

  // Core protocol types
  pub use crate::proto::{
    ZooCreatePathRequest, ZooCreatePathResponse, ZooGetPathChildRequest, ZooGetPathChildResponse,
    ZooRegisterClientRequest, ZooRegisterClientResponse, ZooSyncPathRequest, ZooSyncPathResponse,
  };

  // Common compression (Compressor, CompressType)
  #[cfg(feature = "protocol")]
  pub use crate::common::compression::{CompressionType, Compressor};

  // Client types (re-export main client type and convenient alias)
  #[cfg(feature = "client")]
  pub use crate::client;

  #[cfg(feature = "client")]
  pub use crate::RpcClient;

  // Server types (re-export server module and convenient alias)
  #[cfg(feature = "server")]
  pub use crate::server;

  #[cfg(feature = "server")]
  pub use crate::RpcServer;

  #[cfg(feature = "server")]
  pub use crate::server::Service;

  // Mobile types
  #[cfg(feature = "client")]
  pub use crate::MobileRpcClient;

  #[cfg(feature = "server")]
  pub use crate::MobileRpcServer;

  // Async trait
  #[cfg(any(feature = "client", feature = "server"))]
  pub use crate::async_trait;
}

#[cfg(test)]
mod tests {
  #[test]
  fn test_proto_available() {
    // Protocol should always be available
    use crate::proto::ZooRegisterClientRequest;
    let _req = ZooRegisterClientRequest {};
  }

  #[cfg(feature = "protocol")]
  #[test]
  fn test_common_available() {
    use crate::common::compression::CompressionType;
    let _compression = CompressionType::QuickLZ;
  }

  #[cfg(feature = "client")]
  #[test]
  fn test_client_module_available() {
    // Just check that client module is accessible
    #[allow(unused_imports)]
    use crate::client;
  }

  #[cfg(feature = "server")]
  #[test]
  fn test_server_module_available() {
    // Just check that server module is accessible
    // Service is a trait, so we can't instantiate it
    // Just verify the module exists
    #[allow(unused_imports)]
    use crate::server;
  }
}