rustrade_execution/client/

mod.rs

//! Execution client implementations for various exchanges.
//!
//! # Connector Comparison
//!
//! | Connector | Reconnect | Dedup | Fill Recovery | Ended-order Recovery | Heartbeat | Cancel answers once |
//! |-----------|-----------|-------|---------------|----------------------|-----------|---------------------|
//! | [`binance`] | Auto (1s→30s backoff) | 10k LRU | REST after reconnect | REST after reconnect | 30s | cancelled |
//! | [`alpaca`] | Auto (1s→30s backoff) | 2k LRU | REST after reconnect | REST after reconnect | 35s | accepted |
//! | [`ibkr`] | ibapi-managed | 10k LRU, fills only | Executions request after reconnect | None | N/A | submitted |
//! | [`hyperliquid`] | SDK-managed | 10k LRU, fills only | Venue snapshot on resubscribe | REST after reconnect | SDK-managed | cancelled |
//!
//! "Ended-order Recovery" is whether a reconnect reports how an order the client held as live
//! ended while the stream was down, and only those clients implement [`OrderStatusClient`]. The
//! last column is when [`ExecutionClient::cancel_order`] answers `Ok`. Only for "cancelled" has the
//! order ended by then; see that method.
//!
//! # Resilience Philosophy
//!
//! **WebSocket-based connectors** (Binance, Alpaca) implement auto-reconnection with
//! fill recovery and deduplication. After reconnect, they query REST APIs for missed
//! fills and deduplicate against the LRU cache to prevent duplicate processing.
//!
//! **IBKR** uses TCP to local TWS/Gateway. `ibapi` reconnects that socket itself; the
//! account stream stays open across it and recovers the missed fills from TWS's executions,
//! deduplicating against the LRU cache. Replacing a client that is gone for good requires IB
//! Gateway availability and client ID coordination — decisions that belong in the caller's
//! wrapper. See [`ibkr`] module docs for caller responsibilities.
//!
//! **Hyperliquid** delegates reconnection to the official SDK's `with_reconnect()` mechanism, but
//! deduplicates fills itself: the SDK resubscribes on reconnect and the venue opens a `userFills`
//! subscription with a snapshot, so every reconnect redelivers fills already seen. That snapshot
//! is the only fill recovery: it holds recent fills, how many Hyperliquid does not say, so callers
//! needing older ones call [`ExecutionClient::fetch_trades`], whose results are not deduplicated
//! against the stream. Once the snapshot has been sent on, a reconnect checks how the orders the
//! client holds as live ended, like Binance's and Alpaca's.
//!
//! # Known Limitations
//!
//! Only Binance (Spot and Margin), Alpaca and Hyperliquid (perpetuals and spot) recover the **order
//! lifecycle events** (cancelled, expired, rejected, a fill that completes an order) they missed
//! while disconnected, and only for the orders the client holds as live; IBKR recovers fills only
//! (#370). [`OrderStatusClient`] is the lookup that recovery is built on: given the orders a caller
//! still holds as live, it says how each that has ended did end. Binance Spot, Binance Margin,
//! Alpaca, both Hyperliquid clients and the mock client implement it.
//!
//! The engine closes part of that gap from the account snapshot each reconnect produces: an order a
//! complete list no longer shows is retired (see [`ExecutionClient::account_snapshot`]). That covers
//! the connectors whose snapshot declares its orders complete — Binance Spot and Margin,
//! Hyperliquid, Alpaca, and the mock venue — but not IBKR (#371), and it cannot tell how an order
//! ended. A caller that needs more reconciles against
//! [`ExecutionClient::fetch_open_orders`] after a reconnect.

use crate::{
    UnindexedAccountEvent, UnindexedAccountSnapshot,
    balance::AssetBalance,
    borrow_capacity::BorrowCapacity,
    error::UnindexedClientError,
    order::{
        Order, UnindexedInactiveOrder, UnindexedOrderKey,
        bracket::{BracketOrderRequest, BracketOrderResult},
        request::{OrderRequestCancel, OrderRequestOpen, UnindexedOrderResponseCancel},
        state::{Open, UnindexedOrderState},
    },
    shortability::Shortability,
    trade::TradesRead,
};
use chrono::{DateTime, Utc};
use futures::Stream;
use rustrade_instrument::{
    Side,
    asset::name::AssetNameExchange,
    exchange::ExchangeId,
    instrument::{kind::InstrumentKindDiscriminant, name::InstrumentNameExchange},
};
use std::future::Future;

