simulator-client 0.8.0

//! Ergonomic async client for the simulator backtest WebSocket API.
//!
//! This wraps the `simulator-api` request/response protocol with helpers for common
//! workflows (create session, wait ready, continue/advance, close), while still allowing full
//! access to raw `BacktestRequest` / `BacktestResponse` when needed.
//!
//! ## Quickstart
//! ```no_run
//! use std::time::Duration;
//!
//! use simulator_client::{BacktestClient, Continue, CreateSession};
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! let client = BacktestClient::builder()
//!     .url("ws://localhost:8900/backtest")
//!     .api_key("local-dev-key")
//!     .build();
//!
//! let mut session = client
//!     .create_session(
//!         CreateSession::builder()
//!             .start_slot(100)
//!             .slot_count(10)
//!             .build(),
//!     )
//!     .await?;
//!
//! session.ensure_ready(Some(Duration::from_secs(30))).await?;
//! session
//!     .continue_until_ready(
//!         Continue::builder().advance_count(1).build(),
//!         None,
//!         |_| {},
//!     )
//!     .await?;
//! session.close(Some(Duration::from_secs(10))).await?;
//! # Ok(()) }
//! ```
//!
//! ## Lifecycle notes
//! - `BacktestClient::create_session` sends `CreateBacktestSession` and waits for
//!   `SessionCreated`, buffering other responses until the session is ready.
//! - `BacktestSession::close` sends `CloseBacktestSession` and then closes the WebSocket.
//! - Dropping `BacktestSession` sends a best-effort WebSocket close frame if a Tokio runtime
//!   is available. Call `close` explicitly to ensure server-side session cleanup.
//! - `connect_timeout` governs the initial handshake; `request_timeout` applies to send/receive
//!   operations and can be overridden per call.
//! - For streaming workflows, use `BacktestSession::responses` (consumes the session) or
//!   `next_event` to keep readiness state in sync while consuming responses.

#![forbid(unsafe_code)]

mod builders;
mod client;
mod error;
pub mod injection;
pub mod managed;
mod ranges;
pub mod rpc;
mod session;
pub mod subscriptions;
mod transaction_step;
pub mod urls;

mod pnl;
pub use builders::{Continue, CreateSession, SerializeEncodeError};
pub use client::BacktestClient;
pub use error::{BacktestClientError, BacktestClientResult};
pub use injection::{ProgramModError, build_program_injection, modify_program_via_rpc};
pub use managed::{ControlEvent, ManagedBacktestSession, ManagedEvent, ManagedSessionError};
pub use pnl::report_agent_pnl;
pub use ranges::{RangeBound, filter_ranges};
pub use session::{
    AdvanceState, BacktestSession, ContinueResult, CoverageError, ReadyOutcome, SessionCoverage,
};
pub use simulator_api::{
    AvailableRange, DiscoveryFilter, split_range,
    usage::{ComputeTotals, SessionCounts, UsageReport},
};
pub use subscriptions::{
    AccountDiffContext, AccountDiffNotification, AccountDiffSubscriptionHandle,
    LogSubscriptionHandle, RoutedAccountDiffNotification, SubscriptionError, SubscriptionHandle,
    SubscriptionRuntimeError, subscribe_account_diffs, subscribe_account_diffs_many,
    subscribe_program_diffs, subscribe_program_logs,
};
pub use transaction_step::{DiscoveryPause, DiscoveryStepResult};
pub use urls::{UrlError, http_to_ws_url};