simplejrpc 0.1.0

Unix-socket JSON-RPC 2.0 SDK with middleware, config, and validation
Documentation
//! Declarative macros to cut boilerplate.
//!
//! | Macro | Purpose |
//! |-------|---------|
//! | `define_rpc_codes!` | Custom numeric codes (message = type name) |
//! | `define_rpc_codes_with_msg!` | Custom codes with explicit messages |
//! | `register_methods!` | Register many handlers on a builder |
//! | `rpc_handler!` | Document/emphasize handler closure shape |
//! | `validate_object!` | Inline field validation |
//!
//! Each macro below includes runnable `# Examples`.
//!
//! # Quick tour
//!
//! ```
//! use simplejrpc::{define_rpc_codes_with_msg, register_methods, validate_object, Server};
//! use simplejrpc::valid::FieldRule;
//! use serde_json::json;
//!
//! define_rpc_codes_with_msg! {
//!     QuotaExceeded => (200429, "quota exceeded"),
//! }
//! assert_eq!(QuotaExceeded.message(), "quota exceeded");
//!
//! let _server = register_methods!(Server::builder(), {
//!     "ping" => |_| async { Ok(json!("pong")) },
//! }).build();
//!
//! assert!(validate_object!(&json!({"age": 1}), "age" => FieldRule::Range { min: 18, max: 60 }).is_err());
//! ```

/// Define custom RPC business codes.
///
/// ```
/// use simplejrpc::define_rpc_codes;
/// define_rpc_codes! {
///     /// Payment failed
///     PaymentFailed => 200402,
/// }
/// assert_eq!(PaymentFailed.code(), 200402);
/// // Default message is the type name; use `define_rpc_codes_with_msg!` for human text.
/// assert_eq!(PaymentFailed.message(), "PaymentFailed");
/// ```
#[macro_export]
macro_rules! define_rpc_codes {
    (
        $(
            $(#[$meta:meta])*
            $name:ident => $code:expr
        ),+ $(,)?
    ) => {
        $(
            $(#[$meta])*
            #[derive(Debug, Clone, Copy, PartialEq, Eq)]
            pub struct $name;

            impl $name {
                /// Numeric business code (`200xxx` space), used with [`simplejrpc::Error`].
                pub const fn code(self) -> i32 { $code }
                /// Default message = type name (`stringify!`); prefer
                /// [`simplejrpc::define_rpc_codes_with_msg`] for human copy.
                pub fn message(self) -> &'static str {
                    stringify!($name)
                }
            }
        )+
    };
}

/// Register multiple methods on a server builder.
///
/// ```
/// use simplejrpc::{register_methods, Server};
/// use serde_json::json;
///
/// let server = register_methods!(Server::builder(), {
///     "ping" => |_| async { Ok(json!("pong")) },
///     "echo" => |req| async move { Ok(req.params_raw().clone()) },
/// }).build();
/// let _ = server;
/// ```
#[macro_export]
macro_rules! register_methods {
    ($builder:expr, { $($method:literal => $handler:expr),+ $(,)? }) => {{
        let mut __b = $builder;
        $(
            __b = __b.register($method, $handler);
        )+
        __b
    }};
}

/// Identity macro that documents the expected handler closure shape.
///
/// Expands to the closure unchanged (`$closure`). Useful in examples and at
/// call sites to make the `Request → Result<Value>` async shape obvious; it
/// does **not** change types or add runtime behavior.
///
/// ```
/// use simplejrpc::{rpc_handler, Error, Request};
/// use serde_json::{json, Value};
///
/// let h = rpc_handler!(|req: Request| async move {
///     Ok::<Value, Error>(json!({ "method": req.method() }))
/// });
/// # let _ = h;
/// ```
#[macro_export]
macro_rules! rpc_handler {
    ($closure:expr) => {
        $closure
    };
}

/// Validate a JSON object with inline rules.
///
/// ```
/// use simplejrpc::{validate_object, valid::FieldRule};
/// use serde_json::json;
///
/// let r = validate_object!(
///     &json!({"age": 10}),
///     "age" => FieldRule::Range { min: 18, max: 60 },
/// );
/// assert!(r.is_err());
/// ```
#[macro_export]
macro_rules! validate_object {
    ($obj:expr, $($field:literal => $rule:expr),+ $(,)?) => {{
        let __v = $crate::valid::Validator::new()
            $( .field($field, $rule) )+;
        __v.validate($obj)
    }};
}

// Improve define_rpc_codes message: use a second form that takes explicit messages.
/// Define codes **with** explicit messages (preferred for production).
///
/// ```
/// use simplejrpc::define_rpc_codes_with_msg;
/// define_rpc_codes_with_msg! {
///     UserBanned => (200451, "user is banned"),
/// }
/// assert_eq!(UserBanned.message(), "user is banned");
/// ```
#[macro_export]
macro_rules! define_rpc_codes_with_msg {
    (
        $(
            $(#[$meta:meta])*
            $name:ident => ($code:expr, $msg:expr)
        ),+ $(,)?
    ) => {
        $(
            $(#[$meta])*
            #[derive(Debug, Clone, Copy, PartialEq, Eq)]
            pub struct $name;

            impl $name {
                /// Numeric business code (`200xxx` space).
                pub const fn code(self) -> i32 { $code }
                /// Human-readable message for clients / logs.
                pub const fn message(self) -> &'static str { $msg }
            }
        )+
    };
}