fix(hiroz-py): surface P6 callback thread errors via last_error property

Background callback threads were silently swallowing exceptions via
eprintln. Add a shared Arc<Mutex<Option<String>>> that records the most
recent error; expose it as ZServer.last_error (resets on read).

Also fix a pre-existing broken intra-doc link in lifecycle/node.rs
(create_publisher → Self::create_publisher) that was failing cargo doc.

Author: YuanYuYuan

crates/hiroz-py/python/hiroz_py/__init__.pyi

@@ -288,6 +288,8 @@ class ZServer:
     def take_request(self) -> tuple[dict[str, Any], Any]: ...
     def send_response(self, response: Any, request_id: dict[str, Any]) -> None: ...
     def get_type_name(self) -> str: ...
+    @property
+    def last_error(self) -> str | None: ...
 
 # ---------------------------------------------------------------------------
 # ZActionClient

crates/hiroz-py/src/service.rs

@@ -3,8 +3,8 @@ use hiroz::graph::Graph;
 use hiroz::service::RequestId;
 use pyo3::prelude::*;
 use pyo3::types::PyDict;
-use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
 /// Python wrapper for service client
@@ -90,6 +90,7 @@ struct CallbackServerState {
     stop: Arc<AtomicBool>,
     handle: Option<std::thread::JoinHandle<()>>,
     _server: Arc<dyn RawServer>,
+    last_error: Arc<Mutex<Option<String>>>,
 }
 
 impl Drop for CallbackServerState {
@@ -106,23 +107,27 @@ impl Drop for CallbackServerState {
 /// Pull mode (default): `inner` is `Some`; the caller drives `take_request` /
 /// `send_response`. Callback mode (P6): `inner` is `None` and a background
 /// thread (held in `_callback`) services requests via the user callback.
+/// Errors from the callback thread are stored in `last_error` and surfaced via
+/// the `last_error` Python property.
 #[pyclass(name = "ZServer")]
 pub struct PyZServer {
-    inner: Option<std::sync::Mutex<Box<dyn RawServer>>>,
+    inner: Option<Mutex<Box<dyn RawServer>>>,
     request_type_name: String,
     response_type_name: String,
     _callback: Option<CallbackServerState>,
+    last_error: Arc<Mutex<Option<String>>>,
 }
 
 impl PyZServer {
     pub fn new(inner: Box<dyn RawServer>, service_type: String) -> Self {
         let request_type_name = format!("{}_Request", service_type);
         let response_type_name = format!("{}_Response", service_type);
         Self {
-            inner: Some(std::sync::Mutex::new(inner)),
+            inner: Some(Mutex::new(inner)),
             request_type_name,
             response_type_name,
             _callback: None,
+            last_error: Arc::new(Mutex::new(None)),
         }
     }
 
@@ -137,12 +142,14 @@ impl PyZServer {
         let response_type_name = format!("{}_Response", service_type);
 
         let stop = Arc::new(AtomicBool::new(false));
+        let last_error: Arc<Mutex<Option<String>>> = Arc::new(Mutex::new(None));
         let handle = spawn_callback_loop(
             Arc::clone(&server),
             request_type_name.clone(),
             response_type_name.clone(),
             callback,
             Arc::clone(&stop),
+            Arc::clone(&last_error),
         );
 
         Self {
@@ -153,11 +160,13 @@ impl PyZServer {
                 stop,
                 handle: Some(handle),
                 _server: server,
+                last_error: Arc::clone(&last_error),
             }),
+            last_error,
         }
     }
 
-    fn require_pull(&self) -> PyResult<&std::sync::Mutex<Box<dyn RawServer>>> {
+    fn require_pull(&self) -> PyResult<&Mutex<Box<dyn RawServer>>> {
         self.inner.as_ref().ok_or_else(|| {
             pyo3::exceptions::PyRuntimeError::new_err(
                 "This server runs in callback mode; take_request/send_response are unavailable. \
@@ -174,7 +183,19 @@ fn spawn_callback_loop(
     response_type_name: String,
     callback: PyObject,
     stop: Arc<AtomicBool>,
+    last_error: Arc<Mutex<Option<String>>>,
 ) -> std::thread::JoinHandle<()> {
+    // Helper: record an error both in the shared slot and stderr.
+    macro_rules! record_error {
+        ($last_error:expr, $msg:literal, $e:expr) => {{
+            let msg = format!(concat!("hiroz_py: ", $msg, ": {}"), $e);
+            eprintln!("{}", msg);
+            if let Ok(mut guard) = $last_error.lock() {
+                *guard = Some(msg);
+            }
+        }};
+    }
+
     std::thread::spawn(move || {
         while !stop.load(Ordering::Relaxed) {
             // Poll for a request without holding the GIL.
@@ -188,14 +209,14 @@ fn spawn_callback_loop(
                         ) {
                             Ok(o) => o,
                             Err(e) => {
-                                eprintln!("hiroz_py: request deserialize error: {}", e);
+                                record_error!(last_error, "request deserialize error", e);
                                 return;
                             }
                         };
                         let resp_obj = match callback.call1(py, (req_obj,)) {
                             Ok(o) => o,
                             Err(e) => {
-                                eprintln!("hiroz_py: service callback error: {}", e);
+                                record_error!(last_error, "service callback error", e);
                                 return;
                             }
                         };
@@ -206,18 +227,18 @@ fn spawn_callback_loop(
                         ) {
                             Ok(b) => b,
                             Err(e) => {
-                                eprintln!("hiroz_py: response serialize error: {}", e);
+                                record_error!(last_error, "response serialize error", e);
                                 return;
                             }
                         };
                         if let Err(e) = server.send_response_serialized(&resp_bytes, &request_id) {
-                            eprintln!("hiroz_py: send_response error: {}", e);
+                            record_error!(last_error, "send_response error", e);
                         }
                     });
                 }
                 Ok(None) => std::thread::sleep(Duration::from_millis(2)),
                 Err(e) => {
-                    eprintln!("hiroz_py: service poll error: {}", e);
+                    record_error!(last_error, "service poll error", e);
                     std::thread::sleep(Duration::from_millis(50));
                 }
             }
@@ -289,4 +310,12 @@ impl PyZServer {
             self.request_type_name, self.response_type_name
         )
     }
+
+    /// The last error raised by the callback thread, or None if no error has
+    /// occurred. Resets to None when read. Only meaningful in callback mode;
+    /// always None in pull mode.
+    #[getter]
+    fn last_error(&self) -> Option<String> {
+        self.last_error.lock().ok().and_then(|mut g| g.take())
+    }
 }

crates/hiroz-py/tests/test_rclpy_alignment.py

@@ -147,6 +147,48 @@ def handle(req):
     assert resp.sum == 42
 
 
+def test_p6_last_error_surfaced_on_callback_exception(ctx):
+    node = ctx.create_node("p6_err_node").build()
+
+    def bad_handle(req):
+        raise ValueError("intentional callback failure")
+
+    server = node.create_server(
+        "/p6_err_add", example_interfaces.AddTwoInts, callback=bad_handle
+    )
+    client = node.create_client("/p6_err_add", example_interfaces.AddTwoInts)
+    assert client.wait_for_service(timeout=5.0)
+
+    # The call will fail from the client side (no response sent).
+    try:
+        client.call(example_interfaces.AddTwoInts.Request(a=1, b=2), timeout=1.0)
+    except Exception:
+        pass
+
+    # Give the background thread a moment to record the error.
+    deadline = time.time() + 2.0
+    err = None
+    while err is None and time.time() < deadline:
+        err = server.last_error
+        if err is None:
+            time.sleep(0.05)
+
+    assert err is not None, "last_error should surface the callback exception"
+    assert "intentional callback failure" in err
+
+
+def test_p6_last_error_none_when_no_error(ctx):
+    node = ctx.create_node("p6_ok_node").build()
+
+    def handle(req):
+        return example_interfaces.AddTwoInts.Response(sum=req.a + req.b)
+
+    server = node.create_server(
+        "/p6_ok_add", example_interfaces.AddTwoInts, callback=handle
+    )
+    assert server.last_error is None
+
+
 def test_p1_wait_for_service_timeout_returns_false(ctx):
     node = ctx.create_node("p1_wait_to").build()
     client = node.create_client("/p1_never", example_interfaces.AddTwoInts)