// Account-event deduplication over rustrade's own event type. Gated on the clients that use it
// so a build selecting none of them does not compile it unused. Alpaca deduplicates too, but
// against a raw `SmolStr` fill key rather than this cache, so it is deliberately not in this list.
#[cfg(any(feature = "binance", feature = "hyperliquid", feature = "ibkr"))]
pub(crate) mod dedup;

// What a client knows of its live orders, and the reconnect check of how those orders ended while
// its account stream was down. Gated on the clients that use it, like `dedup`.
#[cfg(any(
    feature = "alpaca",
    feature = "binance",
    feature = "hyperliquid",
    feature = "ibkr"
))]
pub(crate) mod order_recovery;

// Alpaca ExecutionClient implementation (options, equities, crypto — single unified API)
#[cfg(feature = "alpaca")]
pub mod alpaca;

// Binance ExecutionClient implementations: Spot (live) and Cross Margin (identity/config scaffolding)
#[cfg(feature = "binance")]
pub mod binance;

// Hyperliquid perpetual futures and spot ExecutionClient implementations
#[cfg(feature = "hyperliquid")]
pub mod hyperliquid;

// Interactive Brokers ExecutionClient implementation (equities, futures, options, forex)
#[cfg(feature = "ibkr")]
pub mod ibkr;

pub mod mock;

/// An instrument an [`ExecutionClient`] is about to be built to trade, as
/// [`ExecutionClient::validate_config`] sees it.
///
/// `#[non_exhaustive]`, so further detail can be added without breaking an implementation that
/// reads these fields; construct one with [`Self::new`].
#[derive(Debug, Clone, Copy, Eq, PartialEq)]
#[non_exhaustive]
pub struct ClientInstrument<'a> {
    /// The name the venue knows the instrument by, which is what a client's requests carry.
    pub name_exchange: &'a InstrumentNameExchange,
    /// The instrument's kind.
    pub kind: InstrumentKindDiscriminant,
}

impl<'a> ClientInstrument<'a> {
    /// The view of an instrument named `name_exchange`, of kind `kind`.
    pub fn new(
        name_exchange: &'a InstrumentNameExchange,
        kind: InstrumentKindDiscriminant,
    ) -> Self {
        Self {
            name_exchange,
            kind,
        }
    }
}

