Tutorial 6: Services & Actions (Rust)

use horus::prelude::*;

// Generates AddTwoIntsRequest, AddTwoIntsResponse and the AddTwoInts marker
// type. The service name is the snake_case form of the type name, so these
// two halves meet on "add_two_ints".
service! {
    /// Add two integers
    AddTwoInts {
        request {
            a: i64,
            b: i64,
        }
        response {
            sum: i64,
        }
    }
}

fn main() -> Result<()> {
    // ── Server: listens for requests, computes response ─────────
    // build() spawns the polling thread and returns a handle that owns it.
    // Keep the handle alive: dropping it stops the server.
    let _server = ServiceServerBuilder::<AddTwoInts>::new()
        .on_request(|req| {
            // Ok(response) answers the caller; Err(String) sends it a failure,
            // which surfaces client-side as ServiceError::ServiceFailed.
            Ok(AddTwoIntsResponse { sum: req.a + req.b })
        })
        .build()?;

    // ── Client: sends request, waits for response ───────────────
    // Nothing to pump here — the server answers from its own thread while
    // call() blocks, and the timeout bounds the wait if it never does.
    let mut client = ServiceClient::<AddTwoInts>::new()?;

    match client.call(AddTwoIntsRequest { a: 3, b: 4 }, 1_u64.secs()) {
        Ok(res) => println!("Response: sum = {}", res.sum),
        // Output: Response: sum = 7
        Err(e) => println!("Service call failed: {}", e),
    }

    Ok(())
}

use horus::prelude::*;

// Both halves must agree on this definition — put it in a module both
// binaries include, or in a small shared crate.
action! {
    /// Navigate to a target position
    Navigate {
        goal {
            target_x: f64,
            target_y: f64,
        }
        feedback {
            distance_remaining: f64,
            progress: f32,
        }
        result {
            success: bool,
            final_x: f64,
            final_y: f64,
        }
    }
}

fn main() -> Result<()> {
    // Requires the "navigate" action server (shown below) running elsewhere.
    let client = ActionClient::<Navigate>::new()?;

    // send_goal_and_wait_with_feedback drains the client's topics itself, so
    // no node has to tick for the callback to fire. Always bound the wait:
    // with no server running, no result is ever published.
    let outcome = client.send_goal_and_wait_with_feedback(
        NavigateGoal { target_x: 5.0, target_y: 3.0 },
        5_u64.secs(),
        |fb| {
            println!(
                "  feedback: {:.0}% — {:.2} m remaining",
                fb.progress * 100.0,
                fb.distance_remaining
            );
        },
    );

    match outcome {
        Ok(result) => println!(
            "Arrived at ({:.1}, {:.1}) — success={}",
            result.final_x, result.final_y, result.success
        ),
        // The sync client cancels the goal on its way out of a timeout, so a
        // server that is merely slow does not keep driving after you gave up.
        Err(ActionError::GoalTimeout) => {
            println!("No result — is the 'navigate' action server running?")
        }
        Err(e) => println!("Goal failed: {}", e),
    }

    Ok(())
}

use horus::prelude::*;

action! {
    Navigate {
        goal { target_x: f64, target_y: f64 }
        feedback { distance_remaining: f64, progress: f32 }
        result { success: bool, final_x: f64, final_y: f64 }
    }
}

fn main() -> Result<()> {
    let server = ActionServerNode::<Navigate>::builder()
        // Decide whether to accept the goal.
        .on_goal(|goal| {
            if goal.target_x.is_finite() && goal.target_y.is_finite() {
                GoalResponse::Accept
            } else {
                GoalResponse::Reject("target is not a finite position".into())
            }
        })
        .on_cancel(|_goal_id| CancelResponse::Accept)
        // Runs on a dedicated thread per accepted goal. Poll for cancellation,
        // publish feedback, and finish by returning a GoalOutcome.
        .on_execute(|handle| {
            // Read the goal out before finishing: succeed/canceled consume the
            // handle, and `goal()` borrows from it.
            let (tx, ty) = (handle.goal().target_x, handle.goal().target_y);
            let (mut x, mut y) = (0.0_f64, 0.0_f64);

            for step in 1..=10 {
                if handle.is_cancel_requested() {
                    return handle.canceled(NavigateResult {
                        success: false,
                        final_x: x,
                        final_y: y,
                    });
                }

                let t = step as f64 / 10.0;
                x = tx * t;
                y = ty * t;
                let remaining = ((tx - x).powi(2) + (ty - y).powi(2)).sqrt();

                handle.publish_feedback(NavigateFeedback {
                    distance_remaining: remaining,
                    progress: t as f32,
                });
                std::thread::sleep(200_u64.ms());
            }

            handle.succeed(NavigateResult { success: true, final_x: x, final_y: y })
        })
        .build();

    // The scheduler tick is what drives the server: 50 Hz here bounds how fast
    // a new goal is picked up and how promptly feedback reaches the client.
    let mut sched = Scheduler::new().name("navigate_server").tick_rate(50_u64.hz());
    sched.add(server).order(0).build()?;

    println!("Action 'navigate' ready (Ctrl+C to stop)");
    sched.run()
}

# One project, two binaries: src/bin/add_server.rs and src/bin/add_client.rs

# Terminal 1: server
cargo run --bin add_server

# Terminal 2: client
cargo run --bin add_client

horus service list
horus service call add_two_ints '{"a": 3, "b": 4}'   # -> {"sum": 7}
horus action list
horus action send-goal navigate '{"target_x": 5.0, "target_y": 3.0}'