ray/

lib.rs

#![forbid(unsafe_code)]
//! Rust client for the Ray debugging app.
//!
//! Install (package name is `ray-dbg`, crate is `ray`):
//!
//! ```toml
//! [dependencies]
//! ray = { version = "0.1", package = "ray-dbg" }
//! ```
//!
//! Fluent chaining is the intended style:
//!
//! ```no_run
//! use ray::ray;
//!
//! ray!("Hello from Rust").green().label("init");
//! ```
//!
//! Ray app workflow (screens, labels, visuals):
//!
//! ```no_run
//! use ray::ray;
//! use serde::Serialize;
//!
//! #[derive(Serialize)]
//! struct User {
//!     id: u64,
//!     name: &'static str,
//! }
//!
//! let user = User { id: 1, name: "Ada" };
//! ray!().new_screen("Checkout flow");
//! ray!(&user).label("user").green();
//! ray!().table(&user).label("user table");
//! ray!().image("https://example.com/avatar.png").label("avatar");
//! ray!().separator();
//! ray!().link("https://myray.app").label("Ray docs");
//! ray!().notify("Checkout complete");
//! ```
//!
//! Send multiple values in one call:
//!
//! ```no_run
//! use ray::ray;
//!
//! ray!("first", "second", "third");
//! ```
//!
//! See the caller or full trace:
//!
//! ```no_run
//! use ray::ray;
//!
//! ray!().caller();
//! ray!().trace();
//! ```
//!
//! Render custom payloads (JSON, HTML, XML, files, URLs):
//!
//! ```no_run
//! use ray::ray;
//! use serde::Serialize;
//!
//! #[derive(Serialize)]
//! struct Event {
//!     name: String,
//! }
//!
//! let event = Event { name: "started".into() };
//! ray!().to_json(&event).label("json");
//! ray!().html("<strong>bold html</strong>");
//! ray!().xml("<root />");
//! ray!().file("Cargo.toml");
//! ray!().url("https://example.com");
//! ```
//!
//! `ray_dbg!` mirrors `dbg!` by labeling the expression and returning it:
//! It uses `Debug` formatting, so any `Debug` value works.
//!
//! ```no_run
//! use ray::ray_dbg;
//!
//! let value = ray_dbg!(2 + 2);
//! assert_eq!(value, 4);
//! ```
//!
//! Send panic details to Ray:
//!
//! ```no_run
//! ray::panic_hook();
//! ```
//!
//! Pause execution (no-op stub):
//!
//! ```no_run
//! use ray::ray;
//!
//! ray!().pause();
//! ```
//!
//! Halt execution with `die` or `rd!`:
//!
//! ```no_run
//! use ray::{ray, rd};
//!
//! ray!("fatal").die();
//! rd!("fatal");
//! ```
//!
//! Count executions and read counters:
//!
//! ```no_run
//! use ray::ray;
//!
//! for _ in 0..3 {
//!     ray!().count();
//! }
//! for _ in 0..2 {
//!     ray!().count_named("first");
//! }
//! if ray!().counter_value("first") == 2 {
//!     ray!("counter value is two!");
//! }
//! ```
//!
//! Measure time and memory usage between calls:
//!
//! ```no_run
//! use ray::ray;
//! use std::thread;
//! use std::time::Duration;
//!
//! ray!().measure();
//! thread::sleep(Duration::from_millis(200));
//! ray!().measure();
//! ```
//!
//! Display the class name of an object:
//!
//! ```no_run
//! use ray::ray;
//!
//! let value = vec![1, 2, 3];
//! ray!().class_name(&value);
//! ```
//!
//! Update a single entry by reusing the same `Ray` handle:
//!
//! ```no_run
//! use ray::ray;
//!
//! let mut ray = ray!("counting down");
//! for n in (1..=3).rev() {
//!     ray = ray.send(&n);
//! }
//! ray.green().small().label("count");
//! ```
//!
//! Conditionally show items with `when`:
//!
//! ```no_run
//! use ray::ray;
//!
//! ray!().when(true, |ray| ray.log(&"will be shown"));
//! ray!().when(false, |ray| ray.log(&"will be hidden"));
//! ```
//!
//! Return a value while still sending it to Ray:
//!
//! ```no_run
//! use ray::ray;
//!
//! let value = ray!().pass("return value");
//! assert_eq!(value, "return value");
//! ```
//!
//! Show Rust runtime/build info (alias: `phpinfo`):
//!
//! ```no_run
//! use ray::ray;
//!
//! ray!().rust_info();
//! ray!().phpinfo_with_env(["RUST_LOG", "PATH"]);
//! ```
//!
//! Display exceptions and handle fallible callables:
//!
//! ```no_run
//! use ray::ray;
//!
//! let err = std::io::Error::new(std::io::ErrorKind::Other, "boom");
//! ray!().exception(&err);
//! ray!().catch(|| -> Result<(), std::io::Error> {
//!     Err(std::io::Error::new(std::io::ErrorKind::Other, "boom"))
//! });
//! ```
//!
//! Show raw Debug output:
//!
//! ```no_run
//! use ray::ray;
//!
//! let value = vec![1, 2, 3];
//! ray!().raw(&value);
//! ```
//!
//! Remove items and manage screens:
//!
//! ```no_run
//! use ray::ray;
//!
//! let handle = ray!("will be removed");
//! handle.remove();
//! ray!().new_screen("Example screen");
//! ray!().clear_all();
//! ```
//!
//! Control app visibility and UI helpers:
//!
//! ```no_run
//! use ray::ray;
//!
//! ray!().show_app();
//! ray!().hide_app();
//! ray!().notify("Hello from Ray");
//! ray!().confetti();
//! ```
//!
//! Additional helpers (limit/once, rate limiting, carbon):
//!
//! ```no_run
//! use ray::{ray, ray_once};
//! use std::time::SystemTime;
//!
//! ray!().limit(2).text("only twice");
//! ray!().once().text("only once");
//! ray!().once_send("only once (send)");
//! ray_once!("only once (macro)");
//! ray!().rate_limiter().max(10).per_second(5);
//! ray!().carbon(SystemTime::now());
//! ```
//!
//! Batch multiple entries into a single request:
//!
//! ```no_run
//! use ray::ray;
//!
//! ray!()
//!     .batch()
//!     .log(&"first")
//!     .label("batch")
//!     .commit();
//! ```
//!
//! Async support (feature: `transport-reqwest`):
//!
//! ```no_run
//! # #[cfg(feature = "transport-reqwest")]
//! # async fn run() {
//! # use ray::ray_async;
//! ray_async!().label("async").await;
//! # }
//! ```
//!
//! Tracing integration (feature: `tracing`):
//!
//! ```no_run
//! # #[cfg(feature = "tracing")]
//! # fn run() {
//! ray::tracing::init().unwrap();
//! tracing::info!("hello from tracing");
//! # }
//! ```
//!
//! `ray!` logs `Serialize` values as JSON. `ray_json!` is an explicit alias:
//!
//! ```no_run
//! use ray::ray_json;
//! use serde::Serialize;
//!
//! #[derive(Serialize)]
//! struct Event {
//!     name: String,
//! }
//!
//! ray_json!(Event {
//!     name: "started".to_string(),
//! });
//! ```