// `+ Send` bounds on async method return types required for multi-threaded
// Tokio runtime. This is a breaking change vs upstream — any `!Send` executor
// implementation would fail to compile.
pub trait ExecutionClient
where
    Self: Clone,
{
    const EXCHANGE: ExchangeId;

    /// The [`InstrumentKindDiscriminant`]s this client can trade.
    ///
    /// A client works off [`InstrumentNameExchange`] strings and never inspects an instrument's
    /// kind, so nothing downstream can infer this from the implementation — routing a `Future`
    /// through a spot-only venue produces a rejected or, worse, misinterpreted order rather than a
    /// type error. Declaring the set here lets [`ExecutionBuilder`] reject an unsupported
    /// instrument set at build time, before any order is sent.
    ///
    /// Declare what the *venue and this implementation together* can actually route, not what the
    /// exchange's product catalogue advertises. A kind the exchange offers but this client builds
    /// no request for does not belong in the set.
    ///
    /// There is deliberately no default. A new client must state its capabilities rather than
    /// inherit a permissive set that would silently admit every kind.
    ///
    /// It is a `const` and not a `fn supported_kinds(&self)` because [`ExecutionBuilder`] validates
    /// the instrument set *before* [`Self::new`] is ever called — there is no instance to ask at the
    /// point the answer is needed, and deferring validation until after construction would mean
    /// standing up a client for a venue the engine is about to reject. A capability set that varies
    /// with `Self::Config` therefore cannot be expressed here; it would need a separate
    /// pre-construction hook on the config.
    ///
    /// [`ExecutionBuilder`]: https://docs.rs/rustrade/latest/rustrade/execution/builder/struct.ExecutionBuilder.html
    const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant];

    type Config: Clone;

    /// Checks `config` against the instruments this client is about to be built to trade, before
    /// [`Self::new`] is called. `Err` names what is wrong.
    ///
    /// [`SUPPORTED_KINDS`](Self::SUPPORTED_KINDS) rejects a kind the client cannot route at all.
    /// This catches what only the config knows: a per-instrument entry that is invalid, or that
    /// disagrees with the instrument it is keyed to, such as a contract registered as a stock for
    /// an instrument modelled as an option. Each such entry would otherwise be skipped or acted on
    /// silently once the client runs.
    ///
    /// The default accepts every config. Override it when `Self::Config` carries per-instrument
    /// detail.
    ///
    /// [`ExecutionBuilder`] calls it, after checking `SUPPORTED_KINDS`, with the instruments
    /// registered on this client's exchange. A client constructed by calling `new` directly is not
    /// checked; call this first to get the same check.
    ///
    /// [`ExecutionBuilder`]: https://docs.rs/rustrade/latest/rustrade/execution/builder/struct.ExecutionBuilder.html
    fn validate_config(
        config: &Self::Config,
        instruments: &[ClientInstrument<'_>],
    ) -> Result<(), String> {
        let _ = (config, instruments);
        Ok(())
    }

    // `+ Send` required so generic code (e.g. ExecutionManager) can pass
    // the stream to tokio::spawn, which requires Send.
    type AccountStream: Stream<Item = UnindexedAccountEvent> + Send;

    fn new(config: Self::Config) -> Self;

    /// Reads the account's balances, and its open orders and positions for `instruments`, from the
    /// venue.
    ///
    /// Besides startup, the engine's `ExecutionManager` calls this again on every account-stream
    /// reconnect, and emits the result ahead of the new stream's updates. It is how the engine
    /// catches up on what changed while the stream was down.
    ///
    /// # Order completeness
    ///
    /// Each [`InstrumentAccountSnapshot`](crate::InstrumentAccountSnapshot) states through
    /// `orders_complete` whether its `orders` list is every order open at the venue for that
    /// instrument. Set it only when it is true: the engine retires a tracked order that a complete
    /// list omits, so a list that can miss an open order (a capped page, an order dropped on
    /// conversion, an order reported under an id other than the one it was placed with) must say
    /// `false`. `false` is always safe; it only forgoes that reconciliation.
    fn account_snapshot(
        &self,
        assets: &[AssetNameExchange],
        instruments: &[InstrumentNameExchange],
    ) -> impl Future<Output = Result<UnindexedAccountSnapshot, UnindexedClientError>> + Send;

    /// Returns a live stream of account events (fills, order updates, balance changes).
    ///
    /// # Startup race window
    ///
    /// There is an unavoidable gap between the WebSocket subscribe response and the
    /// first event being delivered: fills arriving in this window (typically milliseconds,
    /// no sub-millisecond guarantee) are silently dropped. `account_snapshot` reconciles
    /// open-order state, but TRADE fills in this window are not recoverable from the stream
    /// alone. Callers that require fill completeness at startup **must** call
    /// [`ExecutionClient::fetch_trades`] with at least a 1-second lookback after this method returns.
    ///
    /// # Backpressure
    ///
    /// Implementations use unbounded internal channels. If the consumer cannot keep up,
    /// events queue in memory rather than being dropped — per library philosophy, OOM
    /// crashes are preferable to silent data loss. Consumers requiring backpressure
    /// should implement it at their boundary (e.g., bounded channel with overflow policy).
    fn account_stream(
        &self,
        assets: &[AssetNameExchange],
        instruments: &[InstrumentNameExchange],
    ) -> impl Future<Output = Result<Self::AccountStream, UnindexedClientError>> + Send;

    /// Cancel an order at the venue.
    ///
    /// # Return value
    ///
    /// Every request gets exactly one answer, which the engine's `ExecutionManager` forwards as the
    /// order's response. An implementation must not swallow a request: a failure to send it, or to
    /// read the venue's answer, is an `Err`.
    ///
    /// - `Ok(Cancelled)`: the venue took the cancel. Whether the order has *ended* by then depends
    ///   on the venue; see below.
    /// - `Err`: the venue refused the cancel, or it could not be sent or answered. The order may
    ///   still be open, or may have ended some other way, such as by filling. The account stream
    ///   reports which.
    ///
    /// # A taken cancel is not always an ended order
    ///
    /// Some venues answer a cancel before carrying it out. Until they do, the order is live and can
    /// still fill. From those venues `Ok(Cancelled)` means only that the cancel was accepted, and
    /// the account stream reports how the order actually ended, including any fill in between. The
    /// engine stops tracking an order on `Ok(Cancelled)` from any venue.
    ///
    /// Binance, Hyperliquid and the mock venue answer once the order is cancelled. Alpaca answers
    /// once it has accepted the cancel, and IBKR once the cancel is submitted. The
    /// [connector comparison](crate::client#connector-comparison) lists the same for each
    /// connector; the mock venue is not one, so it has no row there.
    ///
    /// # `filled_quantity` and `time_exchange`
    ///
    /// `Cancelled::filled_quantity` is the quantity the venue reported filled where the answer
    /// carries one, which Binance's and the mock venue's do. Alpaca, IBKR and Hyperliquid answer
    /// without it and report zero, which does not mean nothing filled. The fill total comes from
    /// the account stream, or from [`Self::fetch_trades`]. Likewise `time_exchange` is the venue's
    /// time where the answer carries one, and the local time the answer arrived otherwise.
    fn cancel_order(
        &self,
        request: OrderRequestCancel<ExchangeId, &InstrumentNameExchange>,
    ) -> impl Future<Output = UnindexedOrderResponseCancel> + Send;

    // `+ Send` on default method return types for multi-threaded Tokio runtime
    fn cancel_orders<'a>(
        &self,
        requests: impl IntoIterator<Item = OrderRequestCancel<ExchangeId, &'a InstrumentNameExchange>>,
    ) -> impl Stream<Item = UnindexedOrderResponseCancel> + Send {
        futures::stream::FuturesUnordered::from_iter(
            requests
                .into_iter()
                .map(|request| self.cancel_order(request)),
        )
    }

    /// Place an order on the exchange.
    ///
    /// # Return value
    ///
    /// Every request gets exactly one answer, which the engine's `ExecutionManager` forwards as the
    /// order's response. An implementation must not swallow a request: a failure to send it, or to
    /// read the venue's answer, is `OpenFailed`.
    ///
    /// Returns `OrderState` directly rather than `Result<Open, OrderError>`:
    /// - `OrderState::Active(Open)` - order is resting on the order book
    /// - `OrderState::Inactive(FullyFilled)` - order was immediately filled (includes `avg_price` when available)
    /// - `OrderState::Inactive(Expired)` - order ended in the response itself without filling
    ///   completely, carrying what filled: an IOC or FOK order that found too little liquidity,
    ///   or one expired by self-trade prevention
    /// - `OrderState::Inactive(Cancelled)` - order the venue reports cancelled in the response
    ///   itself, carrying what filled
    /// - `OrderState::Inactive(OpenFailed)` - order placement failed (API error, connectivity, a
    ///   rejection the venue reports in the response, etc.)
    ///
    /// An implementation returns `Expired` or `Cancelled` only when its venue reports the order's
    /// status in the placement response (currently Binance Spot and Margin). The others return
    /// `Open` for such an order, and their account stream reports how it ended.
    ///
    /// This design allows immediate fills to carry metadata (e.g., `avg_price`) that
    /// would be lost if we had to infer terminal state from `Open::filled_quantity`.
    fn open_order(
        &self,
        request: OrderRequestOpen<ExchangeId, &InstrumentNameExchange>,
    ) -> impl Future<Output = Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>> + Send;

    // `+ Send` on default method return types for multi-threaded Tokio runtime
    fn open_orders<'a>(
        &self,
        requests: impl IntoIterator<Item = OrderRequestOpen<ExchangeId, &'a InstrumentNameExchange>>,
    ) -> impl Stream<Item = Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>> + Send
    {
        futures::stream::FuturesUnordered::from_iter(
            requests.into_iter().map(|request| self.open_order(request)),
        )
    }

    /// Fetch current balances for the specified assets.
    ///
    /// An empty `assets` slice is the "return all" sentinel: implementations must return
    /// balances for every asset held. When non-empty, only the listed assets are returned.
    fn fetch_balances(
        &self,
        assets: &[AssetNameExchange],
    ) -> impl Future<Output = Result<Vec<AssetBalance<AssetNameExchange>>, UnindexedClientError>> + Send;

    /// Fetch currently open orders, optionally filtered by instrument.
    ///
    /// An empty `instruments` slice is the "return all" sentinel: implementations must
    /// return open orders across all instruments. When non-empty, only orders for the
    /// listed instruments are returned.
    fn fetch_open_orders(
        &self,
        instruments: &[InstrumentNameExchange],
    ) -> impl Future<
        Output = Result<Vec<Order<ExchangeId, InstrumentNameExchange, Open>>, UnindexedClientError>,
    > + Send;

    /// Read the trades (fills) from `start` to `end`, both inclusive, optionally filtered by
    /// instrument.
    ///
    /// An empty `instruments` slice is the "return all" sentinel: implementations must
    /// return trades across all instruments. When non-empty, only trades for the listed
    /// instruments are returned.
    ///
    /// # Bounded, resumable reads
    ///
    /// One call is bounded by the venue's limits, so it may stop before `end`.
    /// [`TradesRead::resume`] says whether it did:
    /// - `None`: every fill in the span the venue still holds was read.
    /// - `Some(t)`: call again with `start = t` and the same `end` to read on. That read can
    ///   return again fills the previous one returned, so match them by instrument and
    ///   [`TradeId`](crate::trade::TradeId).
    ///
    /// The caller owns the loop, and with it how many calls, and how long, it spends on a span.
    /// A `start` after `end` is an empty span, read as no trades and `resume: None`.
    ///
    /// # Venue limits
    ///
    /// `resume: None` covers what the venue still holds, which can be less than the span:
    /// - IBKR returns the current trading day's executions only.
    /// - Hyperliquid keeps only each wallet's 10,000 most recent fills.
    ///
    /// Binance needs instruments: an empty slice reads nothing. Each client documents its limits.
    ///
    /// # Errors
    ///
    /// [`Truncated`](crate::error::ClientError::Truncated) when a read cannot advance, because
    /// more fills share the span's first moment than one call can read past.
    ///
    /// The fee asset (`AssetNameExchange`) may be quote, base, or third-party (e.g., BNB).
    /// Use `fees.fees_quote` for quote-equivalent value when available.
    fn fetch_trades(
        &self,
        start: DateTime<Utc>,
        end: DateTime<Utc>,
        instruments: &[InstrumentNameExchange],
    ) -> impl Future<
        Output = Result<
            TradesRead<AssetNameExchange, InstrumentNameExchange>,
            UnindexedClientError,
        >,
    > + Send;
}

