ice-rpc 0.2.2

Zero-copy RPC over iceoryx2 with automatic reconnection, service discovery and HTTP gateway
Documentation
//! Shared runtime state for the consumer-side clients generated by
//! `#[service]`.
//!
//! The reconnection callback, the reconnecting loop and the client bootstrap
//! (node creation, discovery, dispatch, publisher pre-creation) used to be
//! emitted into every generated client. They are factored here so the
//! generated code only holds a [`ClientCore`] and delegates to it.

use std::sync::{Arc, Mutex};

use crate::futures::FutureExt;

/// Connection state machine of a generated client.
///
/// Replaces the former trio of independent atomics (`reconnecting`,
/// `server_ready`, `cached_target_node`) whose combinations were not all
/// valid. Transitions are validated by [`is_valid_transition`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ConnectionState {
    /// No target node known yet.
    Unknown,
    /// A discovery/lookup is in progress.
    Discovering,
    /// The client is connected to a provider node.
    Ready(u32),
    /// The provider node was detected dead.
    Dead(u32),
    /// Waiting for the provider to be rediscovered.
    Reconnecting,
}

/// Returns `true` when `from -> to` is an allowed connection transition.
pub fn is_valid_transition(from: ConnectionState, to: ConnectionState) -> bool {
    match (from, to) {
        (ConnectionState::Unknown, ConnectionState::Discovering) => true,
        (ConnectionState::Dead(_), ConnectionState::Discovering) => true,
        (ConnectionState::Reconnecting, ConnectionState::Discovering) => true,
        (ConnectionState::Discovering, ConnectionState::Ready(_)) => true,
        (ConnectionState::Discovering, ConnectionState::Dead(_)) => true,
        (ConnectionState::Ready(_), ConnectionState::Dead(_)) => true,
        (ConnectionState::Dead(_), ConnectionState::Reconnecting) => true,
        (ConnectionState::Reconnecting, ConnectionState::Ready(_)) => true,
        (ConnectionState::Reconnecting, ConnectionState::Dead(_)) => true,
        (ConnectionState::Ready(a), ConnectionState::Ready(b)) => a == b,
        _ => false,
    }
}

/// Runtime state shared by every generated client.
pub struct ClientCore {
    reconnect_cb: Arc<dyn Fn(u32) + Send + Sync>,
    state: Arc<Mutex<ConnectionState>>,
    subscription: Mutex<Option<crate::node_supervisor::Subscription>>,
}

impl ClientCore {
    /// Builds the shared state and the reconnection callback for a service.
    pub fn new(service_name: &'static str) -> Self {
        let state = Arc::new(Mutex::new(ConnectionState::Unknown));
        let reconnect_cb = build_reconnect_cb(service_name, state.clone());

        Self {
            reconnect_cb,
            state,
            subscription: Mutex::new(None),
        }
    }

    /// Subscribes to the node supervisor for a target node (idempotent).
    ///
    /// Replaces the previous subscription when the target node changes. The
    /// old subscription is removed via `Drop`.
    pub fn subscribe(&self, node_id: u32) {
        let mut subscription = self
            .subscription
            .lock()
            .expect("client core subscription lock poisoning");
        if let Some(existing) = subscription.as_ref() {
            if existing.node_id() == node_id {
                return;
            }
        }
        let cb = self.reconnect_cb.clone();
        *subscription =
            Some(crate::node_supervisor::NodeSupervisor::global().subscribe(node_id, cb));
    }

    /// Reads the cached target node id (`0` unless the state is `Ready`).
    pub fn cached_target_node(&self) -> u64 {
        match *self.state.lock().expect("client core state lock poisoning") {
            ConnectionState::Ready(n) => n as u64,
            _ => 0,
        }
    }