mod client;
mod config;
mod datetime;
mod error;
mod info;
mod measure;
mod origin;
mod panic;
mod rate_limiter;
mod ray;
mod render;
mod request;
mod trace;
mod url;

pub mod payload;
#[cfg(feature = "tracing")]
pub mod tracing;

pub use crate::client::Client;
pub use crate::config::{ConfigError, RayConfig};
pub use crate::error::RayError;
pub use crate::origin::Origin;
pub use crate::panic::panic_hook;
pub use crate::rate_limiter::RateLimiterHandle;
#[doc(hidden)]
pub use crate::ray::mode::{Buffered, Immediate};
pub use crate::ray::{Ray, RayBatch};
#[cfg(feature = "transport-reqwest")]
pub use crate::ray::{RayAsync, RayBatchAsync};
pub use crate::request::{PayloadEnvelope, Request};
pub use crate::url::{RayUrl, RayUrlInput};

/// Create a `Ray` handle for fluent chaining or log `Serialize` values immediately.
/// `ray!()` returns a handle, and `ray!(value, ...)` logs and returns the handle
/// so you can keep chaining. Serialization errors are converted to strings.
/// For Debug-only types, use `ray!().raw(&value)`.
///
/// `ray!(json: value)` is an alias for explicit JSON logging.
///
/// ```no_run
/// use ray::ray;
///
/// ray!("hello").green().label("init");
/// ray!("first", "second");
/// ray!(json: "explicit json").label("json");
/// ray!().log(&"structured").label("log");
/// ```
#[cfg(any(not(feature = "debug-macros"), debug_assertions))]
#[macro_export]
macro_rules! ray {
    () => {{
        $crate::Ray::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        )
    }};
    (json: $($value:expr),+ $(,)?) => {{
        $crate::ray!($($value),+)
    }};
    ($($value:expr),+ $(,)?) => {{
        let ray = $crate::Ray::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        );
        ray.log_debug(vec![
            $(
                match ::serde_json::to_value(&$value) {
                    Ok(value) => value,
                    Err(err) => ::serde_json::Value::String(format!(
                        "<serialization error: {}>",
                        err
                    )),
                }
            ),+
        ])
    }};
}