/// Extension trait for exchanges that support native bracket orders.
///
/// A bracket order consists of three linked orders:
/// 1. **Entry**: Limit order to enter the position
/// 2. **Take Profit**: Limit order to exit at profit target
/// 3. **Stop Loss**: Stop (or stop-limit) order to exit at loss limit
///
/// When either exit leg fills, the exchange automatically cancels the other.
///
/// # Type-Level Capability
///
/// This is a supertrait of [`ExecutionClient`], enabling compile-time capability checks:
/// - `impl ExecutionClient` — basic order operations
/// - `impl ExecutionClient + BracketOrderClient` — includes bracket orders
///
/// This follows Rust idioms like `Read + Seek` or `Iterator + ExactSizeIterator`.
///
/// # Why Supertrait Over Alternatives
///
/// **vs. associated types on `ExecutionClient`**: Callers can't construct
/// `Self::BracketRequest` without knowing the concrete type — adds trait surface
/// without enabling generic use.
///
/// **vs. default impl returning `Unsupported`**: Puts a "dead method" on every
/// client (MockExecution, BinanceSpot, HyperliquidClient). Compile-time capability
/// via trait bounds is better than runtime errors.
///
/// # Result Types
///
/// [`BracketOrderResult`] uses `Option<Order>` for child legs to document API divergence:
///
/// | Exchange | `take_profit` | `stop_loss` | Reason |
/// |----------|---------------|-------------|--------|
/// | IBKR     | `Some(...)` | `Some(...)` | Returns all three orders immediately |
/// | Alpaca   | `None` | `None` | Child legs created server-side |
///
/// # Example
///
/// ```ignore
/// use rustrade_execution::client::{ExecutionClient, BracketOrderClient};
/// use rustrade_execution::order::bracket::{BracketOrderRequest, RequestOpenBracket};
///
/// async fn place_bracket<C: ExecutionClient + BracketOrderClient>(
///     client: &C,
///     request: BracketOrderRequest<ExchangeId, &InstrumentNameExchange>,
/// ) -> BracketOrderResult {
///     client.open_bracket_order(request).await
/// }
/// ```
pub trait BracketOrderClient: ExecutionClient {
    /// Place a bracket order (entry + take-profit + stop-loss).
    ///
    /// # Request
    ///
    /// The [`BracketOrderRequest`] contains:
    /// - `key`: Order key (exchange, instrument, strategy, client order ID)
    /// - `state`: [`RequestOpenBracket`](crate::order::bracket::RequestOpenBracket) with
    ///   side, quantity, prices, and optional stop-loss limit price
    ///
    /// # Constraints
    ///
    /// - `time_in_force` must be `Day` or `GoodUntilCancelled` on most exchanges
    /// - Entry order type is always `Limit`
    /// - Price ordering must be valid for the side (see [`RequestOpenBracket`](crate::order::bracket::RequestOpenBracket))
    ///
    /// # Exchange-Specific Field Handling
    ///
    /// `RequestOpenBracket::stop_loss_limit_price` is **not honored uniformly**:
    /// - **Alpaca**: When `Some`, the stop-loss leg becomes a stop-limit order at that price.
    /// - **IBKR**: Silently ignored — the stop-loss leg is always a stop (market) order.
    ///
    /// Generic callers `T: BracketOrderClient` must treat this field as advisory.
    ///
    /// # Return Value
    ///
    /// Returns [`BracketOrderResult`] with:
    /// - `parent`: Always present (entry order)
    /// - `take_profit`: `Some` if exchange returns legs immediately (IBKR), `None` otherwise (Alpaca)
    /// - `stop_loss`: `Some` if exchange returns legs immediately (IBKR), `None` otherwise (Alpaca)
    ///
    /// Either all orders are `Active(Open)` or all are `Inactive` (placement failed), with one
    /// exception: a leg of a failed placement whose fate at the venue is unknown (no status
    /// arrived, or it was accepted and its rollback cancel could not be sent) is returned
    /// `Active(Open)`, so the account stream can resolve it. Only IBKR returns such legs today;
    /// see its `open_bracket_order`.
    fn open_bracket_order(
        &self,
        request: BracketOrderRequest<ExchangeId, &InstrumentNameExchange>,
    ) -> impl Future<Output = BracketOrderResult> + Send;
}

