simulator_client/
lib.rs

1//! Ergonomic async client for the simulator backtest WebSocket API.
2//!
3//! This wraps the `simulator-api` request/response protocol with helpers for common
4//! workflows (create session, wait ready, continue/advance, close), while still allowing full
5//! access to raw `BacktestRequest` / `BacktestResponse` when needed.
6//!
7//! ## Quickstart
8//! ```no_run
9//! use std::time::Duration;
10//!
11//! use simulator_client::{BacktestClient, Continue, CreateSession};
12//!
13//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
14//! let client = BacktestClient::builder()
15//!     .url("ws://localhost:8900/backtest")
16//!     .api_key("local-dev-key")
17//!     .build();
18//!
19//! let mut session = client
20//!     .create_session(
21//!         CreateSession::builder()
22//!             .start_slot(100)
23//!             .slot_count(10)
24//!             .build(),
25//!     )
26//!     .await?;
27//!
28//! session.ensure_ready(Some(Duration::from_secs(30))).await?;
29//! session
30//!     .continue_until_ready(
31//!         Continue::builder().advance_count(1).build(),
32//!         None,
33//!         |_| {},
34//!     )
35//!     .await?;
36//! session.close(Some(Duration::from_secs(10))).await?;
37//! # Ok(()) }
38//! ```
39//!
40//! ## Lifecycle notes
41//! - `BacktestClient::create_session` sends `CreateBacktestSession` and waits for
42//!   `SessionCreated`, buffering other responses until the session is ready.
43//! - `BacktestSession::close` sends `CloseBacktestSession` and then closes the WebSocket.
44//! - Dropping `BacktestSession` sends a best-effort WebSocket close frame if a Tokio runtime
45//!   is available. Call `close` explicitly to ensure server-side session cleanup.
46//! - `connect_timeout` governs the initial handshake; `request_timeout` applies to send/receive
47//!   operations and can be overridden per call.
48//! - For streaming workflows, use `BacktestSession::responses` (consumes the session) or
49//!   `next_event` to keep readiness state in sync while consuming responses.
50
51#![forbid(unsafe_code)]
52
53mod builders;
54mod client;
55mod error;
56pub mod injection;
57mod ranges;
58pub mod rpc;
59mod session;
60pub mod subscriptions;
61mod transaction_step;
62pub mod urls;
63
64mod pnl;
65
66pub use builders::{Continue, CreateSession, SerializeEncodeError};
67pub use client::BacktestClient;
68pub use error::{BacktestClientError, BacktestClientResult};
69pub use injection::{ProgramModError, build_program_injection, modify_program_via_rpc};
70pub use pnl::report_agent_pnl;
71pub use ranges::{RangeBound, filter_ranges};
72pub use session::{
73    AdvanceState, BacktestSession, ContinueResult, CoverageError, ReadyOutcome, SessionCoverage,
74};
75pub use simulator_api::{AvailableRange, DiscoveryFilter, split_range};
76pub use subscriptions::{
77    AccountDiffContext, AccountDiffNotification, AccountDiffSubscriptionHandle,
78    LogSubscriptionHandle, RoutedAccountDiffNotification, SubscriptionError, SubscriptionHandle,
79    SubscriptionRuntimeError, subscribe_account_diffs, subscribe_account_diffs_many,
80    subscribe_program_diffs, subscribe_program_logs,
81};
82pub use transaction_step::{DiscoveryPause, DiscoveryStepResult};
83pub use urls::{UrlError, http_to_ws_url};
simulator_client/lib.rs

simulator_client/
lib.rs