#[cfg(all(feature = "debug-macros", not(debug_assertions)))]
#[macro_export]
macro_rules! ray {
    () => {{
        $crate::Ray::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        )
        .disable()
    }};
    (json: $($value:expr),+ $(,)?) => {{
        $crate::ray!($($value),+)
    }};
    ($($value:expr),+ $(,)?) => {{
        $crate::Ray::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        )
        .disable()
    }};
}

/// Log values as JSON using `Serialize`.
/// `ray_json!()` returns a handle, and `ray_json!(value, ...)` logs and returns
/// the handle for chaining.
/// `ray!(json: value, ...)` is an alias if you prefer to stay on `ray!`.
///
/// ```no_run
/// use ray::ray_json;
/// use serde::Serialize;
///
/// #[derive(Serialize)]
/// struct Event {
///     name: String,
/// }
///
/// ray_json!(Event {
///     name: "started".to_string(),
/// });
/// ```
#[cfg(any(not(feature = "debug-macros"), debug_assertions))]
#[macro_export]
macro_rules! ray_json {
    () => {{
        $crate::ray!()
    }};
    ($($value:expr),+ $(,)?) => {{
        $crate::ray!($($value),+)
    }};
}

/// Debug helper that sends a value to Ray and returns it.
/// Labels the entry with the expression string, similar to `dbg!`.
///
/// ```no_run
/// use ray::ray_dbg;
///
/// let value = ray_dbg!(2 + 2);
/// assert_eq!(value, 4);
/// ```
#[cfg(any(not(feature = "debug-macros"), debug_assertions))]
#[macro_export]
macro_rules! ray_dbg {
    () => {{
        let location = format!("{}:{}", file!(), line!());
        let ray = $crate::Ray::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        );
        let _ = ray.text(location).label("dbg");
    }};
    ($value:expr $(,)?) => {{
        let value = $value;
        let ray = $crate::Ray::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        );
        ray.raw(&value).label(stringify!($value));
        value
    }};
    ($($value:expr),+ $(,)?) => {{
        ( $( $crate::ray_dbg!($value) ),+, )
    }};
}

#[cfg(all(feature = "debug-macros", not(debug_assertions)))]
#[macro_export]
macro_rules! ray_dbg {
    () => { () };
    ($value:expr $(,)?) => {{ $value }};
    ($($value:expr),+ $(,)?) => {{
        ( $( $crate::ray_dbg!($value) ),+, )
    }};
}

#[cfg(all(feature = "debug-macros", not(debug_assertions)))]
#[macro_export]
macro_rules! ray_json {
    () => {{
        $crate::ray!()
    }};
    ($($value:expr),+ $(,)?) => {{
        $crate::ray!($($value),+)
    }};
}

/// Send values to Ray only once from the callsite.
///
/// ```no_run
/// use ray::ray_once;
///
/// ray_once!("only once");
/// ```
#[cfg(any(not(feature = "debug-macros"), debug_assertions))]
#[macro_export]
macro_rules! ray_once {
    () => {{
        $crate::ray!().once()
    }};
    ($($value:expr),+ $(,)?) => {{
        let ray = $crate::ray!().once();
        ray.log_debug(vec![
            $(
                match ::serde_json::to_value(&$value) {
                    Ok(value) => value,
                    Err(err) => ::serde_json::Value::String(format!(
                        "<serialization error: {}>",
                        err
                    )),
                }
            ),+
        ])
    }};
}

#[cfg(all(feature = "debug-macros", not(debug_assertions)))]
#[macro_export]
macro_rules! ray_once {
    () => {{
        $crate::ray!().once()
    }};
    ($($value:expr),+ $(,)?) => {{
        let ray = $crate::ray!().once();
        ray.log_debug(vec![
            $(
                match ::serde_json::to_value(&$value) {
                    Ok(value) => value,
                    Err(err) => ::serde_json::Value::String(format!(
                        "<serialization error: {}>",
                        err
                    )),
                }
            ),+
        ])
    }};
}