/// Extension trait for clients that can say how an order ended at the venue.
///
/// A client that loses its account stream recovers the fills it missed when it reconnects, but not
/// an order that was cancelled, expired or rejected in the meantime: the event that said so went
/// out while nothing was listening. The engine then keeps such an order as live until a complete
/// account snapshot no longer lists it, and even then cannot tell how it ended. This trait is the
/// lookup that answers that: given the orders a caller still holds as live, it returns how each one
/// that has ended did end.
///
/// # By order, not by time
///
/// The obvious alternative, asking the venue for every order closed since the disconnect, does not
/// work. Binance's `allOrders` and Alpaca's `GET /v2/orders?status=closed` both filter their time
/// window on when an order was **created**, so a window opening at the disconnect cannot see an
/// order placed before it and cancelled during it — which is the order that matters, because the
/// caller is tracking it. Looking each order up by its client order id finds it whenever it was
/// placed.
///
/// # Type-Level Capability
///
/// A supertrait of [`ExecutionClient`], for the reason [`BracketOrderClient`] is one: a client that
/// cannot look orders up does not implement it, rather than carrying a method that fails at run
/// time. A caller that needs the lookup bounds on `ExecutionClient + OrderStatusClient`.
pub trait OrderStatusClient: ExecutionClient {
    /// How each of `orders` ended, for those that have.
    ///
    /// # Contract
    ///
    /// - One entry per order that has ended, in no particular order:
    ///   [`FullyFilled`](crate::order::state::InactiveOrderState::FullyFilled),
    ///   [`Cancelled`](crate::order::state::InactiveOrderState::Cancelled) carrying what filled
    ///   before it, [`Expired`](crate::order::state::InactiveOrderState::Expired), or
    ///   [`OpenFailed`](crate::order::state::InactiveOrderState::OpenFailed) for an order the venue
    ///   accepted for processing and later rejected (Binance `REJECTED`, Alpaca `rejected`). An
    ///   order rejected in the response to its open request was answered there and is not expected
    ///   here.
    /// - An order still live is **omitted**, and so is one the venue does not know. Neither is an
    ///   error. A caller compares the result with what it asked for.
    /// - An empty `orders` returns an empty list. Unlike
    ///   [`ExecutionClient::fetch_open_orders`]'s empty slice, it does not mean "all".
    /// - An order is found by its [`cid`](crate::order::OrderKey::cid), and each returned order
    ///   carries the key it was asked for, so a `strategy` the venue does not record survives.
    /// - A key whose `instrument` is not the one the order traded is treated as unknown. The
    ///   `exchange` is not checked: a client answers for its own venue.
    /// - A `cid` asked about more than once is reported at most once, under the first key that
    ///   finds it.
    ///
    /// # Errors
    ///
    /// `Err` if the venue could not answer for every order. A partial list is never returned,
    /// because an order missing from it would read as still live.
    fn fetch_ended_orders(
        &self,
        orders: &[UnindexedOrderKey],
    ) -> impl Future<Output = Result<Vec<UnindexedInactiveOrder>, UnindexedClientError>> + Send;
}