    /// Resolves the target node for an RPC call, encapsulating the state
    /// machine, discovery, publisher availability and node supervision
    /// subscription.
    ///
    /// Returns the cached node when already `Ready`. Otherwise it runs the
    /// discovery loop, ensures the publishers and subscribes before declaring
    /// the client ready.
    pub async fn resolve_target(
        &self,
        service_name: &str,
        timeout_secs: u64,
    ) -> Result<crate::NodeId, crate::RpcError> {
        let cached = self.cached_target_node();
        if cached != 0 {
            let node_id = cached as u32;
            self.subscribe(node_id);
            return Ok(crate::NodeId(node_id));
        }

        self.start_discovery();

        let discovery = crate::ServiceLocator::global().node_discovery();
        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(timeout_secs);
        let mut node = discovery.locate_service(service_name);
        while node.is_none() && std::time::Instant::now() < deadline {
            crate::futures::select! {
                _ = crate::global_cancel_token().cancelled().fuse() => {
                    return Err(crate::RpcError::Cancelled);
                }
                _ = crate::rt::sleep(
                    std::time::Duration::from_millis(crate::SERVER_READY_POLL_MS)
                ).fuse() => {}
            }
            node = discovery.locate_service(service_name);
        }

        let nid = node.ok_or_else(|| crate::RpcError::ServiceNotFound {
            service: service_name.to_string(),
        })?;

        crate::ServiceLocator::global()
            .hub()
            .ensure_publishers(nid)
            .map_err(|e| {
                log::warn!("[{}Client] ensure_publishers failed: {}", service_name, e);
                crate::RpcError::ProviderUnavailable { node: nid.0 }
            })?;

        self.store_target_node(nid.0);
        Ok(nid)
    }

    /// Starts (or restarts) a discovery, if allowed by the state machine.
    pub fn start_discovery(&self) -> bool {
        transition(&self.state, ConnectionState::Discovering)
    }

    /// Marks the client as connected to `node_id` after a successful lookup.
    ///
    /// A successful transition also subscribes to the node supervisor so the
    /// client is notified when the new node dies.
    pub fn store_target_node(&self, node_id: u32) -> bool {
        if transition(&self.state, ConnectionState::Ready(node_id)) {
            self.subscribe(node_id);
            true
        } else {
            false
        }
    }

    /// Marks `node_id` as dead, if allowed by the state machine.
    pub fn mark_dead(&self, node_id: u32) -> bool {
        transition(&self.state, ConnectionState::Dead(node_id))
    }

    /// Marks the client as reconnecting, if allowed by the state machine.
    pub fn mark_reconnecting(&self) -> bool {
        transition(&self.state, ConnectionState::Reconnecting)
    }

    /// Returns the current connection state.
    pub fn state(&self) -> ConnectionState {
        *self.state.lock().expect("client core state lock poisoning")
    }

    /// Bootstraps the client: creates the node, starts discovery, locates the
    /// provider, starts the dispatch loop and pre-creates the publishers.
    ///
    /// # Returns
    /// `true` when the target provider is ready; `false` otherwise.
    pub async fn init(&self, service_name: &'static str) -> bool {
        match crate::ServiceLocator::global().get_node_sync() {
            Ok(_) => {}
            Err(e) => {
                log::error!("[{}Client] get_node failed: {}", service_name, e);
                return false;
            }
        };

        {
            let locator = crate::ServiceLocator::global();
            let _ = crate::rt::spawn_blocking(move || {
                locator.start_discovery();
            })
            .await;
        }

        self.start_discovery();

        let discovery = crate::ServiceLocator::global().node_discovery();
        let target_node = match discovery.locate_service(service_name) {
            Some(n) => n,
            None => {
                log::warn!(
                    "[{}Client] Service '{}' not detected yet (empty cache+Blackboard).",
                    service_name,
                    service_name
                );
                return false;
            }
        };

        {
            let locator = crate::ServiceLocator::global();
            let _ = crate::rt::spawn_blocking(move || {
                locator.start_dispatch_if_needed();
            })
            .await;
        }

        let result = crate::rt::spawn_blocking_value(move || {
            crate::ServiceLocator::global()
                .hub()
                .ensure_publishers(target_node)
        })
        .await;

        match result {
            Ok(()) => {}
            Err(e) => {
                log::error!("[{}Client] ensure_publishers failed: {}", service_name, e);
                return false;
            }
        }

        self.store_target_node(target_node.0);
        self.subscribe(target_node.0);

        log::info!(
            "[{}Client] Ready (publishers pre-created, centralized hub).",
            service_name
        );
        true
    }
}

