Add Cache account lookup error

- Add `AccountLookupError` and `Cache::try_account`.
- Cover missing and cached account lookups in cache tests.
- Use typed account lookups in required fill and portfolio paths.

Author: cjdsellers

crates/common/src/cache/error.rs

@@ -13,10 +13,13 @@
 //  limitations under the License.
 // -------------------------------------------------------------------------------------------------
 
-use nautilus_model::identifiers::{ClientOrderId, InstrumentId, PositionId};
+use nautilus_model::identifiers::{AccountId, ClientOrderId, InstrumentId, PositionId};
 use thiserror::Error;
 use ustr::Ustr;
 
+/// Message used for a missing account lookup.
+pub const ACCOUNT_NOT_FOUND: &str = "account not found in cache";
+
 /// Message used for a missing currency lookup.
 pub const CURRENCY_NOT_FOUND: &str = "currency not found in cache";
 
@@ -29,6 +32,25 @@ pub const ORDER_NOT_FOUND: &str = "order not found in cache";
 /// Message used for a missing position lookup.
 pub const POSITION_NOT_FOUND: &str = "position not found in cache";
 
+/// Error returned when an account cannot be resolved from a cache or store.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
+pub enum AccountLookupError {
+    /// The requested account is not present.
+    #[error("{message}: {account_id}", message = ACCOUNT_NOT_FOUND)]
+    NotFound {
+        /// The account identifier that was requested.
+        account_id: AccountId,
+    },
+}
+
+impl AccountLookupError {
+    /// Returns a not-found error for `account_id`.
+    #[must_use]
+    pub const fn not_found(account_id: AccountId) -> Self {
+        Self::NotFound { account_id }
+    }
+}
+
 /// Error returned when a currency cannot be resolved from a cache or store.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
 pub enum CurrencyLookupError {

crates/common/src/cache/mod.rs

@@ -45,8 +45,9 @@ use bytes::Bytes;
 pub use config::CacheConfig; // Re-export
 use database::{CacheDatabaseAdapter, CacheMap};
 pub use error::{
-    CURRENCY_NOT_FOUND, CurrencyLookupError, INSTRUMENT_NOT_FOUND, InstrumentLookupError,
-    ORDER_NOT_FOUND, OrderLookupError, POSITION_NOT_FOUND, PositionLookupError,
+    ACCOUNT_NOT_FOUND, AccountLookupError, CURRENCY_NOT_FOUND, CurrencyLookupError,
+    INSTRUMENT_NOT_FOUND, InstrumentLookupError, ORDER_NOT_FOUND, OrderLookupError,
+    POSITION_NOT_FOUND, PositionLookupError,
 };
 use index::CacheIndex;
 use nautilus_core::{
@@ -5445,6 +5446,21 @@ impl Cache {
             .map(|account_cell| AccountRef::new(account_cell.borrow()))
     }
 
+    /// Returns a borrow of the account for the `account_id`.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`AccountLookupError::NotFound`] when the account is not present in the cache.
+    pub fn try_account(
+        &self,
+        account_id: &AccountId,
+    ) -> Result<AccountRef<'_>, AccountLookupError> {
+        self.accounts
+            .get(account_id)
+            .map(|account_cell| AccountRef::new(account_cell.borrow()))
+            .ok_or_else(|| AccountLookupError::not_found(*account_id))
+    }
+
     /// Gets an exclusive write borrow of the account with the `account_id` (if found).
     ///
     /// Requires `&mut Cache` so cache writes are reachable only by privileged crates that hold

crates/common/src/cache/tests.rs

@@ -69,9 +69,9 @@ use ustr::Ustr;
 
 use crate::{
     cache::{
-        CURRENCY_NOT_FOUND, Cache, CacheConfig, CacheView, CurrencyLookupError,
-        INSTRUMENT_NOT_FOUND, InstrumentLookupError, ORDER_NOT_FOUND, OrderLookupError, OrderRef,
-        POSITION_NOT_FOUND, PositionLookupError,
+        ACCOUNT_NOT_FOUND, AccountLookupError, CURRENCY_NOT_FOUND, Cache, CacheConfig, CacheView,
+        CurrencyLookupError, INSTRUMENT_NOT_FOUND, InstrumentLookupError, ORDER_NOT_FOUND,
+        OrderLookupError, OrderRef, POSITION_NOT_FOUND, PositionLookupError,
         database::{CacheDatabaseAdapter, CacheMap},
     },
     signal::Signal,
@@ -2903,6 +2903,30 @@ fn test_cache_add_account(mut cache: Cache) {
     assert_eq!(*result.unwrap(), account);
 }
 
+#[rstest]
+fn test_try_account_when_empty(cache: Cache) {
+    let account_id = AccountId::test_default();
+
+    let err = cache.try_account(&account_id).unwrap_err();
+
+    assert_eq!(err, AccountLookupError::not_found(account_id));
+    assert_eq!(
+        err.to_string(),
+        format!("{ACCOUNT_NOT_FOUND}: {account_id}")
+    );
+}
+
+#[rstest]
+fn test_try_account_when_some(mut cache: Cache) {
+    let account = AccountAny::default();
+    let account_id = account.id();
+    cache.add_account(account.clone()).unwrap();
+
+    let result = cache.try_account(&account_id).unwrap();
+
+    assert_eq!(*result, account);
+}
+
 #[rstest]
 fn test_cache_accounts_when_no_accounts_returns_empty(cache: Cache) {
     let result = cache.accounts(&AccountId::test_default());

crates/execution/src/engine/mod.rs

@@ -2587,11 +2587,8 @@ impl ExecutionEngine {
                 return;
             };
 
-        if self.cache.borrow().account(&fill.account_id).is_none() {
-            log::error!(
-                "Cannot handle leg fill: no account found for {}, {fill}",
-                fill.instrument_id.venue,
-            );
+        if let Err(e) = self.cache.borrow().try_account(&fill.account_id) {
+            log::error!("Cannot handle leg fill: {e}, {fill}");
             return;
         }
 
@@ -3096,12 +3093,12 @@ impl ExecutionEngine {
 
         let is_margin_account = {
             let cache = self.cache.borrow();
-            let Some(account) = cache.account(&fill.account_id) else {
-                log::error!(
-                    "Cannot handle order fill: no account found for {}, {fill}",
-                    fill.instrument_id.venue,
-                );
-                return Vec::new();
+            let account = match cache.try_account(&fill.account_id) {
+                Ok(account) => account,
+                Err(e) => {
+                    log::error!("Cannot handle order fill: {e}, {fill}");
+                    return Vec::new();
+                }
             };
 
             account.is_margin_account()

crates/portfolio/src/portfolio.rs

@@ -21,7 +21,7 @@ use ahash::{AHashMap, AHashSet};
 use indexmap::{IndexMap, IndexSet};
 use nautilus_analysis::analyzer::PortfolioAnalyzer;
 use nautilus_common::{
-    cache::Cache,
+    cache::{AccountLookupError, Cache},
     clock::Clock,
     enums::LogColor,
     msgbus::{self, MessagingSwitchboard, TypedHandler, TypedIntoHandler},
@@ -1111,14 +1111,12 @@ impl Portfolio {
 
         for position in &positions_open {
             // Get account for THIS position
-            let account = if let Some(account) = cache.account(&position.account_id) {
-                account
-            } else {
-                log::error!(
-                    "Cannot calculate net exposure: no account for {}",
-                    position.account_id
-                );
-                return None;
+            let account = match cache.try_account(&position.account_id) {
+                Ok(account) => account,
+                Err(e) => {
+                    log::error!("Cannot calculate net exposure: {e}");
+                    return None;
+                }
             };
 
             // Validate consistent base currency across accounts
@@ -2247,11 +2245,12 @@ fn update_order(
     let (instrument, orders_open) = {
         let cache_ref = cache.borrow();
 
-        let account = if let Some(account) = cache_ref.account(&account_id) {
-            account
-        } else {
-            log::error!("Cannot update order: no account registered for {account_id}");
-            return;
+        let account = match cache_ref.try_account(&account_id) {
+            Ok(account) => account,
+            Err(e) => {
+                log::error!("Cannot update order: {e}");
+                return;
+            }
         };
 
         match &*account {
@@ -2325,11 +2324,15 @@ fn update_order(
     };
 
     // No cache borrow held: AccountsManager borrows cache internally for xrate lookups.
-    let mut working_account = if let Some(account) = cache.borrow_mut().take_account(&account_id) {
-        account
-    } else {
-        log::error!("Cannot update order: no account registered for {account_id}");
-        return;
+    let mut working_account = match cache.borrow_mut().take_account(&account_id) {
+        Some(account) => account,
+        None => {
+            log::error!(
+                "Cannot update order: {}",
+                AccountLookupError::not_found(account_id)
+            );
+            return;
+        }
     };
 
     if let OrderEventAny::Filled(order_filled) = event {