/// Extension trait for clients that can say what the venue would lend for a short sale.
///
/// Answers, before an order is sent, the question a short sale otherwise learns only from its
/// rejection: whether the instrument may be sold short, whether it is easy to borrow, how much the
/// venue has to lend and at what fee. Each venue reports a different subset, so each field of the
/// [`Shortability`] it returns is optional; the implementations say which fields they fill.
///
/// # Type-Level Capability
///
/// A supertrait of [`ExecutionClient`], for the reason [`BracketOrderClient`] is one: a client
/// whose venue has nothing to lend, or that does not report it, does not implement it. A simulated
/// venue reads the same [`Shortability`] from a
/// [`ShortabilityProvider`](crate::shortability::ShortabilityProvider) instead.
pub trait ShortabilityClient: ExecutionClient {
    /// What the venue says about lending `instrument` for a short sale.
    ///
    /// # Contract
    ///
    /// - **Advisory.** `Ok` describes the venue's lending as it reported it, not a promise to lend:
    ///   a short sale must still handle
    ///   [`ApiError::BorrowRejected`](crate::error::ApiError::BorrowRejected).
    /// - **Not this account's capacity.** [`Shortability::available`] is what the venue has to
    ///   lend, not what is left of it for this account; that is
    ///   [`BorrowCapacityClient::fetch_borrow_capacity`], where a venue reports it.
    /// - **May be expensive.** An implementation may make several requests, some of them heavy
    ///   against the venue's rate limit, or hold a scarce resource such as a market data line;
    ///   each says what it costs. Fetch it when deciding on a short, not on every tick.
    /// - **May be slow.** Where the venue streams its answer rather than replying to a request,
    ///   the call waits for it, up to a timeout the implementation documents: seconds, not
    ///   milliseconds.
    /// - **May outlive its future.** An implementation that reads on a blocking thread finishes
    ///   that read, and releases what it holds, even when the returned future is dropped first;
    ///   each says so.
    ///
    /// # Errors
    ///
    /// - [`ApiError::InstrumentInvalid`](crate::error::ApiError::InstrumentInvalid) for an
    ///   instrument the venue does not know, or one of a kind that is not sold short by borrowing
    ///   it, such as an option.
    /// - An error, rather than a [`Shortability`] with nothing known, when the venue does not
    ///   answer, including when the account is not entitled to the answer, such as one without the
    ///   market data subscription a venue sends it through.
    fn fetch_shortability(
        &self,
        instrument: &InstrumentNameExchange,
    ) -> impl Future<Output = Result<Shortability, UnindexedClientError>> + Send;
}