/// Send values to Ray and terminate the process (alias of `ray!(...).die()`).
///
/// ```no_run
/// use ray::rd;
///
/// rd!("fatal");
/// ```
#[cfg(any(not(feature = "debug-macros"), debug_assertions))]
#[macro_export]
macro_rules! rd {
    () => {{
        $crate::ray!().die()
    }};
    ($($value:expr),+ $(,)?) => {{
        $crate::ray!($($value),+).die()
    }};
}

#[cfg(all(feature = "debug-macros", not(debug_assertions)))]
#[macro_export]
macro_rules! rd {
    () => {{
        $crate::ray!().die()
    }};
    ($($value:expr),+ $(,)?) => {{
        $crate::ray!($($value),+).die()
    }};
}

#[cfg(any(not(feature = "debug-macros"), debug_assertions))]
#[macro_export]
/// Create a `Ray` handle with strict error handling.
///
/// ```no_run
/// use ray::ray_strict;
///
/// ray_strict!().try_label("strict").unwrap();
/// ```
macro_rules! ray_strict {
    () => {{
        $crate::Ray::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        )
        .strict(true)
    }};
    ($($value:expr),+ $(,)?) => {{
        let ray = $crate::Ray::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        )
        .strict(true);
        ray.try_log_debug(vec![
            $(
                match ::serde_json::to_value(&$value) {
                    Ok(value) => value,
                    Err(err) => ::serde_json::Value::String(format!(
                        "<serialization error: {}>",
                        err
                    )),
                }
            ),+
        ])
        .expect("ray_strict! failed to send payload");
        ray
    }};
}

#[cfg(all(feature = "debug-macros", not(debug_assertions)))]
#[macro_export]
/// Create a `Ray` handle with strict error handling.
///
/// ```no_run
/// use ray::ray_strict;
///
/// ray_strict!().try_label("strict").unwrap();
/// ```
macro_rules! ray_strict {
    () => {{
        $crate::Ray::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        )
        .disable()
    }};
    ($($value:expr),+ $(,)?) => {{
        $crate::Ray::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        )
        .disable()
    }};
}

#[cfg(feature = "transport-reqwest")]
#[cfg(any(not(feature = "debug-macros"), debug_assertions))]
#[macro_export]
/// Create a `RayAsync` handle for fluent async chaining.
///
/// ```no_run
/// use ray::ray_async;
///
/// #[tokio::main]
/// async fn main() {
///     ray_async!().label("async label").await;
/// }
/// ```
macro_rules! ray_async {
    () => {{
        $crate::RayAsync::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        )
    }};
}

#[cfg(feature = "transport-reqwest")]
#[cfg(all(feature = "debug-macros", not(debug_assertions)))]
#[macro_export]
/// Create a `RayAsync` handle for fluent async chaining.
///
/// ```no_run
/// use ray::ray_async;
///
/// #[tokio::main]
/// async fn main() {
///     ray_async!().label("async label").await;
/// }
/// ```
macro_rules! ray_async {
    () => {{
        $crate::RayAsync::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        )
        .disable()
    }};
}

#[cfg(feature = "transport-reqwest")]
#[cfg(any(not(feature = "debug-macros"), debug_assertions))]
#[macro_export]
/// Create a `RayAsync` handle with strict error handling.
///
/// ```no_run
/// use ray::ray_async_strict;
///
/// #[tokio::main]
/// async fn main() {
///     ray_async_strict!().try_label("async label").await.unwrap();
/// }
/// ```
macro_rules! ray_async_strict {
    () => {{
        $crate::RayAsync::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        )
        .strict(true)
    }};
}

#[cfg(feature = "transport-reqwest")]
#[cfg(all(feature = "debug-macros", not(debug_assertions)))]
#[macro_export]
/// Create a `RayAsync` handle with strict error handling.
///
/// ```no_run
/// use ray::ray_async_strict;
///
/// #[tokio::main]
/// async fn main() {
///     ray_async_strict!().try_label("async label").await.unwrap();
/// }
/// ```
macro_rules! ray_async_strict {
    () => {{
        $crate::RayAsync::new_default_callsite_with_base(
            file!(),
            line!(),
            module_path!(),
            env!("CARGO_MANIFEST_DIR"),
        )
        .disable()
    }};
}