Skip to main content

nautilus_live/python/
node.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Python bindings for live node.
17
18use std::{
19    cell::{Cell, Ref, RefCell, RefMut},
20    collections::HashMap,
21    fmt::Debug,
22    future::Future,
23    pin::Pin,
24    rc::Rc,
25    str::FromStr,
26    sync::{
27        Arc,
28        atomic::{AtomicBool, Ordering},
29        mpsc,
30    },
31    task::{Context, Poll, Waker},
32    thread,
33    time::{Duration, Instant},
34};
35
36#[cfg(feature = "examples")]
37use nautilus_common::python::config_error_to_pyvalue_err;
38use nautilus_common::{
39    actor::data_actor::ImportableActorConfig,
40    cache::CacheConfig,
41    enums::Environment,
42    live::get_runtime,
43    logging::logger::LoggerConfig,
44    msgbus::MessageBusConfig,
45    python::{
46        actor::{PyDataActor, prepare_python_actor},
47        cache::{PyCache, get_global_cache_database_factory_registry},
48        msgbus::get_global_msgbus_factory_registry,
49    },
50};
51#[cfg(feature = "examples")]
52use nautilus_core::python::to_pytype_err;
53use nautilus_core::{
54    UUID4,
55    python::{to_pyruntime_err, to_pyvalue_err},
56};
57use nautilus_model::{
58    enums::OmsType,
59    identifiers::{ActorId, ExecAlgorithmId, InstrumentId, StrategyId, TraderId},
60};
61use nautilus_portfolio::{config::PortfolioConfig, python::PyPortfolio};
62use nautilus_system::get_global_pyo3_registry;
63#[cfg(feature = "examples")]
64use nautilus_testkit::{DataTester, DataTesterConfig, ExecTester, ExecTesterConfig};
65#[cfg(feature = "examples")]
66use nautilus_trading::examples::strategies::{
67    CompositeMarketMaker, CompositeMarketMakerConfig, DeltaNeutralVol, DeltaNeutralVolConfig,
68    EmaCross, EmaCrossConfig, GridMarketMaker, GridMarketMakerConfig, HurstVpinDirectional,
69    HurstVpinDirectionalConfig, OrderBookImbalance, OrderBookImbalanceConfig,
70};
71use nautilus_trading::{
72    ImportableControllerConfig, ImportableExecutionAlgorithmConfig, ImportableStrategyConfig,
73    python::{algorithm::PyExecutionAlgorithm, strategy::PyStrategy},
74};
75use parking_lot::{Condvar, Mutex};
76use pyo3::{
77    exceptions::PyBaseExceptionGroup,
78    ffi::c_str,
79    intern,
80    prelude::*,
81    sync::PyOnceLock,
82    types::{PyCFunction, PyDict, PyTuple},
83};
84use serde_json;
85
86use super::client::{PythonClientConfig, PythonClients, PythonDataFactory, PythonExecutionFactory};
87// Re-exported so the `live` module registers every Python class through this module.
88pub use crate::node::NodeState;
89use crate::{
90    builder::LiveNodeBuilder,
91    config::{
92        LiveDataEngineConfig, LiveExecutionEngineConfig, LiveNodeConfig, LiveRiskEngineConfig,
93        PluginConfig,
94    },
95    node::{LiveNode, LiveNodeHandle, NodeRunMode, config::RoutingConfig},
96    python::config::{coerce_json_config, json_value_to_py},
97};
98
99/// Python-facing wrapper owning a [`LiveNode`].
100///
101/// `run_async` moves the node into the returned awaitable, so the wrapper is empty for the
102/// remainder of a hosted run. Every method then fails with a clear error rather than aliasing the
103/// node the run future is driving. Capture `cache`, `portfolio`, and `handle` before starting a
104/// hosted run; each is an independent handle that stays usable while the node runs.
105#[pyo3::pyclass(module = "nautilus_trader.live", name = "LiveNode", unsendable)]
106#[pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")]
107#[derive(Debug)]
108pub struct PyLiveNode {
109    inner: Rc<RefCell<Option<LiveNode>>>,
110    handle: LiveNodeHandle,
111    clients: PythonClients,
112}
113
114impl PyLiveNode {
115    /// Wraps an owned node for Python.
116    #[must_use]
117    pub fn new(node: LiveNode) -> Self {
118        let handle = node.handle();
119
120        Self {
121            inner: Rc::new(RefCell::new(Some(node))),
122            handle,
123            clients: PythonClients::default(),
124        }
125    }
126
127    fn node(&self) -> PyResult<Ref<'_, LiveNode>> {
128        let borrow = self.inner.try_borrow().map_err(|_| node_busy_err())?;
129        if borrow.is_none() {
130            return Err(node_consumed_err());
131        }
132
133        Ok(Ref::map(borrow, |node| {
134            node.as_ref().expect("node presence checked above")
135        }))
136    }
137
138    fn node_mut(&self) -> PyResult<RefMut<'_, LiveNode>> {
139        let borrow = self.inner.try_borrow_mut().map_err(|_| node_busy_err())?;
140        if borrow.is_none() {
141            return Err(node_consumed_err());
142        }
143
144        Ok(RefMut::map(borrow, |node| {
145            node.as_mut().expect("node presence checked above")
146        }))
147    }
148
149    fn is_consumed(&self) -> bool {
150        self.inner.try_borrow().is_ok_and(|node| node.is_none())
151    }
152}
153
154/// Thread-safe control handle for a [`LiveNode`].
155///
156/// Stays valid for the node's whole lifetime, including while a hosted run owns the node, and is
157/// safe to call from any thread or from a signal handler.
158#[pyo3::pyclass(module = "nautilus_trader.live", name = "LiveNodeHandle", frozen)]
159#[pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")]
160#[derive(Clone, Debug)]
161pub struct PyLiveNodeHandle {
162    inner: LiveNodeHandle,
163}
164
165#[pyo3_stub_gen::derive::gen_stub_pymethods]
166#[pymethods]
167impl PyLiveNodeHandle {
168    /// Signals the node to stop, returning immediately.
169    ///
170    /// The node then runs its full shutdown sequence, so callers awaiting `run_async` observe
171    /// completion only once shutdown finishes.
172    #[pyo3(name = "stop")]
173    fn py_stop(&self) {
174        self.inner.stop();
175    }
176
177    /// Returns whether a stop has been requested.
178    #[getter]
179    #[pyo3(name = "is_stopping")]
180    fn py_is_stopping(&self) -> bool {
181        self.inner.should_stop()
182    }
183
184    /// Returns whether the node is currently running.
185    #[getter]
186    #[pyo3(name = "is_running")]
187    fn py_is_running(&self) -> bool {
188        self.inner.is_running()
189    }
190
191    /// Returns the node's current lifecycle state.
192    #[getter]
193    #[pyo3(name = "state")]
194    fn py_state(&self) -> NodeState {
195        self.inner.state()
196    }
197
198    fn __repr__(&self) -> String {
199        format!("LiveNodeHandle(state={:?})", self.inner.state())
200    }
201}
202
203/// How long `close` drives a still-running node before giving up.
204///
205/// A closed host loop can no longer resume the run, so the node is driven to completion inline.
206/// Bounded so interpreter teardown cannot hang indefinitely on an unresponsive venue.
207const CLOSE_DRIVE_TIMEOUT: Duration = Duration::from_secs(30);
208
209thread_local! {
210    /// Guards against a second hosted run on the same thread.
211    ///
212    /// The runner binds its senders into thread-local storage and the msgbus is thread-local, so
213    /// two interleaved hosted nodes would cross-wire each other's events rather than fail.
214    static HOSTED_RUN_ACTIVE: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
215}
216
217/// Waker for driving a run to completion without an event loop.
218///
219/// The host loop is gone by the time this is used, so waking must not touch Python: a tokio worker
220/// that blocked acquiring the GIL could not then wake the thread waiting here.
221#[derive(Debug, Default)]
222struct BlockingWake {
223    woken: Mutex<bool>,
224    signal: Condvar,
225}
226
227impl BlockingWake {
228    /// Waits for a wake, returning `false` once the deadline passes.
229    fn wait_until(&self, deadline: Instant) -> bool {
230        let mut woken = self.woken.lock();
231        while !*woken {
232            let Some(remaining) = deadline.checked_duration_since(Instant::now()) else {
233                return false;
234            };
235
236            let timeout = self.signal.wait_for(&mut woken, remaining);
237
238            if timeout.timed_out() && !*woken {
239                return false;
240            }
241        }
242
243        *woken = false;
244        true
245    }
246}
247
248impl std::task::Wake for BlockingWake {
249    fn wake(self: Arc<Self>) {
250        self.wake_by_ref();
251    }
252
253    fn wake_by_ref(self: &Arc<Self>) {
254        *self.woken.lock() = true;
255        self.signal.notify_all();
256    }
257}
258
259/// Wake state shared between a hosted run and the callback that resumes it.
260#[derive(Debug, Default)]
261struct RunWakeState {
262    pending: Mutex<Option<RunSuspension>>,
263    closed: AtomicBool,
264}
265
266#[derive(Debug)]
267struct RunSuspension {
268    generation: u64,
269    future: Py<PyAny>,
270}
271
272impl RunWakeState {
273    fn suspend(&self, generation: u64, future: Py<PyAny>) {
274        *self.pending.lock() = Some(RunSuspension { generation, future });
275    }
276
277    fn resume(&self, py: Python<'_>, generation: u64) -> PyResult<()> {
278        let mut pending = self.pending.lock();
279
280        let Some(suspension) = pending.as_ref() else {
281            return Ok(());
282        };
283
284        if self.closed.load(Ordering::Acquire) || suspension.generation != generation {
285            return Ok(());
286        }
287
288        let future = pending.take().expect("suspension presence checked").future;
289        drop(pending);
290
291        let future = future.bind(py);
292        if !future
293            .call_method0(intern!(py, "done"))?
294            .extract::<bool>()?
295        {
296            future.call_method1(intern!(py, "set_result"), (py.None(),))?;
297        }
298
299        Ok(())
300    }
301
302    fn close(&self) {
303        self.closed.store(true, Ordering::Release);
304        self.pending.lock().take();
305    }
306}
307
308/// Callable scheduled on the host event loop to resume a hosted run.
309#[pyo3::pyclass(name = "NodeRunWake", frozen)]
310struct PyNodeRunWake {
311    state: Arc<RunWakeState>,
312}
313
314#[pymethods]
315impl PyNodeRunWake {
316    fn __call__(&self, py: Python<'_>, generation: u64) -> PyResult<()> {
317        self.state.resume(py, generation)
318    }
319}
320
321enum HostWakeSignal {
322    Resume(u64),
323    Shutdown,
324}
325
326struct HostWakeControl {
327    sender: mpsc::Sender<HostWakeSignal>,
328    active: AtomicBool,
329    handle: LiveNodeHandle,
330}
331
332impl HostWakeControl {
333    fn resume(&self, generation: u64) {
334        if !self.active.load(Ordering::Acquire) {
335            return;
336        }
337
338        if self
339            .sender
340            .send(HostWakeSignal::Resume(generation))
341            .is_err()
342            && self.active.swap(false, Ordering::AcqRel)
343        {
344            // Nothing can resume a suspended run once the wake pump is gone. Request a stop,
345            // but the awaiting task may remain suspended.
346            log::error!("Hosted run wake pump stopped unexpectedly, stopping node");
347            self.handle.stop();
348        }
349    }
350
351    fn close(&self) {
352        if self.active.swap(false, Ordering::AcqRel) {
353            let _ = self.sender.send(HostWakeSignal::Shutdown);
354        }
355    }
356}
357
358/// Waker that signals the host wake pump from whichever thread completed the work.
359struct HostLoopWaker {
360    generation: u64,
361    scheduled: AtomicBool,
362    control: Arc<HostWakeControl>,
363}
364
365impl std::task::Wake for HostLoopWaker {
366    fn wake(self: Arc<Self>) {
367        self.wake_by_ref();
368    }
369
370    fn wake_by_ref(self: &Arc<Self>) {
371        if !self.scheduled.swap(true, Ordering::AcqRel) {
372            self.control.resume(self.generation);
373        }
374    }
375}
376
377/// Moves Python scheduling off the dependency thread that invoked the waker.
378struct HostWakePump {
379    control: Arc<HostWakeControl>,
380    thread: Option<thread::JoinHandle<()>>,
381}
382
383impl HostWakePump {
384    fn start(
385        event_loop: Py<PyAny>,
386        wake_callback: Py<PyAny>,
387        handle: LiveNodeHandle,
388    ) -> PyResult<Self> {
389        let (sender, receiver) = mpsc::channel();
390
391        let control = Arc::new(HostWakeControl {
392            sender,
393            active: AtomicBool::new(true),
394            handle: handle.clone(),
395        });
396
397        let control_for_thread = control.clone();
398
399        let thread = thread::Builder::new()
400            .name("nautilus-host-wake".to_string())
401            .spawn(move || {
402                while let Ok(signal) = receiver.recv() {
403                    match signal {
404                        HostWakeSignal::Resume(generation) => {
405                            if !control_for_thread.active.load(Ordering::Acquire) {
406                                continue;
407                            }
408
409                            let Some(result) = Python::try_attach(|py| {
410                                event_loop.bind(py).call_method1(
411                                    intern!(py, "call_soon_threadsafe"),
412                                    (wake_callback.bind(py), generation),
413                                )?;
414                                Ok::<(), PyErr>(())
415                            }) else {
416                                log::error!(
417                                    "Python unavailable while scheduling hosted run wake-up, stopping node"
418                                );
419                                handle.stop();
420                                break;
421                            };
422
423                            if let Err(e) = result {
424                                log::error!(
425                                    "Failed to schedule hosted run wake-up, stopping node: {e}"
426                                );
427                                handle.stop();
428                                break;
429                            }
430                        }
431                        HostWakeSignal::Shutdown => break,
432                    }
433                }
434
435                control_for_thread.active.store(false, Ordering::Release);
436            })
437            .map_err(|e| to_pyruntime_err(format!("failed to start hosted run wake pump: {e}")))?;
438
439        Ok(Self {
440            control,
441            thread: Some(thread),
442        })
443    }
444
445    fn waker(&self, generation: u64) -> Waker {
446        Waker::from(Arc::new(HostLoopWaker {
447            generation,
448            scheduled: AtomicBool::new(false),
449            control: self.control.clone(),
450        }))
451    }
452
453    fn close(&self) {
454        self.control.close();
455    }
456
457    fn join(&mut self, py: Option<Python<'_>>) {
458        let Some(thread) = self.thread.take() else {
459            return;
460        };
461
462        let mut thread = Some(thread);
463
464        let result = match py {
465            Some(py) => py.detach(|| thread.take().expect("thread presence checked").join()),
466            None => Python::try_attach(|py| {
467                py.detach(|| thread.take().expect("thread presence checked").join())
468            })
469            .unwrap_or_else(|| thread.take().expect("thread presence checked").join()),
470        };
471
472        if result.is_err() {
473            log::error!("Hosted run wake pump panicked while stopping");
474        }
475    }
476}
477
478impl Drop for HostWakePump {
479    fn drop(&mut self) {
480        self.close();
481        self.join(None);
482    }
483}
484
485struct SendPtr<T>(*mut T);
486
487// SAFETY: the owner of a `SendPtr` holds the only reference to the pointee for the pointer's
488// lifetime, and the pointee outlives every use.
489#[allow(unsafe_code)]
490unsafe impl<T> Send for SendPtr<T> {}
491
492/// Awaitable driving a [`LiveNode`] on the host's asyncio event loop.
493///
494/// Polls the node's run future from loop callbacks, so the node shares the host's thread and never
495/// blocks it. Awaiting resolves once the node has fully stopped.
496#[pyo3::pyclass(name = "NodeRun", unsendable)]
497pub struct PyNodeRun {
498    clients: PythonClients,
499    // Declared before `node` so the future is dropped first; it borrows the node.
500    future: Option<Pin<Box<dyn Future<Output = anyhow::Result<()>>>>>,
501    node: Option<Box<LiveNode>>,
502    owner: Rc<RefCell<Option<LiveNode>>>,
503    handle: LiveNodeHandle,
504    event_loop: Py<PyAny>,
505    wake_pump: HostWakePump,
506    state: Arc<RunWakeState>,
507    generation: u64,
508    pending_throw: Option<PyErr>,
509}
510
511#[allow(
512    clippy::missing_fields_in_debug,
513    reason = "the future and node fields have no useful debug representation"
514)]
515impl Debug for PyNodeRun {
516    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
517        f.debug_struct(stringify!(PyNodeRun))
518            .field("state", &self.handle.state())
519            .field("completed", &self.future.is_none())
520            .finish()
521    }
522}
523
524impl Drop for PyNodeRun {
525    fn drop(&mut self) {
526        self.restore_node(None);
527    }
528}
529
530impl PyNodeRun {
531    #[allow(
532        unsafe_code,
533        reason = "the run future borrows the boxed node this type owns"
534    )]
535    fn new(
536        node: LiveNode,
537        owner: Rc<RefCell<Option<LiveNode>>>,
538        event_loop: Bound<'_, PyAny>,
539        state: Arc<RunWakeState>,
540        wake_pump: HostWakePump,
541        clients: PythonClients,
542    ) -> Self {
543        let handle = node.handle();
544        let mut node = Box::new(node);
545        let node_ptr = SendPtr(std::ptr::from_mut::<LiveNode>(node.as_mut()));
546
547        let future: Pin<Box<dyn Future<Output = anyhow::Result<()>>>> = Box::pin(async move {
548            let ptr = node_ptr;
549            // SAFETY: the node is boxed, so its address is stable for as long as this type owns
550            // it. `run_async` moved the node out of the wrapper, so no other reference exists,
551            // and `future` is declared before `node` so it is dropped first.
552            unsafe { (*ptr.0).run_with_mode(NodeRunMode::Hosted).await }
553        });
554
555        Self {
556            clients,
557            future: Some(future),
558            node: Some(node),
559            owner,
560            handle,
561            event_loop: event_loop.unbind(),
562            wake_pump,
563            state,
564            generation: 0,
565            pending_throw: None,
566        }
567    }
568
569    /// Returns the node to the wrapper, dropping the future that borrows it first.
570    ///
571    /// Releases the per-thread run guard here rather than only on drop, so a completed run does
572    /// not block the next one until the coroutine object happens to be collected.
573    fn restore_node(&mut self, py: Option<Python<'_>>) {
574        Python::attach(|py| {
575            if let Err(e) = self.clients.finish(py) {
576                log::error!("{e}");
577            }
578        });
579
580        self.state.close();
581        self.wake_pump.close();
582        self.future = None;
583        self.wake_pump.join(py);
584
585        if let Some(node) = self.node.take() {
586            *self.owner.borrow_mut() = Some(*node);
587
588            // Release inside the take arm so this runs exactly once, and only for the run that
589            // set the guard. Clearing unconditionally would let a late drop release a newer run's.
590            HOSTED_RUN_ACTIVE.set(false);
591        }
592    }
593
594    /// Returns whether the host event loop is currently running.
595    ///
596    /// Treats an unavailable answer as running, because blocking a live loop is the worse error.
597    fn host_loop_is_running(&self, py: Python<'_>) -> bool {
598        self.event_loop
599            .bind(py)
600            .call_method0(intern!(py, "is_running"))
601            .and_then(|running| running.extract::<bool>())
602            .unwrap_or(true)
603    }
604
605    /// Drives the run to completion on this thread, bounded by [`CLOSE_DRIVE_TIMEOUT`].
606    fn drive_to_completion(&mut self, py: Python<'_>) {
607        let signal = Arc::new(BlockingWake::default());
608        let waker = Waker::from(signal.clone());
609        let deadline = Instant::now() + CLOSE_DRIVE_TIMEOUT;
610
611        loop {
612            let Some(future) = self.future.as_mut() else {
613                return;
614            };
615
616            let poll = {
617                let _guard = get_runtime().enter();
618                future.as_mut().poll(&mut Context::from_waker(&waker))
619            };
620
621            if let Poll::Ready(result) = poll {
622                if let Err(e) = result {
623                    log::error!("Hosted run failed during inline shutdown: {e}");
624                }
625
626                self.restore_node(Some(py));
627                return;
628            }
629
630            // Release the GIL so tokio workers that need it can make progress.
631            if !py.detach(|| signal.wait_until(deadline)) {
632                log::error!(
633                    "Hosted run did not stop within {}s of the host loop closing; abandoning it \
634                     with resources still held",
635                    CLOSE_DRIVE_TIMEOUT.as_secs()
636                );
637                return;
638            }
639        }
640    }
641
642    /// Polls the run future once, returning the asyncio future to suspend on when still running.
643    fn step(&mut self, py: Python<'_>) -> PyResult<Option<Py<PyAny>>> {
644        let Some(future) = self.future.as_mut() else {
645            return Err(to_pyruntime_err("Hosted run has already completed"));
646        };
647
648        let generation = self
649            .generation
650            .checked_add(1)
651            .ok_or_else(|| to_pyruntime_err("Hosted run wake generation exhausted"))?;
652        self.generation = generation;
653
654        // A distinct waker prevents a late wake from an older poll resuming this suspension
655        let waker = self.wake_pump.waker(generation);
656
657        // Timers and the reactor are only reachable inside the runtime context
658        let poll = {
659            let _guard = get_runtime().enter();
660            future.as_mut().poll(&mut Context::from_waker(&waker))
661        };
662
663        match poll {
664            Poll::Ready(result) => {
665                let cleanup = self.clients.finish(py);
666                self.restore_node(Some(py));
667
668                if let Err(e) = &cleanup {
669                    log::error!("{e}");
670                }
671
672                if let Err(e) = &result {
673                    log::error!("Hosted run failed: {e}");
674                }
675
676                if let Some(raised) = self.pending_throw.take() {
677                    // Shutdown finished, so the injected exception is now honored. Reporting
678                    // success here would break `asyncio.timeout`, `wait_for`, and task groups.
679                    if let Err(e) = result {
680                        let shutdown_error = to_pyruntime_err(e);
681                        shutdown_error.set_cause(py, raised.cause(py));
682                        raised.set_cause(py, Some(shutdown_error));
683                    }
684
685                    return Err(raised);
686                }
687
688                result.map_err(to_pyruntime_err)?;
689                cleanup?;
690                Ok(None)
691            }
692            Poll::Pending => {
693                let suspended = self
694                    .event_loop
695                    .bind(py)
696                    .call_method0(intern!(py, "create_future"))?;
697                suspended.setattr(intern!(py, "_asyncio_future_blocking"), true)?;
698
699                // `call_soon_threadsafe` queues the callback, so this publishes before it can run
700                self.state.suspend(generation, suspended.clone().unbind());
701
702                Ok(Some(suspended.unbind()))
703            }
704        }
705    }
706}
707
708#[pymethods]
709impl PyNodeRun {
710    fn __await__(slf: PyRef<'_, Self>) -> PyRef<'_, Self> {
711        slf
712    }
713
714    fn __iter__(slf: PyRef<'_, Self>) -> PyRef<'_, Self> {
715        slf
716    }
717
718    fn __next__(&mut self, py: Python<'_>) -> PyResult<Option<Py<PyAny>>> {
719        self.step(py)
720    }
721
722    #[pyo3(signature = (value=None))]
723    fn send(
724        &mut self,
725        py: Python<'_>,
726        value: Option<&Bound<'_, PyAny>>,
727    ) -> PyResult<Option<Py<PyAny>>> {
728        let _ = value;
729        self.step(py)
730    }
731
732    /// Converts an injected exception into a graceful stop, then re-raises once the node stopped.
733    ///
734    /// Later throws are absorbed while shutdown runs, so a half-stopped node is never abandoned
735    /// with clients connected and channels undrained. The first exception is the one raised.
736    #[pyo3(signature = (*args))]
737    fn throw(&mut self, py: Python<'_>, args: &Bound<'_, PyTuple>) -> PyResult<Option<Py<PyAny>>> {
738        let raised = args.get_item(0)?;
739
740        if self.pending_throw.is_none() {
741            let cancelled_type = cancelled_error_type(py)?;
742            let is_cancelled = raised.is_instance(&cancelled_type)? || raised.is(&cancelled_type);
743            if is_cancelled {
744                log::info!("Hosted run cancelled, requesting graceful shutdown");
745            } else {
746                log::warn!("Exception thrown into hosted run, requesting graceful shutdown");
747            }
748
749            self.pending_throw = Some(PyErr::from_value(raised));
750            self.handle.stop();
751        }
752
753        self.step(py)
754    }
755
756    /// Stops the node, and drives shutdown inline only when no host loop can finish it.
757    ///
758    /// Python calls this when the awaiting task is discarded. With the loop still running, this
759    /// requests the stop and returns, because driving inline would block every host callback; the
760    /// run is then dropped with shutdown incomplete, which the warning names. With no running loop
761    /// nothing else can finish the shutdown, so it is driven here rather than dropping the node
762    /// with venue connections still open.
763    fn close(&mut self, py: Python<'_>) {
764        if self.future.is_none() {
765            return;
766        }
767
768        self.handle.stop();
769
770        // Driving inline blocks this thread, so only do it when the host loop is not running and
771        // therefore cannot finish the shutdown itself.
772        if self.host_loop_is_running(py) {
773            log::warn!(
774                "Hosted run discarded while its event loop is running; shutdown was requested but \
775                 not completed, await the run instead of discarding it"
776            );
777            return;
778        }
779
780        log::warn!("Hosted run closed with no running event loop, draining shutdown inline");
781        self.drive_to_completion(py);
782    }
783
784    fn __repr__(&self) -> String {
785        format!("{self:?}")
786    }
787}
788
789/// Returns the driver that wraps a [`PyNodeRun`] in a native coroutine.
790///
791/// `asyncio.create_task` accepts only coroutines, so returning the awaitable directly would force
792/// every caller to wrap it. Awaiting the coroutine drives the same object, and a cancellation
793/// delivered to the task reaches [`PyNodeRun::throw`] unchanged.
794fn node_run_driver(py: Python<'_>) -> PyResult<&Py<PyAny>> {
795    static DRIVER: PyOnceLock<Py<PyAny>> = PyOnceLock::new();
796
797    DRIVER.get_or_try_init(py, || {
798        let module = PyModule::from_code(
799            py,
800            c_str!("async def drive(run):\n    return await run\n"),
801            c_str!("nautilus_trader/live/_hosted_run.py"),
802            c_str!("nautilus_trader._hosted_run"),
803        )?;
804        Ok(module.getattr("drive")?.unbind())
805    })
806}
807
808/// Returns the `asyncio.CancelledError` type.
809fn cancelled_error_type(py: Python<'_>) -> PyResult<Bound<'_, PyAny>> {
810    py.import("asyncio")?.getattr(intern!(py, "CancelledError"))
811}
812
813/// Reports a borrow that cannot be served because the node is busy inside a call.
814fn node_busy_err() -> PyErr {
815    to_pyruntime_err(
816        "LiveNode is busy servicing another call; do not re-enter the node from a component \
817         callback, use the cache, portfolio, and handle captured beforehand",
818    )
819}
820
821fn node_consumed_err() -> PyErr {
822    to_pyruntime_err(
823        "LiveNode is being run by `run_async`; use the handle returned by `handle()` to stop it, \
824         and the `cache` and `portfolio` captured before the run to read state",
825    )
826}
827
828#[pyo3_stub_gen::derive::gen_stub_pymethods]
829#[pymethods]
830impl PyLiveNode {
831    /// Creates a new `LiveNode` directly from a kernel name and optional configuration.
832    ///
833    /// This is a convenience method for creating a live node with a pre-configured
834    /// kernel configuration, bypassing the builder pattern. If no config is provided,
835    /// a default configuration will be used.
836    ///
837    /// # Errors
838    ///
839    /// Returns an error if kernel construction fails.
840    #[staticmethod]
841    #[pyo3(name = "build")]
842    #[pyo3(signature = (name, config=None, *, data_factories=None, exec_factories=None))]
843    fn py_build(
844        py: Python<'_>,
845        name: String,
846        config: Option<Py<LiveNodeConfig>>,
847        data_factories: Option<Bound<'_, PyDict>>,
848        exec_factories: Option<Bound<'_, PyDict>>,
849    ) -> PyResult<Self> {
850        PyLiveNodeBuilder::py_from_config(py, name, config, data_factories, exec_factories)?
851            .py_build()
852    }
853
854    /// Creates a new `LiveNodeBuilder` for fluent configuration.
855    ///
856    /// # Errors
857    ///
858    /// Returns an error if the environment is invalid for live trading.
859    #[staticmethod]
860    #[pyo3(name = "builder")]
861    fn py_builder(
862        name: String,
863        trader_id: TraderId,
864        environment: Environment,
865    ) -> PyResult<PyLiveNodeBuilder> {
866        match LiveNode::builder(trader_id, environment) {
867            Ok(builder) => Ok(PyLiveNodeBuilder {
868                clients: PythonClients::default(),
869                state: Rc::new(Cell::new(PyLiveNodeBuilderState::Ready(Box::new(
870                    builder.with_name(name),
871                )))),
872            }),
873            Err(e) => Err(to_pyruntime_err(e)),
874        }
875    }
876
877    /// Gets the node's environment.
878    #[getter]
879    #[pyo3(name = "environment")]
880    fn py_environment(&self) -> PyResult<Environment> {
881        Ok(self.node()?.environment())
882    }
883
884    /// Gets the node's trader ID.
885    #[getter]
886    #[pyo3(name = "trader_id")]
887    fn py_trader_id(&self) -> PyResult<TraderId> {
888        Ok(self.node()?.trader_id())
889    }
890
891    /// Gets the node's instance ID.
892    #[getter]
893    #[pyo3(name = "instance_id")]
894    fn py_instance_id(&self) -> PyResult<UUID4> {
895        Ok(self.node()?.instance_id())
896    }
897
898    /// Checks if the live node is currently running.
899    ///
900    /// Answered from the handle, so this stays truthful while a hosted run holds the node.
901    #[getter]
902    #[pyo3(name = "is_running")]
903    fn py_is_running(&self) -> bool {
904        self.handle.is_running()
905    }
906
907    /// Returns the cache shared with the kernel and registered components.
908    #[getter]
909    #[pyo3(name = "cache")]
910    fn py_cache(&self) -> PyResult<PyCache> {
911        Ok(PyCache::from_rc(self.node()?.kernel().cache()))
912    }
913
914    /// Returns the portfolio shared with the kernel and registered components.
915    #[getter]
916    #[pyo3(name = "portfolio")]
917    fn py_portfolio(&self) -> PyResult<PyPortfolio> {
918        Ok(PyPortfolio::from_rc(
919            self.node()?.kernel().portfolio.clone(),
920        ))
921    }
922
923    /// Returns a thread-safe handle for controlling and observing this node.
924    ///
925    /// The handle stays valid for the node's whole lifetime, including while `run_async` owns the
926    /// node, and is the supported way to stop a hosted run.
927    #[pyo3(name = "handle")]
928    fn py_handle(&self) -> PyLiveNodeHandle {
929        PyLiveNodeHandle {
930            inner: self.handle.clone(),
931        }
932    }
933
934    /// Adds a callback for supported typed external messages.
935    ///
936    /// While the node's run loop services external ingress, processors run in registration order
937    /// before normal inbound streaming filters for supported typed JSON or MessagePack payloads.
938    /// Unsupported encodings do not reach processors. Rust callbacks receive the decoded
939    /// concrete value as `Any`, allowing them to downcast to the concrete payload type.
940    ///
941    /// Python callbacks receive the serialized payload shape with an added `payload_type` field.
942    /// Native data replies use the shared response representation keyed by response kind.
943    /// Callback exceptions are logged, stop remaining processors, and skip internal republishing.
944    /// The Python wrapper returns an error if the node is no longer available for mutation.
945    ///
946    /// External egress is suppressed while processors run, so synchronous publications remain
947    /// local. During data-client connection, streaming-registered `DataResponse` messages with a
948    /// pending correlation handler bypass processors and can overtake messages buffered until
949    /// normal dispatch starts.
950    #[pyo3(name = "add_stream_processor")]
951    fn py_add_stream_processor(&self, callback: Py<PyAny>) -> PyResult<()> {
952        self.node_mut()?
953            .add_stream_processor_with_mapping(move |_, mapping| {
954                Python::attach(|py| {
955                    let payload = json_value_to_py(py, mapping)?;
956                    callback.call1(py, (payload,))?;
957                    Ok(())
958                })
959                .map_err(|e: PyErr| anyhow::anyhow!("Python stream processor failed: {e}"))
960            });
961
962        Ok(())
963    }
964
965    /// Runs the live node on the caller's asyncio event loop.
966    ///
967    /// Takes the node and returns an awaitable that resolves once the node has stopped. The host
968    /// owns the loop and its signal handling, so this installs no signal handlers. Stop the node
969    /// through the handle from `handle()`; cancelling the awaiting task requests the same graceful
970    /// shutdown, waits for it to finish, then re-raises the cancellation. A shutdown error,
971    /// including incomplete submission recovery, is preserved as the exception's cause.
972    ///
973    /// Capture `cache`, `portfolio`, and `handle()` before calling this. They stay usable while the
974    /// node runs, whereas the node itself is owned by the returned awaitable.
975    ///
976    /// # Limitations
977    ///
978    /// A node configured with a cache database backing is rejected. Those backings wait for their
979    /// worker task by blocking the calling thread, which stalls the host loop rather than merely
980    /// slowing it. Use `run()` for a database-backed node until the backings can be driven without
981    /// blocking a host loop.
982    ///
983    /// # Errors
984    ///
985    /// Returns an error if the node has already been taken, no event loop is running, a cache
986    /// database backing is configured, or another node is already running on this loop.
987    #[gen_stub(override_return_type(
988        type_repr = "collections.abc.Coroutine[typing.Any, typing.Any, None]",
989        imports = ("collections.abc", "typing")
990    ))]
991    #[pyo3(name = "run_async")]
992    fn py_run_async(&self, py: Python<'_>) -> PyResult<Py<PyAny>> {
993        let event_loop = py
994            .import("asyncio")?
995            .call_method0("get_running_loop")
996            .map_err(|_| {
997                to_pyruntime_err(
998                    "`run_async` requires a running asyncio event loop; use `run` to have the node \
999                     own the thread instead",
1000                )
1001            })?;
1002
1003        // A node runs once. Rejecting anything past `Idle` here turns a second run into an
1004        // immediate error rather than a coroutine that fails only when awaited.
1005        let state = self.node()?.state();
1006        if state != NodeState::Idle {
1007            return Err(to_pyruntime_err(format!(
1008                "LiveNode cannot be run from state {state:?}; build a new node to run again"
1009            )));
1010        }
1011
1012        // The Redis and SQL cache backings block the calling thread while awaiting their worker
1013        // task, which would freeze the host loop inside a poll rather than merely slow it down.
1014        // Fail before taking the node so the caller gets a clear boundary instead of a hang.
1015        if self.node()?.has_pending_cache_database() {
1016            return Err(to_pyruntime_err(
1017                "a cache database backing is not supported on a host event loop, because its \
1018                 blocking calls would stall the loop; native-only nodes can use `run()`, \
1019                 but custom Python clients require a node without a cache database",
1020            ));
1021        }
1022
1023        if HOSTED_RUN_ACTIVE.get() {
1024            return Err(to_pyruntime_err(
1025                "another LiveNode is already running on this event loop; run one concurrent \
1026                 LiveNode per process, or run additional nodes in separate processes",
1027            ));
1028        }
1029
1030        // Everything fallible happens before the node is taken, so a failure here cannot strand
1031        // it. `PyNodeRun` restores the node on drop, covering the paths after this point.
1032        let driver = node_run_driver(py)?.clone_ref(py);
1033        let state = Arc::new(RunWakeState::default());
1034
1035        let wake_callback = Py::new(
1036            py,
1037            PyNodeRunWake {
1038                state: state.clone(),
1039            },
1040        )?
1041        .into_any();
1042
1043        let wake_pump = HostWakePump::start(
1044            event_loop.clone().unbind(),
1045            wake_callback,
1046            self.handle.clone(),
1047        )?;
1048
1049        self.clients.bind(py, &event_loop)?;
1050
1051        let node = self
1052            .inner
1053            .borrow_mut()
1054            .take()
1055            .ok_or_else(node_consumed_err)?;
1056
1057        let run = PyNodeRun::new(
1058            node,
1059            self.inner.clone(),
1060            event_loop,
1061            state,
1062            wake_pump,
1063            self.clients.clone(),
1064        );
1065        HOSTED_RUN_ACTIVE.set(true);
1066
1067        driver.call1(py, (Py::new(py, run)?,))
1068    }
1069
1070    /// Run the live node with automatic shutdown handling.
1071    ///
1072    /// This method starts the node, runs indefinitely, and handles graceful shutdown
1073    /// on interrupt signals.
1074    ///
1075    /// # Thread Safety
1076    ///
1077    /// The event loop runs directly on the current thread (not spawned) because the
1078    /// msgbus uses thread-local storage. Endpoints registered by the kernel are only
1079    /// accessible from the same thread.
1080    ///
1081    /// # Shutdown Sequence
1082    ///
1083    /// 1. Signal received (SIGINT, SIGTERM, or handle stop).
1084    /// 2. Trader components stopped (triggers order cancellations, etc.).
1085    /// 3. Event loop continues processing residual events for the configured grace period.
1086    /// 4. Kernel finalized, clients disconnected, remaining events drained.
1087    ///
1088    /// # Errors
1089    ///
1090    /// Returns an error if the node fails to start or encounters a runtime error.
1091    #[pyo3(name = "run", signature = ())]
1092    fn py_run(slf: &Bound<'_, Self>, py: Python) -> PyResult<()> {
1093        let this = slf.borrow();
1094        if !this.clients.is_empty() {
1095            let asyncio = py.import("asyncio")?;
1096            if asyncio.call_method0("get_running_loop").is_ok() {
1097                return Err(to_pyruntime_err(
1098                    "run() cannot be called from a running event loop; await run_async()",
1099                ));
1100            }
1101
1102            let handle = this.handle.clone();
1103            drop(this);
1104            let driver = PyModule::from_code(
1105                py,
1106                c_str!("async def run(node):\n    return await node.run_async()\n"),
1107                c_str!("client_run.py"),
1108                c_str!("client_run"),
1109            )?;
1110            let event_loop = asyncio.call_method0("new_event_loop")?;
1111            let signal = py.import("signal")?;
1112            let threading = py.import("threading")?;
1113            let is_main = threading
1114                .call_method0("current_thread")?
1115                .is(&threading.call_method0("main_thread")?);
1116
1117            let mut handlers = Vec::new();
1118
1119            let result = (|| -> PyResult<()> {
1120                if is_main {
1121                    let callback = new_sync_py_callback(py, move |_args, _kwargs| {
1122                        handle.stop();
1123                        Ok(())
1124                    })?;
1125
1126                    for name in ["SIGINT", "SIGTERM"] {
1127                        if let Ok(signum) = signal.getattr(name) {
1128                            let original = signal.call_method1("signal", (&signum, &callback))?;
1129                            handlers.push((signum, original));
1130                        }
1131                    }
1132                }
1133
1134                let coroutine = driver.getattr("run")?.call1((slf,))?;
1135                event_loop.call_method1("run_until_complete", (coroutine,))?;
1136                Ok(())
1137            })();
1138
1139            return finish_owned_run(&event_loop, &signal, handlers, result);
1140        }
1141
1142        if this.node()?.is_running() {
1143            return Err(to_pyruntime_err("LiveNode is already running"));
1144        }
1145
1146        // Get a handle for coordinating with the signal checker
1147        let handle = this.node()?.handle();
1148
1149        // Import signal module
1150        let signal_module = py.import("signal")?;
1151        let original_handler =
1152            signal_module.call_method1("signal", (2, signal_module.getattr("SIG_DFL")?))?; // Save original SIGINT handler (signal 2)
1153
1154        // Set up a custom signal handler that uses our handle
1155        let handle_for_signal = handle;
1156
1157        let signal_callback = new_sync_py_callback(
1158            py,
1159            move |_args: &pyo3::Bound<'_, PyTuple>,
1160                  _kwargs: Option<&pyo3::Bound<'_, PyDict>>|
1161                  -> PyResult<()> {
1162                log::info!("Python signal handler called");
1163                handle_for_signal.stop();
1164                Ok(())
1165            },
1166        )?;
1167
1168        // Install our signal handler
1169        signal_module.call_method1("signal", (2, signal_callback))?;
1170
1171        // Run the node and restore signal handler afterward
1172        let mut node = this.node_mut()?;
1173        let result = run_live_node_detached(py, &mut node);
1174
1175        // Restore original signal handler
1176        signal_module.call_method1("signal", (2, original_handler))?;
1177
1178        result
1179    }
1180
1181    /// Stop the live node.
1182    ///
1183    /// This method stops the trader, waits for the configured grace period to allow
1184    /// residual events to be processed, then finalizes the shutdown sequence.
1185    ///
1186    /// # Errors
1187    ///
1188    /// Returns an error if shutdown fails.
1189    #[pyo3(name = "stop")]
1190    fn py_stop(&self, py: Python<'_>) -> PyResult<()> {
1191        let mut node = self.node_mut()?;
1192        if !node.is_running() {
1193            return Err(to_pyruntime_err("LiveNode is not running"));
1194        }
1195
1196        stop_live_node_detached(py, &mut node)
1197    }
1198
1199    /// Disposes the live node kernel and releases resources.
1200    ///
1201    /// Does nothing while a hosted run holds the node. The run returns the node when it finishes,
1202    /// so a `try`/`finally` cleanup that outlives the run disposes it as usual.
1203    #[pyo3(name = "dispose")]
1204    fn py_dispose(&self, py: Python<'_>) -> PyResult<()> {
1205        if self.is_consumed() {
1206            return Ok(());
1207        }
1208
1209        let mut node = self.node_mut()?;
1210
1211        let stop_result = if node.is_running() {
1212            stop_live_node_detached(py, &mut node)
1213        } else {
1214            Ok(())
1215        };
1216
1217        if let Err(ref err) = stop_result {
1218            log::error!("Failed to stop LiveNode during dispose: {err}");
1219        }
1220
1221        node.dispose();
1222        drop(node);
1223        let cleanup_result = self.clients.finish(py);
1224        stop_result.and(cleanup_result)
1225    }
1226
1227    /// Adds a constructed Python actor to the trader.
1228    ///
1229    /// # Errors
1230    ///
1231    /// Returns an error if the node is running, the actor is invalid, or registration fails.
1232    #[pyo3(name = "add_actor")]
1233    fn py_add_actor(&self, actor: &Bound<'_, PyAny>) -> PyResult<()> {
1234        if self.node()?.state() != NodeState::Idle {
1235            return Err(to_pyruntime_err(
1236                "Cannot add actor while node is running, add actors before running the node",
1237            ));
1238        }
1239
1240        log::debug!("`add_actor` with a constructed instance");
1241
1242        let actor = actor.clone().unbind();
1243
1244        let actor_id = Python::attach(|py| {
1245            let actor = actor.bind(py);
1246            let config = actor
1247                .getattr("config")
1248                .ok()
1249                .filter(|config| !config.is_none());
1250            prepare_python_actor(actor, config.as_ref())
1251        })
1252        .map_err(to_pyruntime_err)?;
1253
1254        self.register_python_actor(&actor, actor_id)
1255    }
1256
1257    #[pyo3(name = "add_actor_from_config")]
1258    #[expect(clippy::needless_pass_by_value)]
1259    fn py_add_actor_from_config(&self, _py: Python, config: ImportableActorConfig) -> PyResult<()> {
1260        log::debug!("`add_actor_from_config` with: {config:?}");
1261
1262        // Extract module and class name from actor_path
1263        let parts: Vec<&str> = config.actor_path.split(':').collect();
1264        if parts.len() != 2 {
1265            return Err(to_pyvalue_err(
1266                "actor_path must be in format 'module.path:ClassName'",
1267            ));
1268        }
1269
1270        let (module_name, class_name) = (parts[0], parts[1]);
1271
1272        log::info!("Importing actor from module: {module_name} class: {class_name}");
1273
1274        let (python_actor, actor_id) =
1275            Python::attach(|py| -> anyhow::Result<(Py<PyAny>, ActorId)> {
1276                let actor_module = py
1277                    .import(module_name)
1278                    .map_err(|e| anyhow::anyhow!("Failed to import module {module_name}: {e}"))?;
1279                let actor_class = actor_module
1280                    .getattr(class_name)
1281                    .map_err(|e| anyhow::anyhow!("Failed to get class {class_name}: {e}"))?;
1282
1283                let config_instance =
1284                    create_config_instance(py, &config.config_path, &config.config)?;
1285
1286                let python_actor = if let Some(config_obj) = config_instance.as_ref() {
1287                    actor_class.call1((config_obj,))?
1288                } else {
1289                    actor_class.call0()?
1290                };
1291
1292                log::debug!("Created Python actor instance: {python_actor:?}");
1293
1294                let actor_id = prepare_python_actor(&python_actor, config_instance.as_ref())?;
1295
1296                Ok((python_actor.unbind(), actor_id))
1297            })
1298            .map_err(to_pyruntime_err)?;
1299
1300        self.register_python_actor(&python_actor, actor_id)
1301    }
1302
1303    /// Adds a strategy to the trader.
1304    ///
1305    /// Strategies are registered in both the component registry (for lifecycle management)
1306    /// and the actor registry (for data callbacks via msgbus).
1307    ///
1308    /// # Errors
1309    ///
1310    /// Returns an error if:
1311    /// - The node is currently running.
1312    /// - A strategy with the same ID is already registered.
1313    /// - The configured external order instrument IDs repeat an instrument or the cache already
1314    ///   contains a requested claim.
1315    /// - The strategy configures one or more external order instrument IDs and the cache is already
1316    ///   borrowed.
1317    /// - The strategy configures an OMS type override and the execution engine is already borrowed.
1318    #[allow(
1319        unsafe_code,
1320        reason = "Required for Python strategy component registration"
1321    )]
1322    #[pyo3(name = "add_strategy")]
1323    fn py_add_strategy(&self, strategy: &Bound<'_, PyAny>) -> PyResult<()> {
1324        if self.node()?.state() != NodeState::Idle {
1325            return Err(to_pyruntime_err(
1326                "Cannot add strategy while node is running, add strategies before running the node",
1327            ));
1328        }
1329
1330        log::debug!("`add_strategy` with a constructed instance");
1331
1332        let strategy = strategy.clone().unbind();
1333
1334        let strategy_id = self
1335            .node_mut()?
1336            .kernel_mut()
1337            .trader
1338            .borrow_mut()
1339            .prepare_python_strategy_instance(&strategy)
1340            .map_err(to_pyruntime_err)?;
1341
1342        let (external_order_instrument_ids, oms_type) = Python::attach(
1343            |py| -> anyhow::Result<(Option<Vec<InstrumentId>>, Option<OmsType>)> {
1344                let bound = strategy.bind(py);
1345                let config_obj = bound
1346                    .getattr("config")
1347                    .ok()
1348                    .filter(|config| !config.is_none());
1349
1350                let mut py_strategy_ref = bound
1351                    .extract::<PyRefMut<PyStrategy>>()
1352                    .map_err(Into::<PyErr>::into)
1353                    .map_err(|e| anyhow::anyhow!("Failed to extract PyStrategy: {e}"))?;
1354
1355                if let Some(config_obj) = config_obj.as_ref()
1356                    && let Some(claims) =
1357                        extract_external_order_instrument_ids_config_attr(config_obj)?
1358                {
1359                    py_strategy_ref.set_external_order_instrument_ids(Some(claims));
1360                }
1361
1362                let claims = py_strategy_ref.external_order_instrument_ids();
1363                let oms_type = config_obj
1364                    .as_ref()
1365                    .and_then(|cfg| cfg.getattr("oms_type").ok())
1366                    .filter(|value| !value.is_none())
1367                    .and_then(|value| value.extract::<OmsType>().ok());
1368
1369                Ok((claims, oms_type))
1370            },
1371        )
1372        .map_err(to_pyruntime_err)?;
1373
1374        let external_order_instrument_ids =
1375            external_order_instrument_ids.filter(|claims| !claims.is_empty());
1376        if let Some(claims) = &external_order_instrument_ids {
1377            self.node_mut()?
1378                .register_external_order_claims(strategy_id, claims)
1379                .map_err(to_pyruntime_err)?;
1380        }
1381
1382        let commit_result = self
1383            .node_mut()?
1384            .kernel_mut()
1385            .trader
1386            .borrow_mut()
1387            .commit_python_strategy_instance(&strategy);
1388
1389        if let Err(commit_error) = commit_result {
1390            if let Some(instrument_ids) = external_order_instrument_ids.as_deref()
1391                && let Err(rollback_error) = self
1392                    .node_mut()?
1393                    .rollback_external_order_claims(strategy_id, instrument_ids)
1394            {
1395                return Err(to_pyruntime_err(format!(
1396                    "Failed to add strategy {strategy_id}: {commit_error}; failed to roll back external order claims: {rollback_error}"
1397                )));
1398            }
1399
1400            return Err(to_pyruntime_err(commit_error));
1401        }
1402
1403        if let Some(oms_type) = oms_type {
1404            self.node_mut()?
1405                .kernel()
1406                .exec_engine
1407                .borrow_mut()
1408                .register_oms_type(strategy_id, oms_type);
1409        }
1410
1411        log::info!("Registered Python strategy {strategy_id}");
1412        Ok(())
1413    }
1414
1415    #[pyo3(name = "add_strategy_from_config")]
1416    #[expect(clippy::needless_pass_by_value)]
1417    fn py_add_strategy_from_config(
1418        &self,
1419        _py: Python,
1420        config: ImportableStrategyConfig,
1421    ) -> PyResult<()> {
1422        self.node_mut()?.add_python_strategy_from_config(&config)
1423    }
1424
1425    /// Adds an execution algorithm to the trader.
1426    ///
1427    /// Execution algorithms are registered in both the component registry (for lifecycle
1428    /// management) and the actor registry (for data callbacks via msgbus).
1429    ///
1430    /// # Errors
1431    ///
1432    /// Returns an error if:
1433    /// - The node is currently running.
1434    /// - An execution algorithm with the same ID is already registered.
1435    #[pyo3(name = "add_exec_algorithm")]
1436    fn py_add_exec_algorithm(&self, exec_algorithm: &Bound<'_, PyAny>) -> PyResult<()> {
1437        if self.node()?.state() != NodeState::Idle {
1438            return Err(to_pyruntime_err(
1439                "Cannot add exec algorithm while node is running, add exec algorithms before running the node",
1440            ));
1441        }
1442
1443        log::debug!("`add_exec_algorithm` with a constructed instance");
1444
1445        let exec_algorithm = exec_algorithm.clone().unbind();
1446        let py_exec_algorithm = Python::attach(|py| -> anyhow::Result<PyExecutionAlgorithm> {
1447            let bound = exec_algorithm.bind(py);
1448            let config = bound
1449                .getattr("config")
1450                .ok()
1451                .filter(|config| !config.is_none());
1452
1453            let mut py_exec_algorithm_ref = bound
1454                .extract::<PyRefMut<PyExecutionAlgorithm>>()
1455                .map_err(Into::<PyErr>::into)
1456                .map_err(|e| {
1457                    anyhow::anyhow!(
1458                        "LiveNode.add_exec_algorithm requires a Python v2 ExecutionAlgorithm instance; use add_exec_algorithm_from_config for DataActor-based algorithms: {e}"
1459                    )
1460                })?;
1461
1462            if let Some(config) = config.as_ref() {
1463                py_exec_algorithm_ref.configure_from_py_config(config)?;
1464            }
1465
1466            py_exec_algorithm_ref.set_python_instance(bound)?;
1467            Ok(py_exec_algorithm_ref.clone())
1468        })
1469        .map_err(to_pyruntime_err)?;
1470
1471        let exec_algorithm_id = self
1472            .node_mut()?
1473            .kernel_mut()
1474            .trader
1475            .borrow_mut()
1476            .add_py_execution_algorithm_instance(py_exec_algorithm, &exec_algorithm)
1477            .map_err(to_pyruntime_err)?;
1478
1479        log::info!("Registered Python exec algorithm {exec_algorithm_id}");
1480        Ok(())
1481    }
1482
1483    #[pyo3(name = "add_exec_algorithm_from_config")]
1484    #[expect(clippy::needless_pass_by_value)]
1485    fn py_add_exec_algorithm_from_config(
1486        &self,
1487        _py: Python,
1488        config: ImportableExecutionAlgorithmConfig,
1489    ) -> PyResult<()> {
1490        self.node_mut()?
1491            .add_python_exec_algorithm_from_config(&config)
1492    }
1493
1494    /// Loads and registers one plug-in instance.
1495    ///
1496    /// # Errors
1497    ///
1498    /// Returns an error if called. Dynamic plug-in hosting lives in the host-side integration.
1499    #[pyo3(name = "add_plugin", signature = (path, type_name, config=None, sha256=None))]
1500    fn py_add_plugin(
1501        &self,
1502        path: String,
1503        type_name: String,
1504        config: Option<HashMap<String, Py<PyAny>>>,
1505        sha256: Option<String>,
1506    ) -> PyResult<()> {
1507        let config = PluginConfig {
1508            path,
1509            type_name,
1510            config: match config {
1511                Some(config) => coerce_json_config(config)?,
1512                None => HashMap::new(),
1513            },
1514            sha256,
1515        };
1516
1517        self.node_mut()?
1518            .add_plugin(config)
1519            .map_err(to_pyruntime_err)
1520    }
1521
1522    /// Adds a built-in example actor from its type name and config.
1523    ///
1524    /// This method exists only to single-source bundled example actor code across
1525    /// Rust and Python tests/examples. It is not a first-class extension path for
1526    /// adding native actors.
1527    #[cfg(feature = "examples")]
1528    #[pyo3(name = "add_builtin_actor")]
1529    fn py_add_builtin_actor(&self, type_name: &str, config: &Bound<'_, PyAny>) -> PyResult<()> {
1530        let register = builtin_actor_register(type_name).ok_or_else(|| {
1531            to_pytype_err(format!("Unsupported built-in actor type: {type_name}"))
1532        })?;
1533
1534        let mut node = self.node_mut()?;
1535        register(&mut node, config)
1536    }
1537
1538    /// Adds a built-in example strategy from its type name and config.
1539    ///
1540    /// This method exists only to single-source bundled example strategy code across
1541    /// Rust and Python tests/examples. It is not a first-class extension path for
1542    /// adding native strategies.
1543    #[cfg(feature = "examples")]
1544    #[pyo3(name = "add_builtin_strategy")]
1545    fn py_add_builtin_strategy(&self, type_name: &str, config: &Bound<'_, PyAny>) -> PyResult<()> {
1546        let register = builtin_strategy_register(type_name).ok_or_else(|| {
1547            to_pytype_err(format!("Unsupported built-in strategy type: {type_name}"))
1548        })?;
1549
1550        let mut node = self.node_mut()?;
1551        register(&mut node, config)
1552    }
1553
1554    fn __repr__(&self) -> String {
1555        format!(
1556            "LiveNode(trader_id={}, environment={}, running={})",
1557            self.node()
1558                .map_or_else(|_| "<running>".to_string(), |n| n.trader_id().to_string()),
1559            self.node().map_or_else(
1560                |_| "<running>".to_string(),
1561                |n| format!("{:?}", n.environment())
1562            ),
1563            self.py_is_running()
1564        )
1565    }
1566}
1567
1568impl LiveNode {
1569    // panics-doc-ok
1570    /// Imports and registers a Python strategy before the node starts.
1571    ///
1572    /// Uses the same registration and external order claims as Python's
1573    /// `LiveNode.add_strategy_from_config` method.
1574    /// Requires an initialized Python interpreter with the strategy and configuration
1575    /// modules on its import path.
1576    ///
1577    /// # Panics
1578    ///
1579    /// Panics if Python has not been initialized.
1580    ///
1581    /// # Errors
1582    ///
1583    /// Returns an error if:
1584    /// - The node is not idle.
1585    /// - The strategy or configuration path is invalid.
1586    /// - Python import, construction, or registration fails.
1587    pub fn add_python_strategy_from_config(
1588        &mut self,
1589        config: &ImportableStrategyConfig,
1590    ) -> PyResult<()> {
1591        if self.state() != NodeState::Idle {
1592            return Err(to_pyruntime_err(
1593                "Cannot add strategy while node is running, add strategies before running the node",
1594            ));
1595        }
1596
1597        log::debug!("`add_strategy_from_config` with: {config:?}");
1598
1599        // Extract module and class name from strategy_path
1600        let parts: Vec<&str> = config.strategy_path.split(':').collect();
1601        if parts.len() != 2 {
1602            return Err(to_pyvalue_err(
1603                "strategy_path must be in format 'module.path:ClassName'",
1604            ));
1605        }
1606
1607        let (module_name, class_name) = (parts[0], parts[1]);
1608
1609        log::info!("Importing strategy from module: {module_name} class: {class_name}");
1610
1611        // Phase 1: Create the Python strategy, then prepare it for registration so the strategy ID,
1612        // order ID tag, and logging flags are sourced from the same config as the instance path
1613        let python_strategy = Python::attach(|py| -> anyhow::Result<Py<PyAny>> {
1614            let strategy_module = py
1615                .import(module_name)
1616                .map_err(|e| anyhow::anyhow!("Failed to import module {module_name}: {e}"))?;
1617            let strategy_class = strategy_module
1618                .getattr(class_name)
1619                .map_err(|e| anyhow::anyhow!("Failed to get class {class_name}: {e}"))?;
1620
1621            let config_instance = create_config_instance(py, &config.config_path, &config.config)?;
1622
1623            let python_strategy = if let Some(config_obj) = config_instance {
1624                strategy_class.call1((config_obj,))?
1625            } else {
1626                strategy_class.call0()?
1627            };
1628
1629            log::debug!("Created Python strategy instance: {python_strategy:?}");
1630
1631            Ok(python_strategy.unbind())
1632        })
1633        .map_err(to_pyruntime_err)?;
1634
1635        let strategy_id = self
1636            .kernel_mut()
1637            .trader
1638            .borrow_mut()
1639            .prepare_python_strategy_instance(&python_strategy)
1640            .map_err(to_pyruntime_err)?;
1641
1642        Python::attach(|py| -> anyhow::Result<()> {
1643            let bound = python_strategy.bind(py);
1644            let config_obj = bound
1645                .getattr("config")
1646                .ok()
1647                .filter(|config| !config.is_none());
1648
1649            let mut py_strategy_ref = bound
1650                .extract::<PyRefMut<PyStrategy>>()
1651                .map_err(Into::<PyErr>::into)
1652                .map_err(|e| anyhow::anyhow!("Failed to extract PyStrategy: {e}"))?;
1653
1654            if let Some(config_obj) = config_obj.as_ref()
1655                && let Some(claims) = extract_external_order_instrument_ids_config_attr(config_obj)?
1656            {
1657                py_strategy_ref.set_external_order_instrument_ids(Some(claims));
1658            }
1659
1660            Ok(())
1661        })
1662        .map_err(to_pyruntime_err)?;
1663
1664        // Phase 2: Claim external orders before committing, matching the instance path
1665        let external_order_instrument_ids =
1666            Python::attach(|py| -> anyhow::Result<Option<Vec<_>>> {
1667                let py_strategy = python_strategy.bind(py);
1668                let py_strategy_ref = py_strategy
1669                    .extract::<PyRef<PyStrategy>>()
1670                    .map_err(Into::<PyErr>::into)
1671                    .map_err(|e| anyhow::anyhow!("Failed to extract PyStrategy: {e}"))?;
1672
1673                Ok(py_strategy_ref.external_order_instrument_ids())
1674            })
1675            .map_err(to_pyruntime_err)?;
1676
1677        let external_order_instrument_ids =
1678            external_order_instrument_ids.filter(|claims| !claims.is_empty());
1679        if let Some(claims) = &external_order_instrument_ids {
1680            self.register_external_order_claims(strategy_id, claims)
1681                .map_err(to_pyruntime_err)?;
1682        }
1683
1684        // Phase 3: Register the strategy through the trader's single Python registration path
1685        let commit_result = self
1686            .kernel_mut()
1687            .trader
1688            .borrow_mut()
1689            .commit_python_strategy_instance(&python_strategy);
1690
1691        if let Err(commit_error) = commit_result {
1692            if let Some(instrument_ids) = external_order_instrument_ids.as_deref()
1693                && let Err(rollback_error) =
1694                    self.rollback_external_order_claims(strategy_id, instrument_ids)
1695            {
1696                return Err(to_pyruntime_err(format!(
1697                    "Failed to add strategy {strategy_id}: {commit_error}; failed to roll back external order claims: {rollback_error}"
1698                )));
1699            }
1700
1701            return Err(to_pyruntime_err(commit_error));
1702        }
1703
1704        log::info!("Registered Python strategy {strategy_id}");
1705        Ok(())
1706    }
1707
1708    // panics-doc-ok
1709    /// Imports and registers a Python execution algorithm.
1710    ///
1711    /// Uses the same registration as Python's `LiveNode.add_exec_algorithm_from_config`,
1712    /// including `DataActor`-backed algorithms. The caller initializes Python and makes the
1713    /// algorithm and configuration modules importable before calling this method.
1714    ///
1715    /// # Errors
1716    ///
1717    /// Returns an error if:
1718    /// - The node is running, or the class derives from `ExecutionAlgorithm` and the node is not idle.
1719    /// - An import path is invalid, or importing, construction, configuration, or registration fails.
1720    ///
1721    /// # Panics
1722    ///
1723    /// Panics if Python has not been initialized.
1724    pub fn add_python_exec_algorithm_from_config(
1725        &mut self,
1726        config: &ImportableExecutionAlgorithmConfig,
1727    ) -> PyResult<()> {
1728        if self.is_running() {
1729            return Err(to_pyruntime_err(
1730                "Cannot add exec algorithm while node is running",
1731            ));
1732        }
1733
1734        log::debug!("`add_exec_algorithm_from_config` with: {config:?}");
1735
1736        let (python_exec_algorithm, py_execution_algorithm, actor_id) =
1737            create_python_exec_algorithm(config)?;
1738
1739        let exec_algorithm_id = if let Some(py_execution_algorithm) = py_execution_algorithm {
1740            // This branch registered through `LiveNode::add_exec_algorithm` before the trader owned
1741            // the path, so it keeps that method's stricter state requirement
1742            if self.state() != NodeState::Idle {
1743                return Err(to_pyruntime_err(
1744                    "Cannot add exec algorithm while node is running, add exec algorithms before running the node",
1745                ));
1746            }
1747
1748            self.kernel_mut()
1749                .trader
1750                .borrow_mut()
1751                .add_py_execution_algorithm_instance(py_execution_algorithm, &python_exec_algorithm)
1752                .map_err(to_pyruntime_err)?
1753        } else {
1754            // Phase 2: Register the DataActor-backed algorithm through the trader's single Python
1755            // registration path
1756            self.kernel_mut()
1757                .trader
1758                .borrow_mut()
1759                .add_python_exec_algorithm_instance(&python_exec_algorithm, actor_id)
1760                .map_err(to_pyruntime_err)?
1761        };
1762
1763        log::info!("Registered Python exec algorithm {exec_algorithm_id}");
1764        Ok(())
1765    }
1766}
1767
1768impl PyLiveNode {
1769    fn register_python_actor(&self, actor: &Py<PyAny>, actor_id: ActorId) -> PyResult<()> {
1770        if self
1771            .node()?
1772            .kernel()
1773            .trader
1774            .borrow()
1775            .actor_ids()
1776            .contains(&actor_id)
1777        {
1778            return Err(to_pyruntime_err(format!(
1779                "Actor '{actor_id}' is already registered"
1780            )));
1781        }
1782
1783        self.node_mut()?
1784            .kernel_mut()
1785            .trader
1786            .borrow_mut()
1787            .add_python_actor_instance(actor, actor_id)
1788            .map_err(to_pyruntime_err)?;
1789
1790        log::info!("Registered Python actor {actor_id}");
1791        Ok(())
1792    }
1793}
1794
1795fn finish_owned_run<'py>(
1796    event_loop: &Bound<'py, PyAny>,
1797    signal: &Bound<'py, PyModule>,
1798    handlers: Vec<(Bound<'py, PyAny>, Bound<'py, PyAny>)>,
1799    result: PyResult<()>,
1800) -> PyResult<()> {
1801    let mut errors: Vec<PyErr> = result.err().into_iter().collect();
1802
1803    if let Err(e) = event_loop.call_method0("close") {
1804        errors.push(e);
1805    }
1806
1807    for (signum, original) in handlers {
1808        if let Err(e) = signal.call_method1("signal", (signum, original)) {
1809            errors.push(e);
1810        }
1811    }
1812
1813    match errors.len() {
1814        0 => Ok(()),
1815        1 => Err(errors.pop().unwrap()),
1816        _ => Err(PyBaseExceptionGroup::new_err((
1817            "LiveNode run and cleanup failed",
1818            errors,
1819        ))),
1820    }
1821}
1822
1823fn new_sync_py_callback<F>(py: Python<'_>, closure: F) -> PyResult<Bound<'_, PyCFunction>>
1824where
1825    F: Fn(&Bound<'_, PyTuple>, Option<&Bound<'_, PyDict>>) -> PyResult<()> + Send + Sync + 'static,
1826{
1827    PyCFunction::new_closure(py, None, None, closure)
1828}
1829
1830#[allow(unsafe_code)]
1831fn run_live_node_detached(py: Python<'_>, node: &mut LiveNode) -> PyResult<()> {
1832    let node_ptr = SendPtr(std::ptr::from_mut::<LiveNode>(node));
1833
1834    // SAFETY: `py_run` holds the only mutable reference to `LiveNode` until
1835    // `run()` returns, and the detached closure completes before `py_run` can
1836    // access `node` again.
1837    unsafe {
1838        py.detach(move || {
1839            let ptr = node_ptr;
1840            get_runtime().block_on(async { (*ptr.0).run().await })
1841        })
1842    }
1843    .map_err(to_pyruntime_err)
1844}
1845
1846#[allow(unsafe_code)]
1847fn stop_live_node_detached(py: Python<'_>, node: &mut LiveNode) -> PyResult<()> {
1848    let node_ptr = SendPtr(std::ptr::from_mut::<LiveNode>(node));
1849
1850    // SAFETY: the Python binding holds the only mutable reference to `LiveNode`
1851    // until `stop()` returns, and the detached closure completes before the
1852    // caller can access `node` again.
1853    unsafe {
1854        py.detach(move || {
1855            let ptr = node_ptr;
1856            get_runtime().block_on(async { (*ptr.0).stop().await })
1857        })
1858    }
1859    .map_err(to_pyruntime_err)
1860}
1861
1862fn create_python_exec_algorithm(
1863    config: &ImportableExecutionAlgorithmConfig,
1864) -> PyResult<(Py<PyAny>, Option<PyExecutionAlgorithm>, ActorId)> {
1865    let parts: Vec<&str> = config.exec_algorithm_path.split(':').collect();
1866    if parts.len() != 2 {
1867        return Err(to_pyvalue_err(
1868            "exec_algorithm_path must be in format 'module.path:ClassName'",
1869        ));
1870    }
1871
1872    let (module_name, class_name) = (parts[0], parts[1]);
1873
1874    log::info!("Importing exec algorithm from module: {module_name} class: {class_name}");
1875
1876    // Phase 1: Create and configure the Python exec algorithm.
1877    Python::attach(
1878        |py| -> anyhow::Result<(Py<PyAny>, Option<PyExecutionAlgorithm>, ActorId)> {
1879            let algo_module = py
1880                .import(module_name)
1881                .map_err(|e| anyhow::anyhow!("Failed to import module {module_name}: {e}"))?;
1882            let algo_class = algo_module
1883                .getattr(class_name)
1884                .map_err(|e| anyhow::anyhow!("Failed to get class {class_name}: {e}"))?;
1885
1886            let config_instance = create_config_instance(py, &config.config_path, &config.config)?;
1887
1888            let python_exec_algorithm = if let Some(config_obj) = config_instance.clone() {
1889                algo_class.call1((config_obj,))?
1890            } else {
1891                algo_class.call0()?
1892            };
1893
1894            log::debug!("Created Python exec algorithm instance: {python_exec_algorithm:?}");
1895
1896            let (prepared, actor_id) =
1897                prepare_python_exec_algorithm(&python_exec_algorithm, config_instance.as_ref())?;
1898            Ok((python_exec_algorithm.unbind(), prepared, actor_id))
1899        },
1900    )
1901    .map_err(to_pyruntime_err)
1902}
1903
1904fn prepare_python_exec_algorithm(
1905    algorithm: &Bound<'_, PyAny>,
1906    config: Option<&Bound<'_, PyAny>>,
1907) -> anyhow::Result<(Option<PyExecutionAlgorithm>, ActorId)> {
1908    if let Ok(mut py_exec_algorithm_ref) = algorithm.extract::<PyRefMut<PyExecutionAlgorithm>>() {
1909        if let Some(config_obj) = config {
1910            py_exec_algorithm_ref.configure_from_py_config(config_obj)?;
1911        }
1912
1913        py_exec_algorithm_ref.set_python_instance(algorithm)?;
1914        let actor_id = ActorId::new(py_exec_algorithm_ref.exec_algorithm_id().inner());
1915
1916        return Ok((Some(py_exec_algorithm_ref.clone()), actor_id));
1917    }
1918
1919    let mut py_data_actor_ref = algorithm
1920        .extract::<PyRefMut<PyDataActor>>()
1921        .map_err(Into::<PyErr>::into)
1922        .map_err(|e| anyhow::anyhow!("Failed to extract PyDataActor: {e}"))?;
1923
1924    // Extract ID from config: prefer exec_algorithm_id, fall back to actor_id
1925    if let Some(config_obj) = config {
1926        if let Some(actor_id) = extract_exec_algorithm_actor_id(config_obj)? {
1927            py_data_actor_ref.set_actor_id(actor_id);
1928        }
1929
1930        if let Some(val) = extract_bool_config_attr(config_obj, "log_events") {
1931            py_data_actor_ref.set_log_events(val);
1932        }
1933
1934        if let Some(val) = extract_bool_config_attr(config_obj, "log_commands") {
1935            py_data_actor_ref.set_log_commands(val);
1936        }
1937    }
1938
1939    py_data_actor_ref.set_python_instance(algorithm)?;
1940
1941    let actor_id = py_data_actor_ref.actor_id();
1942
1943    Ok((None, actor_id))
1944}
1945
1946fn extract_exec_algorithm_actor_id(config: &Bound<'_, PyAny>) -> anyhow::Result<Option<ActorId>> {
1947    let Some(value) = config
1948        .getattr("exec_algorithm_id")
1949        .ok()
1950        .filter(|value| !value.is_none())
1951        .or_else(|| {
1952            config
1953                .getattr("actor_id")
1954                .ok()
1955                .filter(|value| !value.is_none())
1956        })
1957    else {
1958        return Ok(None);
1959    };
1960
1961    if let Ok(id) = value.extract::<ExecAlgorithmId>() {
1962        return Ok(Some(ActorId::new(id.inner())));
1963    }
1964
1965    if let Ok(id) = value.extract::<ActorId>() {
1966        return Ok(Some(id));
1967    }
1968
1969    if let Ok(id) = value.extract::<String>() {
1970        return Ok(Some(ActorId::new_checked(&id)?));
1971    }
1972
1973    anyhow::bail!("Invalid `exec_algorithm_id`/`actor_id` type")
1974}
1975
1976/// Creates a Python config instance from a config path and config dictionary.
1977///
1978/// This constructor is shared by `add_actor_from_config` and `add_strategy_from_config`.
1979/// It handles:
1980/// 1. Importing the config class from the module path
1981/// 2. Converting the `HashMap<String, serde_json::Value>` to a Python dict
1982/// 3. Trying kwargs-first construction, falling back to default + setattr
1983/// 4. Calling `__post_init__` for dataclasses when using the setattr path
1984fn create_config_instance<'py>(
1985    py: Python<'py>,
1986    config_path: &str,
1987    config: &HashMap<String, serde_json::Value>,
1988) -> anyhow::Result<Option<Bound<'py, PyAny>>> {
1989    if config_path.is_empty() && config.is_empty() {
1990        log::debug!("No config_path or empty config, using None");
1991        return Ok(None);
1992    }
1993
1994    let config_parts: Vec<&str> = config_path.split(':').collect();
1995    if config_parts.len() != 2 {
1996        anyhow::bail!("config_path must be in format 'module.path:ClassName', was {config_path}");
1997    }
1998
1999    let (config_module_name, config_class_name) = (config_parts[0], config_parts[1]);
2000
2001    log::debug!(
2002        "Importing config class from module: {config_module_name} class: {config_class_name}"
2003    );
2004
2005    let config_module = py
2006        .import(config_module_name)
2007        .map_err(|e| anyhow::anyhow!("Failed to import config module {config_module_name}: {e}"))?;
2008    let config_class = config_module
2009        .getattr(config_class_name)
2010        .map_err(|e| anyhow::anyhow!("Failed to get config class {config_class_name}: {e}"))?;
2011
2012    // Convert config dict to Python dict
2013    let py_dict = PyDict::new(py);
2014
2015    for (key, value) in config {
2016        let py_value = config_value_to_py(py, key, value)?;
2017        py_dict.set_item(key, py_value)?;
2018    }
2019
2020    log::debug!("Created config dict: {py_dict:?}");
2021
2022    // Try kwargs first, then default constructor with setattr
2023    let config_instance = match config_class.call((), Some(&py_dict)) {
2024        Ok(instance) => {
2025            log::debug!("Created config instance with kwargs");
2026            instance
2027        }
2028        Err(kwargs_err) => {
2029            log::debug!("Failed to create config with kwargs: {kwargs_err}");
2030
2031            match config_class.call0() {
2032                Ok(instance) => {
2033                    log::debug!("Created default config instance, setting attributes");
2034
2035                    for (key, value) in config {
2036                        let py_value = config_value_to_py(py, key, value)?;
2037
2038                        if let Err(setattr_err) = instance.setattr(key, py_value) {
2039                            anyhow::bail!("Failed to set attribute {key}: {setattr_err}");
2040                        }
2041                    }
2042
2043                    // Only call __post_init__ if it exists (setattr path
2044                    // needs it, kwargs path already triggered it via __init__)
2045                    if instance.hasattr("__post_init__")? {
2046                        instance.call_method0("__post_init__")?;
2047                    }
2048
2049                    instance
2050                }
2051                Err(default_err) => {
2052                    anyhow::bail!(
2053                        "Failed to create config instance. \
2054                         Tried kwargs: {kwargs_err}, default: {default_err}"
2055                    );
2056                }
2057            }
2058        }
2059    };
2060
2061    log::debug!("Created config instance: {config_instance:?}");
2062
2063    Ok(Some(config_instance))
2064}
2065
2066fn config_value_to_py<'py>(
2067    py: Python<'py>,
2068    key: &str,
2069    value: &serde_json::Value,
2070) -> anyhow::Result<Bound<'py, PyAny>> {
2071    if key == "actor_id"
2072        && let Some(actor_id) = value.as_str()
2073    {
2074        return Ok(ActorId::new_checked(actor_id)?
2075            .into_pyobject(py)?
2076            .into_any());
2077    }
2078
2079    if key == "strategy_id"
2080        && let Some(strategy_id) = value.as_str()
2081    {
2082        return Ok(StrategyId::new_checked(strategy_id)?
2083            .into_pyobject(py)?
2084            .into_any());
2085    }
2086
2087    let json_str = serde_json::to_string(value)
2088        .map_err(|e| anyhow::anyhow!("Failed to serialize config value: {e}"))?;
2089    Ok(PyModule::import(py, "json")?
2090        .call_method("loads", (json_str,), None)?
2091        .into_any())
2092}
2093
2094/// Extracts an optional boolean attribute from a Python config object.
2095///
2096/// Returns `None` if the attribute doesn't exist or isn't a bool,
2097/// without raising an error (config fields are optional overrides).
2098fn extract_bool_config_attr(config_obj: &Bound<'_, PyAny>, attr: &str) -> Option<bool> {
2099    config_obj
2100        .getattr(attr)
2101        .ok()
2102        .and_then(|val| val.extract::<bool>().ok())
2103}
2104
2105fn extract_external_order_instrument_ids_config_attr(
2106    config_obj: &Bound<'_, PyAny>,
2107) -> anyhow::Result<Option<Vec<InstrumentId>>> {
2108    let Ok(claims) = config_obj.getattr("external_order_instrument_ids") else {
2109        return Ok(None);
2110    };
2111
2112    if claims.is_none() {
2113        return Ok(None);
2114    }
2115
2116    if let Ok(claims) = claims.extract::<Vec<InstrumentId>>() {
2117        return Ok(Some(claims));
2118    }
2119
2120    let claim_strings = claims
2121        .extract::<Vec<String>>()
2122        .map_err(|e| anyhow::anyhow!("Invalid `external_order_instrument_ids` type: {e}"))?;
2123
2124    let claims = claim_strings
2125        .into_iter()
2126        .map(|claim| {
2127            InstrumentId::from_str(&claim).map_err(|e| {
2128                anyhow::anyhow!(
2129                    "Invalid `external_order_instrument_ids` instrument ID {claim}: {e}"
2130                )
2131            })
2132        })
2133        .collect::<anyhow::Result<Vec<_>>>()?;
2134
2135    Ok(Some(claims))
2136}
2137
2138#[cfg(feature = "examples")]
2139type BuiltinActorRegister = for<'py> fn(&mut LiveNode, &Bound<'py, PyAny>) -> PyResult<()>;
2140
2141#[cfg(feature = "examples")]
2142type BuiltinStrategyRegister = for<'py> fn(&mut LiveNode, &Bound<'py, PyAny>) -> PyResult<()>;
2143
2144#[cfg(feature = "examples")]
2145fn builtin_actor_register(type_name: &str) -> Option<BuiltinActorRegister> {
2146    match type_name {
2147        "DataTester" => Some(register_data_tester),
2148        _ => None,
2149    }
2150}
2151
2152#[cfg(feature = "examples")]
2153fn builtin_strategy_register(type_name: &str) -> Option<BuiltinStrategyRegister> {
2154    match type_name {
2155        "CompositeMarketMaker" => Some(register_composite_market_maker),
2156        "DeltaNeutralVol" => Some(register_delta_neutral_vol),
2157        "EmaCross" => Some(register_ema_cross),
2158        "ExecTester" => Some(register_exec_tester),
2159        "GridMarketMaker" => Some(register_grid_market_maker),
2160        "HurstVpinDirectional" => Some(register_hurst_vpin_directional),
2161        "OrderBookImbalance" => Some(register_orderbook_imbalance),
2162        _ => None,
2163    }
2164}
2165
2166#[cfg(feature = "examples")]
2167fn register_composite_market_maker(node: &mut LiveNode, config: &Bound<'_, PyAny>) -> PyResult<()> {
2168    let config = config.extract::<CompositeMarketMakerConfig>()?;
2169    node.add_strategy(CompositeMarketMaker::new(config))
2170        .map_err(to_pyruntime_err)
2171}
2172
2173#[cfg(feature = "examples")]
2174fn register_delta_neutral_vol(node: &mut LiveNode, config: &Bound<'_, PyAny>) -> PyResult<()> {
2175    let config = config.extract::<DeltaNeutralVolConfig>()?;
2176    node.add_strategy(DeltaNeutralVol::new(config))
2177        .map_err(to_pyruntime_err)
2178}
2179
2180#[cfg(feature = "examples")]
2181fn register_ema_cross(node: &mut LiveNode, config: &Bound<'_, PyAny>) -> PyResult<()> {
2182    let config = config.extract::<EmaCrossConfig>()?;
2183    node.add_strategy(EmaCross::from_config(config))
2184        .map_err(to_pyruntime_err)
2185}
2186
2187#[cfg(feature = "examples")]
2188fn register_exec_tester(node: &mut LiveNode, config: &Bound<'_, PyAny>) -> PyResult<()> {
2189    let config = config.extract::<ExecTesterConfig>()?;
2190    node.add_strategy(ExecTester::new(config))
2191        .map_err(to_pyruntime_err)
2192}
2193
2194#[cfg(feature = "examples")]
2195fn register_grid_market_maker(node: &mut LiveNode, config: &Bound<'_, PyAny>) -> PyResult<()> {
2196    let config = config.extract::<GridMarketMakerConfig>()?;
2197    node.add_strategy(GridMarketMaker::new(config))
2198        .map_err(to_pyruntime_err)
2199}
2200
2201#[cfg(feature = "examples")]
2202fn register_hurst_vpin_directional(node: &mut LiveNode, config: &Bound<'_, PyAny>) -> PyResult<()> {
2203    let config = config.extract::<HurstVpinDirectionalConfig>()?;
2204    let strategy =
2205        HurstVpinDirectional::new_checked(config).map_err(config_error_to_pyvalue_err)?;
2206    node.add_strategy(strategy).map_err(to_pyruntime_err)
2207}
2208
2209#[cfg(feature = "examples")]
2210fn register_orderbook_imbalance(node: &mut LiveNode, config: &Bound<'_, PyAny>) -> PyResult<()> {
2211    let config = config.extract::<OrderBookImbalanceConfig>()?;
2212    node.add_strategy(OrderBookImbalance::from_config(config).map_err(to_pyvalue_err)?)
2213        .map_err(to_pyruntime_err)
2214}
2215
2216#[cfg(feature = "examples")]
2217fn register_data_tester(node: &mut LiveNode, config: &Bound<'_, PyAny>) -> PyResult<()> {
2218    let config = config.extract::<DataTesterConfig>()?;
2219    node.add_actor(DataTester::new(config))
2220        .map_err(to_pyruntime_err)
2221}
2222
2223/// Python wrapper for `LiveNodeBuilder` that uses interior mutability
2224/// to work around PyO3's shared ownership model.
2225#[pyclass(name = "LiveNodeBuilder", module = "nautilus_trader.live", unsendable)]
2226#[pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")]
2227pub struct PyLiveNodeBuilder {
2228    clients: PythonClients,
2229    state: Rc<Cell<PyLiveNodeBuilderState>>,
2230}
2231
2232#[pyo3_stub_gen::derive::gen_stub_pymethods]
2233#[pymethods]
2234impl PyLiveNodeBuilder {
2235    #[staticmethod]
2236    #[pyo3(name = "from_config", signature = (name, config=None, *, data_factories=None, exec_factories=None))]
2237    fn py_from_config(
2238        py: Python<'_>,
2239        name: String,
2240        config: Option<Py<LiveNodeConfig>>,
2241        data_factories: Option<Bound<'_, PyDict>>,
2242        exec_factories: Option<Bound<'_, PyDict>>,
2243    ) -> PyResult<Self> {
2244        let native_config = config
2245            .as_ref()
2246            .map(|config| config.bind(py).extract::<LiveNodeConfig>())
2247            .transpose()?
2248            .unwrap_or_default();
2249
2250        let builder = Self {
2251            clients: PythonClients::default(),
2252            state: Rc::new(Cell::new(PyLiveNodeBuilderState::Ready(Box::new(
2253                LiveNodeBuilder::from_config(native_config)
2254                    .map_err(to_pyruntime_err)?
2255                    .with_name(name),
2256            )))),
2257        };
2258
2259        if let Some(config) = config {
2260            let configured_clients = py
2261                .import("nautilus_trader.live.config")?
2262                .getattr("configured_clients")?;
2263            let data: Vec<(String, Py<PyAny>, Py<PyAny>)> = configured_clients
2264                .call1((config.getattr(py, "data_clients")?, data_factories))?
2265                .extract()?;
2266            let execution: Vec<(String, Py<PyAny>, Py<PyAny>)> = configured_clients
2267                .call1((config.getattr(py, "exec_clients")?, exec_factories))?
2268                .extract()?;
2269
2270            for (name, factory, config) in data {
2271                builder.py_add_data_client(Some(name), factory, config, None)?;
2272            }
2273
2274            for (name, factory, config) in execution {
2275                builder.py_add_exec_client(Some(name), factory, config, None)?;
2276            }
2277        }
2278
2279        Ok(builder)
2280    }
2281
2282    #[pyo3(name = "with_instance_id")]
2283    fn py_with_instance_id(&self, instance_id: UUID4) -> PyResult<Self> {
2284        self.update_builder(|builder| builder.with_instance_id(instance_id))
2285    }
2286
2287    #[pyo3(name = "with_load_state")]
2288    fn py_with_load_state(&self, load_state: bool) -> PyResult<Self> {
2289        self.update_builder(|builder| builder.with_load_state(load_state))
2290    }
2291
2292    #[pyo3(name = "with_save_state")]
2293    fn py_with_save_state(&self, save_state: bool) -> PyResult<Self> {
2294        self.update_builder(|builder| builder.with_save_state(save_state))
2295    }
2296
2297    #[pyo3(name = "with_timeout_connection")]
2298    fn py_with_timeout_connection(&self, timeout_secs: u64) -> PyResult<Self> {
2299        self.update_builder(|builder| builder.with_timeout_connection(timeout_secs))
2300    }
2301
2302    #[pyo3(name = "with_timeout_reconciliation")]
2303    fn py_with_timeout_reconciliation(&self, timeout_secs: u64) -> PyResult<Self> {
2304        self.update_builder(|builder| builder.with_timeout_reconciliation(timeout_secs))
2305    }
2306
2307    #[pyo3(name = "with_timeout_portfolio")]
2308    fn py_with_timeout_portfolio(&self, timeout_secs: u64) -> PyResult<Self> {
2309        self.update_builder(|builder| builder.with_timeout_portfolio(timeout_secs))
2310    }
2311
2312    #[pyo3(name = "with_timeout_disconnection_secs")]
2313    fn py_with_timeout_disconnection_secs(&self, timeout_secs: u64) -> PyResult<Self> {
2314        self.update_builder(|builder| builder.with_timeout_disconnection_secs(timeout_secs))
2315    }
2316
2317    #[pyo3(name = "with_delay_post_stop_secs")]
2318    fn py_with_delay_post_stop_secs(&self, delay_secs: u64) -> PyResult<Self> {
2319        self.update_builder(|builder| builder.with_delay_post_stop_secs(delay_secs))
2320    }
2321
2322    #[pyo3(name = "with_delay_shutdown_secs")]
2323    fn py_with_delay_shutdown_secs(&self, delay_secs: u64) -> PyResult<Self> {
2324        self.update_builder(|builder| builder.with_delay_shutdown_secs(delay_secs))
2325    }
2326
2327    #[pyo3(name = "with_reconciliation")]
2328    fn py_with_reconciliation(&self, reconciliation: bool) -> PyResult<Self> {
2329        self.update_builder(|builder| builder.with_reconciliation(reconciliation))
2330    }
2331
2332    #[pyo3(name = "with_controller")]
2333    fn py_with_controller(&self, controller: ImportableControllerConfig) -> PyResult<Self> {
2334        self.update_builder(|builder| builder.with_controller(controller))
2335    }
2336
2337    #[pyo3(name = "with_reconciliation_lookback_mins")]
2338    fn py_with_reconciliation_lookback_mins(&self, mins: u32) -> PyResult<Self> {
2339        self.update_builder(|builder| builder.with_reconciliation_lookback_mins(mins))
2340    }
2341
2342    #[pyo3(name = "with_cache_config")]
2343    fn py_with_cache_config(&self, config: CacheConfig) -> PyResult<Self> {
2344        self.update_builder(|builder| builder.with_cache_config(config))
2345    }
2346
2347    #[pyo3(name = "with_cache_database_factory")]
2348    fn py_with_cache_database_factory(&self, factory: Py<PyAny>) -> PyResult<Self> {
2349        let mut operation = self.begin_operation()?;
2350        let factory =
2351            Python::attach(|py| get_global_cache_database_factory_registry().extract(py, factory))?;
2352        let builder = operation.take_builder()?;
2353        operation.complete(builder.with_cache_database_factory(factory));
2354        Ok(self.shared())
2355    }
2356
2357    #[pyo3(name = "with_msgbus_config")]
2358    fn py_with_msgbus_config(&self, config: MessageBusConfig) -> PyResult<Self> {
2359        self.update_builder(|builder| builder.with_msgbus_config(config))
2360    }
2361
2362    #[pyo3(name = "with_external_msgbus_factory")]
2363    fn py_with_external_msgbus_factory(&self, factory: Py<PyAny>) -> PyResult<Self> {
2364        let mut operation = self.begin_operation()?;
2365        let factory =
2366            Python::attach(|py| get_global_msgbus_factory_registry().extract(py, factory))?;
2367        let builder = operation.take_builder()?;
2368        operation.complete(builder.with_external_msgbus_factory(factory));
2369        Ok(self.shared())
2370    }
2371
2372    #[pyo3(name = "with_portfolio_config")]
2373    fn py_with_portfolio_config(&self, config: PortfolioConfig) -> PyResult<Self> {
2374        self.update_builder(|builder| builder.with_portfolio_config(config))
2375    }
2376
2377    #[pyo3(name = "with_data_engine_config")]
2378    fn py_with_data_engine_config(&self, config: LiveDataEngineConfig) -> PyResult<Self> {
2379        self.update_builder(|builder| builder.with_data_engine_config(config))
2380    }
2381
2382    #[pyo3(name = "with_risk_engine_config")]
2383    fn py_with_risk_engine_config(&self, config: LiveRiskEngineConfig) -> PyResult<Self> {
2384        self.update_builder(|builder| builder.with_risk_engine_config(config))
2385    }
2386
2387    #[pyo3(name = "with_exec_engine_config")]
2388    fn py_with_exec_engine_config(&self, config: LiveExecutionEngineConfig) -> PyResult<Self> {
2389        self.update_builder(|builder| builder.with_exec_engine_config(config))
2390    }
2391
2392    #[pyo3(name = "with_logging")]
2393    fn py_with_logging(&self, logging: LoggerConfig) -> PyResult<Self> {
2394        self.update_builder(|builder| builder.with_logging(logging))
2395    }
2396
2397    #[pyo3(name = "add_data_client", signature = (name, factory, config, routing=None))]
2398    fn py_add_data_client(
2399        &self,
2400        name: Option<String>,
2401        factory: Py<PyAny>,
2402        config: Py<PyAny>,
2403        routing: Option<RoutingConfig>,
2404    ) -> PyResult<Self> {
2405        let mut operation = self.begin_operation()?;
2406        Python::attach(|py| -> PyResult<Self> {
2407            let (factory, config) = resolve_registered_client_pair(py, factory, config)?;
2408            let registry = get_global_pyo3_registry();
2409            let is_custom =
2410                python_client_factory_is_custom(py, factory.bind(py), "DataClientFactory")?;
2411
2412            if is_custom {
2413                config.extract::<crate::config::DataClientConfig>(py)?;
2414                let client_name =
2415                    name.ok_or_else(|| to_pyvalue_err("Python clients require an explicit name"))?;
2416
2417                let routing = match routing {
2418                    Some(routing) => routing,
2419                    None => config
2420                        .getattr(py, "routing")?
2421                        .extract::<RoutingConfig>(py)?,
2422                };
2423
2424                if operation
2425                    .builder
2426                    .as_ref()
2427                    .is_some_and(|builder| builder.has_data_client(&client_name))
2428                {
2429                    return Err(to_pyvalue_err(format!(
2430                        "Data client '{client_name}' is already registered"
2431                    )));
2432                }
2433
2434                let builder = operation.take_builder()?;
2435
2436                let updated = builder
2437                    .add_data_client_with_routing(
2438                        Some(client_name),
2439                        Box::new(PythonDataFactory {
2440                            factory,
2441                            clients: self.clients.clone(),
2442                        }),
2443                        Box::new(PythonClientConfig(config)),
2444                        routing,
2445                    )
2446                    .map_err(to_pyruntime_err)?;
2447
2448                operation.complete(updated);
2449                return Ok(self.shared());
2450            }
2451
2452            let boxed_factory = registry.extract_factory(py, factory.clone_ref(py))?;
2453            let boxed_config = registry.extract_config(py, config.clone_ref(py))?;
2454            let factory_name = factory
2455                .getattr(py, "name")?
2456                .call0(py)?
2457                .extract::<String>(py)?;
2458            let client_name = name.unwrap_or(factory_name);
2459
2460            if operation
2461                .builder
2462                .as_ref()
2463                .is_some_and(|builder| builder.has_data_client(&client_name))
2464            {
2465                return Err(to_pyvalue_err(format!(
2466                    "Client '{client_name}' is already registered"
2467                )));
2468            }
2469
2470            let builder = operation.take_builder()?;
2471
2472            let updated_builder = match routing {
2473                Some(routing) => builder.add_data_client_with_routing(
2474                    Some(client_name),
2475                    boxed_factory,
2476                    boxed_config,
2477                    routing,
2478                ),
2479                None => builder.add_data_client(Some(client_name), boxed_factory, boxed_config),
2480            }
2481            .map_err(|e| to_pyruntime_err(format!("Failed to add data client: {e}")))?;
2482
2483            operation.complete(updated_builder);
2484            Ok(self.shared())
2485        })
2486    }
2487
2488    #[pyo3(name = "add_exec_client", signature = (name, factory, config, routing=None))]
2489    fn py_add_exec_client(
2490        &self,
2491        name: Option<String>,
2492        factory: Py<PyAny>,
2493        config: Py<PyAny>,
2494        routing: Option<RoutingConfig>,
2495    ) -> PyResult<Self> {
2496        let mut operation = self.begin_operation()?;
2497        Python::attach(|py| -> PyResult<Self> {
2498            let (factory, config) = resolve_registered_client_pair(py, factory, config)?;
2499            let registry = get_global_pyo3_registry();
2500            let is_custom =
2501                python_client_factory_is_custom(py, factory.bind(py), "ExecutionClientFactory")?;
2502
2503            if is_custom {
2504                config.extract::<crate::config::ExecutionClientConfig>(py)?;
2505                let client_name =
2506                    name.ok_or_else(|| to_pyvalue_err("Python clients require an explicit name"))?;
2507
2508                let routing = match routing {
2509                    Some(routing) => routing,
2510                    None => config
2511                        .getattr(py, "routing")?
2512                        .extract::<RoutingConfig>(py)?,
2513                };
2514
2515                if operation
2516                    .builder
2517                    .as_ref()
2518                    .is_some_and(|builder| builder.has_exec_client(&client_name))
2519                {
2520                    return Err(to_pyvalue_err(format!(
2521                        "Execution client '{client_name}' is already registered"
2522                    )));
2523                }
2524
2525                let builder = operation.take_builder()?;
2526
2527                let updated = builder
2528                    .add_exec_client_with_routing(
2529                        Some(client_name),
2530                        Box::new(PythonExecutionFactory {
2531                            factory,
2532                            clients: self.clients.clone(),
2533                        }),
2534                        Box::new(PythonClientConfig(config)),
2535                        routing,
2536                    )
2537                    .map_err(to_pyruntime_err)?;
2538
2539                operation.complete(updated);
2540                return Ok(self.shared());
2541            }
2542
2543            let boxed_factory = registry.extract_exec_factory(py, factory.clone_ref(py))?;
2544            let boxed_config = registry.extract_config(py, config.clone_ref(py))?;
2545            let factory_name = factory
2546                .getattr(py, "name")?
2547                .call0(py)?
2548                .extract::<String>(py)?;
2549            let client_name = name.unwrap_or(factory_name);
2550
2551            if operation
2552                .builder
2553                .as_ref()
2554                .is_some_and(|builder| builder.has_exec_client(&client_name))
2555            {
2556                return Err(to_pyvalue_err(format!(
2557                    "Client '{client_name}' is already registered"
2558                )));
2559            }
2560
2561            let builder = operation.take_builder()?;
2562
2563            let updated_builder = match routing {
2564                Some(routing) => builder.add_exec_client_with_routing(
2565                    Some(client_name),
2566                    boxed_factory,
2567                    boxed_config,
2568                    routing,
2569                ),
2570                None => builder.add_exec_client(Some(client_name), boxed_factory, boxed_config),
2571            }
2572            .map_err(|e| to_pyruntime_err(format!("Failed to add exec client: {e}")))?;
2573
2574            operation.complete(updated_builder);
2575            Ok(self.shared())
2576        })
2577    }
2578
2579    #[pyo3(name = "add_simulated_exec_client")]
2580    #[expect(clippy::needless_pass_by_value)]
2581    fn py_add_simulated_exec_client(
2582        &self,
2583        name: Option<String>,
2584        factory: Py<PyAny>,
2585        config: Py<PyAny>,
2586    ) -> PyResult<Self> {
2587        let mut operation = self.begin_operation()?;
2588        Python::attach(|py| -> PyResult<Self> {
2589            let registry = get_global_pyo3_registry();
2590            let boxed_factory = registry.extract_sim_exec_factory(py, factory.clone_ref(py))?;
2591            let boxed_config = registry.extract_config(py, config.clone_ref(py))?;
2592            let factory_name = factory
2593                .getattr(py, "name")?
2594                .call0(py)?
2595                .extract::<String>(py)?;
2596            let client_name = name.unwrap_or(factory_name);
2597            let builder = operation.take_builder()?;
2598
2599            let updated_builder = builder
2600                .add_simulated_exec_client(Some(client_name), boxed_factory, boxed_config)
2601                .map_err(|e| {
2602                    to_pyruntime_err(format!("Failed to add simulated exec client: {e}"))
2603                })?;
2604
2605            operation.complete(updated_builder);
2606            Ok(self.shared())
2607        })
2608    }
2609
2610    #[pyo3(name = "build")]
2611    fn py_build(&self) -> PyResult<PyLiveNode> {
2612        let mut operation = self.begin_operation()?;
2613        let mut builder = operation.take_builder()?;
2614
2615        let node = match builder.build_in_place() {
2616            Ok(node) => node,
2617            Err(e) => {
2618                Python::attach(|py| {
2619                    if let Err(cleanup_error) = self.clients.finish(py) {
2620                        log::error!(
2621                            "Failed to clean up Python clients after build failure: {cleanup_error}"
2622                        );
2623                    }
2624                });
2625
2626                operation.complete(builder);
2627                return Err(to_pyruntime_err(e));
2628            }
2629        };
2630
2631        let mut node = PyLiveNode::new(node);
2632        node.clients = self.clients.take();
2633        Ok(node)
2634    }
2635
2636    fn __repr__(&self) -> String {
2637        format!("{self:?}")
2638    }
2639}
2640
2641const BUILDER_OPERATION_IN_PROGRESS: &str = "Builder operation already in progress";
2642const BUILDER_OPERATION_VALUE_TAKEN: &str = "Builder operation value already taken";
2643
2644enum PyLiveNodeBuilderState {
2645    Ready(Box<LiveNodeBuilder>),
2646    InProgress,
2647    Consumed,
2648}
2649
2650struct PyLiveNodeBuilderOperation<'a> {
2651    state: &'a Cell<PyLiveNodeBuilderState>,
2652    builder: Option<LiveNodeBuilder>,
2653}
2654
2655impl PyLiveNodeBuilder {
2656    fn begin_operation(&self) -> PyResult<PyLiveNodeBuilderOperation<'_>> {
2657        match self.state.replace(PyLiveNodeBuilderState::InProgress) {
2658            PyLiveNodeBuilderState::Ready(builder) => Ok(PyLiveNodeBuilderOperation {
2659                state: &self.state,
2660                builder: Some(*builder),
2661            }),
2662            PyLiveNodeBuilderState::InProgress => {
2663                self.state.set(PyLiveNodeBuilderState::InProgress);
2664                Err(to_pyruntime_err(BUILDER_OPERATION_IN_PROGRESS))
2665            }
2666            PyLiveNodeBuilderState::Consumed => {
2667                self.state.set(PyLiveNodeBuilderState::Consumed);
2668                Err(to_pyruntime_err("Builder already consumed"))
2669            }
2670        }
2671    }
2672
2673    fn update_builder<F>(&self, update: F) -> PyResult<Self>
2674    where
2675        F: FnOnce(LiveNodeBuilder) -> LiveNodeBuilder,
2676    {
2677        let mut operation = self.begin_operation()?;
2678        let builder = operation.take_builder()?;
2679        operation.complete(update(builder));
2680        Ok(self.shared())
2681    }
2682
2683    fn shared(&self) -> Self {
2684        Self {
2685            state: self.state.clone(),
2686            clients: self.clients.clone(),
2687        }
2688    }
2689}
2690
2691impl Debug for PyLiveNodeBuilder {
2692    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2693        // Preserve the existing Python repr despite the internal state change
2694        let state = self.state.replace(PyLiveNodeBuilderState::InProgress);
2695
2696        let result = match &state {
2697            PyLiveNodeBuilderState::Ready(builder) => write!(
2698                f,
2699                "PyLiveNodeBuilder {{ inner: RefCell {{ value: Some({builder:?}) }} }}"
2700            ),
2701            PyLiveNodeBuilderState::InProgress => {
2702                f.write_str("PyLiveNodeBuilder { inner: <operation active> }")
2703            }
2704            PyLiveNodeBuilderState::Consumed => {
2705                f.write_str("PyLiveNodeBuilder { inner: RefCell { value: None } }")
2706            }
2707        };
2708
2709        self.state.set(state);
2710        result
2711    }
2712}
2713
2714impl PyLiveNodeBuilderOperation<'_> {
2715    fn take_builder(&mut self) -> PyResult<LiveNodeBuilder> {
2716        self.builder
2717            .take()
2718            .ok_or_else(|| to_pyruntime_err(BUILDER_OPERATION_VALUE_TAKEN))
2719    }
2720
2721    fn complete(&mut self, builder: LiveNodeBuilder) {
2722        self.builder = Some(builder);
2723    }
2724}
2725
2726impl Drop for PyLiveNodeBuilderOperation<'_> {
2727    fn drop(&mut self) {
2728        self.state.set(match self.builder.take() {
2729            Some(builder) => PyLiveNodeBuilderState::Ready(Box::new(builder)),
2730            None => PyLiveNodeBuilderState::Consumed,
2731        });
2732    }
2733}
2734
2735fn resolve_registered_client_pair(
2736    py: Python<'_>,
2737    factory: Py<PyAny>,
2738    config: Py<PyAny>,
2739) -> PyResult<(Py<PyAny>, Py<PyAny>)> {
2740    match py.import("nautilus_trader.live.config") {
2741        Ok(module) => module
2742            .getattr("resolve_client_registration")?
2743            .call1((factory, config))?
2744            .extract(),
2745        Err(e) if e.is_instance_of::<pyo3::exceptions::PyModuleNotFoundError>(py) => {
2746            Ok((factory, config))
2747        }
2748        Err(e) => Err(e),
2749    }
2750}
2751
2752fn python_client_factory_is_custom(
2753    py: Python<'_>,
2754    factory: &Bound<'_, PyAny>,
2755    base_name: &str,
2756) -> PyResult<bool> {
2757    let base = match py.import("nautilus_trader.live.clients") {
2758        Ok(module) => module.getattr(base_name)?,
2759        Err(e) if e.is_instance_of::<pyo3::exceptions::PyModuleNotFoundError>(py) => {
2760            return Ok(false);
2761        }
2762        Err(e) => return Err(e),
2763    };
2764
2765    if let Ok(factory_type) = factory.cast::<pyo3::types::PyType>() {
2766        factory_type.is_subclass(&base)
2767    } else {
2768        factory.is_instance(&base)
2769    }
2770}
2771
2772#[cfg(all(test, feature = "python"))]
2773#[allow(
2774    clippy::await_holding_refcell_ref,
2775    reason = "each test owns its node exclusively, so the wrapper borrow cannot contend"
2776)]
2777mod tests {
2778    use std::{
2779        any::Any,
2780        cell::RefCell,
2781        collections::HashMap,
2782        ffi::{CStr, CString},
2783        fmt::Debug,
2784        rc::Rc,
2785        sync::{
2786            Arc,
2787            atomic::{AtomicBool, AtomicUsize, Ordering},
2788            mpsc,
2789        },
2790        thread,
2791        time::{Duration, Instant},
2792    };
2793
2794    use async_trait::async_trait;
2795    use indexmap::IndexMap;
2796    use nautilus_common::{
2797        actor::DataActor,
2798        cache::{
2799            CacheConfig, CacheView,
2800            database::{CacheDatabaseAdapter, CacheDatabaseFactory},
2801        },
2802        clients::DataClient,
2803        clock::Clock,
2804        enums::Environment,
2805        factories::{ClientConfig, DataClientFactory},
2806        live::{runner::get_data_event_sender, runtime::get_runtime},
2807        messages::{
2808            DataEvent, DataResponse,
2809            data::{BarsResponse, RequestBars},
2810            execution::{CancelAllOrders, SubmitOrder, TradingCommand},
2811        },
2812        msgbus::{
2813            BusMessage, MessageBusBacking, MessageBusBackingFactory, MessageBusConfig,
2814            MessagingSwitchboard, get_message_bus,
2815        },
2816        python::{
2817            actor::PyDataActor, cache::get_global_cache_database_factory_registry,
2818            msgbus::get_global_msgbus_factory_registry, wrappers::get_python_wrapper,
2819        },
2820        runner::{TradingCommandMessage, get_trading_cmd_sender},
2821        testing::wait_until_async,
2822    };
2823    use nautilus_core::{UUID4, UnixNanos};
2824    use nautilus_execution::engine::stubs::StubExecutionClient;
2825    use nautilus_model::{
2826        data::{Bar, BarType},
2827        enums::{OmsType, OrderStatus, OrderType},
2828        identifiers::{
2829            AccountId, ActorId, ClientId, ExecAlgorithmId, InstrumentId, PositionId, StrategyId,
2830            TraderId, Venue,
2831        },
2832        instruments::{Instrument, InstrumentAny, stubs::crypto_perpetual_ethusdt},
2833        orders::{Order, OrderTestBuilder},
2834        types::{Price, Quantity},
2835    };
2836    use nautilus_testkit::cache::{TestCacheDatabase, TestCacheDatabaseControl};
2837    use nautilus_trading::{
2838        ImportableExecutionAlgorithmConfig, ImportableStrategyConfig, nautilus_strategy,
2839        python::{algorithm::PyExecutionAlgorithm, strategy::PyStrategy},
2840        strategy::{StrategyConfig, StrategyCore},
2841    };
2842    use parking_lot::Mutex;
2843    use pyo3::{
2844        IntoPyObject, Py, PyRef, Python,
2845        ffi::c_str,
2846        types::{PyAnyMethods, PyDict, PyModule, PyModuleMethods},
2847    };
2848    use rstest::rstest;
2849
2850    use super::{
2851        BUILDER_OPERATION_IN_PROGRESS, LiveNode, PyLiveNode, PyLiveNodeBuilder,
2852        PyLiveNodeBuilderState, extract_exec_algorithm_actor_id, finish_owned_run,
2853        get_global_pyo3_registry,
2854    };
2855    use crate::node::{NodeState, config::RoutingConfig};
2856
2857    #[rstest]
2858    fn test_owned_run_cleanup_preserves_all_errors(
2859        #[values(false, true)] run_error: bool,
2860        #[values(false, true)] close_error: bool,
2861        #[values(false, true)] restore_error: bool,
2862    ) {
2863        Python::initialize();
2864        Python::attach(|py| {
2865            let module = PyModule::from_code(
2866                py,
2867                c_str!(
2868                    r#"
2869calls = []
2870
2871class Loop:
2872    def close(self):
2873        calls.append("close")
2874        if close_error:
2875            raise RuntimeError("close failed")
2876
2877def signal(signum, original):
2878    calls.append(f"signal:{signum}")
2879    if restore_error and signum == 1:
2880        raise OSError("restore failed")
2881
2882loop = Loop()
2883primary = KeyboardInterrupt("run failed")
2884"#
2885                ),
2886                c_str!("owned_cleanup_test.py"),
2887                c_str!("owned_cleanup_test"),
2888            )
2889            .unwrap();
2890            module.setattr("close_error", close_error).unwrap();
2891            module.setattr("restore_error", restore_error).unwrap();
2892            let primary = module.getattr("primary").unwrap();
2893
2894            let result = if run_error {
2895                Err(pyo3::PyErr::from_value(primary.clone()))
2896            } else {
2897                Ok(())
2898            };
2899
2900            let handlers = [1_i32, 2]
2901                .into_iter()
2902                .map(|signum| {
2903                    (
2904                        signum.into_pyobject(py).unwrap().into_any(),
2905                        py.None().into_bound(py),
2906                    )
2907                })
2908                .collect();
2909
2910            let result =
2911                finish_owned_run(&module.getattr("loop").unwrap(), &module, handlers, result);
2912            let expected: Vec<&str> = [
2913                (run_error, "run failed"),
2914                (close_error, "close failed"),
2915                (restore_error, "restore failed"),
2916            ]
2917            .into_iter()
2918            .filter_map(|(failed, message)| failed.then_some(message))
2919            .collect();
2920
2921            let actual = match result {
2922                Ok(()) => Vec::new(),
2923                Err(e) => {
2924                    let error = e.value(py);
2925
2926                    let errors = if error.is_instance_of::<pyo3::exceptions::PyBaseExceptionGroup>()
2927                    {
2928                        error
2929                            .getattr("exceptions")
2930                            .unwrap()
2931                            .extract::<Vec<pyo3::Bound<'_, pyo3::PyAny>>>()
2932                            .unwrap()
2933                    } else {
2934                        vec![error.clone().into_any()]
2935                    };
2936
2937                    if run_error {
2938                        assert!(errors[0].is(&primary));
2939                    }
2940
2941                    errors
2942                        .into_iter()
2943                        .map(|e| e.str().unwrap().to_string())
2944                        .collect()
2945                }
2946            };
2947
2948            assert_eq!(actual, expected);
2949            assert_eq!(
2950                module
2951                    .getattr("calls")
2952                    .unwrap()
2953                    .extract::<Vec<String>>()
2954                    .unwrap(),
2955                ["close", "signal:1", "signal:2"],
2956            );
2957        });
2958    }
2959
2960    #[derive(Clone, Copy, Debug)]
2961    enum ShutdownRunPath {
2962        Native,
2963        PyO3,
2964    }
2965
2966    static TEST_MSGBUS_FACTORY_CALLS: AtomicUsize = AtomicUsize::new(0);
2967
2968    #[derive(Debug, Clone)]
2969    #[pyo3::pyclass(name = "TestMessageBusFactory", from_py_object)]
2970    struct TestMessageBusFactory;
2971
2972    impl MessageBusBackingFactory for TestMessageBusFactory {
2973        fn create(
2974            &self,
2975            trader_id: TraderId,
2976            _instance_id: UUID4,
2977            config: MessageBusConfig,
2978        ) -> anyhow::Result<Box<dyn MessageBusBacking>> {
2979            TEST_MSGBUS_FACTORY_CALLS.fetch_add(1, Ordering::SeqCst);
2980
2981            anyhow::ensure!(
2982                trader_id == TraderId::from("TESTER-001"),
2983                "unexpected trader ID: {trader_id}"
2984            );
2985            anyhow::ensure!(
2986                config.external_streams == Some(vec!["external-stream".to_string()]),
2987                "unexpected external streams: {:?}",
2988                config.external_streams
2989            );
2990
2991            let (_tx, rx) = tokio::sync::mpsc::channel(1);
2992            Ok(Box::new(TestMessageBusBacking {
2993                rx: Some(rx),
2994                closed: false,
2995            }))
2996        }
2997    }
2998
2999    #[derive(Debug)]
3000    struct TestMessageBusBacking {
3001        rx: Option<tokio::sync::mpsc::Receiver<BusMessage>>,
3002        closed: bool,
3003    }
3004
3005    impl MessageBusBacking for TestMessageBusBacking {
3006        fn is_closed(&self) -> bool {
3007            self.closed
3008        }
3009
3010        fn publish(&self, _message: BusMessage) {}
3011
3012        fn take_receiver(&mut self) -> anyhow::Result<tokio::sync::mpsc::Receiver<BusMessage>> {
3013            self.rx
3014                .take()
3015                .ok_or_else(|| anyhow::anyhow!("Stream receiver already taken"))
3016        }
3017
3018        fn close(&mut self) {
3019            self.closed = true;
3020        }
3021    }
3022
3023    #[expect(clippy::needless_pass_by_value)]
3024    fn extract_test_msgbus_factory(
3025        py: Python<'_>,
3026        factory: Py<pyo3::PyAny>,
3027    ) -> pyo3::PyResult<Box<dyn MessageBusBackingFactory>> {
3028        Ok(Box::new(factory.extract::<TestMessageBusFactory>(py)?))
3029    }
3030
3031    #[rstest]
3032    #[case("instance")]
3033    #[case("class")]
3034    #[case("builder")]
3035    fn test_python_build_rejects_existing_node(#[case] constructor: &str) {
3036        Python::initialize();
3037        Python::attach(|py| {
3038            let builder = PyLiveNode::py_builder(
3039                "Original".to_string(),
3040                TraderId::from("PROBE-001"),
3041                Environment::Sandbox,
3042            )
3043            .unwrap();
3044            let node = Py::new(py, builder.py_build().unwrap()).unwrap();
3045            let bus = get_message_bus();
3046            let second_builder = PyLiveNode::py_builder(
3047                "Extra".to_string(),
3048                TraderId::from("OTHER-002"),
3049                Environment::Sandbox,
3050            )
3051            .unwrap();
3052            let second_builder = Py::new(py, second_builder).unwrap();
3053
3054            let result = match constructor {
3055                "instance" => node.bind(py).call_method1("build", ("Extra",)),
3056                "class" => py
3057                    .get_type::<PyLiveNode>()
3058                    .call_method1("build", ("Extra",)),
3059                "builder" => second_builder.bind(py).call_method0("build"),
3060                _ => unreachable!(),
3061            };
3062
3063            let error = result.unwrap_err();
3064            assert!(error.is_instance_of::<pyo3::exceptions::PyRuntimeError>(py));
3065            assert!(error.to_string().contains("A LiveNode already exists"));
3066            assert!(Rc::ptr_eq(&bus, &get_message_bus()));
3067            assert_eq!(
3068                node.borrow(py).node().unwrap().trader_id(),
3069                TraderId::from("PROBE-001")
3070            );
3071
3072            drop(node);
3073            let replacement = second_builder.bind(py).call_method0("build").unwrap();
3074            assert_eq!(
3075                replacement
3076                    .extract::<pyo3::PyRef<'_, PyLiveNode>>()
3077                    .unwrap()
3078                    .node()
3079                    .unwrap()
3080                    .trader_id(),
3081                TraderId::from("OTHER-002")
3082            );
3083        });
3084    }
3085
3086    #[rstest]
3087    fn test_python_builder_installs_external_msgbus_factory() {
3088        TEST_MSGBUS_FACTORY_CALLS.store(0, Ordering::SeqCst);
3089        get_global_msgbus_factory_registry()
3090            .register(
3091                "TestMessageBusFactory".to_string(),
3092                extract_test_msgbus_factory,
3093            )
3094            .unwrap();
3095        Python::initialize();
3096
3097        Python::attach(|py| {
3098            let factory = Py::new(py, TestMessageBusFactory).unwrap().into_any();
3099
3100            let builder = PyLiveNode::py_builder(
3101                "TEST".to_string(),
3102                TraderId::from("TESTER-001"),
3103                Environment::Sandbox,
3104            )
3105            .unwrap()
3106            .py_with_msgbus_config(MessageBusConfig {
3107                external_streams: Some(vec!["external-stream".to_string()]),
3108                ..Default::default()
3109            })
3110            .unwrap()
3111            .py_with_external_msgbus_factory(factory)
3112            .unwrap();
3113
3114            let node = builder.py_build().unwrap();
3115            let consumed_error = builder
3116                .py_with_msgbus_config(MessageBusConfig::default())
3117                .unwrap_err();
3118
3119            assert!(!node.node_mut().unwrap().is_running());
3120            assert_eq!(TEST_MSGBUS_FACTORY_CALLS.load(Ordering::SeqCst), 1);
3121            assert_eq!(
3122                consumed_error.to_string(),
3123                "RuntimeError: Builder already consumed"
3124            );
3125            assert_eq!(
3126                builder.__repr__(),
3127                "PyLiveNodeBuilder { inner: RefCell { value: None } }"
3128            );
3129            get_message_bus().borrow_mut().dispose();
3130        });
3131    }
3132
3133    static TEST_CACHE_DATABASE_FACTORY_CALLS: AtomicUsize = AtomicUsize::new(0);
3134
3135    #[derive(Debug, Clone)]
3136    #[pyo3::pyclass(name = "TestCacheDatabaseFactory", from_py_object)]
3137    struct TestCacheDatabaseFactory {
3138        database: Arc<parking_lot::Mutex<Option<TestCacheDatabase>>>,
3139        instance_id: Arc<parking_lot::Mutex<Option<UUID4>>>,
3140    }
3141
3142    impl TestCacheDatabaseFactory {
3143        fn new(database: Option<TestCacheDatabase>) -> Self {
3144            Self {
3145                database: Arc::new(parking_lot::Mutex::new(database)),
3146                instance_id: Arc::new(parking_lot::Mutex::new(None)),
3147            }
3148        }
3149
3150        fn received_instance_id(&self) -> Option<UUID4> {
3151            *self.instance_id.lock()
3152        }
3153    }
3154
3155    #[async_trait]
3156    impl CacheDatabaseFactory for TestCacheDatabaseFactory {
3157        async fn create(
3158            &self,
3159            trader_id: TraderId,
3160            instance_id: UUID4,
3161            config: CacheConfig,
3162        ) -> anyhow::Result<Box<dyn CacheDatabaseAdapter>> {
3163            TEST_CACHE_DATABASE_FACTORY_CALLS.fetch_add(1, Ordering::SeqCst);
3164            *self.instance_id.lock() = Some(instance_id);
3165
3166            anyhow::ensure!(
3167                trader_id == TraderId::from("TESTER-001"),
3168                "unexpected trader ID: {trader_id}"
3169            );
3170            anyhow::ensure!(
3171                config.buffer_interval_ms == Some(25),
3172                "unexpected buffer interval: {:?}",
3173                config.buffer_interval_ms
3174            );
3175
3176            let database = self
3177                .database
3178                .lock()
3179                .take()
3180                .ok_or_else(|| anyhow::anyhow!("Test cache database unavailable"))?;
3181            Ok(Box::new(database))
3182        }
3183    }
3184
3185    #[expect(clippy::needless_pass_by_value)]
3186    fn extract_test_cache_database_factory(
3187        py: Python<'_>,
3188        factory: Py<pyo3::PyAny>,
3189    ) -> pyo3::PyResult<Box<dyn CacheDatabaseFactory>> {
3190        Ok(Box::new(factory.extract::<TestCacheDatabaseFactory>(py)?))
3191    }
3192
3193    fn state_factory_builder(factory: &TestCacheDatabaseFactory) -> PyLiveNodeBuilder {
3194        Python::attach(|py| {
3195            PyLiveNode::py_builder(
3196                "TEST".to_string(),
3197                TraderId::from("TESTER-001"),
3198                Environment::Sandbox,
3199            )
3200            .unwrap()
3201            .py_with_cache_config(CacheConfig {
3202                buffer_interval_ms: Some(25),
3203                ..Default::default()
3204            })
3205            .unwrap()
3206            .py_with_cache_database_factory(Py::new(py, factory.clone()).unwrap().into_any())
3207            .unwrap()
3208            .py_with_reconciliation(false)
3209            .unwrap()
3210            .py_with_timeout_connection(0)
3211            .unwrap()
3212            .py_with_timeout_reconciliation(0)
3213            .unwrap()
3214            .py_with_timeout_portfolio(0)
3215            .unwrap()
3216            .py_with_timeout_disconnection_secs(0)
3217            .unwrap()
3218            .py_with_delay_post_stop_secs(0)
3219            .unwrap()
3220            .py_with_delay_shutdown_secs(0)
3221            .unwrap()
3222        })
3223    }
3224
3225    #[tokio::test]
3226    async fn test_python_builder_installs_cache_database_factory_on_start() {
3227        TEST_CACHE_DATABASE_FACTORY_CALLS.store(0, Ordering::SeqCst);
3228        get_global_cache_database_factory_registry()
3229            .register(
3230                "TestCacheDatabaseFactory".to_string(),
3231                extract_test_cache_database_factory,
3232            )
3233            .unwrap();
3234        Python::initialize();
3235
3236        let (database, control) = TestCacheDatabaseControl::create();
3237        let actor_id = ActorId::from("PY-CACHE-FACTORY-ACTOR");
3238        let actor_state = IndexMap::from([("loaded".to_string(), b"value".to_vec())]);
3239        control.set_actor_state(actor_id, &actor_state);
3240        let factory = TestCacheDatabaseFactory::new(Some(database));
3241
3242        let node = state_factory_builder(&factory).py_build().unwrap();
3243
3244        assert_eq!(TEST_CACHE_DATABASE_FACTORY_CALLS.load(Ordering::SeqCst), 0);
3245        assert!(
3246            !node
3247                .node_mut()
3248                .unwrap()
3249                .kernel()
3250                .cache()
3251                .borrow()
3252                .has_backing()
3253        );
3254
3255        node.node_mut().unwrap().start().await.unwrap();
3256
3257        assert_eq!(TEST_CACHE_DATABASE_FACTORY_CALLS.load(Ordering::SeqCst), 1);
3258        assert_eq!(
3259            factory.received_instance_id(),
3260            Some(node.node_mut().unwrap().instance_id())
3261        );
3262        assert!(
3263            node.node_mut()
3264                .unwrap()
3265                .kernel()
3266                .cache()
3267                .borrow()
3268                .has_backing()
3269        );
3270        assert_eq!(
3271            node.node_mut()
3272                .unwrap()
3273                .kernel()
3274                .cache()
3275                .borrow()
3276                .load_actor_state(&actor_id)
3277                .unwrap(),
3278            Some(actor_state)
3279        );
3280
3281        node.node_mut().unwrap().stop().await.unwrap();
3282        node.node_mut().unwrap().dispose();
3283        get_message_bus().borrow_mut().dispose();
3284    }
3285
3286    #[tokio::test]
3287    async fn test_python_builder_propagates_cache_database_factory_error_on_start() {
3288        get_global_cache_database_factory_registry()
3289            .register(
3290                "TestCacheDatabaseFactory".to_string(),
3291                extract_test_cache_database_factory,
3292            )
3293            .unwrap();
3294        Python::initialize();
3295
3296        let factory = TestCacheDatabaseFactory::new(None);
3297        let node = state_factory_builder(&factory).py_build().unwrap();
3298
3299        let error = node.node_mut().unwrap().start().await.unwrap_err();
3300
3301        assert_eq!(
3302            format!("{error:#}"),
3303            "failed to create cache database backing: Test cache database unavailable"
3304        );
3305        assert!(
3306            !node
3307                .node_mut()
3308                .unwrap()
3309                .kernel()
3310                .cache()
3311                .borrow()
3312                .has_backing()
3313        );
3314
3315        let retry_error = node.node_mut().unwrap().start().await.unwrap_err();
3316
3317        assert_eq!(
3318            format!("{retry_error:#}"),
3319            "failed to create cache database backing: Test cache database unavailable"
3320        );
3321        assert!(
3322            !node
3323                .node_mut()
3324                .unwrap()
3325                .kernel()
3326                .cache()
3327                .borrow()
3328                .has_backing()
3329        );
3330
3331        node.node_mut().unwrap().dispose();
3332        get_message_bus().borrow_mut().dispose();
3333    }
3334
3335    #[rstest]
3336    fn test_python_builder_rejects_unregistered_cache_database_factory() {
3337        Python::initialize();
3338
3339        Python::attach(|py| {
3340            let factory = PyDict::new(py).unbind().into_any();
3341            let builder = PyLiveNode::py_builder(
3342                "TEST".to_string(),
3343                TraderId::from("TESTER-001"),
3344                Environment::Sandbox,
3345            )
3346            .unwrap();
3347
3348            let error = builder.py_with_cache_database_factory(factory).unwrap_err();
3349
3350            assert_eq!(
3351                error.to_string(),
3352                "NotImplementedError: No cache database factory extractor registered for 'dict'"
3353            );
3354            builder
3355                .py_with_cache_config(CacheConfig::default())
3356                .unwrap();
3357        });
3358    }
3359
3360    #[rstest]
3361    fn test_python_builder_restores_state_after_factory_type_reentry() {
3362        Python::initialize();
3363
3364        Python::attach(|py| {
3365            let builder = Py::new(
3366                py,
3367                PyLiveNode::py_builder(
3368                    "TEST".to_string(),
3369                    TraderId::from("TESTER-001"),
3370                    Environment::Sandbox,
3371                )
3372                .unwrap(),
3373            )
3374            .unwrap();
3375            let locals = PyDict::new(py);
3376            locals.set_item("builder", &builder).unwrap();
3377            py.run(
3378                pyo3::ffi::c_str!(
3379                    "class ReentrantFactory:\n    def __getattribute__(self, name):\n        if name == '__class__':\n            builder.with_load_state(True)\n        return object.__getattribute__(self, name)\n\nfactory = ReentrantFactory()"
3380                ),
3381                Some(&locals),
3382                None,
3383            )
3384            .unwrap();
3385            let factory = locals.get_item("factory").unwrap();
3386
3387            let error = builder
3388                .call_method1(py, "with_cache_database_factory", (factory,))
3389                .unwrap_err();
3390
3391            assert_eq!(
3392                error.to_string(),
3393                format!("RuntimeError: {BUILDER_OPERATION_IN_PROGRESS}")
3394            );
3395            let builder_ref = builder.borrow(py);
3396            let state = builder_ref
3397                .state
3398                .replace(PyLiveNodeBuilderState::InProgress);
3399            let is_ready = matches!(&state, PyLiveNodeBuilderState::Ready(_));
3400            builder_ref.state.set(state);
3401            assert!(is_ready);
3402            locals.call_method0("clear").unwrap();
3403        });
3404    }
3405
3406    #[rstest]
3407    fn test_python_builder_rejects_unregistered_external_msgbus_factory() {
3408        Python::initialize();
3409
3410        Python::attach(|py| {
3411            let factory = PyDict::new(py).unbind().into_any();
3412            let builder = PyLiveNode::py_builder(
3413                "TEST".to_string(),
3414                TraderId::from("TESTER-001"),
3415                Environment::Sandbox,
3416            )
3417            .unwrap();
3418
3419            let error = builder
3420                .py_with_external_msgbus_factory(factory)
3421                .unwrap_err();
3422
3423            assert_eq!(
3424                error.to_string(),
3425                "NotImplementedError: No message bus factory extractor registered for 'dict'"
3426            );
3427            builder
3428                .py_with_msgbus_config(MessageBusConfig::default())
3429                .unwrap();
3430        });
3431    }
3432
3433    #[derive(Debug)]
3434    struct ShutdownCancelStrategy {
3435        core: StrategyCore,
3436        instrument_id: InstrumentId,
3437    }
3438
3439    impl ShutdownCancelStrategy {
3440        fn new(instrument_id: InstrumentId) -> Self {
3441            Self {
3442                core: StrategyCore::new(StrategyConfig {
3443                    strategy_id: Some(StrategyId::from("SHUTDOWN-CANCEL-001")),
3444                    ..Default::default()
3445                }),
3446                instrument_id,
3447            }
3448        }
3449    }
3450
3451    nautilus_strategy!(ShutdownCancelStrategy);
3452
3453    impl DataActor for ShutdownCancelStrategy {
3454        fn on_stop(&mut self) -> anyhow::Result<()> {
3455            get_trading_cmd_sender().execute(TradingCommandMessage::new(
3456                MessagingSwitchboard::exec_engine_execute(),
3457                TradingCommand::CancelAllOrders(CancelAllOrders::new(
3458                    TraderId::from("TESTER-001"),
3459                    None,
3460                    StrategyId::from("SHUTDOWN-CANCEL-001"),
3461                    self.instrument_id,
3462                    None,
3463                    UUID4::new(),
3464                    UnixNanos::default(),
3465                    None,
3466                    None,
3467                )),
3468            ));
3469            Ok(())
3470        }
3471    }
3472    #[derive(Debug, Default)]
3473    struct TestDataClientConfig;
3474
3475    impl ClientConfig for TestDataClientConfig {
3476        fn as_any(&self) -> &dyn Any {
3477            self
3478        }
3479    }
3480
3481    #[derive(Debug)]
3482    #[expect(
3483        clippy::struct_field_names,
3484        reason = "test counters intentionally share the count postfix"
3485    )]
3486    struct TestHistoricalBarsDataClientFactory {
3487        request_count: Arc<AtomicUsize>,
3488        response_sent_count: Arc<AtomicUsize>,
3489        handler_visible_count: Arc<AtomicUsize>,
3490    }
3491
3492    impl TestHistoricalBarsDataClientFactory {
3493        fn new(
3494            request_count: Arc<AtomicUsize>,
3495            response_sent_count: Arc<AtomicUsize>,
3496            handler_visible_count: Arc<AtomicUsize>,
3497        ) -> Self {
3498            Self {
3499                request_count,
3500                response_sent_count,
3501                handler_visible_count,
3502            }
3503        }
3504    }
3505
3506    impl DataClientFactory for TestHistoricalBarsDataClientFactory {
3507        fn create(
3508            &self,
3509            name: &str,
3510            _config: &dyn ClientConfig,
3511            _cache: CacheView,
3512            _clock: Rc<RefCell<dyn Clock>>,
3513        ) -> anyhow::Result<Box<dyn DataClient>> {
3514            Ok(Box::new(TestHistoricalBarsDataClient::new(
3515                ClientId::from(name),
3516                Venue::from("SIM"),
3517                self.request_count.clone(),
3518                self.response_sent_count.clone(),
3519                self.handler_visible_count.clone(),
3520            )))
3521        }
3522
3523        fn name(&self) -> &'static str {
3524            "TEST_DATA"
3525        }
3526
3527        fn config_type(&self) -> &'static str {
3528            "TestDataClientConfig"
3529        }
3530    }
3531
3532    #[derive(Debug)]
3533    struct TestDisconnectFailureDataClientFactory {
3534        dispose_count: Arc<AtomicUsize>,
3535    }
3536
3537    impl TestDisconnectFailureDataClientFactory {
3538        fn new(dispose_count: Arc<AtomicUsize>) -> Self {
3539            Self { dispose_count }
3540        }
3541    }
3542
3543    impl DataClientFactory for TestDisconnectFailureDataClientFactory {
3544        fn create(
3545            &self,
3546            name: &str,
3547            _config: &dyn ClientConfig,
3548            _cache: CacheView,
3549            _clock: Rc<RefCell<dyn Clock>>,
3550        ) -> anyhow::Result<Box<dyn DataClient>> {
3551            Ok(Box::new(TestDisconnectFailureDataClient::new(
3552                ClientId::from(name),
3553                Venue::from("SIM"),
3554                self.dispose_count.clone(),
3555            )))
3556        }
3557
3558        fn name(&self) -> &'static str {
3559            "TEST_DISCONNECT_FAILURE"
3560        }
3561
3562        fn config_type(&self) -> &'static str {
3563            "TestDataClientConfig"
3564        }
3565    }
3566
3567    #[derive(Debug)]
3568    struct TestDisconnectFailureDataClient {
3569        client_id: ClientId,
3570        venue: Venue,
3571        connected: Arc<AtomicBool>,
3572        dispose_count: Arc<AtomicUsize>,
3573    }
3574
3575    impl TestDisconnectFailureDataClient {
3576        fn new(client_id: ClientId, venue: Venue, dispose_count: Arc<AtomicUsize>) -> Self {
3577            Self {
3578                client_id,
3579                venue,
3580                connected: Arc::new(AtomicBool::new(false)),
3581                dispose_count,
3582            }
3583        }
3584    }
3585
3586    #[async_trait(?Send)]
3587    impl DataClient for TestDisconnectFailureDataClient {
3588        fn client_id(&self) -> ClientId {
3589            self.client_id
3590        }
3591
3592        fn venue(&self) -> Option<Venue> {
3593            Some(self.venue)
3594        }
3595
3596        fn start(&mut self) -> anyhow::Result<()> {
3597            Ok(())
3598        }
3599
3600        fn stop(&mut self) -> anyhow::Result<()> {
3601            Ok(())
3602        }
3603
3604        fn reset(&mut self) -> anyhow::Result<()> {
3605            Ok(())
3606        }
3607
3608        fn dispose(&mut self) -> anyhow::Result<()> {
3609            self.dispose_count.fetch_add(1, Ordering::Relaxed);
3610            Ok(())
3611        }
3612
3613        fn is_connected(&self) -> bool {
3614            self.connected.load(Ordering::Relaxed)
3615        }
3616
3617        fn is_disconnected(&self) -> bool {
3618            !self.is_connected()
3619        }
3620
3621        async fn connect(&mut self) -> anyhow::Result<()> {
3622            self.connected.store(true, Ordering::Relaxed);
3623            Ok(())
3624        }
3625
3626        async fn disconnect(&mut self) -> anyhow::Result<()> {
3627            self.connected.store(false, Ordering::Relaxed);
3628            anyhow::bail!("test disconnect failed")
3629        }
3630    }
3631
3632    struct VenueLessDataClient {
3633        client_id: ClientId,
3634    }
3635
3636    impl VenueLessDataClient {
3637        fn new(client_id: ClientId) -> Self {
3638            Self { client_id }
3639        }
3640    }
3641
3642    #[async_trait(?Send)]
3643    impl DataClient for VenueLessDataClient {
3644        fn client_id(&self) -> ClientId {
3645            self.client_id
3646        }
3647
3648        fn venue(&self) -> Option<Venue> {
3649            None
3650        }
3651
3652        fn start(&mut self) -> anyhow::Result<()> {
3653            Ok(())
3654        }
3655
3656        fn stop(&mut self) -> anyhow::Result<()> {
3657            Ok(())
3658        }
3659
3660        fn reset(&mut self) -> anyhow::Result<()> {
3661            Ok(())
3662        }
3663
3664        fn dispose(&mut self) -> anyhow::Result<()> {
3665            Ok(())
3666        }
3667
3668        fn is_connected(&self) -> bool {
3669            true
3670        }
3671
3672        fn is_disconnected(&self) -> bool {
3673            false
3674        }
3675
3676        async fn connect(&mut self) -> anyhow::Result<()> {
3677            Ok(())
3678        }
3679
3680        async fn disconnect(&mut self) -> anyhow::Result<()> {
3681            Ok(())
3682        }
3683    }
3684
3685    #[derive(Debug)]
3686    struct VenueLessDataClientFactory;
3687
3688    impl DataClientFactory for VenueLessDataClientFactory {
3689        fn create(
3690            &self,
3691            name: &str,
3692            _config: &dyn ClientConfig,
3693            _cache: CacheView,
3694            _clock: Rc<RefCell<dyn Clock>>,
3695        ) -> anyhow::Result<Box<dyn DataClient>> {
3696            Ok(Box::new(VenueLessDataClient::new(ClientId::from(name))))
3697        }
3698
3699        fn name(&self) -> &'static str {
3700            "VENUE_LESS"
3701        }
3702
3703        fn config_type(&self) -> &'static str {
3704            "TestDataClientConfig"
3705        }
3706    }
3707
3708    #[expect(
3709        clippy::unnecessary_wraps,
3710        reason = "signature must match the factory extractor function pointer"
3711    )]
3712    fn extract_reentrant_data_client_factory(
3713        _py: Python<'_>,
3714        _factory: Py<pyo3::PyAny>,
3715    ) -> pyo3::PyResult<Box<dyn DataClientFactory>> {
3716        Ok(Box::new(VenueLessDataClientFactory))
3717    }
3718
3719    #[expect(
3720        clippy::unnecessary_wraps,
3721        reason = "signature must match the config extractor function pointer"
3722    )]
3723    fn extract_reentrant_data_client_config(
3724        _py: Python<'_>,
3725        _config: Py<pyo3::PyAny>,
3726    ) -> pyo3::PyResult<Box<dyn ClientConfig>> {
3727        Ok(Box::new(TestDataClientConfig))
3728    }
3729
3730    #[rstest]
3731    fn test_python_builder_blocks_factory_name_reentry() {
3732        get_global_pyo3_registry()
3733            .register_factory_extractor(
3734                "REENTRANT_DATA".to_string(),
3735                extract_reentrant_data_client_factory,
3736            )
3737            .unwrap();
3738        get_global_pyo3_registry()
3739            .register_config_extractor(
3740                "ReentrantDataClientConfig".to_string(),
3741                extract_reentrant_data_client_config,
3742            )
3743            .unwrap();
3744        Python::initialize();
3745
3746        Python::attach(|py| {
3747            let builder = Py::new(
3748                py,
3749                PyLiveNode::py_builder(
3750                    "TEST".to_string(),
3751                    TraderId::from("TESTER-001"),
3752                    Environment::Sandbox,
3753                )
3754                .unwrap(),
3755            )
3756            .unwrap();
3757            let locals = PyDict::new(py);
3758            locals.set_item("builder", &builder).unwrap();
3759            py.run(
3760                pyo3::ffi::c_str!(
3761                    r#"
3762import sys
3763from types import ModuleType
3764from unittest.mock import patch
3765
3766class ReentrantDataClientFactory:
3767    def __init__(self):
3768        self.reprs = []
3769        self.results = []
3770
3771    def name(self):
3772        self.reprs.append(repr(builder))
3773        try:
3774            builder.with_save_state(True)
3775        except RuntimeError as e:
3776            self.results.append((type(e).__name__, str(e)))
3777        return "REENTRANT_DATA"
3778
3779class ReentrantDataClientConfig:
3780    pass
3781
3782factory = ReentrantDataClientFactory()
3783config = ReentrantDataClientConfig()
3784package_module = ModuleType("nautilus_trader")
3785config_module = ModuleType("nautilus_trader.live.config")
3786config_module.resolve_client_registration = lambda factory, config: (factory, config)
3787clients_module = ModuleType("nautilus_trader.live.clients")
3788clients_module.DataClientFactory = type("DataClientFactory", (), {})
3789
3790def add_data_client():
3791    # Exercise re-entry without importing an independently built extension
3792    with patch.dict(sys.modules, {
3793        package_module.__name__: package_module,
3794        config_module.__name__: config_module,
3795        clients_module.__name__: clients_module,
3796    }):
3797        return builder.add_data_client(None, factory, config)
3798"#
3799                ),
3800                Some(&locals),
3801                None,
3802            )
3803            .unwrap();
3804            let factory = locals.get_item("factory").unwrap();
3805            let add_data_client = locals.get_item("add_data_client").unwrap();
3806
3807            add_data_client.call0().unwrap();
3808
3809            let results = factory
3810                .getattr("results")
3811                .unwrap()
3812                .extract::<Vec<(String, String)>>()
3813                .unwrap();
3814            assert_eq!(
3815                results,
3816                vec![
3817                    (
3818                        "RuntimeError".to_string(),
3819                        BUILDER_OPERATION_IN_PROGRESS.to_string(),
3820                    ),
3821                    (
3822                        "RuntimeError".to_string(),
3823                        BUILDER_OPERATION_IN_PROGRESS.to_string(),
3824                    ),
3825                ]
3826            );
3827            assert_eq!(
3828                factory
3829                    .getattr("reprs")
3830                    .unwrap()
3831                    .extract::<Vec<String>>()
3832                    .unwrap(),
3833                vec!["PyLiveNodeBuilder { inner: <operation active> }"; 2]
3834            );
3835            let builder_ref = builder.borrow(py);
3836            let state = builder_ref
3837                .state
3838                .replace(PyLiveNodeBuilderState::InProgress);
3839            let is_ready = matches!(&state, PyLiveNodeBuilderState::Ready(_));
3840            builder_ref.state.set(state);
3841            assert!(is_ready);
3842            drop(builder_ref);
3843
3844            let duplicate_error = add_data_client.call0().unwrap_err();
3845
3846            assert_eq!(
3847                duplicate_error.to_string(),
3848                "ValueError: Client 'REENTRANT_DATA' is already registered"
3849            );
3850            let builder_ref = builder.borrow(py);
3851            let state = builder_ref
3852                .state
3853                .replace(PyLiveNodeBuilderState::InProgress);
3854            let retains_registration = matches!(
3855                &state,
3856                PyLiveNodeBuilderState::Ready(inner) if inner.has_data_client("REENTRANT_DATA")
3857            );
3858            builder_ref.state.set(state);
3859            assert!(retains_registration);
3860            drop(builder_ref);
3861            builder
3862                .call_method1(py, "with_save_state", (true,))
3863                .unwrap();
3864            locals.call_method0("clear").unwrap();
3865        });
3866    }
3867
3868    #[derive(Debug)]
3869    struct TestHistoricalBarsDataClient {
3870        client_id: ClientId,
3871        venue: Venue,
3872        connected: Arc<AtomicBool>,
3873        request_count: Arc<AtomicUsize>,
3874        response_sent_count: Arc<AtomicUsize>,
3875        handler_visible_count: Arc<AtomicUsize>,
3876    }
3877
3878    impl TestHistoricalBarsDataClient {
3879        fn new(
3880            client_id: ClientId,
3881            venue: Venue,
3882            request_count: Arc<AtomicUsize>,
3883            response_sent_count: Arc<AtomicUsize>,
3884            handler_visible_count: Arc<AtomicUsize>,
3885        ) -> Self {
3886            Self {
3887                client_id,
3888                venue,
3889                connected: Arc::new(AtomicBool::new(false)),
3890                request_count,
3891                response_sent_count,
3892                handler_visible_count,
3893            }
3894        }
3895
3896        fn make_bar(bar_type: BarType) -> Bar {
3897            Bar::new(
3898                bar_type,
3899                Price::from("1.0000"),
3900                Price::from("1.1000"),
3901                Price::from("0.9000"),
3902                Price::from("1.0500"),
3903                Quantity::from("1000"),
3904                UnixNanos::from(1_700_000_000_000_000_000u64),
3905                UnixNanos::from(1_700_000_000_000_000_001u64),
3906            )
3907        }
3908    }
3909
3910    #[async_trait(?Send)]
3911    impl DataClient for TestHistoricalBarsDataClient {
3912        fn client_id(&self) -> ClientId {
3913            self.client_id
3914        }
3915
3916        fn venue(&self) -> Option<Venue> {
3917            Some(self.venue)
3918        }
3919
3920        fn start(&mut self) -> anyhow::Result<()> {
3921            Ok(())
3922        }
3923
3924        fn stop(&mut self) -> anyhow::Result<()> {
3925            Ok(())
3926        }
3927
3928        fn reset(&mut self) -> anyhow::Result<()> {
3929            Ok(())
3930        }
3931
3932        fn dispose(&mut self) -> anyhow::Result<()> {
3933            Ok(())
3934        }
3935
3936        fn is_connected(&self) -> bool {
3937            self.connected.load(Ordering::Relaxed)
3938        }
3939
3940        fn is_disconnected(&self) -> bool {
3941            !self.is_connected()
3942        }
3943
3944        async fn connect(&mut self) -> anyhow::Result<()> {
3945            self.connected.store(true, Ordering::Relaxed);
3946            Ok(())
3947        }
3948
3949        async fn disconnect(&mut self) -> anyhow::Result<()> {
3950            self.connected.store(false, Ordering::Relaxed);
3951            Ok(())
3952        }
3953
3954        fn request_bars(&self, request: RequestBars) -> anyhow::Result<()> {
3955            let bar_type = request.single_bar_type()?;
3956            self.request_count.fetch_add(1, Ordering::Relaxed);
3957
3958            if get_message_bus()
3959                .borrow()
3960                .get_response_handler(&request.request_id)
3961                .is_some()
3962            {
3963                self.handler_visible_count.fetch_add(1, Ordering::Relaxed);
3964            }
3965
3966            let sender = get_data_event_sender();
3967            let client_id = self.client_id;
3968            let response_sent_count = self.response_sent_count.clone();
3969
3970            let response = BarsResponse::new(
3971                request.request_id,
3972                client_id,
3973                bar_type,
3974                vec![Self::make_bar(bar_type)],
3975                None,
3976                None,
3977                UnixNanos::from(1_700_000_000_000_000_002u64),
3978                None,
3979            );
3980
3981            tokio::spawn(async move {
3982                response_sent_count.fetch_add(1, Ordering::Relaxed);
3983                sender
3984                    .send(DataEvent::Response(DataResponse::Bars(response)))
3985                    .expect("test bars response should send");
3986            });
3987
3988            Ok(())
3989        }
3990    }
3991
3992    fn install_tracking_strategy_module(py: Python<'_>, module_name: &str) {
3993        let module = PyModule::new(py, module_name).expect("test module should create");
3994        module
3995            .setattr("Strategy", py.get_type::<PyStrategy>())
3996            .expect("Strategy type should bind");
3997        module
3998            .setattr("BarType", py.get_type::<BarType>())
3999            .expect("BarType type should bind");
4000        module
4001            .setattr("RESULTS", PyDict::new(py))
4002            .expect("RESULTS should bind");
4003
4004        let code = CString::new(
4005            r#"
4006RESULTS["on_start"] = 0
4007RESULTS["on_historical_bars"] = 0
4008RESULTS["historical_bar_count"] = 0
4009RESULTS["last_request_id"] = ""
4010
4011class HistoricalBarsStrategy(Strategy):
4012    def __init__(self):
4013        super().__init__()
4014        self.bar_type = BarType.from_str("AUDUSD.SIM-1-MINUTE-LAST-EXTERNAL")
4015
4016    def on_start(self):
4017        RESULTS["on_start"] += 1
4018        RESULTS["last_request_id"] = self.request_bars(self.bar_type)
4019
4020    def on_stop(self):
4021        pass
4022
4023    def on_historical_bars(self, bars):
4024        RESULTS["on_historical_bars"] += 1
4025        RESULTS["historical_bar_count"] += len(bars)
4026"#,
4027        )
4028        .expect("python test code should be valid CString");
4029
4030        py.run(code.as_c_str(), Some(&module.dict()), None)
4031            .expect("test strategy code should execute");
4032
4033        let sys_modules = py
4034            .import("sys")
4035            .expect("sys should import")
4036            .getattr("modules")
4037            .expect("sys.modules should exist");
4038        sys_modules
4039            .set_item(module_name, module)
4040            .expect("test strategy module should register");
4041    }
4042
4043    fn get_results(py: Python<'_>, module_name: &str) -> (usize, usize, usize) {
4044        let module = py
4045            .import(module_name)
4046            .expect("test strategy module should import");
4047        let results_obj = module.getattr("RESULTS").expect("RESULTS should exist");
4048        let results = results_obj
4049            .cast::<PyDict>()
4050            .expect("RESULTS should be a dict");
4051
4052        let on_start = results
4053            .get_item("on_start")
4054            .expect("on_start key should exist")
4055            .extract::<usize>()
4056            .expect("on_start should extract");
4057        let on_historical_bars = results
4058            .get_item("on_historical_bars")
4059            .expect("on_historical_bars key should exist")
4060            .extract::<usize>()
4061            .expect("on_historical_bars should extract");
4062        let historical_bar_count = results
4063            .get_item("historical_bar_count")
4064            .expect("historical_bar_count key should exist")
4065            .extract::<usize>()
4066            .expect("historical_bar_count should extract");
4067
4068        (on_start, on_historical_bars, historical_bar_count)
4069    }
4070
4071    fn install_timer_strategy_module(py: Python<'_>, module_name: &str) {
4072        let module = PyModule::new(py, module_name).expect("test module should create");
4073        module
4074            .setattr("Strategy", py.get_type::<PyStrategy>())
4075            .expect("Strategy type should bind");
4076        module
4077            .setattr("RESULTS", PyDict::new(py))
4078            .expect("RESULTS should bind");
4079
4080        let code = CString::new(
4081            r#"
4082RESULTS["on_start"] = 0
4083RESULTS["callback_timer_count"] = 0
4084RESULTS["default_timer_count"] = 0
4085RESULTS["callback_event_type"] = ""
4086RESULTS["default_event_type"] = ""
4087RESULTS["callback_event_name"] = ""
4088RESULTS["default_event_name"] = ""
4089
4090class LiveTimerStrategy(Strategy):
4091    def __init__(self):
4092        super().__init__()
4093
4094    def on_start(self):
4095        RESULTS["on_start"] += 1
4096        self.clock.set_timer_ns(
4097            "explicit_timer",
4098            1_000_000,
4099            callback=self._on_timer,
4100            fire_immediately=True,
4101        )
4102        self.clock.set_timer_ns(
4103            "default_timer",
4104            1_000_000,
4105            fire_immediately=True,
4106        )
4107
4108    def on_stop(self):
4109        pass
4110
4111    def _on_timer(self, event):
4112        RESULTS["callback_timer_count"] += 1
4113        RESULTS["callback_event_type"] = type(event).__name__
4114        RESULTS["callback_event_name"] = event.name
4115
4116    def on_time_event(self, event):
4117        RESULTS["default_timer_count"] += 1
4118        RESULTS["default_event_type"] = type(event).__name__
4119        RESULTS["default_event_name"] = event.name
4120"#,
4121        )
4122        .expect("python test code should be valid CString");
4123
4124        py.run(code.as_c_str(), Some(&module.dict()), None)
4125            .expect("test strategy code should execute");
4126
4127        let sys_modules = py
4128            .import("sys")
4129            .expect("sys should import")
4130            .getattr("modules")
4131            .expect("sys.modules should exist");
4132        sys_modules
4133            .set_item(module_name, module)
4134            .expect("test strategy module should register");
4135    }
4136
4137    fn install_claim_strategy_module(py: Python<'_>, module_name: &str) {
4138        let module = PyModule::new(py, module_name).expect("test module should create");
4139        module
4140            .setattr("Strategy", py.get_type::<PyStrategy>())
4141            .expect("Strategy type should bind");
4142
4143        let code = CString::new(
4144            "
4145class ClaimsConfig:
4146    def __init__(
4147        self,
4148        strategy_id=None,
4149        order_id_tag=None,
4150        external_order_instrument_ids=None,
4151        oms_type=None,
4152    ):
4153        self.strategy_id = strategy_id
4154        self.order_id_tag = order_id_tag
4155        self.external_order_instrument_ids = external_order_instrument_ids
4156        self.oms_type = oms_type
4157
4158class ClaimsStrategy(Strategy):
4159    def __init__(self, config):
4160        super().__init__(config)
4161",
4162        )
4163        .expect("python test code should be valid CString");
4164
4165        py.run(code.as_c_str(), Some(&module.dict()), None)
4166            .expect("test strategy code should execute");
4167
4168        let sys_modules = py
4169            .import("sys")
4170            .expect("sys should import")
4171            .getattr("modules")
4172            .expect("sys.modules should exist");
4173        sys_modules
4174            .set_item(module_name, module)
4175            .expect("test strategy module should register");
4176    }
4177
4178    #[derive(Debug)]
4179    struct TimerStrategyResults {
4180        on_start: usize,
4181        callback_timer_count: usize,
4182        default_timer_count: usize,
4183        callback_event_type: String,
4184        default_event_type: String,
4185        callback_event_name: String,
4186        default_event_name: String,
4187    }
4188
4189    fn get_timer_results(py: Python<'_>, module_name: &str) -> TimerStrategyResults {
4190        let module = py
4191            .import(module_name)
4192            .expect("test strategy module should import");
4193        let results_obj = module.getattr("RESULTS").expect("RESULTS should exist");
4194        let results = results_obj
4195            .cast::<PyDict>()
4196            .expect("RESULTS should be a dict");
4197
4198        TimerStrategyResults {
4199            on_start: results
4200                .get_item("on_start")
4201                .expect("on_start key should exist")
4202                .extract::<usize>()
4203                .expect("on_start should extract"),
4204            callback_timer_count: results
4205                .get_item("callback_timer_count")
4206                .expect("callback_timer_count key should exist")
4207                .extract::<usize>()
4208                .expect("callback_timer_count should extract"),
4209            default_timer_count: results
4210                .get_item("default_timer_count")
4211                .expect("default_timer_count key should exist")
4212                .extract::<usize>()
4213                .expect("default_timer_count should extract"),
4214            callback_event_type: results
4215                .get_item("callback_event_type")
4216                .expect("callback_event_type key should exist")
4217                .extract::<String>()
4218                .expect("callback_event_type should extract"),
4219            default_event_type: results
4220                .get_item("default_event_type")
4221                .expect("default_event_type key should exist")
4222                .extract::<String>()
4223                .expect("default_event_type should extract"),
4224            callback_event_name: results
4225                .get_item("callback_event_name")
4226                .expect("callback_event_name key should exist")
4227                .extract::<String>()
4228                .expect("callback_event_name should extract"),
4229            default_event_name: results
4230                .get_item("default_event_name")
4231                .expect("default_event_name key should exist")
4232                .extract::<String>()
4233                .expect("default_event_name should extract"),
4234        }
4235    }
4236
4237    #[cfg(feature = "examples")]
4238    #[rstest]
4239    #[case("CompositeMarketMaker")]
4240    #[case("DeltaNeutralVol")]
4241    #[case("EmaCross")]
4242    #[case("ExecTester")]
4243    #[case("GridMarketMaker")]
4244    #[case("HurstVpinDirectional")]
4245    #[case("OrderBookImbalance")]
4246    fn test_builtin_strategy_register_accepts_supported_names(#[case] type_name: &str) {
4247        assert!(super::builtin_strategy_register(type_name).is_some());
4248    }
4249
4250    #[cfg(feature = "examples")]
4251    #[rstest]
4252    #[case("DataTester")]
4253    fn test_builtin_actor_register_accepts_supported_names(#[case] type_name: &str) {
4254        assert!(super::builtin_actor_register(type_name).is_some());
4255    }
4256
4257    #[cfg(feature = "examples")]
4258    #[rstest]
4259    fn test_builtin_register_rejects_unknown_names() {
4260        assert!(super::builtin_strategy_register("UnknownStrategy").is_none());
4261        assert!(super::builtin_actor_register("UnknownActor").is_none());
4262    }
4263
4264    #[rstest]
4265    fn test_inspection_wrappers_share_kernel_state() {
4266        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
4267            .unwrap()
4268            .with_reconciliation(false)
4269            .build()
4270            .map(PyLiveNode::new)
4271            .unwrap();
4272
4273        let cache = node.py_cache().unwrap();
4274        let portfolio = node.py_portfolio().unwrap();
4275
4276        assert!(Rc::ptr_eq(
4277            &cache.cache_rc(),
4278            &node.node_mut().unwrap().kernel().cache
4279        ));
4280        assert!(Rc::ptr_eq(
4281            &portfolio.portfolio_rc(),
4282            &node.node_mut().unwrap().kernel().portfolio
4283        ));
4284    }
4285
4286    #[cfg(feature = "examples")]
4287    #[rstest]
4288    fn test_builtin_strategy_register_rejects_mismatched_config() {
4289        Python::initialize();
4290
4291        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
4292            .unwrap()
4293            .with_reconciliation(false)
4294            .build()
4295            .map(PyLiveNode::new)
4296            .unwrap();
4297
4298        Python::attach(|py| {
4299            let register = super::builtin_strategy_register("EmaCross").unwrap();
4300            let config = PyDict::new(py);
4301            let error = register(&mut node.node_mut().unwrap(), config.as_any()).unwrap_err();
4302
4303            assert!(error.is_instance_of::<pyo3::exceptions::PyTypeError>(py));
4304        });
4305    }
4306
4307    #[cfg(feature = "examples")]
4308    #[rstest]
4309    fn test_builtin_actor_register_rejects_mismatched_config() {
4310        Python::initialize();
4311
4312        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
4313            .unwrap()
4314            .with_reconciliation(false)
4315            .build()
4316            .map(PyLiveNode::new)
4317            .unwrap();
4318
4319        Python::attach(|py| {
4320            let register = super::builtin_actor_register("DataTester").unwrap();
4321            let config = PyDict::new(py);
4322            let error = register(&mut node.node_mut().unwrap(), config.as_any()).unwrap_err();
4323
4324            assert!(error.is_instance_of::<pyo3::exceptions::PyTypeError>(py));
4325        });
4326    }
4327
4328    #[rstest]
4329    #[case(ShutdownRunPath::Native)]
4330    #[case(ShutdownRunPath::PyO3)]
4331    fn test_native_and_python_shutdown_paths_drain_cancel_command(
4332        #[case] run_path: ShutdownRunPath,
4333    ) {
4334        Python::initialize();
4335
4336        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
4337            .unwrap()
4338            .with_reconciliation(false)
4339            .with_delay_post_stop_secs(1)
4340            .with_timeout_connection(1)
4341            .build()
4342            .map(PyLiveNode::new)
4343            .unwrap();
4344        node.node_mut()
4345            .unwrap()
4346            .add_strategy(ShutdownCancelStrategy::new(InstrumentId::from(
4347                "TEST.POLYMARKET",
4348            )))
4349            .unwrap();
4350
4351        let handle = node.node_mut().unwrap().handle();
4352        let stop_handle = handle.clone();
4353
4354        let stop_thread = thread::spawn(move || {
4355            let deadline = Instant::now() + Duration::from_secs(5);
4356            while !stop_handle.is_running() && Instant::now() < deadline {
4357                thread::sleep(Duration::from_millis(10));
4358            }
4359
4360            stop_handle.stop();
4361        });
4362
4363        match run_path {
4364            ShutdownRunPath::Native => get_runtime()
4365                .block_on(node.node_mut().unwrap().run())
4366                .expect("native LiveNode run should stop cleanly"),
4367            ShutdownRunPath::PyO3 => Python::attach(|py| {
4368                super::run_live_node_detached(py, &mut node.node_mut().unwrap())
4369                    .expect("Python LiveNode run should stop cleanly");
4370            }),
4371        }
4372
4373        stop_thread.join().expect("stop thread should join");
4374        let metrics = handle.metrics_snapshot();
4375
4376        assert_eq!(metrics.exec_commands.dispatched, 1);
4377        assert_eq!(metrics.exec_commands.queue_depth, 0);
4378        assert!(!handle.is_running());
4379    }
4380
4381    #[rstest]
4382    fn test_run_live_node_detached_releases_gil() {
4383        Python::initialize();
4384
4385        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
4386            .unwrap()
4387            .with_reconciliation(false)
4388            .with_delay_post_stop_secs(0)
4389            .with_timeout_connection(1)
4390            .build()
4391            .map(PyLiveNode::new)
4392            .unwrap();
4393
4394        let handle = node.node_mut().unwrap().handle();
4395        let (gil_tx, gil_rx) = mpsc::channel();
4396        let acquired_before_stop = Arc::new(AtomicBool::new(false));
4397        let acquired_before_stop_for_thread = acquired_before_stop.clone();
4398
4399        let stop_thread = thread::spawn(move || {
4400            if gil_rx.recv_timeout(Duration::from_secs(1)).is_ok() {
4401                acquired_before_stop_for_thread.store(true, Ordering::SeqCst);
4402            }
4403
4404            handle.stop();
4405        });
4406
4407        let gil_thread = thread::spawn(move || {
4408            Python::attach(|_| {});
4409            let _ = gil_tx.send(());
4410        });
4411
4412        Python::attach(|py| {
4413            super::run_live_node_detached(py, &mut node.node_mut().unwrap())
4414                .expect("node should run cleanly");
4415        });
4416
4417        stop_thread.join().expect("stop thread should join");
4418        gil_thread.join().expect("GIL thread should join");
4419
4420        assert!(
4421            acquired_before_stop.load(Ordering::SeqCst),
4422            "worker thread should acquire the GIL while LiveNode::run is blocked"
4423        );
4424    }
4425
4426    #[rstest]
4427    fn test_host_loop_waker_coalesces_redundant_wakes() {
4428        let (waker, receiver, _) = host_loop_waker_probe();
4429
4430        std::task::Wake::wake(waker.clone());
4431        let consuming_wake = receiver.recv_timeout(Duration::from_secs(1));
4432        std::task::Wake::wake_by_ref(&waker);
4433        let redundant_wake = receiver.try_recv();
4434
4435        assert!(matches!(
4436            consuming_wake,
4437            Ok(super::HostWakeSignal::Resume(7))
4438        ));
4439        assert!(matches!(redundant_wake, Err(mpsc::TryRecvError::Empty)));
4440    }
4441
4442    #[rstest]
4443    fn test_host_loop_waker_ignores_wake_after_close() {
4444        let (waker, receiver, handle) = host_loop_waker_probe();
4445        waker.control.close();
4446
4447        std::task::Wake::wake_by_ref(&waker);
4448
4449        assert!(matches!(
4450            receiver.recv().unwrap(),
4451            super::HostWakeSignal::Shutdown
4452        ));
4453        assert!(matches!(
4454            receiver.try_recv(),
4455            Err(mpsc::TryRecvError::Empty)
4456        ));
4457        assert!(!handle.should_stop());
4458    }
4459
4460    #[rstest]
4461    fn test_host_loop_waker_stops_node_when_pump_is_gone() {
4462        let (waker, receiver, handle) = host_loop_waker_probe();
4463        drop(receiver);
4464
4465        std::task::Wake::wake_by_ref(&waker);
4466
4467        assert!(!waker.control.active.load(Ordering::Acquire));
4468        assert!(handle.should_stop());
4469    }
4470
4471    fn host_loop_waker_probe() -> (
4472        Arc<super::HostLoopWaker>,
4473        mpsc::Receiver<super::HostWakeSignal>,
4474        crate::node::LiveNodeHandle,
4475    ) {
4476        let (sender, receiver) = mpsc::channel();
4477        let handle = crate::node::LiveNodeHandle::new();
4478
4479        let control = Arc::new(super::HostWakeControl {
4480            sender,
4481            active: AtomicBool::new(true),
4482            handle: handle.clone(),
4483        });
4484
4485        let waker = Arc::new(super::HostLoopWaker {
4486            generation: 7,
4487            scheduled: AtomicBool::new(false),
4488            control,
4489        });
4490
4491        (waker, receiver, handle)
4492    }
4493
4494    #[rstest]
4495    fn test_host_loop_waker_breaks_gil_dependency_lock_cycle() {
4496        Python::initialize();
4497
4498        let (waker, mut wake_pump, event_loop) = Python::attach(|py| {
4499            let event_loop = py
4500                .import("asyncio")
4501                .unwrap()
4502                .call_method0("new_event_loop")
4503                .unwrap();
4504            let state = Arc::new(super::RunWakeState::default());
4505            let wake_callback = Py::new(py, super::PyNodeRunWake { state })
4506                .unwrap()
4507                .into_any();
4508            let event_loop = event_loop.unbind();
4509            let wake_pump = super::HostWakePump::start(
4510                event_loop.clone_ref(py),
4511                wake_callback,
4512                crate::node::LiveNodeHandle::new(),
4513            )
4514            .unwrap();
4515            let waker = wake_pump.waker(1);
4516
4517            (waker, wake_pump, event_loop)
4518        });
4519
4520        let (start_tx, start_rx) = mpsc::channel();
4521        let (locked_tx, locked_rx) = mpsc::channel();
4522        let dependency_lock = Arc::new(Mutex::new(()));
4523        let dependency_lock_for_thread = dependency_lock.clone();
4524
4525        let wake_thread = thread::spawn(move || {
4526            let _guard = dependency_lock_for_thread.lock();
4527            locked_tx.send(()).unwrap();
4528            start_rx.recv().unwrap();
4529            waker.wake_by_ref();
4530        });
4531
4532        locked_rx
4533            .recv_timeout(Duration::from_secs(1))
4534            .expect("wake thread should hold the dependency lock");
4535
4536        let dependency_released_while_gil_held = Python::attach(|_| {
4537            start_tx.send(()).unwrap();
4538            let deadline = Instant::now() + Duration::from_secs(1);
4539
4540            loop {
4541                match dependency_lock.try_lock() {
4542                    Some(_) => break true,
4543                    None if Instant::now() < deadline => {
4544                        thread::yield_now();
4545                    }
4546                    None => break false,
4547                }
4548            }
4549        });
4550
4551        wake_thread.join().unwrap();
4552        Python::attach(|py| {
4553            wake_pump.close();
4554            wake_pump.join(Some(py));
4555            event_loop.bind(py).call_method0("close").unwrap();
4556        });
4557
4558        assert!(dependency_released_while_gil_held);
4559    }
4560
4561    #[rstest]
4562    fn test_run_wake_state_ignores_stale_generation() {
4563        Python::initialize();
4564
4565        Python::attach(|py| {
4566            let event_loop = py
4567                .import("asyncio")
4568                .unwrap()
4569                .call_method0("new_event_loop")
4570                .unwrap();
4571            let future = event_loop.call_method0("create_future").unwrap();
4572            let state = super::RunWakeState::default();
4573            state.suspend(2, future.clone().unbind());
4574
4575            state.resume(py, 1).unwrap();
4576            let done_after_stale: bool = future.call_method0("done").unwrap().extract().unwrap();
4577            state.resume(py, 2).unwrap();
4578            let done_after_current: bool = future.call_method0("done").unwrap().extract().unwrap();
4579            event_loop.call_method0("close").unwrap();
4580
4581            assert!(!done_after_stale);
4582            assert!(done_after_current);
4583        });
4584    }
4585
4586    #[rstest]
4587    fn test_host_wake_pump_resumes_current_suspension() {
4588        Python::initialize();
4589
4590        Python::attach(|py| {
4591            let asyncio = py.import("asyncio").unwrap();
4592            let event_loop = asyncio.call_method0("new_event_loop").unwrap();
4593            let future = event_loop.call_method0("create_future").unwrap();
4594            let state = Arc::new(super::RunWakeState::default());
4595            state.suspend(7, future.clone().unbind());
4596            let wake_callback = Py::new(py, super::PyNodeRunWake { state })
4597                .unwrap()
4598                .into_any();
4599            let mut wake_pump = super::HostWakePump::start(
4600                event_loop.clone().unbind(),
4601                wake_callback,
4602                crate::node::LiveNodeHandle::new(),
4603            )
4604            .unwrap();
4605
4606            wake_pump.waker(7).wake_by_ref();
4607            let wait_for = asyncio.call_method1("wait_for", (&future, 1.0)).unwrap();
4608            let result = event_loop
4609                .call_method1("run_until_complete", (wait_for,))
4610                .unwrap();
4611            wake_pump.close();
4612            wake_pump.join(Some(py));
4613            event_loop.call_method0("close").unwrap();
4614
4615            assert!(result.is_none());
4616        });
4617    }
4618
4619    #[rstest]
4620    fn test_host_wake_pump_stops_node_when_loop_is_closed() {
4621        Python::initialize();
4622
4623        Python::attach(|py| {
4624            let event_loop = py
4625                .import("asyncio")
4626                .unwrap()
4627                .call_method0("new_event_loop")
4628                .unwrap();
4629            event_loop.call_method0("close").unwrap();
4630            let state = Arc::new(super::RunWakeState::default());
4631            let wake_callback = Py::new(py, super::PyNodeRunWake { state })
4632                .unwrap()
4633                .into_any();
4634            let handle = crate::node::LiveNodeHandle::new();
4635            let mut wake_pump =
4636                super::HostWakePump::start(event_loop.unbind(), wake_callback, handle.clone())
4637                    .unwrap();
4638
4639            wake_pump.waker(1).wake_by_ref();
4640            wake_pump.join(Some(py));
4641
4642            assert!(handle.should_stop());
4643        });
4644    }
4645
4646    #[rstest]
4647    fn test_hosted_run_completes_after_stop() {
4648        Python::initialize();
4649
4650        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
4651            .unwrap()
4652            .with_reconciliation(false)
4653            .with_delay_post_stop_secs(0)
4654            .with_delay_shutdown_secs(0)
4655            .with_timeout_connection(0)
4656            .with_timeout_disconnection_secs(0)
4657            .build()
4658            .map(PyLiveNode::new)
4659            .unwrap();
4660
4661        Python::attach(|py| {
4662            let locals = PyDict::new(py);
4663            let py_node = Py::new(py, node).unwrap();
4664            locals.set_item("node", &py_node).unwrap();
4665            py.run(
4666                pyo3::ffi::c_str!(
4667                    "import asyncio\n\nasync def run_node():\n    handle = node.handle()\n    asyncio.get_running_loop().call_soon(handle.stop)\n    await asyncio.wait_for(node.run_async(), timeout=5)\n\nasyncio.run(run_node())"
4668                ),
4669                Some(&locals),
4670                None,
4671            )
4672            .unwrap();
4673
4674            let node = py_node.borrow(py);
4675            assert!(!node.is_consumed());
4676            assert_eq!(
4677                node.node().unwrap().state(),
4678                crate::node::NodeState::Stopped
4679            );
4680        });
4681
4682        get_message_bus().borrow_mut().dispose();
4683    }
4684
4685    #[rstest]
4686    fn test_build_routes_venue_less_data_client_with_venue_routing() {
4687        Python::initialize();
4688
4689        let routing = RoutingConfig::builder()
4690            .venues(vec!["IBIS".to_string()])
4691            .build();
4692        let node = LiveNode::builder(TraderId::from("TEST-001"), Environment::Sandbox)
4693            .unwrap()
4694            .with_reconciliation(false)
4695            .with_timeout_connection(1)
4696            .add_data_client_with_routing(
4697                Some("IB".to_string()),
4698                Box::new(VenueLessDataClientFactory),
4699                Box::new(TestDataClientConfig),
4700                routing,
4701            )
4702            .unwrap()
4703            .build();
4704
4705        assert!(node.is_ok(), "build should succeed: {:?}", node.err());
4706    }
4707
4708    #[rstest]
4709    fn test_build_routes_venue_less_data_client_with_default_and_venues() {
4710        Python::initialize();
4711
4712        let routing = RoutingConfig::builder()
4713            .default(true)
4714            .venues(vec!["IBIS".to_string()])
4715            .build();
4716        let node = LiveNode::builder(TraderId::from("TEST-001"), Environment::Sandbox)
4717            .unwrap()
4718            .with_reconciliation(false)
4719            .with_timeout_connection(1)
4720            .add_data_client_with_routing(
4721                Some("IB".to_string()),
4722                Box::new(VenueLessDataClientFactory),
4723                Box::new(TestDataClientConfig),
4724                routing,
4725            )
4726            .unwrap()
4727            .build();
4728
4729        assert!(node.is_ok(), "build should succeed: {:?}", node.err());
4730    }
4731
4732    #[rstest]
4733    fn test_stop_live_node_detached_releases_gil() {
4734        Python::initialize();
4735
4736        let node = LiveNode::builder(TraderId::from("TESTER-002"), Environment::Sandbox)
4737            .unwrap()
4738            .with_reconciliation(false)
4739            .with_delay_post_stop_secs(1)
4740            .with_timeout_connection(1)
4741            .build()
4742            .map(PyLiveNode::new)
4743            .unwrap();
4744
4745        get_runtime()
4746            .block_on(async { node.node_mut().unwrap().start().await })
4747            .expect("node should start");
4748
4749        let (attempt_tx, attempt_rx) = mpsc::channel();
4750        let acquired_before_stop_return = Arc::new(AtomicBool::new(false));
4751        let acquired_before_stop_return_for_thread = acquired_before_stop_return.clone();
4752        let stop_returned = Arc::new(AtomicBool::new(false));
4753        let stop_returned_for_thread = stop_returned.clone();
4754        let mut gil_thread = None;
4755
4756        Python::attach(|py| {
4757            gil_thread = Some(thread::spawn(move || {
4758                attempt_tx
4759                    .send(())
4760                    .expect("GIL acquisition attempt should send");
4761                Python::attach(|_| {});
4762
4763                if !stop_returned_for_thread.load(Ordering::SeqCst) {
4764                    acquired_before_stop_return_for_thread.store(true, Ordering::SeqCst);
4765                }
4766            }));
4767
4768            attempt_rx
4769                .recv_timeout(Duration::from_secs(1))
4770                .expect("worker thread should attempt to acquire the GIL");
4771
4772            super::stop_live_node_detached(py, &mut node.node_mut().unwrap())
4773                .expect("node should stop cleanly");
4774            stop_returned.store(true, Ordering::SeqCst);
4775        });
4776
4777        gil_thread
4778            .expect("GIL worker thread should be spawned")
4779            .join()
4780            .expect("GIL worker thread should join");
4781
4782        assert!(
4783            acquired_before_stop_return.load(Ordering::SeqCst),
4784            "worker thread should acquire the GIL while LiveNode::stop is blocked"
4785        );
4786        assert!(!node.node_mut().unwrap().is_running());
4787    }
4788
4789    #[rstest]
4790    fn test_py_dispose_disposes_kernel_after_stop_error() {
4791        Python::initialize();
4792
4793        let dispose_count = Arc::new(AtomicUsize::new(0));
4794        let factory = TestDisconnectFailureDataClientFactory::new(dispose_count.clone());
4795        let config = TestDataClientConfig;
4796        let node = LiveNode::builder(TraderId::from("TESTER-003"), Environment::Sandbox)
4797            .unwrap()
4798            .with_reconciliation(false)
4799            .with_delay_post_stop_secs(0)
4800            .with_timeout_connection(1)
4801            .with_timeout_disconnection_secs(0)
4802            .add_data_client(
4803                Some("TEST_DISCONNECT_FAILURE".to_string()),
4804                Box::new(factory),
4805                Box::new(config),
4806            )
4807            .unwrap()
4808            .build()
4809            .map(PyLiveNode::new)
4810            .unwrap();
4811
4812        let dispose_result = Python::attach(|py| {
4813            get_runtime()
4814                .block_on(async { node.node_mut().unwrap().start().await })
4815                .expect("node should start");
4816            assert!(node.node_mut().unwrap().is_running());
4817
4818            node.py_dispose(py)
4819        });
4820
4821        let error = dispose_result.expect_err("dispose should return the stop error");
4822
4823        assert!(
4824            error
4825                .to_string()
4826                .contains("Failed to disconnect data clients: TEST_DISCONNECT_FAILURE")
4827        );
4828        assert!(!error.to_string().contains("test disconnect failed"));
4829        assert_eq!(dispose_count.load(Ordering::Relaxed), 1);
4830        assert!(!node.node_mut().unwrap().is_running());
4831    }
4832
4833    #[rstest]
4834    fn test_live_node_pystrategy_timer_callbacks_run_on_event_loop() {
4835        Python::initialize();
4836
4837        let module_name = "test_live_node_timer_strategy";
4838        Python::attach(|py| install_timer_strategy_module(py, module_name));
4839
4840        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
4841            .unwrap()
4842            .with_reconciliation(false)
4843            .with_delay_post_stop_secs(0)
4844            .with_timeout_connection(1)
4845            .build()
4846            .map(PyLiveNode::new)
4847            .unwrap();
4848
4849        let importable = ImportableStrategyConfig {
4850            strategy_path: format!("{module_name}:LiveTimerStrategy"),
4851            config_path: String::new(),
4852            config: HashMap::new(),
4853        };
4854
4855        Python::attach(|py| {
4856            node.py_add_strategy_from_config(py, importable)
4857                .expect("strategy should register");
4858        });
4859
4860        let handle = node.node_mut().unwrap().handle();
4861        let stop_handle = handle.clone();
4862        let watchdog_handle = handle;
4863        let (done_tx, done_rx) = mpsc::channel();
4864        let module_name_for_stop = module_name.to_string();
4865
4866        let stop_thread = thread::spawn(move || {
4867            let deadline = Instant::now() + Duration::from_secs(5);
4868
4869            loop {
4870                let fired = Python::attach(|py| {
4871                    let results = get_timer_results(py, &module_name_for_stop);
4872                    results.callback_timer_count > 0 && results.default_timer_count > 0
4873                });
4874
4875                if fired || Instant::now() >= deadline {
4876                    break;
4877                }
4878
4879                thread::sleep(Duration::from_millis(20));
4880            }
4881
4882            stop_handle.stop();
4883        });
4884
4885        let watchdog_thread = thread::spawn(move || {
4886            if done_rx.recv_timeout(Duration::from_secs(5)).is_err() {
4887                watchdog_handle.stop();
4888            }
4889        });
4890
4891        Python::attach(|py| {
4892            super::run_live_node_detached(py, &mut node.node_mut().unwrap())
4893                .expect("node should run cleanly");
4894        });
4895
4896        let _ = done_tx.send(());
4897        stop_thread.join().expect("stop thread should join");
4898        watchdog_thread.join().expect("watchdog thread should join");
4899
4900        let results = Python::attach(|py| get_timer_results(py, module_name));
4901
4902        assert_eq!(results.on_start, 1);
4903        assert!(results.callback_timer_count > 0);
4904        assert!(results.default_timer_count > 0);
4905        assert_eq!(results.callback_event_type, "TimeEvent");
4906        assert_eq!(results.default_event_type, "TimeEvent");
4907        assert_eq!(results.callback_event_name, "explicit_timer");
4908        assert_eq!(results.default_event_name, "default_timer");
4909    }
4910
4911    #[rstest]
4912    fn test_add_actor_registers_constructed_python_instance() {
4913        Python::initialize();
4914
4915        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
4916            .unwrap()
4917            .with_reconciliation(false)
4918            .with_delay_post_stop_secs(0)
4919            .with_timeout_connection(1)
4920            .build()
4921            .map(PyLiveNode::new)
4922            .unwrap();
4923        let actor_id = ActorId::from("ACTOR-INSTANCE-001");
4924
4925        Python::attach(|py| {
4926            let config = py
4927                .eval(c_str!("type('_Cfg', (), {})()"), None, None)
4928                .unwrap();
4929            config.setattr("actor_id", actor_id.to_string()).unwrap();
4930            let actor = py
4931                .get_type::<PyDataActor>()
4932                .as_any()
4933                .call1((config,))
4934                .unwrap();
4935
4936            node.py_add_actor(&actor).expect("actor should register");
4937
4938            let actor = actor.extract::<PyRef<PyDataActor>>().unwrap();
4939            assert_eq!(actor.actor_id(), actor_id);
4940            assert!(actor.is_registered());
4941        });
4942
4943        assert_eq!(
4944            node.node_mut()
4945                .unwrap()
4946                .kernel()
4947                .trader
4948                .borrow()
4949                .actor_ids(),
4950            vec![actor_id]
4951        );
4952    }
4953
4954    #[rstest]
4955    fn test_add_actor_rejects_non_idle_node() {
4956        Python::initialize();
4957
4958        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
4959            .unwrap()
4960            .with_reconciliation(false)
4961            .with_delay_post_stop_secs(0)
4962            .with_timeout_connection(1)
4963            .build()
4964            .map(PyLiveNode::new)
4965            .unwrap();
4966
4967        Python::attach(|py| {
4968            let actor = py.get_type::<PyDataActor>().call0().unwrap();
4969            node.handle.set_starting();
4970
4971            let error = node
4972                .py_add_actor(&actor)
4973                .expect_err("a non-idle node should reject actor registration");
4974            let actor = actor.extract::<PyRef<PyDataActor>>().unwrap();
4975
4976            assert_eq!(
4977                error.to_string(),
4978                "RuntimeError: Cannot add actor while node is running, add actors before running the node"
4979            );
4980            assert!(!actor.is_registered());
4981        });
4982
4983        assert!(
4984            node.node()
4985                .unwrap()
4986                .kernel()
4987                .trader
4988                .borrow()
4989                .actor_ids()
4990                .is_empty()
4991        );
4992    }
4993
4994    #[rstest]
4995    #[case::python(false)]
4996    #[case::rust(true)]
4997    fn test_add_strategy_from_config_registers_external_order_instrument_ids(#[case] rust: bool) {
4998        Python::initialize();
4999
5000        let module_name = "test_live_node_claim_strategy";
5001        Python::attach(|py| install_claim_strategy_module(py, module_name));
5002
5003        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
5004            .unwrap()
5005            .with_reconciliation(false)
5006            .with_delay_post_stop_secs(0)
5007            .with_timeout_connection(1)
5008            .build()
5009            .map(PyLiveNode::new)
5010            .unwrap();
5011
5012        let instrument_id = InstrumentId::from("AUDUSD.SIM");
5013        let strategy_id = StrategyId::from("CLAIMS-001");
5014        let mut config = HashMap::new();
5015        config.insert(
5016            "strategy_id".to_string(),
5017            serde_json::json!(strategy_id.to_string()),
5018        );
5019        config.insert(
5020            "external_order_instrument_ids".to_string(),
5021            serde_json::json!([instrument_id.to_string()]),
5022        );
5023
5024        let importable = ImportableStrategyConfig {
5025            strategy_path: format!("{module_name}:ClaimsStrategy"),
5026            config_path: format!("{module_name}:ClaimsConfig"),
5027            config,
5028        };
5029
5030        if rust {
5031            node.node_mut()
5032                .unwrap()
5033                .add_python_strategy_from_config(&importable)
5034                .expect("strategy should register");
5035        } else {
5036            Python::attach(|py| {
5037                node.py_add_strategy_from_config(py, importable)
5038                    .expect("strategy should register");
5039            });
5040        }
5041
5042        {
5043            let guard = node.node_mut().unwrap();
5044            let exec_engine = guard.kernel().exec_engine.borrow();
5045            assert_eq!(
5046                guard.kernel().trader.borrow().strategy_ids(),
5047                vec![strategy_id]
5048            );
5049            assert_eq!(
5050                guard
5051                    .exec_manager()
5052                    .get_external_order_claim(&instrument_id),
5053                Some(strategy_id)
5054            );
5055            assert_eq!(
5056                exec_engine.get_external_order_claim(&instrument_id),
5057                Some(strategy_id)
5058            );
5059        }
5060
5061        let result = node
5062            .node_mut()
5063            .unwrap()
5064            .exec_manager_mut()
5065            .claim_external_orders(instrument_id, StrategyId::from("OTHER-001"));
5066
5067        assert!(result.is_err());
5068        assert!(
5069            result
5070                .unwrap_err()
5071                .to_string()
5072                .contains("already exists for CLAIMS-001")
5073        );
5074    }
5075
5076    #[rstest]
5077    #[case::rust_native(true, "NativeAlgorithm")]
5078    #[case::python_native(false, "NativeAlgorithm")]
5079    #[case::rust_actor(true, "ActorAlgorithm")]
5080    #[case::python_actor(false, "ActorAlgorithm")]
5081    fn test_add_exec_algorithm_from_config_registers_id(
5082        #[case] rust: bool,
5083        #[case] class: &str,
5084        #[values(false, true)] log_events: bool,
5085    ) {
5086        Python::initialize();
5087        let name = "test_live_importable_exec_algorithm";
5088        Python::attach(|py| install_exec_algorithm_module(py, name));
5089        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
5090            .unwrap()
5091            .with_reconciliation(false)
5092            .build()
5093            .map(PyLiveNode::new)
5094            .unwrap();
5095
5096        let config = ImportableExecutionAlgorithmConfig {
5097            exec_algorithm_path: format!("{name}:{class}"),
5098            config_path: format!("{name}:AlgorithmConfig"),
5099            config: HashMap::from([
5100                (
5101                    "exec_algorithm_id".to_string(),
5102                    serde_json::json!("HOST-ALGO"),
5103                ),
5104                ("actor_id".to_string(), serde_json::json!("FALLBACK-ACTOR")),
5105                ("log_events".to_string(), serde_json::json!(log_events)),
5106                ("log_commands".to_string(), serde_json::json!(!log_events)),
5107            ]),
5108        };
5109
5110        let register = || {
5111            if rust {
5112                node.node_mut()
5113                    .unwrap()
5114                    .add_python_exec_algorithm_from_config(&config)
5115            } else {
5116                Python::attach(|py| node.py_add_exec_algorithm_from_config(py, config.clone()))
5117            }
5118        };
5119
5120        register().unwrap();
5121        let error = register().unwrap_err();
5122
5123        let flags = Python::attach(|py| {
5124            let wrapper = get_python_wrapper(ExecAlgorithmId::from("HOST-ALGO").into()).unwrap();
5125            if class == "NativeAlgorithm" {
5126                let algorithm = wrapper.extract::<PyRef<PyExecutionAlgorithm>>(py).unwrap();
5127                let config = DataActor::config(&*algorithm);
5128                (config.log_events, config.log_commands)
5129            } else {
5130                let actor = wrapper.extract::<PyRef<PyDataActor>>(py).unwrap();
5131                let config = &actor.config;
5132                (config.log_events, config.log_commands)
5133            }
5134        });
5135
5136        let guard = node.node_mut().unwrap();
5137        let mut trader = guard.kernel().trader().borrow_mut();
5138        trader.start_components().unwrap();
5139        trader.stop_components().unwrap();
5140
5141        let callbacks = Python::attach(|py| {
5142            py.import(name)
5143                .unwrap()
5144                .getattr("callbacks")
5145                .unwrap()
5146                .extract::<Vec<String>>()
5147                .unwrap()
5148        });
5149
5150        assert_eq!(
5151            trader.exec_algorithm_ids(),
5152            vec![ExecAlgorithmId::from("HOST-ALGO")]
5153        );
5154        assert!(trader.actor_ids().is_empty());
5155        assert_eq!(
5156            error.to_string(),
5157            "RuntimeError: Execution algorithm 'HOST-ALGO' is already registered"
5158        );
5159        assert_eq!(callbacks, vec!["start", "stop"]);
5160        assert_eq!(flags, (log_events, !log_events));
5161    }
5162
5163    #[rstest]
5164    fn test_add_python_exec_algorithm_from_config_rejects_invalid_path() {
5165        Python::initialize();
5166        let mut node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
5167            .unwrap()
5168            .with_reconciliation(false)
5169            .build()
5170            .unwrap();
5171
5172        let config = ImportableExecutionAlgorithmConfig {
5173            exec_algorithm_path: "missing_separator".to_string(),
5174            config_path: String::new(),
5175            config: HashMap::new(),
5176        };
5177
5178        let error = node
5179            .add_python_exec_algorithm_from_config(&config)
5180            .unwrap_err();
5181
5182        assert_eq!(
5183            error.to_string(),
5184            "ValueError: exec_algorithm_path must be in format 'module.path:ClassName'"
5185        );
5186        assert!(
5187            node.kernel()
5188                .trader()
5189                .borrow()
5190                .exec_algorithm_ids()
5191                .is_empty()
5192        );
5193    }
5194
5195    #[rstest]
5196    #[case::native("NativeAlgorithm", false)]
5197    #[case::actor("ActorAlgorithm", true)]
5198    fn test_add_exec_algorithm_from_config_preserves_non_idle_registration(
5199        #[case] class: &str,
5200        #[case] accepted: bool,
5201    ) {
5202        Python::initialize();
5203        let name = "test_non_idle_exec_algorithm";
5204        Python::attach(|py| install_exec_algorithm_module(py, name));
5205        let mut node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
5206            .unwrap()
5207            .with_reconciliation(false)
5208            .build()
5209            .unwrap();
5210        node.handle().set_starting();
5211
5212        let config = ImportableExecutionAlgorithmConfig {
5213            exec_algorithm_path: format!("{name}:{class}"),
5214            config_path: format!("{name}:AlgorithmConfig"),
5215            config: HashMap::from([("actor_id".to_string(), serde_json::json!("ACTOR-FALLBACK"))]),
5216        };
5217
5218        let result = node.add_python_exec_algorithm_from_config(&config);
5219        let ids = node.kernel().trader().borrow().exec_algorithm_ids();
5220
5221        assert_eq!(node.state(), NodeState::Starting);
5222
5223        if accepted {
5224            result.unwrap();
5225            assert_eq!(ids, vec![ExecAlgorithmId::from("ACTOR-FALLBACK")]);
5226        } else {
5227            assert_eq!(
5228                result.unwrap_err().to_string(),
5229                "RuntimeError: Cannot add exec algorithm while node is running, add exec algorithms before running the node"
5230            );
5231            assert!(ids.is_empty());
5232        }
5233    }
5234
5235    #[rstest]
5236    #[tokio::test(flavor = "current_thread")]
5237    async fn test_add_exec_algorithm_from_config_rejects_running_before_import() {
5238        Python::initialize();
5239        let mut node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
5240            .unwrap()
5241            .with_reconciliation(false)
5242            .build()
5243            .unwrap();
5244
5245        let config = ImportableExecutionAlgorithmConfig {
5246            exec_algorithm_path: "must_not_import:Algorithm".to_string(),
5247            config_path: String::new(),
5248            config: HashMap::new(),
5249        };
5250
5251        node.start().await.unwrap();
5252        let running_state = node.state();
5253
5254        let error = node
5255            .add_python_exec_algorithm_from_config(&config)
5256            .unwrap_err();
5257        let ids = node.kernel().trader().borrow().exec_algorithm_ids();
5258        node.stop().await.unwrap();
5259
5260        assert_eq!(running_state, NodeState::Running);
5261        assert_eq!(
5262            error.to_string(),
5263            "RuntimeError: Cannot add exec algorithm while node is running"
5264        );
5265        assert!(ids.is_empty());
5266        assert_eq!(node.state(), NodeState::Stopped);
5267    }
5268
5269    #[rstest]
5270    #[case::native("NoConfigNativeAlgorithm")]
5271    #[case::actor("NoConfigActorAlgorithm")]
5272    fn test_add_exec_algorithm_from_config_without_config(#[case] class: &str) {
5273        Python::initialize();
5274        let name = "test_no_config_exec_algorithm";
5275        Python::attach(|py| install_exec_algorithm_module(py, name));
5276        let mut node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
5277            .unwrap()
5278            .with_reconciliation(false)
5279            .build()
5280            .unwrap();
5281
5282        let config = ImportableExecutionAlgorithmConfig {
5283            exec_algorithm_path: format!("{name}:{class}"),
5284            config_path: String::new(),
5285            config: HashMap::new(),
5286        };
5287
5288        node.add_python_exec_algorithm_from_config(&config).unwrap();
5289
5290        assert_eq!(
5291            node.kernel().trader().borrow().exec_algorithm_ids(),
5292            vec![ExecAlgorithmId::from(class)]
5293        );
5294        assert!(node.kernel().trader().borrow().actor_ids().is_empty());
5295    }
5296
5297    #[rstest]
5298    #[case::exec_id(c_str!("ExecAlgorithmId('PRIMARY')"), c_str!("ActorId('SECONDARY')"), Ok(Some("PRIMARY")))]
5299    #[case::actor_id(c_str!("ActorId('PRIMARY')"), c_str!("None"), Ok(Some("PRIMARY")))]
5300    #[case::string_id(c_str!("'PRIMARY'"), c_str!("None"), Ok(Some("PRIMARY")))]
5301    #[case::fallback(c_str!("None"), c_str!("ActorId('SECONDARY')"), Ok(Some("SECONDARY")))]
5302    #[case::no_id(c_str!("None"), c_str!("None"), Ok(None))]
5303    #[case::invalid(c_str!("42"), c_str!("ActorId('SECONDARY')"), Err("Invalid `exec_algorithm_id`/`actor_id` type"))]
5304    fn test_extract_exec_algorithm_actor_id(
5305        #[case] primary: &CStr,
5306        #[case] fallback: &CStr,
5307        #[case] expected: Result<Option<&str>, &str>,
5308    ) {
5309        Python::initialize();
5310        Python::attach(|py| {
5311            let globals = PyDict::new(py);
5312            globals
5313                .set_item("ExecAlgorithmId", py.get_type::<ExecAlgorithmId>())
5314                .unwrap();
5315            globals
5316                .set_item("ActorId", py.get_type::<ActorId>())
5317                .unwrap();
5318            let config = py
5319                .import("types")
5320                .unwrap()
5321                .getattr("SimpleNamespace")
5322                .unwrap()
5323                .call0()
5324                .unwrap();
5325            config
5326                .setattr(
5327                    "exec_algorithm_id",
5328                    py.eval(primary, Some(&globals), None).unwrap(),
5329                )
5330                .unwrap();
5331            config
5332                .setattr("actor_id", py.eval(fallback, Some(&globals), None).unwrap())
5333                .unwrap();
5334
5335            let actual = extract_exec_algorithm_actor_id(&config)
5336                .map(|id| id.map(|id| id.to_string()))
5337                .map_err(|e| e.to_string());
5338
5339            assert_eq!(
5340                actual,
5341                expected
5342                    .map(|id| id.map(str::to_string))
5343                    .map_err(str::to_string)
5344            );
5345        });
5346    }
5347
5348    fn install_exec_algorithm_module(py: Python<'_>, name: &str) {
5349        let module = PyModule::new(py, name).unwrap();
5350        module
5351            .setattr("ExecutionAlgorithm", py.get_type::<PyExecutionAlgorithm>())
5352            .unwrap();
5353        module
5354            .setattr("DataActor", py.get_type::<PyDataActor>())
5355            .unwrap();
5356        py.run(
5357            c_str!(
5358                r#"
5359callbacks = []
5360
5361class AlgorithmConfig:
5362    def __init__(self, exec_algorithm_id=None, actor_id=None, log_events=False, log_commands=True):
5363        self.exec_algorithm_id = exec_algorithm_id
5364        self.actor_id = actor_id
5365        self.log_events = log_events
5366        self.log_commands = log_commands
5367
5368class NativeAlgorithm(ExecutionAlgorithm):
5369    def on_start(self):
5370        callbacks.append("start")
5371
5372    def on_stop(self):
5373        callbacks.append("stop")
5374
5375class ActorAlgorithm(DataActor):
5376    def on_start(self):
5377        callbacks.append("start")
5378
5379    def on_stop(self):
5380        callbacks.append("stop")
5381
5382class NoConfigNativeAlgorithm(NativeAlgorithm):
5383    def __init__(self):
5384        super().__init__()
5385
5386class NoConfigActorAlgorithm(ActorAlgorithm):
5387    def __init__(self):
5388        super().__init__()
5389"#
5390            ),
5391            Some(&module.dict()),
5392            None,
5393        )
5394        .unwrap();
5395        py.import("sys")
5396            .unwrap()
5397            .getattr("modules")
5398            .unwrap()
5399            .set_item(name, module)
5400            .unwrap();
5401    }
5402
5403    #[rstest]
5404    fn test_add_python_strategy_from_config_rejects_non_idle_node() {
5405        Python::initialize();
5406
5407        let mut node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
5408            .unwrap()
5409            .with_reconciliation(false)
5410            .build()
5411            .unwrap();
5412
5413        let config = ImportableStrategyConfig {
5414            strategy_path: "must_not_import:Strategy".to_string(),
5415            config_path: String::new(),
5416            config: HashMap::new(),
5417        };
5418
5419        node.handle().set_starting();
5420
5421        let error = node.add_python_strategy_from_config(&config).unwrap_err();
5422
5423        assert_eq!(
5424            error.to_string(),
5425            "RuntimeError: Cannot add strategy while node is running, add strategies before running the node"
5426        );
5427        assert_eq!(node.state(), NodeState::Starting);
5428        assert!(node.kernel().trader.borrow().strategy_ids().is_empty());
5429    }
5430
5431    #[rstest]
5432    fn test_add_python_strategy_from_config_claim_conflict_is_atomic() {
5433        Python::initialize();
5434
5435        let module_name = "test_rust_live_node_claim_conflict";
5436        Python::attach(|py| install_claim_strategy_module(py, module_name));
5437        let mut node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
5438            .unwrap()
5439            .with_reconciliation(false)
5440            .build()
5441            .unwrap();
5442        let existing_id = InstrumentId::from("AUDUSD.SIM");
5443        let new_id = InstrumentId::from("EURUSD.SIM");
5444        let existing_strategy = StrategyId::from("EXISTING-001");
5445        node.register_external_order_claims(existing_strategy, &[existing_id])
5446            .unwrap();
5447        let mut config = HashMap::new();
5448        config.insert(
5449            "strategy_id".to_string(),
5450            serde_json::json!("CANDIDATE-002"),
5451        );
5452        config.insert(
5453            "external_order_instrument_ids".to_string(),
5454            serde_json::json!([new_id.to_string(), existing_id.to_string()]),
5455        );
5456
5457        let importable = ImportableStrategyConfig {
5458            strategy_path: format!("{module_name}:ClaimsStrategy"),
5459            config_path: format!("{module_name}:ClaimsConfig"),
5460            config,
5461        };
5462
5463        let error = node
5464            .add_python_strategy_from_config(&importable)
5465            .unwrap_err();
5466        let engine = node.kernel().exec_engine.borrow();
5467
5468        assert!(
5469            error
5470                .to_string()
5471                .contains("already exists for EXISTING-001")
5472        );
5473        assert!(node.kernel().trader.borrow().strategy_ids().is_empty());
5474        assert_eq!(node.exec_manager().get_external_order_claim(&new_id), None);
5475        assert_eq!(engine.get_external_order_claim(&new_id), None);
5476        assert_eq!(
5477            node.exec_manager().get_external_order_claim(&existing_id),
5478            Some(existing_strategy)
5479        );
5480        assert_eq!(
5481            engine.get_external_order_claim(&existing_id),
5482            Some(existing_strategy)
5483        );
5484    }
5485
5486    #[rstest]
5487    fn test_add_strategy_registers_constructed_python_instance() {
5488        Python::initialize();
5489
5490        let module_name = "test_live_node_add_strategy_instance";
5491        Python::attach(|py| install_claim_strategy_module(py, module_name));
5492
5493        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
5494            .unwrap()
5495            .with_reconciliation(false)
5496            .with_delay_post_stop_secs(0)
5497            .with_timeout_connection(1)
5498            .build()
5499            .map(PyLiveNode::new)
5500            .unwrap();
5501
5502        let instrument_id = InstrumentId::from("AUDUSD.SIM");
5503        let strategy_id = StrategyId::from("CLAIMS-002");
5504
5505        Python::attach(|py| {
5506            let module = py.import(module_name).expect("test module should import");
5507            let kwargs = PyDict::new(py);
5508            kwargs
5509                .set_item("strategy_id", strategy_id.to_string())
5510                .unwrap();
5511            kwargs
5512                .set_item(
5513                    "external_order_instrument_ids",
5514                    vec![instrument_id.to_string()],
5515                )
5516                .unwrap();
5517            let config = module
5518                .getattr("ClaimsConfig")
5519                .unwrap()
5520                .call((), Some(&kwargs))
5521                .unwrap();
5522            let strategy = module
5523                .getattr("ClaimsStrategy")
5524                .unwrap()
5525                .call1((config,))
5526                .unwrap();
5527
5528            node.py_add_strategy(&strategy)
5529                .expect("strategy should register");
5530        });
5531
5532        {
5533            let guard = node.node_mut().unwrap();
5534            let exec_engine = guard.kernel().exec_engine.borrow();
5535            assert_eq!(
5536                exec_engine.get_external_order_claim(&instrument_id),
5537                Some(strategy_id)
5538            );
5539        }
5540    }
5541
5542    #[rstest]
5543    fn test_add_strategy_constructed_python_instance_registers_oms_type() {
5544        Python::initialize();
5545
5546        let module_name = "test_live_node_add_strategy_instance_oms_type";
5547        Python::attach(|py| install_claim_strategy_module(py, module_name));
5548
5549        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
5550            .unwrap()
5551            .with_reconciliation(false)
5552            .with_delay_post_stop_secs(0)
5553            .with_timeout_connection(1)
5554            .build()
5555            .map(PyLiveNode::new)
5556            .unwrap();
5557        let strategy_id = StrategyId::from("FUNDING_ARBITRAGE-003");
5558
5559        Python::attach(|py| {
5560            let module = py.import(module_name).expect("test module should import");
5561            let kwargs = PyDict::new(py);
5562            kwargs
5563                .set_item("strategy_id", strategy_id.to_string())
5564                .unwrap();
5565            kwargs.set_item("oms_type", OmsType::Hedging).unwrap();
5566            let config = module
5567                .getattr("ClaimsConfig")
5568                .unwrap()
5569                .call((), Some(&kwargs))
5570                .unwrap();
5571            let strategy = module
5572                .getattr("ClaimsStrategy")
5573                .unwrap()
5574                .call1((config,))
5575                .unwrap();
5576
5577            node.py_add_strategy(&strategy)
5578                .expect("strategy should register");
5579        });
5580
5581        let instrument = crypto_perpetual_ethusdt();
5582        let instrument_id = instrument.id();
5583        let client_id = ClientId::from("STUB");
5584
5585        node.node_mut()
5586            .unwrap()
5587            .kernel()
5588            .cache
5589            .borrow_mut()
5590            .add_instrument(InstrumentAny::CryptoPerpetual(instrument))
5591            .unwrap();
5592        node.node_mut()
5593            .unwrap()
5594            .kernel()
5595            .exec_engine
5596            .borrow_mut()
5597            .register_client(Box::new(StubExecutionClient::new(
5598                client_id,
5599                AccountId::from("TEST-ACCOUNT"),
5600                instrument_id.venue,
5601                OmsType::Netting,
5602                None,
5603            )))
5604            .unwrap();
5605
5606        let order = OrderTestBuilder::new(OrderType::Market)
5607            .trader_id(node.node_mut().unwrap().trader_id())
5608            .strategy_id(strategy_id)
5609            .instrument_id(instrument_id)
5610            .quantity(Quantity::from("1.000"))
5611            .build();
5612        let position_id = PositionId::new("CUSTOM-POSITION-003");
5613
5614        node.node_mut()
5615            .unwrap()
5616            .kernel()
5617            .cache
5618            .borrow_mut()
5619            .add_order(order.clone(), Some(position_id), Some(client_id), true)
5620            .unwrap();
5621
5622        let submit_order = SubmitOrder::new(
5623            order.trader_id(),
5624            Some(client_id),
5625            strategy_id,
5626            instrument_id,
5627            order.client_order_id(),
5628            order.init_event().clone(),
5629            order.exec_algorithm_id(),
5630            Some(position_id),
5631            None,
5632            UUID4::new(),
5633            UnixNanos::default(),
5634            None,
5635        );
5636
5637        node.node_mut()
5638            .unwrap()
5639            .kernel()
5640            .exec_engine
5641            .borrow()
5642            .execute(TradingCommand::SubmitOrder(submit_order));
5643
5644        let guard = node.node_mut().unwrap();
5645        let exec_engine = guard.kernel().exec_engine.borrow();
5646        let cache = exec_engine.cache().borrow();
5647        let cached_order = cache
5648            .order(&order.client_order_id())
5649            .expect("Order should be cached");
5650
5651        assert_eq!(cached_order.status(), OrderStatus::Initialized);
5652    }
5653
5654    #[rstest]
5655    fn test_add_strategy_constructed_python_instance_claim_conflict_does_not_register() {
5656        Python::initialize();
5657
5658        let module_name = "test_live_node_add_strategy_instance_claim_conflict";
5659        Python::attach(|py| install_claim_strategy_module(py, module_name));
5660
5661        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
5662            .unwrap()
5663            .with_reconciliation(false)
5664            .with_delay_post_stop_secs(0)
5665            .with_timeout_connection(1)
5666            .build()
5667            .map(PyLiveNode::new)
5668            .unwrap();
5669        let instrument_id = InstrumentId::from("AUDUSD.SIM");
5670        let first_strategy_id = StrategyId::from("CLAIMS-PRIMARY-001");
5671        let conflicting_strategy_id = StrategyId::from("CLAIMS-CONFLICT-002");
5672
5673        let (error, conflicting_strategy_registered) = Python::attach(|py| {
5674            let module = py.import(module_name).expect("test module should import");
5675            let first_kwargs = PyDict::new(py);
5676            first_kwargs
5677                .set_item("strategy_id", first_strategy_id.to_string())
5678                .unwrap();
5679            first_kwargs
5680                .set_item(
5681                    "external_order_instrument_ids",
5682                    vec![instrument_id.to_string()],
5683                )
5684                .unwrap();
5685            let first_config = module
5686                .getattr("ClaimsConfig")
5687                .unwrap()
5688                .call((), Some(&first_kwargs))
5689                .unwrap();
5690            let first_strategy = module
5691                .getattr("ClaimsStrategy")
5692                .unwrap()
5693                .call1((first_config,))
5694                .unwrap();
5695            node.py_add_strategy(&first_strategy)
5696                .expect("first strategy should register");
5697
5698            let conflicting_kwargs = PyDict::new(py);
5699            conflicting_kwargs
5700                .set_item("strategy_id", conflicting_strategy_id.to_string())
5701                .unwrap();
5702            conflicting_kwargs
5703                .set_item(
5704                    "external_order_instrument_ids",
5705                    vec![instrument_id.to_string()],
5706                )
5707                .unwrap();
5708            let conflicting_config = module
5709                .getattr("ClaimsConfig")
5710                .unwrap()
5711                .call((), Some(&conflicting_kwargs))
5712                .unwrap();
5713            let conflicting_strategy = module
5714                .getattr("ClaimsStrategy")
5715                .unwrap()
5716                .call1((conflicting_config,))
5717                .unwrap();
5718            let error = node
5719                .py_add_strategy(&conflicting_strategy)
5720                .expect_err("conflicting claim should fail");
5721            let is_registered = conflicting_strategy
5722                .extract::<PyRef<PyStrategy>>()
5723                .unwrap()
5724                .is_registered();
5725
5726            (error, is_registered)
5727        });
5728
5729        let strategy_ids = node
5730            .node_mut()
5731            .unwrap()
5732            .kernel()
5733            .trader
5734            .borrow()
5735            .strategy_ids();
5736        let manager_claim = node
5737            .node_mut()
5738            .unwrap()
5739            .exec_manager()
5740            .get_external_order_claim(&instrument_id);
5741        let engine_claim = node
5742            .node_mut()
5743            .unwrap()
5744            .kernel()
5745            .exec_engine
5746            .borrow()
5747            .get_external_order_claim(&instrument_id);
5748
5749        assert!(
5750            error
5751                .to_string()
5752                .contains("already exists for CLAIMS-PRIMARY-001")
5753        );
5754        assert!(!conflicting_strategy_registered);
5755        assert_eq!(strategy_ids, vec![first_strategy_id]);
5756        assert_eq!(manager_claim, Some(first_strategy_id));
5757        assert_eq!(engine_claim, Some(first_strategy_id));
5758    }
5759
5760    #[rstest]
5761    fn test_add_strategy_constructed_python_instance_duplicate_tag_does_not_register() {
5762        Python::initialize();
5763
5764        let module_name = "test_live_node_add_strategy_instance_duplicate_tag";
5765        Python::attach(|py| install_claim_strategy_module(py, module_name));
5766
5767        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
5768            .unwrap()
5769            .with_reconciliation(false)
5770            .with_delay_post_stop_secs(0)
5771            .with_timeout_connection(1)
5772            .build()
5773            .map(PyLiveNode::new)
5774            .unwrap();
5775        let first_strategy_id = StrategyId::from("TAGGED-FIRST-777");
5776        let instrument_id = InstrumentId::from("AUDUSD.SIM");
5777
5778        let (error, duplicate_strategy_registered) = Python::attach(|py| {
5779            let module = py.import(module_name).expect("test module should import");
5780            let first_kwargs = PyDict::new(py);
5781            first_kwargs
5782                .set_item("strategy_id", "TAGGED-FIRST")
5783                .unwrap();
5784            first_kwargs.set_item("order_id_tag", "777").unwrap();
5785            let first_config = module
5786                .getattr("ClaimsConfig")
5787                .unwrap()
5788                .call((), Some(&first_kwargs))
5789                .unwrap();
5790            let first_strategy = module
5791                .getattr("ClaimsStrategy")
5792                .unwrap()
5793                .call1((first_config,))
5794                .unwrap();
5795            node.py_add_strategy(&first_strategy)
5796                .expect("first strategy should register");
5797
5798            let duplicate_kwargs = PyDict::new(py);
5799            duplicate_kwargs
5800                .set_item("strategy_id", "TAGGED-SECOND")
5801                .unwrap();
5802            duplicate_kwargs.set_item("order_id_tag", "777").unwrap();
5803            duplicate_kwargs
5804                .set_item(
5805                    "external_order_instrument_ids",
5806                    vec![instrument_id.to_string()],
5807                )
5808                .unwrap();
5809            let duplicate_config = module
5810                .getattr("ClaimsConfig")
5811                .unwrap()
5812                .call((), Some(&duplicate_kwargs))
5813                .unwrap();
5814            let duplicate_strategy = module
5815                .getattr("ClaimsStrategy")
5816                .unwrap()
5817                .call1((duplicate_config,))
5818                .unwrap();
5819            let error = node
5820                .py_add_strategy(&duplicate_strategy)
5821                .expect_err("duplicate order ID tag should fail");
5822            let is_registered = duplicate_strategy
5823                .extract::<PyRef<PyStrategy>>()
5824                .unwrap()
5825                .is_registered();
5826
5827            (error, is_registered)
5828        });
5829
5830        let strategy_ids = node
5831            .node_mut()
5832            .unwrap()
5833            .kernel()
5834            .trader
5835            .borrow()
5836            .strategy_ids();
5837
5838        assert!(error.to_string().contains("order_id_tag conflict"));
5839        assert!(!duplicate_strategy_registered);
5840        assert_eq!(strategy_ids, vec![first_strategy_id]);
5841        assert_eq!(
5842            node.node_mut()
5843                .unwrap()
5844                .kernel()
5845                .cache
5846                .borrow()
5847                .external_order_claim(&instrument_id),
5848            None
5849        );
5850    }
5851
5852    #[tokio::test(flavor = "current_thread")]
5853    async fn test_live_node_pystrategy_request_bars_dispatches_on_historical_bars() {
5854        Python::initialize();
5855
5856        let module_name = "test_live_node_historical_bars_strategy";
5857        Python::attach(|py| install_tracking_strategy_module(py, module_name));
5858
5859        let request_count = Arc::new(AtomicUsize::new(0));
5860        let response_sent_count = Arc::new(AtomicUsize::new(0));
5861        let handler_visible_count = Arc::new(AtomicUsize::new(0));
5862
5863        let factory = TestHistoricalBarsDataClientFactory::new(
5864            request_count.clone(),
5865            response_sent_count.clone(),
5866            handler_visible_count.clone(),
5867        );
5868        let config = TestDataClientConfig;
5869
5870        let node = LiveNode::builder(TraderId::from("TESTER-001"), Environment::Sandbox)
5871            .unwrap()
5872            .with_reconciliation(false)
5873            .with_delay_post_stop_secs(0)
5874            .with_timeout_connection(1)
5875            .add_data_client(
5876                Some("TEST_DATA".to_string()),
5877                Box::new(factory),
5878                Box::new(config),
5879            )
5880            .unwrap()
5881            .build()
5882            .map(PyLiveNode::new)
5883            .unwrap();
5884
5885        let importable = ImportableStrategyConfig {
5886            strategy_path: format!("{module_name}:HistoricalBarsStrategy"),
5887            config_path: String::new(),
5888            config: HashMap::new(),
5889        };
5890
5891        Python::attach(|py| {
5892            node.py_add_strategy_from_config(py, importable)
5893                .expect("strategy should register");
5894        });
5895
5896        let stop_handle = node.node_mut().unwrap().handle();
5897
5898        let driver = async {
5899            wait_until_async(
5900                || async { Python::attach(|py| get_results(py, module_name).1 == 1) },
5901                Duration::from_secs(3),
5902            )
5903            .await;
5904            stop_handle.stop();
5905        };
5906
5907        {
5908            let mut live_node = node.node_mut().unwrap();
5909
5910            let (result, ()) = tokio::time::timeout(Duration::from_secs(5), async {
5911                tokio::join!(live_node.run(), driver)
5912            })
5913            .await
5914            .expect("historical bars callback completes before shutdown");
5915
5916            result.expect("node should run cleanly");
5917        }
5918
5919        let (on_start, on_historical_bars, historical_bar_count) =
5920            Python::attach(|py| get_results(py, module_name));
5921
5922        assert_eq!(request_count.load(Ordering::Relaxed), 1);
5923        assert_eq!(handler_visible_count.load(Ordering::Relaxed), 1);
5924        assert_eq!(response_sent_count.load(Ordering::Relaxed), 1);
5925        assert_eq!(on_start, 1);
5926        assert_eq!(on_historical_bars, 1);
5927        assert_eq!(historical_bar_count, 1);
5928    }
5929}