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 session;
58pub mod subscriptions;
59pub mod urls;
60
61pub use builders::{Continue, CreateSession, SerializeEncodeError};
62pub use client::BacktestClient;
63pub use error::{BacktestClientError, BacktestClientResult};
64pub use injection::{ProgramModError, build_program_injection};
65pub use session::{
66 AdvanceState, BacktestSession, ContinueResult, CoverageError, ReadyOutcome, SessionCoverage,
67};
68pub use simulator_api::{AvailableRange, split_range};
69pub use subscriptions::{LogSubscriptionHandle, SubscriptionError, subscribe_program_logs};
70pub use urls::{UrlError, http_to_ws_url};