clob_sync/

order_book.rs

use nonempty::NonEmpty;

use crate::execution::{Execution, Executions};
use crate::order::Symbol;
use crate::order::{Order, OrderSide};
use crate::order_book_side::{BookSide, InMemoryOrderBookSide, OrderBookSide};
use crate::prelude::*;

/// A factory trait for creating order book instances.
///
/// Implementors provide a specific order book side implementation.
pub trait OrderBookFactory {
    /// The order book side type
    type BookSide: OrderBookSide;

    /// Creates a new order book for the given symbol.
    fn create_order_book(symbol: Symbol) -> OrderBook<Self::BookSide>;
}

/// An in-memory order book factory that creates order books with
/// binary heap-based priority queues.
///
/// # Example
///
/// ```
/// use clob_sync::prelude::*;
/// use clob_sync::order_book::InMemoryOrderBookFactory;
///
/// let book = InMemoryOrderBookFactory::create_order_book(Symbol::from("BTC-USD"));
/// ```
///
/// or:
///
/// ```
/// use clob_sync::prelude::*;
/// let book = InMemoryOrderBookFactory::create_order_book(Symbol::from("BTC-USD"));
/// ```
#[derive(Debug)]
pub struct InMemoryOrderBookFactory;

impl OrderBookFactory for InMemoryOrderBookFactory {
    type BookSide = InMemoryOrderBookSide;

    fn create_order_book(symbol: Symbol) -> OrderBook<Self::BookSide> {
        OrderBook {
            symbol,
            bids: InMemoryOrderBookSide::new(BookSide::Bids),
            asks: InMemoryOrderBookSide::new(BookSide::Asks),
        }
    }
}

/// A Central Limit Order Book (CLOB) for a single symbol.
///
/// The order book maintains buy orders (bids) and sell orders (asks),
/// executing trades when orders cross.
///
/// # Type Parameters
///
/// * `S` - The order book side implementation
///
/// # Example
///
/// ```
/// use clob_sync::prelude::*;
/// use clob_sync::order::{Order, OrderType, OrderSide, Quantity, Price, Symbol};
/// use clob_sync::order_book::InMemoryOrderBookFactory;
/// use std::str::FromStr;
///
/// fn main() -> Result<()> {
/// let mut book = InMemoryOrderBookFactory::create_order_book(Symbol::from("BTC-USD"));
///
///     // Add a sell order
///     let sell_order = Order::new(
///         OrderType::Limit(Price::try_from("50000.00").unwrap()),
///         Quantity::try_from("1.0").unwrap(),
///         OrderSide::Sell,
///         Symbol::from("BTC-USD"),
///     );
///     book.execute(&sell_order)?;
///
///     // Add a matching buy order
///     let buy_order = Order::new(
///         OrderType::Limit(Price::try_from("50000.00").unwrap()),
///         Quantity::try_from("0.5").unwrap(),
///         OrderSide::Buy,
///         Symbol::from("BTC-USD"),
///     );
///     let result = book.execute(&buy_order)?;
///     assert!(matches!(result, Executions::Executed(_)));
///
///     Ok(())
/// }
/// ```
#[derive(Debug)]
pub struct OrderBook<S>
where
    S: OrderBookSide,
{
    symbol: Symbol,
    bids: S,
    asks: S,
}

impl<S> OrderBook<S>
where
    S: OrderBookSide,
{
    /// Executes an order against the order book.
    ///
    /// For market orders, execution happens at the best available price.
    /// For limit orders, execution happens only if the order crosses the
    /// opposite side of the book.
    ///
    /// # Arguments
    ///
    /// * `order` - The order to execute
    ///
    /// # Returns
    ///
    /// Returns [`Executions`] indicating:
    /// - `AllocatedNoExecutions`: Order was added to book without matching
    /// - `Executed`: Order was fully or partially matched
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidSymbol`] if the order symbol doesn't match
    /// the order book symbol.
    pub fn execute(&mut self, order: &Order) -> Result<Executions> {
        if order.symbol != self.symbol {
            return Err(Error::InvalidSymbol {
                expected: self.symbol,
                received: order.symbol,
            });
        }
        let order = &order.clone().with_id();

        let crosses = match order.side {
            OrderSide::Buy => self.asks.try_cross(order)?,
            OrderSide::Sell => self.bids.try_cross(order)?,
        };

        if let Some(leaves_quantity) = crosses.remaining_incoming_order {
            let remaining_order = order.with_quantity(leaves_quantity);
            match order.side {
                OrderSide::Buy => self.bids.allocate(remaining_order),
                OrderSide::Sell => self.asks.allocate(remaining_order),
            }
        }

        if crosses.matches.is_empty() {
            Ok(Executions::AllocatedNoExecutions)
        } else {
            Ok(Executions::Executed(
                NonEmpty::from_vec(
                    crosses
                        .matches
                        .iter()
                        .flat_map(Vec::<Execution>::from)
                        .collect(),
                )
                .expect("unexpected condition: matches cannot be empty here"),
            ))
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{
        insta_test_utils::insta_settings_with_masking_filters,
        order::{Price, Quantity},
    };
    use insta::assert_debug_snapshot;

    #[test]
    fn test_order_book_factory() {
        assert_debug_snapshot!(InMemoryOrderBookFactory::create_order_book(Symbol::from("AAPL")), @r#"
        OrderBook {
            symbol: Symbol(
                u!("AAPL"),
            ),
            bids: InMemoryOrderBookSide {
                side: Bids,
                orders: [],
            },
            asks: InMemoryOrderBookSide {
                side: Asks,
                orders: [],
            },
        }
        "#);
    }

    #[test]
    fn test_displaced_symbol() {
        let mut book =
            InMemoryOrderBookFactory::create_order_book(Symbol::from("IBM"));

        let result = book.execute(&Order::new(
            OrderType::Limit(Price::from(100)),
            Quantity::from(10u64),
            OrderSide::Buy,
            Symbol::from("AAPL"),
        ));
        assert_debug_snapshot!(result, @r#"
        Err(
            InvalidSymbol {
                expected: Symbol(
                    u!("IBM"),
                ),
                received: Symbol(
                    u!("AAPL"),
                ),
            },
        )
        "#);
    }

    #[test]
    fn test_execute() {
        let mut book =
            InMemoryOrderBookFactory::create_order_book(Symbol::from("AAPL"));

        let result = book.execute(&Order::new(
            OrderType::Limit(Price::from(100)),
            Quantity::from(10u64),
            OrderSide::Buy,
            Symbol::from("AAPL"),
        ));
        assert_debug_snapshot!(result, @r"
        Ok(
            AllocatedNoExecutions,
        )
        ");

        insta_settings_with_masking_filters().bind(|| {
            let result = book.execute(&Order::new(
                OrderType::Limit(Price::from(100)),
                Quantity::from(10u64),
                OrderSide::Sell,
                Symbol::from("AAPL"),
            ));
            assert_debug_snapshot!(result, @r"
            Ok(
                Executed(
                    NonEmpty {
                        head: FullExecution(
                            OrderId(********-****-****-****-************),
                        ),
                        tail: [
                            FullExecution(
                                OrderId(********-****-****-****-************),
                            ),
                        ],
                    },
                ),
            )
            ");
        });
    }
}