/// Applies a connection transition after validating it.
fn transition(state: &Mutex<ConnectionState>, to: ConnectionState) -> bool {
    let mut guard = state.lock().expect("client core state lock poisoning");
    if is_valid_transition(*guard, to) {
        *guard = to;
        true
    } else {
        false
    }
}

/// Builds the reconnection callback fired when the provider node dies.
///
/// The callback only transitions the state machine to `Dead` then
/// `Reconnecting`, and delegates the retry loop to the centralized
/// [`crate::reconnect_manager::ReconnectManager`], which runs a single worker
/// thread for every pending service.
fn build_reconnect_cb(
    service_name: &'static str,
    state: Arc<Mutex<ConnectionState>>,
) -> Arc<dyn Fn(u32) + Send + Sync> {
    let pending = Arc::new(crate::reconnect_manager::PendingService::new(
        service_name,
        state.clone(),
    ));

    Arc::new(move |dead_node_id: u32| {
        {
            let mut guard = state.lock().expect("client core state lock poisoning");
            if !is_valid_transition(*guard, ConnectionState::Dead(dead_node_id)) {
                return;
            }
            *guard = ConnectionState::Dead(dead_node_id);
        }
        log::warn!(
            "[{}Client] Node {} detected dead — reconnecting",
            service_name,
            dead_node_id
        );

        {
            let mut guard = state.lock().expect("client core state lock poisoning");
            if is_valid_transition(*guard, ConnectionState::Reconnecting) {
                *guard = ConnectionState::Reconnecting;
            }
        }

        crate::reconnect_manager::ReconnectManager::global().schedule(dead_node_id, pending.clone());
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use ConnectionState::*;

    #[test]
    fn valid_transition_path() {
        assert!(is_valid_transition(Unknown, Discovering));
        assert!(is_valid_transition(Discovering, Ready(1)));
        assert!(is_valid_transition(Ready(1), Dead(1)));
        assert!(is_valid_transition(Dead(1), Reconnecting));
        assert!(is_valid_transition(Reconnecting, Ready(2)));
    }

    #[test]
    fn invalid_transitions() {
        // Dead -> Ready directly, without going through Reconnecting/Discovering.
        assert!(!is_valid_transition(Dead(1), Ready(2)));
        // Unknown -> Ready without discovery.
        assert!(!is_valid_transition(Unknown, Ready(1)));
        // Switching provider node without a reconnection.
        assert!(!is_valid_transition(Ready(1), Ready(2)));
        // Starting a discovery while already discovering is a no-op.
        assert!(!is_valid_transition(Discovering, Discovering));
    }

    #[test]
    fn client_core_rejects_ready_without_discovery() {
        let core = ClientCore::new("svc");
        assert_eq!(core.state(), Unknown);
        assert!(!core.store_target_node(1));
        assert!(core.start_discovery());
        assert!(core.store_target_node(1));
        assert_eq!(core.state(), Ready(1));
    }

    #[test]
    fn client_core_rejects_dead_to_ready_directly() {
        let core = ClientCore::new("svc");
        core.start_discovery();
        core.store_target_node(1);
        core.mark_dead(1);
        assert_eq!(core.state(), Dead(1));
        assert!(!core.store_target_node(2));
        assert!(core.mark_reconnecting());
        assert!(core.store_target_node(2));
        assert_eq!(core.state(), Ready(2));
    }

    #[test]
    fn resolve_target_returns_cached_node_when_ready() {
        let core = ClientCore::new("svc");
        core.start_discovery();
        core.store_target_node(42);
        let node = pollster::block_on(core.resolve_target("svc", 30)).unwrap();
        assert_eq!(node.0, 42);
    }
}