/// Extension trait for clients that can say how much more this account can borrow.
///
/// Where [`ShortabilityClient`] says what the venue has to lend, this says how much of it this
/// account could take now, given its collateral, its limit and what it has already borrowed. The
/// two are separate types because they are different facts; see [`BorrowCapacity`].
///
/// # Type-Level Capability
///
/// A supertrait of [`ExecutionClient`], for the reason [`BracketOrderClient`] is one. Only a venue
/// that lends against an account's collateral and reports what is left of it implements it.
pub trait BorrowCapacityClient: ExecutionClient {
    /// How much this account can borrow now for an order on `instrument` on `side`.
    ///
    /// A sell borrows the instrument's base asset, which is a short; a buy borrows its quote asset,
    /// which is a leveraged long. The result names that asset, and its amounts are in its units.
    ///
    /// # Contract
    ///
    /// **Advisory**, as [`BorrowCapacity`] says: the amounts are not reserved, so an order sized to
    /// them must still handle [`ApiError::BorrowRejected`](crate::error::ApiError::BorrowRejected).
    ///
    /// # Errors
    ///
    /// [`ApiError::InstrumentInvalid`](crate::error::ApiError::InstrumentInvalid) for an instrument
    /// the client cannot borrow against, such as a pair the venue does not trade on margin.
    fn fetch_borrow_capacity(
        &self,
        instrument: &InstrumentNameExchange,
        side: Side,
    ) -> impl Future<Output = Result<BorrowCapacity, UnindexedClientError>> + Send;
}

