[1/n] [nexus-db-queries] move LookupPath to another crate (#7985)

Introduce `nexus-db-lookup`, a new crate that contains `LookupPath` and all of the corresponding resources.

This change has two advantages:

1. While attempting to split some of omicron-nexus up into multiple crates that could potentially compile in parallel with nexus-db-queries, I ran into the issue that `LookupPath`, which is a fairly fundamental type, lived inside nexus-db-queries.
2. This is an okay build speed improvement in its own right. With this change, `touch nexus-db-queries/src/lib.rs && cargo check -p nexus-db-queries` goes from around 2.45 seconds to 2.15 seconds (around 1.15x faster).

    That's because the `lookup_resource` macros in the new nexus-db-lookup crate [expand](https://crates.io/crates/cargo-expand/) to quite a lot of code: around 15k lines or so compared to the rest of nexus-db-queries' 75k lines when expanded.

In order to achieve this goal:

* This PR provides a trait as an interface that `DataStore` implements. That isn't too bad, though. I'm not totally sure this will end up being the final shape of such an interface, but it works for now and can be changed later with minimal disruption.
* This PR splits some error handling code in nexus-db-queries into its own crate as well. Relatively small but otherwise quite nice chunk of code to move out.

This PR aims to minimize ugliness at callsites (i.e. `nexus.datastore()` rather than `&**nexus.datastore()`). However I did let some churn through, specifically places where we passed in immediately-dereferenced types like `&&DataStore`.

Author: sunshowers

Cargo.lock

@@ -77,7 +77,9 @@ members = [
     "nexus-sled-agent-shared",
     "nexus/authz-macros",
     "nexus/auth",
+    "nexus/db-errors",
     "nexus/db-fixed-data",
+    "nexus/db-lookup",
     "nexus/db-macros",
     "nexus/db-model",
     "nexus/db-queries",
@@ -223,7 +225,9 @@ default-members = [
     "nexus-sled-agent-shared",
     "nexus/authz-macros",
     "nexus/auth",
+    "nexus/db-errors",
     "nexus/db-fixed-data",
+    "nexus/db-lookup",
     "nexus/db-macros",
     "nexus/db-model",
     "nexus/db-queries",
@@ -492,7 +496,9 @@ multimap = "0.10.0"
 nexus-auth = { path = "nexus/auth" }
 nexus-client = { path = "clients/nexus-client" }
 nexus-config = { path = "nexus-config" }
+nexus-db-errors = { path = "nexus/db-errors" }
 nexus-db-fixed-data = { path = "nexus/db-fixed-data" }
+nexus-db-lookup = { path = "nexus/db-lookup" }
 nexus-db-model = { path = "nexus/db-model" }
 nexus-db-queries = { path = "nexus/db-queries" }
 nexus-db-schema = { path = "nexus/db-schema" }

Cargo.toml

@@ -33,6 +33,8 @@ internal-dns-types.workspace = true
 itertools.workspace = true
 nexus-client.workspace = true
 nexus-config.workspace = true
+nexus-db-errors.workspace = true
+nexus-db-lookup.workspace = true
 nexus-db-model.workspace = true
 nexus-db-queries.workspace = true
 nexus-db-schema.workspace = true

dev-tools/omdb/Cargo.toml

@@ -56,6 +56,9 @@ use ipnetwork::IpNetwork;
 use itertools::Itertools;
 use nexus_config::PostgresConfigWithUrl;
 use nexus_config::RegionAllocationStrategy;
+use nexus_db_errors::OptionalError;
+use nexus_db_lookup::DataStoreConnection;
+use nexus_db_lookup::LookupPath;
 use nexus_db_model::CrucibleDataset;
 use nexus_db_model::Disk;
 use nexus_db_model::DnsGroup;
@@ -106,20 +109,17 @@ use nexus_db_queries::context::OpContext;
 use nexus_db_queries::db;
 use nexus_db_queries::db::DataStore;
 use nexus_db_queries::db::datastore::CrucibleTargets;
-use nexus_db_queries::db::datastore::DataStoreConnection;
 use nexus_db_queries::db::datastore::InstanceAndActiveVmm;
 use nexus_db_queries::db::datastore::InstanceStateComputer;
 use nexus_db_queries::db::datastore::SQL_BATCH_SIZE;
 use nexus_db_queries::db::datastore::VolumeCookedResult;
 use nexus_db_queries::db::datastore::read_only_resources_associated_with_volume;
 use nexus_db_queries::db::identity::Asset;
-use nexus_db_queries::db::lookup::LookupPath;
 use nexus_db_queries::db::model::ServiceKind;
 use nexus_db_queries::db::pagination::Paginator;
 use nexus_db_queries::db::pagination::paginated;
 use nexus_db_queries::db::queries::ALLOW_FULL_TABLE_SCAN_SQL;
 use nexus_db_queries::db::queries::region_allocation;
-use nexus_db_queries::transaction_retry::OptionalError;
 use nexus_types::deployment::Blueprint;
 use nexus_types::deployment::BlueprintZoneDisposition;
 use nexus_types::deployment::BlueprintZoneType;

dev-tools/omdb/src/bin/omdb/db.rs

@@ -18,13 +18,13 @@ use clap::Subcommand;
 use diesel::prelude::*;
 use internal_dns_resolver::ResolveError;
 use internal_dns_types::names::ServiceName;
+use nexus_db_lookup::DataStoreConnection;
 use nexus_db_model::Saga;
 use nexus_db_model::SagaNodeEvent;
 use nexus_db_model::SagaState;
 use nexus_db_model::SecId;
 use nexus_db_queries::context::OpContext;
 use nexus_db_queries::db::DataStore;
-use nexus_db_queries::db::datastore::DataStoreConnection;
 use nexus_db_queries::db::datastore::SQL_BATCH_SIZE;
 use nexus_db_queries::db::pagination::Paginator;
 use nexus_db_queries::db::pagination::paginated;

dev-tools/omdb/src/bin/omdb/db/saga.rs

@@ -35,8 +35,8 @@ use nexus_client::types::PhysicalDiskPath;
 use nexus_client::types::SagaState;
 use nexus_client::types::SledSelector;
 use nexus_client::types::UninitializedSledId;
+use nexus_db_lookup::LookupPath;
 use nexus_db_queries::db::DataStore;
-use nexus_db_queries::db::lookup::LookupPath;
 use nexus_inventory::now_db_precision;
 use nexus_saga_recovery::LastPass;
 use nexus_types::deployment::Blueprint;
@@ -3167,7 +3167,7 @@ async fn cmd_nexus_sled_expunge_with_datastore(
     let opctx = &opctx;
 
     // First, we need to look up the sled so we know its serial number.
-    let (_authz_sled, sled) = LookupPath::new(opctx, &datastore)
+    let (_authz_sled, sled) = LookupPath::new(opctx, datastore)
         .sled_id(args.sled_id.into_untyped_uuid())
         .fetch()
         .await
@@ -3271,7 +3271,7 @@ async fn cmd_nexus_sled_expunge_disk_with_datastore(
 
     // First, we need to look up the disk so we can lookup identity information.
     let (_authz_physical_disk, physical_disk) =
-        LookupPath::new(opctx, &datastore)
+        LookupPath::new(opctx, datastore)
             .physical_disk(args.physical_disk_id)
             .fetch()
             .await

dev-tools/omdb/src/bin/omdb/nexus.rs

@@ -106,6 +106,7 @@ uuid.workspace = true
 
 nexus-auth.workspace = true
 nexus-defaults.workspace = true
+nexus-db-lookup.workspace = true
 nexus-db-model.workspace = true
 nexus-db-queries.workspace = true
 nexus-db-schema.workspace = true

nexus/Cargo.toml

@@ -5,7 +5,7 @@
 //! Authz types for resources in the API hierarchy
 //!
 //! The general pattern in Nexus for working with an object is to look it up
-//! (see `nexus_db_queries::db::lookup::LookupPath`) and get back a so-called
+//! (see `nexus_db_lookup::LookupPath`) and get back a so-called
 //! `authz` type.  This type uniquely identifies the resource regardless of
 //! any other changes (e.g., name change or moving it to a different parent
 //! collection). The various datastore functions that modify API resources

nexus/auth/src/authz/api_resources.rs

@@ -0,0 +1,15 @@
+[package]
+name = "nexus-db-errors"
+version = "0.1.0"
+edition = "2021"
+license = "MPL-2.0"
+
+[lints]
+workspace = true
+
+[dependencies]
+diesel.workspace = true
+nexus-auth.workspace = true
+omicron-common.workspace = true
+omicron-workspace-hack.workspace = true
+thiserror.workspace = true

nexus/db-errors/Cargo.toml

@@ -0,0 +1,9 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+mod optional_error;
+mod transaction_error;
+
+pub use optional_error::*;
+pub use transaction_error::*;

nexus/db-errors/src/lib.rs

@@ -0,0 +1,70 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+use diesel::result::Error as DieselError;
+use std::sync::{Arc, Mutex};
+
+/// Helper utility for passing non-retryable errors out-of-band from
+/// transactions.
+///
+/// Transactions prefer to act on the `diesel::result::Error` type,
+/// but transaction users may want more meaningful error types.
+/// This utility helps callers safely propagate back Diesel errors while
+/// retaining auxiliary error info.
+pub struct OptionalError<E>(Arc<Mutex<Option<E>>>);
+
+impl<E> Clone for OptionalError<E> {
+    fn clone(&self) -> Self {
+        Self(self.0.clone())
+    }
+}
+
+impl<E: std::fmt::Debug> OptionalError<E> {
+    #[expect(clippy::new_without_default)] // ehh Default isn't really logical here?
+    pub fn new() -> Self {
+        Self(Arc::new(Mutex::new(None)))
+    }
+
+    /// Sets "Self" to the value of `error` and returns `DieselError::RollbackTransaction`.
+    pub fn bail(&self, err: E) -> DieselError {
+        (*self.0.lock().unwrap()).replace(err);
+        DieselError::RollbackTransaction
+    }
+
+    /// If `diesel_error` is retryable, returns it without setting Self.
+    ///
+    /// Otherwise, sets "Self" to the value of `err`, and returns
+    /// `DieselError::RollbackTransaction`.
+    pub fn bail_retryable_or(
+        &self,
+        diesel_error: DieselError,
+        err: E,
+    ) -> DieselError {
+        self.bail_retryable_or_else(diesel_error, |_diesel_error| err)
+    }
+
+    /// If `diesel_error` is retryable, returns it without setting Self.
+    ///
+    /// Otherwise, sets "Self" to the value of `f` applied to `diesel_err`, and
+    /// returns `DieselError::RollbackTransaction`.
+    pub fn bail_retryable_or_else<F>(
+        &self,
+        diesel_error: DieselError,
+        f: F,
+    ) -> DieselError
+    where
+        F: FnOnce(DieselError) -> E,
+    {
+        if crate::retryable(&diesel_error) {
+            diesel_error
+        } else {
+            self.bail(f(diesel_error))
+        }
+    }
+
+    /// If "Self" was previously set to a non-retryable error, return it.
+    pub fn take(self) -> Option<E> {
+        (*self.0.lock().unwrap()).take()
+    }
+}