/// The capability table, pinned.
///
/// [`ExecutionClient::SUPPORTED_KINDS`] is a `const`: widening one, or adding a kind a client builds
/// no request for, compiles and passes clippy. The only thing it changes is which instruments
/// [`ExecutionBuilder`](https://docs.rs/rustrade/latest/rustrade/execution/builder/struct.ExecutionBuilder.html)
/// admits — so the failure mode is not a broken build but an instrument reaching a venue that cannot
/// encode it, as a silently wrong order. These assertions exist so that changing a client's declared
/// capabilities is a deliberate edit to a test that says what the venue can route, rather than a
/// one-word diff nothing observes.
///
/// The real-client cases are each gated on their own feature, matching the module gates above; the
/// mock case is ungated, like its module. So with `default = []`, a bare
/// `cargo test -p rustrade-execution` compiles only the mock assertion — pinning a real client's
/// capabilities requires `--features <name>` or `--all-features`.
#[cfg(test)]
mod tests {
    use super::*;
    use crate::client::mock::MockExecution;

    #[test]
    fn mock_supports_only_the_kinds_it_can_model() {
        // No expiry, funding schedule or contract chain in `MockExchange`, so `Perpetual`, `Future`
        // and `Option` have no faithful projection onto it. Kept in step with the projection in
        // `generate_mock_exchange_instruments`, which panics on a kind it cannot project.
        assert_eq!(
            <MockExecution<fn() -> DateTime<Utc>> as ExecutionClient>::SUPPORTED_KINDS,
            &[
                InstrumentKindDiscriminant::Spot,
                InstrumentKindDiscriminant::Cfd
            ]
        );
    }

    #[cfg(feature = "binance")]
    #[test]
    fn binance_spot_and_margin_are_spot_only() {
        use crate::client::binance::{BinanceMargin, BinanceSpot};

        assert_eq!(
            BinanceSpot::SUPPORTED_KINDS,
            &[InstrumentKindDiscriminant::Spot]
        );
        // Cross margin trades the same spot instruments on borrowed funds -- the leverage is in the
        // account, not the instrument kind.
        assert_eq!(
            BinanceMargin::SUPPORTED_KINDS,
            &[InstrumentKindDiscriminant::Spot]
        );
    }

    #[cfg(feature = "hyperliquid")]
    #[test]
    fn hyperliquid_splits_perpetual_and_spot_across_two_clients() {
        use crate::client::hyperliquid::{HyperliquidClient, spot::HyperliquidSpotClient};

        assert_eq!(
            HyperliquidClient::SUPPORTED_KINDS,
            &[InstrumentKindDiscriminant::Perpetual]
        );
        assert_eq!(
            HyperliquidSpotClient::SUPPORTED_KINDS,
            &[InstrumentKindDiscriminant::Spot]
        );
    }

    #[cfg(feature = "alpaca")]
    #[test]
    fn alpaca_trades_equities_and_options() {
        use crate::client::alpaca::AlpacaClient;

        assert_eq!(
            AlpacaClient::SUPPORTED_KINDS,
            &[
                InstrumentKindDiscriminant::Spot,
                InstrumentKindDiscriminant::Option
            ]
        );
    }

    #[cfg(feature = "ibkr")]
    #[test]
    fn ibkr_omits_cfd_because_it_builds_no_contract_for_one() {
        use crate::client::ibkr::IbkrClient;

        // `ContractConfig::to_contract` builds `STK`, `FUT`, `OPT` and `CASH` and nothing else, so a
        // CFD routed here would be encoded as some other security type -- exactly the silent
        // wrong-symbol order this const exists to reject. Adding `Cfd` to the list requires adding
        // the arm first.
        assert_eq!(
            IbkrClient::SUPPORTED_KINDS,
            &[
                InstrumentKindDiscriminant::Spot,
                InstrumentKindDiscriminant::Future,
                InstrumentKindDiscriminant::Option
            ]
        );
    }
}